# 平台运维

本文件覆盖 Secret、runtime migration、observability、platform infra、CI tools image、PipelineRun 清理和 rollout 补记。

## Secret 管理

```bash
bun scripts/cli.ts hwlab g14 secret status --lane v02 \
  --name hwlab-v02-openfga|hwlab-v02-master-server-admin-api-key

bun scripts/cli.ts hwlab g14 secret ensure --lane v02 \
  --name hwlab-v02-master-server-admin-api-key [--dry-run|--confirm]

bun scripts/cli.ts hwlab g14 secret delete --lane v02 \
  --name <obsolete-secret> [--dry-run|--confirm]

bun scripts/cli.ts agentrun control-plane secret-sync \
  --node <node> --lane <lane> [--secret-id <yaml-secret-id>] \
  [--dry-run|--confirm] [-o json|yaml] [--full|--raw]
```

Secret 只通过 YAML sourceRef/targetKey 和受控 CLI 下发；输出只披露对象名、key 名、presence、fingerprint 和摘要，不打印完整凭据。

- AgentRun `secret-sync --dry-run` 的默认文本、JSON 和 YAML 使用同一个有界投影：
  - 直接展示 YAML Secret ID、目标 Secret/key、source presence/fingerprint；
  - 阻断时展示 activation fence identity、状态、关联 runner/run/command identity 和可执行只读下钻；
  - 所有模式固定 `valuesPrinted=false`。
- `--secret-id <yaml-secret-id>` 是单个声明的稳定下钻；`--full` 与 `--raw` 才请求 exhaustive probe/capture。
- `secret-sync` 是 YAML 声明的配置维护入口，不是 source delivery 或 CI/CD 恢复入口。

## 运行时迁移

```bash
bun scripts/cli.ts hwlab g14 control-plane runtime-migration \
  --lane v02 [--dry-run|--confirm]
```

通过 runtime 容器内 migration CLI 执行迁移。不要用手工 pod shell 或裸数据库命令作为长期入口。

## 可观测性

```bash
bun scripts/cli.ts hwlab g14 observability status|apply|query|targets|boundary|closeout \
  [--lane v02] [--promql <expr>] [--expect-count N] [--expect-value V] [--dry-run|--confirm]
```

管理 G14 Prometheus 基础设施和 HWLAB lane 监控 closeout。状态、耗时、失败原因、trace、命令结果或关键证据不可见时，先补 CLI/日志/状态输出再继续。

## 平台基础设施

```bash
bun scripts/cli.ts platform-infra sub2api plan|apply|status|validate
bun scripts/cli.ts platform-infra sub2api codex-pool plan|sync|validate|expose|configure-local
bun scripts/cli.ts platform-infra gitea status|validate --target JD01
bun scripts/cli.ts platform-infra gitea mirror status --target JD01
bun scripts/cli.ts platform-infra gitea mirror webhook status --target JD01
bun scripts/cli.ts platform-infra pipelines-as-code status|history --target JD01 [--consumer <id>]
bun scripts/cli.ts platform-infra pipelines-as-code help platform-bootstrap
bun scripts/cli.ts platform-infra pipelines-as-code help compatibility-diagnostics
bun scripts/cli.ts platform-infra kafka groups --node <node> [--limit N|--full|--raw]
bun scripts/cli.ts platform-infra kafka groups cleanup --node <node> --policy <yaml-policy-id> [--confirm]
bun scripts/cli.ts platform-infra wechat-archive plan|apply|status|validate|pull
bun scripts/cli.ts platform-infra wechat-archive wcf-host-status|collector-plan|collector-apply|collector-status
```

- `platform-infra` 是 UniDesk 运维的平台基础设施控制面：
  - 新增平台服务优先进入该命名空间或对应 YAML target；
  - 旧 `devops-infra` 只作为渐进迁移来源；
  - 其他平台服务继续遵循各自 owning YAML 与专项 skill。
- Gitea mirror 和 Pipelines-as-Code 的 source-of-truth：
  - 分别为 `config/platform-infra/gitea.yaml` 与 `config/platform-infra/pipelines-as-code.yaml`；
  - migrated consumer 的唯一交付触发是 GitHub PR merge；
  - 默认入口只有 Gitea/PaC status、history 与只读 debug。
- 平台维护入口边界：
  - `closeout` 只在 PaC compatibility diagnostics scope 中保留为只读历史观察；
  - 会 POST hook test 的 `webhook-test` 已删除；
  - `apply` 只属于首次平台 bootstrap，不能补齐 source PR 合并后的交付；
  - 任何读取失败都必须显式报告，不能误报为空表成功。

## CI 工具镜像

```bash
bun scripts/cli.ts hwlab g14 tools-image status
bun scripts/cli.ts hwlab g14 tools-image build \
  --name ci-node-tools --tag <tag> \
  [--dockerfile deploy/ci/hwlab-ci-node-tools.Dockerfile] [--dry-run|--confirm]
```

tools image 构建只在目标 host 和本地 registry 的受控路径中执行，不把 master server 当通用构建机。

## PipelineRun 清理

```bash
bun scripts/cli.ts hwlab g14 control-plane cleanup-runs \
  --lane v02|g14|all [--min-age-minutes N] [--limit N] [--dry-run|--confirm]

bun scripts/cli.ts hwlab nodes control-plane cleanup-runs \
  --node <node> --lane v03 [--min-age-minutes N] [--limit N] [--dry-run|--confirm --wait]

bun scripts/cli.ts hwlab g14 control-plane cleanup-released-pvs \
  --lane all [--limit N] [--dry-run|--confirm]
```

- 清理范围：
  - 只删除已完成 PipelineRun 及其 Tekton TaskRun/Pod/PVC 链路；
  - 不触碰 registry storage、业务 PVC、Secret、runtime workload 或 GitOps desired state。
- 定点清理：
  - 带 `--pipeline-run` 或 `--source-commit` 时必须直接查询目标对象；
  - 对象不存在返回 `target-pipelinerun-not-found`；
  - 对象未完成返回 `target-pipelinerun-not-terminal`。

- 大型 PipelineRun 造成 Kine/SQLite 压力时：
  - cleanup 只属于控制面快速缓解；
  - 长期修复必须消除 renderer 中重复内联的 `taskSpec`，并通过正常 PR 自动事件验收；
  - 根因判定、k3s 紧急恢复和防复发规则见 [incident-recovery.md](incident-recovery.md#tekton-大对象与-kinesqlite-控制面退化)。

## Rollout 记录

```bash
bun scripts/cli.ts hwlab g14 record-rollout --pr <number> --source-commit <sha>
```

用于手动补记 CI/CD 耗时、TaskRun 指标和语义化 changelog 到指挥简报。补记不能替代真实 runtime closeout。