DB-GPT 文档站点构建与 Docker 多版本部署实战指南【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT本文以 DB-GPT 仓库中的 docs/README.md 为核心系统讲解该项目基于 Docusaurus 构建的官方文档站点从本地启动到 Docker 化多版本发布的完整流程。读者将掌握依赖安装、本地开发调试、Docker 镜像构建参数的含义与调优、Nginx 容器托管以及多版本文档含中文 i18n 骨架同步的部署机制可直接复用于自建 Docusaurus 文档站的运维实践。文档站点整体形态DB-GPT 的官方文档独立存放于仓库根目录的docs/目录下是一套基于Docusaurus 3.4.0的静态站点。从 docs/package.json 可以看出核心依赖包括docusaurus/core、docusaurus/preset-classic、docusaurus/theme-mermaid支持 Mermaid 图表渲染以及easyops-cn/docusaurus-search-local站内本地搜索站点同时启用了en默认与zh-CN双语言支持语言配置在 docs/docusaurus.config.js 中声明Node.js 运行环境要求18.0。docs 目录中的关键组成包括docs/docs/英文文档主体、docs/i18n/中文本地化目录、docs/sidebars.js侧边栏配置、docs/static/静态资源以及docs/nginx/部署用 Nginx 配置。本地快速启动文档站点安装依赖先克隆 DB-GPT 仓库到本地然后在项目根目录进入docs/目录安装 Docusaurus 依赖生成node_modules目录# 进入 docs 目录后执行 yarn install由于 Docusaurus 依赖较多若网络环境不佳可改用 npm 并指定镜像源如https://registry.npmmirror.com与下方 Docker 构建时NPM_REGISTRY参数的用法一致。启动开发服务器yarn start默认开发服务监听3000端口浏览器访问http://localhost:3000即可实时预览文档。开发模式下 docs/docusaurus.config.js 将onBrokenLinks/onBrokenMarkdownLinks设为throw任何失效的内部链接都会直接中断构建便于在编写文档时第一时间暴露问题。常用 npm 脚本package.json 中定义了一组可直接复用的脚本脚本命令作用yarn start本地开发预览端口 3000支持热更新yarn start:zh以zh-CN语言环境启动本地预览yarn build构建生产静态文件输出到build/yarn serve本地静态托管已构建产物yarn write-translations抽取各语言待翻译文案yarn sync-docs-zh-skeleton同步中文文档骨架详见下文 i18n 章节yarn bootstrap-docs-zh一次性完成 zh-CN 翻译文案抽取与骨架同步深入 Docusaurus 站点配置docs/docusaurus.config.js 是文档站的中枢配置文件几个值得注意的实现点版本开关通过环境变量BUILD_FAST与DISABLE_VERSIONING控制是否启用多版本构建第 12-13 行。BUILD_FAST时onlyIncludeVersions仅保留current一份版本大幅缩短 CI 构建时间当前版本命名getNextVersionName()将开发中的文档版本固定命名为dev第 35-36 行与仓库发布版本区分开代码块渲染通过raw-loader支持在 Markdown/MDX 中直接内嵌.py与.ipynb源码第 118-131 行这与仓库大量 Python 示例代码的文档化需求直接相关侧边栏优化自定义sidebarItemsGenerator在长标签的分隔符/后插入零宽空格避免侧边栏标签被截断换行第 165-182 行。版本号清单维护在 docs/versions.json该文件当前为空数组表示仓库默认只发布dev即current版本Docker 多版本构建时由构建脚本动态生成正式版本。使用 Docker 部署多版本文档本地开发满足个人调试需求而对外提供多版本文档每个 Git 发布 tag 一套站点则需要 Docker 化部署。这是 docs/README.md 的核心场景也是本仓库提供 docs/Dockerfile-deploy 的原因。步骤一构建 Docker 镜像在DB-GPT 项目根目录注意不是 docs 目录内执行# 使用默认 npm 源https://registry.npmjs.org # 也可切换为国内镜像 https://www.npmmirror.com/ NPM_REGISTRYhttps://registry.npmmirror.com docker build -f docs/Dockerfile-deploy \ -t eosphorosai/dbgpt-docs \ --build-arg NPM_REGISTRY$NPM_REGISTRY \ --build-arg CIfalse \ --build-arg NUM_VERSION2 .该命令的三个构建参数含义如下构建参数默认值作用NPM_REGISTRYhttps://registry.npmjs.orgnpm 包下载源国内网络可替换为https://registry.npmmirror.comCItrue是否以 CI 模式构建为true时会执行git fetch --prune拉取完整 tag 历史含 shallow 仓库的 unshallow 操作NUM_VERSION2需要构建的文档版本数量取最新的 N 个 Git tag步骤二理解镜像内部的多版本构建原理Dockerfile-deploy 采用多阶段构建第一阶段node:lts-alpine负责依赖安装与站点构建第二阶段nginx:alpine只托管产物。核心逻辑位于第一阶段第 46-94 行记录当前分支位置后取按创建时间倒序的前NUM_VERSION个 Git tag若仓库无任何 tag则退化为取最近NUM_VERSION个提交短哈希第 51-55 行逐个 tag 执行git checkout并检查docs/patchs/下是否存在对应的fix_{版本}.patch补丁文件如 fix_0.6.3.patch、fix_0.7.4.patch存在则git apply应用用于修复历史版本文档在最新版 Docusaurus 下的兼容性问题第 61-72 行拷贝该版本对应的docs/、sidebars.js、static/、src/到构建目录执行docusaurus docs:version tag生成版本化文档第 73-80 行回到原分支将当前dev文档也纳入构建最后npm run build产出静态站点并把构建的版本清单写入build/versions.txt第 82-94 行。这种按 tag 循环 checkout 版本化 打补丁的方式保证了历史版本文档与最新版本文档可以在同一站点内共存并通过 Docusaurus 内置的版本下拉框切换。步骤三运行 Docker 容器docker run -it --rm -p 8089:8089 \ --name my-dbgpt-docs \ -v $(pwd)/docs/nginx/nginx-docs.conf:/etc/nginx/nginx.conf \ eosphorosai/dbgpt-docs容器内 Nginx 监听8089端口映射到宿主机的 8089 端口。关键点在于通过-v卷挂载将宿主机上的 docs/nginx/nginx-docs.conf 覆盖容器内/etc/nginx/nginx.conf——这样无需重新构建镜像即可调整 Nginx 行为。浏览器访问http://localhost:8089即可看到多版本文档站。提示--rm表示容器退出后自动删除如需常驻后台运行可将-it --rm替换为-d。Nginx 配置解析挂载的 nginx-docs.conf 是文档服务的对外网关核心配置包括worker_processes 1与worker_connections 1024适合文档站这类轻量静态服务server块监听8089root指向镜像内/usr/share/nginx/html即 Dockerfile 第二阶段拷贝构建产物的位置见 Dockerfile-deploy 第 103-105 行try_files $uri $uri/ /index.html实现 SPA 式回退确保 Docusaurus 客户端路由如/docs/get_started在直接刷新时也能正确命中index.html。仓库还提供了一份启用 HTTPS 的配置 docs/nginx/nginx-docs-ssl.confHTTP 80 端口通过return 301 https://$host$request_uri强制跳转 HTTPS443 端口开启ssl http2证书路径为/etc/nginx/ssl/nginx.crt与/etc/nginx/ssl/nginx.key。若需要对外提供加密访问可参照该配置挂载证书后复用同一套构建产物。另外Dockerfile-deploy还在镜像内生成了一个versions.sh脚本第 107-110 行执行docker exec 容器名 sh /usr/share/nginx/html/versions.sh可直接查看镜像内置了哪些文档版本。中文本地化与文档骨架同步DB-GPT 文档站内置zh-CN语言中文翻译存放在docs/i18n/zh-CN/docusaurus-plugin-content-docs/下。仓库提供了自动化的骨架同步脚本 docs/scripts/sync-docs-zh-skeleton.mjs遍历英文docs/docs/下所有.md/.mdx文件若中文目标目录中尚不存在对应文件则原样复制作为待翻译的骨架第 23-48 行同时将docs/static/下的静态资源复制到中文站点对应目录第 51-73 行已存在的文件会跳过保证不覆盖人工翻译成果。日常维护中文文档的推荐流程是新增英文文档后在docs/下运行yarn bootstrap-docs-zh内部依次执行write-translations --locale zh-CN与sync-docs-zh-skeleton生成中文占位文件后逐个翻译最后用yarn start:zh预览中文效果。常见问题与注意事项构建参数与镜像的关系NPM_REGISTRY、CI、NUM_VERSION必须在docker build时通过--build-arg显式传入NPM_REGISTRY也支持在命令前用环境变量赋值修改参数后需重新构建镜像才能生效。历史版本依赖多版本构建依赖 Git tag 列表若 clone 时使用了--depth 1浅克隆务必在 CItrue 下构建Dockerfile 会自动执行 unshallow 补齐 tag 历史。补丁机制历史 tag 的文档若在新版依赖下构建失败需将修复内容整理为docs/patchs/fix_{版本号}.patch命名规则为去掉版本号前的v如v0.6.3对应fix_0.6.3.patch构建脚本会自动发现并应用。端口冲突本地yarn start3000与 Docker 文档服务8089端口不同可同时运行若本机 8089 被占用修改docker run -p映射即可但需同步调整挂载的 nginx 配置监听端口。只读仓库约束当前仓库为只读状态本文所有构建、启动、部署操作均应在本地 clone 副本中进行不应直接在仓库工作区执行写操作。小结DB-GPT 文档站点采用本地开发 Docker 多版本发布的双轨方案yarn start支撑日常写作与调试docs/Dockerfile-deploy 配合NUM_VERSION、NPM_REGISTRY、CI三个构建参数自动遍历 Git tag 生成多版本静态站点再由 Nginx 容器对外提供服务。对于任何希望为开源项目搭建多版本文档站的团队这套tag 循环 checkout docusaurus docs:version patch 修复 nginx 托管的流水线都具备直接的参考价值。【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
DB-GPT 文档站点构建与 Docker 多版本部署实战指南【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT本文以 DB-GPT 仓库中的 docs/README.md 为核心系统讲解该项目基于 Docusaurus 构建的官方文档站点从本地启动到 Docker 化多版本发布的完整流程。读者将掌握依赖安装、本地开发调试、Docker 镜像构建参数的含义与调优、Nginx 容器托管以及多版本文档含中文 i18n 骨架同步的部署机制可直接复用于自建 Docusaurus 文档站的运维实践。文档站点整体形态DB-GPT 的官方文档独立存放于仓库根目录的docs/目录下是一套基于Docusaurus 3.4.0的静态站点。从 docs/package.json 可以看出核心依赖包括docusaurus/core、docusaurus/preset-classic、docusaurus/theme-mermaid支持 Mermaid 图表渲染以及easyops-cn/docusaurus-search-local站内本地搜索站点同时启用了en默认与zh-CN双语言支持语言配置在 docs/docusaurus.config.js 中声明Node.js 运行环境要求18.0。docs 目录中的关键组成包括docs/docs/英文文档主体、docs/i18n/中文本地化目录、docs/sidebars.js侧边栏配置、docs/static/静态资源以及docs/nginx/部署用 Nginx 配置。本地快速启动文档站点安装依赖先克隆 DB-GPT 仓库到本地然后在项目根目录进入docs/目录安装 Docusaurus 依赖生成node_modules目录# 进入 docs 目录后执行 yarn install由于 Docusaurus 依赖较多若网络环境不佳可改用 npm 并指定镜像源如https://registry.npmmirror.com与下方 Docker 构建时NPM_REGISTRY参数的用法一致。启动开发服务器yarn start默认开发服务监听3000端口浏览器访问http://localhost:3000即可实时预览文档。开发模式下 docs/docusaurus.config.js 将onBrokenLinks/onBrokenMarkdownLinks设为throw任何失效的内部链接都会直接中断构建便于在编写文档时第一时间暴露问题。常用 npm 脚本package.json 中定义了一组可直接复用的脚本脚本命令作用yarn start本地开发预览端口 3000支持热更新yarn start:zh以zh-CN语言环境启动本地预览yarn build构建生产静态文件输出到build/yarn serve本地静态托管已构建产物yarn write-translations抽取各语言待翻译文案yarn sync-docs-zh-skeleton同步中文文档骨架详见下文 i18n 章节yarn bootstrap-docs-zh一次性完成 zh-CN 翻译文案抽取与骨架同步深入 Docusaurus 站点配置docs/docusaurus.config.js 是文档站的中枢配置文件几个值得注意的实现点版本开关通过环境变量BUILD_FAST与DISABLE_VERSIONING控制是否启用多版本构建第 12-13 行。BUILD_FAST时onlyIncludeVersions仅保留current一份版本大幅缩短 CI 构建时间当前版本命名getNextVersionName()将开发中的文档版本固定命名为dev第 35-36 行与仓库发布版本区分开代码块渲染通过raw-loader支持在 Markdown/MDX 中直接内嵌.py与.ipynb源码第 118-131 行这与仓库大量 Python 示例代码的文档化需求直接相关侧边栏优化自定义sidebarItemsGenerator在长标签的分隔符/后插入零宽空格避免侧边栏标签被截断换行第 165-182 行。版本号清单维护在 docs/versions.json该文件当前为空数组表示仓库默认只发布dev即current版本Docker 多版本构建时由构建脚本动态生成正式版本。使用 Docker 部署多版本文档本地开发满足个人调试需求而对外提供多版本文档每个 Git 发布 tag 一套站点则需要 Docker 化部署。这是 docs/README.md 的核心场景也是本仓库提供 docs/Dockerfile-deploy 的原因。步骤一构建 Docker 镜像在DB-GPT 项目根目录注意不是 docs 目录内执行# 使用默认 npm 源https://registry.npmjs.org # 也可切换为国内镜像 https://www.npmmirror.com/ NPM_REGISTRYhttps://registry.npmmirror.com docker build -f docs/Dockerfile-deploy \ -t eosphorosai/dbgpt-docs \ --build-arg NPM_REGISTRY$NPM_REGISTRY \ --build-arg CIfalse \ --build-arg NUM_VERSION2 .该命令的三个构建参数含义如下构建参数默认值作用NPM_REGISTRYhttps://registry.npmjs.orgnpm 包下载源国内网络可替换为https://registry.npmmirror.comCItrue是否以 CI 模式构建为true时会执行git fetch --prune拉取完整 tag 历史含 shallow 仓库的 unshallow 操作NUM_VERSION2需要构建的文档版本数量取最新的 N 个 Git tag步骤二理解镜像内部的多版本构建原理Dockerfile-deploy 采用多阶段构建第一阶段node:lts-alpine负责依赖安装与站点构建第二阶段nginx:alpine只托管产物。核心逻辑位于第一阶段第 46-94 行记录当前分支位置后取按创建时间倒序的前NUM_VERSION个 Git tag若仓库无任何 tag则退化为取最近NUM_VERSION个提交短哈希第 51-55 行逐个 tag 执行git checkout并检查docs/patchs/下是否存在对应的fix_{版本}.patch补丁文件如 fix_0.6.3.patch、fix_0.7.4.patch存在则git apply应用用于修复历史版本文档在最新版 Docusaurus 下的兼容性问题第 61-72 行拷贝该版本对应的docs/、sidebars.js、static/、src/到构建目录执行docusaurus docs:version tag生成版本化文档第 73-80 行回到原分支将当前dev文档也纳入构建最后npm run build产出静态站点并把构建的版本清单写入build/versions.txt第 82-94 行。这种按 tag 循环 checkout 版本化 打补丁的方式保证了历史版本文档与最新版本文档可以在同一站点内共存并通过 Docusaurus 内置的版本下拉框切换。步骤三运行 Docker 容器docker run -it --rm -p 8089:8089 \ --name my-dbgpt-docs \ -v $(pwd)/docs/nginx/nginx-docs.conf:/etc/nginx/nginx.conf \ eosphorosai/dbgpt-docs容器内 Nginx 监听8089端口映射到宿主机的 8089 端口。关键点在于通过-v卷挂载将宿主机上的 docs/nginx/nginx-docs.conf 覆盖容器内/etc/nginx/nginx.conf——这样无需重新构建镜像即可调整 Nginx 行为。浏览器访问http://localhost:8089即可看到多版本文档站。提示--rm表示容器退出后自动删除如需常驻后台运行可将-it --rm替换为-d。Nginx 配置解析挂载的 nginx-docs.conf 是文档服务的对外网关核心配置包括worker_processes 1与worker_connections 1024适合文档站这类轻量静态服务server块监听8089root指向镜像内/usr/share/nginx/html即 Dockerfile 第二阶段拷贝构建产物的位置见 Dockerfile-deploy 第 103-105 行try_files $uri $uri/ /index.html实现 SPA 式回退确保 Docusaurus 客户端路由如/docs/get_started在直接刷新时也能正确命中index.html。仓库还提供了一份启用 HTTPS 的配置 docs/nginx/nginx-docs-ssl.confHTTP 80 端口通过return 301 https://$host$request_uri强制跳转 HTTPS443 端口开启ssl http2证书路径为/etc/nginx/ssl/nginx.crt与/etc/nginx/ssl/nginx.key。若需要对外提供加密访问可参照该配置挂载证书后复用同一套构建产物。另外Dockerfile-deploy还在镜像内生成了一个versions.sh脚本第 107-110 行执行docker exec 容器名 sh /usr/share/nginx/html/versions.sh可直接查看镜像内置了哪些文档版本。中文本地化与文档骨架同步DB-GPT 文档站内置zh-CN语言中文翻译存放在docs/i18n/zh-CN/docusaurus-plugin-content-docs/下。仓库提供了自动化的骨架同步脚本 docs/scripts/sync-docs-zh-skeleton.mjs遍历英文docs/docs/下所有.md/.mdx文件若中文目标目录中尚不存在对应文件则原样复制作为待翻译的骨架第 23-48 行同时将docs/static/下的静态资源复制到中文站点对应目录第 51-73 行已存在的文件会跳过保证不覆盖人工翻译成果。日常维护中文文档的推荐流程是新增英文文档后在docs/下运行yarn bootstrap-docs-zh内部依次执行write-translations --locale zh-CN与sync-docs-zh-skeleton生成中文占位文件后逐个翻译最后用yarn start:zh预览中文效果。常见问题与注意事项构建参数与镜像的关系NPM_REGISTRY、CI、NUM_VERSION必须在docker build时通过--build-arg显式传入NPM_REGISTRY也支持在命令前用环境变量赋值修改参数后需重新构建镜像才能生效。历史版本依赖多版本构建依赖 Git tag 列表若 clone 时使用了--depth 1浅克隆务必在 CItrue 下构建Dockerfile 会自动执行 unshallow 补齐 tag 历史。补丁机制历史 tag 的文档若在新版依赖下构建失败需将修复内容整理为docs/patchs/fix_{版本号}.patch命名规则为去掉版本号前的v如v0.6.3对应fix_0.6.3.patch构建脚本会自动发现并应用。端口冲突本地yarn start3000与 Docker 文档服务8089端口不同可同时运行若本机 8089 被占用修改docker run -p映射即可但需同步调整挂载的 nginx 配置监听端口。只读仓库约束当前仓库为只读状态本文所有构建、启动、部署操作均应在本地 clone 副本中进行不应直接在仓库工作区执行写操作。小结DB-GPT 文档站点采用本地开发 Docker 多版本发布的双轨方案yarn start支撑日常写作与调试docs/Dockerfile-deploy 配合NUM_VERSION、NPM_REGISTRY、CI三个构建参数自动遍历 Git tag 生成多版本静态站点再由 Nginx 容器对外提供服务。对于任何希望为开源项目搭建多版本文档站的团队这套tag 循环 checkout docusaurus docs:version patch 修复 nginx 托管的流水线都具备直接的参考价值。【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
