【运维篇】如何基于官方文档构建一个在内网使用的文档

📥 社区投稿 最佳实践
#1

基于 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/

1赞

京ICP备2022026421号-1