📝 调整文档分层并补充 workflow 运行模型

2026-05-22 11:08:15 +08:00 · 2026-05-22 11:08:15 +08:00 · 0579c2dc97
parent beab4e5696
commit 0579c2dc97
5 changed files with 82 additions and 68 deletions
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@ -36,9 +36,6 @@ docker-runner/
 │   ├── register.sh           # Runner 注册脚本
 │   └── manage.sh             # Runner 管理脚本
 │
-├── .gitea/ci/
-│   └── bootstrap_workspace.sh # workflow 自举脚本(下载后准备 mirror 和独立工作区)
-│
 └── presets/                   # 预设配置(选择一个使用)
    ├── standard-ubuntu-22/    # 标准版 (Ubuntu 22.04)
    │   ├── Dockerfile
@ -56,14 +53,7 @@ docker-runner/
 - `common/` 目录中的脚本由所有版本共享,其中 `entrypoint.sh`、`setup.sh`、`upgrade.sh`、`register.sh`、`manage.sh` 会通过 docker-compose.yml 挂载到容器
 - `check_crlf.sh` 是宿主机本地检查工具,用于在构建前修复 `common/` 目录脚本的换行符和执行权限
 - `presets/` 目录中每个子目录是一个完整的预设配置,包含 Dockerfile 和 docker-compose.yml
- 数据持久化在 `runner-data/` 目录(自动创建),包含 runner 配置、mirror 缓存和 act_runner 二进制文件
-
-### 并发与工作区模型
-
- 新注册的 runner 默认 `capacity=4`
- 共享仓库缓存保存在 `/data/git-mirrors/<owner>/<repo>.git`
- 每个 job 会从 mirror 本地克隆到独立目录 `/home/workspace/jobs/<owner>/<repo>/<job-identity>/repo`
- job 结束后临时工作目录会自动清理，mirror 会保留以加速后续大仓库同步
+- 数据持久化在 `runner-data/` 目录(自动创建),包含 runner 配置和 act_runner 二进制文件

 ---

@ -607,9 +597,6 @@ docker system df
 runner-data/
 ├── bin/
 │   └── act_runner        # Runner 可执行文件(持久化)
-├── git-mirrors/          # 持久化 bare mirror 缓存
-│   └── <owner>/
-│       └── <repo>.git
 ├── runners/              # Runner 配置目录
 │   └── <runner-name>/
 │       ├── .runner       # 注册信息
@ -619,7 +606,7 @@ runner-data/
    └── .configured
 ```

-容器重启或重建后,数据不会丢失。workflow 的临时工作目录位于 `/home/workspace/jobs/...`,任务结束后会自动清理,不会作为持久化数据保留。
+容器重启或重建后,这些持久化数据不会丢失。

 ### Q10: 如何切换不同预设?

--- a/README.md
+++ b/README.md
@ -2,56 +2,50 @@

 [![Docker](https://img.shields.io/badge/docker-ready-brightgreen.svg)](https://www.docker.com/)

-> Gitea Runner Docker 部署模板，附带可直接复用的 Actions workflow 示例。
+> 🚀 Gitea Runner Docker 部署模板 + Actions Workflow 示例 + 文档规范

-## 📖 这个仓库提供什么
+## 📖 项目简介

- `docker-runner/presets/`：可直接部署的 runner 预设
- `docker-runner/common/`：安装、注册、升级、管理脚本
- `.gitea/workflows/`：可复制的 workflow 示例
- `.gitea/ci/bootstrap_workspace.sh`：workflow 工作区自举脚本
+这是一个完整的 Gitea Runner 模板项目，提供：

-## ⚙️ 当前默认行为
+- 🐳 **Docker 部署方案**：开箱即用的 Runner 容器化部署
+- 📝 **Workflow 示例**：自动化 CHANGELOG、Release 和统计徽章工作流
+- 📚 **文档规范**：统一的部署说明与工作流说明
+- 🔧 **配置指南**：预设配置、注册流程和运行方式说明

- 新注册的 runner 默认 `capacity=4`
- 大仓库会缓存到 `/data/git-mirrors/<owner>/<repo>.git`
- 每个 workflow job 使用独立临时目录 `/home/workspace/jobs/<owner>/<repo>/<job-identity>/repo`
- job 结束后自动清理临时工作目录，mirror 缓存保留在 `runner-data/`
- 每个 preset 通过 `.env.example` 提供实例配置模板，部署时复制为 `.env`
+## 📂 文档导航

-## 🚀 快速开始
+### 🚀 Runner

-以标准 Ubuntu 22.04 预设为例：
+#### [DEPLOYMENT.md](./DEPLOYMENT.md)

-```bash
-cd docker-runner/presets/standard-ubuntu-22
-cp .env.example .env
-docker compose build
-docker compose up -d
-docker compose exec gitea-runner /data/setup.sh
-docker compose exec gitea-runner /data/register.sh
-```
+**Gitea Runner Docker 部署完整教程**

-开始前至少需要在 `.env` 中填好 `GITEA_TOKEN`，必要时调整 `GITEA_INSTANCE`。
+包含内容：

-完整部署步骤、Buildx 版本选择、升级和故障排查见 [DEPLOYMENT.md](./DEPLOYMENT.md)。
+- 📦 标准版 vs Buildx 多架构版选择
+- 📝 Dockerfile 和 docker-compose.yml 配置
+- 🔧 安装、注册、管理脚本详解
+- ⚙️ 完整的部署流程
+- ❓ 常见问题和故障排除

-## 📂 你要找什么
+👉 **完整的 Runner 部署教程，从零开始搭建**

- 部署或运维 runner：看 [DEPLOYMENT.md](./DEPLOYMENT.md)
- 使用或定制 workflow：看 [WORKFLOW.md](./WORKFLOW.md)
- 查看当前示例 workflow：直接看 `.gitea/workflows/`
+---

-## 🗂️ 仓库结构
+### 📋 [WORKFLOW.md](./WORKFLOW.md)

-```txt
-.
-├── .gitea/
-│   ├── ci/bootstrap_workspace.sh
-│   └── workflows/
-├── docker-runner/
-│   ├── common/
-│   └── presets/
-├── DEPLOYMENT.md
-└── WORKFLOW.md
-```
+**Gitea Actions 自动化工作流示例**
+
+包含内容：
+
+- 💡 工作流配置说明
+- 🔧 如何使用和定制
+- 🔄 案例：`changelog_and_release.yml` - 自动更新 CHANGELOG 和自动创建 Release
+- 📊 案例：`update_stats_badge.yaml` - 自动生成代码统计徽章
+
+👉 **实用的 Actions 工作流，可直接复制使用**
+
+---
+
+具体部署步骤、预设选择、注册流程、升级方式和故障排查请查看 [DEPLOYMENT.md](./DEPLOYMENT.md)。
--- a/WORKFLOW.md
+++ b/WORKFLOW.md
@ -2,7 +2,7 @@

 本目录包含 Gitea Actions 的自动化工作流示例，展示如何使用 Gitea Actions 实现 CI/CD 自动化。

- 先看仓库总览和 runner 默认行为：回到 [README.md](./README.md)
+- 先看仓库总览：回到 [README.md](./README.md)
 - 需要部署或维护 runner：参考 [DEPLOYMENT.md](./DEPLOYMENT.md)

 ---
@ -18,6 +18,18 @@

 ---

+## 🧱 运行模型
+
+本模板中的 workflow 采用“Git bare 镜像 + 工作副本”的方案：
+
+- Git bare 镜像作为共享仓库缓存，负责复用仓库对象，避免大仓库在每次运行时都重新完整拉取
+- 每个 job 都在自己的独立工作副本中执行，避免并发任务之间互相污染工作目录
+- 任务结束后会清理独立工作副本，只保留共享缓存用于后续加速
+
+这个设计的目标是同时兼顾大仓库场景下的同步效率和多 job 并发执行时的隔离性。
+
+---
+
 ## 🎯 功能列表

 ### ✅ 已实现
--- a/tests/template_defaults_test.sh
+++ b/tests/template_defaults_test.sh
@ -55,6 +55,19 @@ test_workflow_docs_and_links_use_actual_paths() {
    ! rg -q '/\\.github/workflows/' "${release_workflow}" || fail "release workflow should not link to .github/workflows"
 }

+test_workflow_doc_describes_workspace_architecture() {
+    local file
+
+    file="${REPO_ROOT}/WORKFLOW.md"
+
+    grep -q 'Git bare 镜像 + 工作副本' "${file}" || fail "WORKFLOW.md should explicitly describe the bare mirror plus worktree-style model"
+    grep -q '共享仓库缓存' "${file}" || fail "WORKFLOW.md should describe the shared repository cache model"
+    grep -q '独立工作副本' "${file}" || fail "WORKFLOW.md should describe isolated per-job work copies"
+    grep -q '任务结束后' "${file}" || fail "WORKFLOW.md should mention cleanup after workflow completion"
+    ! rg -q 'bootstrap_workspace\.sh' "${file}" || fail "WORKFLOW.md should describe architecture rather than helper implementation"
+    ! rg -q '/data/git-mirrors|/home/workspace/jobs' "${file}" || fail "WORKFLOW.md should avoid implementation-specific workspace paths"
+}
+
 test_presets_do_not_mount_check_crlf_helper() {
    ! rg -q 'check_crlf\.sh:/data/check_crlf\.sh:ro' "${REPO_ROOT}/docker-runner/presets" || fail "preset compose files should not mount check_crlf helper into containers"
 }
@ -70,15 +83,29 @@ test_runner_data_is_gitignored() {
    done
 }

-test_readme_is_navigation_focused() {
+test_readme_has_project_intro_and_navigation() {
    local file

    file="${REPO_ROOT}/README.md"

-    grep -q '^## 🚀 快速开始$' "${file}" || fail "README.md should provide a quick start section"
+    grep -q '^## 📖 项目简介$' "${file}" || fail "README.md should provide a project intro section"
+    grep -q '^## 📂 文档导航$' "${file}" || fail "README.md should provide a document navigation section"
    grep -q '\[DEPLOYMENT.md\](\./DEPLOYMENT.md)' "${file}" || fail "README.md should link to DEPLOYMENT.md"
    grep -q '\[WORKFLOW.md\](\./WORKFLOW.md)' "${file}" || fail "README.md should link to WORKFLOW.md"
-    grep -q 'cp \.env\.example \.env' "${file}" || fail "README.md quick start should mention copying .env.example"
+    grep -q '具体部署步骤.*\[DEPLOYMENT.md\](\./DEPLOYMENT.md)' "${file}" || fail "README.md should delegate deployment details to DEPLOYMENT.md"
+    ! rg -q '^## 🚀 快速提示$' "${file}" || fail "README.md should not carry concrete deployment tip sections"
+    ! rg -q '^## ⚙️ 当前默认行为$' "${file}" || fail "README.md should not carry default behavior details"
+}
+
+test_deployment_doc_stays_runner_focused() {
+    local file
+
+    file="${REPO_ROOT}/DEPLOYMENT.md"
+
+    ! rg -q '^## ⚙️ 默认行为$' "${file}" || fail "DEPLOYMENT.md should not carry generic default behavior sections"
+    ! rg -q '/data/git-mirrors/<owner>/<repo>\.git' "${file}" || fail "DEPLOYMENT.md should not document workflow mirror paths"
+    ! rg -q '/home/workspace/jobs/' "${file}" || fail "DEPLOYMENT.md should not document workflow temp workspace paths"
+    ! rg -q 'bootstrap_workspace\.sh' "${file}" || fail "DEPLOYMENT.md should stay focused on runner deployment, not workflow helpers"
 }

 test_presets_define_expected_hostname() {
@ -104,9 +131,11 @@ test_preset_compose_uses_env_for_instance
 test_workflows_do_not_hardcode_company_server
 test_stats_workflow_uses_workflow_secret_consistently
 test_workflow_docs_and_links_use_actual_paths
+test_workflow_doc_describes_workspace_architecture
 test_presets_do_not_mount_check_crlf_helper
 test_runner_data_is_gitignored
-test_readme_is_navigation_focused
+test_readme_has_project_intro_and_navigation
+test_deployment_doc_stays_runner_focused
 test_presets_define_expected_hostname
 test_preset_env_examples_exist

--- a/tests/workspace_helper_test.sh
+++ b/tests/workspace_helper_test.sh
@ -164,13 +164,6 @@ test_presets_do_not_mount_workspace_helper() {
    fi
 }

-test_docs_mention_git_mirrors() {
-    if ! grep -q "/data/git-mirrors" "${REPO_ROOT}/DEPLOYMENT.md"; then
-        echo "FAIL: deployment docs should describe persistent git mirrors" >&2
-        exit 1
-    fi
-}
-
 test_repo_path_layout
 test_job_identity_prefers_run_metadata
 test_sanitize_job_name
@ -181,6 +174,5 @@ test_register_default_capacity_is_four
 test_changelog_workflow_uses_workspace_helper
 test_stats_workflow_uses_workspace_helper
 test_presets_do_not_mount_workspace_helper
-test_docs_mention_git_mirrors

 echo "workspace_helper_test.sh: PASS"