Codex
138 lines
6.2 KiB
Markdown
138 lines
6.2 KiB
Markdown
# PikaOA
|
||
|
||
## 配置真相
|
||
|
||
- PikaOA 平台配置唯一真相是 `config/pikaoa.yaml`。
|
||
- 测试运行面固定使用：
|
||
- Target：`NC01`；
|
||
- route：`NC01:k3s`；
|
||
- namespace：`pikaoa-test`；
|
||
- NodePort：`32080`。
|
||
- 测试 namespace 不根据 commit、instance 或任务动态生成。
|
||
- `pikaoa` 与 `pikaoa-ci` 是正式交付保护 namespace。
|
||
- 测试入口不得渲染、覆盖或删除保护 namespace 中的对象。
|
||
|
||
## 数据库边界
|
||
|
||
- 测试数据库固定使用 PK01 host PostgreSQL。
|
||
- `config/platform-db/postgres-pk01.yaml` 声明独立的：
|
||
- role：`pikaoa_test`；
|
||
- database：`pikaoa_test`；
|
||
- schema：`pikaoa`；
|
||
- `DATABASE_URL` export：`platform-infra/pikaoa-test.env`。
|
||
- `pikaoa-test` namespace 不创建 PostgreSQL StatefulSet、Service 或临时数据库。
|
||
- 数据库生命周期独立于 namespace 和业务 workload。
|
||
- 测试数据清理由 PK01 PostgreSQL 受控入口负责，不依赖删除 namespace。
|
||
|
||
## Secret 初始化
|
||
|
||
- `config/secrets-distribution.yaml` 声明：
|
||
- source：`platform-infra/pikaoa-test.env`；
|
||
- target：`pikaoa-test-nc01`；
|
||
- scope：`pikaoa-test`；
|
||
- Kubernetes Secret：`pikaoa-test-runtime`。
|
||
- `platform-infra/pikaoa-test.env` 必须包含：
|
||
- `DATABASE_URL`；
|
||
- `PIKAOA_SESSION_SECRET`。
|
||
- `DATABASE_URL` 由 `platform-db postgres export-secrets` 写入并保留。
|
||
- `createIfMissing` 只为 `PIKAOA_SESSION_SECRET` 生成值，不覆盖已有 `DATABASE_URL`。
|
||
- 管理员和员工密码继续使用既有 external raw sources：
|
||
- `~/.unidesk/.env/pikaoa-admin-password.txt`；
|
||
- `~/.unidesk/.env/pikaoa-employee-password.txt`。
|
||
- Secret 输出只披露对象、key、presence、fingerprint 和摘要，不读取或打印值。
|
||
|
||
## Test Target CLI
|
||
|
||
- 受控入口是 `bun scripts/cli.ts pikaoa test-target`。
|
||
- `config/pikaoa.yaml#testRuntime` 声明固定 namespace、镜像、PVC、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=<instance-id>`。
|
||
- `stop` 只允许删除同时匹配固定 namespace 和全部所有权标签的运行面。
|
||
- CLI 使用异步任务状态目录记录有界状态和事件，不建立第二数据库、控制器、租约或锁服务。
|
||
|
||
## 初始化顺序
|
||
|
||
1. 使用 `platform-db postgres` 受控入口准备 PK01 `pikaoa_test` role/database，并 export `DATABASE_URL`。
|
||
2. 执行 foundation：
|
||
|
||
```bash
|
||
bun scripts/cli.ts pikaoa test-target start \
|
||
--target NC01 \
|
||
--instance default \
|
||
--step foundation \
|
||
--confirm
|
||
```
|
||
|
||
3. foundation 只创建带所有权标签的固定 `pikaoa-test` Namespace 和附件 PVC，不要求业务 Secret 已存在。
|
||
4. 执行 Secret 下发：
|
||
|
||
```bash
|
||
bun scripts/cli.ts secrets sync \
|
||
--config config/secrets-distribution.yaml \
|
||
--scope pikaoa-test \
|
||
--confirm
|
||
```
|
||
|
||
5. `secrets sync` 按 YAML 声明补齐允许生成的本地来源，并下发 `pikaoa-test-runtime`。
|
||
6. 使用同一 commit 依次执行：
|
||
- `--step init`，仅初始化全新数据库；
|
||
- `--step api`；
|
||
- `--step worker`；
|
||
- `--step web`。
|
||
7. Web 固定通过 `152.53.229.148:32080` 的 NodePort 入口验收。
|
||
|
||
## 单步运行
|
||
|
||
- foundation 不需要 `--commit`，也不检查业务 Secret。
|
||
- init、api、worker、web 和 all 必须显式提供 `--commit`。
|
||
- 每个 `start` 立即返回任务 ID；使用同一 target、instance 和 step 的 `status` 查询终态。
|
||
- request identity 包含：
|
||
- target；
|
||
- instance；
|
||
- 产品 commit；
|
||
- step；
|
||
- 当前 step 的稳定 structural manifest fingerprint。
|
||
- request fingerprint 对 Secret `stringData` 只保留 key 结构和脱敏占位，不包含 Secret 原值。
|
||
- request fingerprint 排除 `pikaoa.unidesk.io/expires-at` 等每次渲染变化的易变字段。
|
||
- 完全相同 request 重复提交只返回已有任务状态，不并行创建第二任务。
|
||
- 不同 request 遇旧任务处于 queued/running 且 worker 存活时返回 `start-instance-conflict`。
|
||
- 不同 request 遇旧任务已 succeeded/failed/canceled，或 queued/running 但 worker 明确缺失时：
|
||
- 原子退役该 step 的旧有界状态目录；
|
||
- 继续使用同一 `target/instance/step` 状态路径提交新任务；
|
||
- `status` 只读取该 step 的最新任务。
|
||
- foundation 也遵循相同规则。
|
||
- foundation 需要显式形成新 request 时，可以：
|
||
- 提供新的 `--commit` 修订标识；
|
||
- 修改 foundation 的稳定 manifest 结构。
|
||
- 不为重跑引入第二状态库、控制器、租约或长期历史存储。
|
||
- initializer、rollout 或运行面查询失败返回具名失败码，不静默进入下一阶段。
|
||
- OTel exporter、配置版本和 commit 对齐漂移只产生 `blocking=false` warning，不恢复 dedicated 门禁。
|
||
|
||
## 交付阶段
|
||
|
||
- `pikaoa-test-nc01` 独立 test CI/CD 复用同一 owning YAML：
|
||
- 产品 `master` 只生成 `.tekton/pikaoa-test-nc01-pac.yaml`；
|
||
- API、Worker、Web 并行构建并以 digest 发布 GitOps；
|
||
- initializer 通过 Argo `PreSync` 在 API、Worker、Web 前初始化全新数据库；
|
||
- 不创建专用测试集群；
|
||
- 不生成动态 namespace；
|
||
- 不创建 namespace-local PostgreSQL；
|
||
- 不把测试 CI/CD 变成生产交付或用户业务的阻塞门禁。
|
||
- GitOps 接管后，手动 `test-target start|stop` mutation 仅用于暂停 Argo 自动同步后的有界调试；禁止 CLI direct-apply 与 Argo 同时写入。
|
||
- 生产 `pikaoa-nc01` 保留 `release` source authority，但当前不 bootstrap、不生成 `.tekton`、不创建 PipelineRun。
|
||
- PR、构建或单测不能替代固定 NodePort 原入口验收。
|
||
|
||
## 本地验证
|
||
|
||
- `config/fixtures/pikaoa-test-target.yaml` 只用于 renderer 和 CLI 测试。
|
||
- fixture target 固定为 `validationOnly=true`，不得连接真实 route。
|
||
- 最小验证包括：
|
||
- `bun --check scripts/src/pikaoa-test-target.ts`；
|
||
- `bun test scripts/src/pikaoa-test-target-async.test.ts`；
|
||
- `bun scripts/cli.ts check --syntax-only`；
|
||
- `pikaoa test-target plan --step foundation`；
|
||
- `git diff --check`。
|