pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-010604-public-entry.md

PJ2026-010604 公开入口

修改历史

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

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

正文

PJ2026-010604 公开入口需求规格

1. 文档控制

字段	内容
编号	PJ2026-010604
短名	公开入口
层级	L2 课题
状态	已生效
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-0106 平台运维
规格治理索引	规格治理

本文采用 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工作台。
• HTTP API path、JSON envelope、错误语义和同源路由归 PJ2026-010403 API契约。
• 用户登录、API key、组织和权限归 用户管理。
• 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运维、客户端

公开入口应以目标 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运维、发布流水

公开入口应通过受控 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-010403 API契约

公开入口应保持 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 漂移处理	运维监控、客户端

公开入口应在 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 总规格 的 7. 过程控制。