增加调试前端页面
This commit is contained in:
andy committed
1 parent
3080b17d02
commit
ee9d2d7cf1
22 files changed
+1442
-59
No files matched your search
@@ -2,7 +2,7 @@
|
||||
|
||||
| 项 | 内容 |
|
||||
| --- | --- |
|
||||
| 目标 | 让 `agent.nianxx.com` 通过 HTTPS 访问本项目的兼容对话接口和 MCP |
|
||||
| 目标 | 让 `agent.nianxx.com` 通过 HTTPS 访问本项目的可选测试页面、兼容对话接口和 MCP |
|
||||
| 状态 | 示例配置；公网机器、证书、网络白名单和真实鉴权仍待联调 |
|
||||
| 上游 | 仅反代本机 `127.0.0.1:16587`；容器内部仍监听 8080 |
|
||||
|
||||
@@ -27,6 +27,8 @@ Nginx 不再调用 DashScope，也不保存或注入 SuperAgent Open API Key、C
|
||||
| 路径 | 用途 | 鉴权与限制 |
|
||||
| --- | --- | --- |
|
||||
| `/api/v1/apps/<safe-app-id>/completion` | 截图所示的 DashScope-compatible 用户对话 SSE | Go 校验 `xtoken`；请求体 128 KiB；示例限流 5 req/s、burst 20 |
|
||||
| `/chat`、`/chat/` | 可选的受控测试对话页面 | `/chat` 由 Go 规范化重定向到 `/chat/`（308）；页面 GET 不要求 Token；Go 由 `FIRE_SAFETY_CHAT_PAGE_ENABLED` 决定返回 HTML 或 404；示例限流 5 req/s、burst 20 |
|
||||
| `/chat/app.css`、`/chat/app.js` | 测试页面静态资源 | 页面开关关闭时由 Go 返回 404；开启时返回对应资源；示例限流 5 req/s、burst 20 |
|
||||
| `/mcp` | SuperAgent 调用本项目的 MCP | Go 校验独立 `Authorization: Bearer`；请求体 256 KiB；示例限流 20 req/s、burst 40 |
|
||||
| `/health` | 可选进程存活检查 | 不访问数据库；如不希望公开可删除该 location |
|
||||
| 其他路径 | 不对外提供 | Nginx 固定返回 404 |
|
||||
@@ -39,6 +41,20 @@ Nginx 不再调用 DashScope，也不保存或注入 SuperAgent Open API Key、C
|
||||
4. 直接在宿主机运行 Go 时，应选择未占用的回环端口并同步修改 Nginx upstream；使用本仓库 Compose 时，容器内监听 `:8080`，端口映射保持为 `127.0.0.1:16587:8080`。不要把 16587、容器 8080 或 PostgreSQL 5432 暴露到公网。
|
||||
5. 按环境配置 DNS、云防火墙/安全组和 SuperAgent 对 `/mcp` 的来源 IP/TLS 要求；这些部署事实尚未由本项目验证。
|
||||
|
||||
示例中的 `location = /chat`、`location = /chat/`、`location = /chat/app.css` 和
|
||||
`location = /chat/app.js` 是页面及其资源的精确入口，均反代到同一个 `127.0.0.1:16587`
|
||||
上游。Nginx 不判断页面开关，也不提供备用 HTML、CSS 或 JavaScript：
|
||||
|
||||
- `FIRE_SAFETY_CHAT_PAGE_ENABLED=true` 且依赖完整时，Go 返回页面 HTML；
|
||||
- 页面请求 `/chat` 时，Go 返回 308 并规范化到 `/chat/`；随后 `/chat/` 返回页面 HTML；
|
||||
- 页面请求 CSS/JavaScript 资源时，Go 返回资源内容；
|
||||
- 开关为 `false` 或页面依赖不满足时，Go 对页面和资源路径返回 404；
|
||||
- 不要把这些 location 改成旧配置的 `location /`，也不要在 Nginx 中注入 xtoken。
|
||||
|
||||
页面默认关闭。测试开启时，Go 进程配置的 `FIRE_SAFETY_CHAT_ALLOWED_ORIGINS` 必须包含精确
|
||||
Origin `https://agent.nianxx.com`；该值是浏览器从页面同源发出 completion 请求时的来源。不要
|
||||
用 `*`，也不要把 Token 写入 Nginx。
|
||||
|
||||
`limit_req_zone` 必须位于 Nginx `http` context，不能放进 `server` 或 `location`。示例文件假定它被 `conf.d/*.conf` 从 `http {}` 中 include；如果部署系统不是这样 include，应把两条 `limit_req_zone` 指令单独移到 `http {}`，并保留 `server`/`upstream` 在合法上下文。
|
||||
|
||||
## 3. Go 服务配置
|
||||
@@ -60,6 +76,10 @@ FIRE_SAFETY_CHAT_AUTH_TOKEN=<chat-xtoken>
|
||||
# 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>
|
||||
# Optional public test page; keep false unless this test surface is needed.
|
||||
FIRE_SAFETY_CHAT_PAGE_ENABLED=false
|
||||
# If the page is enabled, this exact same-origin value is required.
|
||||
FIRE_SAFETY_CHAT_ALLOWED_ORIGINS=https://agent.nianxx.com
|
||||
|
||||
FIRE_SAFETY_MCP_ENABLED=true
|
||||
FIRE_SAFETY_MCP_AUTH_TOKEN=<different-mcp-bearer-at-least-32-printable-ascii-characters>
|
||||
@@ -74,6 +94,12 @@ FIRE_SAFETY_POSTGIS_DSN=<readonly-postgresql-dsn>
|
||||
- `FIRE_SAFETY_MCP_AUTH_TOKEN` 只用于 SuperAgent -> Go `/mcp`，不应复用 Chat Token。
|
||||
- Chat、SuperAgent、MCP 和 PostGIS 的完整配置校验以 `.env.example` 和对应项目文档为准。
|
||||
- 浏览器会看到 `xtoken`；它不能代表最终用户身份、角色、租户或数据授权。公网真实用户入口仍需身份提供方、动态授权、限流、Secret 轮换和持久审计。
|
||||
- `FIRE_SAFETY_CHAT_PAGE_ENABLED` 默认必须为 `false`。开启页面只适用于受控测试；页面 GET 本身
|
||||
不需要 Token，用户在页面输入的 `xtoken` 只在当前页面内存中使用，不写入 HTML、Cookie、URL、
|
||||
localStorage 或 sessionStorage。
|
||||
- 页面与兼容接口同源时，`FIRE_SAFETY_CHAT_ALLOWED_ORIGINS` 必须包含精确的
|
||||
`https://agent.nianxx.com`。这不是把页面变成生产认证；Token 仍为静态测试凭证，必须由用户
|
||||
手动输入并按测试范围管理。
|
||||
- Nginx 不读取、比较或存储 Chat Token，也不需要为 legacy 开关增加配置；请求 Header 原样转发给 Go 校验。开关启用时 Go 仅记录不含 Secret 的安全 warning，便于迁移完成后清理。
|
||||
|
||||
测试服务器使用 Docker Compose 的完整目录、启动、更新和回滚步骤见 [`docker-test-deployment.md`](docker-test-deployment.md)。
|
||||
@@ -135,6 +161,47 @@ curl -N --fail \
|
||||
|
||||
如果目标客户端不接受 `text/event-stream` 或只需要一次性 JSON，应先以接口 Spec 为准；不要让 Nginx 擅自将 SSE 缓冲成普通 JSON。
|
||||
|
||||
### 受控测试页面
|
||||
|
||||
页面由 Go 在开关开启时提供，Nginx 只做四个精确路径的反代（页面、规范化入口和两个资源）：
|
||||
|
||||
```bash
|
||||
curl -i https://agent.nianxx.com/chat
|
||||
curl -i https://agent.nianxx.com/chat/
|
||||
```
|
||||
|
||||
预期行为：
|
||||
|
||||
- `FIRE_SAFETY_CHAT_PAGE_ENABLED=false`：`/chat` 和 `/chat/` 均直接返回 HTTP 404；
|
||||
- `FIRE_SAFETY_CHAT_PAGE_ENABLED=true` 且 Chat 兼容配置完整：`/chat` 返回 HTTP 308，
|
||||
`/chat/` 返回 HTTP 200，`Content-Type` 为 `text/html`；
|
||||
- 开启时页面加载的 `/chat/app.css` 和 `/chat/app.js` 也应返回 HTTP 200；关闭时均为 404。
|
||||
|
||||
需要跟随 `/chat` 的规范化重定向时使用：
|
||||
|
||||
```bash
|
||||
curl -iL https://agent.nianxx.com/chat
|
||||
```
|
||||
|
||||
浏览器打开 `https://agent.nianxx.com/chat/` 后，手动输入受控测试 `xtoken` 和不含敏感信息的
|
||||
问题。页面使用 `fetch` 向同源的
|
||||
`/api/v1/apps/<same-safe-app-id>/completion` 发起 POST，Header 为 `xtoken`、
|
||||
`Content-Type: application/json`、`Accept: text/event-stream`，请求体仍是：
|
||||
|
||||
```json
|
||||
{"input":{"prompt":"观水镇附近有哪些地点候选？"},"parameters":{}}
|
||||
```
|
||||
|
||||
页面只在内存中保存最终成功的 `output.session_id`，下一轮把它放入 `input.session_id`；刷新或
|
||||
关闭页面后不恢复。只有 `finish_reason=stop` 才显示为成功，初始 `finish_reason=null`、HTTP
|
||||
错误、`event: error` 或断流不能当作完整答案。页面不会把 xtoken 写入 HTML、浏览器存储、Cookie、
|
||||
URL、Nginx 或日志。
|
||||
|
||||
浏览器 Network 面板应能确认：请求为同源 POST、Origin 为 `https://agent.nianxx.com`、使用正确
|
||||
的公开 App ID、没有跨域失败，并且第二次请求包含上一轮返回的 `session_id`。如果出现 403，优先
|
||||
检查 `FIRE_SAFETY_CHAT_ALLOWED_ORIGINS` 是否包含精确 Origin；如果出现 404，检查页面开关和
|
||||
容器是否已 recreate；如果出现 401，重新输入正确的测试 xtoken。
|
||||
|
||||
### MCP 探活/初始化
|
||||
|
||||
MCP 请求需要独立 Token，具体 JSON-RPC body 以 MCP Spec 为准：
|
||||
@@ -166,13 +233,19 @@ curl --fail \
|
||||
完成 `nginx -t` 和 reload 后，应至少验证：
|
||||
|
||||
1. `/health` 返回 200（如果保留可选 location）。
|
||||
2. 兼容对话首轮在正确 `xtoken` 下返回 SSE，末尾出现 `finish_reason: stop`；错误 Token 返回 401，且 Go 不会创建 SuperAgent Run。
|
||||
3. 兼容对话多轮使用返回的本地会话 ID；服务重启或会话失效后按契约返回会话不存在，不把 ID 当成 Provider Session。
|
||||
4. `/mcp` 使用独立 Bearer，错误或缺失 Bearer 返回 401；Nginx 没有注入任何 MCP Token。
|
||||
5. 未列出的路径（例如 `/api/chat`、`/api/v1/apps/other/completion` 和 `/anything`）返回 404。
|
||||
2. 页面开关关闭时 `/chat` 和 `/chat/` 均直接返回 404；开启且依赖完整时 `/chat` 返回 308、`/chat/` 返回 200 HTML，且两个资源路径返回 200。
|
||||
3. 兼容对话首轮在正确 `xtoken` 下返回 SSE，末尾出现 `finish_reason: stop`；错误 Token 返回 401，且 Go 不会创建 SuperAgent Run。
|
||||
4. 兼容对话多轮使用返回的本地会话 ID；服务重启或会话失效后按契约返回会话不存在，不把 ID 当成 Provider Session。
|
||||
5. `/mcp` 使用独立 Bearer，错误或缺失 Bearer 返回 401；Nginx 没有注入任何 MCP Token。
|
||||
6. 未列出的路径（例如 `/api/chat`、`/api/v1/apps/other/completion` 和 `/anything`）返回 404。
|
||||
|
||||
如果 reload 后发现兼容路由、证书或 SSE 行为异常，先恢复上一个已验证的 Nginx 配置并保留 `nginx -t` 输出；不要通过放开 `location /`、关闭 Go 鉴权或把 Secret 写入 Nginx 来排障。
|
||||
|
||||
如只需紧急关闭测试页面，不必改动 Nginx：将 Go 环境中的
|
||||
`FIRE_SAFETY_CHAT_PAGE_ENABLED` 改为 `false`，重新创建容器后确认 `/chat`、`/chat/` 和资源
|
||||
路径均直接返回 404。这样不会自动关闭兼容 completion；如果也要关闭对话 API，再按 Chat 配置和对应回滚流程
|
||||
处理。页面开关和 Nginx 路由均应保留清晰的变更记录。
|
||||
|
||||
## 7. 未确认事项
|
||||
|
||||
- 目标公网机器的 Nginx 版本、include 层级、TLS 终止位置和证书续期方式；示例同时监听 80 做 HTTPS 跳转，安全组需按实际策略决定是否允许 80。
|
||||
|
||||
Reference in new issue
Block a user