huangting/fire-safety-ymd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7243319bbbde58d29e25e7cffccc4ee2b3fbba70
fire-safety-ymd/docs/project/operations/docker-test-deployment.md
andy 7243319bbb superagent请求问题修复
2026-09-06 01:40:15 +08:00

30 KiB
Raw Blame History

测试服务器 Docker 部署手册

项 约定
目标服务器目录 /home/firee-safety-ymd
运行方式 宿主机 Nginx 终止 HTTPS，Docker Compose 运行单个 Go 服务
应用监听边界 容器内监听 8080，只发布到宿主机 127.0.0.1:16587
数据库 使用现有 PostgreSQL/PostGIS；本手册不创建数据库容器、不导入 SQL
状态 测试环境部署基线；目标机镜像构建和 Nginx 语法检查已由现场截图证明通过，但容器稳定运行、页面资源、公网 TLS 和 SuperAgent MCP 完整工具链仍待重测

本手册不包含真实 Token、API Key、数据库密码或旧 Nginx 配置内容。命令中的尖括号是服务器上需要替换的占位符；不要把 Secret 写进命令行、Nginx 文件、镜像构建参数或 Git。

1. 部署前提

本仓库已有可由服务器获取的 main 分支。后续部署仍必须由项目维护者先审阅本地变更、手动 commit 并 push 到远程仓库；本项目不会自动提交、推送或迁移服务器数据。以下命令以发布 main 分支为例。

在开发机提交前先检查暂存区，不要把 .env 或被忽略的原始 SQL 强制加入 Git：

cd /Users/andy/IdeaProjects/fire-safety-ymd
git status --short
git diff --cached --stat
# 审阅后通过 IDE 或逐项执行 git add，只暂存确定要发布的路径。
git commit
git push -u origin main

服务器需要具备：

  • Git、Docker Engine 和 Docker Compose v2（命令为 docker compose）。
  • 宿主机 Nginx、可由 Nginx 读取的 agent.nianxx.com 证书和私钥。
  • 到 PostgreSQL/PostGIS 的网络访问；数据库账号应为运行时只读账号。
  • 如由 SuperAgent 访问 MCP，防火墙、安全组和 TLS 必须允许按约定访问 443。

先确认工具版本，不要把配置文件内容打印到日志：

git --version
docker --version
docker compose version
nginx -v

如果 Nginx 尚未安装，可按发行版选择一种方式；用户已安装时跳过：

# Debian/Ubuntu
sudo apt-get update
sudo apt-get install -y nginx

# RHEL/CentOS/Fedora 系
sudo dnf install -y nginx

安装后确认服务：

sudo systemctl enable --now nginx
sudo systemctl status nginx --no-pager

2. 获取代码到 /home/firee-safety-ymd

首次部署

维护者完成 commit/push 后，在服务器上执行。私有仓库使用服务器已有的 Git 凭证管理方式，不要把 Git 密码或 Token 写入命令：

sudo mkdir -p /home/firee-safety-ymd
sudo chown "$(id -un):$(id -gn)" /home/firee-safety-ymd
git clone https://git.nianxx.cn/huangting/fire-safety-ymd.git /home/firee-safety-ymd
cd /home/firee-safety-ymd
git switch main

如果目录已经是本仓库的工作副本，先确认远程、分支和工作树，再只做快进更新：

cd /home/firee-safety-ymd
git remote -v
git status --short
git fetch --prune origin
git switch main
git pull --ff-only origin main

若 git status --short 有服务器本地改动，先确认归属；不要用 git reset --hard 或覆盖本地文件排障。

3. 创建服务器 .env

.env.example 只是字段说明，不能作为运行时 Secret 文件。首次部署时复制并收紧权限：

cd /home/firee-safety-ymd
cp .env.example .env
chmod 600 .env

用服务器上的受保护编辑器填写 .env，至少确认以下值。三个凭证必须分别生成，不能相互复用：

FIRE_SAFETY_HTTP_ADDR=:8080
# Build-time only. Keep the official default unless the target server cannot
# reach it; this value is not passed to the running application container.
FIRE_SAFETY_BUILD_GOPROXY=https://proxy.golang.org,direct

FIRE_SAFETY_SUPERAGENT_ENABLED=true
FIRE_SAFETY_SUPERAGENT_BASE_URL=https://<superagent-api-host>
FIRE_SAFETY_SUPERAGENT_OPEN_API_KEY=<superagent-open-api-key>
# 当前外部应用策略关闭 Trace 时保持 false；只有策略显式允许 Trace 才设置 true
FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE=false

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>
# 可选的受控测试页面默认关闭；开启时必须同时启用 Chat/兼容入口
FIRE_SAFETY_CHAT_PAGE_ENABLED=false
# 页面从 agent.nianxx.com 同源加载时必须包含该精确 Origin；可按需追加其他测试 Origin
FIRE_SAFETY_CHAT_ALLOWED_ORIGINS=https://agent.nianxx.com

FIRE_SAFETY_MCP_ENABLED=true
FIRE_SAFETY_MCP_AUTH_TOKEN=<独立的高熵MCP-bearer>
FIRE_SAFETY_MCP_SCOPE_MODE=all
FIRE_SAFETY_MCP_ALLOWED_TOWNS=

FIRE_SAFETY_POSTGIS_ENABLED=true
FIRE_SAFETY_POSTGIS_DSN=<只读PostgreSQL连接串>
FIRE_SAFETY_POSTGIS_MIGRATION_DSN=
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//completion 完全一致。
  • FIRE_SAFETY_CHAT_PAGE_ENABLED 默认必须为 false。开启后 Go 提供 /chat、/chat/ 以及同源的 /chat/app.css、/chat/app.js；/chat 会 308 到 /chat/，页面和资源的最终可用性仍由 Go 开关决定。页面只用于受控测试，不嵌入或持久化 Token。
  • FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE 默认必须为 false。无 Trace 的严格成功条件是最终 AI 消息 finish_reason=stop、非空顶层 event: message.final 加顶层 event: end；设置为 true 时还要求 run.completed(status=success)，且外部应用策略必须开启 trace_policy.enabled=true。无 Trace 只是不返回公开工具/步骤轨迹，不等于禁止 SuperAgent 调用 MCP。
  • 页面开启时 FIRE_SAFETY_CHAT_ALLOWED_ORIGINS 必须包含精确的 https://agent.nianxx.com，并且 Chat 兼容 App ID、Chat Token 和 SuperAgent 配置已经可用；该静态页面不是最终用户认证。
  • 使用 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。
  • 修改 FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE 或其他 SuperAgent 代码/配置后，至少执行 docker compose config --quiet、docker compose build --pull 和 docker compose up -d --force-recreate --remove-orphans；仅 docker compose restart 不会 重新读取 .env，也不会把新代码构建进镜像。

4. 容器访问现有 PostgreSQL/PostGIS

本项目不在 Compose 中创建或初始化数据库。数据库继续由现有 PostgreSQL/PostGIS 运维，Go 服务只使用已完成 SRID 确认的只读数据源。

如果 PostgreSQL 在另一台机器：

  • DSN 使用数据库私网 DNS 或私网地址，不使用容器内的 127.0.0.1。
  • 数据库防火墙只允许测试服务器访问 5432；如启用 TLS，按数据库证书要求配置 DSN 的 sslmode，不要为了省事关闭证书校验。

如果 PostgreSQL 与 Docker 在同一台宿主机：

  • 容器内的 127.0.0.1 指向容器自身；DSN 使用 Compose 声明的 host.docker.internal（或运维明确提供的 Docker 网关地址）。
  • Linux Compose 需要有 host.docker.internal:host-gateway 映射；本仓库的 Compose 配置包含该映射时才能使用这个名称。
  • PostgreSQL 的 listen_addresses、pg_hba.conf 和主机防火墙只允许 Docker 网段中的只读账号访问，不要发布 5432 到公网。
  • 不要把迁移账号放入 .env；数据库配置变更先由管理员验证最小权限。

服务启动时进行 MCP PostGIS readiness 校验。SRID、几何类型或 WGS84 范围硬门禁失败会阻止服务装配；空/无效几何和缺 GiST 索引是当前已知 warning。GET /health 只是进程存活检查，不代表数据库、SuperAgent 或 MCP 已可用，必须同时检查 Compose 日志和实际接口。

5. 构建、启动和本机检查

以下命令在服务器项目目录执行。Compose 构建上下文不复制 .env；非 Secret 的 FIRE_SAFETY_BUILD_GOPROXY 只会被映射为构建参数，并在运行容器环境中强制清空。

先检查 Go 模块代理是否从服务器/Docker 所在网络可达：

curl --head --connect-timeout 10 https://proxy.golang.org/

如果连接官方代理超时，可以测试经运维认可的替代代理。例如 Goproxy.cn 官方说明支持标准 Go module proxy 协议：

curl --head --connect-timeout 10 https://goproxy.cn/

只有确认替代代理可达且组织允许使用时，才在服务器 .env 中改为：

FIRE_SAFETY_BUILD_GOPROXY=https://goproxy.cn,direct

该值必须是不含用户名、密码或 Token 的代理地址；Docker build argument 不是 Secret 注入机制。若组织代理要求认证，需要另做 BuildKit Secret 设计，不能把凭证嵌进 URL 或 .env 中的构建参数。

主机侧 curl 成功只能初步说明连通性；最终仍以 docker compose build 是否能下载并校验模块为准。如果两个地址都超时，应修复 Docker/宿主机的 DNS、HTTPS 出口、透明代理或防火墙，或者使用组织自建的可信 Go module proxy。不要设置 GOSUMDB=off、跳过 go.sum 校验或反复执行 docker compose up 掩盖依赖下载失败。

代理连通后再构建并启动：

cd /home/firee-safety-ymd
docker compose config --quiet
docker compose build --pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 api
curl --fail http://127.0.0.1:16587/health

预期结果：容器为 Up（健康状态由 Compose 显示），health 返回 HTTP 200；有限日志不应出现 DSN、密码、Token 或 API Key。docker compose config --quiet 只验证配置，不输出展开后的 Secret。若 Compose 不支持 --quiet，升级 Compose 或使用不会回显结果的等价校验方式。

若构建在 RUN go mod download 处失败，则镜像和容器尚未生成，后续访问宿主机端口会得到 connection refused。先解决模块代理连通性并重新执行 docker compose build --pull，成功后才能执行 up -d。

失败时只读取有限日志：

docker compose ps
docker compose logs --tail=200 api

不要把完整日志粘贴到公共工单；先删去 URL 凭证、连接串、Header、联系人和精确位置。readiness 报错时核对数据库地址、只读权限和 FIRE_SAFETY_POSTGIS_EXPECTED_SRID=4326，不要关闭门禁或修改原始几何。

6. 安装/替换宿主机 Nginx 配置

仓库模板为 deploy/nginx/fire-safety-ymd.conf.example，不含真实 Secret。它把精确 Chat 兼容路径、/mcp 和可选 /health 反代到 127.0.0.1:16587，其他路径返回 404；详细 SSE 边界见 nginx-public-entry.md。

先只查找拥有 agent.nianxx.com 的配置文件名，避免使用 nginx -T 把旧文件中的 DashScope Key 打到终端：

sudo grep -RIl \
  'server_name[[:space:]]\+agent\.nianxx\.com' \
  /etc/nginx/conf.d /etc/nginx/sites-enabled 2>/dev/null

旧配置迁移前：

  1. 记录旧配置文件路径和归属；不要把旧配置内容复制到仓库或新模板。
  2. 如需回滚，将旧文件以 root 权限备份到不被 Nginx include 的目录并限制为 600；若含真实 DashScope Key，应由凭证所有者安排轮换。
  3. 把旧文件移出 *.conf include（例如改为 .disabled），避免同一域名出现两个冲突的 server 块。移动前确认目标是上一步查到的精确路径，不要批量操作整个 /etc/nginx。

部署模板的示例（目录因发行版而异；使用 sites-enabled 时按实际 include 位置调整）：

sudo install -o root -g root -m 0644 \
  deploy/nginx/fire-safety-ymd.conf.example \
  /etc/nginx/conf.d/fire-safety-ymd.conf
sudo vi /etc/nginx/conf.d/fire-safety-ymd.conf

编辑时完成以下非 Secret 替换：

  • 将 replace-with-fire-safety-app-id 替换为 .env 中的 FIRE_SAFETY_CHAT_COMPAT_APP_ID。
  • 确认证书路径、域名和上游 127.0.0.1:16587 符合测试服务器。
  • 保留精确 location、SSE 的 proxy_buffering off/超时设置和其他路径的 404；不要恢复旧配置的 location /、DashScope proxy_pass、Authorization Key 或 Nginx if Token 比较。
  • limit_req_zone 必须位于 Nginx http 上下文；模板假定由 conf.d/*.conf 在 http {} 中 include。若 include 层级不同，把指令移到合法的 http 上下文。

确认旧配置已禁用且新文件不含 Secret 后，再验证并 reload：

sudo nginx -t
sudo systemctl reload nginx

如果 Nginx 不由 systemd 管理，使用发行版的 reload 方式；reload 前必须先通过 nginx -t。

7. 公网 Chat SSE 冒烟

先验证宿主机本地 /health 和 HTTPS /health，再用不含敏感信息的问题验证 SSE。将 Token 安全注入当前 shell（例如受保护的 Secret 管理器或交互式读取），不要把字面量写入 shell 历史：

read -rsp 'Chat xtoken: ' CHAT_XTOKEN
printf '\n'

首轮请求：

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，最后一个成功事件的 output.finish_reason 为 stop。只有 stop 事件的 output.text 可当作完成；中途断流、HTTP 错误或只有 finish_reason=null 不得当作可信答案。output.session_id 是本项目本地会话 ID，不是 SuperAgent 内部 Session ID。

后续轮次使用上一轮成功返回的本地会话 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'

至少验证：错误 xtoken 为 401；不存在的 app ID 和未列出的路径为 404。不要使用真实联系人、电话或精确敏感位置作为冒烟问题。

完成 Chat 测试后清理当前 shell 中的临时变量：

unset CHAT_XTOKEN

8. 公网 Chat 测试页面

测试页面由 Go 可选提供，不需要单独的前端容器或 Nginx 静态目录。页面及两个同源资源的 Nginx 精确路径已经包含在仓库模板中：/chat、/chat/、/chat/app.css 和 /chat/app.js。 Nginx 始终可以反代这些路径，但是否返回内容由 Go 的 FIRE_SAFETY_CHAT_PAGE_ENABLED 控制。

开启页面

在服务器受保护的 .env 中确认或修改以下非 Secret 配置：

FIRE_SAFETY_CHAT_ENABLED=true
FIRE_SAFETY_CHAT_COMPAT_APP_ID=<与Nginx completion路径一致的公开app-id>
FIRE_SAFETY_CHAT_PAGE_ENABLED=true
FIRE_SAFETY_CHAT_ALLOWED_ORIGINS=https://agent.nianxx.com

页面开启要求 Chat、兼容 App ID、Chat 测试凭证和 SuperAgent 配置已经有效； https://agent.nianxx.com 必须是精确 Origin，不能使用 *。页面是受控测试工具，不是最终 用户认证，用户要在页面中手动输入 xtoken，不能把 Token 写入页面、Nginx 或镜像。

修改 .env 后必须重新创建容器，单独 restart 不会重新读取环境变量：

cd /home/firee-safety-ymd
docker compose config --quiet
docker compose up -d --force-recreate --no-build
docker compose ps
curl --fail http://127.0.0.1:16587/health

如果 Nginx 模板刚刚更新，再执行 sudo nginx -t，确认通过后再 reload；只改 Go 开关时不需要 改 Nginx 文件。

页面验收

先不带 Token 检查页面和资源路由：

curl -i https://agent.nianxx.com/chat
curl -i https://agent.nianxx.com/chat/
curl -i https://agent.nianxx.com/chat/app.css
curl -i https://agent.nianxx.com/chat/app.js

开启时预期 /chat 返回 HTTP 308 并指向 /chat/，/chat/ 返回 HTTP 200 HTML，CSS 和 JavaScript 返回 HTTP 200。需要自动跟随入口重定向时使用：

curl -iL https://agent.nianxx.com/chat

关闭时，Go 不注册页面 Handler，/chat、/chat/、/chat/app.css 和 /chat/app.js 均 直接返回 HTTP 404；这与 Nginx 是否保留四个精确 location 无关。

浏览器打开 https://agent.nianxx.com/chat/，手动输入受控测试 xtoken（页面不会预填或保存）， 发送不含敏感信息的问题。Network 面板应看到同源 POST 到 /api/v1/apps/<same-safe-app-id>/completion，请求体为第三方兼容格式，Header 含 xtoken， 响应为 event: result SSE。只有 output.finish_reason=stop 才是成功；第二轮请求应把第一轮 成功返回的 output.session_id 放入 input.session_id。刷新或关闭页面后，Token 和 session_id 均应清除，不得自动恢复。

关闭与回滚

紧急关闭页面时，将 .env 的 FIRE_SAFETY_CHAT_PAGE_ENABLED 改回 false，执行：

cd /home/firee-safety-ymd
docker compose up -d --force-recreate --no-build
curl -i https://agent.nianxx.com/chat
curl -i https://agent.nianxx.com/chat/

确认两个路径直接 404（无 308），并按需检查 CSS/JavaScript 资源也为 404。该操作不会自动 关闭兼容 completion；如需一并关闭 Chat，再按 Chat 总开关执行配置回滚。若页面版本或 Nginx 版本导致故障，回到维护者指定的已验证 Git revision 或 root-only Nginx 备份，先 nginx -t 再 reload；不要恢复旧的全路径 DashScope 代理、关闭 Go 鉴权或把 Secret 写入 Nginx。

9. SuperAgent Open API 无 Trace 模式

当前测试环境优先使用无 Trace 模式，避免外部应用策略未开放公开 Trace 导致消息流返回 HTTP 403 / open_agent_trace_disabled。在服务器 .env 中确认：

FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE=false

无 Trace 模式仍严格要求上游最终 AI 消息的 finish_reason=stop、非空顶层 event: message.final 和顶层 event: end；最终回答只取 message.final.text。它只是不向调用方 返回公开工具/步骤轨迹，不等于禁止 SuperAgent 在执行中调用已配置的 MCP 工具。确认 MCP 是否 实际被调用，必须检查 /mcp 日志和返回结果。只有外部应用策略显式开启 trace_policy.enabled=true 时，才把该值改为 true；Trace 模式会额外要求 run.completed(status=success)。

修改 .env 后必须重新构建并重新创建服务，使配置在运行容器中生效：

cd /home/firee-safety-ymd
docker compose config --quiet
docker compose build --pull
docker compose up -d --force-recreate --remove-orphans
docker compose ps
docker compose logs --tail=100 api
curl --fail http://127.0.0.1:16587/health

不要在日志或工单中粘贴 Open API Key。若仍收到 403，只记录 HTTP 状态、脱敏后的 Provider code、 时间和请求关联 ID，交由 SuperAgent 平台核对外部应用策略；不要反复轮换无关的 Chat/MCP 凭证。

受控诊断已经确认：同一 Key 的 include_trace=true 因应用策略返回 403 open_agent_trace_disabled；同一 Key 的 include_trace=false 已由真实探针完成严格成功判定， 本地兼容 Chat SSE 也完成 finish_reason=null -> stop。公网完整消防对话、MCP 实际工具调用和 多轮会话仍需单独验收。

10. SuperAgent MCP 回调配置与冒烟

在 SuperAgent 的工具/MCP 配置中新增远程 MCP 服务：

URL: https://agent.nianxx.com/mcp
Method: POST
Authorization: Bearer <FIRE_SAFETY_MCP_AUTH_TOKEN>

该 Bearer 必须是 .env 中独立的 FIRE_SAFETY_MCP_AUTH_TOKEN，不要填 Chat xtoken 或 SuperAgent Open API Key。SuperAgent 当前不能在配置中指定 protocolVersion；不要把它或 MCP-Protocol-Version 作为客户端配置项加入。已稳定接通的 th-hotel-simple-superagent 不读取或校验这些版本元数据，而是固定返回 2025-06-18；消防 MCP 按这一已验证兼容档案接入，目标是打通工具调用，不是追求最新协议。SuperAgent 还可能需要公网来源 IP 白名单、TLS CA 或其他平台级 Header，按实际平台和网络策略确认。

服务端兼容规则如下：对可解析的 JSON-RPC initialize，params.protocolVersion 的缺失、空值、非字符串或其他值都不作为版本拒绝条件，响应固定返回 result.protocolVersion: "2025-06-18"；MCP-Protocol-Version Header 的缺失或值也不作为版本拒绝条件。固定返回该版本不表示服务实现或声明支持任意客户端版本，2025-03-26、2025-11-25 等值也不改变服务端实现目标。兼容仅针对版本元数据，Bearer、Content-Type、非空 Origin、JSON-RPC 结构、只读工具、服务端数据范围和敏感字段边界仍严格执行。

现场日志已证明公网 /mcp 完成 initialize、notifications/initialized、tools/list，并成功调用一次 fire_safety_search_place_candidates；该证据只覆盖地点搜索，不能替代其余消防工具和完整多工具链验收。同一 SuperAgent 中 th-hotel-simple-superagent 已稳定调用是兼容档案参照。部署后继续通过 direct_success（客户端值为 2025-06-18）或 compatibility_success（版本字段缺失或其他值被兼容处理）日志分类确认，服务端不得记录原始版本值。

如果修改了 MCP Handler 或握手协商逻辑，目标机必须拉取包含该修改的明确 revision 后重建镜像；仅 docker compose restart 不会更新镜像中的代码：

cd /home/firee-safety-ymd
git fetch --prune origin
git switch main
git pull --ff-only origin main
docker compose config --quiet
docker compose build --pull
docker compose up -d --force-recreate --remove-orphans
docker compose ps
docker compose logs --tail=100 api
curl --fail http://127.0.0.1:16587/health

在服务器或受控终端用独立变量测试初始化。下面的版本字段只是普通 JSON-RPC 参数示例，SuperAgent 不需要配置它；也可以省略或使用客户端实际发送的值：

read -rsp 'MCP bearer: ' MCP_BEARER
printf '\n'
curl --fail \
  -H "Authorization: Bearer $MCP_BEARER" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --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' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  'https://agent.nianxx.com/mcp'

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

curl --fail \
  -H "Authorization: Bearer $MCP_BEARER" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"fire_safety_search_place_candidates","arguments":{"place_name":"观水镇","limit":3}}}' \
  'https://agent.nianxx.com/mcp'

确认第一步固定返回 result.protocolVersion: 2025-06-18，第二步返回 HTTP 202，第三步列出 7 个固定工具，第四步至少完成一个受控只读 tools/call。这四步 initialize → notifications/initialized → tools/list → tools/call 才是 SuperAgent 能调用消防 MCP 的验收链路；只看到 initialize 成功不能宣称接通。版本 Header 不需要配置或继续携带。再用无敏感信息的已知地名/点位做少量只读调用，核对正确 Bearer 成功、错误/缺失 Bearer 为 401、warnings 保留、非法参数不会变成任意 SQL。查询到资源记录不代表实时可用、路线已规划或正式集结点。

完成 MCP 测试后清理当前 shell 中的临时变量：

unset MCP_BEARER

11. 更新、重启与回滚

发布新版本

维护者先将目标版本 commit/push 后，服务器快进更新并重建：

cd /home/firee-safety-ymd
git fetch --prune origin
git switch main
git pull --ff-only origin main
docker compose config --quiet
docker compose build --pull
docker compose up -d --remove-orphans
docker compose ps
docker compose logs --tail=100 api

更新会重启单个 Go 进程，现有内存会话丢失；客户端按会话失效处理并重新开始对话。当前部署不支持多实例共享会话，也没有持久化历史或审计。

回滚

回滚到上一个已验证的 Git commit 或镜像版本。先保留现状信息并确认目标版本；不要用破坏性 reset 覆盖未知的服务器本地改动：

cd /home/firee-safety-ymd
git status --short
git log --oneline -5

由维护者确认目标 commit（例如 <verified-commit>）后，先以 detached HEAD 检出该已验证版本，再重新构建启动；这是显式回滚，不会自动覆盖服务器本地改动：

git fetch --prune origin
git switch --detach <verified-commit>
docker compose build --pull
docker compose up -d --remove-orphans
docker compose ps

回滚结束并准备恢复正常发布轨道时，再切回维护者指定的分支：

git switch main
git pull --ff-only origin main

如果是 Nginx 配置导致故障，先恢复 root-only 备份，确认旧域名配置没有重复 include，再执行：

sudo nginx -t
sudo systemctl reload nginx

回滚后重新检查本机和公网 /health、Chat 401/404 边界以及 MCP 初始化。docker compose down 只停止容器，不删除代码或数据库；明确需要停服时再执行：

cd /home/firee-safety-ymd
docker compose down

12. 完成判定与当前限制

本手册完成不代表公网部署已完成。现场交付至少应记录：

  • 目标机 Compose 配置校验、build、up、健康检查和无 Secret 的有限日志结果。
  • 目标机 nginx -t 和 reload 成功；443 证书、DNS、安全组及旧 location / 已确认不再生效。
  • 页面开关关闭时 /chat、/chat/、/chat/app.css、/chat/app.js 直接返回 404；开启时 /chat 返回 308、/chat/ 返回 200 HTML，两个资源返回 200；FIRE_SAFETY_CHAT_ALLOWED_ORIGINS 包含 https://agent.nianxx.com。
  • Chat 首轮/多轮 SSE、错误凭证、未知 app/path 的实际 HTTPS 响应。
  • 页面浏览器验收证明用户手动输入 xtoken、Token 不被页面持久化、兼容 completion SSE 及同页面 session_id 复用；这只是静态测试页面，不是生产认证。
  • 若为已交付旧客户端临时开启 Chat legacy 短凭证兼容，应记录受控迁移窗口，确认启动 warning 不含 Secret，并在凭证轮换后恢复 FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=false。
  • SuperAgent Open API 使用 FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE=false 时，验证最终 AI 消息 finish_reason=stop、非空顶层 message.final 加顶层 end；若切换为 true，验证外部应用 Trace 策略已开启且 run.completed(status=success) 仍为必要条件。无 Trace 不等同于 MCP 禁用；完整消防对话和 MCP 工具调用仍须单独记录。
  • SuperAgent -> /mcp 的独立 Bearer、TLS/网络白名单、无版本配置 initialize 兼容响应、notifications/initialized、tools/list 和全部 7 个受控只读 tools/call。现场已有地点搜索一次成功证据，但其余工具未验收；版本字段/Header 不作为配置或拒绝门禁；公网请求到达但没有完成这条调用链，不算完成。
  • 数据库未公开 5432，运行账号保持只读，PostGIS readiness warning 和 35 条无效面几何缺口已记录。

若目标服务器无法使用 host.docker.internal、Compose 不支持 --quiet、Nginx include 目录不同、证书路径不同或 SuperAgent 对 MCP 的认证格式不同，应先记录实际环境并调整部署 Spec；不要通过放开端口、写入 Token、关闭 readiness 或恢复全路径反代规避问题。