基于 StarRocks 官方文档构建内网文档站点（Linux 部署指南）
1. 背景与目标
为了提升内部研发与运维对 StarRocks 的使用效率，需要在公司内网部署一套 可访问 的 StarRocks 文档站点，并支持后续同步更新。
本指南目标：
- 在 Linux 服务器中部署一套内部 StarRocks 文档站点
- 支持 Markdown 文档渲染
- 能与 StarRocks 官方文档保持同步（手动或自动）
2. 说明
- StarRocks 官方文档是基于 Docusaurus
- 内网环境可纯静态部署，无需数据库
- 支持 Markdown + 版本管理
3. 克隆代码仓库
git clone -b branch-3.3 https://github.com/StarRocks/starrocks.git
cd starrocks
4. 环境准备
系统要求
- Linux（CentOS7 / Ubuntu 20+ / Rocky / Debian 均可）
- Node.js ≥ 18（推荐用 nvm 管理）
- Git
- Nginx（用于静态文件托管）
由于大部分服务器都使用centos 7，涉及的包都比较旧，在无网络的情况下升级是非常麻烦的，所以这里最好采用docker 的方式来构建，构建完毕后，直接部署build 目录即可。 如果不使用docker 构建，参考文档第6步即可
docker 构建方式
1. 在/opt/sr-docs/ 目录下创建Dockerfile
FROM node:20
# 设置工作目录
WORKDIR /build
2. 创建docker image
sudo docker build -t sr-docs-builder -f sr-docs-builder.Dockerfile .
3. 查看
sudo docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
sr-docs-builder latest 427373d09631 17 seconds ago 1.1GB
4. 挂载并启动
这里挂载只需要挂载docs 目录即可，无需挂载整个项目
例如：
[user@cs03 starrocks]$ ll
总用量 539952
drwxr-xr-x 9 <user> <user> 4096 11月 11 10:47 docs
-rw-rw-r-- 1 <user> <user> 50 11月 18 17:27 sr-docs-builder.Dockerfile
-rw-r--r-- 1 <user> <user> 552893879 11月 17 17:43 starrocks-docs.zip
[user@cs03 starrocks]$
[user@cs03 starrocks]$
[user@cs03 starrocks]$ ll docs
总用量 36
drwxr-xr-x 11 <user> <user> 4096 11月 18 17:47 docusaurus
drwxr-xr-x 22 <user> <user> 4096 11月 11 10:47 en
drwxr-xr-x 22 <user> <user> 4096 11月 11 10:47 ja
-rw-r--r-- 1 <user> <user> 2947 11月 11 10:47 lychee.toml
-rw-r--r-- 1 <user> <user> 61 11月 11 10:47 mlc_config.json
drwxr-xr-x 2 <user> <user> 4096 11月 11 10:47 PDFoutput
-rw-r--r-- 1 <user> <user> 4088 11月 11 10:47 README.md
drwxr-xr-x 6 <user> <user> 4096 11月 11 10:47 translation
drwxr-xr-x 23 <user> <user> 4096 11月 11 10:47 zh
启动
sudo docker run -it --name sr-docs -v /home/disk1/<user>/opt/docs/starrocks:/build/starrocks sr-docs-builder bash
5. 准备文档文件
StarRocks 文档源文件：
-
英文:
docs/en/ -
中文:
docs/zh/ -
日文:
docs/ja/（可选）
6. 构建多语言文档
进入 Docusaurus 项目目录：
cd /build/starrocks/docs/docusaurus
# 安装依赖
yarn install --frozen-lockfile
# 清除缓存
yarn clear
rm -rf ./docs
rm -rf ./build
rm -rf ./.docusaurus
复制文档源文件：
# 英文文档
mkdir -p ./docs
cp -r ../en/* ./docs/
# 中文文档
rm -rf ./i18n/zh/docusaurus-plugin-content-docs/current
mkdir -p ./i18n/zh/docusaurus-plugin-content-docs
cp -r ../zh ./i18n/zh/docusaurus-plugin-content-docs/current
# 日文文档（可选）
rm -rf ./i18n/ja/docusaurus-plugin-content-docs/current
mkdir -p ./i18n/ja/docusaurus-plugin-content-docs
cp -r ../ja ./i18n/ja/docusaurus-plugin-content-docs/current
删除不需要的内容（可选）：
rm -rf ./docs/release_notes ./docs/ecosystem_release
rm -rf ./i18n/zh/docusaurus-plugin-content-docs/current/release_notes
rm -rf ./i18n/zh/docusaurus-plugin-content-docs/current/ecosystem_release
构建：
DOCUSAURUS_IGNORE_SSG_WARNINGS=true DISABLE_VERSIONING=true yarn build
构建完成后退出docker 即可，build 目录在
/home/disk1/user/opt/docs/starrocks/docs/docusaurus
7. 部署到后台服务器
方法一：使用 Nginx 部署静态文件
构建完成后，静态文件位于 docs/docusaurus/build/。
# 安装 Nginx
sudo apt-get update
sudo apt-get install nginx
# 复制构建文件到 Nginx 目录
sudo cp -r docs/docusaurus/build/* /var/www/html/
# 启动服务
sudo systemctl start nginx
sudo systemctl enable nginx
访问地址：
-
英文：
http://your-server-ip/docs/ -
中文：
http://your-server-ip/zh/docs/
方法二：使用 Docusaurus 内置服务器
cd docs/docusaurus
# 前台启动
yarn serve
# 后台运行
nohup yarn serve > docusaurus.log 2>&1 &
默认端口：http://localhost:3000
方法三：使用 PM2 管理进程
npm install -g pm2
cd docs/docusaurus
pm2 start yarn --name "starrocks-docs" -- serve
pm2 startup
pm2 save
开发模式（本地预览）
cd docs/docusaurus
# 启动开发服务器（支持热重载）
yarn start
# 只启动中文
yarn start --locale zh
访问：http://localhost:3000
环境变量说明
-
DISABLE_VERSIONING=true：禁用版本管理，只构建当前版本 -
DOC_LOCALE=zh：构建指定语言 -
DOCUSAURUS_IGNORE_SSG_WARNINGS=true：忽略警告 -
NODE_OPTIONS=--max-old-space-size=8192：增加 Node 内存限制
常见问题
1. Node.js 版本不兼容
使用 Node.js 18 或 20，避免 25.x。
2. 构建缓存问题
执行 yarn clear。
3. 文档文件未找到
确保正确复制源文档至 docs/docusaurus/docs/。
Notes
-
生产环境建议使用 Nginx 或其他 Web 服务器部署静态文件
-
开发模式 (
yarn start) 不适合生产环境 -
构建时间取决于文档数量
-
官方文档地址：https://docs.starrocks.io/