turing_alert_web/API.md

Superbox Go API Reference

后端 API 端点详尽文档。源自动词检索表 + 路由注册表 (internal/router/router.go) + handler/model 实现。

目录

• 基础信息
• 统一响应信封
• 认证机制
• 访问控制矩阵
• 错误码与 HTTP 状态码
• 公共端点
  • 健康检查
  • 系统初始化
  • 认证
  • 事件流 (SSE / WebSocket)
• API 端点
  • Detectors 检测器管理
  • Cameras 摄像头管理
  • Events 事件管理
  • Rules 规则管理
  • Mediums 媒体文件
  • Webhooks 回调配置
  • Algorithms 算法管理
  • Samples 样本管理
  • Users 用户管理
  • Settings 系统设置
  • Stream 视频流
• 静态资源
• 数据模型
• 附录：约束与默认值
  • JWT 与登录
  • Refresh token 行为
  • 客户端 silent refresh 协议
  • 多 tab 已知限制

---

基础信息

• 基础路径: /api/v1 （/health 例外，直接挂在根路径）
• 默认监听地址: 0.0.0.0:8000（可在 config.json → server.addr 修改或 serve --addr 覆盖）
• 内容类型: application/json; charset=utf-8（除文件上传、媒体文件、HLS 之外）
• 字符编码: UTF-8
• 跨域: Access-Control-Allow-Origin: *，Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
• 限流: 暂未实现

全部错误均带 JSON 状态码/详情字段（见下）。所有受保护接口需先 /api/v1/auth/login 拿到 JWT。

---

统一响应信封

所有非文件流的成功响应均使用 response/response.go 中定义的信封：

{
  "err": {
    "ec": 0,
    "dm": "ok",
    "em": ""
  },
  "ret": <data>
}

字段	类型	说明
err.ec	int	自定义错误码，0 = 成功；与 HTTP 状态码同步
err.dm	string	错误描述宏（ok / Bad Request / Not Found / Internal Server Error 等）
err.em	string	错误详情原文（成功时省略）
ret	any	业务负载，结构视端点而异

列表型分页负载（response.RetList）

{
  "err": { "ec": 0, "dm": "ok" },
  "ret": {
    "count": 42,
    "next": null,
    "previous": null,
    "results": [ ... ]
  }
}

count 为符合条件的总行数；results 为当前页的对象数组。next / previous 始终为 null（Django 兼容字段），分页通过 limit / offset query 参数控制。

数组型负载（response.RetArray）

/api/v1/algorithms 的 GET 接口直接返回数组，不带分页包装：

{ "err": { "ec": 0, "dm": "ok" }, "ret": [ {...}, {...} ] }

空响应

response.NoContent 直接返回 204 No Content，无 body（用于 DELETE、PATCH 等无业务数据的接口）。

---

认证机制

Token 体系（access + refresh）

后端使用 stateful 双 token 模型：

Token	格式	存储	TTL	用途
access_token	HS256 JWT（含 user_id / username / is_admin / exp / iat claims）	仅客户端	jwt.access_token_ttl（默认 15m）	访问受保护 API
refresh_token	32 字节随机 → 43 字符 base64-url	客户端明文 + 服务端存 sha256 哈希	jwt.refresh_token_ttl（默认 7d，sliding）	换新 access + refresh 对

关键属性：

• 严格轮换（strict rotation）：每次 POST /api/v1/auth/refresh 成功都会签发新 pair，旧的 refresh 立即失效（在 DB 行上标记 rotated_at = now()，不删除）。
• Reuse detection：被轮换过的 refresh token 若被再次使用，整个 family（同一登录会话的 token 链）全部吊销，原持有者被迫重新登录。视为凭据泄露的应对策略。
• Sliding window：每次成功 refresh 都会把 expires_at 重新设为 now + 7d，活跃用户不需要重新输入密码。真正决定"多久要重新登录"的是 refresh token 的不活跃时长。
• 7 天不活跃就要重新登录；7 天内活跃用户永不重新登录（直到主动 logout 或 reuse detection 触发）。

登录获取 token pair

调用 POST /api/v1/auth/login，返回：

{
  "err": { "ec": 0, "dm": "ok" },
  "ret": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "Z3pFmT7uVxKqY8sN2Lc4hJ1bP9aD5wE0rM6iO3yU2kX8vN4cB1gQ7zH5fS9a",
    "expires_at": "2026-06-03T12:34:56Z",
    "refresh_expires_at": "2026-06-10T12:34:56Z",
    "user": { "id": 1, "username": "admin", "is_admin": true, "is_active": true }
  }
}

JWT 负载 (Claims)：

{
  "user_id": 1,
  "username": "admin",
  "is_admin": true,
  "exp": 1748944496,
  "iat": 1748943596
}

签名算法：HS256，密钥取自 config.json → jwt.secret_key，TTL 由 jwt.access_token_ttl 控制（默认 15m）。

续期 token（silent refresh）

access 过期前无需主动操作；前端 axios 拦截器会在 401 时自动：

1. 用 localStorage.refresh_token 调 POST /api/v1/auth/refresh
2. 成功后更新 localStorage + 重发原请求
3. 失败（refresh 也过期 / 被吊销 / reuse detected）则清状态并跳 /admin/login

5 个并发 401 共用一个 in-flight refresh 请求（模块级 Promise 缓存），避免 strict rotation 误触发 reuse detection 把整个 family 杀光。

携带 access token

任选其一：

# Header 方式（推荐）
Authorization: Bearer <access_token>

# Query 方式（用于浏览器 HLS / SSE / WebSocket）
GET /api/v1/events/stream?token=<access_token>
GET /api/v1/cameras/1/stream?token=<access_token>
GET /hls/camera_1.m3u8?token=<access_token>

中间件优先读 Authorization 头，缺失时回退到 ?token= query。

携带 refresh token

refresh token 不通过 header 传递（永远不进 URL / Authorization 头），仅用于以下两种途径：

# 1. 主动调 /auth/refresh 时放在 body
POST /api/v1/auth/refresh
Content-Type: application/json
{ "refresh_token": "<raw>" }

# 2. 主动 logout 时放在 body（让服务端能删 DB 行）
POST /api/v1/auth/logout
Authorization: Bearer <access>
{ "refresh_token": "<raw>" }

鉴权模式

模式	描述	失败返回
Auth	必须携带有效 access JWT	401 Unauthorized
AuthOrDetector	access JWT 有效 或 调用方 IP 在 detectors 表中注册过	401 Unauthorized
AdminOnly	紧接 Auth 使用，要求 is_admin == true	403 Forbidden
公开	无任何校验	—

Detector 接入

当 AuthOrDetector 中间件检测到 Authorization 无效时，会读取 c.ClientIP()，查询 detectors 表的 ip 字段；命中即放行（在 gin context 写入 detector_ip），否则 401。Detector 自身用 /auth/login 登录后也走同一 refresh 机制。

---

访问控制矩阵

下表汇总每个端点的访问控制（C = 受 CORS 公开；A = JWT 必填；AD = 仅管理员；AO = JWT 或 Detector IP；AOO = JWT 或 Detector IP）。

路径	方法	鉴权	备注
/health	GET	C	—
/api/v1/health	GET	C	—
/api/v1/setup/config	POST	C	初始化写入
/api/v1/init	GET, POST	C	系统初始化
/api/v1/auth/login	POST	C	登录，颁发 access + refresh pair
/api/v1/auth/refresh	POST	C	用 refresh token 换新 access + refresh pair
/api/v1/auth/logout	POST	A	注销当前会话（access + refresh 双 token）
/api/v1/events/stream	GET (SSE)	A	需 query token
/api/v1/events/ws	GET (WS)	A	需 query token
/api/v1/detectors	GET, POST, DELETE	AD	按角色限制
/api/v1/detectors/register	POST	A	检测器自助注册
/api/v1/detectors/:ip	GET, PUT, PATCH, DELETE	AD	—
/api/v1/cameras	GET	A	—
/api/v1/cameras	POST	AD	—
/api/v1/cameras/:id	GET, PATCH	AO	—
/api/v1/cameras/:id	PUT	AD	—
/api/v1/cameras/:id	DELETE	AD	—
/api/v1/cameras/:id/enable_sampling	POST	AD	—
/api/v1/cameras/:id/disable_sampling	POST	AD	—
/api/v1/cameras/:id/stream	GET	A	拉取 / 启动信息
/api/v1/cameras/:id/stream/start	POST	AD	启动转码
/api/v1/cameras/:id/stream/stop	POST	AD	停止转码
/api/v1/cameras/:id/snapshot	GET	A	拉取 JPEG 快照
/api/v1/events	GET	A	分页过滤
/api/v1/events	POST	AO	创建事件
/api/v1/events/:id	GET	A	—
/api/v1/events/:id	PUT, PATCH, DELETE	AD	—
/api/v1/events/:id/close_event	POST	AD	—
/api/v1/events/:id/push_event	POST	AO	—
/api/v1/events/queue_analysis	POST	AO	—
/api/v1/events/people_count	POST	AO	—
/api/v1/events/unmarked	GET	A	—
/api/v1/events/retrieve_ids	GET	A	拉取 ID 列表
/api/v1/events/retrieves	GET	A	拉取对象列表
/api/v1/events/delete_all	POST	AD	批量删除
/api/v1/rules	GET	A	—
/api/v1/rules	POST	AD	—
/api/v1/rules/:id	GET	A	—
/api/v1/rules/:id	PUT, PATCH, DELETE	AD	—
/api/v1/rules/camera/:camera_id	GET	A	—
/api/v1/rules/camera/:camera_id	POST	AD	—
/api/v1/mediums	GET	A	—
/api/v1/mediums	POST	AO	multipart/form-data
/api/v1/mediums/:id	GET	A	—
/api/v1/mediums/:id	PUT, PATCH, DELETE	AD	—
/api/v1/mediums/:id/file	GET	A	文件下载
/api/v1/webhooks	GET, POST	AD	—
/api/v1/webhooks/:id	GET, PUT, PATCH, DELETE	AD	—
/api/v1/webhooks/echo	POST	AD	回声测试
/api/v1/algorithms	GET	AO	数组返回
/api/v1/algorithms	POST	AD	—
/api/v1/algorithms/:code_name	GET	AO	—
/api/v1/algorithms/:code_name	DELETE	AD	—
/api/v1/samples	GET, POST	AO	—
/api/v1/samples/:id	GET, PUT, PATCH, DELETE	AO	—
/api/v1/samples/:id/upload_file	POST	AO	创建 SampleFile
/api/v1/samples/files/:id/mark_uploaded	POST	AO	标记完成
/api/v1/users	GET, POST	AD	—
/api/v1/users/:id	GET, PUT, PATCH, DELETE	AD	—
/api/v1/users/:id/change_password	POST	AD	—
/api/v1/settings	GET, POST	AD	—
/api/v1/settings/:id	GET, PUT, PATCH, DELETE	AD	—
/api/v1/settings/name/:name	GET	AD	—
/api/v1/settings/by-name/:name	PUT	AD	Upsert
/api/v1/stream/webrtc/proxy	GET	A	WebRTC → go2rtc 代理
/hls/*filepath	GET	A	HLS 切片（query token）
/storage/*filepath	GET	C	静态文件
/, /admin, /admin/*, /assets/*	GET	C	前端 SPA

警告：Auth 中间件对未带 token 的请求直接 401，不进入 handler；AuthOrDetector 失败也回 401。

---

错误码与 HTTP 状态码

HTTP	场景
200 OK	默认成功
201 Created	POST 创建成功（response.RetCreated）
204 No Content	DELETE / 无业务数据 PATCH
400 Bad Request	参数缺失、JSON 解析失败、字段校验未通过
401 Unauthorized	Token 缺失或无效
403 Forbidden	非管理员访问受控端点
404 Not Found	资源不存在
500 Internal Server Error	未捕获异常 / 服务层错误 / panic（被 Recovery 中间件捕获）

SSE/WS/HLS 在 token 缺失或无效时返回 401 Unauthorized（{"error": "..."}，信封外）。

---

公共端点

健康检查

GET /health

无鉴权。仅返回 {"status":"ok"}。

GET /health HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{ "status": "ok" }

GET /api/v1/health

同上的别名挂载（/api/v1/health）。

---

系统初始化

仅用于系统首次部署；正常情况下使用 superbox config init CLI。

GET /api/v1/init

读取数据库中管理员用户数量。

// Response 200
{
  "err": { "ec": 0, "dm": "ok" },
  "ret": { "initialized": true, "needs_setup": false }
}

数据库不可达时也返回 {"initialized": false, "needs_setup": true}（兜底）。

POST /api/v1/init

创建初始管理员（仅当尚无管理员用户时成功）。

请求体：

{ "username": "ops", "password": "Str0ng-Pass!" }

校验规则：

• username 非空
• password 长度 ≥ 8，且不等于 username
• 命中弱密码黑名单（password、12345678、qwerty、admin、letmein、welcome，不区分大小写）会被拒

成功：

{ "err": { "ec": 0, "dm": "ok" }, "ret": { "success": true } }

失败：

• 管理员已存在 → 400 admin user already exists
• 密码过弱 → 400 password too weak

POST /api/v1/setup/config

无数据库时仍可调用：写 config.json + 连接数据库 + AutoMigrate + 创建管理员，一次性走完。

请求体（SetupConfigRequest）：

{
  "database": {
    "type": "sqlite | postgres | mysql",
    "host": "127.0.0.1",
    "port": 5432,
    "name": "superbox.db",
    "user": "superbox",
    "password": "secret"
  },
  "cloud": { "box_file": "...", "http_server": "...", "ws_server": "..." },
  "storage": {
    "type": "local",
    "local": { "path": "./data" }
  },
  "admin": { "username": "ops", "password": "Str0ng-Pass!" }
}

成功：

{ "err": { "ec": 0, "dm": "ok" }, "ret": { "success": true, "config_path": "/etc/superbox/config.json" } }

副作用：

• 写入文件权限 0600 的 config.json
• 自动生成 32 字节随机 jwt.secret_key（hex）
• 默认 access_token_ttl=15m、refresh_token_ttl=7d、storage.type=local、go2rtc 默认参数

---

认证

全部 3 个端点走 application/json 信封（{"err":{...},"ret":...}），见前文「统一响应信封」。

POST /api/v1/auth/login

• 鉴权：公开（无 token）
• Content-Type: application/json
• 副作用：
  • 在 refresh_tokens 表 INSERT 一行（family_id 为新 UUIDv4，expires_at = now + 7d）
  • 更新 users.last_login = now（失败时记 WARN，不影响登录结果）

请求：

{ "username": "ops", "password": "Str0ng-Pass!" }

字段约束：

• username、password 均为 binding:"required"，缺失 → 400 Bad Request
• 用户名 / 密码错误 或 用户 is_active=false → 401 invalid credentials（不区分两种情况，避免账号枚举）

成功响应（LoginResult）：

{
  "err": { "ec": 0, "dm": "ok" },
  "ret": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "Z3pFmT7uVxKqY8sN2Lc4hJ1bP9aD5wE0rM6iO3yU2kX8vN4cB1gQ7zH5fS9a",
    "expires_at": "2026-06-03T12:34:56Z",
    "refresh_expires_at": "2026-06-10T12:34:56Z",
    "user": {
      "id": 1,
      "username": "ops",
      "is_admin": true,
      "is_active": true
    }
  }
}

字段	类型	说明
access_token	string	HS256 JWT；客户端用于 Authorization: Bearer ...
refresh_token	string	43 字符 base64-url 随机串；客户端必须持久化（localStorage）；服务端只存 sha256 哈希
expires_at	RFC 3339 string	access token 过期时间（默认 = now + 15m）
refresh_expires_at	RFC 3339 string	refresh token 过期时间（默认 = now + 7d）
user	object	登录用户对象（同 UserResponse）

失败：

• 缺字段 / JSON 解析失败 → 400 Bad Request
• 用户名 / 密码错 / 用户禁用 → 401 invalid credentials
• 内部错误（DB 写失败等）→ 500 Internal server error

---

POST /api/v1/auth/refresh

• 鉴权：公开（无 access token）；用 body 里的 refresh_token 验真
• 作用：用 refresh token 换新 access + refresh pair（strict rotation）
• 副作用：
  • 在事务中：把旧行的 rotated_at 设为 now()，并 INSERT 新行（同 family_id，新 token_hash，新 expires_at = now + 7d）
  • 不更新 users.last_login（refresh 不算"登录"）
• 行为（按结果分类）：

条件	行为	HTTP
body 缺 refresh_token	400	400 Bad Request
DB 找不到该 sha256(refresh_token)	401（= invalid）	401 refresh failed
旧行 rotated_at 非空（reuse）	杀整个 family（DELETE WHERE family_id = ?），401	401 refresh failed
expires_at 已过	401	401 refresh failed
用户不存在 / is_active=false	杀 family，401	401 refresh failed
其它 DB 错误	500	500 Internal server error
成功	200 + 新 pair	200 OK

故意统一 401 响应（无论 invalid / expired / reused），前端不区分具体原因，UX 一致即可。

请求：

{ "refresh_token": "Z3pFmT7uVxKqY8sN2Lc4hJ1bP9aD5wE0rM6iO3yU2kX8vN4cB1gQ7zH5fS9a" }

成功响应（同 LoginResult 形状）：

{
  "err": { "ec": 0, "dm": "ok" },
  "ret": {
    "access_token": "<NEW access JWT>",
    "refresh_token": "<NEW refresh token>",
    "expires_at": "2026-06-03T12:50:00Z",
    "refresh_expires_at": "2026-06-10T12:50:00Z",
    "user": { "id": 1, "username": "ops", "is_admin": true, "is_active": true }
  }
}

旧 refresh token 在响应后立即失效；继续用旧 token 调本端点会触发 reuse detection，杀 family。

---

POST /api/v1/auth/logout

• 鉴权：必填 access token（Authorization: Bearer <access>）—— 中间件从中解析 user_id
• 作用：删 refresh_tokens 表中当前会话对应的那一行；不删其它会话（多端点登录互不影响）
• Idempotent：找不到行或 refresh_token 为空都返 200

请求：

POST /api/v1/auth/logout
Authorization: Bearer <access_token>
Content-Type: application/json

{ "refresh_token": "Z3pFmT7uVxKqY8sN2Lc4hJ1bP9aD5wE0rM6iO3yU2kX8vN4cB1gQ7zH5fS9a" }

refresh_token 在 body 里是可选的（缺省 / 解析失败都容忍），便于前端在 access 已过期的情况下也能 logout。

成功响应：

{ "err": { "ec": 0, "dm": "ok" }, "ret": {} }

失败：

• 缺 Authorization 头 / access token 无效 → 401 Unauthorized（由中间件返）
• service 层 DB 错误 → 500 Internal server error

当前只退出"当前会话"。没有"退出所有会话"端点，也不主动吊销其它 family 的 token。要彻底吊销需要 DELETE FROM refresh_tokens WHERE user_id = ? 手工执行（DB 层）。

---

事件流 (SSE / WebSocket)

GET /api/v1/events/stream (Server-Sent Events)

• 鉴权：通过 ?token= query 传递 JWT
• Content-Type: text/event-stream
• 帧格式：event: <type>\ndata: <json>\n\n

事件类型（sse.EventType）：

type	触发时机	data 字段
event_create	新事件入库（POST /events、POST /events/:id/push_event、detector 上报成功）	{ id, camera_id, camera_name, types, status, started_at, thumbnail_url }
event_update	事件字段更新（保留）	与 event_create 同结构

控制开关：

• 读取 settings.frontend.event_popup_enabled（值 "false" 时停止推送，默认/缺失 → 启用）
• 设置后由 SettingHandler.UpsertByName 同步失效 SSE 内部缓存（30s TTL）

详情：见 internal/sse/events.go 与 internal/handler/event_handler.go 的 publishEventCreate。

GET /api/v1/events/ws (WebSocket)

• 鉴权：?token= query JWT
• 同源策略已禁用（CheckOrigin: return true）
• 心跳：服务端每 54s 发 Ping；客户端需在 60s 内响应 Pong
• 接收消息格式与 SSE 一致（type + data），由 ws.Manager.BroadcastJSON 转发

握手失败（无 token / 无效 token）返回 401 {"error": "..."}。

---

API 端点

Detectors 检测器管理

边缘 AI 检测器注册表。AuthOrDetector 中间件用这里的 IP 实现"凭 IP 信任"。

GET /api/v1/detectors

鉴权: Admin 响应: { ret: { count, results: DetectorResponse[] } }

// DetectorResponse
{ "ip": "192.168.1.20", "type": "jetson", "version": "1.4.0" }

POST /api/v1/detectors

鉴权: Admin

请求体：

{ "ip": "192.168.1.20", "type": "jetson", "version": "1.4.0" }

ip 必填（数据库唯一索引）。

成功返回 201 Created + 新建对象。

GET /api/v1/detectors/:ip

鉴权: Admin 路径参数: ip — 字符串 IP 地址

成功返回单个 DetectorResponse，未找到 → 404 detector not found。

PUT /api/v1/detectors/:ip / PATCH /api/v1/detectors/:ip

鉴权: Admin Body: 局部更新（type、version），ip 不可改。

返回更新后的对象。

DELETE /api/v1/detectors/:ip

鉴权: Admin 返回 204 No Content。

POST /api/v1/detectors/register

鉴权: 任意已登录用户 用途: 检测器自服务注册/心跳。

请求体：

{ "ip": "192.168.1.20", "type": "jetson", "version": "1.4.0" }

不存在则创建、存在则更新 type + version（凭 IP）。返回 DetectorResponse。

DELETE /api/v1/detectors?id=<id>

鉴权: Admin Query: id (uint, 必填) 返回 204 No Content。未找到 → 404 detector not found。

---

Cameras 摄像头管理

GET /api/v1/cameras

鉴权: Auth 响应: CameraResponse[] 的分页包装。

// CameraResponse
{
  "id": 1,
  "name": "Front Door",
  "uri": "rtsp://user:pass@192.168.1.10/stream1",
  "streaming_uri": "rtsp://192.168.1.10/stream1",
  "mode": "detect",
  "schedule": { /* JSON, 见 model.Camera.Schedule */ },
  "status": "online",
  "detect_params": { /* JSON */ },
  "default_params": { /* JSON */ },
  "rules": [ /* RuleResponse[] */ ],
  "should_push": false,
  "config_params": { /* JSON */ },
  "sampling": "5m",
  "note": null,
  "snapshot": "snapshots/cam1.jpg",
  "remote_id": "",
  "raw_address": "192.168.1.10",
  "ip": "192.168.1.10",
  "port": 554
}

POST /api/v1/cameras

鉴权: Admin Body: Camera JSON（除 id/created_at/updated_at 外）。 成功 201，返回带数据库写入后字段的对象。

GET /api/v1/cameras/:id

鉴权: Auth 或 Detector IP 路径参数: id uint

未找到 → 404 camera not found。

PUT /api/v1/cameras/:id

鉴权: Admin 全量替换（id 来自 URL）。

PATCH /api/v1/cameras/:id

鉴权: Auth 或 Detector IP 局部更新（仅出现在 body 里的字段被覆盖，handler 未做 diff，传整个对象即可）。

DELETE /api/v1/cameras/:id

鉴权: Admin 返回 204。

POST /api/v1/cameras/:id/enable_sampling

鉴权: Admin 将 Camera.Sampling 设为启用（enableSampling 在 service 层实现具体策略）。返回 200 { ret: {} }。

POST /api/v1/cameras/:id/disable_sampling

鉴权: Admin 对应关闭采样。

GET /api/v1/cameras/:id/stream

鉴权: Auth

返回当前拉流状态：

// 已有 HLS 转码
{
  "err": { "ec": 0, "dm": "ok" },
  "ret": {
    "status": "running",
    "playlist": "<internal playlist path>",
    "hls_url": "/hls/camera_1.m3u8",
    "webrtc_url": "/api/v1/stream/webrtc/proxy?src=<encoded-uri>",
    "webrtc_src": "rtsp://..."
  }
}

// 未启动
{
  "err": { "ec": 0, "dm": "ok" },
  "ret": {
    "status": "stopped",
    "webrtc_url": "/api/v1/stream/webrtc/proxy?src=<encoded-uri>",
    "webrtc_src": "rtsp://..."
  }
}

优先使用 camera.streaming_uri，未设置时退回 camera.uri。

POST /api/v1/cameras/:id/stream/start

鉴权: Admin 启动 ffmpeg → go2rtc → HLS。

返回：

{
  "err": { "ec": 0, "dm": "ok" },
  "ret": {
    "status": "started",
    "playlist": "<internal playlist path>",
    "hls_url": "/hls/camera_1.m3u8",
    "webrtc_url": "/api/v1/stream/webrtc/proxy?src=<encoded-uri>",
    "webrtc_src": "rtsp://..."
  }
}

HLS 切片存放：{storage.local.path}/hls/camera_<id>.{ts,m3u8}，经 /hls/* 路由鉴权后由 ServeHLS 读取。

POST /api/v1/cameras/:id/stream/stop

鉴权: Admin

{ "err": { "ec": 0, "dm": "ok" }, "ret": { "status": "stopped" } }

GET /api/v1/cameras/:id/snapshot

鉴权: Auth 响应: image/jpeg 二进制（c.Data(200, "image/jpeg", snapshot)），由 stream.Manager.TakeSnapshot 通过 ffmpeg 单帧抓取。

未配置 URI → 400 camera has no stream URI configured。

---

Events 事件管理

GET /api/v1/events

鉴权: Auth 支持的 Query 参数：

参数	类型	说明
camera_id	uint / 逗号分隔 uint	单值精确匹配；多值转 camera_id__in 语义
status	string	精确匹配 events.status
types	逗号分隔 string	不区分大小写；空段会被丢弃
time_after	RFC3339	started_at >= value
time_before	RFC3339	started_at <= value
limit	int	默认 20，上限 1000
offset	int	默认 0
ordering	string	"field"（ASC） / "-field"（DESC），字段白名单见 repo；非法 → id DESC

响应: 标准分页。results: EventResponse[]：

{
  "id": 123,
  "camera_id": 1,
  "started_at": "2026-06-03T08:30:00Z",
  "ended_at": null,
  "mediums": [
    { "id": 456, "name": "frame.jpg", "file": "mediums/event_1/.../frame.jpg", "event_id": 1 }
  ],
  "camera": { /* CameraResponse */ },
  "types": "person,vehicle",
  "types_bits": 6,
  "obj_types": null,
  "uuid": "0c1b...",
  "status": "open",
  "remark": "",
  "should_push": false,
  "metadata": null
}

任意 query 参数解析失败会静默忽略（不返回 400），与 Python 版本行为一致。

GET /api/v1/events/:id

鉴权: Auth 返回单个 EventResponse。未找到 → 404 event not found。

POST /api/v1/events

鉴权: Auth 或 Detector IP Body: Event JSON

必填字段：

• camera_id (uint)
• types (string，去空白后非空)

可选：

• mediums: [{id, name, file, ...}] — 仅 id 会被采纳，自动设置 event.medium_id = mediums[0].id，然后 event.mediums 在 handler 中清空（重新加载时由 service 预加载）。

成功 201，返回 EventResponse，并广播 SSE/WS event_create（受 frontend.event_popup_enabled 开关控制）。

PUT /api/v1/events/:id / PATCH /api/v1/events/:id

鉴权: Admin Body: 完整 Event（id 来自 URL）。

当前实现：把 id 之外的字段全量覆盖到数据库行（service 层 Save / Updates），不是真正的 PATCH 语义。

DELETE /api/v1/events/:id

鉴权: Admin 返回 204。

POST /api/v1/events/:id/close_event

鉴权: Admin 关闭事件（设置 ended_at 等，具体见 EventService.CloseEvent）。

POST /api/v1/events/delete_all

鉴权: Admin Body: [1, 2, 3] — uint ID 数组 返回 204。

POST /api/v1/events/:id/push_event

鉴权: Auth 或 Detector IP

同 POST /events，但在 service 层走 PushEvent（语义：可能触发"事件升级 / 推送规则"链路）。成功同样广播 SSE event_create。

POST /api/v1/events/queue_analysis

鉴权: Auth 或 Detector IP Body:

{ "camera_name": "Front Door", "type": "motion" }

成功 201，返回 EventResponse。camera_name 与 type 均必填。

POST /api/v1/events/people_count

鉴权: Auth 或 Detector IP Body:

{
  "macAddress": "AA:BB:CC:DD:EE:FF",
  "eventType": "PeopleCounting",
  "enter": 3,
  "exit": 1,
  "startTime": "2026-06-03T08:00:00Z",
  "endTime": "2026-06-03T08:30:00Z"
}

校验：

• macAddress 必填
• eventType 必须严格等于 "PeopleCounting"（其他值 → 400 event_type must be 'PeopleCounting'）

成功 201，返回 EventResponse。

GET /api/v1/events/unmarked

鉴权: Auth 返回每个摄像头未标记（remark == ''）的事件数：

{
  "err": { "ec": 0, "dm": "ok" },
  "ret": [
    { "camera_id": 1, "count": 5 },
    { "camera_id": 2, "count": 0 }
  ]
}

数据结构由 EventService.CountUnmarkedByCamera 返回。

GET /api/v1/events/retrieve_ids

鉴权: Auth 用途: Python 兼容 cursor 风格拉取 ID 列表（id >= start_id，升序，最多 10000）。

Query 参数：

• start_id (uint, 默认 1)
• id (uint) — 限定单条
• 其它同 GET /events（camera_id / status / types / 时间范围 / limit / offset / ordering）

响应：

{
  "err": { "ec": 0, "dm": "ok" },
  "ret": { "ids": [101, 102, 103], "total": 3 }
}

GET /api/v1/events/retrieves

鉴权: Auth 用途: Python 兼容"倒序 + has_next"分页。

Query 参数：

• start_id (uint, 默认 0xffffffff) — 拉取 id < start_id
• id (uint) — 限定单条
• limit (int, 默认 20, 上限 1000, 负数 → 0)
• 其它同 GET /events

响应：

{
  "err": { "ec": 0, "dm": "ok" },
  "ret": {
    "objects": [ /* EventResponse[] */ ],
    "total": 7,
    "has_next": true
  }
}

当传 ?id=<n> 时走快速路径，直接返回单条 + has_next: false。

---

Rules 规则管理

GET /api/v1/rules

鉴权: Auth 响应: RuleResponse[] 分页包装。

// RuleResponse
{
  "id": 7,
  "camera": 1,
  "unique_id": "uuid-v4",
  "name": "person-rule",
  "mode": "detect",
  "algo": "yolov8n",
  "params": { /* JSON */ },
  "params_base": { /* JSON */ },
  "schedule": { /* JSON */ },
  "event_types": { "person": "Person" }
}

event_types 是从数据库 JSON 列中只保留 string→string 键值对后的精简版（model.RuleResponse 注释）。

POST /api/v1/rules

鉴权: Admin Body: 完整 Rule（camera_id 必填）。返回 201 + RuleResponse。

GET /api/v1/rules/:id

鉴权: Auth 未找到 → 404 rule not found。

PUT /api/v1/rules/:id / PATCH /api/v1/rules/:id

鉴权: Admin Body: 局部覆盖（name / mode / algo / schedule 出现即覆盖）。

注意：camera_id 一旦设置后通过此接口不能修改。

DELETE /api/v1/rules/:id

鉴权: Admin 返回 204。

GET /api/v1/rules/camera/:camera_id

鉴权: Auth 返回该摄像头下的所有规则（标准分页包装）。

POST /api/v1/rules/camera/:camera_id

鉴权: Admin Body: Rule JSON（无需包含 camera_id，URL 提供）。 返回 201。

---

Mediums 媒体文件

文件存于 {storage.local.path}/mediums/{event_<id>|unassigned}/<timestamp>_<name>.<ext>，最大 100MB。

GET /api/v1/mediums

鉴权: Auth 响应: MediumResponse[] 分页包装：

{
  "id": 100,
  "name": "frame.jpg",
  "file": "mediums/event_1/1717400000_frame.jpg",
  "event_id": 1
}

POST /api/v1/mediums

鉴权: Auth 或 Detector IP Content-Type: multipart/form-data 字段:

字段	类型	必填	说明
file	file	是	最大 100MB
name	string	否	默认取 file.Filename
event_id	uint (form 字段)	否	关联事件 ID

成功 201，返回 MediumResponse。

GET /api/v1/mediums/:id

鉴权: Auth 未找到 → 404 medium not found。

PUT /api/v1/mediums/:id / PATCH /api/v1/mediums/:id

鉴权: Admin Body: 局部更新（name / file）。

⚠️ 当前实现直接以 file 字符串覆盖原相对路径，不会把文件复制/移动到新位置。

DELETE /api/v1/mediums/:id

鉴权: Admin 副作用: 同时删除磁盘文件（若 medium.file 非空）。返回 204。

GET /api/v1/mediums/:id/file

鉴权: Auth 响应: 二进制流，附带 Content-Disposition: inline; filename*=UTF-8''<encoded-name> 头。

文件缺失 → 404 file not found。

---

Webhooks 回调配置

GET /api/v1/webhooks

鉴权: Admin 响应: WebhookResponse[] 分页：

{
  "id": 1,
  "types": "person,vehicle",
  "url": "https://example.com/hook",
  "serializer": "default"
}

POST /api/v1/webhooks

鉴权: Admin Body: 完整 Webhook JSON。返回 201。

GET /api/v1/webhooks/:id

鉴权: Admin

PUT /api/v1/webhooks/:id / PATCH /api/v1/webhooks/:id

鉴权: Admin Body: 局部覆盖（url / types / serializer）。

DELETE /api/v1/webhooks/:id

鉴权: Admin 返回 204。

POST /api/v1/webhooks/echo

鉴权: Admin Body: 任意 JSON / 文本（最多读取 1MB）。 响应: 把请求体原样以字符串形式回显：

{ "err": { "ec": 0, "dm": "ok" }, "ret": "{\"foo\":\"bar\"}" }

用于配置/连通性测试。

---

Algorithms 算法管理

与 Rule.algo 字段关联的算法字典表（code_name 为主键）。

GET /api/v1/algorithms

鉴权: Auth 或 Detector IP 响应: 直接数组（无分页包装，RetArray）：

{ "err": { "ec": 0, "dm": "ok" }, "ret": [ { "code_name": "yolov8n", "name": "YOLOv8 Nano" } ] }

POST /api/v1/algorithms

鉴权: Admin Body:

{ "code_name": "yolov8n", "name": "YOLOv8 Nano" }

GET /api/v1/algorithms/:code_name

鉴权: Auth 或 Detector IP 路径参数: code_name (string, 主键) 未找到 → 404 algorithm not found。

DELETE /api/v1/algorithms/:code_name

鉴权: Admin 返回 204。

---

Samples 样本管理

视频样本聚合（含若干 SampleFile），用于后续分析、上传到云端。

GET /api/v1/samples

鉴权: Auth 或 Detector IP 响应: Sample[] 分页包装。

// Sample
{
  "id": "uuid-string",
  "camera_id": 1,
  "started_at": "2026-06-03T08:00:00Z",
  "ended_at": "2026-06-03T08:05:00Z",
  "notified_cloud": false,
  "notified_cloud_at": null,
  "expired": 0,
  "file_count": 3,
  "types": "person,vehicle",
  "types_at": null,
  "metadata": null,
  "notified_guardian": false,
  "notified_guardian_at": null,
  "event_at": null,
  "created_at": "2026-06-03T08:00:00Z",
  "updated_at": "2026-06-03T08:00:00Z",
  "sample_files": []
}

id 是 char(36) 字符串（UUID），区别于其它资源的 uint 主键。

POST /api/v1/samples

鉴权: Auth 或 Detector IP Body: 完整 Sample（id 必填，需为合法 UUID）。

GET /api/v1/samples/:id

鉴权: Auth 或 Detector IP 未找到 → 404 sample not found。

PUT /api/v1/samples/:id / PATCH /api/v1/samples/:id

鉴权: Auth 或 Detector IP Body: 完整 Sample（id 来自 URL）。

DELETE /api/v1/samples/:id

鉴权: Auth 或 Detector IP 返回 204。

POST /api/v1/samples/:id/upload_file

鉴权: Auth 或 Detector IP Body: 完整 SampleFile JSON（id 字段填入 URL 中的数字 ID）：

{
  "path": "samples/<uuid>/file1.mp4",
  "content_type": "mp4",
  "s3_data": { /* optional JSON */ }
}

成功 201，返回 SampleFile：

{
  "id": 12,
  "sample_id": "<uuid>",
  "path": "samples/<uuid>/file1.mp4",
  "content_type": "mp4",
  "s3_data": null,
  "uploaded_at": null,
  "file_deleted": false,
  "created_at": "2026-06-03T08:00:00Z",
  "updated_at": "2026-06-03T08:00:00Z"
}

常量 ContentTypeJPEG = "jpeg" / ContentTypePNG = "png" / ContentTypeMP4 = "mp4"（model.Sample）。

POST /api/v1/samples/files/:id/mark_uploaded

鉴权: Auth 或 Detector IP 路径参数: id (uint, SampleFile.ID)

将 SampleFile.UploadedAt 设为当前时间。返回 200 { ret: {} }。

---

Users 用户管理

GET /api/v1/users

鉴权: Admin 响应: UserResponse[] 分页：

{ "id": 1, "username": "ops", "is_admin": true, "is_active": true }

password 不会出现在响应中（json:"-"）。

POST /api/v1/users

鉴权: Admin Body: 完整 User JSON。返回 201。

创建时密码通过 AuthService.CreateUser 加 bcrypt（默认 cost）后存储。重复用户名 → 服务层 ErrUserExists → 500（当前实现未专门捕获 409 语义）。

GET /api/v1/users/:id

鉴权: Admin

PUT /api/v1/users/:id / PATCH /api/v1/users/:id

鉴权: Admin Body: 局部覆盖（username / is_active / is_admin）。

通过此接口不能修改密码 — 使用 POST /api/v1/users/:id/change_password。

DELETE /api/v1/users/:id

鉴权: Admin 返回 204。

POST /api/v1/users/:id/change_password

鉴权: Admin Body:

{ "old_password": "old", "new_password": "new-Str0ng!" }

AuthService.UpdatePassword（user_service.go）的实际语义是仅验证 old_password 与新密码均非空后覆盖哈希。返回 200 { ret: {} }。

---

Settings 系统设置

KV 表（name 唯一索引）。SSE 推送开关即存于此。

GET /api/v1/settings

鉴权: Admin 响应: SettingResponse[] 分页：

{ "id": 1, "name": "frontend.event_popup_enabled", "value": "true" }

POST /api/v1/settings

鉴权: Admin Body: 完整 Setting JSON。返回 201。

GET /api/v1/settings/:id

鉴权: Admin

GET /api/v1/settings/name/:name

鉴权: Admin 路径参数: name (string) 未找到 → 404 setting not found。

PUT /api/v1/settings/:id / PATCH /api/v1/settings/:id

鉴权: Admin Body: 局部覆盖（name / value）。

PUT /api/v1/settings/by-name/:name

鉴权: Admin Body:

{ "value": "true" }

Upsert 语义：若 name 存在则更新 value，否则创建新行。

副作用：调用成功后立即失效 SSE 内部的 frontend.event_popup_enabled 缓存（30s TTL），使管理界面开关立即生效。

DELETE /api/v1/settings/:id

鉴权: Admin 返回 204。

预置默认设置（启动时由 cmd/superbox 自动创建）：

• frontend.event_popup_enabled = "true"

---

Stream 视频流

GET /api/v1/stream/webrtc/proxy?src=<uri>

鉴权: Auth Query: src (string, 必填) — 原始媒体 URI

内部把 src 包装为 ffmpeg:<src>#video=h264，转发到 go2rtc 的 http://127.0.0.1:<port>/api/stream.mp4?src=<encoded>，并将响应体流式复制回客户端，保留 Content-Type / Content-Length 头。

错误：

• src 缺失 → 400 missing src parameter
• go2rtc 返回非 200 → 500 go2rtc returned status <n>
• 网络错误 → 500 failed to fetch stream: ...

GET /hls/*filepath

鉴权: 通过 ?token= query JWT 用途: 暴露 {storage.local.path}/hls/ 下的转码产物。 限制: 文件后缀必须为 .m3u8 或 .ts，否则 400 invalid file type。

浏览器 <video> 元素播放 HLS 时，URL 模板：

/hls/camera_<id>.m3u8?token=<JWT>

---

静态资源

路径	说明
/storage/*	{storage.local.path} 下的所有文件（公开）
/assets/*	嵌入的前端静态资源（公开）
/admin, /admin/*	前端 SPA 入口（公开；带路径时回落到 index.html）
/	前端根入口（公开）

静态资源未走认证，直接 200。

---

数据模型

完整字段以 GORM tag 为准；以下 JSON 字段是 API 响应里出现的精简版。

CameraResponse

字段	类型	说明
id	uint	主键
name	string	名称
uri	string	主码流 RTSP / HTTP URI
streaming_uri	string	备用流地址（缺省时回退到 uri）
mode	string	detect / sample 等
schedule	JSON	排期（具体 schema 见 Rule.Schedule）
status	string	online / offline 等（由 CameraMonitor 周期刷新）
detect_params	JSON	检测相关参数
default_params	JSON	默认参数
rules	RuleResponse[]	该摄像头的规则（外键）
should_push	bool	是否推送至云
config_params	JSON	其它自定义配置
sampling	string	采样频率字符串（如 5m）
note	JSON	备注
snapshot	string	静态预览图相对路径（/storage/<snapshot> 访问）
remote_id	string	云端 ID（边缘同步）
raw_address	string	裸 IP / 域名
ip	string	等同于 raw_address（保持 Django 字段兼容）
port	int	RTSP 端口

EventResponse

字段	类型	说明
id	uint	主键
camera_id	uint	外键
started_at	string (RFC3339Z)	事件开始
ended_at	string? (RFC3339Z)	事件结束（可空）
mediums	MediumResponse[]	关联媒体（外键 EventID）
camera	CameraResponse?	嵌套摄像头（service 预加载）
types	string	逗号分隔事件类型
types_bits	uint64	类型位掩码
obj_types	JSON	目标类别详情
uuid	string	唯一 UUID
status	string	open / closed / marked 等
remark	string	备注（用于"标记"语义）
should_push	bool	是否推送至云
metadata	JSON	任意附加元数据

RuleResponse

字段	类型	说明
id	uint	主键
camera	uint	camera_id（字段名 camera 保持 Django 兼容）
unique_id	string	UUID
name	string	—
mode	string	detect / sample
algo	string	对应 algorithms.code_name
params	JSON	当前参数
params_base	JSON	基础参数
schedule	JSON	排期
event_types	map[string]string	仅保留字符串键值对

MediumResponse

字段	类型	说明
id	uint	主键
name	string	文件名
file	string	相对 storage.local.path 的路径
event_id	uint*	关联事件（可空）

DetectorResponse

字段	类型	说明
ip	string	唯一索引
type	string	设备类型
version	string	固件 / 软件版本

与 Django 一致：不返回 id、created_at、updated_at。

WebhookResponse

字段	类型	说明
id	uint	主键
types	string	触发事件类型，逗号分隔
url	string	目标 URL
serializer	string	序列化器名（默认 default）

UserResponse

字段	类型	说明
id	uint	主键
username	string	唯一索引
is_admin	bool	是否管理员
is_active	bool	是否启用

SettingResponse

字段	类型	说明
id	uint	主键
name	string	唯一索引
value	string	字符串值（无类型）

AlgorithmResponse

字段	类型	说明
code_name	string	主键
name	string	显示名

Sample / SampleFile

见 Samples 章节中的字段说明。

---

附录：约束与默认值

JWT 与登录

• access token 签名：HS256
• 密钥：config.json → jwt.secret_key（32 字节 hex，CLI 命令 superbox jwt key generate -s 可生成并写回）
• access token TTL：access_token_ttl（默认 15m）；由 JWT exp 声明携带，过期即失效
• refresh token TTL：refresh_token_ttl（默认 7d）；由 refresh_tokens.expires_at 列存 DB，每次成功 refresh 都重置为 now + 7d（sliding window）
• refresh token 格式：crypto/rand 32 字节 → base64.RawURLEncoding → 43 字符 [A-Za-z0-9_-]
• refresh token 存储：服务端只存 sha256 哈希（refresh_tokens.token_hash），DB 泄露也不暴露明文
• 密码：bcrypt DefaultCost（10）
• 弱密码黑名单：password、12345678、qwerty、admin、letmein、welcome（不区分大小写）
• 用户名不可等于密码，不可为 admin

Refresh token 行为

• Login 颁发新 pair，INSERT 一行 refresh_tokens（family_id = 新 UUIDv4）
• Refresh（成功）：事务里把旧行 rotated_at = now()，INSERT 新行（同 family_id、新 hash、expires_at = now + 7d）
• Reuse detection：被轮换过的旧 token 再次被提交 → DELETE FROM refresh_tokens WHERE family_id = ?（杀整个 family），返 401
• User deactivation / deletion 在 refresh 时被检测 → 杀 family，401
• Logout：删 user_id + token_hash 匹配的 1 行；找不到也返 200（idempotent）
• 无后台清理任务（YAGNI）：过期行自然累积，可手工 DELETE FROM refresh_tokens WHERE expires_at < now() 或跑 RefreshTokenRepository.DeleteExpired()

客户端 silent refresh 协议

• 前端 axios 响应拦截器在收到 401 时：
  1. 若 localStorage.refresh_token 存在且请求不是 /auth/refresh 本身且未重试过：调 /auth/refresh，成功后用新 token 重发原请求
  2. 否则：清 localStorage、window.location.href = '/admin/login'
• in-flight 去重：5 个并发 401 共享一个 /auth/refresh 请求（模块级 Promise 缓存），避免 strict rotation 误触发 reuse detection

多 tab 已知限制

in-flight 去重是单 page-load 级别。两个 tab 同时触发 401 时：

• Tab 1 调 /auth/refresh 成功，family 已轮换
• Tab 2 调 /auth/refresh 命中 reuse detection，family 杀光
• 结果：两个 tab 都被强制重新登录

v1 不修。NVR admin 多 tab 不常见。下次重登即可。后续可加 BroadcastChannel 或 Web Locks API。

事件查询

• limit 默认 20，上限 1000
• retrieve_ids 返回最多 10000 条
• retrieves 的 start_id 默认 0xffffffff
• 任何 query 参数解析失败 → 静默忽略（不返回 400）

上传与存储

• mediums 文件大小上限 100MB（storage.maxUploadSize）
• 路径规则：{storage.local.path}/mediums/{event_<id>|unassigned}/<ts_ms>_<safe-name>.<ext>
• 文件名清洗：保留 [a-zA-Z0-9_-]，其它字符 → _，最长 50 字符
• Medium.ServeFile 时使用 http.ServeContent（支持 Range 与 Last-Modified）

HLS 切片

• 文件后缀必须为 .m3u8 或 .ts，否则 400
• 路径限制在 {storage.local.path}/hls/ 下

WebRTC 代理

• 始终以 ffmpeg:<src>#video=h264 形式包装原始流，确保浏览器 H264 兼容
• go2rtc 默认端口 1984（由 config.json → stream.go2rtc_port 修改）

SSE 推送

• 事件类型：event_create（新增）、event_update（保留）
• 触发点：POST /api/v1/events、POST /api/v1/events/:id/push_event（detector 上报 / 业务方创建）
• 受 settings.frontend.event_popup_enabled 开关控制（默认启用）
• 缓存 TTL：30 秒；PUT /settings/by-name/<name> 会主动失效

Detector IP 信任

• 仅 AuthOrDetector 模式生效
• detector.ip 是 size:64 字符串（兼容 IPv4/IPv6）
• 触发时 gin.Context 写入 detector_ip，业务层可读取

中间件链顺序（全局）

1. middleware.Recovery(logger) — panic 兜底
2. middleware.Logger(logger) — 请求日志
3. middleware.CORS() — 跨域

启动行为（cmd/superbox）

• 配置文件查找顺序：--config → viper.AddConfigPath(".", "./config", "/etc/superbox/") → 默认数据目录
• 缺失时自动生成默认 config.json（含随机 JWT key）
• 启动时执行 AutoMigrate + ensureDefaultSettings（注入 frontend.event_popup_enabled=true）
• CameraMonitor 默认 enabled=true，interval_sec=30

数据库支持

• sqlite / sqlite3（默认）
• postgres / postgresql
• mysql（默认）