企业官网建设流程全解析

InsForge 自托管部署完全指南：从 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 官方部署文档体系展开，系统讲解如何将 InsForge 这套开源后端平台（数据库、认证、存储、Serverless 函数、AI 网关等）部署到你自己掌控的服务器上：从四服务架构、部署前置要求、deploy/setup.sh一键拉取与密钥生成，到反向代理、TLS、防火墙加固、更新回滚与自动化备份的完整生产链路。读完本文，你将掌握在任何 Linux VPS 上从零搭建一个可对外服务的 InsForge 实例，并具备维护与加固它的实战能力。

自托管 ≠ 站点托管：本文部署的是 InsForge 平台本身。如果你只是想把你用 InsForge 构建的应用发布上线，应使用 Sites 托管，而不是本文介绍的自托管方案。

一、部署指南文档体系总览

InsForge 仓库的 docs/deployment 目录集中存放了全部分平台部署指南，覆盖「通用 VPS」「主流云厂商」「自托管 PaaS」三类场景：

官方同时声明：云厂商走查类指南由社区维护，可能滞后于最新版本；始终以仓库中 deploy/docker-compose/ 目录为准——它是与发行版保持同步的权威部署形态。

文档还列出了规划中的平台：Digital Ocean（Droplet）、Kubernetes（生产级编排）、Railway（一键部署）、Fly.io（全球边缘部署），目前均处于 Coming Soon 状态。

二、架构概览：四个核心服务

部署文档明确了 InsForge 自托管架构由 4 个服务组成，deploy/docker-compose/docker-compose.yml 中给出了完整定义：

几个值得注意的实现细节（从 compose 文件注释可确认）：

• PostgreSQL 镜像使用ghcr.io/insforge/postgres:v15.13.4，通过command注入自定义配置postgresql.conf，并把app.encryption_key作为自定义 GUC 传入，供数据库端加密使用；初始化脚本 deploy/docker-init/db/db-init.sql 会创建anon、authenticated、project_admin三个角色，并注册一个 DDL 事件触发器——每当新建启用 RLS 的表时自动为其生成project_admin的默认策略。
• PostgREST使用postgrest/postgrest:v12.2.12，数据库连接池PGRST_DB_POOL默认 50，与后端POSTGREST_MAX_SOCKETS对齐；该服务没有 healthcheck——amd64 镜像仅包含 24 个文件（二进制 + 证书目录），容器内没有任何 shell 可供探测，强制加探测反而会永久显示 unhealthy。
• Deno Runtime基于denoland/deno:alpine-2.0.6，以--no-lock运行 functions/server.ts，因为functions/目录以只读方式挂载，Deno 无法回写deno.lock；函数代码运行在 Deno 自身的权限沙箱内。
• 后端镜像（Dockerfile）通过 tini 作为 PID 1、su-exec从 root 降权到node（UID 1000）执行进程，docker/entrypoint.sh负责在加入 Docker socket 组后完成降权——这是 Docker Compose 部署形态下默认非 root 运行的基础。

三、通用部署要求

无论选择哪个平台，所有部署方式都共享以下前置条件（来自部署文档的 General Requirements 章节）：

• 支持Docker 与 Docker Compose（容器化部署的基础）
• 最低 2 GB 内存（推荐 4 GB）
• 20 GB 存储（推荐 30 GB）
• PostgreSQL 15+ 兼容
• 可访问互联网，用于外部服务调用

其中 4 个服务共享一台 2 vCPU / 2 GB RAM 起步的 VPS 即可运转；对于多用户的生产负载，建议从 4 GB 起步，并用docker stats观察资源占用后按需垂直扩容。

四、平台选择：按需求对号入座

部署文档的「Choosing a Platform」章节给出了清晰的选型建议：

以 Hetzner 指南为例，社区推荐的机型为 CX23（2 vCPU / 4 GB RAM / 40 GB 磁盘）起步、CX33（4 vCPU / 8 GB RAM / 80 GB 磁盘）用于生产；InsForge 发布多架构镜像，但指南默认按 x86 的 CX 系列走查。

五、快速上手：在任意 Linux VPS 上部署

以 Ubuntu 22.04/24.04（Debian 12 亦可）为例，完整的部署链路如下。

5.1 初始化服务器

ssh root@your-server-ip apt update && apt upgrade -y # 创建非 root 部署用户 adduser deploy usermod -aG sudo deploy su - deploy # 设置时区并启用自动安全更新 sudo timedatectl set-timezone UTC sudo apt install unattended-upgrades -y sudo dpkg-reconfigure -plow unattended-upgrades

5.2 安装 Docker 与 Compose 插件

sudo apt install ca-certificates curl gnupg -y sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod a+r /etc/apt/keyrings/docker.gpg echo \ "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt update sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y sudo usermod -aG docker deploy newgrp docker

注意：加入docker组等于获得宿主机 root 级权限，这只适用于专用部署用户，不要给共享服务器上的普通账户赋权。

5.3 一键拉取自托管文件并生成密钥

InsForge 提供了一个幂等的安装脚本 deploy/setup.sh：

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

该脚本做了什么（从源码可确认）：

1. **稀疏检出（sparse checkout）**只拉取运行栈所需的最小文件集，包括.env.example、deploy/docker-compose/docker-compose.yml、deploy/docker-init/db/三个初始化 SQL/配置、functions/函数运行时、deploy/backup.sh备份脚本等，总计约 34KB，而非 47MB 的完整仓库（也可通过INSFORGE_NO_GIT=1走 HTTPS 直取模式）。
2. 生成并写入~/insforge/.env（权限 600）：
   • JWT_SECRET（32 字节 hex）与ENCRYPTION_KEY（32 字节 hex），刻意生成两个独立值；
   • ROOT_ADMIN_PASSWORD（12 字节）；
   • POSTGRES_PASSWORD（16 字节，Postgres 只在首次初始化集群时读取）；
   • ACCESS_API_KEY（ik_前缀）与ACCESS_ANON_KEY（anon_前缀）——CLI 与 SDK 的认证密钥。
3. 把COMPOSE_FILE固定为deploy/docker-compose/docker-compose.yml。
4. 不启动任何服务，等待你检查.env。

脚本可安全重复执行：已有.env时保留你的值，只补充或修正COMPOSE_FILE。若不想直接 pipe 执行，可先下载审阅再运行：

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

5.4 启动并验证

cd ~/insforge docker compose up -d docker compose ps

应看到 4 个容器处于running/healthy状态；随后验证健康检查端点：

curl http://localhost:7130/api/health # {"status":"ok","version":"1.x.x","service":"Insforge OSS Backend","timestamp":"..."}

六、生产环境变量配置详解

编辑~/insforge/.env，对照 .env.example 完成生产配置。

6.1 必改的安全变量

# 必须与默认值不同，用终端生成 JWT_SECRET=<openssl rand -base64 32 的输出> ENCRYPTION_KEY=<openssl rand -base64 24 的输出> ROOT_ADMIN_USERNAME=admin ROOT_ADMIN_PASSWORD=<强唯一密码> # 公网 URL，必须与你的域名/IP 一致 API_BASE_URL=https://insforge.yourdomain.com VITE_API_BASE_URL=https://insforge.yourdomain.com

关键陷阱：JWT_SECRET与ENCRYPTION_KEY必须是不同值。ENCRYPTION_KEY未设置时后端会回退到JWT_SECRET，但事后轮换JWT_SECRET将导致所有已存储的密钥（API Key、OAuth Token 等）永久无法解密。setup.sh已按此原则生成两个独立值，不要改动它们。

6.2 数据库与端口变量

POSTGRES_USER=postgres POSTGRES_DB=insforge POSTGRES_PORT=5432 POSTGREST_PORT=5430 APP_PORT=7130 AUTH_PORT=7131 DENO_PORT=7133 COMPOSE_PROJECT_NAME=insforge

• POSTGRES_PASSWORD已由setup.sh生成，Postgres 只在初始化时读取，启动后再改无效。
• COMPOSE_PROJECT_NAME会作为所有容器、卷、网络的前缀。同一宿主机上的第二个实例必须换一个项目名和一组端口，否则docker compose up会接管并重建第一个实例的容器。

6.3 可选集成变量

# OAuth 提供方（启用社交登录时填写） GOOGLE_CLIENT_ID= / GOOGLE_CLIENT_SECRET= GITHUB_CLIENT_ID= / GITHUB_CLIENT_SECRET= MICROSOFT_CLIENT_ID= / MICROSOFT_CLIENT_SECRET= DISCORD_CLIENT_ID= / DISCORD_CLIENT_SECRET= LINKEDIN_CLIENT_ID= / LINKEDIN_CLIENT_SECRET= X_CLIENT_ID= / X_CLIENT_SECRET= APPLE_CLIENT_ID= / APPLE_CLIENT_SECRET= # AI / LLM（OpenRouter 兼容凭据，首次启动写入加密密钥库） OPENROUTER_API_KEY= MAX_COMPLETION_TOKENS=16384 # S3 兼容存储（留空则使用本地文件系统） S3_BUCKET= / S3_REGION= / S3_ACCESS_KEY_ID= / S3_SECRET_ACCESS_KEY= S3_ENDPOINT_URL= # MinIO/RustFS/Wasabi/R2/COS/OSS 等自定义端点，AWS S3 留空 S3_FORCE_PATH_STYLE=true # 路径风格寻址，MinIO 必需 S3_USE_PRESIGNED_URLS= # false 时对象字节流经后端代理（端点对浏览器不可达时必需） S3_MAX_OBJECT_SIZE_BYTES= # 单次 S3 网关上传上限，默认 5368709120（5GB） # Deno 函数 WORKER_TIMEOUT_MS=60000

对存储方向，仓库还提供了自带对象存储 overlay：将COMPOSE_FILE追加:docker-compose.minio.yml或:docker-compose.rustfs.yml即可在 Docker 网络中旁挂 MinIO/RustFS（代理模式已预配置）；但务必在生产前修改其默认凭据（MINIO_ROOT_USER/MINIO_ROOT_PASSWORD或RUSTFS_ACCESS_KEY/RUSTFS_SECRET_KEY）。更多细节见 自托管存储指南。

修改环境变量后需重启生效：

cd ~/insforge docker compose down docker compose up -d

七、反向代理与 HTTPS/TLS

自托管形态下 7130 端口直接暴露并不理想，生产环境应在前面放置反向代理，提供 TLS 终止、HTTP/2 与无端口号的干净 URL。

Option A：Nginx + Certbot（推荐）

创建/etc/nginx/sites-available/insforge：

server { listen 80; listen [::]:80; server_name insforge.yourdomain.com; add_header X-Frame-Options "SAMEORIGIN" always; add_header X-Content-Type-Options "nosniff" always; add_header X-XSS-Protection "1; mode=block" always; add_header Referrer-Policy "strict-origin-when-cross-origin" always; client_max_body_size 50M; # 与 .env 的 MAX_FILE_SIZE 匹配，默认 50MB location / { proxy_pass http://127.0.0.1:7130; proxy_http_version 1.1; # WebSocket 支持（Realtime 功能必需） 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; # 长请求超时（如 AI 补全） proxy_read_timeout 120s; proxy_send_timeout 120s; } }

启用站点并签发证书：

sudo ln -s /etc/nginx/sites-available/insforge /etc/nginx/sites-enabled/ sudo nginx -t && sudo systemctl reload nginx sudo apt install certbot python3-certbot-nginx -y sudo certbot --nginx -d insforge.yourdomain.com # 验证自动续期（证书 90 天过期） sudo certbot renew --dry-run sudo systemctl status certbot.timer

Option B：Caddy（自动 HTTPS）

Caddy 配置更简单，自动申请并续期 Let's Encrypt 证书：

insforge.yourdomain.com { reverse_proxy localhost:7130 header { X-Frame-Options "SAMEORIGIN" X-Content-Type-Options "nosniff" X-XSS-Protection "1; mode=block" Referrer-Policy "strict-origin-when-cross-origin" } request_body { max_size 50MB } }

拿到证书后，把.env中的API_BASE_URL/VITE_API_BASE_URL更新为 HTTPS 地址并重启服务。此外，安全指南建议生产环境收紧 CORS：后端默认回显请求的Origin头并对函数代理响应设置Access-Control-Allow-Origin: *，便于本地开发但过于宽松，生产应限制为实际服务的域名。

八、安全加固清单

8.1 端口管理

关键警告：Docker 直接操作 iptables，会绕过 UFW。默认 compose 若把端口绑定到0.0.0.0，等于把 PostgreSQL（含默认凭据）直接暴露到公网。必须给所有发布端口加上127.0.0.1:前缀（自托管镜像 compose 已默认如此，如"127.0.0.1:${POSTGRES_PORT:-5432}:5432"）。在自托管部署文件中，5430、5433 等内部端口本就只绑定回环地址。

8.2 UFW 防火墙

sudo ufw default deny incoming sudo ufw default allow outgoing sudo ufw allow OpenSSH # 务必先放行 SSH 再 enable，否则会被锁在门外 sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable

8.3 SSH 加固与 Docker 安全

• 用ssh-keygen -t ed25519生成密钥、ssh-copy-id分发，然后在sshd_config中设置PermitRootLogin no、PasswordAuthentication no、PubkeyAuthentication yes、MaxAuthTries 3。
• 安装 fail2ban 并对sshdjail 设置maxretry = 5、bantime = 3600。
• 给 compose 服务加security_opt: [no-new-privileges:true]（生产版 docker-compose.prod.yml 已内置），可选加deploy.resources.limits限制内存/CPU。
• .env保持权限 600，使用openssl rand -base64 32生成独立密钥，绝不提交到版本控制、绝不复用默认口令。

九、更新、回滚与备份

9.1 更新前备份

自托管安装自带 deploy/backup.sh，一条命令同时完成数据库逻辑备份（pg_dump）与.env副本，落盘到~/insforge/backups/：

cd ~/insforge ./deploy/backup.sh # 默认保留 14 天，可 RETENTION_DAYS=30 覆盖

该脚本内部做了空文件校验（pg_dump产出空文件即中止并报错）、umask 077、失败 trap 清理等防护。

9.2 更新流程

自托管栈会从本机 checkout 读取 Postgres 配置与 Deno 函数源码，所以更新不止是拉镜像：

cd ~/insforge git fetch origin main git diff HEAD origin/main -- deploy functions .env.example # 先审阅差异 git merge --ff-only origin/main sh deploy/setup.sh . # 拾取本次发行版新增的文件，保留你的 .env docker compose pull docker compose down && docker compose up -d docker compose logs -f --tail=50 curl http://localhost:7130/api/health

.env.example中的新增变量需要手工复制进你的.env。

9.3 回滚

在.env旁写pin.yml钉住旧版本镜像，并追加到COMPOSE_FILE：

services: insforge: image: ghcr.io/insforge/insforge-oss:v2.2.9

COMPOSE_FILE=deploy/docker-compose/docker-compose.yml:pin.yml

随后docker compose up -d即可回退；确认正常后移除:pin.yml。若更新引入了数据库迁移问题，可用备份的 SQL 通过psql恢复（先只启动postgres服务并等待 healthy）。

9.4 定时自动备份

crontab -e # 每天 3 点备份 0 3 * * * /home/deploy/insforge/deploy/backup.sh >> /home/deploy/insforge/backups/cron.log 2>&1

灾备建议：用aws s3 sync或rsync将backups/同步到外部位置；Hetzner 等云厂商的磁盘快照备份是逻辑备份的补充而非替代。

十、监控与故障排查

常用诊断命令：

docker compose ps # 服务状态 docker compose logs -f insforge # 跟踪指定服务日志 docker stats --no-stream # 资源占用 df -h && free -h # 磁盘与内存

健康检查端点https://your-domain/api/health可接入外部监控（如每 5 分钟 curl 探测报警）。常见问题与对策：

• 启用 UFW 后无法连接：用 VPS 厂商的 Web 控制台带外登录，重新ufw allow OpenSSH && ufw enable。
• Docker 绕过 UFW：所有发布端口绑定127.0.0.1。
• 服务起不来：先看docker compose logs postgres|insforge，检查磁盘/内存，必要时systemctl restart docker。
• 端口冲突：sudo ss -tlnp | grep :7130定位占用进程，再改.env中的APP_PORT。
• 数据库连接问题：docker compose ps postgres确认健康，docker compose exec postgres psql -U postgres -d insforge直连验证。

十一、仓库中的权威部署资产

最终以仓库内实际文件为准：

• 自托管镜像栈：deploy/docker-compose/docker-compose.yml
• 生产构建栈：docker-compose.prod.yml（含no-new-privileges与资源限制示例）
• 安装/密钥生成脚本：deploy/setup.sh
• 备份脚本：deploy/backup.sh
• 数据库初始化：deploy/docker-init/db/db-init.sql、deploy/docker-init/db/jwt.sql、deploy/docker-init/db/postgresql.conf
• 镜像构建：Dockerfile、docker/entrypoint.sh
• 函数运行时：functions/server.ts、functions/worker-template.js
• 全量环境变量说明：.env.example

十二、贡献部署指南

如果你在未收录的平台上有成功的部署经验，欢迎参照 AWS EC2 指南的模板补充新平台的部署文档并提交 Pull Request，仓库参与规范见 CONTRIBUTING.md。

小结：InsForge 的自托管部署是一条「四服务 Docker Compose 栈 + 一键密钥生成 + 反向代理 + 安全加固 + 更新回滚备份」的完整链路。以 部署与安全指南 为总纲、Hetzner 等分平台指南为实例、deploy/ 目录为权威实现，任何具备基础 Linux 与 Docker 经验的开发者都能在一台 2 GB 内存的 VPS 上运行起属于自己的 InsForge 后端平台，并将其安全地维护在生产状态。

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