chore: add probe

Author: soulteary

cmd/runner-manager/templates/index.html

@@ -117,6 +117,28 @@
     .modal-body .row { margin-bottom: 12px; }
     .modal-body .row label { display: block; color: var(--muted); font-size: 12px; margin-bottom: 4px; }
     .modal-body .row .val { font-family: ui-monospace, monospace; font-size: 13px; word-break: break-all; }
+    .btn-reveal-fix {
+      padding: 4px 10px;
+      font-size: 12px;
+      background: transparent;
+      color: var(--warn);
+      border: 1px solid var(--warn);
+      border-radius: 4px;
+      cursor: pointer;
+      margin-right: 8px;
+    }
+    .btn-reveal-fix:hover { opacity: 0.9; }
+    .btn-copy-cmd {
+      padding: 4px 10px;
+      font-size: 12px;
+      background: transparent;
+      color: var(--accent);
+      border: 1px solid var(--accent);
+      border-radius: 4px;
+      cursor: pointer;
+      margin-right: 8px;
+    }
+    .btn-copy-cmd:hover { opacity: 0.9; }
     .modal-body input, .modal-body select { width: 100%; padding: 8px 12px; background: var(--bg); border: 1px solid var(--border); border-radius: 6px; color: var(--text); margin-top: 4px; }
     .modal-footer { padding: 12px 20px; border-top: 1px solid var(--border); }
     .modal-footer button { margin-right: 8px; }
@@ -197,7 +219,7 @@ <h2>Runner 列表</h2>
           <td>
             <span class="badge {{.Status}}">{{.Status}}</span>
             {{if .Running}}<span class="badge running">运行中</span>{{end}}
-            {{if .ProbeError}}<br><span class="probe-err" title="{{.ProbeError}}">探测失败</span>{{end}}
+            {{if .Probe}}<br><span class="probe-err" title="{{.Probe.Error}}">探测失败{{if .Probe.Type}} ({{.Probe.Type}}){{end}}</span>{{end}}
           </td>
           {{if $.Config.Runners.ContainerMode}}<td><code>{{.JobDockerBackend}}</code></td>{{end}}
           <td>
@@ -222,6 +244,10 @@ <h2>Runner 列表</h2>
           <td>
             {{if and (eq .Status "installed") (not .Running)}}<button type="button" class="btn-start" data-name="{{.Name}}" title="启动 Runner">启动</button>{{end}}
             {{if .Running}}<button type="button" class="btn-stop" data-name="{{.Name}}" title="停止 Runner">停止</button>{{end}}
+            {{if eq .Status "unknown"}}
+            <button type="button" class="btn-start" data-name="{{.Name}}" title="状态探测失败，尝试启动 Runner">启动</button>
+            <button type="button" class="btn-stop" data-name="{{.Name}}" title="状态探测失败，尝试停止 Runner">停止</button>
+            {{end}}
             <button type="button" class="btn-view" data-name="{{.Name}}" title="查看配置">查看</button>
             <button type="button" class="btn-edit" data-name="{{.Name}}" title="编辑配置">编辑</button>
             <button type="button" class="btn-del" data-name="{{.Name}}" title="从配置中移除">删除</button>
@@ -285,6 +311,10 @@ <h3 id="modalTitle">Runner 配置</h3>
           <div class="row"><label>安装目录</label><div class="val path" id="vInstallDir"></div></div>
           <div class="row" id="vJobDockerBackendRow" style="display:none"><label>Docker 后端</label><div class="val"><code id="vJobDockerBackend"></code></div></div>
           <div class="row"><label>状态</label><div class="val"><span id="vStatus"></span><span id="vRunning"></span></div></div>
+          <div class="row"><label>探测错误类型</label><div class="val" id="vProbeErrorType"></div></div>
+          <div class="row"><label>建议操作</label><div class="val" id="vProbeSuggestion"></div></div>
+          <div class="row"><label>检查命令（只读）</label><div class="val"><button type="button" id="vCopyCheckCmdBtn" class="btn-copy-cmd" style="display:none">复制命令</button><span id="vProbeCheckCommand"></span></div></div>
+          <div class="row"><label>修复命令（有副作用）</label><div class="val"><button type="button" id="vRevealFixCmdBtn" class="btn-reveal-fix" style="display:none">显示修复命令</button><button type="button" id="vCopyFixCmdBtn" class="btn-copy-cmd" style="display:none">复制命令</button><span id="vProbeFixCommand"></span></div></div>
           <div class="row"><label>探测错误</label><div class="val" id="vProbeError"></div></div>
           <div class="row"><label>注册结果</label><div class="val" id="vRegistrationMessage"></div></div>
           <div class="row"><label>注册检查时间</label><div class="val" id="vRegistrationCheckedAt"></div></div>
@@ -443,13 +473,69 @@ <h3 id="modalTitle">Runner 配置</h3>
       d.textContent = s;
       return d.innerHTML;
     }
+    function resolveProbeSuggestion(data) {
+      if (data && data.probe && data.probe.suggestion) return data.probe.suggestion;
+      return '请先尝试“停止/启动”进行自愈；若仍失败，查看 manager 与 runner 容器日志。';
+    }
+    function resolveProbeError(data) {
+      if (data && data.probe && data.probe.error) return data.probe.error;
+      return '';
+    }
+    function resolveProbeCheckCommand(data) {
+      if (data && data.probe && data.probe.check_command) return data.probe.check_command;
+      return 'docker compose ps && docker logs --tail=200 runner-manager';
+    }
+    function resolveProbeFixCommand(data) {
+      if (data && data.probe && data.probe.fix_command) return data.probe.fix_command;
+      return 'docker compose up -d --force-recreate';
+    }
+    function resolveProbeType(data) {
+      if (data && data.probe && data.probe.type) return data.probe.type;
+      return 'unknown';
+    }
     const modal = document.getElementById('runnerModal');
     const modalTitle = document.getElementById('modalTitle');
     const modalView = document.getElementById('modalView');
     const modalEditForm = document.getElementById('modalEditForm');
     const modalEditBtn = document.getElementById('modalEditBtn');
     const modalSaveBtn = document.getElementById('modalSaveBtn');
     const modalMsg = document.getElementById('modalMsg');
+    const revealFixBtn = document.getElementById('vRevealFixCmdBtn');
+    const copyCheckBtn = document.getElementById('vCopyCheckCmdBtn');
+    const copyFixBtn = document.getElementById('vCopyFixCmdBtn');
+    const probeFixCmdEl = document.getElementById('vProbeFixCommand');
+    const probeCheckCmdEl = document.getElementById('vProbeCheckCommand');
+    let currentProbeCheckCommand = '';
+    let currentProbeFixCommand = '';
+    let probeFixRevealed = false;
+
+    async function copyCommandText(text) {
+      if (!text) return false;
+      try {
+        if (navigator.clipboard && navigator.clipboard.writeText) {
+          await navigator.clipboard.writeText(text);
+          return true;
+        }
+      } catch (_) {
+        // ignore and fallback below
+      }
+      // 回退：在不支持/拒绝 clipboard API 的环境里尝试 execCommand
+      try {
+        const ta = document.createElement('textarea');
+        ta.value = text;
+        ta.setAttribute('readonly', '');
+        ta.style.position = 'fixed';
+        ta.style.top = '-9999px';
+        document.body.appendChild(ta);
+        ta.select();
+        ta.setSelectionRange(0, ta.value.length);
+        const ok = document.execCommand && document.execCommand('copy');
+        document.body.removeChild(ta);
+        return !!ok;
+      } catch (_) {
+        return false;
+      }
+    }
 
     function openModal(mode, name) {
       modalMsg.style.display = 'none';
@@ -479,7 +565,18 @@ <h3 id="modalTitle">Runner 配置</h3>
             }
             document.getElementById('vStatus').innerHTML = '<span class="badge ' + escapeHtml(data.status || '') + '">' + escapeHtml(data.status || '') + '</span>';
             document.getElementById('vRunning').innerHTML = data.running ? ' <span class="badge running">运行中</span>' : '';
-            document.getElementById('vProbeError').textContent = data.probe_error || '—';
+            const probeError = resolveProbeError(data);
+            document.getElementById('vProbeErrorType').textContent = probeError ? resolveProbeType(data) : '—';
+            document.getElementById('vProbeSuggestion').textContent = probeError ? resolveProbeSuggestion(data) : '—';
+            currentProbeCheckCommand = probeError ? resolveProbeCheckCommand(data) : '';
+            probeCheckCmdEl.textContent = currentProbeCheckCommand || '—';
+            copyCheckBtn.style.display = currentProbeCheckCommand ? 'inline-block' : 'none';
+            currentProbeFixCommand = probeError ? resolveProbeFixCommand(data) : '';
+            probeFixRevealed = false;
+            probeFixCmdEl.textContent = probeError ? '（默认隐藏，点击“显示修复命令”）' : '—';
+            revealFixBtn.style.display = probeError ? 'inline-block' : 'none';
+            copyFixBtn.style.display = 'none';
+            document.getElementById('vProbeError').textContent = probeError || '—';
             document.getElementById('vRegistrationMessage').textContent = data.registration_message || '—';
             document.getElementById('vRegistrationCheckedAt').textContent = data.registration_checked_at || '—';
             var gh = data.registered_on_github;
@@ -497,6 +594,11 @@ <h3 id="modalTitle">Runner 配置</h3>
               startStopSpan.style.display = 'inline-block';
               startBtn.style.display = data.running ? 'none' : 'inline-block';
               stopBtn.style.display = data.running ? 'inline-block' : 'none';
+            } else if (data.status === 'unknown') {
+              // 状态探测失败时允许用户手动尝试启停进行自愈
+              startStopSpan.style.display = 'inline-block';
+              startBtn.style.display = 'inline-block';
+              stopBtn.style.display = 'inline-block';
             } else {
               startBtn.style.display = 'none';
               stopBtn.style.display = 'none';
@@ -600,14 +702,45 @@ <h3 id="modalTitle">Runner 配置</h3>
         const r = await fetch('/api/runners/' + encodeURIComponent(name) + '/' + action, { method: 'POST' });
         const data = await r.json().catch(() => ({}));
         if (r.ok) {
-          if (data && data.probe_error) {
-            alert((data.message || '操作已执行') + '\n\n探测错误：' + data.probe_error);
+          const probeError = resolveProbeError(data);
+          if (probeError) {
+            const probeType = resolveProbeType(data);
+            const checkMsg =
+              (data.message || '操作已执行') +
+              '\n\n探测错误类型：' + probeType +
+              '\n建议：' + resolveProbeSuggestion(data) +
+              '\n检查命令：' + resolveProbeCheckCommand(data) +
+              '\n探测错误：' + probeError;
+            alert(checkMsg);
+            if (confirm('是否显示修复命令（有副作用）？建议先执行检查命令确认。')) {
+              alert('修复命令：\n' + resolveProbeFixCommand(data));
+            }
           }
           location.reload();
         }
         else { alert(data.message || r.statusText || '请求失败'); }
       } catch (e) { alert(e.message); }
     }
+    revealFixBtn.addEventListener('click', () => {
+      if (!currentProbeFixCommand) return;
+      if (!confirm('修复命令可能有副作用，确认显示？')) return;
+      probeFixCmdEl.textContent = currentProbeFixCommand;
+      probeFixRevealed = true;
+      copyFixBtn.style.display = 'inline-block';
+    });
+    copyCheckBtn.addEventListener('click', async () => {
+      if (!currentProbeCheckCommand) return;
+      const ok = await copyCommandText(currentProbeCheckCommand);
+      alert(ok ? '检查命令已复制' : '复制失败，请手动复制');
+    });
+    copyFixBtn.addEventListener('click', async () => {
+      if (!probeFixRevealed || !currentProbeFixCommand) {
+        alert('请先显示修复命令并确认后再复制');
+        return;
+      }
+      const ok = await copyCommandText(currentProbeFixCommand);
+      alert(ok ? '修复命令已复制' : '复制失败，请手动复制');
+    });
     document.querySelectorAll('.btn-start').forEach(btn => {
       if (btn.id === 'modalStartBtnFooter') return;
       btn.addEventListener('click', () => runnerAction(btn.getAttribute('data-name'), 'start'));

docs/README.md

@@ -2,6 +2,8 @@
 
 本目录为 Runner Fleet 的详细文档，主文档见 [README](../README.md)。
 
+> 接口变更提示：探测失败信息现仅通过结构化 `probe` 返回，历史扁平字段 `probe_*` 已移除。详见 [开发与构建](development.md) 的 HTTP API 说明与示例。
+
 | 文档 | 说明 |
 |------|------|
 | [配置说明](config.md) | `config.yaml` 各字段说明与示例 |

docs/adding-runner.md

@@ -49,6 +49,14 @@
 - **注册结果**：仅使用添加时在表单中填写的 Token（从 GitHub 复制的短期 token）。每次在界面使用 Token 执行注册后，结果会写入该 runner 目录下的 `.registration_result.json`（成功或失败原因），并在列表与详情中显示。
 - **GitHub 显示检查**（可选）：服务内建定时任务约每 5 分钟检查各 runner 是否已在 GitHub 的 Actions Runners 列表中显示。若需此功能，请在该 runner 安装目录下放置 `.github_check_token` 文件，内容为 PAT（需 scope：组织用 `admin:org`，仓库用 `repo`）。检查结果写入各 runner 目录的 `.github_status.json`，并在界面「注册 / GitHub」列与详情中展示。
 
+## 探测失败与自愈（容器模式）
+
+当列表状态显示 `unknown` 时，表示 Manager 无法完成容器状态探测（例如 Docker 访问异常、Agent 不可达、Agent HTTP 错误），并不代表「启动/停止」一定失败。
+
+- 详情弹窗会展示结构化 `probe` 信息（错误类型、建议、检查命令、修复命令）。
+- 建议先执行「检查命令（只读）」定位问题，再决定是否执行「修复命令（有副作用）」。
+- 在 `status=unknown` 时界面仍保留「启动 / 停止」按钮，可用于手动自愈尝试。
+
 ## 一台机器多 Runner
 
 每个 Runner 使用独立子目录（如 `runners/runner-1`、`runners/runner-2`），互不干扰，可同时运行多个 Runner 并行执行任务。

docs/development.md

@@ -54,10 +54,40 @@ make run
 |------|------|------|
 | `/health` | GET | 返回 `{"status":"ok"}`，可用于 Ingress/K8s 探针。 |
 | `/version` | GET | 返回 `{"version":"..."}`。 |
-| `/api/runners` | GET | 返回 Runner 列表。容器模式下若状态探测失败，会返回 `status=unknown` 且带 `probe_error`。 |
-| `/api/runners/:name` | GET | 返回单个 Runner 详情。容器模式下若状态探测失败，同样返回 `probe_error` 便于排障。 |
-| `/api/runners/:name/start` | POST | 启动指定 Runner。容器模式下若状态探测失败，仍会尝试启动，并在响应中返回 `probe_error`。 |
-| `/api/runners/:name/stop` | POST | 停止指定 Runner。容器模式下若状态探测失败，仍会尝试停止，并在响应中返回 `probe_error`。 |
+| `/api/runners` | GET | 返回 Runner 列表。容器模式下若状态探测失败，会返回 `status=unknown` 且带结构化 `probe`（含 `error/type/suggestion/check_command/fix_command`）。 |
+| `/api/runners/:name` | GET | 返回单个 Runner 详情。容器模式下若状态探测失败，同样返回结构化 `probe`。 |
+| `/api/runners/:name/start` | POST | 启动指定 Runner。容器模式下若状态探测失败，仍会尝试启动，并在响应中返回结构化 `probe`。 |
+| `/api/runners/:name/stop` | POST | 停止指定 Runner。容器模式下若状态探测失败，仍会尝试停止，并在响应中返回结构化 `probe`。 |
+
+### 升级注意（破坏性变更）
+
+- 探测失败相关的历史扁平字段（`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 会将命令拆分为「检查命令（只读）」与「修复命令（有副作用）」，默认建议先执行检查命令；修复命令需要二次确认后才显示。两类命令都支持一键复制（仅复制，不执行），并带浏览器权限受限时的回退复制逻辑。
+
+示例（探测失败）：
+
+```json
+{
+  "name": "runner-a",
+  "status": "unknown",
+  "probe": {
+    "error": "agent 返回 502: bad gateway",
+    "type": "agent-http",
+    "suggestion": "查看 runner 容器日志，确认 Agent 与 /runner 下脚本进程状态",
+    "check_command": "docker ps -a | rg \"github-runner-\" && docker logs --tail=200 <runner_container_name>",
+    "fix_command": "docker restart <runner_container_name>"
+  }
+}
+```
 
 ## Makefile 目标
 

docs/docker.md

@@ -212,6 +212,21 @@ docker run -d --name runner-manager \
 - **回滚**：将 `job_docker_backend` 设为 `dind` 并确保 DinD 已启动（`docker compose --profile dind up -d`）。
 - **可选**：改为 `host-socket` 时需在创建 Runner 容器时挂载宿主机 socket，Compose 已为 Manager 挂载；Runner 容器由 Manager 按 `host-socket` 自动注入挂载与 `DOCKER_HOST`。改为 `none` 时 Job 内无法使用 Docker。
 
+### 状态 `unknown` 的处理（容器模式）
+
+当列表中 Runner 显示 `status=unknown` 时，表示 Manager 对该 Runner 的状态探测失败。常见原因包括：
+
+- Manager 无法访问 Docker（权限、socket、daemon）。
+- Manager 无法连通 Runner 容器内 Agent（网络或容器未就绪）。
+- Agent 返回非 200（Runner 进程异常、容器内依赖异常）。
+
+排查建议：
+
+1. 在 WebUI 详情弹窗查看 `probe` 字段（`error/type/suggestion/check_command/fix_command`）。
+2. 先执行 `probe.check_command`（只读）确认问题边界。
+3. 再按需执行 `probe.fix_command`（有副作用）。
+4. 在 `status=unknown` 时可直接尝试 UI 的「启动 / 停止」按钮进行自愈；接口会继续尝试执行启停动作。
+
 ### 最小验收清单
 
 - [ ] WebUI 可新增一个项目下多个 Runner，并能独立启动/停止。