Codex
127 lines
7.9 KiB
Markdown
127 lines
7.9 KiB
Markdown
# PJ2026-010604 公开入口
|
||
|
||
## 修改历史
|
||
|
||
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|
||
| --- | --- | --- | --- |
|
||
|
||
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
|
||
|
||
## 正文
|
||
|
||
## PJ2026-010604 公开入口需求规格
|
||
|
||
## 1. 文档控制
|
||
|
||
| 字段 | 内容 |
|
||
| --- | --- |
|
||
| 编号 | PJ2026-010604 |
|
||
| 短名 | 公开入口 |
|
||
| 层级 | L2 课题 |
|
||
| 状态 | 已生效 |
|
||
| 需求规格模板 | [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 的边界说明。
|
||
- 公开入口状态、渲染目标、健康探针和失败摘要的受控输出。
|
||
|
||
### 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。 |
|
||
| 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。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。
|
||
|
||
### 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 服务不一致时输出可定位的漂移摘要，使平台管理员能判断问题位于入口投递、目标服务、域名证书还是业务接口。
|
||
|
||
入口漂移处理只说明外部访问链路是否到达正确 runtime，不把 health 200、Caddy reachable 或 FRP connected 升级为 Web、登录、Agent、HWPOD 或 CaseRun 业务通过。
|
||
|
||
## 7. 过程控制
|
||
|
||
本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。
|