0 Fork 0

Files

T

2026-09-05 15:46:37 +08:00

10 KiB

Raw Blame History

Nginx 公网入口（受控联调示例）

项	内容
目标	让 `agent.nianxx.com` 通过 HTTPS 访问本项目的兼容对话接口和 MCP
状态	示例配置；公网机器、证书、网络白名单和真实鉴权仍待联调
上游	仅反代本机 `127.0.0.1:8080`

1. 与旧配置的变化

旧配置把整个 / 转发到 DashScope，并在 Nginx 中比较 xtoken、注入 DashScope API Key。新边界是：

公网 HTTPS
  -> Nginx（TLS、精确路径、限流、SSE 传输设置）
  -> 127.0.0.1:8080（fire-safety-ymd）
  -> Go 侧校验 xtoken / MCP Bearer

Nginx 不再调用 DashScope，也不保存或注入 SuperAgent Open API Key、Chat xtoken、MCP Bearer 或数据库凭证。Go 服务负责把用户兼容请求转发到 SuperAgent，并负责 /mcp 的独立 Bearer 校验。这样可避免把 Secret 写入 Nginx 配置，也避免使用 Nginx if 比较 Secret。

2. 可复制的配置示例

配置文件位于 ../../../deploy/nginx/fire-safety-ymd.conf.example。它只公开以下路径：

路径	用途	鉴权与限制
`/api/v1/apps/<safe-app-id>/completion`	截图所示的 DashScope-compatible 用户对话 SSE	Go 校验 `xtoken`；请求体 128 KiB；示例限流 5 req/s、burst 20
`/mcp`	SuperAgent 调用本项目的 MCP	Go 校验独立 `Authorization: Bearer`；请求体 256 KiB；示例限流 20 req/s、burst 40
`/health`	可选进程存活检查	不访问数据库；如不希望公开可删除该 location
其他路径	不对外提供	Nginx 固定返回 404

将示例放入 Nginx 的 http 配置范围（例如 /etc/nginx/conf.d/fire-safety-ymd.conf）前，必须完成以下替换：

把 location = /api/v1/apps/replace-with-fire-safety-app-id/completion 中的占位符替换为安全的 app ID。
该 app ID 必须与 Go 服务的 FIRE_SAFETY_CHAT_COMPAT_APP_ID 完全一致；两处不一致会导致请求被拒绝。
确认证书路径 /cert/agent.nianxx.com.pem 和 /cert/agent.nianxx.com.key 在公网机器上存在，并由 Nginx 进程可读。
直接在宿主机运行 Go 时，确认服务只监听 127.0.0.1:8080；使用本仓库 Compose 时，容器内监听 :8080，但端口映射必须保持为 127.0.0.1:8080:8080。两种方式都不要把 8080 或 PostgreSQL 5432 暴露到公网。
按环境配置 DNS、云防火墙/安全组和 SuperAgent 对 /mcp 的来源 IP/TLS 要求；这些部署事实尚未由本项目验证。

limit_req_zone 必须位于 Nginx http context，不能放进 server 或 location。示例文件假定它被 conf.d/*.conf 从 http {} 中 include；如果部署系统不是这样 include，应把两条 limit_req_zone 指令单独移到 http {}，并保留 server/upstream 在合法上下文。

3. Go 服务配置

在服务器的未提交 Secret 管理方式（例如权限收紧的 .env、systemd EnvironmentFile 或容器 Secret）中配置，不要写入 Nginx 文件或 Git：

# 宿主机直接运行时使用 127.0.0.1:8080；Compose 会覆盖为容器内的 :8080，
# 并只把端口发布到宿主机回环地址。
FIRE_SAFETY_HTTP_ADDR=127.0.0.1:8080

FIRE_SAFETY_SUPERAGENT_ENABLED=true
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_COMPAT_APP_ID=<same-safe-app-id-as-nginx-location>

FIRE_SAFETY_MCP_ENABLED=true
FIRE_SAFETY_MCP_AUTH_TOKEN=<different-mcp-bearer-at-least-32-printable-ascii-characters>
FIRE_SAFETY_POSTGIS_ENABLED=true
FIRE_SAFETY_POSTGIS_DSN=<readonly-postgresql-dsn>

当前仍是受控联调静态门禁：

FIRE_SAFETY_CHAT_AUTH_TOKEN 由用户请求的 xtoken Header 携带，必须与 SuperAgent Open API Key、MCP Token 使用不同值。
FIRE_SAFETY_MCP_AUTH_TOKEN 只用于 SuperAgent -> Go /mcp，不应复用 Chat Token。
Chat、SuperAgent、MCP 和 PostGIS 的完整配置校验以 .env.example 和对应项目文档为准。
浏览器会看到 xtoken；它不能代表最终用户身份、角色、租户或数据授权。公网真实用户入口仍需身份提供方、动态授权、限流、Secret 轮换和持久审计。

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

4. SSE 代理边界

兼容对话响应是长连接 SSE。示例对该精确路径设置：

proxy_http_version 1.1、清空 Connection，保持上游流式连接。
proxy_buffering off、proxy_cache off、proxy_request_buffering off 和 gzip off，并返回 X-Accel-Buffering: no。
proxy_read_timeout/proxy_send_timeout 为 660 秒，覆盖 Go 默认 10 分钟总运行时限并留出少量余量；如提高 Go 的运行时限，必须同步提高 Nginx 超时。
proxy_next_upstream off，避免 POST 流中断后 Nginx 自动重试而产生重复 SuperAgent Run。
限流拒绝使用 HTTP 429 和稳定 JSON；客户端仍需把网关层非 SSE 响应视为失败，不能等待 finish_reason=stop。
透传 Host、X-Forwarded-For、X-Forwarded-Proto、X-Forwarded-Host、X-Forwarded-Port、X-Forwarded-Server 和 X-Request-ID。
不设置 proxy_set_header xtoken ... 或 proxy_set_header Authorization ...；客户端送来的 xtoken 原样到 Go，由 Go 做常量时间比较，MCP Bearer 同理。

MCP 是普通 JSON 请求，不需要 SSE 的关闭响应缓冲设置；示例使用 30 秒读写超时，仍关闭上游自动重试。

5. 启用与检查

启动 Go 服务前，在服务器的进程环境中加载 Secret。不要把 Secret 直接写进命令行或 shell 历史；可以在受保护的环境文件中加载后，再通过 Header 环境变量展开：

直接在宿主机运行时可使用 go run ./cmd/server；测试服务器的默认方式是由 Compose 启动镜像，不在宿主机安装或运行 Go 工具链。

在 reload 前先检查 Nginx 配置；示例机器没有安装 Nginx 时，本地无法代替目标服务器完成这一检查：

sudo nginx -t
sudo nginx -s reload

首轮兼容对话 SSE

以下命令不会把 Token 字面量写入命令历史；CHAT_XTOKEN 应由受保护的环境文件或 Secret 管理器注入当前 shell：

curl -N --fail \
  -H "xtoken: ${CHAT_XTOKEN}" \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  --data '{"input":{"prompt":"观水镇附近有哪些水源候选？"},"parameters":{}}' \
  'https://agent.nianxx.com/api/v1/apps/<same-safe-app-id>/completion'

客户端应读取 event: result 的 SSE 数据，等待 output.finish_reason 为 stop 后再把最终 output.text 视为完成；中途断流不能当作可信答案。首轮返回的 output.session_id 是本项目的本地会话 ID，后续是否能继续多轮取决于兼容接口的契约，不能自行把它当作 SuperAgent Provider Session。

多轮兼容对话 SSE

使用上一轮服务返回并确认成功的会话 ID；不要把 SuperAgent 的内部 Session ID 放入客户端请求：

curl -N --fail \
  -H "xtoken: ${CHAT_XTOKEN}" \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  --data '{"input":{"prompt":"再说明这些候选的限制","session_id":"<session-id-from-previous-response>"},"parameters":{}}' \
  'https://agent.nianxx.com/api/v1/apps/<same-safe-app-id>/completion'

如果目标客户端不接受 text/event-stream 或只需要一次性 JSON，应先以接口 Spec 为准；不要让 Nginx 擅自将 SSE 缓冲成普通 JSON。

MCP 探活/初始化

MCP 请求需要独立 Token，具体 JSON-RPC body 以 MCP Spec 为准：

curl --fail \
  -H "Authorization: Bearer ${MCP_BEARER}" \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual-probe","version":"1"}}}' \
  'https://agent.nianxx.com/mcp'

curl --fail --output /dev/null --write-out 'initialized HTTP %{http_code}\n' \
  -H "Authorization: Bearer ${MCP_BEARER}" \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  'https://agent.nianxx.com/mcp'

curl --fail \
  -H "Authorization: Bearer ${MCP_BEARER}" \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  'https://agent.nianxx.com/mcp'

预期 initialize 返回协议版本 2025-06-18，initialized notification 返回 HTTP 202，tools/list 返回 7 个固定工具。只收到 HTTP 200 但 JSON-RPC 中含 error 也属于失败，不能把它当作 MCP 已就绪。

6. 验收边界与回滚

完成 nginx -t 和 reload 后，应至少验证：

/health 返回 200（如果保留可选 location）。
兼容对话首轮在正确 xtoken 下返回 SSE，末尾出现 finish_reason: stop；错误 Token 返回 401，且 Go 不会创建 SuperAgent Run。
兼容对话多轮使用返回的本地会话 ID；服务重启或会话失效后按契约返回会话不存在，不把 ID 当成 Provider Session。
/mcp 使用独立 Bearer，错误或缺失 Bearer 返回 401；Nginx 没有注入任何 MCP Token。
未列出的路径（例如 /api/chat、/api/v1/apps/other/completion 和 /anything）返回 404。

如果 reload 后发现兼容路由、证书或 SSE 行为异常，先恢复上一个已验证的 Nginx 配置并保留 nginx -t 输出；不要通过放开 location /、关闭 Go 鉴权或把 Secret 写入 Nginx 来排障。

7. 未确认事项

目标公网机器的 Nginx 版本、include 层级、TLS 终止位置和证书续期方式；示例同时监听 80 做 HTTPS 跳转，安全组需按实际策略决定是否允许 80。
agent.nianxx.com 的 DNS、安全组、反向代理来源 IP 和 SuperAgent 对 MCP 回调的网络策略。
兼容接口在目标 SuperAgent/Profile 中对 input.session_id、parameters 和 SSE result 事件的最终协议；实现以本项目 Spec 和实际联调为准。
生产最终用户认证、动态授权、会话共享/持久化、主动取消、配额、审计和 Secret 轮换。

10 KiB Raw Blame History Unescape Escape