pikastech
160 lines
11 KiB
Markdown
160 lines
11 KiB
Markdown
# PJ2026-010604 公开入口
|
||
|
||
## 修改历史
|
||
|
||
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|
||
| --- | --- | --- | --- |
|
||
|
||
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
|
||
|
||
## 正文
|
||
|
||
## PJ2026-010604 公开入口需求规格
|
||
|
||
## 1. 文档控制
|
||
|
||
| 字段 | 内容 |
|
||
| --- | --- |
|
||
| 编号 | PJ2026-010604 |
|
||
| 短名 | 公开入口 |
|
||
| 层级 | L2 课题 |
|
||
| 状态 | 已生效 |
|
||
| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e |
|
||
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
|
||
| 上级规格 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) |
|
||
| 规格治理索引 | [规格治理](spec-governance.md) |
|
||
|
||
本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 HWLAB 公开入口的稳定使命、范围、术语、系统边界、内部分工和原子需求。
|
||
|
||
## 2. 目的和范围
|
||
|
||
### 2.1 目的
|
||
|
||
公开入口负责把 HWLAB 目标 node/lane 的 Web、API、health 和必要管理入口通过受控 FRP、Caddy、域名、TLS 和 public URL 暴露给用户、内测执行者和自动化验收入口。
|
||
|
||
本课题的目标状态是：正式用户入口来自 YAML 声明和受控状态查询，浏览器、CLI、测试大纲和 issue 复现都使用同一公开入口；实现端口、ClusterIP、node port、历史 FRP 端口和临时域名只作为诊断或迁移对照，不反向成为用户入口真相。
|
||
|
||
### 2.2 范围内
|
||
|
||
- node/lane Web public URL、API public URL、health URL 和 TLS 域名归属。
|
||
- FRP remote port、Caddy route、managed block、DNS/TLS、public health 和入口漂移处理。
|
||
- 同一公开入口下 Web route、API path、health path 的边界说明。
|
||
- 公开入口状态、渲染目标、健康探针和失败摘要的受控输出。
|
||
- Web CaseRun 和 web-probe 验收的入口选择边界：默认使用正式 public URL；本次 D601/v03 端到端验收可由 YAML 显式切换到 internal IP origin。内部端口、旧 lane 和临时转发未被 YAML 选中时只可作为诊断对照。
|
||
|
||
### 2.3 范围外
|
||
|
||
- Web 页面布局、SPA route fallback 和用户交互归 [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)。
|
||
- HTTP API path、JSON envelope、错误语义和同源路由归 [PJ2026-010403 API契约](PJ2026-010403-api-contract.md)。
|
||
- 用户登录、API key、组织和权限归 [用户管理](PJ2026-0105-user-management.md)。
|
||
- Agent、HWPOD、CaseRun 或业务接口的成功标准不由公开入口定义。
|
||
- 具体域名、端口、证书文件、FRP 配置值和 Caddy upstream 数值以 YAML/config 和受控状态为准，不在本规格硬编码。
|
||
|
||
## 3. 术语表
|
||
|
||
| 术语 | 定义 |
|
||
| --- | --- |
|
||
| 公开入口 | 用户或自动化从外部访问 HWLAB 的 Web/API/health 地址集合。 |
|
||
| public URL | YAML 和受控状态查询声明的正式外部 URL。 |
|
||
| internal validation origin | YAML 声明的内网 Web origin，用于受控端到端验收或排障，不替代长期 public URL 真相。 |
|
||
| FRP | 将目标 node/lane 内部服务暴露到公网入口的反向代理通道。 |
|
||
| Caddy managed block | 由受控 CLI 管理的 Caddy 配置片段，只更新所属服务块，不整文件覆盖共享配置。 |
|
||
| public health | 通过公开入口访问的健康检查，证明入口链路到达目标运行面。 |
|
||
| 入口漂移 | 文档、YAML、Caddy、FRP、DNS、TLS 或运行面状态之间的入口目标不一致。 |
|
||
|
||
## 4. 系统边界和接口
|
||
|
||
| 边界项 | 内容 |
|
||
| --- | --- |
|
||
| 外部使用者 | 硬件研发用户、内测用户、平台管理员、Web/CLI 自动化验收任务。 |
|
||
| 外部输入 | node/lane 选择、YAML publicExposure、Web/API 服务声明、health path、domain/TLS/FRP/Caddy 配置请求。 |
|
||
| 受控资源 | FRP client/server 配置、Caddy route、DNS/TLS 目标、public URL、public health 探针和入口状态摘要。 |
|
||
| 外部输出 | Web public URL、API public URL、health URL、入口健康状态、漂移摘要和 redacted 失败原因。 |
|
||
| 用户接口 | 受控平台运维 CLI、HWLAB lane 状态查询、Web/CLI 默认端点解析和 public health。 |
|
||
| 系统边界 | 公开入口负责外部流量到正确 runtime 的连通和可解释状态；不定义 Web 页面、API 业务语义、用户权限或 Agent 执行结果。 |
|
||
|
||
## 5. 内部分工与规格索引
|
||
|
||
| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
| PJ2026-01060401 | URL真相 | 本规格 6.1 | public web/api/health URL、node/lane 归属和旧入口降级 | YAML运维、源码同步 | 客户端、内测说明 |
|
||
| PJ2026-01060402 | 代理投递 | 本规格 6.2 | FRP、Caddy、TLS、DNS 和 managed block 投递 | YAML publicExposure、运行服务 | Web/API 访问 |
|
||
| PJ2026-01060403 | Route边界 | 本规格 6.3 | Web route、API path、health path 和坏端口边界 | Web工作台、API契约 | CLI、Playwright、用户访问 |
|
||
| PJ2026-01060404 | 漂移处理 | 本规格 6.4 | public URL、FRP、Caddy、DNS/TLS、runtime health 不一致时的状态归因 | 运维监控、YAML运维 | 平台管理员、用户反馈分流 |
|
||
|
||
## 6. 原子需求
|
||
|
||
### 6.1 OPS-PUBLIC-REQ-001 公开 URL 真相
|
||
|
||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||
| --- | --- | --- | --- |
|
||
| OPS-PUBLIC-REQ-001 | URL真相 | PJ2026-01060401 URL真相 | [YAML运维](PJ2026-010603-yaml-first-ops.md)、[客户端](PJ2026-0104-client.md) |
|
||
|
||
公开入口应以目标 node/lane 的 YAML 声明和受控状态查询作为 Web、API 和 health public URL 真相，使用户说明、CLI 默认端点、Playwright 验收和 issue 复现不会误用旧端口或其他 lane。
|
||
|
||
FRP remote port、node 内部 service、ClusterIP、pod IP、历史 nip.io 域名和临时 port-forward 只能作为实现细节或诊断入口出现。缺少正式 public URL 时，应返回配置缺口，不得让调用者自动退回旧入口继续验收。
|
||
|
||
### 6.2 OPS-PUBLIC-REQ-002 代理投递
|
||
|
||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||
| --- | --- | --- | --- |
|
||
| OPS-PUBLIC-REQ-002 | 代理投递 | PJ2026-01060402 代理投递 | [YAML运维](PJ2026-010603-yaml-first-ops.md)、[发布流水](PJ2026-010601-controlled-release.md) |
|
||
|
||
公开入口应通过受控 FRP、Caddy、DNS 和 TLS 投递目标 Web/API 服务，使外部流量到达声明的 node/lane runtime。
|
||
|
||
Caddy 更新必须使用受控 managed block 合并，不能用某个服务的渲染结果整文件覆盖共享 Caddyfile。
|
||
|
||
共享边缘应满足以下 authority 与防覆盖要求：
|
||
|
||
- 只有 owning YAML 声明的唯一 merge-driven authority 可以执行 mutation。
|
||
- L1、领域 CLI、任务 worktree 和人工会话只能提交 owning YAML 与执行只读 plan/status。
|
||
- 自动 reconcile 必须串行执行。
|
||
- 自动 reconcile 必须以 installed source commit 和 candidate ancestry 做单调判定。
|
||
- 绝对外部 owning YAML 必须 pin 40 位 Git commit，并从该 commit 读取。
|
||
- 旧提交、分叉提交和乱序交付必须在 mutation 前拒绝。
|
||
- 运行面必须记录 redacted authority、source commit 与 fingerprint provenance。
|
||
- 只读状态必须区分 source commit 一致、installed 为 desired 祖先、
|
||
installed 为 desired 后继、分叉和无法验证。
|
||
- installed 为 desired 祖先且受管配置指纹与 desired 完全一致时，
|
||
应判定配置当前，不应要求无关后继提交强制重写运行面。
|
||
- 候选安装前的硬校验只覆盖 provenance、source ancestry、监听器、
|
||
Compose 与 Caddy 配置有效性，以及继续安装会直接损害共享边缘的条件。
|
||
- 逐站点 DNS 与 public health 属于运行面漂移诊断：
|
||
- 必须输出具名、可下钻且 `blocking=false` 的 warning；
|
||
- 任一站点 DNS 不一致不得阻塞其他站点的候选安装；
|
||
- 不得把全站 DNS 聚合结果重新包装为共享边缘交付门禁。
|
||
|
||
FRP、Caddy 和 TLS 输出只能包含目标、状态、fingerprint、health 和错误摘要，不输出 Secret、token、证书私钥或可复制凭据。
|
||
|
||
### 6.3 OPS-PUBLIC-REQ-003 Route 边界
|
||
|
||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||
| --- | --- | --- | --- |
|
||
| OPS-PUBLIC-REQ-003 | Route边界 | PJ2026-01060403 Route边界 | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md) |
|
||
|
||
公开入口应保持 Web route、API path 和 health path 的边界清楚：Web public URL 承载浏览器页面和 SPA history route，API public URL 承载 JSON API、JSON-RPC 和 health 语义。
|
||
|
||
API/edge 直达入口不需要为页面 route 返回 HTML fallback；Web public 入口需要按 route policy 把 API path 分流到 API 服务。内部 `:6666`/`:6667` 这类实现端口不能作为浏览器验收默认入口；对 Node/undici bad-port 有限制的内部探测应使用 repo-owned probe、curl 或正式 public URL。
|
||
|
||
Web CaseRun 与 web-probe 验收默认从正式 public Web URL 进入，并通过同一 origin 下的 CaseRun、Workbench、HWPOD 和 health path 观察结果。本次 D601/v03 端到端验收允许 YAML 把 selected Web origin 切换到 internal validation origin；切换结果必须在 CLI/web-probe 输出中显示 originMode、YAML source path 和 selected origin 摘要。公开入口可以暴露路由、TLS、Caddy、FRP 和 health 漂移诊断，但不得让 web-probe 退回未声明的内部 service URL、node port、旧 v0.2 runner 地址、D601 SSH、本地 gateway 端口或临时 port-forward 来证明 CaseRun 通过。
|
||
|
||
### 6.4 OPS-PUBLIC-REQ-004 入口漂移处理
|
||
|
||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||
| --- | --- | --- | --- |
|
||
| OPS-PUBLIC-REQ-004 | 漂移处理 | PJ2026-01060404 漂移处理 | [运维监控](PJ2026-010605-observability-monitoring.md)、[客户端](PJ2026-0104-client.md) |
|
||
|
||
公开入口应在 YAML、FRP、Caddy、DNS/TLS、public health 或 runtime 服务不一致时输出可定位的漂移摘要，使平台管理员能判断问题位于入口投递、目标服务、域名证书还是业务接口。
|
||
|
||
逐站点 DNS 或 public health 失败摘要应满足：
|
||
|
||
- 直接给出 YAML site 身份、hostname、health path 或 expected A 与稳定错误码。
|
||
- 单次受控状态查询即可定位失败对象。
|
||
- 不要求调用者组合其他配置读取或临时远端探针。
|
||
|
||
入口漂移处理只说明外部访问链路是否到达正确 runtime，不把 health 200、Caddy reachable 或 FRP connected 升级为 Web、登录、Agent、HWPOD 或 CaseRun 业务通过。
|
||
|
||
## 7. 过程控制
|
||
|
||
本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。
|