📝 收紧文档入口与导航层次

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)
+
 ---
 
 ## 📂 目录结构

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/presets/`：可直接部署的 runner 预设
-
+- `docker-runner/common/`：安装、注册、升级、管理脚本
-- 🐳 **Docker 部署方案**：开箱即用的 Runner 容器化部署
+- `.gitea/workflows/`：可复制的 workflow 示例
-- 📝 **Workflow 示例**：自动化 CHANGELOG 和 Release 工作流
+- `.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/`
+- job 结束后自动清理临时工作目录，mirror 缓存保留在 `runner-data/`
-- 每个 preset 通过 `.env.example` 提供公司默认实例值，部署时复制为 `.env` 即可
+- 每个 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)
+```txt
-
+.
-**Gitea Actions 自动化工作流示例**
+├── .gitea/
-
+│   ├── ci/bootstrap_workspace.sh
-包含内容：
+│   └── workflows/
-
+├── docker-runner/
-- 💡 工作流配置说明
+│   ├── common/
-- 🔧 如何使用和定制
+│   └── presets/
-- 🔄 案例：`changelog_and_release.yml` - 自动更新 CHANGELOG 和自动创建 Release
+├── DEPLOYMENT.md
-
+└── WORKFLOW.md
-👉 **实用的 Actions 工作流，可直接复制使用**
+```
-
----

WORKFLOW.md

@@ -2,6 +2,9 @@
 
 本目录包含 Gitea Actions 的自动化工作流示例，展示如何使用 Gitea Actions 实现 CI/CD 自动化。
 
+- 先看仓库总览和 runner 默认行为：回到 [README.md](./README.md)
+- 需要部署或维护 runner：参考 [DEPLOYMENT.md](./DEPLOYMENT.md)
+
 ---
 
 ## 📂 文件结构

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"