门禁兼容修复

2026-09-05 17:36:23 +08:00
1 parent f60b416949
commit 801c0af692
@@ -112,6 +112,9 @@ FIRE_SAFETY_SUPERAGENT_OPEN_API_KEY=<superagent-open-api-key>

 FIRE_SAFETY_CHAT_ENABLED=true
 FIRE_SAFETY_CHAT_AUTH_TOKEN=<独立的高熵xtoken>
+# 新环境必须保持 false；仅当已交付旧客户端的短凭证无法立即更换时，
+# 才能在受控测试/迁移窗口临时设置 true，轮换后恢复 false。
+FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=false
 FIRE_SAFETY_CHAT_SUBJECT_ID=fire-safety-ymd-chat-test-subject
 FIRE_SAFETY_CHAT_COMPAT_APP_ID=<与Nginx路径完全一致的公开app-id>
 # 仅浏览器实际 Origin；CLI/服务端调用可以留空
@@ -131,11 +134,13 @@ FIRE_SAFETY_POSTGIS_EXPECTED_SRID=4326
 注意：

 - FIRE_SAFETY_CHAT_AUTH_TOKEN 只用于兼容对话入口的 xtoken；FIRE_SAFETY_MCP_AUTH_TOKEN 只用于 SuperAgent 调用 /mcp；FIRE_SAFETY_SUPERAGENT_OPEN_API_KEY 只用于 Go 服务访问 SuperAgent。三者必须不同。
+- Chat Token 默认至少 32 个可打印 ASCII 字符。如果已交付的旧客户端凭证较短且无法立即更换，只能临时设置 `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=true`；此时仍要求 Token 非空、不超过 4096 字节，并且每个字符都在 ASCII `0x21-0x7e` 范围内（无空格、控制字符或 Unicode）。该开关只影响 Chat 原生 Bearer 和兼容 `xtoken`，不放宽 MCP Token 至少 32 个可打印 ASCII 字符的要求。新环境不得开启，凭证轮换完成后必须恢复 `false`；开关启用时启动日志会记录不含 Secret 的安全 warning。
 - FIRE_SAFETY_CHAT_COMPAT_APP_ID 是公开路径标识，不是 Secret；它必须与 Nginx 的精确 location = /api/v1/apps/<app-id>/completion 完全一致。
 - 使用 FIRE_SAFETY_MCP_SCOPE_MODE=all 时，FIRE_SAFETY_MCP_ALLOWED_TOWNS 必须保持为空。all 是服务账号级的固定查询表范围，不是最终用户级授权。
 - FIRE_SAFETY_POSTGIS_MIGRATION_DSN 不应配置给运行服务；迁移凭证只供一次性迁移命令使用，完成后应移除。
 - FIRE_SAFETY_HTTP_ADDR 在容器内应为 :8080，安全边界由 Compose 的 127.0.0.1:16587:8080 和宿主机 Nginx 提供；不要在 Compose 场景设为容器内的 127.0.0.1:8080。
 - 不要用没有 --quiet 的 docker compose config 或 docker inspect 把完整环境渲染到终端、CI 日志或工单；检查 .env 权限仍为 600。
+- 修改 `.env` 后必须重新创建容器（例如 `docker compose up -d --force-recreate --no-build`）才能加载新的 Chat 兼容开关；单独 `docker compose restart` 不会重新读取容器环境。旧短凭证仅用于受控测试/迁移，完成轮换后把开关改回 `false` 并再次 recreate。

 ## 4. 容器访问现有 PostgreSQL/PostGIS

@@ -402,6 +407,7 @@ docker compose down
 - 目标机 Compose 配置校验、build、up、健康检查和无 Secret 的有限日志结果。
 - 目标机 nginx -t 和 reload 成功；443 证书、DNS、安全组及旧 location / 已确认不再生效。
 - Chat 首轮/多轮 SSE、错误凭证、未知 app/path 的实际 HTTPS 响应。
+- 若为已交付旧客户端临时开启 Chat legacy 短凭证兼容，应记录受控迁移窗口，确认启动 warning 不含 Secret，并在凭证轮换后恢复 `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=false`。
 - SuperAgent -> /mcp 的独立 Bearer、TLS/网络白名单、工具发现和至少一个受控只读工具调用。
 - 数据库未公开 5432，运行账号保持只读，PostGIS readiness warning 和 35 条无效面几何缺口已记录。

@@ -55,7 +55,10 @@ FIRE_SAFETY_SUPERAGENT_BASE_URL=https://<superagent-domain>
 FIRE_SAFETY_SUPERAGENT_OPEN_API_KEY=<superagent-open-api-key>

 FIRE_SAFETY_CHAT_ENABLED=true
-FIRE_SAFETY_CHAT_AUTH_TOKEN=<chat-xtoken-at-least-32-printable-ascii-characters>
+FIRE_SAFETY_CHAT_AUTH_TOKEN=<chat-xtoken>
+# Keep false for new environments. Only set true in a controlled migration
+# when an already-issued legacy Chat credential is shorter than 32 characters.
+FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=false
 FIRE_SAFETY_CHAT_COMPAT_APP_ID=<same-safe-app-id-as-nginx-location>

 FIRE_SAFETY_MCP_ENABLED=true
@@ -67,9 +70,11 @@ FIRE_SAFETY_POSTGIS_DSN=<readonly-postgresql-dsn>
 当前仍是受控联调静态门禁：

 - `FIRE_SAFETY_CHAT_AUTH_TOKEN` 由用户请求的 `xtoken` Header 携带，必须与 SuperAgent Open API Key、MCP Token 使用不同值。
+- 默认要求 Chat Token 至少 32 个可打印 ASCII 字符；若已交付的旧客户端短凭证无法立即更换，只能在 Go 服务环境中显式设置 `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=true` 做受控测试/迁移。无论开关如何，Token 都必须非空、不超过 4096 字节，并且只含 ASCII `0x21-0x7e`（无空格、控制字符或 Unicode）；轮换完成后恢复 `false`，新环境不得开启。该开关同时适用于原生 Bearer 和兼容 `xtoken`，不放宽 MCP Token 的至少 32 字符门禁。
 - `FIRE_SAFETY_MCP_AUTH_TOKEN` 只用于 SuperAgent -> Go `/mcp`，不应复用 Chat Token。
 - Chat、SuperAgent、MCP 和 PostGIS 的完整配置校验以 `.env.example` 和对应项目文档为准。
 - 浏览器会看到 `xtoken`；它不能代表最终用户身份、角色、租户或数据授权。公网真实用户入口仍需身份提供方、动态授权、限流、Secret 轮换和持久审计。
+- Nginx 不读取、比较或存储 Chat Token，也不需要为 legacy 开关增加配置；请求 Header 原样转发给 Go 校验。开关启用时 Go 仅记录不含 Secret 的安全 warning，便于迁移完成后清理。

 测试服务器使用 Docker Compose 的完整目录、启动、更新和回滚步骤见 [`docker-test-deployment.md`](docker-test-deployment.md)。