使用 Docker Compose 将 InsForge 部署到 AWS EC2：从零开始的完整实战指南-平芜编程栈

使用 Docker Compose 将 InsForge 部署到 AWS EC2：从零开始的完整实战指南

【免费下载链接】InsForgeThe all-in-one, open-source backend platform for agentic coding. InsForge gives your coding agent database, auth, storage, compute, hosting, and AI gateway to ship full-stack apps end-to-end.项目地址: https://gitcode.com/GitHub_Trending/in/InsForge

本文是一份面向正式环境的中文实战指南，完整讲解如何在 AWS EC2 上以 Docker Compose 方式部署自托管版 InsForge（开源的全栈后端平台，集数据库、认证、存储、计算、托管与 AI 网关于一体）。文章覆盖 EC2 实例选型与安全组配置、SSH 连接、Docker 环境搭建、通过官方setup.sh自动生成密钥与拉取运行文件、.env环境变量配置、服务验证、Nginx 反向代理与 Let's Encrypt TLS，以及日常维护、备份、性能调优与安全加固。读完本文，你将能独立拥有一台可被 AI 编码代理连接、可对外提供 API 与仪表板的自托管 InsForge 实例。

社群维护声明：本文属于云端部署教学文档，由社群维护，可能落后于最新版 InsForge。标准且永远最新的部署配置以仓库内 deploy/docker-compose/docker-compose.yml 目录为准。本仓库中该指南的中文繁体版本位于 docs/zh-Hant/deployment/deploy-to-aws-ec2.md，英文版本位于 docs/deployment/deploy-to-aws-ec2.md。

事前准备

在开始之前，请确认具备以下条件：

具备 EC2 存取权限的 AWS 账户
具备 SSH 与命令列操作的基本知识
一个域名（可选，用于自定义域名与 HTTPS 配置）

InsForge 的自托管形态是"镜像驱动"的：运行栈由 deploy/docker-compose/docker-compose.yml 定义的 4 个容器组成（PostgreSQL、PostgREST、InsForge 后端、Deno 运行时），不要求你从源码构建镜像，因此对实例的硬件要求不高，一台 2 vCPU / 4 GB 内存的实例即可流畅运行。

第一步：创建并配置 EC2 实例

1.1 启动 EC2 实例

登录 AWS Console，进入 EC2 仪表板；
点击Launch Instance（启动实例）；
按下表配置实例：

配置项	推荐值	说明
名称	`insforge-server`	可自定义
AMI	Ubuntu Server 24.04 LTS (HVM)，SSD Volume Type	本文所有命令均基于 Ubuntu 系
实例类型	`t3.medium`或更高（最低 2 vCPU、4 GB RAM）	正式环境建议`t3.large`（2 vCPU、8 GB RAM）；测试环境最低`t3.small`（2 vCPU、2 GB RAM）
密钥对	新建或选择既有密钥对	下载并妥善保存`.pem`文件
存储	30 GB gp3	建议最低 20 GB

从源码结构看，生产镜像（ghcr.io/insforge/insforge-oss:latest）基于 Node.js 20 构建，并内置了完整的仪表板静态资源（见 Dockerfile 的多阶段构建），因此单个后端容器同时承载 API 与仪表板，这也是文档中 API 与 Dashboard 可以指向同一端口的根本原因。

1.2 配置安全组

创建或修改安全组，加入以下传入（Inbound）规则：

类型	协议	端口范围	来源	说明
SSH	TCP	22	My IP	SSH 存取
HTTP	TCP	80	0.0.0.0/0	HTTP 存取
HTTPS	TCP	443	0.0.0.0/0	HTTPS 存取
Custom TCP	TCP	7130	0.0.0.0/0	仪表板 + API
Custom TCP	TCP	5432	0.0.0.0/0	PostgreSQL（可选）

⚠️安全性注意事项：在正式环境中，请将 PostgreSQL（5432）限制为特定 IP 地址，或完全移除对外开放。建议使用反向代理（Nginx），仅对外开放 80/443 端口。

需要特别说明的是，5432这一条是可选的。查看 deploy/docker-compose/docker-compose.yml 可知，PostgreSQL 与 PostgREST 的宿主机端口均被刻意绑定到回环地址127.0.0.1（如"127.0.0.1:${POSTGRES_PORT:-5432}:5432"），即只有本机（以及同网络的容器）能访问数据库，容器间通过 Docker 内部网络insforge-network以服务名postgres、postgrest通信。因此，除非你需要从外部直接连数据库调试，否则完全没必要在安全组中放行 5432。

1.3 配置弹性 IP（建议）

在 EC2 仪表板进入Elastic IPs；
点击Allocate Elastic IP address；
将弹性 IP 与你的实例关联。

这可以确保实例在重启后仍然保有相同的公网 IP，后续配置 DNS 记录、Nginx 与 HTTPS 时也不会因为 IP 漂移而失效。

第二步：SSH 连接实例

# 为密钥文件设置正确权限 chmod 400 your-key-pair.pem # 通过 SSH 连接 ssh -i your-key-pair.pem ubuntu@your-ec2-public-ip

Ubuntu 官方 AMI 的默认用户名为ubuntu。连接后，建议先运行sudo apt update确认网络与软件源正常。

第三步：安装依赖软件

3.1 更新系统软件包

sudo apt update && sudo apt upgrade -y

3.2 安装 Docker

请按照 Docker 官方文档《Install Docker Engine on Ubuntu》的步骤在 Ubuntu EC2 实例上安装并验证 Docker（docker --version能输出版本号即视为安装成功）。安装完成后，Docker 守护进程会由 systemd 管理，通常无需额外配置即可使用。

3.3 将当前用户加入 Docker 群组

安装 Docker 后，需要将你的用户加入docker群组，才能在不使用sudo的情况下执行 Docker 命令：

# 将用户加入 docker 群组 sudo usermod -aG docker $USER # 使群组变更立即生效 newgrp docker

验证是否成功：

# 此命令现在应无需 sudo 即可运行 docker ps

💡注意：若docker ps未能立即生效，请先登出再重新通过 SSH 登录，然后再试一次。

⚠️安全性注意事项：将用户加入docker群组会授予其与 root 等同的系统权限。对于像 EC2 实例这样的单用户环境是可以接受的，但在共享系统上请格外谨慎。

3.4 安装 Git

sudo apt install git -y

Git 是部署与更新流程的必需组件——下文setup.sh的默认安装路径依赖git clone拉取运行文件，更新时也需要git pull。

第四步：部署 InsForge

4.1 获取仓库运行文件

curl -fsSL https://raw.githubusercontent.com/InsForge/InsForge/main/deploy/setup.sh | sh -s ~/insforge

这条命令会从远端获取 deploy/setup.sh 并立即执行，其行为可以拆解为三个动作：

拉取运行文件：以稀疏检出（sparse checkout）方式克隆 InsForge 仓库到~/insforge，只检出运行栈实际需要的文件——包括.env.example、生产 Compose 文件deploy/docker-compose/docker-compose.yml、数据库初始化 SQL（deploy/docker-init/db/db-init.sql、jwt.sql、postgresql.conf）、函数运行时（functions/server.ts、functions/worker-template.js、functions/deno.json）以及备份脚本deploy/backup.sh；
生成密钥并写入.env：脚本会基于openssl rand生成JWT_SECRET（32 字节）、ENCRYPTION_KEY（32 字节）、ROOT_ADMIN_PASSWORD（12 字节）、POSTGRES_PASSWORD（16 字节），并额外生成带前缀的ACCESS_API_KEY（ik_前缀）与ACCESS_ANON_KEY（anon_前缀）供 CLI/SDK 认证使用；
什么都不启动：脚本只准备文件与环境，绝不自动docker compose up，以便你先行审阅.env。

从 deploy/setup.sh 的源码注释可以确认几个关键设计：

幂等可重跑：脚本安全地支持重复执行，已存在的.env会被保留，只补充或修正COMPOSE_FILE指向；
密钥必须由脚本生成，不要手改：若openssl rand失败，脚本会直接删除半成品.env并以非零状态退出，避免实例以占位符密钥上线；
ENCRYPTION_KEY与JWT_SECRET分开生成：若ENCRYPTION_KEY未设置，后端会回退使用JWT_SECRET，届时轮换JWT_SECRET会导致所有已存储的密钥（API Key、OAuth Token 等）永久无法解密；
POSTGRES_PASSWORD仅在首次初始化数据库集群时被读取，之后修改.env不会生效——这正是文档强调"密钥已经生成，请勿改动"的底层原因。

4.2 配置环境变量

cd ~/insforge nano .env

密钥已自动生成，请勿改动。接下来设置浏览器将访问的地址（公网 IP 或后续的域名）：

API_BASE_URL=http://<你的公开IP>:7130 VITE_API_BASE_URL=http://<你的公开IP>:7130

这两个变量分别作用于后端生成 URL 与前端（Vite）构建的 API 地址。其余可选变量默认全部关闭，按需启用：

OPENROUTER_API_KEY= # AI 功能 VERCEL_TOKEN= # 网站部署 GOOGLE_CLIENT_ID= # OAuth 提供者 GOOGLE_CLIENT_SECRET=

其余变量及其默认值都在.env.example中（部署目录下对应文件为 .env.example），包括：

服务端口：APP_PORT=7130（主应用）、AUTH_PORT=7131、UI_PORT=7132、DENO_PORT=7133、POSTGREST_PORT=5430、POSTGRES_PORT=5432；
管理员凭据：ROOT_ADMIN_USERNAME（默认admin）、ROOT_ADMIN_PASSWORD（正式环境必须修改）；
OAuth 提供者：Google、GitHub、Microsoft、Discord、LinkedIn、X、Apple 的*_CLIENT_ID/*_CLIENT_SECRET，各提供者的回调地址形如http://localhost:7130/auth/google/callback；
存储：留空S3_BUCKET使用本地文件系统（容器内挂载于/insforge-storage），设置S3_*变量则切换到任意 S3 兼容存储（AWS S3、MinIO、RustFS、Wasabi、R2、腾讯 COS、阿里云 OSS 等）；
AI 网关：OPENROUTER_API_KEY在首次启动时被写入加密密钥库，之后可在 Model Gateway 设置中覆盖；
遥测：InsForge 会发送匿名自托管使用事件，设置INSFORGE_TELEMETRY_DISABLED=1可完全关闭。

💡 请务必将.env备份到安全的地方。迁移或还原该实例完全依赖其中的密钥。

4.3 启动 InsForge 服务

# 拉取 Docker 镜像并启动服务 docker compose up -d # 查看日志，确认一切正常启动 docker compose logs -f

按Ctrl+C退出日志查看画面。

在正式启动前，建议先运行docker compose config检查 Compose 渲染结果（尤其是.env变量是否被正确注入）。运行栈共 4 个服务，各服务镜像与关键配置如下（依据 deploy/docker-compose/docker-compose.yml）：

服务	镜像	职责	关键点
`postgres`	`ghcr.io/insforge/postgres:v15.13.4`	数据存储	启动时依次执行`db-init.sql`、`jwt.sql`，加载`postgresql.conf`；数据持久化于`postgres-data`卷；带`pg_isready`健康检查
`postgrest`	`postgrest/postgrest:v12.2.12`	REST 数据 API	连接池`PGRST_DB_POOL`默认 50，与后端`POSTGREST_MAX_SOCKETS`对齐；启用`pgrst`频道实现 Schema 热重载
`insforge`	`ghcr.io/insforge/insforge-oss:latest`	后端 + 仪表板	承载全部 API 路由与前端静态资源；持久化`storage-data`（存储）与`insforge-logs`（日志）两个卷
`deno`	`denoland/deno:alpine-2.0.6`	Serverless 函数运行时	以只读方式挂载`functions/`，`deno cache`后运行 functions/server.ts，执行`WORKER_TIMEOUT_MS`（默认 60000ms）超时控制

四个容器共享同一个桥接网络insforge-network，后端通过http://postgrest:3000、http://deno:7133访问内部服务。

4.4 验证服务

# 检查运行中的容器 docker compose ps # 应看到 4 个运行中的服务： # - postgres # - postgrest # - insforge # - deno

如果容器反复重启，优先用docker compose logs <service>定位问题（例如 Postgres 首次启动时密钥不匹配、端口冲突等）。

第五步：访问你的 InsForge 实例

5.1 测试后端 API

curl http://your-ec2-ip:7130/api/health

预期响应：

{ "status": "ok", "version": "2.1.7", "service": "Insforge OSS Backend", "timestamp": "2025-10-17T..." }

该健康检查端点定义于 backend/src/server.ts：apiRouter.get('/health', ...)返回status、后端版本号（取自package.json）、服务名与 ISO 时间戳。它不依赖数据库连接状态，是判断"后端进程是否存活"的最轻量探针，可用于云监控告警或负载均衡器健康检查。

5.2 访问仪表板

打开浏览器访问：

http://your-ec2-ip:7130

使用.env中设置的ROOT_ADMIN_USERNAME与ROOT_ADMIN_PASSWORD登录。登录后即可在仪表板中创建项目，连接 AI 编码代理（Cursor、Claude Code、Codex 等），使用数据库、认证、存储、函数、实时消息、支付等能力。

第六步：配置域名与 TLS（可选，但强烈建议）

在正式环境中，通过 IP + 端口访问既不安全也不专业。以下步骤将接入自定义域名与 HTTPS。

6.1 更新 DNS 记录

在域名服务商处新增指向 EC2 弹性 IP 的 DNS A 记录：

api.yourdomain.com → your-ec2-ip app.yourdomain.com → your-ec2-ip

6.2 安装 Nginx 反向代理

sudo apt install nginx -y

创建 Nginx 配置文件：

sudo nano /etc/nginx/sites-available/insforge

写入以下配置：

# Backend API server { listen 80; server_name api.yourdomain.com; location / { proxy_pass http://localhost:7130; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_cache_bypass $http_upgrade; } } # Dashboard (served by the backend on the same port as the API) server { listen 80; server_name app.yourdomain.com; location / { proxy_pass http://localhost:7130; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_cache_bypass $http_upgrade; } }

这段配置有两个值得注意的细节：

proxy_set_header Upgrade/Connection 'upgrade'：这是 WebSocket 代理的关键头，InsForge 的实时（Realtime）消息与 Presence 功能依赖 WebSocket 长连接；
X-Forwarded-Proto：后端依赖该头判断请求是否来自 HTTPS，从而正确生成 URL。仓库中的 trust-proxy.ts 负责解析这些转发头。

启用配置并重载：

sudo ln -s /etc/nginx/sites-available/insforge /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx

nginx -t会先校验配置语法，通过后再重载，避免中断现有连接。

6.3 安装 SSL 证书（建议）

# 安装 Certbot sudo apt install certbot python3-certbot-nginx -y # 获取 SSL 证书 sudo certbot --nginx -d api.yourdomain.com -d app.yourdomain.com # 按提示完成设置

Certbot 会自动修改 Nginx 配置以启用 HTTPS，并配置自动续期。

然后更新.env改用 HTTPS 地址：

cd ~/insforge nano .env

修改为：

API_BASE_URL=https://api.yourdomain.com VITE_API_BASE_URL=https://api.yourdomain.com

重启服务使配置生效：

docker compose down docker compose up -d

注意docker compose down不会删除命名卷（postgres-data等），因此数据是安全的；重启后容器会以新 URL 重新启动。配置域名后，安全组只需保留 22/80/443，7130 端口可以关闭对外访问，由 Nginx 统一转发。

管理与维护

查看日志

# 全部服务 docker compose logs -f # 单个服务 docker compose logs -f insforge docker compose logs -f postgres docker compose logs -f deno

停止服务

docker compose down

重启服务

docker compose restart

更新 InsForge

更新是"拉取镜像 + 重启"，但checkout 同样重要：Postgres 的配置与 Deno 函数都是从它读取的。请从~/insforge执行以下命令：

cd ~/insforge git pull origin main # 获取此版本在稀疏检出中新增的文件 sh deploy/setup.sh . docker compose pull && docker compose up -d

这一步之所以必不可少，是因为 deploy/setup.sh 采用稀疏检出（sparse checkout）：git pull只会更新已在检出清单中的文件，而新版本若在 Compose 文件中引用了新增文件，必须通过sh deploy/setup.sh .把新文件路径补进检出清单，否则容器可能因缺少文件而启动失败。脚本幂等设计保证了重复执行安全，且不会覆盖你已生成的.env。

备份数据库

请从~/insforge执行以下命令：

# 创建备份 docker compose exec postgres pg_dump -U postgres insforge > backup_$(date +%Y%m%d_%H%M%S).sql # 从备份还原 cat backup_file.sql | docker compose exec -T postgres psql -U postgres -d insforge

对于正式环境，更推荐使用仓库自带的 deploy/backup.sh：

# 逻辑备份 + .env 副本，默认保留 14 天 ~/insforge/deploy/backup.sh # 自定义保留天数与备份目录 RETENTION_DAYS=30 BACKUP_DIR=/mnt/backups/insforge ~/insforge/deploy/backup.sh

该脚本执行pg_dump逻辑备份并同时复制一份.env（因为还原实例依赖其中的密钥），还支持按保留期自动清理旧备份。生产环境建议将其加入cron定时执行，并把备份文件同步到 S3 等异地存储。

监控资源

# 检查磁盘占用 df -h # 检查内存占用 free -h # 查看 Docker 资源统计 docker stats

疑难排解

服务无法启动

# 查看日志定位错误 docker compose logs # 检查磁盘空间 df -h # 检查内存 free -h # 重启 Docker 守护进程 sudo systemctl restart docker docker compose up -d

容器反复重启时，请重点查看docker compose logs insforge：后端启动时会先执行数据库迁移（npm run migrate:up，见 Dockerfile 的 CMD），迁移失败会导致进程退出，常见诱因是JWT_SECRET与POSTGRES_PASSWORD被误改，或磁盘空间不足。

无法连接数据库

# 检查 PostgreSQL 是否运行 docker compose ps postgres # 查看 PostgreSQL 日志 docker compose logs postgres # 核对 .env 中的凭据 cat .env | grep POSTGRES

注意，POSTGRES_PASSWORD只在数据库集群首次初始化时生效，此后修改.env不会改变已存在集群的密码，因此请避免在部署后随意轮换数据库密码。

端口已被占用

# 查看占用端口的进程 sudo netstat -tulpn | grep :7130 # 终止占用进程，或在 docker-compose.yml 中修改端口

内存不足

考虑升级到更大规格的实例类型：

- 当前: t3.medium (4 GB RAM) - 升级至: t3.large (8 GB RAM)

SSL 证书问题

# 续期证书 sudo certbot renew # 测试续期 sudo certbot renew --dry-run

性能优化

面向正式环境的工作负载

升级实例类型：使用t3.large或t3.xlarge；
启用自动扩展：配置应用负载均衡器（ALB）并搭配自动扩展组；
使用 RDS：从容器化 PostgreSQL 迁移至 AWS RDS，获得托管备份、多可用区等可靠性能力；
启用 CloudWatch：监控指标并设置告警；
配置备份：建立自动化的每日备份；
使用 S3 存储：配置 S3 存储桶替代本地存储处理文件上传（对应.env中的S3_BUCKET、S3_REGION、S3_ACCESS_KEY_ID、S3_SECRET_ACCESS_KEY等变量）。

数据库优化

# 增加 PostgreSQL shared_buffers（编辑 deploy/docker-init/db/postgresql.conf） # 建议：可用内存的 25% shared_buffers = 1GB effective_cache_size = 3GB

仓库提供的 deploy/docker-init/db/postgresql.conf 已预置了 InsForge 所需的扩展与参数：shared_preload_libraries = 'pg_cron,http,pgcrypto,insforge_pg_utils'、cron.database_name = 'insforge'（供定时任务使用）、wal_level = logical等。修改该文件后需要重建容器（docker compose up -d --force-recreate postgres）才能让配置进入容器。

连接池对齐

后端到 PostgREST 的并发连接数由POSTGREST_MAX_SOCKETS（默认 50）控制，而 PostgREST 自身的数据库连接池由PGRST_DB_POOL（Compose 中默认 50）控制。二者必须保持对齐：只调大前端而不同步调大后端池，只是把排队挪进 PostgREST。小规格实例可同时调低这两个值以节省内存。

安全性最佳实践

更改默认密码：更新管理员与数据库密码（.env中ROOT_ADMIN_PASSWORD、POSTGRES_PASSWORD）；
启用防火墙：有效运用 AWS 安全组，DB 端口（5432）只对必要 IP 开放或干脆关闭；
定期更新：持续更新系统与 Docker 镜像（执行"更新 InsForge"一节的三步命令）；
SSL/TLS：正式环境务必使用 HTTPS，配置域名后关闭 7130 端口的公网访问；
定期备份：自动化数据库备份（建议使用 deploy/backup.sh + cron + 异地同步）；
监控日志：配置日志监控与告警（后端日志落盘于/insforge-logs卷，也可配置 CloudWatch）；
限制 SSH 访问：将 SSH 来源限制在特定 IP 地址，并优先使用密钥而非密码登录；
使用 IAM 角色：尽可能以 IAM 角色替代 AWS 访问密钥，为 EC2 实例授予最小权限。

此外，deploy/docker-compose/docker-compose.yml 中 PostgREST、Deno、AUTH 端口的宿主绑定均默认限制在127.0.0.1，这是镜像栈自带的安全基线，请勿随意改为0.0.0.0。更多安全细节参见部署安全指南。

费用估算

每月 AWS 费用（约略）：

项目	类型	每月费用
EC2 实例	t3.medium	~$30
存储（30 GB）	EBS gp3	~$3
弹性 IP	（若 24/7 运行）	$0
数据传输	前 100GB 免费	变动
总计	~$33/月

💡成本优化：长期部署可使用 AWS Savings Plans 或 Reserved Instances，最高可节省 70%。

总结

至此，你的 InsForge 实例已成功运行在 AWS EC2 上：通过 deploy/setup.sh 完成运行文件拉取与密钥生成，docker compose拉起 PostgreSQL、PostgREST、InsForge 与 Deno 四个容器，再以 Nginx + Certbot 接入域名与 HTTPS。现在你可以打开仪表板创建项目，并将 AI 编码代理连接到你的后端平台，开始端到端地构建全栈应用。如需其他正式环境部署策略（Coolify、Dokploy、Zeabur、云主机等），可继续阅读 docs/deployment 下的其余部署指南。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考