From 683d7b745950de97ef6148bc44bc2d13bb6eeac4 Mon Sep 17 00:00:00 2001 From: Codex Agent Date: Thu, 4 Jun 2026 13:46:23 +0800 Subject: [PATCH] docs(v02): record Keycloak deployment baseline --- docs/reference/spec-v02-auth.md | 54 ++++++++++++++++++++++++++++----- 1 file changed, 46 insertions(+), 8 deletions(-) diff --git a/docs/reference/spec-v02-auth.md b/docs/reference/spec-v02-auth.md index 01827fd9..3c55a205 100644 --- a/docs/reference/spec-v02-auth.md +++ b/docs/reference/spec-v02-auth.md @@ -2,7 +2,7 @@ 本文是 HWLAB `v0.2` 登录、认证和应用层鉴权入口的长期规格。它把 Keycloak OIDC、浏览器 Web session、CLI/API/AgentRun 共用的用户 API key 和 HWLAB 内部 `AuthPrincipal` 归一到同一套口径，避免把本地账号密码、浏览器 cookie 和设备专用系统 key 混用。 -基础设施实施跟踪见 [pikasTech/HWLAB#788](https://github.com/pikasTech/HWLAB/issues/788)。用户角色、Code Agent session owner、device pod grant 和资源授权矩阵见 [spec-user-access.md](spec-user-access.md)；本文只定义“如何登录、如何恢复 actor、如何把请求归一成 actor”。 +基础设施实施跟踪见 [pikasTech/HWLAB#788](https://github.com/pikasTech/HWLAB/issues/788)，Keycloak 到 HWLAB 的接入收口见 [pikasTech/HWLAB#814](https://github.com/pikasTech/HWLAB/issues/814)。用户角色、Code Agent session owner、device pod grant 和资源授权矩阵见 [spec-user-access.md](spec-user-access.md)；本文只定义“如何登录、如何恢复 actor、如何把请求归一成 actor”。 ## 设计目标 @@ -47,6 +47,44 @@ https://auth.74-48-78-17.nip.io/realms/hwlab - `hwlab-cloud-api`、`hwlab-cloud-web` 和 CLI 仍保持 v0.2 原入口 `19666/19667`；Keycloak 只新增 auth 域名，不替代 HWLAB Cloud Web。 - Keycloak OIDC client 的 redirect URI 必须指向 `hwlab-cloud-api` callback（当前 v0.2 为 `http://74.48.78.17:19667/auth/oidc/callback`）。`https://auth.74-48-78-17.nip.io` 只作为 Keycloak issuer/authorization host，不能配置成 HWLAB callback 目标。 +## Keycloak 当前部署基线 + +v0.2 的 Keycloak 部署已经具备公网 HTTPS 原生后台管理入口和 `hwlab` realm OIDC issuer。后续 HWLAB 接入工作应把 Keycloak 当成已存在的外部 OIDC provider 消费，不再把 Keycloak 基础部署、Postgres 或 HTTPS 暴露混入 Cloud Web/Cloud API 接入任务。 + +部署拓扑： + +```text +browser + -> https://auth.74-48-78-17.nip.io + -> master Caddy :443 + -> master frps remotePort 28443 + -> G14 keycloak-frpc + -> keycloak.keycloak.svc.cluster.local:8080 +``` + +运行基线： + +- Kubernetes namespace 固定为 `keycloak`，与 `hwlab-v02` 解耦。 +- Keycloak Deployment 使用 `quay.io/keycloak/keycloak:25.0`，Postgres 使用 `postgres:16-alpine`，FRP client 使用 `fatedier/frpc:v0.68.1`。 +- `keycloak` Deployment、`keycloak-frpc` Deployment 和 `keycloak-postgres` StatefulSet 必须 Ready；`keycloak-bootstrap-realm` Job 必须已成功完成。 +- 公网管理入口是 `https://auth.74-48-78-17.nip.io/admin/master/console/`，`/admin/` 可以重定向到该原生 console；不要在 HWLAB Cloud Web 中重做 Keycloak 管理 UI。 +- 公网 issuer 是 `https://auth.74-48-78-17.nip.io/realms/hwlab`，discovery 与 JWKS 必须全部返回 HTTPS URL。 +- Keycloak management 端口 `9000` 不作为公网入口暴露；健康和管理探测留在集群内或受控透传内完成。 +- `hwlab` realm 必须 enabled，并在小范围测试阶段允许 self-registration；新注册用户在 HWLAB 应用层只能默认成为普通 `user`，不自动拥有 device pod grant。 +- `hwlab-cloud-web` client 的 redirect URI 指向 `http://74.48.78.17:19667/auth/oidc/callback`，web origin 指向 `http://74.48.78.17:19666`。 + +管理员凭据边界： + +- `master` realm 的 `admin` 用户只用于 Keycloak 原生后台和自动化 bootstrap，不是 HWLAB 应用管理员账号。 +- Kubernetes Secret `keycloak-admin/password` 是 Keycloak 初始管理员和后续自动化 Job 获取 admin token 的凭据来源；如果人工在 Keycloak UI 里轮换 admin 密码，必须同步更新该 Secret，否则重跑 bootstrap/admin REST Job 会继续使用旧密码并失败。 +- 不要把 admin password、client secret、session token 或完整 API key 写入 issue、长期参考、ConfigMap、日志或 trace。临时取密脚本使用后必须删除。 +- `hwlab-cloud-web-client` Secret 只保存 Keycloak OIDC client secret；Cloud Web 不直接读取它，只有 `hwlab-cloud-api` 在 callback/token exchange 中使用。 + +部署硬化项： + +- Keycloak 当前已能通过公网 HTTPS issuer 和 forwarded headers 正常工作；后续 render 可显式固定 `--hostname=https://auth.74-48-78-17.nip.io` 和必要的 `--hostname-admin`，减少代理链路变化导致的 issuer/callback 歧义。 +- 小范围测试可先使用 bootstrap 创建的 client secret；进入更大范围公网使用前应轮换为随机 secret，并同时更新 Keycloak client 与 `hwlab-cloud-web-client` Secret。 + ## 注册策略 短期小范围测试允许 Keycloak 开启自助注册，并且不要求邮箱或手机校验。该策略只有在以下条件同时满足时成立： @@ -240,13 +278,13 @@ API key 行为： | 规格项 | 状态 | 说明 | | --- | --- | --- | -| Keycloak 独立 namespace 与公网 HTTPS issuer | 目标状态 | 实施跟踪见 #788；短期建议 `auth.74-48-78-17.nip.io` + Caddy/Let's Encrypt + FRP。 | -| Keycloak 自助注册且不强制邮箱/手机验证 | 目标状态 | 只适合小范围测试；默认 `user`、无 device pod grant。 | -| Web OIDC login/callback | 目标状态 | 当前源码仍以 `/auth/login` 本地账号密码为主。 | -| Web session 24 小时轮换 | 目标状态 | 当前 `internal/cloud/access-control.ts` 为 7 天本地 session，后续需改为 24 小时。 | -| CLI/AgentRun `HWLAB_API_KEY` 一等登录 | 目标状态 | 当前 CLI 主要保存 cookie session，AgentRun/device-pod 仍有旧 shared key 口径；目标是统一 env API key 映射到用户，无浏览器跳转，无跨用户 device-pod key。 | -| 默认 API key 自动生成和 Web 可查看 | 目标状态 | 小范围测试允许重复查看明文；生产化再改为 hash-only。 | -| `AuthPrincipal` 归一 | 目标状态 | 后续实现必须把 Web session、CLI API key 和 AgentRun `hwpod` API key 都归一成同一用户 actor。 | +| Keycloak 独立 namespace 与公网 HTTPS issuer | 部署已完成 | `keycloak` namespace、Caddy/FRP HTTPS、`hwlab` issuer、admin console 和 bootstrap Job 已形成部署基线；后续只按本文件继续硬化。 | +| Keycloak 自助注册且不强制邮箱/手机验证 | Keycloak 侧已完成 | 只适合小范围测试；HWLAB 应用层仍必须默认 `user`、无 device pod grant。 | +| Web OIDC login/callback | 待 HWLAB 接入收口 | Keycloak 侧 redirect URI 已配置，Cloud API/Web rollout 和浏览器 callback 验收见 #814。 | +| Web session 24 小时轮换 | 待 HWLAB 接入收口 | 当前目标是 callback 成功后由 `hwlab-cloud-api` 发行 24 小时 `hwlab_session`；验收见 #814。 | +| CLI/AgentRun `HWLAB_API_KEY` 一等登录 | 待 HWLAB 接入收口 | 目标是统一 env API key 映射到用户，无浏览器跳转，无跨用户 device-pod key；验收见 #814。 | +| 默认 API key 自动生成和 Web 可查看 | 待 HWLAB 接入收口 | 小范围测试允许本人重复查看明文；生产化再改为 hash-only。 | +| `AuthPrincipal` 归一 | 待 HWLAB 接入收口 | 后续实现必须把 Web session、CLI API key 和 AgentRun `hwpod` API key 都归一成同一用户 actor。 | | `admin/user` 与 device pod grant 授权 | 部分实现 | 现有 cloud-api 已有本地用户、session、grant 和 Code Agent owner 绑定；资源授权继续按 spec-user-access 收敛。 | ## Keycloak 部署纪律