docs: update docs

Author: soulteary

.env.example

@@ -21,6 +21,6 @@
 # 容器模式：Manager 需访问宿主机 Docker（创建/启停 Runner 容器）。宿主机 docker 组 GID 与 999 不同时在此设置，例如：
 # DOCKER_GID=113
 #
-# Basic Auth（可选）：设置后管理界面与 API 需输入用户名密码访问；留空则不鉴权。GET /health 始终免鉴权。
-# BASIC_AUTH_USER=admin
-# BASIC_AUTH_PASSWORD=
+# Basic Auth（可选）：设置后管理界面与 API 需输入用户名密码访问；GET /health 始终免鉴权。
+# BASIC_AUTH_USER=admin   # 可选，默认 admin
+# BASIC_AUTH_PASSWORD=   # 设置后启用 Basic Auth，留空则不鉴权

README.md

@@ -2,8 +2,16 @@
 
 基于 Golang Echo 的 HTTP 管理界面，在一台机器上查看和管理多个 GitHub Actions 自托管 Runner。使用 YAML 配置，无需数据库。
 
-许可证：MIT，见 [LICENSE](LICENSE)。  
-CI：push 到 `main`/`master`/`develop` 时由 [CI (Manager)](.github/workflows/ci-manager.yml) 与 [CI (Runner)](.github/workflows/ci-agent.yml) 分别执行检查与构建；[Publish image (Manager)](.github/workflows/publish-image-manager.yml) / [Publish image (Runner)](.github/workflows/publish-image-agent.yml) 在 push 分支或 tag 时构建并推送对应容器镜像到 GHCR。推送 tag `v*.*.*` 时 [Release (Manager)](.github/workflows/release-manager.yml) 构建二进制与 Manager 镜像并创建 GitHub Release，[Release (Runner)](.github/workflows/release-agent.yml) 推送 Runner 镜像（tag 带 `-runner` 后缀）。
+MIT 许可证，见 [LICENSE](LICENSE)。CI/镜像/Release 见 [.github/workflows](.github/workflows)。
+
+## 亮点
+
+- **零数据库**：仅用 YAML 配置，无外部依赖，配置即备份、易版本管理。
+- **Web 一站式**：添加、注册、启停、编辑、查看状态均在界面完成，无需 SSH 或手动执行 GitHub Runner `config.sh`。
+- **自动安装与注册**：在「快速添加」中填写 Token 即可自动下载 runner、执行注册并启动；支持从 GitHub 页面复制 `./config.sh --url ... --token ...` 一键解析并填充表单。
+- **容器化优先**：Docker / docker-compose 开箱即用，支持 DinD 与 host-socket 两种 Job 内 Docker 方式；可选**容器模式**（一 Runner 一容器），由 Manager 统一启停与状态采集。
+- **自愈与排障**：服务启动约 15 秒后自动拉起已注册未运行 Runner，并每 5 分钟定时检查；容器模式下 `status=unknown` 时提供结构化 probe（错误类型、检查/修复命令），便于复制命令排障或尝试启停自愈。
+- **可观测**：注册结果写入并在界面展示；可选配置 PAT（`.github_check_token`），定时检查 Runner 是否已在 GitHub 列表显示，结果与界面同步。
 
 ## 功能
 
@@ -12,31 +20,28 @@ CI：push 到 `main`/`master`/`develop` 时由 [CI (Manager)](.github/workflows/
 - **快速添加**：名称 + 目标（组织/仓库）+ 可选 Token，一键添加并可自动注册
 - **删除**：从配置中移除（不删磁盘目录）
 - **启停**：对已注册 Runner 启动/停止
-- **容器模式**（可选）：每个 Runner 运行在独立容器中，Manager 通过 C/S 控制并获取状态；Runner 与 Manager 同镜像名，CI 推送 tag 带 `-runner` 后缀（如 `:main-runner`、`:1.0.0-runner`）
+- **容器模式**（可选）：每个 Runner 独立容器，Manager 通过 C/S 启停；Runner 镜像 tag 带 `-runner` 后缀
 
 ## 快速开始
 
 ```bash
-# 1. 复制配置（config.yaml 已在 .gitignore，需从示例复制）
 cp config.yaml.example config.yaml
+# 编辑 config.yaml：runners.base_path 改为 /app/runners
+# 宿主机：mkdir -p runners && chown 1001:1001 config.yaml runners
 
-# 2. 二选一：本地运行 或 Docker
-go run ./cmd/runner-manager # 需 Go 1.26
-# 或 Docker（需挂载 config 与 runners，详见 docs/docker.md）
-make docker-build && make docker-run
-# 或使用已发布镜像：见 docs/docker.md 中的「运行容器」与 DinD 说明
+docker network create runner-net 2>/dev/null || true
+docker compose up -d
 ```
 
-浏览器打开 http://localhost:8080。健康检查：`GET /health`；版本：`GET /version` 或 `./runner-manager -version`。
+浏览器打开 http://localhost:8080。更多方式（docker run、DinD、容器模式）见 [使用指南](docs/guide.md)。健康检查：`GET /health`；版本：`GET /version`。
 
-## 文档
+## 适用场景
 
-详细说明见 [docs/](docs/README.md)：
+- **个人 / 团队**：一台机器快速配置为多个 repo 或 org 提供自托管 Runner，用 Web 界面统一管理，无需记命令。
+- **内网 CI**：在内网部署，Job 需要 Docker 时选用 DinD（隔离）或 host-socket（与宿主机共享）；Manager 或 DinD 重启后 Runner 自动恢复。
+- **需要隔离与可追溯**：容器模式下每 Runner 独立容器，资源与权限边界清晰；结合注册结果与 GitHub 显示检查，便于核对 Runner 是否生效。
+
+## 文档
 
-| 文档 | 说明 |
-|------|------|
-| [配置说明](docs/config.md) | config.yaml 字段与示例 |
-| [Docker 部署](docs/docker.md) | 镜像构建、运行、Make 目标 |
-| [添加 Runner](docs/adding-runner.md) | Token 获取、界面添加、多 Runner 同机 |
-| [安全与校验](docs/security.md) | 鉴权、路径安全、唯一性 |
-| [开发与构建](docs/development.md) | 构建、开发、API、Makefile |
+- **[使用指南](docs/guide.md)**：部署（Docker/docker-compose）、配置、添加 Runner、安全与排障
+- **[开发与构建](docs/development.md)**：Go 构建、本地调试、HTTP API、Makefile

docs/README.md

@@ -1,15 +1,6 @@
-# 文档索引
+# 文档
 
-本目录为 Runner Fleet 的详细文档，主文档见 [README](../README.md)。
-
-> 接口变更提示：探测失败信息现仅通过结构化 `probe` 返回，历史扁平字段 `probe_*` 已移除。详见 [开发与构建](development.md) 的 HTTP API 说明与示例。
-
-| 文档 | 说明 |
-|------|------|
-| [配置说明](config.md) | `config.yaml` 各字段说明与示例 |
-| [Docker 部署](docker.md) | 镜像构建、运行、挂载与 Make 目标 |
-| [添加 Runner](adding-runner.md) | 从 GitHub 获取 Token、界面添加、多 Runner 同机部署 |
-| [安全与校验](security.md) | 鉴权、路径安全、唯一性、Token 与敏感文件 |
-| [开发与构建](development.md) | Go 构建、本地开发、API（health/version）、Makefile |
+- **[使用指南](guide.md)**：部署、配置、添加 Runner、安全与排障
+- **[开发与构建](development.md)**：构建、API、Makefile
 
 [← 返回项目首页](../README.md)

docs/adding-runner.md

@@ -1,5 +1,7 @@
 # 开发与构建
 
+生产环境请使用容器部署，见 [使用指南](guide.md)。本文档面向贡献者本地构建与调试。
+
 ## 环境要求
 
 - Go 1.26（与 [go.mod](../go.mod) 一致）。
@@ -21,28 +23,15 @@ go build -o runner-agent ./cmd/runner-agent
 
 模板已通过 `embed` 内嵌于 Manager 二进制（`cmd/runner-manager/templates/`），可执行文件可单文件分发，无需附带 `templates/` 目录。
 
-## 本地开发
+## 本地开发与调试
 
 ```bash
-# 需先有 config.yaml（可 cp config.yaml.example config.yaml）
+cp config.yaml.example config.yaml
 go run ./cmd/runner-manager
-
-# 或：先 build 再运行
-make run
-```
-
-## 运行
-
-```bash
-# 使用当前目录 config.yaml
-./runner-manager
-
-# 指定配置文件
-./runner-manager -config /path/to/config.yaml
+# 或 make run（先 build 再运行）；指定配置：./runner-manager -config /path/to/config.yaml
 ```
 
-默认监听 `:8080`，浏览器打开 http://localhost:8080 使用管理界面。
-本地需验证 Basic Auth 时，可设置环境变量后启动，例如：`BASIC_AUTH_PASSWORD=你的密码 go run ./cmd/runner-manager`（详见 [安全与校验](security.md)）。
+默认监听 `:8080`，http://localhost:8080。Basic Auth 调试：`BASIC_AUTH_PASSWORD=密码 go run ./cmd/runner-manager`，见 [使用指南 - 安全与校验](guide.md#四安全与校验)。
 
 ## 命令行参数
 
@@ -64,17 +53,7 @@ make run
 
 ### 升级注意（破坏性变更）
 
-- 探测失败相关的历史扁平字段（`probe_error`、`probe_error_type`、`probe_suggestion`、`probe_check_command`、`probe_fix_command`）已移除。
-- 调用方需统一读取 `probe` 对象：
-  - 错误文本：`probe.error`
-  - 错误类型：`probe.type`
-  - 建议与命令：`probe.suggestion`、`probe.check_command`、`probe.fix_command`
-- 若你有自定义前端、告警或脚本，请将解析逻辑从 `probe_*` 切换到 `probe.*`。
-
-WebUI 在 `status=unknown` 时会保留「启动 / 停止」手动操作入口，便于运维在探测异常时执行自愈动作。
-`probe.type` 目前可能值：`docker-access`、`agent-http`、`agent-connect`、`unknown`。
-WebUI 优先展示后端返回的 `probe` 字段（后端为建议与命令单点来源），前端仅保留兜底通用提示。
-WebUI 会将命令拆分为「检查命令（只读）」与「修复命令（有副作用）」，默认建议先执行检查命令；修复命令需要二次确认后才显示。两类命令都支持一键复制（仅复制，不执行），并带浏览器权限受限时的回退复制逻辑。
+历史扁平字段 `probe_*` 已移除，请统一使用 `probe` 对象：`probe.error`、`probe.type`、`probe.suggestion`、`probe.check_command`、`probe.fix_command`。`probe.type` 可能值：`docker-access`、`agent-http`、`agent-connect`、`unknown`。WebUI 在 `status=unknown` 时仍可「启动/停止」自愈。
 
 示例（探测失败）：
 
@@ -100,10 +79,10 @@ WebUI 会将命令拆分为「检查命令（只读）」与「修复命令（
 - `make build-all`：同时构建 Manager 与 Agent。
 - `make test`：运行测试。
 - `make run`：先 build 再运行 Manager。
-- `make docker-build` / `make docker-run` / `make docker-stop`：Manager 镜像构建与运行，见 [Docker 部署](docker.md)。
+- `make docker-build` / `make docker-run` / `make docker-stop`：Manager 镜像构建与运行，见 [使用指南](guide.md)。
 - `make docker-build-runner`：构建容器模式用的 Runner 镜像（`Dockerfile.runner`，默认 tag 见 `RUNNER_IMAGE`）。
 - `make clean`：删除生成的二进制（runner-manager、runner-agent）。
 
-容器模式下 Runner 容器内运行的是 `cmd/runner-agent` 编译出的 Agent，仅构建 Manager 时不会包含该二进制；Runner 镜像单独用 `Dockerfile.runner` 构建。
+容器模式用的 Agent 为 `cmd/runner-agent`，Runner 镜像用 `Dockerfile.runner` 单独构建。
 
-[← 返回文档索引](README.md)
+[← 返回文档](README.md)