MyAiDesk/nomifun-tauri/docs/reference/api-overview.zh.md

API 概览

NomiFun 的后端（nomifun-app，二进制 nomicore）对外暴露的是单一的 axum HTTP 服务。SPA、桌面外壳，以及任何外部集成，与它沟通的方式都一样： HTTP 上的 JSON 用于命令/查询，WebSocket 用于流式事件。

本页是一份导览，不是穷尽式的端点参考。完整的接口面位于 crates/backend/ 下的各路由模块；源码即权威参考。下方列出了各分组的 基础路径与对应的路由 owner——请从那里开始查阅。

Base URL

宿主	默认 base URL	备注
nomifun-desktop	http://127.0.0.1:<picked-port>	启动时挑选一个空闲的 localhost 端口。渲染端通过 IPC 获知端口号，并以此向 /api 与 /ws 发起调用。
nomifun-web	http://<host>:<port>（默认 http://127.0.0.1:8787）	同一个后端，与 SPA 一并在同一个端口上提供。
nomicore 独立运行	http://127.0.0.1:25808	单独运行后端——便于调试。

SPA 使用相对路径（/api/...、/ws）。客户端不需要指向另一台 API 服务——SPA 与 API 同址。

鉴权模型

NomiFun 启动时进入三种鉴权策略之一：

已鉴权模式（nomifun-web 默认）

• 通过 POST /login 登录，返回一个会话 JWT，同时写入 cookie （nomifun-session，HttpOnly）与 JSON body。后续请求依靠该 cookie 或 Authorization: Bearer … 请求头进行鉴权。
• 状态变更类请求还必须附带 CSRF 请求头 x-csrf-token，其值需与 nomifun-csrf-token cookie 匹配（Double Submit Cookie 模式）。安全 方法（GET、HEAD、OPTIONS）跳过 CSRF；登录/设置/二维码登录端点 因尚无会话被豁免。
• WebSocket 升级携带同一份 JWT——通常通过 Sec-WebSocket-Protocol 传输，可由 GET /api/ws-token 获取。/ws 路由对 CSRF 豁免（在 WebSocket 升级中无法做基于 cookie 的双提交），但仍需鉴权。
• 限流器分别按客户端作用于登录尝试、一般 API 流量与已鉴权的状态变更 动作。

桌面本地信任模式（nomifun-desktop）

• 嵌入式后端使用 AuthPolicy::TrustLocalToken。
• 桌面 WebView 会得到每次启动生成的 secret（window.__nomiLocalTrust），并在 HTTP/WebSocket 请求中呈递它。
• 其他客户端即使在同一台机器上，也不会因为来自 loopback 自动受信任；除非它拥有正常登录会话。这也是 WebUI 远程访问可以放在登录后的原因。

无鉴权本地模式（nomicore --local，或 Web 宿主 --insecure-no-auth）

• 鉴权与 CSRF 完全关闭。每个请求都以 system_default_user 身份执行。
• 加入一层宽松的 CORS，使桌面 WebView（以及工具）可以自由调用 API。
• 仅本地可达的路由（如 /api/auth/internal/* 与 /api/webui/*）变为 可达。

本地模式下的信任边界是网络——只能将其暴露在 loopback 或完全受信任的 私有网络上。Web 宿主在 --insecure-no-auth 与非 loopback 绑定同时使用 时会大声地打印警告日志。

请求体大小与上限

• 请求体的默认大小上限是 10 MiB（nomifun-common 中的 BODY_LIMIT）。确实需要更大的路由（文件上传、ZIP 创建等）会安装自己 的更大限制——/api/fs/upload 接受最大 30 MiB。
• 代用户下载的远程图片上限为 5 MiB，最多跟随 5 次重定向。

路由分组

每个分组归属一个特定的 crate。下表中的基础路径就是挂载到 app router 中 的实际 URL 前缀；鉴权在已鉴权模式和桌面本地信任模式下生效。

分组	基础路径	鉴权	归属 crate / 文件
健康检查	/health	公共	router/health.rs
鉴权 —— 登录 / 设置 / 状态 / 刷新	/login、/logout、/api/auth/*、/api/ws-token、/qr-login	混合（登录/设置/qr-login：公共；其余：已鉴权）	nomifun-auth/src/routes.rs
鉴权 —— 仅本地 admin/internal	/api/webui/*、/api/auth/internal/*	仅本地模式	同上
会话	/api/conversations/*、/api/messages/search	已鉴权	nomifun-conversation/src/routes.rs、routes_aux.rs
智能体（本地 CLI 智能体）	/api/agents/*	已鉴权	nomifun-ai-agent/src/routes/agent.rs
远程智能体	/api/remote-agents/*	已鉴权	nomifun-ai-agent/src/routes/remote.rs
助手	/api/assistants/*	已鉴权	nomifun-assistant/src/routes.rs
助手标签	/api/assistant-tags/*	已鉴权	同上
MCP 服务	/api/mcp/*	已鉴权	nomifun-mcp/src/routes.rs
技能	/api/skills/*	已鉴权	nomifun-extension/src/skill_routes.rs
扩展	/api/extensions/*	已鉴权	nomifun-extension/src/routes.rs
Hub（扩展市场）	/api/hub/*	已鉴权	nomifun-extension/src/hub_routes.rs
计划任务	/api/cron/*	已鉴权	nomifun-cron/src/routes.rs
频道（IM 桥）	/api/channel/*	已鉴权	nomifun-channel/src/routes.rs
Webhook + 标签设置	/api/webhooks/*、/api/tags/{tag}/settings	已鉴权	nomifun-webhook/src/routes.rs
需求（项目看板）	/api/requirements/*	已鉴权	nomifun-requirement/src/routes.rs
AutoWork / IDMM	/api/idmm/*、/api/requirements/autowork*	已鉴权	nomifun-idmm/src/routes.rs
团队（后端实现面；当前没有对应用户指南路由）	/api/teams/*	已鉴权	nomifun-team/src/routes.rs
终端	/api/terminals/*	已鉴权	nomifun-terminal/src/routes.rs
终端 knowledge 注册辅助	/api/terminals/mcp-register-template、/api/terminals/register-knowledge*、/api/terminals/knowledge-global-status	已鉴权	router/health.rs
知识库	/api/knowledge/*	已鉴权	nomifun-knowledge/src/routes.rs
伙伴	/api/companion/*	已鉴权	nomifun-companion/src/routes.rs
WebUI/public 能力 companion token	/api/webui/companions/{id}/access-token	已鉴权 / 本地 WebUI admin 流	router/companion_token_routes.rs
Browser-use secrets	/api/browser-secrets/*	已鉴权	nomifun-secret/src/routes.rs
文件系统	/api/fs/*	已鉴权	nomifun-file/src/routes.rs
Office 预览	/api/word-preview/*、/api/excel-preview/*、/api/ppt-preview/*、/api/document/convert、/api/preview-history/*、/api/star-office/detect	已鉴权	nomifun-office/src/routes.rs
Office iframe 代理	/api/ppt-proxy/*、/api/office-watch-proxy/*	公共（提供 iframe 内容；不鉴权）	同上
设置 + 提供商 + 系统信息	/api/settings、/api/providers/*、/api/system/*	已鉴权	nomifun-system/src/routes.rs
全局模型故障转移队列	/api/agent/model-failover	已鉴权	router/model_failover.rs
连接探测（Bedrock 等）	/api/bedrock/test-connection	已鉴权	nomifun-system/src/bedrock_probe/routes.rs
Shell 辅助 + STT	/api/shell/*、/api/stt	已鉴权	nomifun-shell/src/routes.rs
公共资源（logo）	/api/assets/logos/*	公共	nomifun-assets/src/routes.rs
Public MCP front door	/mcp/*	companion-token / 已配置 public auth	nomifun-public/src/router.rs
Public MCP agent front door	/mcp-agent/*	companion-token / 已配置 public auth	nomifun-public/src/router.rs
Remote capability REST API	/v1/*	companion-token	nomifun-public/src/rest.rs
实时 WebSocket	/ws	已鉴权（token 通过 Sec-WebSocket-Protocol 或查询串传递）	nomifun-realtime/src/handler.rs

如需各路由具体支持的方法，请阅读对应的 routes.rs 文件——每个 router 都在源文件内联声明自身的路由。

选取的鉴权端点

下面这些是客户端最常直接交互的鉴权端点：

方法 + 路径	用途
POST /login	用户名 + 密码登录。返回 {success, user, token} 并设置会话 cookie。CSRF 豁免。带限流。
POST /api/auth/setup	全新安装上的一次性首位管理员创建。原子操作；并发调用通过条件 UPDATE 竞争，只有一个会赢（其余得到 409 Conflict）。CSRF 豁免。
POST /logout	将当前 token 加入黑名单；清除会话 cookie。
GET /api/auth/status	公共——返回 {needs_setup, user_count, is_authenticated}。可作为 liveness/health 探针。
GET /api/auth/user	返回当前 {id, username}。
POST /api/auth/change-password	修改当前用户密码并轮换 JWT 密钥（使其他会话全部失效）。
POST /api/auth/refresh	刷新仍然有效但接近过期的 token。
GET /api/ws-token	返回用于 WebSocket 升级的 token。
POST /api/auth/qr-login	消费一次性的二维码登录 token（由 WebUI 远程访问流程下发）。
GET /qr-login	静态 HTML 页面，用于完成来自手机扫码的二维码登录跳转。

WebSocket 事件模型

/ws 是用于流式更新的单一双向通道：智能体 token 流、终端输出， 需求/计划任务/团队的状态变化等等。

• 鉴权：通过 GET /api/ws-token 获得的 JWT，放在 WebSocket 的 Sec-WebSocket-Protocol 请求头中（或 Authorization）。token 无效或 过期 → 服务端发出 auth-expired 事件并以 1008 关闭。完全没有 token → 以 1008 关闭，原因为 "no token provided"。
• 升级成功后，每条消息都是带 type 与 payload 的 JSON 对象。当域内 事件发生时（新的智能体 token、一个终端字节、需求状态切换），由 服务端推送；客户端通常无需回送任何内容。服务端把单一的 BroadcastEventBus 多路复用给所有已连接客户端。
• 心跳：每 30 秒 ping 一次，60 秒超时（HEARTBEAT_INTERVAL_MS / HEARTBEAT_TIMEOUT_MS）。
• 关闭码：1000 表示正常关闭；1008 表示策略违规（鉴权失败、token 无效）。

type 取值集合是开放的——扩展与功能模块会发出各自的类型。请把未知 类型当作向前兼容的：忽略它们即可。

响应包络

绝大多数 JSON 响应使用同一种形状（来自 nomifun-api-types 的 ApiResponse<T>）：

{ "success": true, "data": { ... } }

错误使用恰当的 HTTP 状态码返回，body 形如：

{ "success": false, "error": "Invalid username or password" }

登录/设置/刷新这几个 handler 会返回略微富化的包络 （LoginResponse、RefreshResponse）——它们会把 token 或 user 对象 内联在响应中。

真值来源指引

上面的列表只是为了把你引导到对的模块。到达后请阅读源码——每个 router 在一处声明全部路由，每个 handler 都在同一个文件或紧挨着的下一个文件 里。Router 装配本身位于 crates/backend/nomifun-app/src/router/routes.rs； 中间件栈（CSRF、安全响应头、请求体上限、可选的 CORS）也在那里。

另见

• 配置参考 —— 参数、环境变量、鉴权密钥解析顺序。
• 疑难排查 —— 常见的 API 与 WebSocket 故障 形态。
• Web 服务部署 —— 在 TLS 之后把 API 暴露到网络上。