docs: update docs

Author: soulteary

README.md

@@ -1,47 +1,61 @@
-# Runner Fleet - GitHub Actions Runner 管理服务
+# Runner Fleet - GitHub Actions Runner Manager
 
-基于 Golang Echo 的 HTTP 管理界面，在一台机器上查看和管理多个 GitHub Actions 自托管 Runner。使用 YAML 配置，无需数据库。
+HTTP management UI built with Golang Echo to view and manage multiple self-hosted GitHub Actions Runners on one machine. YAML-based config, no database required.
 
-MIT 许可证，见 [LICENSE](LICENSE)。CI/镜像/Release 见 [.github/workflows](.github/workflows)。
+## Highlights
 
-## 亮点
+- **Zero database**: YAML-only config, no external deps; config is your backup and easy to version.
+- **Web one-stop**: Add, register, start/stop, edit, and view status in the UI—no SSH or manual `config.sh`.
+- **Auto install & register**: In "Quick Add" enter a token to auto-download the runner, register, and start; paste `./config.sh --url ... --token ...` from GitHub to parse and fill the form.
+- **Container-first**: Docker / docker-compose out of the box; DinD and host-socket for in-job Docker; optional **container mode** (one runner per container) with Manager controlling lifecycle and status.
+- **Self-heal & troubleshoot**: ~15s after start, registered but stopped runners are started; periodic check every 5 minutes; in container mode, `status=unknown` shows a structured probe (error type, check/fix commands) for copy-paste troubleshooting or start/stop self-heal.
+- **Observable**: Registration result is written and shown in the UI; optional PAT (`.github_check_token`) to periodically verify runners appear in GitHub's list, synced to the UI.
 
-- **零数据库**：仅用 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 列表显示，结果与界面同步。
+## Features
 
-## 功能
+- **View**: List all runners, status (installed/unregistered/missing dir), running or not; view full config per runner.
+- **Edit**: Change subpath, target type, target, labels (name is read-only).
+- **Quick Add**: Name + target (org/repo) + optional token; one-click add and optional auto-register.
+- **Delete**: Remove from config (does not delete disk).
+- **Start/Stop**: Start or stop registered runners.
+- **Container mode** (optional): One runner per container; Manager starts/stops via Docker; runner image tag uses `-runner` suffix.
 
-- **查看**：列表展示所有 Runner，状态（已安装/未注册/目录缺失）、是否运行中；支持查看单个 Runner 完整配置
-- **编辑**：修改子路径、目标类型、目标、标签（名称不可改）
-- **快速添加**：名称 + 目标（组织/仓库）+ 可选 Token，一键添加并可自动注册
-- **删除**：从配置中移除（不删磁盘目录）
-- **启停**：对已注册 Runner 启动/停止
-- **容器模式**（可选）：每个 Runner 独立容器，Manager 通过 C/S 启停；Runner 镜像 tag 带 `-runner` 后缀
-
-## 快速开始
+## Quick start
 
 ```bash
 cp config.yaml.example config.yaml
-# 编辑 config.yaml：runners.base_path 改为 /app/runners
-# 宿主机：mkdir -p runners && chown 1001:1001 config.yaml runners
+# Edit config.yaml: set runners.base_path to /app/runners
+# On host: mkdir -p runners && chown 1001:1001 config.yaml runners
 
 docker network create runner-net 2>/dev/null || true
 docker compose up -d
 ```
 
-浏览器打开 http://localhost:8080。更多方式（docker run、DinD、容器模式）见 [使用指南](docs/guide.md)。健康检查：`GET /health`；版本：`GET /version`。
+Open http://localhost:8080. For more options (docker run, DinD, container mode) see the [User Guide](docs/guide.md). Health: `GET /health`; version: `GET /version`.
+
+## Use cases
+
+- **Personal / team**: One machine as self-hosted runners for multiple repos or orgs; manage via Web UI, no need to remember CLI.
+- **Internal CI**: Deploy on internal network; use DinD (isolated) or host-socket (shared with host) when jobs need Docker; runners recover after Manager or DinD restart.
+- **Isolation & traceability**: Container mode gives one container per runner with clear boundaries; combine with registration result and GitHub visibility check to verify runners.
+
+## Documentation
+
+- **[User Guide](docs/guide.md)** — Deployment (Docker/docker-compose), config, adding runners, security & troubleshooting
+- **[Development & Build](docs/development.md)** — Go build, local debug, HTTP API, Makefile
+
+Documentation in other languages (each contains User Guide and Development & Build):
 
-## 适用场景
+| Language   | Docs |
+|------------|------|
+| 中文       | [docs/zh/](docs/zh/) |
+| Français   | [docs/fr/](docs/fr/) |
+| Deutsch    | [docs/de/](docs/de/) |
+| 한국어      | [docs/ko/](docs/ko/) |
+| 日本語     | [docs/ja/](docs/ja/) |
 
-- **个人 / 团队**：一台机器快速配置为多个 repo 或 org 提供自托管 Runner，用 Web 界面统一管理，无需记命令。
-- **内网 CI**：在内网部署，Job 需要 Docker 时选用 DinD（隔离）或 host-socket（与宿主机共享）；Manager 或 DinD 重启后 Runner 自动恢复。
-- **需要隔离与可追溯**：容器模式下每 Runner 独立容器，资源与权限边界清晰；结合注册结果与 GitHub 显示检查，便于核对 Runner 是否生效。
+## Other
 
-## 文档
+CI / images / releases: [.github/workflows](.github/workflows).
 
-- **[使用指南](docs/guide.md)**：部署（Docker/docker-compose）、配置、添加 Runner、安全与排障
-- **[开发与构建](docs/development.md)**：Go 构建、本地调试、HTTP API、Makefile
+MIT License — see [LICENSE](LICENSE).

docs/README.md

@@ -1,6 +1,8 @@
-# 文档
+# Documentation
 
-- **[使用指南](guide.md)**：部署、配置、添加 Runner、安全与排障
-- **[开发与构建](development.md)**：构建、API、Makefile
+- **[User Guide](guide.md)** — Deployment, configuration, adding runners, security & troubleshooting
+- **[Development & Build](development.md)** — Build, API, Makefile
 
-[← 返回项目首页](../README.md)
+**Language:** English (default) | [中文](zh/) | [Français](fr/) | [Deutsch](de/) | [한국어](ko/) | [日本語](ja/)
+
+[← Back to project home](../README.md)

docs/de/README.md

@@ -0,0 +1,8 @@
+# Dokumentation
+
+- **[Benutzerhandbuch](guide.md)** — Bereitstellung, Konfiguration, Runner hinzufügen, Sicherheit und Fehlerbehebung
+- **[Entwicklung & Build](development.md)** — Build, API, Makefile
+
+**Sprache:** [English (default)](../) | [中文](../zh/) | [Français](../fr/) | Deutsch | [한국어](../ko/) | [日本語](../ja/)
+
+[← Zurück zur Projektstartseite](../../README.md)

docs/de/development.md

@@ -0,0 +1,88 @@
+# Entwicklung & Build
+
+Für Produktion Container-Bereitstellung verwenden; siehe [Benutzerhandbuch](guide.md). Dieses Dokument ist für Mitwirkende: lokaler Build und Debug.
+
+## Anforderungen
+
+- Go 1.26 (abgestimmt auf [go.mod](../../go.mod)).
+
+## Build
+
+```bash
+# runner-manager-Binary bauen
+go build -o runner-manager ./cmd/runner-manager
+
+# Mit Version (für /version und Debug)
+go build -ldflags "-X main.Version=1.0.0" -o runner-manager ./cmd/runner-manager
+
+# Nur Runner Agent bauen (Containermodus)
+go build -o runner-agent ./cmd/runner-agent
+
+# Oder Make: make build / make build-agent / make build-all
+```
+
+Templates sind im Manager-Binary eingebettet (`cmd/runner-manager/templates/`); einzelnes Binary, kein separates `templates/` nötig.
+
+## Lokal ausführen und debuggen
+
+```bash
+cp config.yaml.example config.yaml
+go run ./cmd/runner-manager
+# Oder make run (build dann run); eigene Config: ./runner-manager -config /path/to/config.yaml
+```
+
+Lauscht auf `:8080`, http://localhost:8080. Basic Auth zum Debuggen: `BASIC_AUTH_PASSWORD=secret go run ./cmd/runner-manager`; siehe [Benutzerhandbuch – Sicherheit](guide.md#4-sicherheit-und-validierung).
+
+## CLI-Flags
+
+- `-config <path>`: Pfad zur Konfigurationsdatei.
+- `-version`: Version ausgeben und beenden (beim Build mit `-ldflags "-X main.Version=..."` injizieren).
+
+## HTTP-API
+
+Mit Basic Auth müssen alle Anfragen außer `/health` den Header `Authorization: Basic <base64(user:password)>` enthalten.
+
+| Pfad | Methode | Beschreibung |
+|------|---------|--------------|
+| `/health` | GET | Gibt `{"status":"ok"}` zurück; für Ingress/K8s-Probes; immer unauthentifiziert. |
+| `/version` | GET | Gibt `{"version":"..."}` zurück. |
+| `/api/runners` | GET | Runner-Liste. Im Containermodus bei Probe-Fehler `status=unknown` mit strukturiertem `probe` (`error/type/suggestion/check_command/fix_command`). |
+| `/api/runners/:name` | GET | Einzelner Runner. Gleiches `probe` bei Probe-Fehler im Containermodus. |
+| `/api/runners/:name/start` | POST | Runner starten. Bei Probe-Fehler startet trotzdem, gibt strukturiertes `probe` in der Antwort zurück. |
+| `/api/runners/:name/stop` | POST | Runner stoppen. Bei Probe-Fehler stoppt trotzdem, gibt strukturiertes `probe` in der Antwort zurück. |
+
+### Breaking Change (Upgrade-Hinweis)
+
+Alte flache Felder `probe_*` sind entfernt; Objekt `probe` verwenden: `probe.error`, `probe.type`, `probe.suggestion`, `probe.check_command`, `probe.fix_command`. Werte von `probe.type`: `docker-access`, `agent-http`, `agent-connect`, `unknown`. Die Web-UI kann bei `status=unknown` weiter „Start/Stop“ zur Selbstheilung nutzen.
+
+Beispiel (Probe-Fehler):
+
+```json
+{
+  "name": "runner-a",
+  "status": "unknown",
+  "probe": {
+    "error": "agent returned 502: bad gateway",
+    "type": "agent-http",
+    "suggestion": "Check runner container logs and Agent + /runner process state",
+    "check_command": "docker ps -a | rg \"github-runner-\" && docker logs --tail=200 <runner_container_name>",
+    "fix_command": "docker restart <runner_container_name>"
+  }
+}
+```
+
+## Makefile-Ziele
+
+- `make help`: Alle Ziele anzeigen.
+- `make build`: Manager bauen (mit Version-ldflags).
+- `make build-agent`: Runner Agent bauen (Containermodus).
+- `make build-all`: Manager und Agent bauen.
+- `make test`: Tests ausführen.
+- `make run`: Manager bauen und ausführen.
+- `make docker-build` / `make docker-run` / `make docker-stop`: Manager-Image bauen und ausführen; siehe [Benutzerhandbuch](guide.md).
+- `make docker-build-runner`: Runner-Image für Containermodus bauen (`Dockerfile.runner`, Standard-Tag in `RUNNER_IMAGE`).
+- `make clean`: Gebaute Binaries entfernen (runner-manager, runner-agent).
+
+Containermodus nutzt Agent aus `cmd/runner-agent` und Runner-Image aus `Dockerfile.runner`.
+
+[← Zurück zur Dokumentation](README.md)

docs/de/guide.md

@@ -0,0 +1,155 @@
+# Benutzerhandbuch
+
+Bereitstellung, Konfiguration, Hinzufügen von Runnern und Sicherheit werden hier behandelt. Für Build und API für Mitwirkende siehe [Entwicklung & Build](development.md).
+
+---
+
+## 1. Bereitstellung (Docker)
+
+- Das Image basiert auf **Ubuntu** mit .NET Core 6.0-Abhängigkeiten; läuft unter **UID 1001** – gemountete Host-Verzeichnisse müssen für diesen Benutzer schreibbar sein (z. B. `chown 1001:1001 config.yaml runners`).
+- Etwa 15 Sekunden nach dem Start werden registrierte, aber gestoppte Runner automatisch gestartet; periodische Prüfung alle 5 Minuten.
+
+### Veröffentlichtes Image verwenden (empfohlen)
+
+```bash
+docker pull ghcr.io/soulteary/runner-fleet:main
+```
+
+### docker-compose Schnellstart
+
+Im Repo-Root liegt `docker-compose.yml`. DinD nur aktivieren, wenn Sie den Containermodus nutzen und Jobs Docker mit `job_docker_backend: dind` benötigen.
+
+```bash
+cp config.yaml.example config.yaml
+# config.yaml bearbeiten: runners.base_path auf /app/runners setzen
+
+chown 1001:1001 config.yaml
+mkdir -p runners && chown 1001:1001 runners
+
+docker network create runner-net 2>/dev/null || true
+docker compose up -d
+# Bei job_docker_backend: dind: docker compose --profile dind up -d
+```
+
+UI: http://localhost:8080. Auth-Details in [4. Sicherheit und Validierung](#4-sicherheit-und-validierung).
+
+### Container starten (volle Parameter)
+
+`config.yaml` und `runners` müssen gemountet werden; der Port muss mit `server.port` in der Config übereinstimmen (Standard 8080).
+
+```bash
+docker run -d --name runner-manager \
+  -p 8080:8080 \
+  -v $(pwd)/config.yaml:/app/config.yaml \
+  -v $(pwd)/runners:/app/runners \
+  ghcr.io/soulteary/runner-fleet:main
+```
+
+Host-Verzeichnisse müssen für UID 1001 schreibbar sein. Basic Auth: `-e BASIC_AUTH_PASSWORD=password`, `-e BASIC_AUTH_USER=admin`. Für Docker in Jobs `-v /var/run/docker.sock:/var/run/docker.sock` hinzufügen oder DinD nutzen (siehe Repo `docker-compose.yml`, `--profile dind`). Das Image enthält die Docker-CLI; gängige Actions funktionieren mit DinD.
+
+### Automatische Installation und Registrierung
+
+In der UI „Quick Add Runner“ Name, Ziel, Token eingeben und absenden; zuerst läuft das Installationsskript, dann Registrierung und Start. Bei Fehlern:
+
+```bash
+docker exec runner-manager /app/scripts/install-runner.sh <name> [version]
+```
+
+Oder auf dem Host [actions-runner](https://github.com/actions/runner/releases) unter `runners/<name>/` entpacken, dann in der UI absenden oder `./config.sh` manuell ausführen.
+
+### Containermodus (ein Runner pro Container)
+
+Jeder Runner läuft in seinem eigenen Container; der Manager startet/stoppt über Host-Docker und holt den Status per HTTP vom Agent im Container.
+
+In **config.yaml** aktivieren (siehe `config.yaml.example`):
+
+```yaml
+runners:
+  base_path: /app/runners
+  container_mode: true
+  container_image: ghcr.io/soulteary/runner-fleet-runner:main
+  container_network: runner-net
+  agent_port: 8081
+  job_docker_backend: dind   # dind | host-socket | none
+  dind_host: runner-dind
+  volume_host_path: /abs/path/on/host/to/runners
+```
+
+Runner-Image: gleicher Name wie Manager mit Tag `-runner`, oder lokal bauen: `docker build -f Dockerfile.runner -t ghcr.io/soulteary/runner-fleet-runner:main .`. Der Manager muss Host-Docker verwenden (Mount von `docker.sock`), nicht DinD über `DOCKER_HOST`; in Compose `group_add` für Host-Docker-GID oder `user: "0:0"` verwenden. Runner-Namen werden zu Containernamen normalisiert; Duplikate nach dem Mapping kollidieren.
+
+### Fehlerbehebung
+
+- **Runner startet nach compose down nicht**: Einmal `docker network create runner-net` ausführen. Bei anhaltendem Fehler in der UI „Start“ zum Neuerstellen nutzen oder `docker rm -f github-runner-<name>` dann „Start“.
+- **Lauf als root**: Gemountete Verzeichnisse müssen für den Prozessbenutzer schreibbar sein; für root `RUNNER_ALLOW_RUNASROOT=1` setzen.
+- **Altes Runner-Image**: `docker rm -f github-runner-<name>`, dann in der UI „Start“ zum Neuerstellen.
+- **status=unknown**: Probe im Detail-Popup prüfen; „Start/Stop“ zur Selbstheilung versuchen.
+
+### Images lokal bauen
+
+```bash
+docker build -t runner-manager .
+docker build -f Dockerfile.runner -t ghcr.io/soulteary/runner-fleet-runner:main .
+```
+
+Make: `make docker-build`, `make docker-run`, `make docker-stop`.
+
+---
+
+## 2. Konfiguration
+
+```bash
+cp config.yaml.example config.yaml
+```
+
+| Feld | Beschreibung | Standard |
+|------|--------------|----------|
+| `server.port` | HTTP-Server-Port | `8080` |
+| `server.addr` | Bind-Adresse; leer = alle Interfaces | leer |
+| `runners.base_path` | Wurzelpfad der Runner-Installationsverzeichnisse; **in Container auf `/app/runners` setzen** | `./runners` |
+| `runners.items` | Vordefinierte Runner-Liste | Kann auch über die Web-UI hinzugefügt werden |
+| `runners.container_mode` | Containermodus aktivieren | `false` |
+| `runners.container_image` | Runner-Image im Containermodus (Tag -runner) | `ghcr.io/soulteary/runner-fleet-runner:main` |
+| `runners.container_network` | Netzwerk für Runner im Containermodus | `runner-net` |
+| `runners.agent_port` | Agent-Port im Container | `8081` |
+| `runners.job_docker_backend` | Docker in Jobs: `dind` / `host-socket` / `none` | `dind` |
+| `runners.dind_host` | DinD-Hostname bei `job_docker_backend=dind` | `runner-dind` |
+| `runners.volume_host_path` | Absoluter Host-Pfad zu runners im Containermodus (erforderlich) | leer |
+
+**Validierung**: Keine doppelten Namen; Containermodus prüft auf Container-Namenskonflikte. `job_docker_backend` erlaubt nur `dind`/`host-socket`/`none`; im Containermodus mit Container-`base_path` ist `volume_host_path` erforderlich. Fehlendes `job_docker_backend` bedeutet `dind`; nach Backend-Änderung Runner in der UI neu starten.
+
+Beispiel:
+
+```yaml
+server:
+  port: 8080
+  addr: 0.0.0.0
+runners:
+  base_path: /app/runners
+  items: []
+```
+
+---
+
+## 3. Runner hinzufügen
+
+**Token besorgen**: Repo/Org → Settings → Actions → Runners → New self-hosted runner, Token kopieren (ca. 1 Stunde gültig). Jeder Runner braucht einen neuen Token.
+
+**Im Service hinzufügen**: In der UI „Quick Add Runner“ Name (eindeutig), Zieltyp (org/repo), Ziel, Token (optional; wenn gesetzt, kann Absenden automatisch registrieren und starten) eingeben. Sie können `./config.sh --url ... --token ...` von GitHub in „Parse from GitHub command“ einfügen und „Parse & fill“ klicken. Auto-Registrierung nur für GitHub.com; GitHub Enterprise erfordert manuelles `config.sh` im Runner-Verzeichnis.
+
+**Wenn Runner nicht installiert**: Von [GitHub Actions Runner](https://github.com/actions/runner/releases) herunterladen, unter `runners/<name>/` entpacken, dann Token in der UI eingeben oder `./config.sh` dort ausführen. Bei Container-Deploy löst das Absenden eines Tokens in der UI zuerst Installation, dann Registrierung aus; Containermodus erfordert zuerst Runner-Image und `volume_host_path` (siehe Containermodus oben).
+
+**Registrierungsergebnis**: Wird in `.registration_result.json` im Runner-Verzeichnis geschrieben. **GitHub-Sichtbarkeitsprüfung** (optional): `.github_check_token` (PAT; Org braucht `admin:org`, Repo braucht `repo`) ins Runner-Verzeichnis legen; wird ca. alle 5 Minuten geprüft, Ergebnis in `.github_status.json`.
+
+Mehrere Runner pro Maschine: getrennte Unterverzeichnisse verwenden.
+
+---
+
+## 4. Sicherheit und Validierung
+
+**Auth**: Standardmäßig keine Anmeldung; nur im internen Netz oder auf localhost verwenden. Umgebungsvariable `BASIC_AUTH_PASSWORD` setzen für Basic Auth; `BASIC_AUTH_USER` optional (Standard `admin`). Alle Routen außer `GET /health` erfordern Auth; keine Secrets committen – `.env` verwenden. Im Container: `-e BASIC_AUTH_PASSWORD=...` oder compose `env_file`.
+
+**Pfade und Eindeutigkeit**: name/path dürfen nicht `..`, `/`, `\` enthalten; Verzeichnisse müssen unter `runners.base_path` liegen. Keine doppelten Namen; Name beim Bearbeiten schreibgeschützt. Im Containermodus werden Namen zu Containernamen normalisiert; Duplikate nach Mapping führen zu Fehler.
+
+**Sensible Dateien**: config.yaml und .env stehen in `.gitignore`. Für `.github_check_token` jedes Runners `chmod 600` verwenden; `**/.github_check_token` zu `.gitignore` hinzufügen, wenn unter Versionskontrolle.
+
+[← Zurück zur Projektstartseite](../../README.md)