feat: add Keycloak authentication

README.md

@@ -34,6 +34,9 @@ Agent 服务默认地址为 `http://127.0.0.1:8787`。需要完整对话能力
 
 | 变量 | 默认值 | 说明 |
 | --- | --- | --- |
+| `TJWATER_AUTH_MODE` | `required` | Keycloak 认证模式；本地测试可显式设为 `disabled` |
+| `TJWATER_KEYCLOAK_ISSUER` | 无 | Keycloak Realm issuer，例如 `https://keycloak.example.com/realms/tjwater` |
+| `TJWATER_KEYCLOAK_CLIENT_ID` | `next-tjwater` | Keycloak public client ID |
 | `TJWATER_MAPBOX_ACCESS_TOKEN` | 空 | Mapbox 底图访问令牌 |
 | `TJWATER_MAP_URL` | `https://geoserver.waternetwork.cn/geoserver` | GeoServer 服务地址 |
 | `TJWATER_GEOSERVER_WORKSPACE` | `tjwater` | GeoServer 工作区 |
@@ -43,6 +46,10 @@ Agent 服务默认地址为 `http://127.0.0.1:8787`。需要完整对话能力
 
 `.env.local` 已被 Git 忽略，请勿提交令牌或生产环境配置。
 
+浏览器使用 Keycloak Standard Flow 和 PKCE S256，不需要也不能配置 client secret。生产环境必须提供 Realm issuer；未认证用户会跳转到 Keycloak，同一 Realm 中已有登录会话时会直接完成单点登录。
+
+Keycloak 中的 `next-tjwater` Client 应关闭 Client Authentication，开启 Standard Flow，并关闭 Implicit Flow 与 Direct Access Grants。Valid Redirect URIs 和 Web Origins 只配置实际使用的前端地址。
+
 Agent 请求由浏览器直接访问 `TJWATER_AGENT_API_BASE_URL`，部署环境需要为前端来源配置 CORS。语音播放始终请求同源 `/api/tts/edge`；开发和预览由 Vite 中间件处理，生产镜像会启动仅监听容器回环地址的 Edge TTS 适配器。无需配置 TTS 服务 URL，可选的服务端变量 `EDGE_TTS_VOICE` 用于覆盖默认中文语音。
 
 ## 常用命令