feat: 增加 Sub2API 用户反馈只读追踪
This commit is contained in:
Codex
@@ -164,7 +164,7 @@ PipelineRun 失败或长时间未完成时，先按定点 `control-plane status
|
||||
- `hwlab g14 git-mirror status|apply|sync|flush [--dry-run|--confirm]` 是 `devops-infra` git mirror/relay 的受控维护入口：`apply` 渲染并 server-side apply `devops-infra/git-mirror.yaml`，同时删除遗留 `git-mirror-hwlab-sync` CronJob；`sync` 创建一次性 manual Job，把 GitHub allowlist refs 拉入本地 mirror；`flush` 创建一次性 manual Job，把本地 `v0.2-gitops` 快进推回 GitHub。
|
||||
`status` 返回 read/write URL、last sync/write/flush、本地 ref、GitHub staging ref 和 pending flush 状态，并在 `cache.summary` 给出 `localV02`、`localGitops`、`githubGitops`、`pendingFlush`、`flushNeeded`、`githubInSync` 和下一条受控 `flushCommand`。confirmed `sync` 和 `flush` 默认创建 `.state/jobs/` 异步 job 并立刻返回可查询状态，只有现场同步调试才显式加 `--wait`；mirror 不设置 CronJob。
|
||||
如果 PipelineRun 的 `gitops-promote` 阶段报 git mirror 控制面漂移或 refs 不一致，先执行 `hwlab g14 git-mirror apply --confirm` 重新应用当前 `devops-infra/git-mirror.yaml` hook/ConfigMap，再执行 `hwlab g14 git-mirror sync --confirm --wait` 复核 refs；失败的同名 PipelineRun 只能通过 `hwlab g14 control-plane cleanup-runs --lane <lane> --pipeline-run <name> --confirm` 受控清理后重试，不要用原生 `kubectl delete` 或手工改 mirror hook。修复后仍必须用 `control-plane status --pipeline-run <name>` 和 `git-mirror status` 分别确认 runtime closeout 与 GitHub flush。
|
||||
- `platform-infra sub2api|langbot|n8n|wechat-archive ...` 是 `platform-infra` namespace 内平台公共服务和公共工作流的受控入口；`sub2api` 支持 `plan|apply|status|validate|codex-pool`，`langbot` 和 `n8n` 支持各自 YAML-controlled `plan|apply|status|logs|validate` 等公共服务操作，`wechat-archive` 支持 `plan|apply|status|validate|pull`，用 `config/platform-infra/wechat-archive.yaml` 声明 LangBot/n8n/Baidu Netdisk 归档链路，以及 D601 Windows 隔离 PC 微信 + WeChatFerry host + D601 k3s 只读 collector 的 personal WeChat upstream；collector 必须复用 D601 已有 `platform-infra` namespace，`createNamespace=false`。`--target` 选择运行目标，默认 `G14` 为 active runtime，`D601` 为同一 YAML 控制的 standby predeploy target。镜像版本和 target 边界由 `config/platform-infra/*.yaml` 控制，Codex 上游池、统一 API key Secret、FRP 公网端口和 master `~/.codex` 消费端由 `config/platform-infra/sub2api-codex-pool.yaml` 控制；完整 Sub2API 日常部署、上游增删、FRP 暴露、local Codex 配置、验收和排障步骤统一见 `$unidesk-sub2api`（`.agents/skills/unidesk-sub2api/SKILL.md`）。`docs/reference/platform-infra.md` 保留 namespace、YAML-first、路由、Secret 脱敏、PK01 Caddy+FRP 和探针开发边界。
|
||||
- `platform-infra sub2api|langbot|n8n|wechat-archive ...` 是 `platform-infra` namespace 内平台公共服务和公共工作流的受控入口；`sub2api` 支持 `plan|apply|status|validate|codex-pool`，其中用户反馈一键只读追踪见 `docs/reference/sub2api-user-feedback.md`；`langbot` 和 `n8n` 支持各自 YAML-controlled `plan|apply|status|logs|validate` 等公共服务操作，`wechat-archive` 支持 `plan|apply|status|validate|pull`，用 `config/platform-infra/wechat-archive.yaml` 声明 LangBot/n8n/Baidu Netdisk 归档链路，以及 D601 Windows 隔离 PC 微信 + WeChatFerry host + D601 k3s 只读 collector 的 personal WeChat upstream；collector 必须复用 D601 已有 `platform-infra` namespace，`createNamespace=false`。`--target` 选择运行目标，默认 `G14` 为 active runtime，`D601` 为同一 YAML 控制的 standby predeploy target。镜像版本和 target 边界由 `config/platform-infra/*.yaml` 控制，Codex 上游池、统一 API key Secret、FRP 公网端口和 master `~/.codex` 消费端由 `config/platform-infra/sub2api-codex-pool.yaml` 控制；完整 Sub2API 日常部署、上游增删、FRP 暴露、local Codex 配置、验收和排障步骤统一见 `$unidesk-sub2api`（`.agents/skills/unidesk-sub2api/SKILL.md`）。`docs/reference/platform-infra.md` 保留 namespace、YAML-first、路由、Secret 脱敏、PK01 Caddy+FRP 和探针开发边界。
|
||||
- `platform-infra observability plan|apply|status|validate|trace --target <node>` 是 `platform-infra` 内 OTel Collector 和 Tempo trace backend 的受控入口，`--target` 必须选择 trace 所属运行面节点；具体 trace 查询、噪声压制、Code Agent/AgentRun 排障和“先改进 OTel”的操作面统一见 `$unidesk-otel`（`.agents/skills/unidesk-otel/SKILL.md`）。
|
||||
- `secrets plan|sync|status --config config/secrets-distribution.yaml --scope platform-infra` 是平台服务本地 Secret sourceRef 到 Kubernetes Secret key 的受控下发入口。`plan` 只读展示 sourceRef、必需 key、目标 Secret/key、missingKeys 和 fingerprint；`sync --confirm` 只按 YAML 声明创建允许生成的本地 key 并下发到声明的目标 Secret；`status` 只验证 live Secret key presence。该入口禁止从 live pod 或 Kubernetes Secret 反推密码、API key、JWT secret、n8n encryption key 或 `DATABASE_URL`，输出也不得打印 base64、解码值或远端 raw transcript；即使显式 `--raw` 也只返回脱敏 summary 和 raw omission 标记。LangBot/n8n Secret 轮换和缺 key 修复规则见 `docs/reference/platform-infra.md#secret-distribution-boundary`。
|
||||
- `hwlab g14 observability status|apply|query|targets|boundary|closeout [--lane v02] [--promql <expr>] [--expect-count N] [--expect-value V] [--dry-run|--confirm]` 是 G14 `devops-infra` 共享监控基础设施和 HWLAB v0.2 监控 closeout 的受控入口。`apply` 固定安装 Prometheus Operator `v0.91.0`、Prometheus `v3.12.0`、Prometheus 发现 RBAC、`devops-infra` 内 Prometheus 实例和 ClusterIP query Service，并给被允许发现的 workload namespace 打低风险 label；它不把 Prometheus、Grafana 或 Alertmanager 部署到 `hwlab-v02`，也不接管 HWLAB runtime Deployment/Service。`status` 只读汇总 CRD、operator Deployment、Prometheus CR/pod/service、`hwlab-v02` ServiceMonitor/PrometheusRule 和 bounded `up` 查询；`query` 只通过 Kubernetes service proxy 查询 Prometheus，支持 `--expect-count` / `--expect-value` 输出 `assertion`、bad values 和 missing/extra series；`targets` 汇总 ServiceMonitor/PrometheusRule、metrics sidecar readiness/restart、三层指标值和 `metrics.k8s.io` 当前 CPU/内存资源快照；`boundary` 验证 workload namespace 没有 Prometheus/Alertmanager，并对 `19666/19667` 公网 `/metrics` 做负向验证；`closeout` 聚合平台 ready、scrape reachable、sidecar serving、business health probe、resource snapshot、namespace boundary 和 public metrics exposure 语义结论。长期边界见 `docs/reference/g14-observability-infra.md`。
|
||||
|
||||
@@ -0,0 +1,61 @@
|
||||
# Sub2API 用户反馈只读追踪
|
||||
|
||||
## 入口
|
||||
|
||||
- 按用户邮箱或正整数用户 ID 查询：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts platform-infra sub2api codex-pool feedback \
|
||||
--target PK01 \
|
||||
--user <email-or-id>
|
||||
```
|
||||
|
||||
- 默认窗口为 `30m`；可显式选择 `5m|30m|1h|6h|24h|7d|30d`。
|
||||
- 默认输出 Kubernetes 列表风格紧凑文本；只有显式 `--json` 才输出完整脱敏 JSON。
|
||||
- 请求表固定返回 10 条，并输出 `returned`、`total`、`moreAvailable`、`nextPageToken`；下一页使用 CLI 给出的完整 `Next` 命令，不提供手工 `limit`。
|
||||
- `REQUEST ID INDEX` 输出当前页完整、可复制的 request ID；主表使用页内序号避免重复宽字段。
|
||||
- 按默认表格中的 client request ID 或内部 request ID 下钻：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts platform-infra sub2api codex-pool feedback \
|
||||
--target PK01 \
|
||||
--user <email-or-id> \
|
||||
--request-id <client-or-internal-id>
|
||||
```
|
||||
|
||||
- 稳定游标下一页：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts platform-infra sub2api codex-pool feedback \
|
||||
--target PK01 \
|
||||
--user <email-or-id> \
|
||||
--window 24h \
|
||||
--page-token <nextPageToken>
|
||||
```
|
||||
|
||||
## 证据组合
|
||||
|
||||
- 用户与 API Key：使用 Sub2API 原生 `admin users` 和用户 API Key 列表，输出邮箱、名称、分组与当前并发，不输出 Key 值。
|
||||
- 请求时间线：自动分页读取窗口内全部 `ops requests`，逐项显示相邻请求空窗、模型、状态、耗时、账号和 proxy。
|
||||
- ID 关联：一次读取 `ops system-logs`，在本地关联 client request ID 与内部 request ID；指定 `--request-id` 时披露关联日志。
|
||||
- 实时状态：组合用户、账号和分组并发，区分无入站证据、排队、在途与已完成。
|
||||
- 基础设施：组合账号可用性、账号当前状态、proxy 状态和 Sub2API 组件健康摘要。
|
||||
|
||||
## 归因边界
|
||||
|
||||
- `client-before-submit-or-no-inbound-evidence` 表示窗口内没有 Sub2API 入站记录且实时并发为零，不等价于证明客户端没有尝试调用。
|
||||
- `sub2api-queue` 需要实时等待队列证据；`in-flight` 需要实时并发证据。
|
||||
- `upstream-first-byte-stream`、`proxy-egress` 和 `client-connection` 只根据原生 Ops 日志、账号、proxy 与基础设施证据分类，不执行探针或写操作。
|
||||
- 无足够分层证据时返回 `sub2api-or-upstream-unknown`，禁止扩大结论。
|
||||
|
||||
## 脱敏与只读
|
||||
|
||||
- 入口只调用 GET 类 admin/ops 接口、管理员登录和运行组件健康读取。
|
||||
- 不调用账号测试、探针、调度、取消、清理、更新或其他运行面写接口。
|
||||
- JSON 和文本均不披露 API Key、管理员 token、账号 credentials、proxy 用户名、密码或其他 Secret。
|
||||
- 所有分页由 CLI 自动完成，不提供手工 `limit` 作为输出规避手段。
|
||||
|
||||
## 调用量
|
||||
|
||||
- issue `#2000` 的人工调查包含用户、请求、系统日志、两种 request ID trace、账号、proxy、进程/端口和 journal 共 9 次工具入口。
|
||||
- 本入口将用户侧工具调用收敛为 1 次，减少 8 次，即 `88.9%`；内部只读 API 来源在 JSON `sources` 字段披露。
|
||||
Reference in New Issue
Block a user