Rspress 部署与更新流程

本文档记录 RyB 知识库从本地开发到服务器部署的完整流程，以及后续内容更新的操作步骤。

环境信息

项目	说明
文档仓库本地路径	`D:\Projects\vcpkg\vcpkg\vcpkg\safeSpace\RybKownledgeBase`
Rspress 仓库本地路径	`D:\Projects\vcpkg\vcpkg\vcpkg\safeSpace\RyBRspress`
框架	Rspress `1.47.2`
Node.js	本地 ≥ 18，服务器 Node.js 20
文档 Git 仓库	`https://gitee.com/hisos/ryb-knowledge-base.git`
Rspress Git 仓库	`https://gitee.com/hisos/ryb_rpress.git`
服务器	腾讯云 Ubuntu，IP `118.24.117.176`，用户 `ubuntu`
访问地址	`http://notes.toobox.love/`

项目结构

RybKownledgeBase/                 # https://gitee.com/hisos/ryb-knowledge-base.git
├── public_docs/                  # 公共知识库文档与静态资源
├── private_docs/                 # 个人知识空间文档
├── .gitignore                    # 忽略本地工具/杂项文件
└── .windsurfrules                # 本地 AI 工作流规则（可选）

RyBRspress/                       # https://gitee.com/hisos/ryb_rpress.git
├── theme/components/             # 知识库外壳、搜索、大纲、图片查看器
├── styles/index.css              # 全局自定义样式
├── kb-navigation.json            # 公共/个人导航配置
├── rspress.config.ts             # 公共文档构建配置
├── rspress.private.config.ts     # 个人文档构建配置
├── package.json                  # 依赖与脚本
├── deploy.sh                     # 原子构建与部署脚本
└── webhook.js                    # 服务器端 Webhook 监听

本地开发

Rspress 工程与文档分开存放。Rspress 配置默认读取同级目录下的 RybKownledgeBase，也可以通过 KB_CONTENT_ROOT 指向其他文档仓库。

安装依赖

cd D:\Projects\vcpkg\vcpkg\vcpkg\safeSpace\RyBRspress
npm install

启动开发服务器

npm run dev

默认在 http://localhost:5173/ 访问。

构建生产包

npm run build

构建产物输出到 RyBRspress/doc_build/ 目录。

本地预览构建结果

npm run preview

服务器部署（首次）

1. 服务器环境准备

# 安装 Node.js 20
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证
node -v   # 应显示 v20.x
npm -v

2. 配置 SSH 免密登录

本地机器生成密钥（如已有可跳过）：

ssh-keygen -t ed25519

将本地公钥添加到服务器：

ssh-copy-id ubuntu@118.24.117.176

验证免密登录：

ssh ubuntu@118.24.117.176 'echo ok'

3. 服务器配置 Gitee SSH Key

服务器需要拉取私有仓库，需将服务器公钥添加到 Gitee：

# 在服务器上查看公钥
cat ~/.ssh/id_ed25519.pub
# 若不存在则先生成
ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519

将输出的公钥添加到 Gitee → 设置 → SSH 公钥。

4. 克隆仓库

sudo mkdir -p /home/projects
sudo chown ubuntu:ubuntu /home/projects
cd /home/projects
git clone git@gitee.com:hisos/ryb-knowledge-base.git
git clone git@gitee.com:hisos/ryb_rpress.git

5. 安装依赖并首次构建

cd /home/projects/ryb_rpress
KB_CONTENT_ROOT=/home/projects/ryb-knowledge-base npm install
KB_CONTENT_ROOT=/home/projects/ryb-knowledge-base npm run build

6. 配置目录权限

Nginx 以 www-data 用户运行，需要读取权限：

chmod o+rx /home/projects
chmod -R o+rX /home/projects/ryb_rpress/doc_build

7. 配置 Nginx

新建 /etc/nginx/sites-enabled/notes-toobox-love.conf：

server {
    listen 80;
    server_name notes.toobox.love;

    # 静态资源（带 hash）：长缓存 + 预压缩
    location ^~ /static/ {
        alias /home/projects/ryb_rpress/knowledge_live/static/;
        expires 30d;
        add_header Cache-Control "public, max-age=2592000, immutable" always;
        access_log off;
        gzip_static on;
    }

    # 页面：原子软链；HTML 不长期缓存
    location / {
        alias /home/projects/ryb_rpress/knowledge_live/;
        index index.html;
        add_header Cache-Control "no-cache" always;
        gzip_static on;
    }
}

WARNING

🚧 部署前确保 DNS 已添加 notes.toobox.love A 记录指向 118.24.117.176。

主配置 /etc/nginx/nginx.conf 的 http 段务必打开：

gzip on;
gzip_vary on;
gzip_comp_level 5;
gzip_types text/plain text/css application/javascript application/json image/svg+xml ...;

TIP

慢加载常见原因：只开了 gzip on 却注释掉 gzip_types，导致 JS/CSS 不压缩（单文件可达 2MB+）。
deploy.sh 会预生成 .gz，配合 gzip_static on 直接吐压缩文件。

WARNING

🚧 必须使用 ^~ 前缀匹配，否则会被已有的 ~* 正则规则（css/js）拦截导致 404。
部署必须用原子切换（deploy.sh 构建到 releases/<id> 再切 knowledge_live），禁止在 Nginx 正在读的目录里直接 npm run build，否则构建中会间歇 404。

重载 Nginx：

sudo nginx -t
sudo systemctl reload nginx

8. 配置 Webhook 自动部署

部署脚本 `deploy.sh`

仓库根目录已包含 deploy.sh（纳入 Git）。要点：

KB_OUT_DIR=releases/<时间戳> 旁路构建
校验 index.html 存在
ln -sfn + mv -T 原子切换 knowledge_live
只保留最近 5 个 release

chmod +x /home/projects/ryb_rpress/deploy.sh
KB_CONTENT_ROOT=/home/projects/ryb-knowledge-base bash /home/projects/ryb_rpress/deploy.sh

Webhook 监听服务

项目根目录的 webhook.js 监听 127.0.0.1:9001，验证密码后执行 deploy.sh。

使用 pm2 启动：

sudo npm install -g pm2
cd /home/projects/ryb_rpress
WEBHOOK_SECRET='你的密码' WEBHOOK_PORT=9001 DEPLOY_SCRIPT=/home/projects/ryb_rpress/deploy.sh pm2 start webhook.js --name webhook
pm2 save
pm2 startup    # 开机自启

Nginx 反向代理 Webhook（可选）

如需从外网接收 Gitee Webhook 请求，在 Nginx 中添加：

location /webhook/ {
    proxy_pass http://127.0.0.1:9001/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

配置 Gitee Webhook

进入 Gitee 仓库 → 管理 → WebHooks
URL 填写：http://notes.toobox.love/webhook/（或服务器 IP:端口）
密码填写：与 WEBHOOK_SECRET 一致
触发事件选择：Push

后续更新流程

日常更新内容

文档和 Rspress 代码分别提交到各自仓库：

# 更新文档
cd /home/projects/ryb-knowledge-base
git add public_docs private_docs
git commit -m "更新笔记内容"
git push

# 更新 Rspress 配置、主题或部署脚本时
cd /home/projects/ryb_rpress
git add theme styles kb-navigation.json rspress.config.ts rspress.private.config.ts package.json package-lock.json deploy.sh webhook.js
git commit -m "更新 Rspress 展示层"
git push

任一仓库推送后，Gitee Webhook 自动触发服务器 RyBRspress/deploy.sh；脚本会分别更新两个仓库，再构建站点。

手动触发部署

如 Webhook 未生效，可手动 SSH 执行：

ssh ubuntu@118.24.117.176 'KB_CONTENT_ROOT=/home/projects/ryb-knowledge-base bash /home/projects/ryb_rpress/deploy.sh'

更新图表（D2）

全库图表统一用 D2 源文件 + 渲染出的 SVG，两者都纳入 Git：

public_docs/<主题>/diagrams/图1_xxx.d2        ← 源文件（改这个）
public_docs/<主题>/diagrams/图1_xxx.d2.svg    ← 渲染产物
public_docs/public/<主题>/diagrams/图1_xxx.d2.svg  ← 实际被站点访问的副本

Markdown 里引用的始终是 .d2.svg：

![图 1 · xxx](/主题/diagrams/图1_xxx.d2.svg)

改图流程（需先安装 D2）：

# 1. 编辑 public_docs/<主题>/diagrams/图1_xxx.d2
# 2. 渲染（只重编译有改动的，加 -Force 全量重编译）
powershell -File scripts/build-d2.ps1
# 3. 同步到 public（站点静态目录）
powershell -File scripts/sync-diagrams-public.ps1

TIP

scripts/svg2d2.py 是一次性迁移工具（旧的手写 .drawio.svg → .d2）。它生成的文件头部带 # generated-by: scripts/svg2d2.py 标记，--overwrite 只会覆盖带此标记的文件，手写 D2 不会被覆盖。日常改图只需改 .d2 后跑 build-d2.ps1，不要再跑迁移脚本。

升级 Rspress 版本

cd /home/projects/ryb_rpress
# 本地修改 package.json 中 rspress 版本号
# 或
npm install rspress@<目标版本>

# 本地测试（默认读取同级 RybKownledgeBase 文档）
npm run dev
npm run build

# 确认无误后推送，服务器自动部署
git add package.json package-lock.json
git commit -m "升级 rspress 到 xxx 版本"
git push

TIP

升级 Rspress 大版本时，注意检查 rspress.config.ts 配置兼容性，以及 OutlineToggle.tsx 等自定义组件的类名是否需要适配。

排查指南

访问 404

检查 Nginx location 是否用了 ^~ 前缀
检查 knowledge_live/ 软链是否指向有效的 release 目录
检查 chmod -R o+rX doc_build 权限

Webhook 不触发

检查 Gitee Webhook 密码与服务器 WEBHOOK_SECRET 是否一致
检查 pm2 服务是否运行：pm2 status
查看日志：pm2 logs webhook

构建失败

SSH 到服务器手动执行 deploy.sh 查看错误输出
检查 Node.js 版本：node -v（需 ≥ 18）
检查磁盘空间：df -h

样式异常

清除浏览器缓存后重试
检查 styles/index.css 是否有冲突的自定义样式
确认 rspress.config.ts 中 globalStyles 路径正确

Rspress 部署与更新流程#

环境信息#

项目结构#

本地开发#

安装依赖#

启动开发服务器#

构建生产包#

本地预览构建结果#

服务器部署（首次）#

1. 服务器环境准备#

2. 配置 SSH 免密登录#

3. 服务器配置 Gitee SSH Key#

4. 克隆仓库#

5. 安装依赖并首次构建#

6. 配置目录权限#

7. 配置 Nginx#

8. 配置 Webhook 自动部署#

部署脚本 deploy.sh#

Webhook 监听服务#

Nginx 反向代理 Webhook（可选）#

配置 Gitee Webhook#

后续更新流程#

日常更新内容#

手动触发部署#

更新图表（D2）#

升级 Rspress 版本#

排查指南#

访问 404#

Webhook 不触发#

构建失败#

样式异常#