huangting/fire-safety-ymd
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

门禁兼容修复

Browse Source
This commit is contained in:
andy committed 2026-09-05 17:36:23 +08:00
1 parent f60b416949
commit 801c0af692
18 files changed
+257 -87
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/architecture/chat-api-v1.md
+2
View File
@@ -66,6 +66,8 @@ busy
- 进度只允许安全字符组成的 `run.*` / `tool.*` 事件，以及工具名和状态；消息 delta、Provider ID、工具参数和结果不向客户端透传。
- 错误映射为稳定代码，不回显 Provider 响应正文、URL、Session、堆栈或 Secret。
- API 默认关闭；启用必须同时具备有效 SuperAgent 配置和独立 Chat Bearer。
- Chat 凭证默认至少 32 个可打印 ASCII 字符。为兼容已经交付且无法立即更换的旧客户端短凭证，只有在受控测试/迁移窗口显式设置 `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=true` 才允许短值；无论开关如何，凭证都必须非空、不超过 4096 字节且仅含 ASCII `0x21-0x7e`（无空格、控制字符或 Unicode）。该开关同时适用于原生 Bearer 和兼容 `xtoken`，不影响 MCP 的至少 32 字符门禁；三种凭证必须不同。轮换后恢复 `false`，新环境不得开启。
- 开关启用时只记录不含 Secret 的安全 warning，提醒运维在迁移完成后关闭兼容。
## 5. 伸缩与后续替换点
docs/project/integrations/superagent-openapi.md
+4 -1
View File
@@ -74,6 +74,9 @@ FIRE_SAFETY_SUPERAGENT_OPEN_API_KEY=<secret>
FIRE_SAFETY_CHAT_ENABLED=true
FIRE_SAFETY_CHAT_AUTH_TOKEN=<another-secret-at-least-32-printable-ascii-characters>
# Keep false for new environments. Only set true during 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_ALLOWED_ORIGINS=http://localhost:5173
```
@@ -105,7 +108,7 @@ go run ./cmd/superagent-probe
- [`../../workflows/user-chat.md`](../../workflows/user-chat.md)
- [`../../specs/fire-safety-ymd-chat-api-v1.md`](../../specs/fire-safety-ymd-chat-api-v1.md)
`FIRE_SAFETY_CHAT_AUTH_TOKEN` 是独立的首版联调凭证：原生接口将其作为 Bearer，兼容入口将其作为 `xtoken`。它不是最终用户登录；浏览器会暴露静态 Token，因此公网真实用户入口仍必须接入身份提供方、动态授权、限流和审计。
`FIRE_SAFETY_CHAT_AUTH_TOKEN` 是独立的首版联调凭证：原生接口将其作为 Bearer，兼容入口将其作为 `xtoken`。默认要求至少 32 个字符；如果旧客户端已经拿到且无法立即更换的凭证较短，只能在受控测试/迁移窗口显式设置 `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=true`。此时仍要求凭证非空、不超过 4096 字节，并且仅含 ASCII `0x21-0x7e`（无空格、控制字符或 Unicode）；该开关不影响 MCP Token 的至少 32 个字符门禁，三种凭证仍必须不同。轮换后恢复 `false`，新环境不得开启；服务会记录不含 Secret 的安全 warning 提醒清理。它不是最终用户登录；浏览器会暴露静态 Token，因此公网真实用户入口仍必须接入身份提供方、动态授权、限流和审计。
## 8. 与 MCP 的关系
docs/project/operations/docker-test-deployment.md
+6
View File
@@ -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 条无效面几何缺口已记录。
docs/project/operations/nginx-public-entry.md
+6 -1
View File
@@ -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)。
docs/project/security-access-control-boundary.md
+3 -1
View File
@@ -15,7 +15,7 @@
| 能力 | 状态 | 当前含义 |
| --- | --- | --- |
| `GET /health` | 已实现 | 公开的进程存活响应，不访问业务数据 |
| 用户认证 | 仅首版联调门禁 | `/api/chat` 使用独立静态 Bearer；可选兼容路径用同一信任方向的 `xtoken`；它们不是最终用户身份，身份提供方和正式 Token 格式待确认 |
| 用户认证 | 仅首版联调门禁 | `/api/chat` 使用独立静态 Bearer；可选兼容路径用同一信任方向的 `xtoken`；默认要求至少 32 个可打印 ASCII 字符；已交付旧短凭证仅可通过默认关闭的显式 legacy 开关在受控测试/迁移窗口暂时兼容；它们不是最终用户身份，身份提供方和正式 Token 格式待确认 |
| 角色/区域/租户授权 | 部分实现 | MCP 使用显式服务端静态范围：默认镇街白名单，或经授权的数据库全范围；最终用户动态身份/角色/租户仍未实现 |
| SuperAgent Open API Adapter | 已实现、模拟测试通过 | 默认关闭；Secret 仅由项目环境变量注入；真实环境未联调 |
| 用户聊天与会话映射 | 已实现、默认关闭 | 原生 `POST /api/chat` 和可选 DashScope 风格 `completion` 路径、严格 SSE 最终回答、单进程内存映射和同会话并发冲突；无持久化、跨实例恢复或最终用户授权 |
@@ -48,6 +48,7 @@
- 联系人、电话和精确敏感位置按字段级权限控制，不因同一记录的普通字段可见而自动可见。
- `FIRE_SAFETY_MCP_SCOPE_MODE=all` 是 MCP 固定查询表的数据库全范围授权，只能在该 MCP 凭证确实获准读取这些表全部记录时显式使用；它不会从业务数据自动推导授权。
- `all` 与镇街白名单不能同时配置，避免操作者误以为白名单仍限制结果；两种模式都不能由模型或工具参数修改。
- `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN` 默认必须为 `false`。只有已交付旧客户端的 Chat 凭证较短且无法立即更换时，才允许在受控测试/迁移窗口显式设为 `true`；无论开关如何，Chat 凭证必须非空、不超过 4096 字节且仅含 ASCII `0x21-0x7e`（不得包含空格、控制字符或 Unicode）。该开关只影响 Chat 原生 Bearer 和兼容入口 `xtoken`，不放宽 MCP Token 至少 32 个可打印 ASCII 字符的要求；Chat、SuperAgent Open API 和 MCP 三种凭证必须不同。轮换完成后必须恢复 `false`，新环境不得开启。启用期间仅记录不含 Secret 的安全 warning，以提示后续清理。
- 地名搜索只读取已允许的名称、镇街、村庄和几何字段，仍应用相同服务端数据范围；不读取联系人、电话或任意表。
- 地名匹配输出属于候选。线和面的代表点只用于帮助用户识别记录，未经用户确认不得作为演练点继续查询或形成距离结论。
@@ -93,6 +94,7 @@ MCP 第一阶段已按以下只读边界实现：
- `/api/chat` 不转发消息 delta；只有 Adapter 的严格成功条件全部满足后才发送最终 `message` 和 `done`。公开进度只保留安全的 `run.*` / `tool.*` 事件、工具名和状态。
- 兼容 `completion` 路径同样不转发消息 delta；它先返回无正文的 `finish_reason="null"`，严格成功后才发送 `finish_reason="stop"` 和最终正文。URL App ID 只是公开路由标识，不是授权依据。
- 兼容路径的 `xtoken` 复用 Chat 入站凭证而不是 SuperAgent Key。Nginx 不保存、比较或注入任何应用 Secret，只把 Header 交给 Go 校验。
- `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN` 是 Go 服务侧的配置，不由 Nginx 参与；Nginx 不读取、比较或存储 Chat Token，短凭证兼容规则和 warning 均由 Go 执行。
- 同一内存会话只允许一个活动 Run。流失败或结果不确定时删除本地映射，避免继续复用可能仍在运行的 Provider Session。
- 当前会话只在单进程内存中保存且有数量/TTL 上限；不保存消息历史。重启或多实例切换会导致旧对话不可用，不得向用户承诺持久会话。
docs/specs/fire-safety-ymd-chat-api-v1.md
+8 -3
View File
@@ -17,7 +17,7 @@
## 2. 目标
- 新增默认关闭的 `POST /api/chat`。
- 使用独立静态 Bearer Token 保护首版测试入口，不复用 SuperAgent Key 或 MCP Token。
- 使用独立静态 Bearer Token 保护首版测试入口，不复用 SuperAgent Key 或 MCP Token；默认要求至少 32 个可打印 ASCII 字符。
- 首轮创建随机本地 `conversation_id` 和 SuperAgent Session；后续轮次复用映射。
- 同一 `conversation_id` 同时只允许一个活动 Run，冲突时返回 `409`。
- 通过 SSE 返回对话 ID、安全进度、严格完成后的最终回答和完成事件。
@@ -119,7 +119,8 @@ SSE 开始后的 Provider 失败使用终止 `error` 事件，不返回部分回
| 环境变量 | 默认值 | 说明 |
| --- | --- | --- |
| `FIRE_SAFETY_CHAT_ENABLED` | `false` | 对话 API 总开关；启用时要求 SuperAgent 同时启用 |
| `FIRE_SAFETY_CHAT_AUTH_TOKEN` | 空 | 独立高熵静态 Bearer，至少 32 个可打印 ASCII 字符 |
| `FIRE_SAFETY_CHAT_AUTH_TOKEN` | 空 | 独立静态 Bearer；默认至少 32 个可打印 ASCII 字符，兼容开关开启时允许已交付的旧短凭证 |
| `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN` | `false` | 仅为已交付旧客户端短凭证的受控测试/迁移临时兼容开关；新环境不得开启 |
| `FIRE_SAFETY_CHAT_SUBJECT_ID` | `fire-safety-ymd-chat-test-subject` | 服务端固定测试主体，不使用真实用户标识 |
| `FIRE_SAFETY_CHAT_ALLOWED_ORIGINS` | 空 | 逗号分隔的精确 HTTP(S) Origin；空值只允许无 Origin 的服务端/CLI 调用 |
| `FIRE_SAFETY_CHAT_MAX_BODY_BYTES` | `131072` | HTTP JSON 请求体上限，最大 1 MiB |
@@ -129,13 +130,15 @@ SSE 开始后的 Provider 失败使用终止 `error` 事件，不返回部分回
`FIRE_SAFETY_CHAT_AUTH_TOKEN` 必须分别不同于 `FIRE_SAFETY_SUPERAGENT_OPEN_API_KEY` 和 `FIRE_SAFETY_MCP_AUTH_TOKEN`。
`FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN` 默认为 `false`。只有在旧客户端已经拿到、且无法立即更换的短凭证时，才可在受控测试或迁移窗口显式设置为 `true`。无论开关取值如何，`FIRE_SAFETY_CHAT_AUTH_TOKEN` 都必须非空、不超过 4096 字节，并且每个字符都在 ASCII `0x21-0x7e` 范围内（不得包含空格、控制字符或 Unicode）；开关只影响 Chat 原生 Bearer 和兼容入口的 `xtoken`，不放宽 MCP Token 至少 32 个可打印 ASCII 字符的门禁。三种凭证仍必须使用不同值。凭证轮换完成后必须恢复 `false`；新环境不得以该开关绕过默认门禁。开关启用时，服务启动日志会记录不含 Secret 的安全 warning，便于后续清理。
## 7. CORS 与鉴权边界
- 无 `Origin` 的 CLI/服务端请求可以进入 Bearer 校验。
- 带 `Origin` 的浏览器请求必须精确匹配配置列表；不支持 `*`。
- 预检只允许 `POST` 以及 `Authorization`、`Content-Type` Header。
- 不启用 Cookie 身份或 CORS credentials。
- 静态 Bearer 只适合首版受控联调；公网最终用户入口必须接入真实身份认证、速率限制和动态授权。
- 静态 Bearer 只适合首版受控联调；legacy 短凭证开关只适合明确的迁移窗口，公网最终用户入口必须接入真实身份认证、速率限制和动态授权。
## 8. 日志与数据边界
@@ -153,6 +156,8 @@ SSE 开始后的 Provider 失败使用终止 `error` 事件，不返回部分回
- Given 同一会话已有活动 Run，When 再次发送，Then 返回 `409` 且不发第二个上游请求。
- Given Provider 流不完整或 Run 失败，When 处理结束，Then 不发送 `message` 或 `done`，只返回安全错误。
- Given 服务重启、会话过期或随机 ID 不存在，When 继续对话，Then 返回 `404` 而不把客户端值当作 Provider Session。
- Given `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN` 未开启，When Chat Token 少于 32 个字符，Then 服务启动配置校验失败。
- Given `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=true`，When 旧短凭证用于受控测试/迁移，Then 原生 Bearer 和兼容 `xtoken` 均可校验，但非空、4096 字节上限和 ASCII `0x21-0x7e` 约束仍生效，且启动日志只记录不含 Secret 的安全 warning。
- Given 无真实网络和 Secret，When 执行自动化测试，Then 使用本地 fake/模拟 Provider 并全部通过。
## 10. Definition of Done
docs/specs/fire-safety-ymd-dashscope-compatible-chat-v1.md
+6 -1
View File
@@ -36,10 +36,13 @@
| 环境变量 | 默认值 | 说明 |
| --- | --- | --- |
| `FIRE_SAFETY_CHAT_COMPAT_APP_ID` | 空 | 非空时注册兼容路径；1 至 128 个 ASCII 字母、数字、下划线或连字符 |
| `FIRE_SAFETY_CHAT_AUTH_TOKEN` | 空 | 兼容路径期望的 `xtoken`，仍必须与 SuperAgent Key、MCP Token 不同 |
| `FIRE_SAFETY_CHAT_AUTH_TOKEN` | 空 | 兼容路径期望的 `xtoken`；默认至少 32 个可打印 ASCII 字符，兼容开关开启时允许已交付的旧短凭证 |
| `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN` | `false` | 仅为已交付旧客户端短凭证的受控测试/迁移临时兼容开关；新环境不得开启 |
兼容路径只有在 `FIRE_SAFETY_CHAT_ENABLED=true` 且 App ID 非空时注册。App ID 是用于路径匹配的公开标识，不是 Secret；不匹配的路径返回 404。
`FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN` 默认为 `false`。只有在旧客户端已经拿到、且无法立即更换的短 `xtoken` 时，才可在受控测试或迁移窗口显式设置为 `true`。无论开关取值如何，Chat 凭证都必须非空、不超过 4096 字节，并且每个字符都在 ASCII `0x21-0x7e` 范围内（不得包含空格、控制字符或 Unicode）；开关同时适用于原生 `/api/chat` 的 Bearer 和本兼容路径的 `xtoken`，不放宽 MCP Token 至少 32 个可打印 ASCII 字符的门禁。Chat、SuperAgent Open API 和 MCP 三种凭证仍必须使用不同值。凭证轮换完成后必须恢复 `false`，新环境不得开启该开关。开关启用时，服务启动日志会记录不含 Secret 的安全 warning，便于后续清理。
## 5. 请求契约
```http
@@ -130,6 +133,8 @@ SSE 开始后的失败发送 `event: error`，只包含稳定 code、通用 mess
- Given App ID 未配置，When 请求兼容路径，Then 路由返回 404，原生 `/api/chat` 行为不变。
- Given App ID 或 `xtoken` 错误，When 请求，Then 在读取问题和调用 SuperAgent 前拒绝。
- Given `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN` 未开启，When 已交付的旧 `xtoken` 少于 32 个字符，Then 服务启动配置校验失败。
- Given `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=true`，When 旧短 `xtoken` 用于受控测试/迁移，Then 兼容入口允许该凭证但仍执行非空、4096 字节上限和 ASCII `0x21-0x7e` 校验，并记录不含 Secret 的安全 warning；MCP Token 的至少 32 字符门禁不变。
- Given 首轮请求成功，When 读取 SSE，Then 先收到字符串 `"null"` 会话事件，再收到同会话 `"stop"` 最终正文。
- Given 后续请求携带成功返回的 `session_id`，When 调用，Then 复用同一服务端会话映射。
- Given Provider 流失败，When SSE 已开始，Then 收到安全 `error`，不收到部分正文或 `stop`。