From a6478936cb04dfd8d61e1da918d9e51acbb3169b Mon Sep 17 00:00:00 2001
From: pikastech <liang6516@outlook.com>
Date: Mon, 20 Jul 2026 09:21:15 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=9B=BA=E5=8C=96=20PaC=20=E5=85=AC?=
 =?UTF-8?q?=E5=85=B1=E9=98=9F=E5=88=97=E6=81=A2=E5=A4=8D=E8=BE=B9=E7=95=8C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../references/incident-recovery.md           | 35 +++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/.agents/skills/unidesk-cicd/references/incident-recovery.md b/.agents/skills/unidesk-cicd/references/incident-recovery.md
index e6296eb3..593b2427 100644
--- a/.agents/skills/unidesk-cicd/references/incident-recovery.md
+++ b/.agents/skills/unidesk-cicd/references/incident-recovery.md
@@ -211,6 +211,41 @@
   - 被点名 credential 文件的写入者与 source of truth；
   - 受控 CLI 对该 fatal 的诊断、可恢复备份和验收能力。
 
+### PaC watcher 跨节点失联与 Pending 队列恢复
+
+- 适用指纹：
+  - PaC watcher Deployment 显示 Ready，但日志停止推进；
+  - 多个 consumer 的 PipelineRun 长期停在 `PipelineRunPending`，没有 TaskRun；
+  - watcher 访问集群内 Gitea Service 超时，而 Gitea Pod、Service endpoint
+    和同节点探针正常；
+  - watcher 位于已 cordon 或 Pod 网段异常的 worker，Gitea 位于控制面节点。
+- 先区分公共控制面与具体 Provider：
+  - watcher、Tekton controller、Gitea、Service 网络和共享 PaC 队列属于公共 CI/CD；
+  - AgentRun runner、HWLAB node、业务 Deployment 和 Provider 数据通道不在恢复范围；
+  - 用户只授权公共运维时，不得借机重启、迁移或修改具体 Provider。
+- 快速恢复必须按依赖顺序执行：
+  - 先确认 node、Gitea Pod、Service endpoint 和 watcher placement；
+  - 公共无状态 controller 卡在不可调度且跨节点网络失效的 worker 时，
+    只删除该精确 Pod，让 Deployment 在 YAML 允许的健康节点重建；
+  - controller 重新取得 leader 且能访问 Gitea 后，再处理队列；
+  - 不得先批量删除 PipelineRun，也不得用业务重跑掩盖公共依赖故障。
+- watcher 停机后可能只重建内存队列，无法补发已经完成的前序事件：
+  - 用 `execution-order`、source commit、`spec.status`、TaskRun 数量和终态条件
+    确认卡住的事件组；
+  - 当前权威 source commit 只从 GitHub source branch 获取；
+  - 仅取消同一 Repository 中仍为 Pending 且已被权威 commit 取代的运行；
+  - 使用 Tekton 合法的 `spec.status: Cancelled`，保留 PipelineRun 历史对象；
+  - 保护权威 commit 的完整执行组、active run、latest success 和审计证据；
+  - 没有明确公共运维授权时，只报告候选，不执行队列 mutation。
+- 临时恢复不能作为完成证据：
+  - Pod 重建、精确 Pending 取消和 controller 重新选主只证明公共通道恢复；
+  - 长期调度归属必须回写 owning YAML，避免公共 controller 再落到隔离 worker；
+  - 最终必须由新的正常 GitHub source event 自动经过 Gitea、PaC、Tekton
+    和 public-edge reconcile；
+  - 公网入口验收同时要求受控 public-edge status 无 unresolved/probe failure、
+    desired/current fingerprint 一致、provenance source commit 对齐，
+    并以绕过本机代理的公网 IP HTTPS probe 确认 TLS 和 readiness。
+
 ### 长期防复发
 
 - 从 renderer/source 消除重复内联：