企业官网建设流程全解析

InsForge 自托管部署指南：在 AWS EC2 上用 Docker Compose 搭建完整的后端平台

【免费下载链接】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

本文是一份面向开发者的实战指南，讲解如何把 InsForge 这套开源的"一体化 Agent 后端平台"以自托管方式部署到 AWS EC2 实例上，覆盖从实例创建、安全组配置、依赖安装、setup.sh一键拉取与密钥生成、.env配置，到 Nginx 反向代理、Certbot HTTPS 证书、日常运维、备份与故障排查的完整流程。读完本文，你将拥有一个可运行的 InsForge 实例——包含 PostgreSQL、PostgREST、InsForge Backend 与 Deno 运行时四个核心服务，并能为你的编码 Agent 提供数据库、认证、存储、计算与 AI 网关能力。

部署对象说明：本文部署的是 InsForge 平台本身，而不是你用 InsForge 构建的应用。如果你只是想把自建应用上线，请使用 Sites 功能；本文面向的是在自有基础设施上运行 InsForge 后端的情形。

架构概览：自托管栈由四个服务组成

在动手部署前，先理解这套栈的组成。从 deploy/docker-compose/docker-compose.yml 可以清晰看到，InsForge 自托管实例由 4 个容器组成（这也是docker compose ps期待看到的 4 个运行中服务）：

几个关键设计点值得注意（均来自 compose 文件源码注释）：

• 对外只暴露 7130：insforge服务的ports是"${APP_PORT:-7130}:7130"，而 postgres、postgrest、deno 默认都绑定在127.0.0.1上，只能通过 Docker 内部网络insforge-network互通。这是默认的安全姿态——外部流量统一从 7130 进入。
• Postgres 只在首次初始化时读取密码：compose 文件中POSTGRES_PASSWORD传给数据库后，只有在集群初始化（initdb）那一刻生效。这就是为什么.env必须在第一次启动前就配置好，之后修改密码不会改变已初始化的集群。
• deno 容器直接挂载仓库的functions/目录（只读），用--no-lock参数避免写回deno.lock；函数代码运行在 Deno 自己的权限沙箱内。

一、前置条件

开始之前，请确认具备：

• 一个拥有 EC2 访问权限的 AWS 账户
• SSH 与命令行操作的基本知识
• （可选）一个域名，用于配置自定义域名和 HTTPS

通用部署要求（与其它部署平台一致，见 deployment/README.md）包括：支持 Docker 与 Docker Compose、最低 2 GB 内存（推荐 4 GB）、20 GB 存储（推荐 30 GB）、PostgreSQL 15+ 兼容，以及访问外部服务的网络连通性。

二、创建并配置 EC2 实例

2.1 启动 EC2 实例

1. 登录 AWS Console，进入 EC2 Dashboard。
2. 点击Launch Instance。
3. 按下表配置实例：

2.2 配置安全组

为实例创建或配置安全组，添加入站规则：

⚠️安全提示：生产环境中，应将 PostgreSQL（5432）限制为特定 IP 或彻底移除外部访问。更推荐的做法是使用反向代理（nginx），只对外暴露 80/443 端口，让 7130 也走内网访问。

2.3 分配弹性 IP（推荐）

1. 在 EC2 Dashboard 进入Elastic IPs。
2. 点击Allocate Elastic IP address。
3. 将该弹性 IP 关联到你的实例。

这样实例即使重启，IP 地址也不会变化——对后续配置域名解析至关重要。

三、连接 EC2 实例

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

四、安装依赖

4.1 更新系统包

sudo apt update && sudo apt upgrade -y

4.2 安装 Docker

按照 Docker 官方文档中 Ubuntu 的安装指引，在全新的 Ubuntu EC2 实例上安装并验证 Docker。安装完成后确认docker --version与docker compose version均可正常输出。

4.3 将用户加入 docker 组

安装 Docker 后，把当前用户加入docker组，以便无需sudo即可运行 Docker 命令：

# 将当前用户加入 docker 组 sudo usermod -aG docker $USER # 立即应用组变更 newgrp docker

验证是否生效：

# 此时无需 sudo 即可运行 docker ps

💡提示：如果docker ps没有立即生效，请注销并重新通过 SSH 登录后再试。

⚠️安全提示：将用户加入docker组等于授予其系统上的 root 级权限。对于 EC2 这类单用户环境这是可接受的，但在共享系统上需格外谨慎。

4.4 安装 Git

sudo apt install git -y

五、部署 InsForge

5.1 获取仓库文件并生成密钥

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

这条命令会检出栈运行所需的文件，并在.env中生成JWT_SECRET、ENCRYPTION_KEY、ROOT_ADMIN_PASSWORD和POSTGRES_PASSWORD。注意：脚本不会启动任何服务。

本仓库中的对应脚本位于 deploy/setup.sh，它的行为可以从源码中得到精确印证：

• 拉取方式：默认通过git clone --depth 1 --filter=blob:none --sparse做浅克隆 + 稀疏检出；如果环境没有 git 或设置INSFORGE_NO_GIT=1，则改为逐文件 HTTPS 拉取（全部文件仅约 34KB，而仓库 tarball 为 47MB）。两种方式读取同一份FILES清单，因此对"栈需要哪些文件"不会产生分歧。
• 文件清单：脚本只拉取.env.example、docker-compose.minio.yml、docker-compose.rustfs.yml、functions/deno.json、functions/server.ts、functions/worker-template.js、deploy/backup.sh、deploy/docker-compose/docker-compose.yml以及deploy/docker-init/db/下的三个数据库初始化文件。
• 可重复执行：脚本设计为"安全可重跑"——已存在的.env会被保留，只会补充或修正COMPOSE_FILE变量。这正是后续升级流程会再次调用它的原因。
• 密钥生成细节：gen_secret函数使用openssl rand -hex生成随机值，JWT_SECRET/ENCRYPTION_KEY各 32 字节、ROOT_ADMIN_PASSWORD12 字节、POSTGRES_PASSWORD16 字节；ACCESS_API_KEY与ACCESS_ANON_KEY分别以ik_、anon_前缀生成（20 字节随机部分），因为后端要求这两个键带前缀。如果openssl失败，脚本会删除半成品.env并报错退出，绝不会留下占位密钥让你带着已知密钥上线。
• 权限：生成的.env权限为600，仅属主可读写。

5.2 创建环境配置

cd ~/insforge nano .env

密钥已经生成——保持原样即可。接下来设置浏览器将要使用的 URL：

API_BASE_URL=http://<your-public-ip>:7130 VITE_API_BASE_URL=http://<your-public-ip>:7130

可选配置项（默认全部关闭）：

OPENROUTER_API_KEY= # AI 功能 VERCEL_TOKEN= # 站点部署 GOOGLE_CLIENT_ID= # OAuth 提供商 GOOGLE_CLIENT_SECRET=

.env.example（仓库根目录的 .env.example）携带了其余所有变量及其默认值。

💡 请把.env备份到安全位置。其中的密钥是迁移或恢复此实例的唯一凭据。

关于.env，结合 deploy/docker-compose/docker-compose.yml 源码可以补充几个重要的行为细节：

• ENCRYPTION_KEY与JWT_SECRET必须独立：compose 中ENCRYPTION_KEY=${ENCRYPTION_KEY:-${JWT_SECRET:-...}}，即未设置时回退到JWT_SECRET。但setup.sh特意分开生成二者，原因正如脚本注释所写：若ENCRYPTION_KEY未设置而回退到JWT_SECRET，之后轮换JWT_SECRET会导致所有已存储的密钥（API Key、OAuth Token 等）永久无法解密。
• POSTGRES_PASSWORD只在首次启动生效：Postgres 仅在初始化集群时读取它，因此必须在第一次docker compose up前确定。
• COMPOSE_FILE由脚本自动写入：值为deploy/docker-compose/docker-compose.yml。如果你需要叠加 MinIO/RustFS 存储，可以用冒号追加 overlay：COMPOSE_FILE=deploy/docker-compose/docker-compose.yml:docker-compose.minio.yml。
• 可选的OPENROUTER_API_KEY：首次启动时该值会被复制进 InsForge 的加密密钥库，并在没有存储密钥时作为回退；Model Gateway 设置可以覆盖它，已存储的值始终优先。
• OAuth 回调地址：配置 Google/GitHub 等 OAuth 时，回调地址形如http://<host>:7130/auth/google/callback，域名模式启用 HTTPS 后为https://api.yourdomain.com/auth/google/callback。

5.3 启动 InsForge 服务

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

按Ctrl+C退出日志视图。

5.4 验证服务

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

Compose 文件中的启动编排细节：postgrest通过depends_on: postgres: condition: service_healthy等待 Postgres 健康检查通过（pg_isready，5 秒间隔、5 次重试）；insforge与deno则依赖 postgres 健康与 postgrest 启动。Deno 容器有自己的健康检查（wget --spider http://127.0.0.1:7133/health，含 15 秒启动宽限期），PostgREST 由于 amd64 镜像内没有 shell 而故意不配置健康检查。

六、访问你的 InsForge 实例

6.1 测试后端 API

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

预期响应（健康检查端点在 backend/src/server.ts 中实现，返回status: 'ok'与service: 'Insforge OSS Backend'）：

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

6.2 访问 Dashboard

打开浏览器访问：

http://your-ec2-ip:7130

使用.env中设置的ROOT_ADMIN_USERNAME和ROOT_ADMIN_PASSWORD登录。从 compose 源码可以看到，ROOT_ADMIN_USERNAME缺省回退到ADMIN_EMAIL再回退到admin，ROOT_ADMIN_PASSWORD同理回退到change-this-password——但setup.sh已为你生成了强随机值，无需依赖回退。

七、配置域名（可选但推荐）

7.1 更新 DNS 记录

添加指向 EC2 弹性 IP 的 DNS A 记录：

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

7.2 安装 Nginx 反向代理

sudo apt install nginx -y

创建 Nginx 配置：

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

添加以下配置（注意：Dashboard 与 API 由后端在同一个 7130 端口上提供，所以两个 server 块都代理到localhost:7130）：

# 后端 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（与 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; } }

启用配置：

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

代理模式补充：由于反向代理位于后端之前，.env中的KEEP_ALIVE_TIMEOUT_MS（默认 65000ms，见 .env.example）必须大于任何负载均衡器或代理的空闲超时，否则客户端会复用已被服务端关闭的连接。同理，PostgREST 侧的POSTGREST_FREE_SOCKET_TIMEOUT_MS（默认 4000ms）必须低于 PostgREST 服务端空闲超时，以避免ECONNRESET。

7.3 安装 SSL 证书（推荐）

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

更新.env文件中的 URL 为 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 logs -f # 单个服务 docker compose logs -f insforge docker compose logs -f postgres docker compose logs -f deno

停止服务

docker compose down

重启服务

docker compose restart

更新 InsForge

更新本质上是一次"拉取 + 重启"，但检出内容同样重要——栈会读取 Postgres 的配置与 Deno 函数，因此必须在~/insforge下执行：

cd ~/insforge git pull origin main # 补上本次发布在稀疏检出新加入的文件 sh deploy/setup.sh . docker compose pull && docker compose up -d

为什么更新后要再跑一次setup.sh？从 deploy/setup.sh 源码看，稀疏检出模式（git sparse-checkout set --no-cone）只在每次运行时按FILES清单把文件带入工作树。某个 release 新增了 compose 读取的文件，其路径会随脚本一起发布；合并后不重跑脚本，该文件会落在 git 里却不会出现在工作树中。同时脚本会保留你已有的.env值，只补充或修正COMPOSE_FILE。如果你需要锁定版本而非跟随 main，可以在首次部署时设置INSFORGE_REF=vX.Y.Z（标签、分支或 commit 均可）。

备份数据库

在~/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副本 + 自动清理，并支持两个环境变量：BACKUP_DIR（备份目录，默认~/insforge/backups）与RETENTION_DAYS（保留天数，默认 14）。使用方式：

# 直接运行（要求栈处于运行状态，且 .env 可读） ./deploy/backup.sh # 自定义保留天数与目录 RETENTION_DAYS=30 BACKUP_DIR=/mnt/backups/insforge ./deploy/backup.sh

脚本细节：以set -euo pipefail严格模式运行，umask 077保证备份文件权限收紧；先pg_dump到临时文件，为空则报错退出；成功后同时复制.env为env_<时间戳>.bak（因为.env中的密钥是恢复实例的关键）；最后按RETENTION_DAYS清理过期文件。

监控资源

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

九、故障排查

服务无法启动

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

无法连接数据库

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

关键提醒：Postgres 只在首次初始化集群时读取POSTGRES_PASSWORD。如果你在数据库已初始化后才修改.env中的密码，连接会失败——这是本方案最常见的"假故障"之一。

端口被占用

# 查看谁在使用 7130 端口 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

十、生产环境性能优化

面向生产负载

1. 升级实例类型：使用t3.large或t3.xlarge
2. 启用自动扩缩容：配置 Application Load Balancer 与自动扩缩组
3. 使用 RDS：从容器化 PostgreSQL 迁移到 AWS RDS 以获得更高可靠性
4. 启用 CloudWatch：监控指标并设置告警
5. 配置备份：设置自动化每日备份
6. 使用 S3 存储：为文件上传配置 S3 桶，替代本地存储

数据库调优

仓库自带的 deploy/docker-init/db/postgresql.conf 是 InsForge 定制过的 PostgreSQL 配置，其中值得关注的有：

# 共享预加载库：pg_cron、http、pgcrypto 与 InsForge 自己的扩展 shared_preload_libraries = 'pg_cron,http,pgcrypto,insforge_pg_utils' # 内部 schema 白名单：这些 schema 绝不对 REST 数据 API 暴露 insforge.internal_schemas = 'ai,auth,compute,deployments,email,functions,memory,payments,realtime,schedules,storage,system'

针对更大内存的实例，可在此基础上调整（原文档建议，参考 PostgreSQL 通用实践）：

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

⚠️ 注意：deploy/docker-init/db/postgresql.conf是作为只读卷挂载进 postgres 容器的（/etc/postgresql/postgresql.conf:ro,z），Postgres 启动时通过-c config_file=/etc/postgresql/postgresql.conf读取。修改后需要重建容器生效，建议在更新流程（git pull+sh deploy/setup.sh .）后自然带入。

此外，如果走 Docker 内置的本地 S3 兼容存储（MinIO/RustFS），可通过在COMPOSE_FILE中追加 overlay（docker-compose.minio.yml或docker-compose.rustfs.yml，见 docker-compose.minio.yml）启用；生产环境强烈建议改用 AWS S3 等外部对象存储（设置S3_BUCKET、S3_REGION、S3_ACCESS_KEY_ID、S3_SECRET_ACCESS_KEY，AWS S3 场景下S3_ENDPOINT_URL留空走 SDK 默认端点，也可用 IAM 角色提供凭据）。

十一、安全最佳实践

1. 修改默认密码：更新管理员与数据库密码（setup.sh已自动生成强随机值，切勿替换为弱口令）
2. 启用防火墙：有效利用 AWS 安全组，限制入站规则
3. 定期更新：保持系统与 Docker 镜像更新（按上文更新流程操作）
4. SSL/TLS：生产环境始终使用 HTTPS
5. 定期备份：自动化数据库备份（推荐使用deploy/backup.sh）
6. 监控日志：配置日志监控与告警
7. 限制 SSH 访问：将 SSH 限制为特定 IP 地址
8. 使用 IAM 角色：尽可能用 IAM 角色替代 AWS 访问密钥

十二、成本估算

月度 AWS 成本（近似值）：

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

十三、后续方向

至此，你的 InsForge 实例已在 AWS EC2 上运行。接下来你可以：把 AI 编码 Agent 连接到这个自托管后端平台，开始构建全栈应用；为边缘函数启用 Deno 运行时；配置 OAuth 登录提供商（Google、GitHub、Discord 等，对应 .env.example 中的*_CLIENT_ID/*_CLIENT_SECRET变量）；以及接入 Stripe/Razorpay 支付能力。

本文为社区维护的云平台部署指引，可能滞后于最新 release；始终最新的权威配置位于本仓库的 deploy/docker-compose/docker-compose.yml，其它生产部署策略可参考 deployment-security-guide 与 deployment/README.md 中的 Coolify、Dokploy、Hetzner、Containarium 等部署方案。

【免费下载链接】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