From 61e512c2aef133cc5aa2263acca1cab006296317 Mon Sep 17 00:00:00 2001
From: csh <caoshenghui@tinysoft.com.cn>
Date: Fri, 22 May 2026 10:20:33 +0800
Subject: [PATCH] =?UTF-8?q?:memo:=20=E6=94=B6=E7=B4=A7=E6=96=87=E6=A1=A3?=
 =?UTF-8?q?=E5=85=A5=E5=8F=A3=E4=B8=8E=E5=AF=BC=E8=88=AA=E5=B1=82=E6=AC=A1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 DEPLOYMENT.md                   |  3 ++
 README.md                       | 71 +++++++++++++++++----------------
 WORKFLOW.md                     |  3 ++
 tests/template_defaults_test.sh | 12 ++++++
 4 files changed, 54 insertions(+), 35 deletions(-)

diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
index 1309770..b650ad7 100644
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -19,6 +19,9 @@ Gitea Runner 是 Gitea 的 CI/CD 执行器,类似于 GitLab Runner 或 GitHub Ac
 
 本项目提供了标准版和 Buildx 版两种部署方案,通过预设配置快速部署。
 
+- 只想先看仓库总览和最快上手路径：回到 [README.md](./README.md)
+- 需要查看 workflow 示例和 secret 约定：参考 [WORKFLOW.md](./WORKFLOW.md)
+
 ---
 
 ## 📂 目录结构
diff --git a/README.md b/README.md
index 8243413..1b7bb1a 100644
--- a/README.md
+++ b/README.md
@@ -2,55 +2,56 @@
 
 [![Docker](https://img.shields.io/badge/docker-ready-brightgreen.svg)](https://www.docker.com/)
 
-> 🚀 Gitea Runner Docker 部署模板 + Actions Workflow 示例 + 文档规范
+> Gitea Runner Docker 部署模板，附带可直接复用的 Actions workflow 示例。
 
-## 📖 项目简介
+## 📖 这个仓库提供什么
 
-这是一个完整的 Gitea Runner 模板项目，提供：
-
-- 🐳 **Docker 部署方案**：开箱即用的 Runner 容器化部署
-- 📝 **Workflow 示例**：自动化 CHANGELOG 和 Release 工作流
-- 📚 **文档规范**：统一的文档格式和版本管理规范
-- 🔧 **配置指南**：详细的配置说明和最佳实践
+- `docker-runner/presets/`：可直接部署的 runner 预设
+- `docker-runner/common/`：安装、注册、升级、管理脚本
+- `.gitea/workflows/`：可复制的 workflow 示例
+- `.gitea/ci/bootstrap_workspace.sh`：workflow 工作区自举脚本
 
 ## ⚙️ 当前默认行为
 
 - 新注册的 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` 即可
+- 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](./WORKFLOW.md)
-
-**Gitea Actions 自动化工作流示例**
-
-包含内容：
-
-- 💡 工作流配置说明
-- 🔧 如何使用和定制
-- 🔄 案例：`changelog_and_release.yml` - 自动更新 CHANGELOG 和自动创建 Release
-
-👉 **实用的 Actions 工作流，可直接复制使用**
-
----
+```txt
+.
+├── .gitea/
+│   ├── ci/bootstrap_workspace.sh
+│   └── workflows/
+├── docker-runner/
+│   ├── common/
+│   └── presets/
+├── DEPLOYMENT.md
+└── WORKFLOW.md
+```
diff --git a/WORKFLOW.md b/WORKFLOW.md
index 1688621..ab0cded 100644
--- a/WORKFLOW.md
+++ b/WORKFLOW.md
@@ -2,6 +2,9 @@
 
 本目录包含 Gitea Actions 的自动化工作流示例，展示如何使用 Gitea Actions 实现 CI/CD 自动化。
 
+- 先看仓库总览和 runner 默认行为：回到 [README.md](./README.md)
+- 需要部署或维护 runner：参考 [DEPLOYMENT.md](./DEPLOYMENT.md)
+
 ---
 
 ## 📂 文件结构
diff --git a/tests/template_defaults_test.sh b/tests/template_defaults_test.sh
index 2772eee..c68f038 100644
--- a/tests/template_defaults_test.sh
+++ b/tests/template_defaults_test.sh
@@ -70,6 +70,17 @@ test_runner_data_is_gitignored() {
     done
 }
 
+test_readme_is_navigation_focused() {
+    local file
+
+    file="${REPO_ROOT}/README.md"
+
+    grep -q '^## 🚀 快速开始$' "${file}" || fail "README.md should provide a quick start 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"
+}
+
 test_preset_env_examples_exist() {
     local file
 
@@ -89,6 +100,7 @@ test_stats_workflow_uses_workflow_secret_consistently
 test_workflow_docs_and_links_use_actual_paths
 test_presets_do_not_mount_check_crlf_helper
 test_runner_data_is_gitignored
+test_readme_is_navigation_focused
 test_preset_env_examples_exist
 
 echo "template_defaults_test.sh: PASS"