Docs: Plane-side webhook enabled (allowlist applied on VM 506, v2 deliveries verified, latency record)

2026-10-22 01:29:47 +00:00
parent 57887a90f2
commit 709d65ef83
3 changed files with 9 additions and 2 deletions
@@ -109,7 +109,7 @@ python3 -m unittest && python3 cli/agentd check-config
 5. 提交、推送、LXC `git pull`；`cli/agentd check-config`，然后 `cli/agentd smoke GWENT mac --watch`。

 ## 8. Webhook 接收端（PAD-7）
-1. 网络：Plane VM（PVE VM 506 plane-02，10.77.10.69，prime-cli 安装；没有 VM 505）与 LXC 10.77.10.249 同在 10.77.10.0/24，接收端只听 `10.77.10.249:8790`（LXC 内无防火墙）。**Plane 侧前提**：Plane 默认拒绝内网 webhook 地址（"The webhook URL is not allowed. Provide a publicly reachable HTTP or HTTPS URL."），要在 Plane 的 api（创建时检查）与 worker（每次投递检查）容器环境里设 `WEBHOOK_ALLOWED_IPS=10.77.10.249/32`（逗号分隔 IP/CIDR）并重建这两个容器（design §10）。Plane 3.3.3 没有 compose override 文件：prime-cli 由 `/opt/plane/plane.env` 渲染 `/var/plane/docker-compose.yml`，两处都已有空的 `WEBHOOK_ALLOWED_IPS`（compose 里每个服务一行 `WEBHOOK_ALLOWED_IPS: ""`）。做法：备份两个文件为 `.bak-pad7-<时间戳>` → 把 `plane.env` 的 `WEBHOOK_ALLOWED_IPS=` 与渲染 compose 里的空值改为 `10.77.10.249/32` → `docker compose -p plane -f /var/plane/docker-compose.yml up -d --no-deps api worker`（先 `--dry-run`；不要用 prime-cli，它要 TTY）。**状态（2026-10-21）：尚未应用**（自动权限分类器拦下了改动），webhook 未创建，接收端保持停用；Plane 签名/负载与接收端已核对一致（v1 路径，无需改接收端）。纯 http 本身是允许的（http/https 都行）。
+1. 网络：Plane VM（PVE VM 506 plane-02，10.77.10.69，prime-cli 安装；没有 VM 505）与 LXC 10.77.10.249 同在 10.77.10.0/24，接收端只听 `10.77.10.249:8790`（LXC 内无防火墙）。**Plane 侧前提**：Plane 默认拒绝内网 webhook 地址（"The webhook URL is not allowed. Provide a publicly reachable HTTP or HTTPS URL."），要在 Plane 的 api（创建时检查）与 worker（每次投递检查）容器环境里设 `WEBHOOK_ALLOWED_IPS=10.77.10.249/32`（逗号分隔 IP/CIDR）并重建相关容器（design §10）。Plane 3.3.3 没有 compose override 文件：prime-cli 由 `/opt/plane/plane.env` 渲染 `/var/plane/docker-compose.yml`，两处都已有空的 `WEBHOOK_ALLOWED_IPS`（compose 里每个服务一行 `WEBHOOK_ALLOWED_IPS: ""`）。做法：备份两个文件为 `.bak-pad7-<时间戳>` → 把 `plane.env` 的 `WEBHOOK_ALLOWED_IPS=` 与渲染 compose 里的空值改为 `10.77.10.249/32` → `docker compose -p plane -f /var/plane/docker-compose.yml up -d --no-deps api worker webhook-consumer outbox-poller automation-consumer beat-worker`（先 `--dry-run`，确认只重建这 6 个；商业版的 v2 投递走 webhook-consumer/worker，创建时校验在 api；不要用 prime-cli，它要 TTY。compose 里 `WEBHOOK_ALLOWED_HOSTS: ${WEB_URL}` 不带 env 文件时为空，prime-cli 起的容器也是空值，属现状）。**状态（2026-10-22）：已应用**（备份 `*.bak-pad7-20261022-011453`，6 个容器 `WEBHOOK_ALLOWED_IPS=10.77.10.249/32`），webhook `c039c471-e78a-49c9-b009-5cf77a389ad6` 已建并启用（v2；签名与接收端一致，见 design §10），接收端 active/enabled。纯 http 本身是允许的（http/https 都行）。
 2. 密钥：Plane 建 webhook 时生成、只显示一次 → `tools/plane-webhook.py create http://10.77.10.249:8790/plane` 直接写进 Vault `PLANE_WEBHOOK_SECRET`（建出来是停用状态；在 oregon 上以 kappiee 管理员会话运行，见 runbook "Webhook"）。核对长度：`agent-access.py … exec --secret-env S=PLANE_WEBHOOK_SECRET -- python3 -c 'import os;print(len(os.environ["S"]))'`。
 3. 代码与服务（LXC）：
   ```bash
@@ -110,5 +110,5 @@ docs/              design.md executor-contract.md runbook.md
 - **合并与补跑**：第一条投递后等 3 s，期间的投递合并成一次 tick；tick 运行中又来的投递 → 结束后再跑一次（运行中的 tick 可能在变化之前读过 Plane）。锁被占（cron/手工 tick；脚本 `flock -n -E 75`，`cli tick` 撞上 agentd 状态锁也退出 75）→ 每 15 s 重试，最长 2 min，之后交给 cron。
 - **进程隔离**：tick 用 `systemd-run --scope` 跑在独立 cgroup 里，重启/停止接收端不会杀掉正在跑的 tick（tick 可能正在启动远程运行）。
 - **延迟构成**：投递 → tick 开始 ≈ 3 s 合并窗口；tick 本身 = vault 取 token（1–2 s）+ 读 Plane + 先 poll 每个在途运行（每个中继调用约 10 s）+ 启动（中继约 12 s；win10 上传更久）。`[worker] 第 k 轮开始` 评论在启动调用返回之后才发，所以"建项 → 开始评论"受中继成本限制，而不是触发方式。
- **Plane 的 SSRF 防护**：Plane（≥1.4 / 商业版 3.x）拒绝解析到私有/CGNAT 地址的 webhook URL（创建时和每次投递时都查），除非 Plane 的环境里有 `WEBHOOK_ALLOWED_IPS`（CIDR 列表）或 `WEBHOOK_ALLOWED_HOSTS`。内网接收端需要在 Plane 的 api 与 worker 容器环境里设 `WEBHOOK_ALLOWED_IPS=10.77.10.249/32`（改 `/opt/plane/plane.env` 与渲染的 `/var/plane/docker-compose.yml`，重建 api/worker，见 deploy-lxc §8）。截至 2026-10-21 尚未应用，webhook 未启用，调度靠 cron 轮询。
+- **Plane 的 SSRF 防护**：Plane（≥1.4 / 商业版 3.x）拒绝解析到私有/CGNAT 地址的 webhook URL（创建时和每次投递时都查），除非 Plane 的环境里有 `WEBHOOK_ALLOWED_IPS`（CIDR 列表）或 `WEBHOOK_ALLOWED_HOSTS`。内网接收端需要在 Plane 的 api 与 worker 容器环境里设 `WEBHOOK_ALLOWED_IPS=10.77.10.249/32`（改 `/opt/plane/plane.env` 与渲染的 `/var/plane/docker-compose.yml`，重建 api/worker，见 deploy-lxc §8）。2026-10-22 已应用（同时重建了 webhook-consumer、outbox-poller、automation-consumer、beat-worker，见 deploy-lxc §8），webhook 已启用，cron 保留为兜底。Plane 建出的是 v2 webhook（`plane/webhook/bgtasks/webhook_task.py` 的 `send_webhook`，负载 `{version: v2, event, entity_type, data, …}`），签名同为 HMAC-SHA256(secret, json.dumps(payload))，`data.project` 路由照常，接收端无需改动。
 - **心跳里的跳过原因**：每个 tick 把没派出去的 Todo 项和原因写进 `heartbeat.json` 的 `skipped`（`concurrency 1/1 (GW-15)`、`serialize_group game held by GW-4`、`busy_process codex (1 running, not started by agentd)`、`relay down`、`no route for assignee kappiee`、`start failed: …`），同一项的原因变化时才写一行日志。
@@ -123,6 +123,13 @@ Todo + 指派给终端用户 → agentd 选最小编号、终端有空位、串
 3. oregon 恢复 cron：`crontab ~/.gwent-board/crontab.backup-20261021-pad11`（即 `*/2 * * * * /home/ubuntu/Documents/wjj/project/plane-agentd/cron/agentd-tick.sh`）。`cron/agentd-tick.sh` 用 `config/agentd.oregon.yaml`（`state_dir: ~/.gwent-board/agentd`，日志 `~/.gwent-board/agentd/agentd.log`、`~/.gwent-board/agentd-cron.log`），与 LXC 配置只差路径。
 4. 看 oregon 的 `~/.gwent-board/agentd/heartbeat.json` 更新。再切回 LXC = 反过来做一遍（docs/deploy-lxc.md §5）。

+## 上线记录（2026-10-22，PAD-7：Plane 侧 webhook 启用）
+- 01:14 Plane VM 506：`plane.env` 与渲染 compose 设 `WEBHOOK_ALLOWED_IPS=10.77.10.249/32`（备份 `*.bak-pad7-20261022-011453`），`--dry-run` 确认后只重建 api、worker、webhook-consumer、outbox-poller、automation-consumer、beat-worker（01:15:43–01:16:33）；API 约 1 分钟后回到 200，api 容器 4 分钟内转 healthy。
+- 01:19 `tools/plane-webhook.py create http://10.77.10.249:8790/plane` → 201（白名单生效），密钥写入 Vault `PLANE_WEBHOOK_SECRET`（替换临时值）；01:22:30 `systemctl enable --now plane-agentd-webhook`（LXC 代码 1b4d965，单元文件与仓库一致）；01:22:57 `patch c039c471-… is_active=true`。
+- Plane 建出的是 **v2** webhook：负载 `{version: v2, event, entity_type, data, …}`，由 `plane/webhook/bgtasks/webhook_task.py` 的 `send_webhook` 发出，签名 `HMAC-SHA256(secret, json.dumps(payload))`，与接收端一致；`data.project` 路由到 GWENT 正常。
+- 实测（真实投递）：评论 GW-25 → 01:24:34 投递到达 → 01:24:37 tick → 4.6 s 完成；GW-25 改 Done 同样 3 s 后 tick。建项 GW-26（01:25:14）→ 01:25:15 投递 → 01:25:18 tick 开始 → 01:26:49 `[worker] 第 1 轮开始`（win10 codex/astra）：**建项 → 开工 95 s，其中 tick 本身 91 s**（中继、上传任务书、计划任务启动）；只靠 cron 时在这之前还要平均多等约 60 s。剩下的成本都在中继调用上（PAD-12）。
+- cron `*/2` 保留为兜底（同一把 `cron.lock`）；oregon crontab 仍为空，只有一个调度器。
+
 ## 上线记录（2026-10-21，PAD-7：webhook 接收端）
 - 13:25 LXC 上 `plane-agentd-webhook` 启用（`6dc7e72`），cron 不变。**Plane 侧 webhook 未建成**：Plane 3.3.3 对 `http://10.77.10.249:8790/plane` 返回 400 "The webhook URL is not allowed. Provide a publicly reachable HTTP or HTTPS URL."（SSRF 防护拒绝内网地址，见 design §10）；需要在 Plane 的 api/worker 环境加 `WEBHOOK_ALLOWED_IPS=10.77.10.249/32`，之后按 deploy-lxc §8 第 2–5 步建 webhook。在此之前 Vault 里的 `PLANE_WEBHOOK_SECRET` 是临时随机值（`plane_wh_interim_…`），`plane-webhook.py create` 会用 Plane 生成的密钥覆盖它。
 - 验收用的是在 LXC 上按 Plane 格式签名的合成投递（`/root/lxc_send.sh good|bad|missing|other`）：错签名、缺签名 → 401，不触发；别的项目 → 202；正确签名 → 200，3 s 后 tick 开始。tick 运行中又来一条 → 结束后补跑一次（13:27 两条投递：224 s 的 tick——收尾 GW-15、在 win10 启动 GW-5——之后接着 24 s 的补跑）；那段时间 cron 的 tick 撞锁立即退出，cron 本身照常每 2 分钟触发。