PAD-12: per-terminal transport (direct Tailscale SSH or Warpgate, pre-session fallback, pinned host keys, agent key from Vault), one-call win10 launch and one-call collect, remote call timings, agentd ping
This commit is contained in:
jj.wang
+56
-5
@@ -1,6 +1,6 @@
|
||||
# 在精简 LXC 上部署 agentd（design §9 阶段 3）
|
||||
|
||||
调度器跑在一台**不装任何 agent CLI** 的 Debian 12 LXC（`agentd-01`）上；所有终端（win10、oregon、mac…）都经 Warpgate SSH 远程启动（`transport: warpgate-ssh`）。LXC 只做调度、回帖、通知。
|
||||
调度器跑在一台**不装任何 agent CLI** 的 Debian 12 LXC（`agentd-01`）上；所有终端（win10、oregon、mac…）都是远程启动：经 Warpgate SSH（`transport: warpgate-ssh`），或经 Tailscale 直连并以 Warpgate 兜底（`transport: direct-ssh`，PAD-12，§9）。LXC 只做调度、回帖、通知。
|
||||
|
||||
实际部署（2026-10-21，PAD-11）：`agentd-01` = PVE CT 600，Debian 12，tailnet `100.69.78.124`，Warpgate target `agentd-01`，登录 **root**（Vault skill `ssh-agentd-01`；没有另建部署用户，agentd 以 root 运行）。下面是实际做过的步骤；从 oregon 发命令都经 `agent-access.py … run --target agentd-01 --timeout N -- bash -c '…'`。
|
||||
|
||||
@@ -9,14 +9,15 @@ LXC 交付时已有 `python3`（3.11）、`python3-yaml`、`openssh-client`、`g
|
||||
```bash
|
||||
apt-get update && apt-get install -y python3 python3-yaml openssh-client git cron ca-certificates
|
||||
```
|
||||
`jsonschema` 可选，没有就用内置子集校验器。
|
||||
`jsonschema` 可选，没有就用内置子集校验器。`direct-ssh` 要用的 `ssh`、`ssh-agent`、`ssh-add`、`ssh-keygen` 都在 `openssh-client` 包里（Debian 12：OpenSSH 9.2）。
|
||||
|
||||
## 2. 网络
|
||||
| 去向 | 用途 |
|
||||
|---|---|
|
||||
| `nas.tail9531b.ts.net:8443`（tailnet） | Agent Vault 身份配置 `identity/agent.json`（含 vault token 与 Warpgate 主机公钥）→ LXC 已在 tailnet |
|
||||
| Vault（身份配置里的地址） | 取 Plane token、Warpgate 密码 |
|
||||
| Warpgate SSH `115.28.210.101:2222` | 所有终端的中继（LXC → win10 / oregon） |
|
||||
| Warpgate SSH `115.28.210.101:2222` | `warpgate-ssh` 终端的中继，以及 `direct-ssh` 的兜底（LXC → win10 / oregon） |
|
||||
| tailnet：win10 `100.123.209.19:22`、oregon `100.127.58.78:22` | `direct-ssh` 直连（PAD-12，§9） |
|
||||
| `https://plane.kappiee.com` | Plane API |
|
||||
| `https://git.kappiee.com` | `git pull`（公开仓库，无需凭据） |
|
||||
|
||||
@@ -48,7 +49,7 @@ mkdir -p /var/lib/plane-agentd /var/log/plane-agentd && chmod 700 /var/lib/plane
|
||||
python3 -m unittest && python3 cli/agentd check-config
|
||||
```
|
||||
不需要本地配置文件，全部在仓库里（部署可复现）：
|
||||
- `config/agentd.yaml` = agentd-01 的实时配置：`state_dir: /var/lib/plane-agentd`（状态、心跳、锁），`log_dir: /var/log/plane-agentd`（`agentd.log`），`helpers_dir: tools/win10`，`vault.client: ~/.local/share/server-access-client/agent-access.py`（root 下即 `/root/...`）。终端 win10（warpgate-ssh/windows/schtasks）和 oregon（warpgate-ssh/linux/nohup，`run_root: /home/ubuntu/.gwent-board/agentd-runs`，`bins.claude`）；没有 local 终端。
|
||||
- `config/agentd.yaml` = agentd-01 的实时配置：`state_dir: /var/lib/plane-agentd`（状态、心跳、锁），`log_dir: /var/log/plane-agentd`（`agentd.log`），`helpers_dir: tools/win10`，`vault.client: ~/.local/share/server-access-client/agent-access.py`（root 下即 `/root/...`）。终端 win10（direct-ssh + 兜底 warpgate-ssh/windows/schtasks）和 oregon（direct-ssh + 兜底 warpgate-ssh/linux/nohup，`run_root: /home/ubuntu/.gwent-board/agentd-runs`，`bins.claude`）；没有 local 终端。`agentd.ssh_key: AGENTD_SSH_KEY`，`agentd.ssh_dir: /run/plane-agentd/ssh`（ControlMaster 套接字和生成的 known_hosts，agentd 自己建，权限 0700）。
|
||||
- `tools/win10/win10-ps.sh`、`win10-put.sh`：win10 helper（vault 客户端目录取 `AGENT_ACCESS_HOME`，默认 `~/.local/share/server-access-client`；身份取 `AGENT_ACCESS_CONFIG`）。相对 `helpers_dir` 按仓库根解析。
|
||||
- `config/protocols/gwent-board-protocol.md`：看板协议（拼进每轮 prompt，LXC 本机读取）。来源是 gwent 仓库 `design/board-protocol.md`，**协议更新时复制过来提交**，然后 LXC `git pull`。
|
||||
- `config/agentd.oregon.yaml`：oregon 作调度器时的配置（回滚用，见 runbook）。
|
||||
@@ -67,7 +68,7 @@ python3 -m unittest && python3 cli/agentd check-config
|
||||
```
|
||||
*/2 * * * * /opt/plane-agentd/cron/agentd-tick-lxc.sh
|
||||
```
|
||||
`cron/agentd-tick-lxc.sh` = `flock -n /var/lib/plane-agentd/cron.lock timeout 900 python3 -I /root/.local/share/server-access-client/agent-access.py --config <identity> exec --secret-env PLANE_OREGON_API_TOKEN=… --secret-env PLANE_WINDOW10_API_TOKEN=… --timeout 850 -- python3 /opt/plane-agentd/cli/agentd --config /opt/plane-agentd/config/agentd.yaml tick --once >> /var/log/plane-agentd/cron.log 2>&1`。
|
||||
`cron/agentd-tick-lxc.sh` = 拿 `/var/lib/plane-agentd/cron.lock`（`flock -n -E 75`）后执行 `timeout 900 python3 -I /root/.local/share/server-access-client/agent-access.py --config <identity> exec --secret-env PLANE_OREGON_API_TOKEN=… --secret-env PLANE_WINDOW10_API_TOKEN=… --secret-env AGENTD_SSH_KEY=AGENTD_SSH_KEY --timeout 850 -- python3 /opt/plane-agentd/cli/agentd --config /opt/plane-agentd/config/agentd.yaml tick --once`，输出追加到 `/var/log/plane-agentd/cron.log`；Vault 取不到 `AGENTD_SSH_KEY` 时不带它重跑一次（§9）。
|
||||
注意：经中继装 crontab 时别在 `set -e` 下写 `(crontab -l | grep -v …; echo …) | crontab -`——没有旧 crontab 时 grep 返回 1，子 shell 提前退出，装进去的是空 crontab。直接 `printf '%s\n' '<行>' | crontab -`。
|
||||
5. 验证：`/var/lib/plane-agentd/heartbeat.json` 的 `at` 每 2 分钟更新。
|
||||
6. 冒烟经 LXC 调度器：在 oregon 上 `cli/agentd smoke GWENT oregon --watch`（`--watch` = 只建项并等待，不在本机 tick；oregon 上 `cli/agentd` 默认读 `config/agentd.yaml`，CLI 只需要 Plane token）。
|
||||
@@ -122,3 +123,53 @@ python3 -m unittest && python3 cli/agentd check-config
|
||||
单元文件复用 cron 脚本的 vault 客户端调用方式：`python3 -I /root/.local/share/server-access-client/agent-access.py --config <identity> exec --secret-env PLANE_WEBHOOK_SECRET=PLANE_WEBHOOK_SECRET --timeout 315360000 -- python3 /opt/plane-agentd/cli/agentd … webhook-serve --bind 10.77.10.249 --port 8790`，`Restart=always`。tick 由接收端经 `systemd-run --scope … cron/agentd-tick-lxc.sh` 拉起（同一把 `cron.lock`，`flock -n -E 75`）。
|
||||
4. 启用 Plane 侧：`tools/plane-webhook.py patch <id> is_active=true`，然后 `systemctl restart plane-agentd-webhook`（若第 2 步之后密钥变过）。
|
||||
5. 验证：随便改一个 GWENT 工作项 → `webhook.log` 出现 `decision=tick` 和 `tick start`/`tick done`；错签名请求得 401 且没有 tick；`journalctl -u cron` 里 cron 仍每 2 分钟一次；`systemctl restart plane-agentd-webhook` 后 `/healthz` 恢复。
|
||||
|
||||
## 9. 直连 SSH（PAD-12）
|
||||
LXC 经 Tailscale 直连终端的 sshd，不经过 Warpgate（design §9"终端通道"）。每个终端单独配置，Warpgate 留作兜底。前提：终端在 tailnet 上，LXC（`100.69.78.124`）能连到它的 22 端口。实测：win10 `100.123.209.19`（Windows OpenSSH，账号 administrator，直连 RTT 27 ms），oregon `100.127.58.78`（账号 ubuntu，RTT 233 ms）。
|
||||
|
||||
**上线顺序**：`cron/agentd-tick-lxc.sh` 带着 `--secret-env AGENTD_SSH_KEY=AGENTD_SSH_KEY`。agent-access.py 没有可选密钥，取不到键时报 `credential_unavailable`，整个 exec 失败；cron 脚本认出这种情况后会去掉这个参数再跑一次（cron.log 记一行 `AGENTD_SSH_KEY not available from Vault …`），所以先 pull 也不会停派单，只是直连终端一直走兜底。仍然建议第 1–3 步做完再 pull，免得每个 tick 多取一次 Vault。
|
||||
|
||||
1. **生成专用密钥**（在 LXC 上；私钥只进 Vault，不留在磁盘上）：
|
||||
```bash
|
||||
umask 077; d=$(mktemp -d -p /dev/shm) # tmpfs：私钥不落到磁盘（磁盘上 shred 在日志式/写时复制文件系统上不可靠）
|
||||
ssh-keygen -q -t ed25519 -N '' -C plane-agentd@agentd-01 -f "$d/agentd"
|
||||
cat "$d/agentd.pub" # 公钥，下面两步要用
|
||||
```
|
||||
私钥 `$d/agentd` 原样（多行文本）写进 Vault 键 **`AGENTD_SSH_KEY`**：在 Vault UI 里粘贴，或者用与 `tools/plane-webhook.py` 的 `vault_store()` 相同的接口（`POST /v1/credentials`，agent 身份），读文件直接写，不打印。值里的换行被转义成 `\n` 也可以，agentd 会还原。写完删掉：`rm -rf "$d"`（在 tmpfs 上，删掉即可）。核对时只看长度：
|
||||
`agent-access.py --config <identity> exec --secret-env K=AGENTD_SSH_KEY --timeout 60 -- python3 -c 'import os;print(len(os.environ["K"]))'`（ed25519 私钥约 400 字符）。
|
||||
2. **oregon**（经 Warpgate 操作）：在 `~ubuntu/.ssh/authorized_keys` 追加一行（目录 700、文件 600）：
|
||||
```
|
||||
restrict,from="100.69.78.124" ssh-ed25519 AAAA…（上一步的公钥） plane-agentd@agentd-01
|
||||
```
|
||||
`restrict` 关掉所有转发、pty 和 `~/.ssh/rc`（agentd 用 `-T`，不需要 pty），不必再单独写 `no-port-forwarding` 等；`from=` 只放行 LXC 的 tailnet 地址。sshd 不认识 `restrict`（OpenSSH 7.2 之前）时会把整行判为无效：认证失败、终端走兜底，不会放宽权限；第 5 步的 ping 能看出来（`sshd -V` 或 Windows 上 `sshd.exe -V` 看版本）。可选的再一层：Tailscale ACL 只允许 LXC（`100.69.78.124` 或它的 tag）访问 win10/oregon 的 `:22`，这样密钥泄露了也没用。
|
||||
3. **win10**（经 Warpgate，`tools/win10/win10-ps.sh`）：Administrator 属于 Administrators 组，所以 sshd 读的是 `C:\ProgramData\ssh\administrators_authorized_keys`，不是用户目录下的文件。用 ASCII 追加同样的一行（别覆盖已有的行），再把 ACL 收紧到只有 Administrators 和 SYSTEM（用 SID，不受系统语言影响），否则 sshd 会忽略这个文件：
|
||||
```powershell
|
||||
$f = 'C:\ProgramData\ssh\administrators_authorized_keys'
|
||||
$line = 'restrict,from="100.69.78.124" ssh-ed25519 AAAA… plane-agentd@agentd-01'
|
||||
if ((Test-Path $f) -and (Get-Content -Raw $f) -and -not (Get-Content -Raw $f).EndsWith("`n")) { $line = "`r`n" + $line } # 原文件末尾没换行时，别把新行粘到最后一把钥匙后面
|
||||
Add-Content -Path $f -Encoding ascii -Value $line
|
||||
icacls $f /inheritance:r /grant '*S-1-5-32-544:F' /grant '*S-1-5-18:F'
|
||||
```
|
||||
顺便确认 sshd 的默认 shell 是 cmd.exe（`HKLM:\SOFTWARE\OpenSSH` 下没有 `DefaultShell`，或它指向 cmd.exe）。agentd 发的远程命令是 `powershell.exe -NoProfile -NonInteractive -EncodedCommand <引导>`，真正的脚本经 stdin 传过去。外层如果被改成 PowerShell，stdin 可能转不到内层；第 5 步的 ping 能直接发现这个问题。
|
||||
4. **钉住的主机公钥**已写在 `config/agentd.yaml` 的 `terminals.<t>.ssh.host_key`，经两个通道核对过：Warpgate 读终端上的 `ssh_host_ed25519_key.pub`，与 tailnet 上 `ssh-keyscan -t ed25519` 的结果一致。新加终端照此办理：
|
||||
```bash
|
||||
ssh-keyscan -t ed25519 <tailnet ip> # LXC 上，直连
|
||||
agent-access.py … run --target <t> -- cat /etc/ssh/ssh_host_ed25519_key.pub # 第二通道（Windows：type C:\ProgramData\ssh\ssh_host_ed25519_key.pub）
|
||||
```
|
||||
两边一致才能写进配置。agentd 每次调用都用它生成 known_hosts（`<ssh_dir>/known_hosts.<终端>`，别名 `agentd-<终端>`），全局和用户的 known_hosts 都不读。
|
||||
5. **上线与验证**（在 LXC 上；拿着 cron 锁做，期间 cron 和 webhook 的 tick 会跳过，webhook 会自动重试）：
|
||||
```bash
|
||||
cd /root/.local/share/server-access-client
|
||||
flock /var/lib/plane-agentd/cron.lock bash -c '
|
||||
git -C /opt/plane-agentd pull &&
|
||||
for t in win10 oregon; do
|
||||
python3 -I agent-access.py --config https://nas.tail9531b.ts.net:8443/identity/agent.json exec \
|
||||
--secret-env AGENTD_SSH_KEY=AGENTD_SSH_KEY --timeout 120 -- \
|
||||
python3 /opt/plane-agentd/cli/agentd ping $t --transport direct-ssh -n 3
|
||||
done'
|
||||
```
|
||||
预期每个终端打印 3 行 `term=<t> via=direct op=ping ms=… rc=0` 和 `ping n: … ms PONG=…`。第 1 次要握手（win10 约 0.5–1.5 s，oregon 约 2–3 s），第 2、3 次复用连接，应明显更快。win10 若是 `timeout`，多半是 stdin 没到内层 PowerShell，见第 3 步。`--transport warpgate-ssh` 可顺带确认兜底仍然通（约 9 s）。
|
||||
`cli/agentd check-config` 会多出 `direct-ssh …` 行，`cron/exec secret args` 末尾多了 `--secret-env AGENTD_SSH_KEY=AGENTD_SSH_KEY`。
|
||||
6. **观察**：下一个 tick 后看 `/var/log/plane-agentd/remote.log`，应该只有 `via=direct` 行；出现 `via=fallback` 说明直连失败了，同时 `agentd.log` 会有一行原因。在 oregon 上 `cli/agentd smoke GWENT win10 --watch`，量"建项 → `[worker] 第 1 轮开始`"，目标 ≤ 15 s（原来 91 s）。
|
||||
7. **回滚**：把终端的 `transport` 改回 `warpgate-ssh`（提交、推送、LXC 上 `git pull`；`ssh`/`fallback` 可以留着）。cron 脚本里的 `--secret-env AGENTD_SSH_KEY=…` 可以保留：agentd 总会把它从子进程环境里去掉。Vault 键被删掉也不会停 tick（脚本会不带它重跑），但每个 tick 会多取一次 Vault，届时最好也删掉这一行。紧急情况下可在 LXC 上 `git -C /opt/plane-agentd checkout 83bc0f2 -- config/agentd.yaml`（旧配置，全部走 Warpgate，新代码照常能用）。要彻底撤销直连授权：删掉两台终端 authorized_keys 里那一行，再在 LXC 上关掉已经建好的 ControlMaster 连接（删 authorized_keys 不会断开它们，紧挨着的 webhook tick 能让它们活过 60 s）：`for s in /run/plane-agentd/ssh/*-*; do [ -S "$s" ] && ssh -O exit -o ControlPath="$s" x; done`。
|
||||
8. **轮换密钥**：照第 1 步生成新钥，先把新公钥加到两台终端，再更新 Vault `AGENTD_SSH_KEY`，然后删掉旧公钥的行，再照第 7 步关掉已有的 ControlMaster 连接（否则它们空闲 60 s 后才退出）。之后新连接就用新钥。改了某个终端钉住的 `host_key` 不需要这一步：套接字名里带着 pin 的指纹，新 pin 自动用新连接。
|
||||
|
||||
Reference in New Issue
Block a user