Merge pull request #2059 from pikasTech/docs/2058-pikaoa-test-cluster-spec
规范 PikaOA 专用测试集群临时运行路径
This commit is contained in:
Lyon
@@ -89,6 +89,9 @@
|
||||
#### R1.5.8 [in_progress]
|
||||
|
||||
修复 `pikaoa test-target` 临时运行面缺失附件配置与数据库迁移启动链，使 fixture 能渲染当前产品可启动的 namespace-local 后端运行面，保持未声明 target 与 `validationOnly` 全程无远端变更，执行记录见 [pikasTech/unidesk#2053](https://github.com/pikasTech/unidesk/issues/2053)，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.5.8_Task_Report.md)。
|
||||
#### R1.5.9 [in_progress]
|
||||
|
||||
落实用户最新要求：PikaOA 可不经过 CI/CD，由 YAML-first 在专用测试集群启动临时 Kubernetes 做测试和调试；SPEC 分离正式发布与临时测试，登记并验收真实 target，执行记录见 [pikasTech/unidesk#2058](https://github.com/pikasTech/unidesk/issues/2058)，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.5.9_Task_Report.md)。
|
||||
### R1.6
|
||||
|
||||
审核并合并双仓 PR，执行首次受控 PaC bootstrap，由正常 source PR merge 自动发布，依赖 R1.3-R1.5，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.6_Task_Report.md)。
|
||||
|
||||
@@ -8,6 +8,7 @@
|
||||
| v0.2 | 待本版本提交 | 2026-07-14 | 统一平级 REST 资源、UUIDv7 全局标识和仅通过 typed ID 建立对象关联的契约。 |
|
||||
| v0.3 | 待本版本提交 | 2026-07-14 | 将审计语义校验收敛为非阻塞 warning 和最小安全归一化，避免开发期复杂审计门禁阻塞业务。 |
|
||||
| v0.4 | 待本版本提交 | 2026-07-14 | 允许 Web 与后端并行开发，最终以同一公开 HTTP API 和 CLI/Web 等价业务流完成集成验收。 |
|
||||
| v0.5 | 待本版本提交 | 2026-07-14 | 增加不经过 CI/CD 的 YAML-first 专用测试集群临时运行面，并与正式自动交付严格隔离。 |
|
||||
|
||||
修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。
|
||||
|
||||
@@ -82,7 +83,8 @@ PikaOA 终态必须同时具备：
|
||||
- PostgreSQL 是业务数据真相；
|
||||
- 文件内容通过可替换存储端口管理，元数据与哈希进入业务数据；
|
||||
- 配置、Secret、数据库绑定、运行目标和公网暴露均由 owning YAML 管理；
|
||||
- GitHub 合并触发自动 CI/CD、GitOps 和运行面收敛。
|
||||
- 正式发布由 GitHub 合并触发自动 CI/CD、GitOps 和运行面收敛；
|
||||
- 后端测试和调试可以不经过 CI/CD，由 owning YAML 在专用测试集群创建临时 Kubernetes 运行面。
|
||||
- 首版可观测能力：
|
||||
- Web、CLI、API、Worker 和 CI/CD 统一传播 W3C trace context；
|
||||
- Go 服务从第一版接入 OpenTelemetry traces、metrics 和结构化日志关联；
|
||||
@@ -100,6 +102,7 @@ PikaOA 终态必须同时具备：
|
||||
- CLI、Web 工作台、HTTP API、健康接口和异步任务入口。
|
||||
- OpenTelemetry Collector 接入、Prometheus 指标、结构化日志和 trace/metric 关联。
|
||||
- PostgreSQL、Kubernetes namespace、Secret、CI/CD、GitOps 和公网 HTTPS。
|
||||
- 专用测试集群上的 YAML-first 临时后端运行面、临时 PostgreSQL、可观测性和清理入口。
|
||||
|
||||
### 2.4 范围外
|
||||
|
||||
@@ -126,6 +129,7 @@ PikaOA 终态必须同时具备：
|
||||
| Typed ID 关联 | 资源只保存关联对象的资源类型和全局唯一 ID，不复制关联对象私有载荷，也不以嵌套路径或表级从属关系定义资源身份。 |
|
||||
| 模块 | 具有独立领域边界、权限、迁移、API、事件和前端入口的可插拔业务能力。 |
|
||||
| 领域事件 | 模块完成业务事务后写入的结构化事实，用于同进程订阅或异步扩展。 |
|
||||
| 临时测试运行面 | 不经过正式 CI/CD，在 YAML 声明的专用测试集群中按源码提交创建并可完整删除的 API、Worker 与测试依赖集合。 |
|
||||
|
||||
## 4. 系统边界和内部模块
|
||||
|
||||
@@ -281,6 +285,22 @@ sequenceDiagram
|
||||
A-->>W: 展示废弃标识且默认排除有效统计
|
||||
```
|
||||
|
||||
### 5.5 正式发布与临时测试数据流
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
G[GitHub 目标分支合并] --> C[PaC 与 Tekton]
|
||||
C --> A[GitOps 与 Argo]
|
||||
A --> P[正式 PikaOA namespace]
|
||||
Y[config/pikaoa.yaml testRuntime] --> T[pikaoa test-target]
|
||||
T --> K[专用测试集群临时 namespace]
|
||||
K --> D[(临时 PostgreSQL)]
|
||||
K --> O[OTel 与 Prometheus]
|
||||
T --> X[按实例删除临时 namespace]
|
||||
```
|
||||
|
||||
正式发布与临时测试是职责隔离的两条路径。正式发布的 source authority、镜像、数据库、Secret、公网入口和运行 namespace 只由正式交付配置管理。临时测试只消费 owning YAML 明确声明的专用测试 target 和 commit-pinned 镜像，在实例 namespace 内创建 API、Worker、迁移、附件存储和临时 PostgreSQL；它不得读取、修改或清理正式交付对象。
|
||||
|
||||
## 6. 全局原子需求
|
||||
|
||||
### 6.1 PIKAOA-L0-REQ-001 模块化平台内核
|
||||
@@ -400,7 +420,7 @@ Web 必须是高密度、可持续使用的办公工作台。首屏直接显示
|
||||
- 版本历史、废弃标识和甲方分类可直接扫描；
|
||||
- 图标按钮有可访问名称和工具提示。
|
||||
|
||||
### 6.9 PIKAOA-L0-REQ-009 自动交付和配置真相
|
||||
### 6.9 PIKAOA-L0-REQ-009 正式自动交付和配置真相
|
||||
|
||||
PikaOA 必须运行在独立 Kubernetes namespace。目标、namespace、镜像、数据库引用、Secret、资源、探针、持久卷、公网域名和 CI/CD 参数均由 owning YAML 声明；代码只校验和渲染。
|
||||
|
||||
@@ -463,6 +483,27 @@ Prometheus 必须覆盖：
|
||||
|
||||
Web、API、Worker 和 CI/CD 必须输出结构化日志、健康状态和 trace 上下文。源码版本、镜像版本和 API 版本漂移只能形成非阻塞 warning，不得阻塞可安全解释的用户业务。
|
||||
|
||||
### 6.13 PIKAOA-L0-REQ-013 YAML-first 专用测试集群
|
||||
|
||||
PikaOA 后端测试和调试必须支持不经过 PaC、Tekton、GitOps、Argo 或正式 CI/CD 的临时 Kubernetes 运行面。该运行面只能部署到 owning YAML 明确声明的专用测试集群 target；未声明、零匹配或多匹配时，受控入口必须在连接远端前返回 `configured=false` 或 typed blocker，并保持 `mutation=false`。
|
||||
|
||||
测试 target 必须由 owning YAML 声明：
|
||||
|
||||
- 节点、route、namespace 前缀、实例 TTL 和清理策略；
|
||||
- 源码仓库、源码提交和 commit-pinned API、Worker、迁移镜像；
|
||||
- 临时 PostgreSQL、运行 Secret、管理员与普通员工初始凭据来源；
|
||||
- namespace-local 附件存储、健康探针、OTel endpoint 和 Prometheus 抓取；
|
||||
- 正式 namespace 保护集合和对象所有权标签。
|
||||
|
||||
接受标准包括：
|
||||
|
||||
- `plan` 只读渲染目标、实例 namespace、镜像提交、Secret presence、可观测性和保护集合；
|
||||
- `start` 只在显式确认后创建实例 namespace，并在 API 与 Worker ready 前完成数据库迁移；
|
||||
- `status` 返回迁移、API、Worker、PostgreSQL、OTel 和 Prometheus 的有界状态；
|
||||
- `stop` 只删除 target、instance 和 managed-by 标签同时匹配的精确 namespace；
|
||||
- 临时运行面不连接正式 PostgreSQL，不复用正式 Secret，不进入正式公网入口，也不改变正式发布 source authority；
|
||||
- 配置一致性、版本漂移和 OTel exporter 失败只产生 `blocking=false` warning，Secret 缺失或 namespace 所有权不安全仍在 mutation 前失败。
|
||||
|
||||
## 7. API、数据与兼容边界
|
||||
|
||||
- 外部 HTTP API 使用 `/api/v1` 版本前缀。
|
||||
@@ -498,6 +539,8 @@ Web、API、Worker 和 CI/CD 必须输出结构化日志、健康状态和 trace
|
||||
### 8.3 运行验收
|
||||
|
||||
- CI/CD 绑定 source commit、PipelineRun、镜像 digest、GitOps revision、Argo 状态和运行面 ready；
|
||||
- 临时测试通过 YAML 声明的专用测试 target 完成 `plan`、`start`、`status`、CLI 后端业务验证和 `stop`，不触发正式 CI/CD；
|
||||
- 临时测试结束后实例 namespace 已删除，正式 namespace、正式数据库、正式 Secret 和公网入口保持不变；
|
||||
- Web、API 和 Worker 运行在 owning YAML 声明的 namespace；
|
||||
- PostgreSQL 连接、迁移、附件存储和健康检查通过；
|
||||
- OTel Collector 接收 Web/CLI/API/Worker trace，Prometheus 抓取 API/Worker 指标；
|
||||
|
||||
Reference in New Issue
Block a user