FastGPT 部署脚本维护指南：基于 init.mjs 模板系统的 Docker Compose 版本管理与向量库扩展

FastGPT 部署脚本维护指南基于 init.mjs 模板系统的 Docker Compose 版本管理与向量库扩展【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPTFastGPT 开源仓库将整套 Docker Compose 部署文件生产版、开发版、安装脚本、公开下载产物纳入一套模板 占位符 版本参数的自动化生成体系。本文以 deploy/README.md 为骨架结合 deploy/init.mjs 的源码实现完整讲解如何更新版本号、新增版本、新增服务、新增向量库以及 YAML 锚点/引用在模板中的实际用法帮助维护者与二次开发者掌握这套部署文件的正确改法避免手工改动几十份 yml 导致的版本漂移与镜像错配。一、总体架构一份模板多处产物FastGPT 的部署文件不是手工维护的而是由入口脚本 deploy/init.mjs 统一渲染生成。脚本执行后的输出分为三处产物说明生成逻辑deploy/dev/docker-compose.yml/docker-compose.cn.yml本地开发环境的依赖服务编排读取 templates/docker-compose.dev.yml使用main或第一个可用版本的参数渲染region 分别为global/cndocument/public/deploy/install.sh用户下载的一键安装脚本在固定标记块# BEGIN GENERATED DEPLOY VERSIONS与# END GENERATED DEPLOY VERSIONS之间重写DEPLOY_VERSIONS(...)版本数组document/public/deploy/docker/{version}/{region}/docker-compose.{vec}.yml公开下载的生产部署文件按版本 × 区域 × 向量库全组合生成输出目录每次先清空重建其中region只有cn与global两种见 init.mjs 的RegionEnum分别对应国内镜像源与海外镜像源vec对应可选向量库pg、milvus、zilliz、ob、seekdb、opengauss。从源码看整个渲染链路的主干为loadDeployVersions() 扫描 version/* 目录 → syncInstallScriptVersions() 回写 install.sh 版本数组 → loadVectorConfigs() 加载 templates/vector/config.json 共享向量库片段 → generateDevFile() 生成 dev 两份文件 → generateProdFile() 生成所有 version×region×vec 的公开产物版本目录的硬性约束loadDeployVersions 规定每个版本目录如deploy/version/main必须同时包含args.json与docker-compose.template.yml否则该目录不会被识别为可发布版本若一个版本都找不到脚本直接抛错No deploy versions found in deploy/version。排序规则为main恒排首位对应当前稳定主线其余按版本号数值倒序v4.15排在v4.14前。二、正常更新只改版本号不动服务当只是把某个版本的镜像升级到新 tag、不改动任何服务结构时操作最轻量编辑version/{version}/args.json中对应的 tag例如 deploy/version/v4.15/args.json 或 deploy/version/main/args.json在 FastGPT 仓库根目录执行node deploy/init.mjs脚本自动刷新三处产物deploy/dev下的开发编排、document/public/deploy/install.sh、document/public/deploy/docker/{version}下的全部生产部署文件。以 deploy/version/main/args.json 为例其结构分为tags与images两大块tags声明每个服务的版本号如fastgpt: v4.16.2、redis: 7.2-alpine、milvus-standalone: v2.6.22images则按cn/global两个区域分别声明镜像仓库地址。loadArgsinit.mjs会把二者合并为{ tag, image: { cn, global } }供渲染使用。因此换版本只需改tags换镜像源只需改images对应区域其余模板文件无需触碰。三、添加新版本三步完成版本接入假设要发布v4.15稳定版README 给出的是三步走创建deploy/version/v4.15目录添加 deploy/version/v4.15/args.json注意tags中的每个 key 必须与模板中${{xxx}}占位符一致添加deploy/version/v4.15/docker-compose.template.yml可直接复制main的模板再按需调整执行node deploy/init.mjs脚本自动扫描并生成document/public/deploy/docker/v4.15下的所有组合文件。生产渲染函数 generateProdFile 会先清空并重建输出目录然后对版本 × 区域 × 向量库全排列写出文件命名格式为docker-compose.{向量库filename}.yml如docker-compose.pg.yml、docker-compose.oceanbase.yml。因此每个新增版本天然获得与既有版本一致的完整矩阵无需手工复制。值得注意的是prod 各版本使用各自的args.json而 dev 固定使用main的参数注释与generateDevFile中defaultDevVersion的逻辑均印证了这一点这样稳定版的 tag 不会被main分支的迭代镜像意外覆盖。四、添加新服务三处同步key 值必须对齐假设要添加example服务README 列出 5 个步骤核心是占位符 key 全链路对齐在init.mjs的Services Enum中登记fastgptExample: fastgpt-examplekey 为模板占位符名value 为 compose 服务名在所有version/*/args.json中添加example的image与tag且args的key 必须与init.mjs登记的 value 一致更新所有需要生效的version/*/docker-compose.template.yml把服务配置加进去并把 image 写成${{example.image}}:${{example.tag}}如需同步开发环境再更新templates/docker-compose.dev.yml执行node deploy/init.mjs重新生成。占位符的解析逻辑在 replace 中形如${{a.b}}的表达式会被拆成a与b两段——b tag取args[a].tagb image取args[a].image[region]。如果模板里出现了args.json中不存在的 key脚本会直接抛错Missing deploy arg ... Please add it to args.json or remove the placeholder from the template.从机制上杜绝了模板引用了未定义镜像这类静默失败。五、添加新向量库模板片段 配置清单联动向量库是 FastGPT 部署中扩展性最强的一环它被设计成共享片段而非在版本模板中内联。添加exampleDB的完整步骤在 deploy/templates/vector 下新增exampleDB.txt服务片段参考其他 txt 的缩进image 写成${{exampleDB.image}}:${{exampleDB.tag}}service name 必须为vectorDB即 compose 内的fastgpt-vector在所有version/*/args.json中补上exampleDB的镜像与 tag新增连接配置片段如exampleDB.config.txt会被注入 FastGPT 主服务的环境变量如需额外configs如 OpenGauss / OceanBase 的 init SQL新增exampleDB.extra.txt在 deploy/templates/vector/config.json 中登记该向量库声明filename、dbFile、configFile、extraFile执行node deploy/init.mjs。config.json 字段语义deploy/templates/vector/config.json 目前登记了 6 种向量库字段含义如下字段作用示例pgfilename决定输出文件名docker-compose.{filename}.ymlpgdbFile服务片段文件注入services:下service 名为fastgpt-vectorpg.txtconfigFile连接配置片段注入x-vec-config环境变量pg.config.txtextraFile额外 configs 片段可选注入configs:块ob.extra.txtob 独有loadVectorConfigsinit.mjs读取该清单后会生成三类渲染单元db服务片段本身模板中以独立注释行# ${{vec.db}}挂载到services:下config注入x-vec-config锚点最终成为 FastGPT 主服务的向量库环境变量如PG_URL、MILVUS_ADDRESS、OCEANBASE_URLextra/extraBlock注入configs:块如 ob 的init_sqldepends当存在dbFile时自动生成fastgpt-vector: { condition: service_healthy }的依赖声明确保主服务等待向量库健康后再启动。六种向量库的接线方式源码实证pgpgvectorpg.txt 定义fastgpt-vectorpgvector 镜像 健康检查pg.config.txt 注入PG_URL: postgresql://username:passwordfastgpt-vector:5432/postgres。注意注释提醒数据库账号密码只有首次运行生效改后需删除持久化数据重启。milvusmilvus.txt 是三件套milvus-minio milvus-etcd milvus-standalonestandalone 通过ETCD_ENDPOINTS与MINIO_ADDRESS依赖前两者milvus.config.txt 注入MILVUS_ADDRESS: http://fastgpt-vector:19530。它运行在独立vector网络。zilliz云端 Milvus无dbFile仅 zilliz.config.txt 注入云地址与 tokenzilliz_cloud_address/zilliz_cloud_token即不部署本地向量库服务。obOceanBaseob.txt 使用OB_SYS_PASSWORD、OB_TENANT_NAME、OB_TENANT_PASSWORD、MODEMINI/NORMAL等环境变量ob.extra.txt 挂载init_sqlconfig内容为ALTER SYSTEM SET ob_vector_memory_limit_percentage 30;ob.config.txt 注入 MySQL 协议连接串OCEANBASE_URL: mysql://root%40tenantname:tenantpasswordfastgpt-vector:2881/mysql。seekdbseekdb.txt 兼容 MySQL 协议ROOT_PASSWORDMODEMINI健康检查用mysqladmin ping端口 2881。opengaussopengauss.txt 直接写死opengauss/opengauss:7.0.0-RC1镜像未走${{}}占位符密码要求大写小写数字特殊字符且不少于 8 位并需privileged: true。从模板主文件的挂载点可见完整接线docker-compose.template.yml 中x-vec-config锚点通过注释行# ${{vec.config}}引入连接配置services:下通过# ${{vec.db}}引入服务片段depends_on中通过# ${{vec.depends}}引入健康依赖文件末尾configs:块通过# ${{vec.extraEntries}}引入额外配置——同一套模板因此能渲染出 6 种向量库的完整 compose 文件。六、YAML 锚点与引用模板复用的基础语法deploy/README.md 最后用最小示例说明了 YAML 锚点语法这也是整个模板体系x-share-db-config、x-log-config、x-no-proxy-config、x-vec-config等的底层机制定义一个锚点可引用后续复用x-share-config: x-share-config I am the config content x-share-config-list: x-share-config-list key1: value key2: value*引用一个锚点some_other_example: *x-share-config-list在 FastGPT 模板中的典型用法是先定义、后合并。例如x-share-db-config锚点集中定义 Mongo / Redis / MinIO 的连接参数见 docker-compose.template.yml随后 FastGPT 主服务用合并列表语法一次性展开多组锚点environment: : [*x-share-db-config, *x-vec-config, *x-log-config, *x-no-proxy-config, *x-agent-sandbox-config]同理fastgpt-plugin使用: [*x-share-db-config, *x-log-config, *x-no-proxy-config]。除此之外模板中还大量使用标量锚点做跨服务传值例如x-system-key、x-plugin-auth-token、x-agent-sandbox-proxy-secret定义一次被ROOT_KEY: *x-system-key、PLUGIN_TOKEN: *x-plugin-auth-token、AGENT_SANDBOX_PROXY_SECRET: *x-agent-sandbox-proxy-secret等分别引用——保证 FastGPT 主站与 plugin / 沙盒 / 卷管理等附属服务的密钥天然一致。七、占位符解析的工程细节replace函数init.mjs是这套系统的核心其行为有两点值得维护者注意行级块占位符必须独立成注释行YAML 块占位符如# ${{vec.db}}、# ${{vec.config}}必须写成独立注释行正则^[^\S\r\n]*#\s*${{...}}负责匹配渲染时若值为空则整行删除。这样模板文件本身仍然是合法 YAML可被编辑器/CI 直接解析。行内变量占位符如image: ${{fastgpt.image}}:${{fastgpt.tag}}走第二个正则${{([^}]*)}}全部替换支持在同一条语句内出现多次。vec.*表达式走独立分支vec.db会递归渲染服务片段片段内部还可能再包含其他占位符vec.config/vec.extra等直接取值若引用了未登记的向量库名会抛Unknown vector config。此外 dev 与 prod 均通过formatYamlOutput做trimEnd 换行规范化输出保证生成文件的排版一致性。八、开发环境编排与生产模板的差异deploy/templates/docker-compose.dev.yml 是开发用途的独立模板与生产模板有几个关键差异不含 FastGPT 主服务只编排最小运行条件pgvector、mongo、redis、minio、code-sandbox、plugin、opensandbox-server、agent-sandbox-proxy、volume-manager、aiproxy依赖服务端口全部映射到宿主机fastgpt-pg: 5432、fastgpt-mongo: 27017、fastgpt-redis: 6379、fastgpt-code-sandbox: 3002、fastgpt-plugin: 3004等fastgpt-plugin使用network_mode: host便于本地进程直连固定以 pgvector 为默认向量库生成两份deploy/dev/docker-compose.cn.ymlcn 镜像与deploy/dev/docker-compose.ymlglobal 镜像。因此在 README 的加服务流程中第 4 步同步开发环境特指修改此 dev 模板而生产各版本模板在version/*/docker-compose.template.yml中维护二者职责分离、互不覆盖。九、验证与常见问题执行node deploy/init.mjs后建议按以下顺序自检看控制台输出脚本依次打印generating dev/docker-compose.yml、success generated dev files、generating public prod docker-compose.yml files、success generated prod files检查生成产物数量document/public/deploy/docker下应有版本数 × 2(region) × 向量库数份文件新增向量库后数量会随之增加检查 install.sh 版本数组document/public/deploy/install.sh的BEGIN/END GENERATED DEPLOY VERSIONS块中应包含全部新版本且main在前校验 YAML 合法对生成的 yml 执行docker compose config可验证锚点展开与占位符替换结果。常见失败场景与对应报错均来自 init.mjs 源码版本目录缺文件 →No deploy versions found in deploy/version模板引用了 args.json 中没有的 key →Missing deploy arg xxx ... Please add it to args.json占位符指向不存在的向量库 →Unknown vector config: xxxinstall.sh 中找不到版本标记块 →Can not find generated deploy versions block in install.sh某个 region 缺镜像地址 →Missing deploy image xxx.cn ...。这些显式报错让改错模板在生成阶段即可被发现而非等到用户部署时暴露。十、总结FastGPT 的部署维护体系可以概括为一句话版本号与镜像源写在version/*/args.json服务结构写在版本模板与 dev 模板向量库以共享片段形式挂在templates/vector并由config.json登记最终统一由node deploy/init.mjs渲染出全部产物。日常升级只需改args.json新增版本需要同时补齐args.json与模板新增服务要保证占位符 key、args key、Services Enum 三者一致新增向量库则走txt 片段 config.json 登记的插件式流程。理解这套约定后任何部署文件的增改都能在几分钟内完成且不会破坏版本矩阵的一致性。【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考