在 Dokploy 上自托管 InsForgeCompose 应用部署与源码级配置指南【免费下载链接】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 的官方部署文档《Self-Host InsForge on Dokploy》整理而成的一站式技术指南。它面向已经拥有 Dokploy 实例的开发者讲解如何以Compose 应用的形式把 InsForge 后端平台部署到自己的服务器上并深入解释其中的关键设计为什么 Postgres 要“现构建”而非直接拉取镜像、ENCRYPTION_KEY为什么必须单独设置、对象存储在该平台下的正确配置方式。读完本文你将掌握在 Dokploy 上完成 InsForge 创建、环境变量注入、域名路由、首次部署、后续更新与存储接入的完整实战流程。注意本指南部署的是InsForge 平台本身而不是你基于 InsForge 构建的应用。如果你只是想把你写的应用上线请使用 Sites 功能而不是自托管整个平台。前置条件开始之前你需要具备一台可用的Dokploy 实例Dokploy 是开源的、可自托管在你自己服务器上的 PaaS 平台一个指向该服务器的域名或子域名用于后续路由到 InsForge 服务。仓库中对自托管的一般性硬件建议见 docs/deployment/README.md同样适用于 Dokploy至少 2 GB 内存推荐 4 GB、至少 20 GB 存储推荐 30 GB并需支持 Docker 与 Docker Compose。1. 创建 Compose 应用在 Dokploy 控制台中进入Create → Compose将本仓库作为 provider 连接然后按以下字段配置字段值Compose Pathdeploy/dokploy/docker-compose.ymlCompose TypeDocker Compose仓库中对应的 Compose 文件位于 deploy/dokploy/docker-compose.yml它定义了完整的服务栈postgres、postgrest、insforge后端 Dashboard与deno函数运行时以及 4 个本地命名卷postgres-data、deno_cache、storage-data、insforge-logs。所有服务均带security_opt: no-new-privileges:true加固且没有任何服务把仓库目录 bind-mount 进容器——这是为 Dokploy“每次部署重新克隆code/”的行为专门设计的详见第 7 节。2. 配置环境变量在 Dokploy 的Environment标签页中设置以下变量。每个密钥建议用openssl rand -hex 32生成JWT_SECRET32 characters ENCRYPTION_KEY32 characters, different from JWT_SECRET POSTGRES_PASSWORDstrong password ROOT_ADMIN_USERNAMEadmin ROOT_ADMIN_PASSWORDstrong password其中前三个变量在 Compose 文件里使用了 Docker 的强制插值语法:?缺失时服务会直接启动失败而不是带着占位符运行。例如 deploy/dokploy/docker-compose.yml 中 Postgres 的启动命令command: postgres -c config_file/etc/postgresql/postgresql.conf \ -c cron.database_name${POSTGRES_DB:-insforge} \ -c app.encryption_key${ENCRYPTION_KEY:?set ENCRYPTION_KEY in Dokploy Environment - openssl rand -hex 32, must differ from JWT_SECRET}为什么 ENCRYPTION_KEY 必须单独设置文档明确指出ENCRYPTION_KEY在未设置时会回退到JWT_SECRET而事后轮换JWT_SECRET会让所有已加密存储的密钥永远无法解密。这一点在源码中有直接对应实现——backend/src/infra/security/encryption.manager.tsconst key process.env.ENCRYPTION_KEY || process.env.JWT_SECRET; if (!process.env.ENCRYPTION_KEY) { logger.warn( ENCRYPTION_KEY is not set — falling back to JWT_SECRET for secrets encryption. WARNING: rotating JWT_SECRET without setting a dedicated ENCRYPTION_KEY will corrupt all stored secrets. ); } this.encryptionKey crypto.createHash(sha256).update(key).digest();密钥经过 SHA-256 哈希后用于AES-256-GCM加解密。一旦使用JWT_SECRET加密过 Secrets、OAuth 凭据等数据再轮换JWT_SECRET就意味着解密密钥变化、数据全部不可读。因此务必在首次部署时就为ENCRYPTION_KEY设置一个与JWT_SECRET不同的独立值。POSTGRES_PASSWORD 只在初始化时生效Postgres 只有在**首次初始化数据簇initdb**时才会读取POSTGRES_PASSWORD。之后修改该变量并不会改变数据库密码必须通过其他数据库运维手段处理。这也是为什么首部署前就要把密码定好的原因。其余可选变量除上述必填项外Compose 文件还透传了大量可选变量均带默认值涵盖对象存储S3_*系列、OAuth 登录GOOGLE_CLIENT_ID、GITHUB_CLIENT_ID、DISCORD_*、MICROSOFT_*、LINKEDIN_*、X_*、APPLE_*、支付STRIPE_TEST_SECRET_KEY、STRIPE_LIVE_SECRET_KEY、AI 网关OPENROUTER_API_KEY、Sites 部署VERCEL_TOKEN等、自定义计算COMPUTE_*/ Docker provider以及遥测开关INSFORGE_TELEMETRY_DISABLED。Compose 文件默认值只是占位符而非安全值生产环境务必显式覆盖。后端实际读取这些变量时有一套完整的解析逻辑默认值、布尔解析、字节上限钳制见 backend/src/infra/config/app.config.ts。几个与 Dokploy 部署直接相关的要点POSTGREST_MAX_SOCKETS默认50与 Compose 中 PostgREST 的PGRST_DB_POOL默认值保持一致deploy/dokploy/docker-compose.yml 有“Keep in sync”注释——调大任一侧都会导致连接池排队位置发生偏移S3_USE_PRESIGNED_URLS、S3_FORCE_PATH_STYLE都是非false即开的宽松解析! false而布尔开关如COMPUTE_ISOLATE_NETWORK则用parseEnvBool支持1/true/yes/on多种写法COMPUTE_BUILD_MAX_CONTEXT默认64mbCOMPUTE_BUILD_UPLOAD_IDLE_TIMEOUT默认 30 秒并被钳制在 32 位有符号整数上限内这是对“一次只允许一个构建”的自我保护。3. 添加域名由于 Compose 文件没有向宿主机发布任何端口整个栈只会停留在 Dokploy 的内部网络上必须通过域名路由才能访问。在 Dokploy 的Domains中为insforge服务添加域名字段值Service NameinsforgeContainer Port7130然后回到 Environment把与该域名匹配的 URL 加进环境变量API_BASE_URLhttps://insforge.example.com VITE_API_BASE_URLhttps://insforge.example.com这两者必须与浏览器实际访问的 URL完全一致否则 Dashboard 会向后端发出错误的 origin 请求。7130正是后端服务端口PORT默认值见 backend/src/infra/config/app.config.ts。只有insforge需要域名。Postgres、PostgREST 和 Deno 运行时都留在 Dokploy 内部网络中通过服务名互通POSTGRES_HOST: postgres、POSTGREST_BASE_URL: http://postgrest:3000、DENO_RUNTIME_URL: http://deno:7133。4. 部署点击Deploy按钮。首次部署会执行两件事构建两个小镜像基于仓库的 Postgres 镜像deploy/Dockerfile.postgres和 Deno 函数宿主镜像deploy/Dockerfile.deno其余镜像postgrest/postgrest:v12.2.12、ghcr.io/insforge/insforge-oss:latest直接拉取启动后自动运行后端的数据库迁移无需手动干预。部署完成后打开你的域名使用ROOT_ADMIN_USERNAME/ROOT_ADMIN_PASSWORD登录 Dashboard 即可。服务依赖与健康检查Compose 文件为服务间的启动顺序定义了明确的依赖关系postgrest等待postgres的service_healthypg_isready探测5 秒间隔、5 次重试insforge同时等待postgres健康与postgrest启动deno依赖postgres与postgrest并以wget --spider http://127.0.0.1:7133/health自检60 秒启动宽限。值得注意的是 PostgREST 服务没有健康检查——注释说明其 amd64 官方镜像不携带 shell 与任何工具容器内没有可用的探测程序这也是部署时无需为其配置 healthcheck 的原因。5. 更新更新 InsForge 非常简单再次点击Deploy或开启Auto Deploy在推送代码时自动重新部署。每次部署都会从当前 commit 重新构建 Postgres 与 Deno 镜像因此它们的配置和函数宿主始终跟随最新发布不会出现“代码已更新、底层配置还是旧的”的漂移问题。更新前请审查.env.example的 diff如果新版本新增了环境变量它不会自动出现在你的 Dokploy 环境里需要手动补上。仓库根目录的 .env.example位于仓库根列出了所有受支持变量及其默认值是核对的最佳依据。6. 存储Dokploy 场景下的对象存储InsForge 的对象存储默认使用容器文件系统上的 Docker 卷STORAGE_DIR/insforge-storage对应storage-data卷开箱即用。这也意味着 Dokploy 之外的 MinIO/RustFSoverlay 方式在这里不适用——Dokploy 只接受单个 Compose 文件无法叠加docker-compose.minio.yml或docker-compose.rustfs.yml。在 Dokploy 上接入 S3 存储有两种可行方案详见 docs/deployment/self-host-storage.mdx使用外部 S3 兼容存储在 Dokploy 的 Environment 中设置S3_BUCKET、S3_ENDPOINT_URL、S3_ACCESS_KEY_ID、S3_SECRET_ACCESS_KEY、S3_FORCE_PATH_STYLEtrue私有端点还需S3_USE_PRESIGNED_URLSfalse。deploy/dokploy/docker-compose.yml已将这些变量完整透传给后端在同一台 Dokploy 主机上自部署 MinIO/RustFS把它们作为独立的 Dokploy 服务运行再把上面的环境变量指向其内部地址。相关默认值与 backend/src/infra/config/app.config.ts 一致S3_REGION默认us-east-2S3_FORCE_PATH_STYLE默认trueS3_USE_PRESIGNED_URLS默认trueS3_MAX_OBJECT_SIZE_BYTES默认 5 GBMAX_FILE_SIZEREST 上传上限默认 50 MB。警告把已有部署从本地存储切换到 S3 后端不会迁移旧对象。切换前请先迁移storage-data卷中的内容例如用mc mirror或aws s3 sync或干脆清空重来。7. 为什么 Postgres 要“现构建”而不是直接拉取这是本文档最有价值的设计决策之一。InsForge 的 Postgres 镜像需要仓库中的三个文件deploy/docker-init/db/postgresql.conf核心配置其中shared_preload_libraries pg_cron,http,pgcrypto,insforge_pg_utils加载了insforge_pg_utils扩展——托管表的行级安全RLS依赖它同时还定义了insforge.internal_schemas后端内部 schema 白名单与insforge.policy_grant_role等参数deploy/docker-init/db/db-init.sql初始化脚本创建anon/authenticated/project_admin三类角色并注册事件触发器——任何新表创建或启用 RLS 时自动为project_admin生成默认策略deploy/docker-init/db/jwt.sqlJWT 相关初始化脚本。对应构建方式见 deploy/Dockerfile.postgres它以ghcr.io/insforge/postgres:v15.13.4为基础把上述三个文件复制进镜像FROM ghcr.io/insforge/postgres:v15.13.4 COPY deploy/docker-init/db/postgresql.conf /etc/postgresql/postgresql.conf COPY deploy/docker-init/db/db-init.sql /docker-entrypoint-initdb.d/01-init.sql COPY deploy/docker-init/db/jwt.sql /docker-entrypoint-initdb.d/02-jwt.sql为什么不改用 bind mount 或预构建镜像Dokploy每次部署都会重新克隆code/目录指向仓库的 bind mount 会随之失效其官方文档也要求用 UI 中创建的 File Mounts 并以../files/形式引用这需要为每次安装做手动配置。而在部署时构建镜像则把当前文件直接烧进镜像无需任何额外配置开箱即用配置永远不会落后于代码——对比预构建镜像其内部文件被冻结在构建那一刻历史上就曾因此导致自托管 RLS 失效镜像里缺少insforge_pg_utils的shared_preload_libraries。同样的理由也适用于 Deno 函数宿主ghcr.io/insforge/deno-runtime预构建镜像在另一个仓库组装其functions/副本不对应当前仓库的任何 commit本仓库的修复永远到不了它。因此 deploy/Dockerfile.deno 直接从denoland/deno:alpine-2.0.6构建把本仓库的functions/目录复制进去并以非 root 的deno用户运行注意基础镜像已自带 uid 1000 的 deno 用户重复创建会导致构建失败。架构速览综合 docs/deployment/README.md 与 Compose 文件这套栈共 4 个主要服务服务作用端口PostgreSQL数据库内置 RLS 扩展与初始化脚本5432内部PostgREST自动生成的 REST APIinsforge后端通过 HTTP 连接池代理转发3000内部InsForge BackendNode.js API 服务同时托管 Dashboard7130对外Deno Runtime无服务器函数运行时7133内部结语在 Dokploy 上部署 InsForge 的核心体验是“一个 Compose 文件搞定一切”配置集中在 deploy/dokploy/docker-compose.yml关键密钥通过 Dokploy 的 Environment 注入并以:?强制校验Postgres 与 Deno 宿主由仓库现构建从而与代码保持同步域名路由只需指向insforge:7130。只要遵守“ENCRYPTION_KEY独立设置、域名与API_BASE_URL一致、更新前审查.env.examplediff”三条纪律后续的升级与运维都相当省心。若需在其他 PaaS 或裸机 VPS 上部署可参考仓库中同目录下的 Coolify 指南 与 通用部署与安全指南。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考