门禁兼容修复

docs/project/operations/docker-test-deployment.md

@@ -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 条无效面几何缺口已记录。