docs(v02): record Keycloak deployment baseline
This commit is contained in:
Codex Agent
@@ -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 部署纪律
|
||||
|
||||
Reference in New Issue
Block a user