联调与边界:从本地可用到可以公开
结论
本地联调需要同时打开三层:后端进程、Nitro 代理开关、前端入口开关。任何一层没开,表现都不同:404、415、502 或一条流内 error。
当前状态是“本地可用,生产默认关闭”。在鉴权、配额、限流和会话策略完成之前,不能把 /api/chat 公开。
问题与设计
先启动后端。具体配置以 backend/.env.example 为准,不要把真实 Key 写进仓库:
cd backend
uv sync
cp .env.example .env
docker compose -f ../infra/docker-compose.dev.yml up -d
uv run python -m backend.ingest --recreate
uv run uvicorn backend.app:app --reload --port 8000
再给前端三个变量。它们分别控制不同层,不能混用:
# frontend/.env
NUXT_ASSISTANT_ENABLED=true
NUXT_ASSISTANT_BACKEND_URL=http://127.0.0.1:8000
NUXT_PUBLIC_ASSISTANT_ENABLED=true
| 变量 | 作用 | 是否进入客户端 | 关闭后的表现 |
|---|---|---|---|
NUXT_ASSISTANT_ENABLED |
Nitro 代理是否允许转发 | 否 | /api/assistant/chat 返回 404 |
NUXT_ASSISTANT_BACKEND_URL |
私有后端地址 | 否 | 代理返回 503 |
NUXT_PUBLIC_ASSISTANT_ENABLED |
是否渲染全站浮窗 | 是 | 页面没有浮窗按钮 |
启动前端开发服务器:
cd frontend
npm run dev
npm run preview 预览的是生产构建,代理会按生产规则返回 404。本地联调要用 dev server,或者临时改代理策略;不要为了联调把生产 fail-closed 删掉。
关键代码
先直连后端,确认流本身没有问题:
curl -N -X POST http://127.0.0.1:8000/api/chat \
-H 'content-type: application/json' \
-d '{"query":"多阶段构建解决了什么问题?","history":[],"top_k":5}'
再走同源代理:
curl -N -X POST http://localhost:3000/api/assistant/chat \
-H 'content-type: application/json' \
-d '{"query":"多阶段构建解决了什么问题?","history":[],"top_k":5}'
两次输出应该都是逐事件出现,而不是等几秒后一次性打印。如果直连有流、代理没有,问题在 Nitro 或反向代理的缓冲;如果两边都没有,先看后端入库和模型配置。
浏览器 Network 面板里,一次提问应该看到:
POST /api/assistant/chat 200
content-type: text/event-stream
响应体按时间增长,而不是在结束时突然出现。点“停止生成”后,请求状态应变为 cancelled,后端日志里能看到客户端断开。
排查顺序可以固定成一张表:
| 现象 | 优先检查 |
|---|---|
| 404 | 代理开关、生产环境、请求路径是否正确 |
| 415 | 请求头是否为 application/json |
| 502 | 后端是否启动、地址是否可达、端口是否写错 |
| 503 | NUXT_ASSISTANT_BACKEND_URL 是否为空;后端配置是否完整 |
| 200 但一直没有 token | 后端检索是否命中、模型是否配置、代理是否缓冲 |
| 有 token 但界面不更新 | useChat 是否在修改响应式代理、解析器是否收到事件 |
流内 error |
上游模型超时或失败;看服务端日志,不看浏览器状态码 |
这里要把“传输成功”和“回答可用”分开:200 只说明连接建立,sources 只说明检索返回了候选,done 只说明生成流程结束。引用是否相关、回答是否正确,需要另一套评测,不属于前端联调。
验证
一套最小验收:
curl -N直连后端,事件顺序为sources → token → done。curl -N走代理,输出同样是逐事件出现。- 浏览器打开
/chat,提问后能看到来源和逐步增长的文本。 - 点击停止,消息显示“回答已停止”,不是错误。
- 关闭后端再提问,显示可读错误;恢复后端后可以继续发送。
- 生产构建请求
/api/assistant/chat返回 404。
最后一条对应端到端测试里的生产模式断言。它验证的是代理边界,不是前端按钮是否隐藏。
边界
当前实现和上线必需分开看:
| 能力 | 当前状态 | 公开前需要 |
|---|---|---|
| 身份认证 | 没有 | 登录态或服务间身份 |
| 配额 | 没有 | 用户 / 日预算与超额提示 |
| 限流 | 没有 | 按 IP、用户或会话的速率限制 |
| 会话持久化 | 只在内存,刷新即清空 | 会话 id、存储、恢复与清理策略 |
| 请求体限制 | 代理完整读入,无独立上限 | 请求大小限制与超时 |
| 质量评测 | 没有系统化评测 | 固定问题集、引用准确性、拒答率 |
| 可观测性 | 日志与 /health |
指标、追踪、成本告警、错误聚合 |
| 部署 | 本地 dev + 生产 fail-closed | 私有网络、反向代理不缓冲、密钥管理 |
生产环境还要确认:
- FastAPI 不直接暴露公网,只允许 Nitro 所在网络访问。
- Caddy / Nginx 关闭响应缓冲,读超时覆盖最长回答时间。
- 日志不记录用户完整问题、模型完整回答和任何密钥。
- 前端公开开关与后端代理开关分开管理,代理始终保留 fail-closed。
- 先有小流量灰度,再根据成本和错误率调整配额。
这个系列到这里结束。后端如何切片、检索和生成,见 AI助手后端实现;联调后怎样减少无关引用,见 如何优化。
前端这一层的价值,不是把接口包一层,而是把不可预测的模型输出收束成可理解、可中断、可恢复、可验证的交互。界面完成只是开始,访问控制和成本边界才是公开的前提。