Files

T

Lyon 48e3d24ad6 fix: converge v02 authorization on OpenFGA (#899 )

Co-authored-by: Codex Agent <codex@hwlab.local>

2026-06-05 11:11:15 +08:00

15 KiB

Raw Blame History

v0.2 微服务总体规格

本文是 HWLAB v0.2 微服务总体规格和服务规格索引。它定义组件取舍、依赖方向、语言迁移边界、裁撤口径和单服务 spec 入口；单个服务的 API、测试规格和实现状态以对应 docs/reference/spec-*.md 为准。

docs/reference/spec-*.md 是微服务、稳定外部服务、短连接 CLI 和系统能力的权威出处；代码开发和测试代码编写必须先对齐对应 spec，再修改实现或测试。

细节权威出处：

用户、权限、session 归属和 device pod relation：见 spec-user-access.md。
OpenFGA 细粒度授权、Admin Access 管理页和同路径 CLI：见 spec-v02-openfga-authorization.md。
device pod profile authority、REST/job 和 gateway 执行边界：见 spec-device-pod.md。
v0.2 branch、namespace、GitOps、FRP、SecretRef 和发布验收：见 spec-v02-cicd.md。
Code Agent provider 真实聊天验收：见 code-agent-chat-readiness.md。
G14 GitOps、Tekton、Argo CD、registry 和外部稳定中间件边界：见 g14-gitops-cicd.md。
保留服务、稳定外部服务和短连接 CLI 的单项 spec：见本文“服务总表”。

在系统中的职责划分

hwlab-v02 是独立 runtime namespace，公网只暴露 19666/19667。浏览器进入 hwlab-cloud-web，API、agent、device 和 gateway 请求收敛到 hwlab-cloud-api，内部硬件与 agent 能力由专门服务承接，稳定外部服务只提供数据库、模型桥、provider 通道和 FRP 入口。

hwlab-cloud-api 是 v0.2 应用层 authority：用户身份、admin/user、Code Agent session owner、OpenFGA relation、profile authority 和用户态 REST 都在这里判定。
OpenFGA 是 hwlab-v02 内部稳定授权服务，只作为 cloud-api 的 PDP/relationship store；Keycloak、Cloud Web、CLI、AgentRun runner 和普通用户都不能直接调用 OpenFGA。
hwlab-cloud-web 只作为用户入口和 API proxy，不拥有业务 authority；CLI 可以旁路 UI，但不能旁路 cloud-api 的授权。
hwlab-device-pod 是正式设备业务承载点；用户态请求必须走 cloud-api -> hwlab-device-pod -> hwlab-gateway -> device-host-cli -> hardware。
Code Agent session 归属、鉴权、trace 和用户态 API 收敛在 hwlab-cloud-api；执行调度接入 AgentRun v0.1 共享基础设施。hwlab-agent-mgr、hwlab-agent-worker 和 repo-owned codex-stdio supervisor 不是 v0.2 runtime service matrix，不再生成 Deployment、Job template、Service、artifact 或 GitOps desired state。
hwlab-gateway 是 transport，不理解用户权限、不保存 profile authority；用户端已经验证稳定，v0.2 第一阶段先不改造它。
Code Agent provider 通道分为 codex-api loopback forwarder 和 deepseek bridge/Moon Bridge；自研 bridge/forwarder 属于 HWLAB 常驻服务，Moon Bridge 和 hyueapi/DeepSeek upstream 是稳定外部依赖。
hwlab-router、hwlab-tunnel-client、hwlab-gateway-simu、hwlab-box-simu、hwlab-patch-panel 在 v0.2 裁撤；不再为这些裁撤对象保留单独规格文档。
hwlab-cli 是固定 repo 内短连接业务 client，不是镜像、常驻服务或 Job template；一次性脚本、render/publish/smoke helper、vendored 前端库和稳定外部服务不纳入 Bun + TypeScript 常驻服务迁移范围，短连接 CLI 自身按 spec-v02-hwlab-cli.md 使用 Bun + TypeScript。

内部架构

v0.2 的主要请求链路按以下方向收敛：

browser
-> hwlab-cloud-web
-> hwlab-edge-proxy
-> hwlab-cloud-api
-> Postgres

cloud-web or device-pod-cli or code agent tool
-> hwlab-cloud-api
-> hwlab-device-pod
-> hwlab-gateway
-> device-host-cli
-> Keil / pyOCD / UART / target

hwlab-cloud-api
-> OpenFGA
-> Postgres

hwlab-cloud-api
-> codex-api profile
-> hwlab-codex-api-responses-forwarder
-> hyueapi upstream

hwlab-cloud-api
-> deepseek profile
-> hwlab-deepseek-responses-bridge
-> Moon Bridge
-> DeepSeek upstream

origin/v0.2
-> G14 Tekton / BuildKit / registry
-> v0.2-gitops
-> Argo CD
-> hwlab-v02 namespace
-> 19666 / 19667

这些链路只表达总体依赖方向。接口、鉴权、SecretRef、health、job、profile 和 provider 行为以对应规格文档为准。

API 接口说明

接口类别	入口	权威规格
浏览器工作台	`http://74.48.78.17:19666/`	spec-v02-hwlab-cloud-web.md
API/live 公网入口	`http://74.48.78.17:19667/health/live` 和同源 API	spec-v02-hwlab-edge-proxy.md、spec-v02-hwlab-cloud-api.md
用户、session、授权	`/auth/`、`/v1/admin/`、`/v1/agent/chat*`	spec-user-access.md、spec-v02-hwlab-cloud-api.md
OpenFGA 授权管理	`/v1/admin/access*`、`hwlab-cli client access ...`、Cloud Web Access 页面	spec-v02-openfga-authorization.md
Device Pod	`/v1/device-pods*`、正式 job/admin API	spec-device-pod.md、spec-v02-hwlab-device-pod-service.md
Gateway transport	`cloud-api /v1/gateway/poll`、`/v1/gateway/result`、gateway `/status`	spec-v02-hwlab-gateway.md
Code Agent provider	`deepseek` 和 `codex-api` provider profile	spec-v02-deepseek-proxy.md、spec-v02-codex-api-forwarder.md
Code Agent AgentRun 调度	`hwlab-cloud-api` 会话 owner/auth/trace -> AgentRun v0.1 dispatch	agentrun-code-agent-dispatch.md、spec-v02-hwlab-agent-skills.md
短连接 CLI	`G14:/root/hwlab-v02` 内直接运行 `hwlab-cli client ...`	spec-v02-hwlab-cli.md
Durable runtime store	Postgres TCP `5432` and cloud-api DB readiness	spec-v02-postgres.md
公网 FRP	master `frps` + `hwlab-v02-frpc` TCP `19666/19667`	spec-v02-frpc.md
CI/CD 控制	render、Tekton、GitOps、Argo、runtime health	spec-v02-cicd.md

服务级 HTTP、CLI、Job 或 TCP 接口以各服务 spec 为准。用户态入口只走 19666/19667，内部服务只通过 ClusterIP 或 Job 模板调用，稳定外部服务只暴露最小必要协议，不向普通用户开放 Kubernetes、Secret、Service 直连或 provider 凭据。

服务总表

对象	类型	v0.2 处理	Bun + TS	细节出处
`hwlab-cloud-api`	HWLAB 自研常驻服务	保留并核心化	是，P0	spec-v02-hwlab-cloud-api.md、spec-user-access.md、spec-device-pod.md
`hwlab-cloud-web` runtime wrapper	HWLAB 自研常驻 web/proxy wrapper	保留	是，P0	spec-v02-hwlab-cloud-web.md、cloud-workbench.md
`hwlab-edge-proxy`	HWLAB 自研常驻服务	保留	是，P0	spec-v02-hwlab-edge-proxy.md
`hwlab-device-pod`	HWLAB 自研常驻服务	保留并增强	是，P0	spec-v02-hwlab-device-pod-service.md、spec-device-pod.md
`hwlab-codex-api-responses-forwarder`	HWLAB 自研常驻 sidecar	保留	是，P1	spec-v02-codex-api-forwarder.md
`hwlab-deepseek-responses-bridge` / `hwlab-deepseek-proxy`	HWLAB 自研 bridge + Moon Bridge 外部依赖	保留	是，P1 for bridge	spec-v02-deepseek-proxy.md
AgentRun v0.1 runner	共享 Agent 执行基础设施	作为外部基础设施接入，不进 HWLAB service/artifact matrix	否	agentrun-code-agent-dispatch.md
`hwlab-agent-skills` wrapper	HWLAB 自研 bundle/health wrapper	保留	仅常驻 wrapper 需要，P2	spec-v02-hwlab-agent-skills.md
`hwlab-gateway`	HWLAB 自研用户端/硬件 transport	保留	暂不迁	spec-v02-hwlab-gateway.md、gateway-outbound-demo.md
v0.2 Observability Monitoring	应用侧监控声明	保留为业务接入能力，不进 runtime service inventory	否	spec-v02-observability-monitoring.md
`hwlab-router`	HWLAB 自研路由占位服务	裁撤	否	本文即裁撤权威，不保留单独 spec
`hwlab-tunnel-client`	HWLAB 自研 tunnel 状态占位服务	裁撤	否	本文即裁撤权威，不保留单独 spec
`hwlab-gateway-simu`	HWLAB 自研模拟服务	裁撤	否	本文即裁撤权威，不保留单独 spec
`hwlab-box-simu`	HWLAB 自研模拟服务	裁撤	否	本文即裁撤权威，不保留单独 spec
`hwlab-patch-panel`	HWLAB 自研接线盘服务	裁撤	否	本文即裁撤权威，不保留单独 spec
`hwlab-cli`	固定 repo 短连接 client	保留为 WEB 等价非视觉业务入口，不进 runtime service inventory	是，CLI 自身	spec-v02-hwlab-cli.md
`device-pod-cli`	CLI 工具	保留并改 REST 调用	否	spec-device-pod.md
render/publish/smoke scripts	一次性脚本	保留现状	否	spec-v02-cicd.md、g14-gitops-cicd.md
browser-side Cloud Web JS	HWLAB 自研前端浏览器代码	保留并 TS 化	是，P0	spec-v02-hwlab-cloud-web.md、cloud-workbench.md
Moon Bridge	外部稳定服务	保留	否	spec-v02-deepseek-proxy.md
`frpc` / `frps`	外部稳定服务	保留	否	spec-v02-frpc.md
Postgres	外部稳定服务	保留	否	spec-v02-postgres.md
OpenFGA	外部稳定服务 / 内部授权 PDP	新增并保留，ClusterIP-only	否	spec-v02-openfga-authorization.md
Argo CD / Tekton / BuildKit / registry	外部稳定服务	保留	否	spec-v02-cicd.md、g14-gitops-cicd.md
Codex CLI	外部工具/runtime	保留	否	code-agent-chat-readiness.md
Keil / pyOCD / UART 工具	外部或主机侧工具	保留	否	spec-device-pod.md

语言迁移边界

v0.2 服务语言统一约束 HWLAB 仓库内自研、会以 Deployment、sidecar 或长期进程运行的 JavaScript 服务代码，同时约束 HWLAB 自研 Cloud Web 浏览器端代码。稳定外部服务、外部镜像、第三方二进制、CLI、一次性脚本、测试脚本、GitOps/render/publish helper 和 vendored 代码不纳入迁移范围。

迁移目标：

自研常驻服务入口使用 Bun + TypeScript。
自研前端浏览器代码使用 TypeScript 并进入前端 build/typecheck 链路；低频 UI 分支不能只依赖浏览器运行时发现语法错误。
Bun 负责运行 .ts；发布前必须通过 TypeScript 类型检查，不能只依赖 Bun 运行时转译。
镜像构建和 CI 原语校验必须包含 tsc --noEmit 或等价 bun run typecheck。
每个 .ts 文件不超过 2000 行；超过必须先拆模块，再迁移或继续开发。
一个服务迁移完成后，不长期保留 .mjs 和 .ts 双入口兼容；runtime command、health check、artifact inventory 和 GitOps render 必须收敛到单一入口。

第一阶段迁移集合：

hwlab-cloud-api
hwlab-cloud-web runtime wrapper
hwlab-edge-proxy
hwlab-device-pod
hwlab-codex-api-responses-forwarder
hwlab-deepseek-responses-bridge
browser-side Cloud Web JS

后续迁移集合：

hwlab-agent-skills wrapper

暂不迁移集合：

hwlab-gateway
device-pod-cli
scripts and tools
stable external services

裁撤集合：

hwlab-router
hwlab-tunnel-client
hwlab-gateway-simu
hwlab-box-simu
hwlab-patch-panel
hwlab-agent-mgr
hwlab-agent-worker

裁撤集合不再新增单服务 spec。若历史文档仍提到这些服务作为 v0.2 必需依赖，应删除旧口径或交叉引用本文。

测试规格

T1

阅读 docs/reference/spec-v02-services.md，然后用 cli 手动测试以下内容：列出 docs/reference/spec-*.md，确认 AGENTS.md 的“规格”部分索引了全部 spec，且没有 hwlab-router、hwlab-tunnel-client、hwlab-gateway-simu、hwlab-box-simu 或 hwlab-patch-panel 的单服务 spec 入口。

T2

阅读 docs/reference/spec-v02-services.md，然后用 cli 手动测试以下内容：从 deploy/gitops/g14/runtime-v02 读取 Deployment、StatefulSet、Service 和 Job 模板，确认每个保留服务和稳定外部服务都有对应 spec；确认 hwlab-router、hwlab-tunnel-client、hwlab-gateway-simu、hwlab-box-simu 和 hwlab-patch-panel 不再出现在 v0.2 runtime desired state 或 v0.2 artifact catalog 中。

T3

阅读 docs/reference/spec-v02-services.md，然后用 cli 手动测试以下内容：检查自研常驻服务和 browser-side Cloud Web JS 是否被列入 Bun + TypeScript 迁移集合，确认 CLI、一次性脚本、vendored 代码和稳定外部服务不被误纳入迁移范围。

T4

阅读 docs/reference/spec-v02-services.md，然后用 cli 手动测试以下内容：逐个检查 docs/reference/spec-*.md 是否包含“在系统中的职责划分”“内部架构”“API 接口说明”“测试规格”“规格的实现情况”五个部分。

规格的实现情况

规格项	状态	说明
v0.2 总体依赖方向	已实现	本文定义浏览器、API、device、provider 和 CI/CD 链路。
保留服务均有 spec	已实现	本文服务总表列出当前保留服务和 spec 文件。
稳定外部服务纳入 spec	已实现	Postgres、Codex API forwarder/hyueapi、DeepSeek/Moon Bridge、FRP 已独立成文或交叉引用权威规格。
OpenFGA 授权服务纳入 spec	目标状态	需要按 spec-v02-openfga-authorization.md 完成 GitOps、cloud-api、WebUI 和 CLI。
`simu`、接线盘、router、tunnel-client 裁撤	已实现	本文记录裁撤口径；v0.2 render、artifact catalog、Tekton build service set 和 cloud-api 运行时 env 不再包含裁撤对象。
Bun + TypeScript 迁移边界	已实现	本文区分第一阶段、后续、暂不迁移和裁撤集合。
spec 作为开发和测试权威	已实现	AGENTS.md 规格区提供顶级索引。

15 KiB Raw Blame History Unescape Escape