2921323707 · 2921323707 · Jul 22, 2026
@@ -7,6 +7,13 @@ updates:
     groups:
       frontend-dependencies:
         patterns: ["*"]
+  - package-ecosystem: npm
+    directory: /docs
+    schedule:
+      interval: weekly
+    groups:
+      documentation-dependencies:
+        patterns: ["*"]
   - package-ecosystem: gomod
     directory: /server
     schedule:

@@ -0,0 +1,105 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-production-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    name: Build VitePress site
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+      - run: npm ci
+      - name: Add deployment revision
+        env:
+          DOCS_REVISION: ${{ github.sha }}
+        run: printf '%s\n' "$DOCS_REVISION" > public/revision.txt
+      - run: npm run build
+      - name: Verify generated routes
+        run: |
+          test -f .vitepress/dist/index.html
+          test -f .vitepress/dist/roadmap.html
+          test -f .vitepress/dist/zh/roadmap.html
+          test -f .vitepress/dist/revision.txt
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cpa-orbit-docs-${{ github.sha }}
+          path: docs/.vitepress/dist
+          if-no-files-found: error
+          retention-days: 14
+
+  deploy:
+    name: Deploy documentation
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: documentation
+      url: http://165.154.205.54/cpa_orbit/
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: cpa-orbit-docs-${{ github.sha }}
+          path: dist
+      - name: Configure SSH
+        env:
+          DOCS_SSH_PRIVATE_KEY: ${{ secrets.DOCS_SSH_PRIVATE_KEY }}
+          DOCS_SSH_KNOWN_HOSTS: ${{ secrets.DOCS_SSH_KNOWN_HOSTS }}
+        run: |
+          install -m 700 -d ~/.ssh
+          printf '%s\n' "$DOCS_SSH_PRIVATE_KEY" > ~/.ssh/docs_deploy
+          chmod 600 ~/.ssh/docs_deploy
+          printf '%s\n' "$DOCS_SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts
+          chmod 600 ~/.ssh/known_hosts
+      - name: Synchronize generated site
+        env:
+          DOCS_HOST: ${{ vars.DOCS_HOST }}
+          DOCS_SSH_PORT: ${{ vars.DOCS_SSH_PORT }}
+          DOCS_SSH_USER: ${{ vars.DOCS_SSH_USER }}
+          DOCS_DEPLOY_PATH: ${{ vars.DOCS_DEPLOY_PATH }}
+        run: |
+          : "${DOCS_HOST:?Set DOCS_HOST in the documentation environment}"
+          : "${DOCS_SSH_USER:?Set DOCS_SSH_USER in the documentation environment}"
+          : "${DOCS_DEPLOY_PATH:?Set DOCS_DEPLOY_PATH in the documentation environment}"
+          DOCS_SSH_PORT="${DOCS_SSH_PORT:-22}"
+          case "$DOCS_DEPLOY_PATH" in
+            /cpa_orbit|/cpa_orbit/) ;;
+            *) echo "Refusing unexpected deployment path: $DOCS_DEPLOY_PATH" >&2; exit 1 ;;
+          esac
+          rsync -az --delete --delay-updates \
+            -e "ssh -i ~/.ssh/docs_deploy -p $DOCS_SSH_PORT" \
+            dist/ "$DOCS_SSH_USER@$DOCS_HOST:${DOCS_DEPLOY_PATH%/}/"
+      - name: Verify public deployment
+        env:
+          DOCS_REVISION: ${{ github.sha }}
+        run: |
+          base='http://165.154.205.54/cpa_orbit'
+          curl --fail --silent --show-error --retry 5 --retry-delay 3 "$base/" >/dev/null
+          curl --fail --silent --show-error --retry 5 --retry-delay 3 "$base/roadmap" >/dev/null
+          curl --fail --silent --show-error --retry 5 --retry-delay 3 "$base/zh/roadmap" >/dev/null
+          curl --fail --silent --show-error --retry 5 --retry-delay 3 "$base/favicon.svg" >/dev/null
+          test "$(curl --fail --silent --show-error --retry 5 --retry-delay 3 "$base/revision.txt")" = "$DOCS_REVISION"
@@ -44,10 +44,28 @@ location ^~ /cpa_orbit/ {
 }
 ```
 
+## Automatic publication
+
+`docs/` is the single source for the online site, including [`roadmap.md`](./roadmap.md), which builds to `/cpa_orbit/roadmap`. The `Documentation` GitHub Actions workflow builds every documentation pull request and deploys documentation changes merged into `main`.
+
+Configure a GitHub environment named `documentation` with:
+
+| Name | Type | Purpose |
+| --- | --- | --- |
+| `DOCS_SSH_PRIVATE_KEY` | Secret | Private key for the restricted deployment account. |
+| `DOCS_SSH_KNOWN_HOSTS` | Secret | Pinned SSH host-key entry for the documentation server. |
+| `DOCS_HOST` | Variable | Deployment host, currently `165.154.205.54`. |
+| `DOCS_SSH_USER` | Variable | Restricted SSH deployment user. |
+| `DOCS_SSH_PORT` | Variable | SSH port; defaults to `22` when omitted. |
+| `DOCS_DEPLOY_PATH` | Variable | Must be `/cpa_orbit`; the workflow refuses any other path. |
+
+The deployment account must have write access only to `/cpa_orbit`. The workflow uploads generated `dist/` files with `rsync`, removes stale generated files within that bounded directory, and then verifies the home, English/Chinese roadmap, favicon, and commit revision marker over HTTP. Use the workflow's manual dispatch to republish the current `main` documentation without a source change.
+
 ## Release checks
 
-- Direct refresh works on the home, guide, and modules routes.
+- Direct refresh works on the home, guide, roadmap, and modules routes.
 - English is the default and the language menu opens the matching Chinese route.
-- `/cpa_orbit/favicon.svg` and `/cpa_orbit/assets/` return 200.
+- `/cpa_orbit/favicon.svg`, `/cpa_orbit/assets/`, and `/cpa_orbit/revision.txt` return 200.
+- The deployed `revision.txt` matches the commit built by GitHub Actions.
 - Only the generated `dist/` contents are public.
 - Source, `.git/`, `node_modules/`, and local runtime data remain outside the web surface.
@@ -17,9 +17,27 @@ npm run build
 
 发布目录为 `docs/.vitepress/dist/`。当前站点使用基础路径 `/cpa_orbit/`，可通过 **[CPA Orbit 在线文档](http://165.154.205.54/cpa_orbit/)** 直接访问。
 
+## 自动发布
+
+`docs/` 是在线文档的唯一内容来源，其中 [`docs/roadmap.md`](../roadmap.md) 构建为 `/cpa_orbit/roadmap`，本文档的中文路线图构建为 `/cpa_orbit/zh/roadmap`。GitHub Actions 的 `Documentation` 工作流会构建每个文档 PR，并在文档改动合并到 `main` 后自动发布。
+
+需要在 GitHub 中建立名为 `documentation` 的 Environment，并配置：
+
+| 名称 | 类型 | 用途 |
+| --- | --- | --- |
+| `DOCS_SSH_PRIVATE_KEY` | Secret | 受限部署账号的 SSH 私钥。 |
+| `DOCS_SSH_KNOWN_HOSTS` | Secret | 文档服务器固定的 SSH host key。 |
+| `DOCS_HOST` | Variable | 部署主机，当前为 `165.154.205.54`。 |
+| `DOCS_SSH_USER` | Variable | 仅用于文档部署的 SSH 用户。 |
+| `DOCS_SSH_PORT` | Variable | SSH 端口；未设置时使用 `22`。 |
+| `DOCS_DEPLOY_PATH` | Variable | 必须为 `/cpa_orbit`，工作流会拒绝其他路径。 |
+
+部署账号应当仅能写入 `/cpa_orbit`。工作流通过 `rsync` 同步生成的 `dist/` 文件、清除该限定目录中的旧生成文件，然后通过 HTTP 验证首页、中英文路线图、favicon 以及提交 revision 标记。需要重新发布当前 `main` 文档而不改源码时，可以手动运行该工作流。
+
 ## 发布检查
 
-- 首页、指南与模块页面可以直接刷新。
+- 首页、指南、路线图与模块页面可以直接刷新。
 - 默认显示英文，语言菜单可以切换到对应中文页面。
-- favicon 与静态资源返回 200。
+- `/cpa_orbit/favicon.svg`、`/cpa_orbit/assets/` 与 `/cpa_orbit/revision.txt` 返回 200。
+- 线上 `revision.txt` 与 GitHub Actions 构建的提交一致。
 - 服务器只公开 `dist/`，不公开源码、`.git/`、`node_modules/` 或运行数据。