dao-os-docs/.gitea/workflows/build_and_deploy_docs.yml

name: Build and Deploy Dao OS Docs

on:
  push:
    branches:
      - main # 当推送到 main 分支时触发

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest # 或者你的 Gitea Actions 运行器
    env: # 在 Job 级别设置环境变量
      ACTIONS_STEP_DEBUG: true # 启用 Actions 步骤的调试输出
      ACTIONS_RUNNER_DEBUG: true # 启用 Runner 的调试输出
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4 # 使用最新的 checkout action

      # 步骤 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:
          toolchain: stable # 安装稳定版 Rust
          profile: minimal # 安装最小化配置文件，只包含 cargo 和 rustc，下载更快
          override: true # 确保这个 Rust 版本被设置为默认

      # 步骤 3: 有条件地安装 mdBook (如果缓存未命中)
      - name: Install mdBook
        run: |
          # 检查 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
        run: |
          # 确保 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:
          # 如果你的 Gitea Runner 需要特定权限来写入 pages 目录，这里需要配置
          # 例如：GITEA_SSH_KEY: ${{ secrets.GITEA_SSH_KEY }}
          # 具体取决于你的 Gitea Runner 如何与 Pages 目录进行权限交互。
          # 对于自建的 Gitea Actions Runner，你需要确保运行它的用户对 /root/gitea/gitea/data/pages 具有写入权限。