feat(agent): node agent — enroll/mTLS, heartbeat, command stream, sing-box 用户表 (tsk__R8M4jEw43JR)

与控制面同仓同 go.mod，新增节点 agent 实现：

- proto/agent/v1/agent.proto + internal/pb/agentv1：冻结的控制面↔agent gRPC 契约
  （Enroll/Register/Heartbeat/Subscribe/Ack/ReportUsage）。仓库尚无 protoc 流水线，
  暂以手写 Go 类型 + JSON gRPC codec 实现，与 proto 1:1 对应，待 protoc 接入即可替换。
- internal/agentd：
  - enroll.go：首启生成 EC 密钥+CSR，持 bootstrap token 调 Enroll 换 90d 节点证书
    （CN=node_uuid），落 /etc/pangolin-agent/，此后 mTLS。
  - conn.go(agent.go)+creds.go：mTLS 主动拨号 + 指数退避重连；重连携带 last_command_id；
    Register 取 ConfigSnapshot 全量配置覆盖本地。
  - heartbeat.go：30s 上报 peer/带宽/CPU + config_version；need_full_resync→全量同步。
  - command.go：消费 Subscribe，Upsert/Revoke/Rotate/ApplyConfig/Lifecycle 幂等处理后
    Ack（at-least-once，按 command_id 去重）。
  - singbox.go+render.go：内存用户表 + 落盘 state.json（仅 dp_uuid+expires_at）；任何变更
    渲染完整 sing-box 配置（REALITY users[uuid,flow] + Hy2 users[派生口令]）→ 500ms 去抖
    合并 → systemd 重启。
  - ttl.go：凭证 TTL 定时移除并上报。
  - usage.go：按 dp_uuid 聚合上报，绝无 user_id/email/目的地址。
  - derive.go：Hy2 口令 = HMAC-SHA256(key, dp_uuid)，与控制面同源派生。
- cmd/agent：入口（flag/env 配置）。
- infra/cloud-init/{node.yaml.tmpl,install-node.sh,README.md}：一段式安装，下载锁定版本
  二进制并校验 SHA-256，systemd 拉管，首启即 Enroll/Register。shellcheck -S warning 通过。

测试（bufconn mock 控制面，无需 docker）：Enroll→Register→Heartbeat 全流转；Upsert/Revoke
渲染正确；Rotate 宽限期新旧并存到点移除；TTL 自动移除并上报；断流重连 last_command_id
续发不丢不重；need_full_resync 触发重注册；state.json 恢复；去抖合并；扫描确认无身份字段。
go test -race ./internal/agentd/... ./internal/pb/... 通过；go vet ./... 通过。

落实 doc/04 §2 节点无状态化与 doc/06 §3 数据面红线（节点仅见 dp_uuid）。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

infra/cloud-init/README.md

@@ -0,0 +1,39 @@
+# infra/cloud-init —— 节点一段式安装
+
+加速节点开机即用所需的全部物料。控制面（或 #14 弹性开机）在创建节点前，用 `sed`
+把模板里的 `__PLACEHOLDER__` 替换成真实值（沿用 `deploy/` 渲染约定），再作为
+user-data 注入。
+
+## 文件
+
+- `node.yaml.tmpl` —— cloud-config 模板。写入 `/etc/pangolin-agent/agent.env`
+  （含一次性 bootstrap token，0600），下载并按 SHA-256 校验 `install-node.sh` 后执行。
+- `install-node.sh` —— 幂等安装脚本：下载锁定版本的 `sing-box` + `pangolin-agent`
+  二进制并校验 SHA-256，装 systemd 单元（agent 拉管 sing-box），生成 Hy2 自签证书，
+  启动 agent（首启即 Enroll/Register）。`shellcheck -S warning` 通过。
+
+## 占位符
+
+| 占位符 | 含义 |
+| --- | --- |
+| `__CONTROL_PLANE__` | 控制面 gRPC 地址 `host:port` |
+| `__SERVER_NAME__` | 校验控制面证书的 TLS SNI（留空取 host） |
+| `__BOOTSTRAP_TOKEN__` | 一次性引导 token（`mtls.BootstrapTokenManager`，15min TTL） |
+| `__DERIVE_KEY__` | Hy2 口令派生密钥（与控制面同源，见 `agentd.DeriveHy2Password`） |
+| `__AGENT_VERSION__` | agent 版本（与产物命名 + SHA 一致） |
+| `__SINGBOX_VERSION__` / `__SINGBOX_SHA256__` | sing-box 版本与校验和 |
+| `__AGENT_SHA256__` | agent 二进制校验和 |
+| `__ARTIFACT_BASE__` | 二进制 + 安装脚本下载根 URL |
+| `__INSTALL_SHA256__` | `install-node.sh` 自身的 SHA-256（防篡改） |
+
+## 可复现性
+
+版本与 SHA-256 全部锁定：`install-node.sh` 顶部的版本/校验和占位符由发布流水线渲染
+为固定值并随产物一起发布；cloud-init 下载脚本后先校验脚本 SHA-256 再执行，脚本再逐个
+校验二进制 SHA-256。任何一环不匹配即 `set -e` 中止，保证整链可复现、不可被中间人替换。
+
+## 无状态红线
+
+节点除 `/etc/pangolin-agent/{node.key,node.crt,ca.crt,state.json}` 与 `/etc/sing-box`
+外不落任何持久数据；`state.json` 仅含 `dp_uuid + expires_at`，无任何账号/设备/目的地址/
+DNS 信息，亦无访问日志（见 `doc/04 §2`、`doc/06 §3`）。

infra/cloud-init/install-node.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# install-node.sh —— Pangolin 加速节点一键安装（由 cloud-init runcmd 调用，幂等）。
+#
+# 职责：下载锁定版本的 sing-box + pangolin-agent 二进制并校验 SHA-256 → 安装 systemd
+# 单元（agent 拉管 sing-box）→ 生成 Hy2 自签证书 → 启动 agent（首启即 Enroll/Register）。
+#
+# 版本与校验和通过 __PLACEHOLDER__ 由发布流水线/控制面 provisioner 用 sed 渲染（沿用
+# deploy/ 约定），保证「二进制版本 + SHA-256 锁定可复现」。也可用同名环境变量覆盖。
+#
+# 数据面无状态红线：本脚本不写任何用户身份、不开访问日志；唯一持久数据是
+# /etc/pangolin-agent/state.json（仅 dp_uuid + expires_at，由 agent 维护）。
+set -euo pipefail
+
+SINGBOX_VERSION="${SINGBOX_VERSION:-__SINGBOX_VERSION__}"
+SINGBOX_SHA256="${SINGBOX_SHA256:-__SINGBOX_SHA256__}"
+AGENT_VERSION="${AGENT_VERSION:-__AGENT_VERSION__}"
+AGENT_SHA256="${AGENT_SHA256:-__AGENT_SHA256__}"
+ARTIFACT_BASE="${ARTIFACT_BASE:-__ARTIFACT_BASE__}"
+
+STATE_DIR=/etc/pangolin-agent
+INSTALL_DIR=/usr/local/bin
+SB_CFG_DIR=/etc/sing-box
+MASQ_CN=www.bing.com
+
+log() { echo "[install-node] $*"; }
+
+# 架构映射（与发布产物命名对齐）。
+arch="$(uname -m)"
+case "$arch" in
+  x86_64 | amd64) goarch=amd64 ;;
+  aarch64 | arm64) goarch=arm64 ;;
+  *)
+    echo "[install-node] unsupported arch: $arch" >&2
+    exit 1
+    ;;
+esac
+
+# fetch_verify URL EXPECTED_SHA256 DEST —— 下载、校验、原子安装为可执行文件。
+fetch_verify() {
+  url="$1"
+  sha="$2"
+  dest="$3"
+  tmp="$(mktemp)"
+  log "downloading $url"
+  curl -fsSL --retry 3 "$url" -o "$tmp"
+  echo "${sha}  ${tmp}" | sha256sum -c -
+  install -m 0755 "$tmp" "$dest"
+  rm -f "$tmp"
+  log "installed $dest"
+}
+
+install -d -m 700 "$STATE_DIR"
+install -d -m 755 "$SB_CFG_DIR" "$SB_CFG_DIR/cert"
+
+fetch_verify "${ARTIFACT_BASE}/sing-box-${SINGBOX_VERSION}-linux-${goarch}" \
+  "$SINGBOX_SHA256" "${INSTALL_DIR}/sing-box"
+fetch_verify "${ARTIFACT_BASE}/pangolin-agent-${AGENT_VERSION}-linux-${goarch}" \
+  "$AGENT_SHA256" "${INSTALL_DIR}/pangolin-agent"
+
+# Hy2 入站需要 TLS 证书；自签即可（masquerade 用），幂等。
+if [[ ! -f "${SB_CFG_DIR}/cert/hy2.crt" || ! -f "${SB_CFG_DIR}/cert/hy2.key" ]]; then
+  log "generating self-signed Hy2 certificate"
+  openssl ecparam -genkey -name prime256v1 -out "${SB_CFG_DIR}/cert/hy2.key"
+  openssl req -new -x509 -days 3650 -key "${SB_CFG_DIR}/cert/hy2.key" \
+    -out "${SB_CFG_DIR}/cert/hy2.crt" -subj "/CN=${MASQ_CN}"
+  chmod 600 "${SB_CFG_DIR}/cert/hy2.key"
+  chmod 644 "${SB_CFG_DIR}/cert/hy2.crt"
+fi
+
+# sing-box 单元：由 agent 渲染配置后 `systemctl restart` 拉起（不预启，避免无配置失败循环）。
+cat > /etc/systemd/system/sing-box.service <<'UNIT'
+[Unit]
+Description=sing-box data plane (managed by pangolin-agent)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=/usr/local/bin/sing-box run -c /etc/sing-box/config.json
+Restart=on-failure
+RestartSec=1
+LimitNOFILE=1048576
+# 无状态：禁止持久写盘（配置目录除外）。
+NoNewPrivileges=true
+ProtectHome=true
+
+[Install]
+WantedBy=multi-user.target
+UNIT
+
+# pangolin-agent 单元：常驻、自动重连；EnvironmentFile 由 cloud-init 写入。
+cat > /etc/systemd/system/pangolin-agent.service <<'UNIT'
+[Unit]
+Description=Pangolin node agent
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+EnvironmentFile=/etc/pangolin-agent/agent.env
+ExecStart=/usr/local/bin/pangolin-agent
+Restart=always
+RestartSec=2
+NoNewPrivileges=true
+
+[Install]
+WantedBy=multi-user.target
+UNIT
+
+systemctl daemon-reload
+# sing-box 仅 enable 不 start：等 agent 首次渲染配置后由 agent restart 拉起。
+systemctl enable sing-box.service
+systemctl enable --now pangolin-agent.service
+
+log "done; agent will Enroll/Register and render sing-box config on first connect"

infra/cloud-init/node.yaml.tmpl

@@ -0,0 +1,45 @@
+#cloud-config
+# Pangolin 加速节点一段式安装模板（与 #14 弹性开机共用）。
+#
+# 渲染：控制面 provisioner 用 sed 替换所有 __PLACEHOLDER__（沿用 deploy/ 约定）。
+#   __CONTROL_PLANE__   控制面 gRPC 地址 host:port
+#   __SERVER_NAME__     校验控制面证书的 TLS SNI（留空则取 host 部分）
+#   __BOOTSTRAP_TOKEN__ 一次性引导 token（由 mtls.BootstrapTokenManager.IssueToken 预签发，15min TTL）
+#   __DERIVE_KEY__      Hy2 口令派生密钥（与控制面同源，见 agentd.DeriveHy2Password）
+#   __AGENT_VERSION__   pangolin-agent 版本（与产物命名/SHA 锁定一致）
+#   __ARTIFACT_BASE__   二进制与安装脚本下载根 URL
+#   __INSTALL_SHA256__  install-node.sh 的 SHA-256（整链可复现校验）
+#
+# 安全：agent.env 内含 bootstrap token，权限 0600；token 一次性消费后即失效。
+# 节点无状态：除 /etc/pangolin-agent/{node.key,node.crt,ca.crt,state.json} 与
+# /etc/sing-box 外不落任何持久数据，且 state.json 仅含 dp_uuid + expires_at。
+
+write_files:
+  - path: /etc/pangolin-agent/agent.env
+    permissions: '0600'
+    owner: root:root
+    content: |
+      PANGOLIN_AGENT_CONTROL_PLANE=__CONTROL_PLANE__
+      PANGOLIN_AGENT_SERVER_NAME=__SERVER_NAME__
+      PANGOLIN_AGENT_BOOTSTRAP_TOKEN=__BOOTSTRAP_TOKEN__
+      PANGOLIN_AGENT_DERIVE_KEY=__DERIVE_KEY__
+      PANGOLIN_AGENT_STATE_DIR=/etc/pangolin-agent
+      PANGOLIN_AGENT_SINGBOX_CONFIG=/etc/sing-box/config.json
+      PANGOLIN_AGENT_SINGBOX_UNIT=sing-box
+      PANGOLIN_AGENT_VERSION=__AGENT_VERSION__
+
+runcmd:
+  - |
+    set -euo pipefail
+    mkdir -p /opt/pangolin
+    tmp="$(mktemp)"
+    # 下载安装脚本并按锁定 SHA-256 校验后再执行（拒绝被篡改的脚本）。
+    curl -fsSL --retry 3 "__ARTIFACT_BASE__/install-node.sh" -o "$tmp"
+    echo "__INSTALL_SHA256__  $tmp" | sha256sum -c -
+    install -m 0755 "$tmp" /opt/pangolin/install-node.sh
+    rm -f "$tmp"
+    ARTIFACT_BASE="__ARTIFACT_BASE__" AGENT_VERSION="__AGENT_VERSION__" \
+      bash /opt/pangolin/install-node.sh
+
+# 整机 3–5 分钟内可服务：cloud-init 完成 → agent 首启 Enroll → Register 取全量配置 →
+# 渲染 sing-box config 并 restart sing-box → REALITY/Hy2 入站上线。