From 3686f1d03ff4980f77a04d295d731a1051196375 Mon Sep 17 00:00:00 2001
From: windychen <windychen00n@gmail.com>
Date: Thu, 6 Aug 2026 11:25:57 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20runner=20=E8=87=AA?=
 =?UTF-8?q?=E4=B8=BB=E7=BB=B4=E6=8A=A4=20docker-compose=20=E9=85=8D?=
 =?UTF-8?q?=E7=BD=AE=E6=8C=87=E5=8D=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .gitea/RUNNER-MAINTENANCE.md | 62 ++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 .gitea/RUNNER-MAINTENANCE.md

diff --git a/.gitea/RUNNER-MAINTENANCE.md b/.gitea/RUNNER-MAINTENANCE.md
new file mode 100644
index 0000000..78cccec
--- /dev/null
+++ b/.gitea/RUNNER-MAINTENANCE.md
@@ -0,0 +1,62 @@
+# Gitea Runner 自主维护配置指南
+
+## 当前状态
+- Runner 名称: gitea-runner (online, label: docker)
+- 维护 workflow: `.gitea/workflows/runner-maintenance.yaml` (每 6 小时 + 手动触发)
+
+## 宿主机 docker-compose 推荐配置
+
+在 fnOS 上找到 gitea-runner 的 compose 文件，确保包含以下配置：
+
+```yaml
+services:
+  gitea:
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/api/healthz"]
+      interval: 10s
+      retries: 3
+      start_period: 30s
+      timeout: 10s
+
+  gitea-runner:
+    image: gitea/act_runner:latest
+    container_name: gitea-runner
+    restart: unless-stopped
+    depends_on:
+      gitea:
+        condition: service_healthy
+        restart: true
+    volumes:
+      - ./runner-data:/data
+      - /var/run/docker.sock:/var/run/docker.sock
+    environment:
+      - GITEA_INSTANCE_URL=https://gitea.windychen00n.work
+      - GITEA_RUNNER_JOB_CONTAINER_NETWORK=<gitea所在docker网络名>
+      # 首次注册时需要，之后可删除
+      # - GITEA_RUNNER_REGISTRATION_TOKEN=<token>
+    networks:
+      - <gitea所在docker网络名>
+
+networks:
+  <gitea所在docker网络名>:
+    external: true
+```
+
+## 查找 docker 网络名
+
+在 fnOS SSH 执行：
+```bash
+docker inspect gitea --format "{{range $k,$v := .NetworkSettings.Networks}}{{$k}}{{end}}"
+docker inspect gitea-runner --format "{{range $k,$v := .NetworkSettings.Networks}}{{$k}}{{end}}"
+```
+
+将 `GITEA_RUNNER_JOB_CONTAINER_NETWORK` 设为 gitea 容器所在的网络名，
+这样 CI job 容器才能通过 `http://gitea:3000` 和 `http://verdaccio:4873` 访问内网服务。
+
+## 应用后验证
+
+```bash
+docker compose up -d gitea-runner
+```
+
+然后在 Gitea 页面手动触发 "Runner Self-Maintenance" workflow，应全部通过。