前端多用户与 JWT 接入 API 文档

状态：已实现（2026-08-21）。用户、会话归属、Agent 状态和沙箱映射均持久化在 MongoDB。

身份与隔离

注册后 MongoDB users._id 的字符串形式是稳定的 user_id。后端从 JWT sub 获取该值，并用于：

session_owners.user_id：会话所有权；
sandbox_registry.user_id：用户专属 OpenSandbox；
/memories/{user_id}/preferences.md：用户偏好记忆；
LangGraph configurable.user_id 与运行时 ProcurementContext。

前端不得在聊天请求体中传递或信任 user_id、username、sandbox_id。登录和读取历史不会创建沙箱；用户首次发送消息时才认领预热沙箱或创建新沙箱。

认证接口

`POST /api/auth/register`

{"username":"zhangsan","password":"至少8位密码","display_name":"张三"}

用户名为 3–32 位中文、字母、数字、下划线或连字符。密码使用带随机盐的 scrypt 哈希保存，不保存明文。成功返回 201，用户名重复返回 409。

`POST /api/auth/login`

{"username":"zhangsan","password":"至少8位密码"}

注册和登录成功响应：

{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 43200,
  "user": {
    "user_id": "MongoDB ObjectId 字符串",
    "username": "zhangsan",
    "display_name": "张三"
  }
}

`GET /api/auth/me`

携带 Bearer Token，返回上面响应中的 user 对象。当前版本没有 Refresh Token；前端把 Access Token 放在 sessionStorage，401 时清除 Token 并返回登录页。

鉴权方式

聊天与历史接口均要求：

Authorization: Bearer <access_token>

未登录或 Token 过期返回 401；访问其他用户的会话统一返回 404，避免枚举会话 ID。

对话接口

`POST /api/chat/stream`

{"message":"帮我分析本月采购额","thread_id":"可选；为空时由后端生成"}

响应为 SSE。事件类型为 token、tool_start、tool_args、tool_result、interrupt、done 和 error。done.thread_id 是后续消息使用的会话 ID。

`POST /api/chat/{thread_id}/resume`

{"resume":{"supplement":"预算上限为 10 万元"}}

审批恢复可传 {"resume":{"decisions":[{"type":"approve"}]}}。后端先验证会话归属，再返回与聊天相同的 SSE 流。

状态接口

GET /api/chat/{thread_id}：当前状态；
GET /api/chat/{thread_id}/history?limit=50：LangGraph 状态历史。

历史接口

方法	路径	说明
`GET`	`/api/history?page=1&limit=20`	当前用户的会话列表
`GET`	`/api/history/{thread_id}/messages`	当前用户的展示消息
`DELETE`	`/api/history/{thread_id}`	删除当前用户会话
`PATCH`	`/api/history/{thread_id}?title=...`	已做归属校验；标题持久化仍为预留功能

部署配置

MONGODB_URI：默认连接本机 Docker MongoDB；
JWT_SECRET_KEY：生产环境必须设置为随机且至少 32 字节的秘密值；
JWT_EXPIRE_HOURS：Access Token 有效小时数，默认 12。

生产部署还应把 CORS 的 allow_origins 从开发配置收紧到实际前端域名，并使用 HTTPS。

FilesExpand file tree

frontend-multi-user-api.md

Latest commit

History