access-collector API 文档

门禁采集器后端 · 纯 JSON 接口 · 已开启跨域 CORS

Base URL：https://access.zhendx.cn  |  数据格式：application/json  |  令牌管理：/ · 健康检查：GET /api/health

项目简介：本服务是「门禁采集器」后端，接收工厂/园区门禁设备的人脸识别进出记录（姓名、工号、抓拍图、方向、时间），写入 SQLite 并提供统计、设备/人员管理、记录检索等 JSON 接口。

数据链路：门禁设备 → HTTPS 回调 /api/lan/callback（或云端上报）→ 后端落库 → 前端经 派发令牌（或管理员登录会话）调用 /api/* 拉取展示。设备侧无需改造，新增同协议设备只需在设备后台填上报地址即可自动入库。

一、鉴权

除 根路径 /（令牌管理页，用管理员账号密码登录）、/api/health、/api/login / /api/logout / /api/me、以及 设备数据上报 3 个接口 外，所有 /api/* 都必须携带有效 派发令牌（给前端 / 第三方跨域调用），或处于管理员登录会话（管理页自身调用）。

调用令牌（仅一种形态 — 派发令牌）：

派发令牌三种传递方式任选其一：

Authorization: Bearer <派发令牌>        # 推荐（跨域 header）
?token=<派发令牌>                        # URL 参数
X-API-Token: <派发令牌>                  # 自定义 header

Token 管理：访问 令牌管理页 /，须用管理员账号密码登录（默认 admin / admin123，登录后请改密）。登录成功后管理面板才会出现，非管理员看不到生成 / 吊销 / 轮换入口；后端接口强制仅管理员登录会话可调用。派发令牌明文仅在生成 / 轮换时显示一次，请立即复制保存。切勿在前端代码硬编码或提交到公开仓库；按人 / 按项目分发并定期更换。

⚠️ 设备上报接口不能要求 token（设备固件发不出 token 字段），其安全性由 HTTPS + 网络隔离保障。Master 令牌已弃用、不再参与鉴权；若既无管理员登录会话、也未生成任何派发令牌，所有业务接口将拒绝访问（不会裸奔）。

二、设备数据上报（公开，无需 token）

由门禁设备主动 POST，云后端落库。前端无需关心，仅作对接说明。

方法路径协议说明
POST/api/lan/callback局域网 HTTP门禁设备回调，字段见下
POST/record/upload/onlineRV1109 云端云端上报（同 /api/cloud/upload）
POST/api/cloud/upload云端云端上报（同上）

局域网回调请求体示例：

{
  "Mac_addr": "示例MAC地址",
  "SN": "示例设备SN",
  "employee_number": "1001",
  "IdentifyType": "1",
  "inout": "1",
  "time": "2026-07-27 10:00:00",
  "name": "示例姓名",
  "face_base64": "<base64 jpg>",
  "devicename": "gate-01"
}
# 响应：{"message":"Set access groups success","result":0}

三、接口清单

方法路径鉴权说明 / 参数
GET/api/health公开健康检查，返回 status / records / devices / online_devices / offline_devices / offline_devices_list(离线设备 device_sn+alias+last_seen) / offline_threshold_minutes / night_window / mqtt_connected
GET/api/statstoken总统计：total / in_out / by_device / by_hour / by_identify_type
GET/api/stats/dailytoken按日聚合 in/out/unknown/total。参数 from to device；format=csv 导出
GET/api/devicestoken设备列表。返回字段：device_sn / name / model / ip / protocol / online(0/1) / status(online|offline，后端按 3h/6h 窗口算好) / last_seen / last_heart / last_record_time(最近一条出入记录) / alias
POST/api/device/<sn>/aliastoken设设备别名，body {"alias":"前门闸机"}，空串清空
GET/api/recordstoken记录列表（后端分页）。参数：page(默认1) size(默认20,≤200) from to device q(姓名/工号模糊) fields(字段投影白名单，逗号分隔) format=csv(导出)。默认不返回 face_img/face_template 大字段，返回信封 {items,page,size,total}
GET/api/records/<id>/facetoken按需取单条记录图片，避免列表内联大字段。参数 kind=capture(默认,抓拍 face_img) 或 template(底库照 face_template)，返回 data:image/jpeg;base64,...
GET/api/personstoken人员花名册（后端分页）。参数 page(默认1) size(默认20,≤200)。返回信封 {items,page,size,total}，每项为：person_key(人员唯一键)、name(展示名，alias 优先，其次最近记录姓名)、alias(自定义别名)、face_img(录入照/底库照，base64 data URL，无则 null)、total(总次数)、in(进)、out(出)、last_active(最近活跃时间)
GET/api/persons/<person_key>token单人详情：person_key / name / alias / face_img(录入照 base64) / total / in / out / last_active / by_device
GET/api/persons/<person_key>/facetoken单人录入照原图(image/jpeg)，供 WP 代理 /api/face 带 Authorization: Bearer 服务端取回后转发浏览器，避免前端 <img> 直连被 CORS/鉴权拦截
POST/api/person/<key>/aliastoken设人员别名，body {"alias":"张三"}，空串清空
GET/api/person?key=token单人员进出统计 in/out/total/by_device（含 face_img 录入照）；format=csv 导出
GET
POST		/api/person/maptoken
(POST)		人员 key 映射。POST body {"raw_key":"...","canonical_key":"..."}
GET
POST		/api/userstoken用户管理。POST body {"username","password","role":"admin|viewer","display_name"}
DEL/api/users/<uid>token删除用户（不能删自己）
POST/api/users/<uid>/passwordtoken改密码，body {"password":"新密码"}(≥4位)
POST/api/login公开管理员登录（账号密码），body {"username","password"}；成功置会话 cookie（7天），管理页凭此进入
POST/api/logout公开登出，清除会话
GET/api/me会话当前登录用户（含 role）；管理页用于自动登录判定
POST/api/me/password会话修改当前管理员密码，body {"password":"新密码"}（≥4位）
▾ 令牌管理（仅管理员账号密码登录会话可调用；派发令牌不可进入）
GET/api/tokensadmin列出已签发令牌（不含明文）。返回 {tokens:[{id,label,role,created_at,last_used,expires_at,revoked}]}
POST/api/tokensadmin生成派发令牌。body {"label":"张三-前端","expires_in_days":90}（天数留空=永久）；返回 {id,token(仅此一次),expires_at,warning}
DEL/api/tokens/<id>admin吊销令牌，立即失效。返回 {ok,id,revoked}
POST/api/tokens/<id>/rotateadmin轮换令牌，旧令牌立即失效、发新令牌。返回 {id,token(仅此一次),warning}

通用时间参数 from / to 格式：YYYY-MM-DD HH:MM:SS（如 2026-07-19 00:00:00）。

四、调用示例

# 1) 健康检查（公开）
curl https://access.zhendx.cn/api/health

# 2) 不带 token 调接口 → 401
curl https://access.zhendx.cn/api/devices

# 3) 带派发令牌 → 200
curl -H "Authorization: Bearer <派发令牌>" https://access.zhendx.cn/api/devices

# 4) 设备别名（写操作）
curl -X POST -H "Authorization: Bearer <派发令牌>" \
  -H "Content-Type: application/json" \
  -d '{"alias":"前门闸机"}' \
  https://access.zhendx.cn/api/device/<DEVICE_SN>/alias

# 5) 导出记录为 CSV
curl -H "Authorization: Bearer <派发令牌>" \
  "https://access.zhendx.cn/api/records?from=2026-07-19%2000:00:00&to=2026-07-25%2023:59:59&format=csv"

# 6) 生成派发令牌（需管理员账号密码登录，凭会话 cookie 调用）
curl -c cookies.txt -d '{"username":"admin","password":"<管理员密码>"}' https://access.zhendx.cn/api/login
curl -b cookies.txt -X POST -H "Content-Type: application/json" \
  -d '{"label":"张三-前端","expires_in_days":90}' \
  https://access.zhendx.cn/api/tokens

五、前端对接要点

六、设备在线 / 离线状态

本页由后端 /docs 路由自动提供 · 与接口实现同源维护