Codex
82 lines
4.1 KiB
Markdown
82 lines
4.1 KiB
Markdown
# PikaOA 开发与测试运行面
|
||
|
||
## 配置真相
|
||
|
||
- PikaOA 平台配置唯一真相是 `config/pikaoa.yaml`。
|
||
- 正式交付与临时测试运行面职责分离：
|
||
- `delivery.targets` 只描述正式 CI/CD、GitOps、运行 namespace、数据库和公网暴露；
|
||
- `testRuntime.targets` 只描述专用测试集群上的临时后端运行面。
|
||
- 禁止把现有节点推断成 PikaOA 专用测试集群。
|
||
- `testRuntime.targets` 为空时表示当前没有获准的测试运行面：
|
||
- `plan` 和 `status` 返回 `configured=false`、`mutation=false`；
|
||
- `start` 和 `stop` 在任何远端调用前失败。
|
||
|
||
## 受控入口
|
||
|
||
```bash
|
||
bun scripts/cli.ts pikaoa test-target plan
|
||
bun scripts/cli.ts pikaoa test-target status
|
||
bun scripts/cli.ts pikaoa test-target start --target <id> --instance <run-id> --commit <sha> --confirm
|
||
bun scripts/cli.ts pikaoa test-target stop --target <id> --instance <run-id> --confirm
|
||
```
|
||
|
||
- `plan` 是本地只读渲染入口，不接受 `--dry-run`。
|
||
- `start` 和 `stop` 只在显式 `--confirm` 后执行。
|
||
- `--config <path>` 可用于 fixture 或本地 override；`validationOnly=true` 的 target 永远不连接 route。
|
||
- 默认输出是紧凑文本；`--output json` 或 `--json` 输出单一 JSON 文档。
|
||
|
||
## 临时运行面
|
||
|
||
- namespace 固定由 YAML `namespacePrefix` 和 CLI `--instance` 组成。
|
||
- namespace、API、Worker、临时 PostgreSQL、Service 和 Secret 都带以下可审计标签：
|
||
- `app.kubernetes.io/managed-by=unidesk-pikaoa-test-target`；
|
||
- `pikaoa.unidesk.io/test-runtime=true`；
|
||
- `pikaoa.unidesk.io/target=<target-id>`；
|
||
- `pikaoa.unidesk.io/instance=<run-id>`。
|
||
- `stop` 删除前重新校验 target、instance 和 managed-by 标签，只删除精确实例 namespace。
|
||
- 正式 namespace 保护集合来自以下 YAML 字段：
|
||
- `delivery.targets.*.namespace`；
|
||
- `delivery.targets.*.ci.namespace`。
|
||
- 测试入口不得渲染或删除保护集合中的任何对象。
|
||
- PostgreSQL 使用 namespace 内的临时存储，namespace 删除后测试数据随之清理。
|
||
- 附件运行参数与 namespace 内的临时 PVC 来自 target YAML：
|
||
- `runtime.attachment.storageRoot` 和 `runtime.attachment.maxBytes` 直接写入严格 runtime YAML；
|
||
- PVC 名称、容量、StorageClass 和 access mode 只从同一 target 声明读取；
|
||
- API 挂载该 PVC，删除临时 namespace 时一并删除 PVC。
|
||
- 空数据库启动固定分为三个受控阶段：
|
||
- 先渲染基础对象并等待 namespace 内 PostgreSQL 就绪；
|
||
- 再使用 `source.images.migration` 和 `migration.command` 运行产品内置 `pikaoa migrate up` Job；
|
||
- 迁移 Job 完成后才创建 API 和 Worker Deployment 并等待 rollout。
|
||
- PostgreSQL、迁移 Job 或业务 Deployment 失败会返回具名失败码，不会静默进入下一阶段。
|
||
- TTL 和清理策略来自 target YAML：
|
||
- TTL 写入 namespace annotation；
|
||
- 当前 `cleanup.mode=delete-namespace`，由显式 `stop` 执行；
|
||
- `cleanup.requireOwnershipLabels=true` 时，删除前必须校验归属标签；
|
||
- 不建立额外控制器或长期状态库。
|
||
|
||
## Secret 与可观测性
|
||
|
||
- Secret 值只从 YAML `sourceRef` 读取并写入目标 Secret。
|
||
- CLI 输出只显示 `sourceRef`、`targetKey`、presence 和 fingerprint，始终保持 `valuesPrinted=false`。
|
||
- Secret 缺失会在连接测试集群前阻塞 `start`。
|
||
- API 和 Worker 从同一 Secret 挂载严格的 PikaOA runtime YAML。
|
||
- OTel endpoint、Prometheus scrape、指标路径和探针全部由 target YAML 声明。
|
||
- 配置一致性、镜像/commit 漂移和 OTel exporter 失败只产生 `blocking=false` warning，不作为 MVP 门禁。
|
||
|
||
## 本地验收
|
||
|
||
`config/fixtures/pikaoa-test-target.yaml` 只用于本地验证：
|
||
|
||
- 证明 namespace、选择器、附件 PVC、迁移 Job、工作负载和 Secret 引用的渲染结果；
|
||
- 证明 TTL、OTel、Prometheus 和正式 namespace 保护；
|
||
- fixture target 固定为 `validationOnly=true`，不得用于真实集群操作。
|
||
|
||
```bash
|
||
bun scripts/cli.ts pikaoa test-target plan \
|
||
--config config/fixtures/pikaoa-test-target.yaml \
|
||
--target TEST01 \
|
||
--instance issue-2046 \
|
||
--commit 0123456789abcdef \
|
||
--output json
|
||
```
|