企业官网建设流程全解析

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/FastGPT

FastGPT 开源仓库将整套 Docker Compose 部署文件（生产版、开发版、安装脚本、公开下载产物）纳入一套模板 + 占位符 + 版本参数的自动化生成体系。本文以 deploy/README.md 为骨架，结合 deploy/init.mjs 的源码实现，完整讲解如何更新版本号、新增版本、新增服务、新增向量库，以及 YAML 锚点/引用在模板中的实际用法，帮助维护者与二次开发者掌握这套部署文件的正确改法，避免手工改动几十份 yml 导致的版本漂移与镜像错配。

一、总体架构：一份模板，多处产物

FastGPT 的部署文件不是手工维护的，而是由入口脚本 deploy/init.mjs 统一渲染生成。脚本执行后的输出分为三处：

其中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、不改动任何服务结构时，操作最轻量：

1. 编辑version/{version}/args.json中对应的 tag，例如 deploy/version/v4.15/args.json 或 deploy/version/main/args.json；
2. 在 FastGPT 仓库根目录执行node deploy/init.mjs；
3. 脚本自动刷新三处产物：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.22），images则按cn/global两个区域分别声明镜像仓库地址。loadArgs（init.mjs）会把二者合并为{ tag, image: { cn, global } }供渲染使用。因此换版本只需改tags，换镜像源只需改images对应区域，其余模板文件无需触碰。

三、添加新版本：三步完成版本接入

假设要发布v4.15稳定版，README 给出的是三步走：

1. 创建deploy/version/v4.15目录；
2. 添加 deploy/version/v4.15/args.json（注意tags中的每个 key 必须与模板中${{xxx}}占位符一致）；
3. 添加deploy/version/v4.15/docker-compose.template.yml（可直接复制main的模板，再按需调整）；
4. 执行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 全链路对齐：

1. 在init.mjs的Services Enum中登记fastgptExample: fastgpt-example（key 为模板占位符名，value 为 compose 服务名）；
2. 在所有version/*/args.json中添加example的image与tag，且args的key 必须与init.mjs登记的 value 一致；
3. 更新所有需要生效的version/*/docker-compose.template.yml，把服务配置加进去，并把 image 写成${{example.image}}:${{example.tag}}；
4. 如需同步开发环境，再更新templates/docker-compose.dev.yml；
5. 执行node deploy/init.mjs重新生成。

占位符的解析逻辑在 replace 中：形如${{a.b}}的表达式会被拆成a与b两段——b === 'tag'取args[a].tag，b === '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的完整步骤：

1. 在 deploy/templates/vector 下新增exampleDB.txt（服务片段），参考其他 txt 的缩进；image 写成${{exampleDB.image}}:${{exampleDB.tag}}，service name 必须为vectorDB（即 compose 内的fastgpt-vector）；
2. 在所有version/*/args.json中补上exampleDB的镜像与 tag；
3. 新增连接配置片段，如exampleDB.config.txt（会被注入 FastGPT 主服务的环境变量）；
4. 如需额外configs（如 OpenGauss / OceanBase 的 init SQL），新增exampleDB.extra.txt；
5. 在 deploy/templates/vector/config.json 中登记该向量库，声明filename、dbFile、configFile、extraFile；
6. 执行node deploy/init.mjs。

config.json 字段语义

deploy/templates/vector/config.json 目前登记了 6 种向量库，字段含义如下：

loadVectorConfigs（init.mjs）读取该清单后，会生成三类渲染单元：

• db：服务片段本身，模板中以独立注释行# ${{vec.db}}挂载到services:下；
• config：注入x-vec-config锚点，最终成为 FastGPT 主服务的向量库环境变量（如PG_URL、MILVUS_ADDRESS、OCEANBASE_URL）；
• extra/extraBlock：注入configs:块（如 ob 的init_sql）；
• depends：当存在dbFile时自动生成fastgpt-vector: { condition: service_healthy }的依赖声明，确保主服务等待向量库健康后再启动。

六种向量库的接线方式（源码实证）

• pg（pgvector）：pg.txt 定义fastgpt-vector（pgvector 镜像 + 健康检查），pg.config.txt 注入PG_URL: postgresql://username:password@fastgpt-vector:5432/postgres。注意注释提醒：数据库账号密码只有首次运行生效，改后需删除持久化数据重启。
• milvus：milvus.txt 是"三件套"（milvus-minio + milvus-etcd + milvus-standalone），standalone 通过ETCD_ENDPOINTS与MINIO_ADDRESS依赖前两者；milvus.config.txt 注入MILVUS_ADDRESS: http://fastgpt-vector:19530。它运行在独立vector网络。
• zilliz（云端 Milvus）：无dbFile，仅 zilliz.config.txt 注入云地址与 token（zilliz_cloud_address/zilliz_cloud_token），即不部署本地向量库服务。
• ob（OceanBase）：ob.txt 使用OB_SYS_PASSWORD、OB_TENANT_NAME、OB_TENANT_PASSWORD、MODE=MINI/NORMAL等环境变量；ob.extra.txt 挂载init_sqlconfig，内容为ALTER SYSTEM SET ob_vector_memory_limit_percentage = 30;；ob.config.txt 注入 MySQL 协议连接串OCEANBASE_URL: mysql://root%40tenantname:tenantpassword@fastgpt-vector:2881/mysql。
• seekdb：seekdb.txt 兼容 MySQL 协议，ROOT_PASSWORD+MODE=MINI，健康检查用mysqladmin ping（端口 2881）。
• opengauss：opengauss.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）是这套系统的核心，其行为有两点值得维护者注意：

1. 行级块占位符必须独立成注释行：YAML 块占位符（如# ${{vec.db}}、# ${{vec.config}}）必须写成独立注释行，正则^[^\S\r\n]*#\s*${{...}}负责匹配，渲染时若值为空则整行删除。这样模板文件本身仍然是合法 YAML，可被编辑器/CI 直接解析。
2. 行内变量占位符（如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.yml（cn 镜像）与deploy/dev/docker-compose.yml（global 镜像）。

因此在 README 的"加服务"流程中，第 4 步"同步开发环境"特指修改此 dev 模板，而生产各版本模板在version/*/docker-compose.template.yml中维护，二者职责分离、互不覆盖。

九、验证与常见问题

执行node deploy/init.mjs后，建议按以下顺序自检：

1. 看控制台输出：脚本依次打印generating dev/docker-compose.yml、success generated dev files、generating public prod docker-compose.yml files、success generated prod files；
2. 检查生成产物数量：document/public/deploy/docker下应有版本数 × 2(region) × 向量库数份文件；新增向量库后数量会随之增加；
3. 检查 install.sh 版本数组：document/public/deploy/install.sh的BEGIN/END GENERATED DEPLOY VERSIONS块中应包含全部新版本，且main在前；
4. 校验 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: xxx；
• install.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