ci(文档部署): 优化文档构建和部署流程

添加 Rust 工具链和 mdBook 的缓存机制以减少构建时间
简化部署步骤并添加详细的注释说明
更新文档标题格式为一级标题

.gitea/workflows/build_and_deploy_docs.yml

@@ -12,7 +12,27 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4 # 使用最新的 checkout action
 
-      # 新增：安装 Rust 工具链
+      # 步骤 1: 缓存 Rust 工具链和 Cargo 相关文件
+      - name: Cache Rust and mdBook artifacts
+        uses: actions/cache@v4 # 使用 actions/cache Action
+        with:
+          path: | # 需要缓存的路径
+            ~/.cargo/registry # Cargo 的包注册表缓存
+            ~/.cargo/git      # Cargo 的 Git 依赖缓存
+            ~/.cargo/bin      # Cargo 安装的二进制文件（mdBook 会在这里）
+            ~/.rustup         # Rustup 工具链本身的安装目录
+          key: ${{ runner.os }}-rust-${{ hashFiles('book.toml') }}-${{ hashFiles('.gitea/workflows/build-and-deploy-docs.yml') }} # 缓存键
+          # 缓存键的含义：
+          #   - ${{ runner.os }}: 操作系统类型（如 Ubuntu），确保不同 OS 的缓存隔离
+          #   - rust-: 固定前缀
+          #   - ${{ hashFiles('book.toml') }}: 如果 book.toml 文件内容变化，缓存失效（例如 mdBook 配置或版本变更）
+          #   - ${{ hashFiles('.gitea/workflows/build-and-deploy-docs.yml') }}: 如果 workflow 文件本身变化，缓存失效（例如 Rust toolchain 版本变化或 mdBook 安装方式变化）
+          restore-keys:
+            | # 恢复键（当主键不匹配时，尝试恢复更旧的、不那么精确的缓存）
+            ${{ runner.os }}-rust-${{ hashFiles('book.toml') }}
+            ${{ runner.os }}-rust-
+
+      # 步骤 2: 设置 Rust 工具链
       - name: Setup Rust toolchain
         uses: actions-rs/toolchain@v1 # 使用 actions-rs/toolchain 来安装 Rust
         with:
@@ -20,25 +40,28 @@ jobs:
           profile: minimal # 安装最小化配置文件，只包含 cargo 和 rustc，下载更快
           override: true # 确保这个 Rust 版本被设置为默认
 
+      # 步骤 3: 有条件地安装 mdBook (如果缓存未命中)
       - name: Install mdBook
         run: |
-          cargo install mdbook --locked --no-default-features # 只安装 mdbook，不安装额外特性以加速
+          # 检查 mdbook 是否已经安装在 PATH 中 (通过缓存恢复)
+          if ! command -v mdbook &> /dev/null
+          then
+              echo "mdBook not found or not in PATH, installing..."
+              cargo install mdbook --locked --no-default-features
+          else
+              echo "mdBook already installed (from cache or previous step), skipping installation."
+          fi
 
       - name: Build mdBook
         run: mdbook build # 构建文档到默认的 'book' 目录
 
       - name: Deploy to Gitea Pages
-        # 这里需要以 root 权限访问 Gitea PAGES_ROOT
-        # 实际部署时可能需要 SSH 密钥、或 Gitea Runner 特殊权限，
-        # 或者 Gitea Actions 提供了官方的 Pages 部署 action
-        # 假设你的 Gitea Runner 有权限写入 /root/gitea/gitea/data/pages/dao-os/dao-os-docs/
         run: |
-          # 清理旧的 docs 目录
+          # 确保 Gitea Runner 运行用户拥有 /root/gitea/gitea/data/pages/ 的写入权限
           sudo rm -rf /root/gitea/gitea/data/pages/dao-os/dao-os-docs/*
-          # 复制新构建的文档
           sudo cp -r book/* /root/gitea/gitea/data/pages/dao-os/dao-os-docs/
         env:
-          # 你可能需要在这里配置 SSH 密钥或其他凭据，以便 Gitea Runner 有权限写入目标目录
-          # GITEA_SSH_KEY: ${{ secrets.GITEA_SSH_KEY }}
-          # 确保 Gitea Runner 运行用户拥有 /root/gitea/gitea/data/pages/ 的写入权限
-          # 或者，如果你使用官方的 Pages 部署 action，则无需手动 cp
+          # 如果你的 Gitea Runner 需要特定权限来写入 pages 目录，这里需要配置
+          # 例如：GITEA_SSH_KEY: ${{ secrets.GITEA_SSH_KEY }}
+          # 具体取决于你的 Gitea Runner 如何与 Pages 目录进行权限交互。
+          # 对于自建的 Gitea Actions Runner，你需要确保运行它的用户对 /root/gitea/gitea/data/pages 具有写入权限。

src/SUMMARY.md

@@ -7,13 +7,13 @@
 
 ---
 
-## 子项目文档
+# 子项目文档
 
 * [meta-unit-core 文档](https://mask.doylee.cn/dao-os/meta-unit-core/)
 * [meta-unit-proto 文档](https://mask.doylee.cn/dao-os/meta-unit-proto/)
 * [Avatar Host 文档](https://mask.doylee.cn/dao-os/avatar-host-rust-cli/) (假设存在)
 
-## 贡献者指南
+# 贡献者指南
 
 * [行为准则](CODE_OF_CONDUCT.md)
 * [贡献指南](CONTRIBUTING.md)