mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d269c6b043ba1c38ed40f1764c970f7d1773ac37
pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-01060106-hwlab-dev-production-lanes.md
T
pikastech 63f0f8a46c docs: 限定数据库迁移阻塞范围
2026-07-21 10:13:58 +02:00

11 KiB
Raw Blame History

PJ2026-01060106 HWLAB双环境

修改历史

版本 对应 commit id 更新日期 变更说明

当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。

正文

PJ2026-01060106 HWLAB双环境需求规格

1. 文档控制

字段 内容
编号 PJ2026-01060106
短名 HWLAB双环境
层级 L3 子课题
状态 草稿
实现引用版本 draft-2026-07-14-p0-hwlab-dev-production-lanes
需求规格模板 ISO/IEC/IEEE 29148 需求规格模板
上级规格 PJ2026-010601 发布流水
关联规格 PJ2026-010602 源码同步、PJ2026-010603 YAML运维、PJ2026-010401080313 Workbench实时权威
规格治理索引 规格治理

本文定义 HWLAB 在 NC01 上的 development/production 双环境。所有可调事实由 owning YAML 控制，L2/L3 发布只允许通过受控 plan 和手动 trigger 执行；PR merge/branch update 不得创建 PipelineRun。禁止裸补跑 PipelineRun、手工 Argo sync、运行时 patch 或从集群反解配置。

2. 目的和范围

2.1 目的

把当前 v0.3 固定为开发环境，并建立跟随 release 分支的生产环境。两套环境在发布身份、运行资源、公开入口、数据库数据域和 Kafka consumer identity 上隔离，使开发变更可以持续滚动，同时只有经过开发原入口验证的 commit 才能晋升为生产基线。

2.2 范围内

  • v0.3 development 与 release production 的 source、PaC consumer、Tekton Pipeline、GitOps branch/path、Argo Application、namespace 和 artifact provenance。
  • development 的 NC01 公网 IP HTTP 入口与 production 的 https://hwlab.pikapython.com 入口。
  • 共用 NC01 host PostgreSQL 服务时，两套独立 database、role、Secret consumer 和 migration ledger。
  • 两套独立 Kafka consumer group identity，以及纯 Kafka实时/回放权威不被数据库迁移阻塞的边界。
  • v0.3 到 release 的受控晋升、手动计划发布和原入口验证。

2.3 范围外

  • Web 页面能力和组件重写归客户端规格。
  • AgentRun 自身的发布 lane 和数据库归 AgentRun 专项规格。
  • DNS、Caddy、FRP 和证书服务的通用实现归 YAML运维与公开入口平台；本规格只定义 HWLAB 两个 consumer 的所有权。
  • 从 development 向 production 复制业务数据、Secret value 或用户会话不在本任务范围内。

3. 术语表

术语 定义
development lane source 为 v0.3、保留当前开发 namespace、通过 NC01 公网 IP 空闲 HTTP 端口访问的 HWLAB 环境。
production lane source 为 release、使用独立 production namespace、通过 https://hwlab.pikapython.com 访问的 HWLAB 环境。
晋升 把已在 development 完成原入口验证的精确 commit 纳入 release；分支推进不发布，仍需对 production 单独 plan 和手动 trigger。
数据域隔离 两个环境不共享 PostgreSQL database、role、Secret consumer 或 migration ledger，任何 schema/data mutation 只作用于选中 lane。
入口所有权 owning YAML 中唯一声明某 public origin 的 consumer；同一 host/origin 不得同时归 development 和 production。

4. 架构与数据流

4.1 系统架构

flowchart LR
  V03[HWLAB v0.3] --> DEVPA[development PaC/Pipeline]
  DEVPA --> DEVGIT[development GitOps]
  DEVGIT --> DEVNS[development namespace]
  DEVNS --> DEVHTTP[152.53.229.148:YAML端口]
  DEVNS --> DEVDB[(host PostgreSQL: development database)]

  REL[HWLAB release] --> PRODPA[production PaC/Pipeline]
  PRODPA --> PRODGIT[production GitOps]
  PRODGIT --> PRODNS[production namespace]
  PRODNS --> PRODHTTPS[https://hwlab.pikapython.com]
  PRODNS --> PRODDB[(host PostgreSQL: production database)]

  KAFKA[(Kafka)] -->|development consumer group| DEVNS
  KAFKA -->|production consumer group| PRODNS

4.2 运行数据流

flowchart LR
  AR[agentrun.event.v1] --> MAP[HWLAB mapper]
  MAP --> HE[hwlab.event.v1]
  HE -->|development group| DEVSSE[development live/replay SSE]
  HE -->|production group| PRODSSE[production live/replay SSE]
  DEVSSE --> DEVWEB[development Web]
  PRODSSE --> PRODWEB[production Web]
  DEVWEB -.显式查询.-> DEVDB[(development read model)]
  PRODWEB -.显式查询.-> PRODDB[(production read model)]

Kafka event 是实时与回放 authority。数据库只保存各 lane 的业务数据和派生读模型；任一数据库 schema 缺失不得改变 Kafka direct publish/live/replay 路径，也不得成为 Cloud API 启动或自动滚动前置。

4.3 晋升与手动发布时序

sequenceDiagram
  participant D as v0.3
  participant DC as development CI/CD
  participant DV as development 原入口验证
  participant R as release
  participant PC as production CI/CD
  participant PV as production 原入口验证
  D->>DC: merge/update commit C，不触发发布
  DC->>DC: plan C，审阅 env reuse 与构建范围
  DC->>DV: 手动 trigger C，构建、GitOps、rollout
  DV-->>D: C 验证通过
  D->>R: 受控晋升精确 commit C
  R->>PC: branch update，不触发发布
  PC->>PC: plan C，审阅 env reuse 与构建范围
  PC->>PV: 获得当次授权后手动 trigger C
  PV-->>R: digest/source/runtime/入口证据

初始 release 分支只能从完成 P0 纯 Kafka纠偏并在 development 原入口验证通过的 v0.3 commit 创建。不得从已知强制 PostgreSQL transactional projector 的事故 commit 创建，也不得绕过 plan 和受控 trigger，用裸 PipelineRun 或 runtime patch 填补发布链。

5. 配置与隔离

5.1 YAML-first 配置

owning YAML 至少声明：

  • lane id、source repository/branch、PaC consumer、Pipeline、GitOps branch/path、Argo Application 和 namespace。
  • public exposure 的 scheme、host、port、target service、health path、Caddy/FRP managed block 引用。
  • PostgreSQL host service reference、database、role、Secret sourceRef/targetKey、migration ledger identity。
  • Kafka bootstrap SecretRef、topic contract、consumer group identity 和 replay retention/cursor 配置。
  • artifact repository、image name、digest provenance 和 source commit label。

代码只校验和渲染 YAML，不内置 development/production 特例，不从现有 Deployment、Secret、Ingress、Caddy 或数据库反解事实。Secret 输出只允许 presence、object/key、fingerprint 和脱敏摘要。

5.2 公开入口

  • development 正式入口是 http://152.53.229.148:<development.publicExposure.port>；实施任务应探测空闲端口并把最终值固化到 owning YAML。
  • production 正式入口固定为 https://hwlab.pikapython.com，由 production publicExposure 独占。
  • development 必须删除 hwlab.pikapython.com 的 route、probe、CORS/origin 和 managed block 所有权；Web/API/health 使用同源 development 入口。
  • production 证书、Caddy/FRP route 和 health probe 由 YAML 渲染，禁止手改共享配置文件。

5.3 PostgreSQL 与 Kafka 隔离

  • 两个 lane 可以复用同一 NC01 host PostgreSQL 服务进程，但必须使用不同 database、role、Secret consumer 和 migration ledger。
  • migration 命令必须显式选中 lane，只能迁移其 database；禁止用共享 DSN、共享 schema 或默认 database 回退。
  • migration 执行边界：
    • lane 自有 schema migration 可以作为 owning workload 的 init 阶段执行；
    • 禁止使用会在 migration 失败时停止整个 Argo Application 资源应用的 Sync hook；
    • migration 失败只能使依赖该 schema 的组件保持未就绪；
    • 失败状态必须保留具名组件、lane 和失败阶段，不能阻止同一 lane 的无关服务滚动。
  • production 初始化不复制 development 会话、用户业务数据或 migration history；需要数据导入时必须另立受控任务。
  • development 与 production 使用不同 Kafka consumer group identity。运行状态和 lag 必须带 lane 标签，禁止同名 group 导致 offset 互相推进。
  • 数据库、Kafka 或 schema warning 不得触发功能关闭、authority 切换、HTTP fallback 或阻塞其他 lane 滚动上线。

6. 原子需求

6.1 HWLAB-LANE-REQ-001 Development迁移

v0.3 的受控手动发布链必须部署到 development namespace，并迁移到 YAML 声明的 NC01 公网 IP HTTP 入口。迁移完成后 https://hwlab.pikapython.com 只指向 production，不再路由到 development。

6.2 HWLAB-LANE-REQ-002 Production手动发布链

release 必须拥有独立 PaC consumer、Tekton Pipeline/ServiceAccount、GitOps branch/path、Argo Application、namespace、image provenance 和 release status。release update 不得触发完整链；获得当次 L3 授权后，发布人员必须先审阅精确 commit 的 plan，再用受控 trigger 发布，禁止裸补跑。

6.3 HWLAB-LANE-REQ-003 Source与制品对齐

每个 lane 的 PipelineRun、GitOps desired state、runtime image digest 和 workload label 必须能关联同一 source commit。缺失或不一致必须可见，但微服务契约、版本或 schema 检查只输出 warning，不得阻塞业务和滚动上线。

6.4 HWLAB-LANE-REQ-004 数据边界

任一 lane 的应用、migration、Secret 和管理命令不得连接另一 lane 的 database/role。验收必须证明两个环境写入的 canary 数据、migration ledger 和 consumer group offset 互不出现于对方数据域。

6.5 HWLAB-LANE-REQ-005 原入口验收

原入口验收要求如下：

  • development 从新的公网 IP HTTP 入口完成 Web、API、health 和至少一次实时/回放 SSE 验收。
  • production 从 https://hwlab.pikapython.com 完成同样验收。
  • production 同时核对 source commit、image digest、namespace、database identity 和 Kafka consumer group。
  • 源码测试、PipelineRun 成功或 Argo Synced 不能单独替代原入口通过。

7. 过程控制

  • 父任务由 pikasTech/unidesk#2008 跟踪。
  • development 入口迁移由 pikasTech/unidesk#2009 和 MDTODO R7.1 跟踪。
  • production release lane 由 pikasTech/unidesk#2010 和 MDTODO R7.2 跟踪。
  • 两个实施任务可以在独立 worktree 并行；共享 YAML/publicExposure 基线的合并和上线顺序由主代理审核。
  • production 实现可以先准备，但 release 分支创建、生产部署和公网切换必须等待 P0 纯 Kafka纠偏在 development 验证完成。
Reference in New Issue View Git Blame Copy Permalink