从后端模板迁过来的样式现在真正用上了,并修掉两处不一致:
- 登录页:.panel-switch + .pane-account / .pane-wechat + 右上角 .corner-toggle 三角形切换;
字段改成无 label 的 .field-plain + 悬浮 .tip;验证码用 .input-row 与按钮同行。
- 找回 / 重置密码页:同样换成 .field-plain 紧凑字段。
- 列表页(设备管理 / 扫码记录):AppLayout 支持 fill → 内容区加 .content-fill,
表格包进 .table-wrap → 卡片撑满剩余高度、表头吸顶、只有表格内部滚动、分页贴底。
- 卡片间距交给 .card + .card;测试页结果区改用全局 .json-box 与 .sub-title。
- ⚠️ 修 bug:「注册」标签下注册面板不显示 —— 登录与注册共用 .pane-account,
但 CSS 只写了 .is-login .pane-account / .is-register .pane-register(后者没有对应元素);
同时给 .is-register 补上 padding-top,避免折角三角形压住第一个输入框。
- 顺带去掉不再需要的内联 margin。
验证:vue-tsc + vite build 通过;浏览器实测三个面板都能切换(注册面板 5 个字段可见、
三角形不压输入框),两个列表页 content-fill 生效、整页不滚动、表格内部滚动且表头 sticky。
云仓视频溯源系统(pack-service)
中文名(前端页面/邮件里显示的那个)在
config.siteName里,默认「云仓视频溯源系统」,可用环境变量SITE_NAME覆盖 —— 要改名只改这一处(邮件用app.config.siteName)。pack-service只作为技术标识保留:npm 包名、JWTissuer、日志目录、egg-scripts --title。
基于 Egg.js 3 的纯接口服务(⚠️ 不再渲染任何页面:模板引擎已移除,/ 这一侧由
app/middleware/frontend.js 反代给前端 dev server 或托管 ../frontend/dist),
数据库 MySQL(Sequelize ORM),缓存与登录码用 Redis。
页面在隔壁
../frontend/(Vite + Vue3 + TS SPA);两个服务的端口与启动方式见仓库根目录的README.md。
业务场景:设备(扫描枪 / 中控)扫码登录 —— 设备屏幕显示二维码,已登录的手机确认一下; 服务端在确认那一刻才把设备注册到那个账号名下,并下发长期 JWT(默认 1 年,库里存
jti可随时撤销), 之后设备调本服务的接口都靠这枚令牌鉴权。只有这一条身份链路(没有 sn + secret 那套)。
环境要求
- Node.js >= 18(Egg 3 要求 >= 14.20,建议用 18/20 LTS)
- MySQL 5.7+ / 8.x
- Redis 5+
目录结构
packService/backend
├── app
│ ├── controller # **按「谁在调」分模块**(Egg 支持多级目录 → controller.internal.user)
│ │ ├── home.js # GET /api/info 服务信息(公共)
│ │ ├── health.js # GET /health 健康检查(公共)
│ │ ├── web/ # **用户端(前端 SPA)**:user JWT(typ=user),只能动自己的数据
│ │ │ ├── auth.js # /api/web/auth/{login,register,register/code,forgot,reset}
│ │ │ ├── profile.js # /api/web/me [/password] 我的资料 / 改密码
│ │ │ ├── stats.js # /api/web/stats 首页统计(按当前用户)
│ │ │ ├── device.js # /api/web/devices* 我的设备(列表/详情/通道/解绑/删除)
│ │ │ ├── record.js # /api/web/records 我的扫码记录(按自己设备过滤)
│ │ │ └── test.js # /api/web/test/{device-login,scan} 前端测试页的模拟接口
│ │ ├── internal/ # 运维/内部(❗需内部令牌,挂在 middleware.internalAuth() 后面)
│ │ │ ├── user.js # /api/users* 用户 CRUD(含缓存)
│ │ │ ├── wechat.js # /api/wechat/:appid/:openid、bind、tokens、解绑、用户的授权列表
│ │ │ ├── config.js # /api/configs* 系统配置读写
│ │ │ └── device.js # /api/scanners*、/api/scanner/{bind,unbind} 设备列表/详情/解绑/删除
│ │ ├── auth/ # 公开的登录接口(发码 / 查码 / 微信回调,无需令牌)
│ │ │ └── wechat.js # /api/wechat/{login,status,qrcode.svg,callback}
│ │ ├── client/ # 小程序 / Win 客户端 / SPA(user JWT,typ=user)
│ │ │ └── wechat.js # /api/wechat/confirm
│ │ └── device/ # 设备(长期 JWT,typ=scanner)
│ │ ├── auth.js # /api/device/login 扫码登录+注册(登录即注册,下发长期 JWT)
│ │ ├── self.js # /api/scanner/{me,heartbeat} 自检 / 保活
│ │ └── scan.js # /api/scan/* 中控上报通道 / 扫码记录(去重)
│ ├── middleware
│ │ ├── api_auth.js # **用户端接口鉴权(只认 header 令牌,不看 cookie/session)**
│ │ ├── internal_auth.js # **运维/内部接口鉴权**(X-Internal-Token 或白名单账号的 user JWT)
│ │ ├── scanner_auth.js # 扫描器 JWT 鉴权(Authorization: Bearer <token>)
│ │ ├── frontend.js # **前端入口**:dev 反代前端 dev server / 生产托管 frontend/dist(SPA 回退)
│ │ └── error_handler.js # 异常统一成 JSON(4xx 原消息 / 5xx 只回「服务器内部错误」)
│ ├── model
│ │ ├── user.js # users
│ │ ├── wechat_oauth.js # wechat_oauth
│ │ ├── sys_config.js # sys_config
│ │ ├── scanner.js # scanners
│ │ ├── scan_channel.js # scan_channels
│ │ └── scan_record.js # scan_records(去重)
│ ├── service
│ │ ├── auth.js # 登录校验(bcrypt 密码比对)+ 自助注册
│ │ ├── mail.js # 发邮件(邮箱验证码 / 重置密码链接;开发模式只写日志)
│ │ ├── verify_code.js # 邮箱验证码:生成/发送/校验/消费(Redis 存储 + 重发节流)
│ │ ├── wechat_login.js # 微信扫码登录:二维码本地生成 / 扫码状态机 / code 换 openid
│ │ ├── password_reset.js # 找回密码:重置令牌生成/校验/消费(Redis 存摘要 + 旧链接失效 + 重发节流)
│ │ ├── cache.js # Redis 封装(JSON 序列化 / 过期 / cache-aside / 降级)
│ │ ├── config.js # 配置读写(带 Redis 缓存)
│ │ ├── jwt.js # 令牌签发 / 校验(HS256 + typ + jti,见下文)
│ │ ├── scanner.js # 设备记录:扫码登录即注册 + 绑定/解绑/心跳(只认长期 JWT)
│ │ ├── scan.js # 中控通道上报 / 扫码入库去重 / 扫码查询
│ │ ├── health.js # MySQL / Redis 连通性探测
│ │ ├── user.js # 用户数据访问(app.model.User)
│ │ └── wechat.js # 微信授权数据访问
│ └── router.js
├── config
│ ├── config.default.js # 统一配置(连接 / 端口 / 安全 / 前端入口 / 内部鉴权)
│ ├── config.local.js # 本机密码等(已 gitignore,仅 env=local 加载)
│ ├── config.unittest.js # 单测用的固定内部令牌
│ ├── plugin.js # 只开 sequelize / redis
│ └── plugin.unittest.js # 单测环境关闭 DB 相关插件
├── scripts
│ ├── db-config.js # 脚本共用的连接信息解析
│ ├── init-db.js # 执行 sql 下的 SQL 文件(npm run db:init [file])
│ └── set-password.js # 创建用户/重置密码(npm run user:pass -- 账号 密码)
├── sql
│ ├── schema.sql # 建表脚本(幂等)
│ └── migrations/ # 一次性数据迁移脚本
├── test
│ ├── utils/fake-redis.js # 单测用的内存版 Redis
│ └── utils/internal.js # 内部接口鉴权 header(X-Internal-Token)
└── package.json
快速开始
# 1. 安装依赖
npm install
# 2. 填写本机连接信息:编辑 config/config.local.js(该文件已被 .gitignore 忽略)
# - mysql.client.password = MySQL(127.0.0.1:3307,账号 packservice) 的密码
# - redis.client.password / db = Redis 的密码(无密码写 null)与库序号(本机用 1)
# 也可以改用环境变量 MYSQL_PASSWORD / REDIS_PASSWORD / REDIS_DB
# 3. 建表(库 packservice 需已存在,账号 packservice 仅有该库权限)
npm run db:init
# 如果是旧版本库,按顺序补跑迁移:
# npm run db:init sql/migrations/20261016_rebuild_users.sql # users 表结构重建
# npm run db:init sql/migrations/20261016_add_user_password.sql # 增加 password_hash
# npm run db:init sql/migrations/20261016_devices_to_scanners.sql # 删掉旧的 devices 表(改用 scanners)
# npm run db:init sql/migrations/20261016_add_user_email.sql # users 增加 email(可当登录账号)
# 4. 建一个登录账号(不存在会直接创建,密码 bcrypt 入库)
npm run user:pass -- admin 123456 管理员
# 5. 启动(默认 http://127.0.0.1:7001)
# 登录页:http://127.0.0.1:7001/login(用上面的账号登录)
npm run dev
# 本地测试想要一个“专用端口”(默认 7300,可与 npm run dev 同时开):
npm run dev:test
# → http://127.0.0.1:7300 ;想换端口:egg-bin dev --port 7400,或 $env:PORT=7400; npm run dev
# 两实例并存时给测试实例单独日志目录:$env:LOG_DIR='logs-test'; npm run dev:test
# 生产模式
npm start # egg-scripts 后台启动
npm stop
验证:
curl -I http://127.0.0.1:7001/login # 200:反代到前端 dev server(前端没起则 502 提示页)
curl http://127.0.0.1:7001/health
curl http://127.0.0.1:7001/api/users # 401:内部接口要令牌(X-Internal-Token 或管理员 user JWT)
curl -H 'X-Internal-Token: <INTERNAL_TOKEN>' http://127.0.0.1:7001/api/users # 200
后端只管接口:页面在
../frontend/(npm run dev起在 7301)。 联调推荐只开后端地址http://127.0.0.1:7001(dev 环境自动把页面请求反代给前端);也可以直接开前端 7301(Vite 把/api反代到 7001)。
单元测试
npm test # 无需本机启动 MySQL / Redis
npm run cov
本地专用测试端口(npm run dev:test)
-
npm run dev:test=egg-bin dev --port 7300(可与 7001 的npm run dev同时跑);端口也可用环境变量PORT覆盖(egg-cluster 会读process.env.PORT),config.cluster.listen.port的默认值是Number(PORT || 7001); -
登录态是共享的:cookie(
packs_sess)不带端口,127.0.0.1:7001的登录 cookie 在127.0.0.1:7300一样有效,换端口不用重新登录;两个实例也共用同一套 MySQL / Redis(都读config/config.local.js); -
扫码二维码地址会自动跟随端口:二维码内容是
ctx.origin拼的http://<当前访问的 host:port>/wechat?spm=1.0.<码>.1,所以在 7300 打开的登录页,扫出来的就是 7300 的地址,不用改配置;邮件里的重置链接同理(config.email.siteUrl || ctx.origin),只有显式配了SITE_URL才需要跟着改; -
两个实例并存时日志默认都写
logs/pack-service/,想分开就$env:LOG_DIR='logs-test'; npm run dev:test(PowerShell)/LOG_DIR=logs-test npm run dev:test(bash); -
npm test是单测(不监听固定端口),和这两个端口不冲突; -
config/plugin.unittest.js在测试环境关闭sequelize与redis插件(这两个插件在启动时都会连库); -
测试中用
mock(app, 'model', fakeModel)/mock(app, 'redis', fakeRedis)注入假实现,因此 CI 上不依赖外部服务。
环境变量
不配置时使用默认值(127.0.0.1:3307 / 账号 packservice / 库名 packservice,密码为空需在 config/config.local.js 填)。
| 变量 | 默认值 | 说明 |
|---|---|---|
MYSQL_HOST |
127.0.0.1 |
MySQL 地址 |
MYSQL_PORT |
3307 |
MySQL 端口 |
MYSQL_USER |
packservice |
用户名(大小写敏感) |
MYSQL_PASSWORD |
空 | 密码,本地放 config/config.local.js |
MYSQL_DATABASE |
packservice |
库名 |
MYSQL_POOL_SIZE |
10 |
Sequelize 连接池上限(pool.max) |
REDIS_HOST |
127.0.0.1 |
Redis 地址 |
REDIS_PORT |
6379 |
Redis 端口 |
REDIS_PASSWORD |
空(null) |
密码,无密码时必须为空 |
REDIS_DB |
0 |
库序号 |
CACHE_PREFIX |
packs: |
业务缓存 key 前缀 |
CACHE_TTL |
300 |
默认缓存过期(秒) |
JWT_SECRET |
开发默认值 | 扫描器 JWT 签名密钥,生产未设置会启动失败 |
SITE_NAME |
云仓视频溯源系统 |
站点/产品中文名(页面标题、侧边栏品牌、邮件主题与正文都用它) |
SCANNER_JWT_EXPIRES |
365d |
扫描器长期 JWT 默认有效期(jsonwebtoken 语法,如 30d / 720h) |
DEVICE_JWT_EXPIRES |
同 SCANNER_JWT_EXPIRES |
/api/device/login 下发令牌的默认时长 + 上限;设备可用 ?expiresIn=30d 申请更短的,不能更长 |
REGISTER_ENABLED |
true |
是否允许登录页自助注册(false/0/no/off 关闭;生产建议关掉,用 npm run user:pass 建号) |
SMTP_HOST |
空 | SMTP 主机;不配就走开发模式(验证码只写日志 + 注册页回显,不发真邮件) |
SMTP_PORT |
465 |
SMTP 端口 |
SMTP_SECURE |
true |
是否用 TLS(465 用 true,587 用 false) |
SMTP_USER / SMTP_PASSWORD |
空 | SMTP 账号密码(放 config/config.local.js 或环境变量) |
SMTP_FROM |
云仓视频溯源系统 <no-reply@...> |
发件人(默认取 SITE_NAME 作显示名) |
EMAIL_CODE_TTL |
600 |
邮箱验证码有效期(秒) |
EMAIL_CODE_RESEND |
60 |
同一邮箱重发验证码的间隔(秒) |
EMAIL_CODE_ATTEMPTS |
5 |
同一个验证码最多校验几次(超过则作废) |
EMAIL_RESET_TTL |
1800 |
重置密码链接有效期(秒,默认 30 分钟) |
SITE_URL |
空 | 邮件里重置链接的站点地址(如 https://packs.example.com);不配则用当前请求的 host |
WECHAT_APPID |
空 | 微信开放平台网站应用 appid;不配时登录页二维码退化为本地演示码(不会假装能用) |
WECHAT_SECRET |
空 | 同上对应的 appsecret |
WECHAT_REDIRECT_URI |
空 | 扫码回调地址(需与开放平台后台配置一致);不配则按当前请求 origin 拼 /login/wechat/callback |
WECHAT_API_BASE |
https://api.weixin.qq.com |
微信接口域名(自建网关/联调时可改) |
WECHAT_QR_CELL / WECHAT_QR_MARGIN |
6 / 4 |
二维码 SVG 的单元格像素 / 静默区格数(⚠️ 库的 margin 参数单位是像素,代码里已按格×单元格换算;<4 格会影响扫码) |
WECHAT_STATE_TTL |
600 |
扫码串码(二维码)有效期(秒) |
WECHAT_CODE_LENGTH |
6 |
扫码串码长度(数字 + 大写字母,去掉了 0/O/1/I 等易混字符) |
WECHAT_SPM_PATTERN |
1.0.{code}.1 |
二维码地址里的 spm 格式({code} 会被替换成串码) |
USER_JWT_EXPIRES |
7d |
扫码登录接口下发的用户 JWT 有效期 |
WECHAT_POLL_WAIT |
60 |
扫码登录接口长轮询最多挂起多少秒(前端自己的超时建议再 +10s;反代注意 proxy_read_timeout 要大于它) |
Windows PowerShell 示例:
$env:MYSQL_PASSWORD = 'your-pass'; $env:REDIS_PASSWORD = 'your-pass'; npm run dev
数据表
六张表统一约定:BIGINT UNSIGNED 自增主键、created_at / updated_at、deleted_at(软删除,Sequelize paranoid: true)、status 状态位。
users 用户表
| 字段 | 类型 | 说明 |
|---|---|---|
| id | bigint unsigned | 主键 |
| username | varchar(64) | 登录名,唯一,可空(纯微信登录可不设) |
| nickname | varchar(64) | 昵称 |
| varchar(128) | 邮箱,唯一、可空;注册可选填,可当登录账号(入库统一转小写) | |
| avatar | varchar(255) | 头像 |
| phone | varchar(20) | 手机号,唯一 |
| gender | tinyint unsigned | 0 未知 / 1 男 / 2 女 |
| status | tinyint unsigned | 1 正常 / 0 禁用 |
| remark | varchar(255) | 备注 |
| last_login_at | datetime | 最近登录时间 |
| created_at / updated_at / deleted_at | datetime | 时间戳与软删除 |
wechat_oauth 微信授权表
一条记录 = 某用户在某 appid 下的一次授权,一个用户可绑定多个微信。
| 字段 | 类型 | 说明 |
|---|---|---|
| id | bigint unsigned | 主键 |
| user_id | bigint unsigned | 关联 users.id |
| appid | varchar(64) | 微信 appid,与 openid 组成唯一键 |
| openid | varchar(64) | 用户在该 appid 下的 openid |
| unionid | varchar(64) | 开放平台 unionid |
| nickname / avatar | varchar | 授权时的微信资料 |
| session_key | varchar(128) | 小程序 session_key |
| access_token / refresh_token | varchar(512) | 网页授权令牌 |
| scope | varchar(64) | 授权 scope |
| token_expires_at | datetime | access_token 过期时间 |
| last_auth_at | datetime | 最近授权时间 |
| created_at / updated_at / deleted_at | datetime | 时间戳与软删除 |
sys_config 系统配置表
group_name + config_key 唯一定位一条配置,value_type 决定 config_value 的解析方式(string / number / boolean / json)。
注意:本表用软删除,若建唯一索引会被已删除的记录占用,导致同 key 无法重建,因此唯一性由 service 层保证(先查后写),表上只建普通索引。
scanners 设备表
设备(条码/二维码扫描枪、中控)扫码登录时自动注册,user_id 为空表示尚未绑定账号
(设备归哪个账号由「扫码确认」的人决定,也可由管理员解绑)。
| 字段 | 类型 | 说明 |
|---|---|---|
| id | bigint unsigned | 主键 |
| user_id | bigint unsigned | 绑定的用户 id,未绑定为 NULL |
| sn | varchar(64) | 设备 SN,唯一(设备唯一标识;设备不传时由服务端生成 DEV-…) |
| name / model / vendor / firmware | varchar | 名称、型号、厂商、固件/客户端版本 |
| ip | varchar(45) | 最近登录 IP |
| secret_hash | varchar(100) | 历史字段(早期 sn+secret 登录用),现已不再写入 |
| token_jti | varchar(64) | 当前长期 JWT 的 jti,唯一;库里不存令牌本体 |
| token_expires_at | datetime | 令牌过期时间(默认 365 天) |
| status | tinyint unsigned | 1 正常 / 0 禁用(禁用后登录与所有带令牌的接口都 403) |
| last_register_at / last_login_at / last_seen_at | datetime | 最近注册、最近登录、最近心跳时间 |
| created_at / updated_at / deleted_at | datetime | 时间戳与软删除 |
设备接入流程(只有一条链路):
- 拿令牌(也就是注册):
GET /api/device/login(公开,无需任何凭据):- ① 不带参数 → 返回登录码 + 二维码地址(
qrContent/qrImageUrl),此时库里还没有任何记录; - ② 手机用
POST /api/wechat/confirm确认(已登录用户); - ③ 设备带
?code=&wait=60长轮询 → 这一边才注册:按 SN 建/取记录、绑定到确认登录的账号,并拿到长期 JWT;
- ① 不带参数 → 返回登录码 + 二维码地址(
- 用令牌:之后所有请求带
Authorization: Bearer <JWT>;GET /api/scanner/me自检、POST /api/scanner/heartbeat保活(刷新last_seen_at)、/api/scan/*上报; - 令牌到期 / 设备重装:再扫一次码即可(不需要密钥:设备屏幕出码、人确认一下)—— 记录已存在时不重复建,只换发新令牌;
- 换人使用(设备转让):先由原账号在
/scanners解绑(或管理侧POST /api/scanner/unbind),新使用人再扫码登录即可认领; - SN 曾经被删除过也能继续用同一个 SN:扫码登录会把那条软删除的记录复活(id 不变、
deleted_at清空)—— 软删行仍占着sn唯一键,不复活就会撞键。
历史变更:早期的
POST /api/scanner/register(自己注册拿 sn+secret)与POST /api/scanner/login(sn+secret 换令牌) 已下线(跟扫码登录重复,而且会先建出一条user_id = NULL的无主记录);设备身份现在只有长期 JWT 一种。
设备通讯用的长期 JWT
- 算法 HS256,
issuer = pack-service、audience = scanner,payload 含sub(设备 id)/sn/typ: 'scanner'/jti; - 有效期:默认 365 天(
config.jwt.deviceExpiresIn,envDEVICE_JWT_EXPIRES,不配就跟SCANNER_JWT_EXPIRES走);设备可用?expiresIn=30d(或秒数)申请更短的,超上限 422; - 可撤销:每次扫码登录都会生成新的
jti写库(scanners.token_jti),旧令牌因jti不匹配立即 401;把status置 0 也可让令牌失效(403); - 令牌本体不落库(只存
jti);列表/详情/me等响应都不返回token_jti(app/service/scanner.js的sanitize()兜底清洗); - 签名密钥取
config.jwt.secret(来自JWT_SECRET),生产环境未设置会直接启动失败。
令牌取用顺序:Authorization: Bearer <token> → X-Scanner-Token → ?access_token=(见 app/middleware/scanner_auth.js)。
scan_channels 扫描中控通道表
「中控」就是绑定端(复用 scanners,用自己的 sn + 长期 JWT 上报):一台中控可接多个扫码设备,
每个扫码设备对应一个通道,中控把 通道 id + 通道名 上报上来,一个通道一行。
| 字段 | 类型 | 说明 |
|---|---|---|
| id | bigint unsigned | 主键 |
| scanner_id | bigint unsigned | 上报的中控(= scanners.id) |
| channel_id | varchar(64) | 通道 id(中控上报,同一中控内唯一) |
| channel_name | varchar(128) | 通道名(中控上报) |
| last_report_at | datetime | 最近一次上报时间 |
| status | tinyint unsigned | 1 正常 / 0 停用 |
| created_at / updated_at / deleted_at | datetime | 时间戳与软删除 |
- 唯一键
(scanner_id, channel_id):同一中控重复上报同一个通道 = 更新通道名与last_report_at,不会重复建行; - 因为
channel_id只在同一中控内唯一,所以关联/去重都必须带上scanner_id; - 用软删除:曾被停用(
deleted_at非空)的通道再次上报时会自动「复活」。
scan_records 扫码记录表
中控上报的扫码流水:条码 + 扫描时间 + 通道 id,需要去重存储。
| 字段 | 类型 | 说明 |
|---|---|---|
| id | bigint unsigned | 主键 |
| scanner_id | bigint unsigned | 上报的中控(= scanners.id) |
| channel_id | varchar(64) | 通道 id |
| barcode | varchar(255) | 条码内容 |
| scan_time | datetime | 扫描时间(中控上报,精确到秒,去重键之一) |
| reported_at | datetime | 服务端接收时间 |
| created_at / updated_at | datetime | 时间戳 |
去重规则(唯一键 uk_scan_dedup = (scanner_id, channel_id, barcode, scan_time)):
- 同一中控 + 同一通道 + 同一条码 + 同一扫描时间(秒) 只入库一次,重复上报不会报错,接口返回
duplicated计数; - 上报前先用一次查询(按中控 + 通道 + 时间范围)捞出已存在的记录做过滤,剩下的批量插入;
真出现并发撞唯一键时会自动退化成逐条插入,撞上的计入
duplicated; - 同一批里完全相同的上报也只留一条(内存里先去重);
- 条码相同但时间或通道不同 → 视为两条不同记录;
- 时间精度到秒:
scan_time会先把毫秒截断,再做去重与入库(同一秒内的同条码算重复)。
本表不用软删除(paranoid 关闭):软删除会让记录占用唯一键,导致同一条扫码数据再也无法入库; 需要清理请按时间物理删除:
DELETE FROM scan_records WHERE scan_time < ?。
页面(在前端项目里)
⚠️ 后端不再渲染页面:app/view/、nunjucks、session、CSRF 都已移除,app/controller/page/ 也删掉了。
登录 / 注册 / 找回密码 / 扫码确认 / 首页 / 设备管理 / 扫码记录 / 个人中心 / 测试页
全都在 ../frontend/(Vite + Vue3 + TS 的 SPA)里,通过下面的 JSON 接口通讯:
| 页面 | 前端路由 | 用到的接口 |
|---|---|---|
| 登录 / 注册 / 扫码 | /login |
/api/web/auth/*、/api/wechat/{login,status,qrcode.svg} |
| 手机确认登录 | /wechat?spm=… |
/api/wechat/confirm |
| 忘记 / 重置密码 | /forgot、/reset |
/api/web/auth/{forgot,reset} |
| 首页统计 | / |
/api/web/stats |
| 设备管理 | /devices |
/api/web/devices* |
| 扫码记录 | /records |
/api/web/records |
| 个人中心 | /profile |
/api/web/me* |
| 测试页 | /test |
/api/web/test/*、/api/wechat/{status,confirm} |
后端怎么把页面交出去(app/middleware/frontend.js,只接管「非 /api、/health」的 GET/HEAD 请求):
- 开发(
env=local):反代到FRONTEND_DEV_SERVER(默认http://127.0.0.1:7301,即frontend/ && npm run dev), 包含 HMR 的 WebSocket 升级 —— 所以联调只开http://127.0.0.1:7001一个地址就够(前端热更新照常生效); 前端没起来时会回一个 502 提示页,而不是白屏; - 生产:托管
FRONTEND_DIST(默认../frontend/dist);找不到文件且请求要 HTML 时回退index.html(SPA 深链/devices刷新不会 404);dist 不存在时回 503 并提示先npm run build; - 单测(
env=unittest):整个中间件跳过(不连前端、也不要求 dist 存在)。
接口
按调用方分模块(目录 / 鉴权 / 路径 一一对应)
| 调用方 | 控制器目录 | 鉴权 | 典型接口 |
|---|---|---|---|
| 用户端(前端 SPA) | app/controller/web/ |
middleware.apiAuth()(user JWT,typ=user);登录/注册/找回免令牌 |
/api/web/{auth/*,me*,stats,devices*,records,test/*} |
| 运维 / 内部(运维脚本、后台系统) | app/controller/internal/ |
middleware.internalAuth()(X-Internal-Token 或白名单账号的 user JWT) |
/api/users*、/api/configs*、/api/scanners*、/api/scanner/{bind,unbind}、/api/wechat/{bind,:id/tokens} |
| 用户态(小程序 / Win 客户端) | app/controller/client/ |
middleware.apiAuth()(user JWT,typ=user) |
/api/wechat/confirm |
| 设备(扫描枪 / 中控) | app/controller/device/ |
middleware.scannerAuth()(device JWT,typ=scanner) |
/api/device/login、/api/scanner/{me,heartbeat}、/api/scan/* |
| 公开登录接口 | app/controller/auth/ |
无 | /api/wechat/{login,status,qrcode.svg,callback}(/api/device/login 的发码也无需凭据) |
| 公共 | home.js / health.js |
无 | /api/info、/health |
- 小程序与 Win 客户端共用
client/那一套:它们身份相同(都是「某个登录用户」),业务接口不该复制两份;要区分用途用 header(如X-Client: miniapp|win)或令牌里的自定义声明,别用路径分叉。 - 令牌层是硬隔离:
verifyUser()只认typ: 'user'(默认 7d),verifyScanner()只认typ: 'scanner'(默认 365d)——用户令牌调设备接口、设备令牌调用户接口都直接 401。 (⚠️ 两个verify*都必须比对typ:用户令牌与设备令牌用的是同一把密钥,不比对的话用户令牌就能当设备令牌用。) - 前端只能碰自己的数据:
/api/web/devices*、/api/web/records、/api/web/stats的过滤条件一律取令牌里的userId,前端传的userId/deviceId越权一概 404(不泄露别人有没有这台设备)。 - 服务层不按调用方分:
app/service/按领域拆文件(scanner/scan/user/config/wechat/wechat_login/jwt/cache/mail/verify_code/password_reset),因为设备与内部接口会共用同一个领域服务(如service.scanner既被device/*也被internal/device.js调用);app/model/按表拆。 - Egg 支持多级目录:
app/controller/internal/user.js→controller.internal.user(路由里就是这么引用的),typings/会自动重新生成。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/info |
服务信息(JSON) |
| GET | /health |
健康检查,MySQL 或 Redis 不可用时返回 503 |
| GET | /api/users?page=1&pageSize=20&keyword=&status= |
用户分页(keyword 模糊匹配昵称/登录名/手机号) |
| GET | /api/users/:id |
用户详情(Redis 缓存 → 回源数据库) |
| POST | /api/users |
新增,body: {"username":"zhangsan","nickname":"张三","phone":"13800000000"} |
| PUT | /api/users/:id |
更新(清除该用户缓存) |
| DELETE | /api/users/:id |
软删除(清除该用户缓存) |
| GET | /api/users/:id/wechats |
某用户的全部微信授权 |
| GET | /api/wechat/:appid/:openid |
按 appid + openid 反查授权与关联用户 |
| POST | /api/wechat/bind |
绑定/更新授权,body: {"userId":1,"appid":"wx123","openid":"o_abc"} |
| PUT | /api/wechat/:id/tokens |
更新 session_key / 令牌,body: {"sessionKey":"sk","expiresIn":7200} |
| DELETE | /api/wechat/:id |
解绑(软删除) |
| GET | /api/configs?group=wechat |
配置列表(管理用,含禁用项) |
| GET | /api/configs/:group/:key |
取单个配置值(带 Redis 缓存) |
| GET | /api/configs/:group |
取分组内所有启用配置 |
| PUT | /api/configs |
新增/更新(幂等),body: {"groupName":"wechat","configKey":"appid","configValue":"wx123"} |
| DELETE | /api/configs/:group/:key |
软删除(清缓存) |
| GET | /api/device/login |
设备「扫码登录 + 注册」(参考 /api/wechat/login,但下发长期 JWT):不需要凭据、不需要预先注册(公开接口);?sn=/name/vendor/model/firmware 可选(发码时带上最省事,服务端会暂存)、?expiresIn=30d 可选(只能比服务端上限短);不带 code → 发登录码(code / spm / qrContent(二维码要编的完整网址) / qrImageUrl(完整地址的 SVG));带 ?code=&wait=N → 长轮询,手机用 POST /api/wechat/confirm 确认后立即返回 { firstTime, sn, token, expiresIn, expiresAt, scanner, user },注册/绑定就发生在这一刻(SN 已属于别人 → 403) |
| POST | /api/scanner/bind |
管理侧:把设备绑定到账号,body: { sn, username } 或 { sn, userId } |
| POST | /api/scanner/unbind |
管理侧:解绑,body: { sn }(设备可再扫码重新认领) |
| GET | /api/scanner/me |
需 JWT:返回当前设备信息(自检连通性) |
| POST | /api/scanner/heartbeat |
需 JWT:保活,刷新 last_seen_at 并返回服务端时间 |
| GET | /api/scanners?page=&pageSize=&keyword=&userId=&status= |
设备列表(带绑定账号;管理侧) |
| GET | /api/scanners/:id |
扫描器详情 |
| DELETE | /api/scanners/:id |
软删除扫描器 |
| POST | /api/scan/channels |
需扫描器 JWT:中控上报通道,body: { channels: [{ channelId, channelName }] }(单条也可)→ { created, updated, invalid, errors } |
| GET | /api/scan/channels?page=&pageSize=&keyword=&status= |
需扫描器 JWT:当前中控已登记的通道 |
| POST | /api/scan/records |
需扫描器 JWT:中控上报扫码,body: { records: [{ barcode, scanTime, channelId }] } → { received, inserted, duplicated, invalid, unknownChannels } |
| GET | /api/scan/records?page=&pageSize=&channelId=&barcode=&startTime=&endTime= |
需扫描器 JWT:当前中控上报的扫码记录 |
扫码上报的两个接口都不会因为重复而报错(幂等):重复条数计入 duplicated;
单条非法(缺条码 / 时间非法 / 超长)会被跳过并计入 invalid + errors;整体为空数组才返回 422。
上报还支持 records 传 JSON 字符串(部分设备端会这么塞);上报成功会顺手刷新中控心跳与通道的 last_report_at,
遇到未登记的通道会自动补建一行(channel_name 留空,同时记 WARN 日志)。
统一响应格式:成功 { "ok": true, "data": ... };失败 { "ok": false, "message": "..." }(由 app/middleware/error_handler.js 保证 4xx/5xx 也返回 JSON);
接口路径写错(没匹配到路由)也是 JSON:404 { ok:false, message:'接口不存在' }(不会再返 HTML 404 页把客户端的 JSON 解析弄挂)。
扫描器 JWT 鉴权结果:缺令牌 / 签名不对 / 已过期 / jti 已被轮换 / 扫描器不存在 → 401;扫描器被禁用 → 403。
用法速查
// ===== MySQL:Sequelize 模型(定义在 app/model/*.js)=====
// 通过 app.model.User / this.app.model.User / ctx.model.User 访问
const { User, WechatOauth, SysConfig } = this.app.model;
await User.findByPk(1); // 主键查询
await User.findOne({ where: { username: 'zhangsan' } });
await User.findAll({ where: { status: 1 }, limit: 10, offset: 0, order: [[ 'id', 'DESC' ]] });
const { rows, count } = await User.findAndCountAll({ limit: 10 }); // 分页
await User.create({ username: 'zhangsan', nickname: '张三' }); // 新增(自动写 created_at/updated_at)
await User.update({ status: 0 }, { where: { id: 1 } }); // 更新
await User.destroy({ where: { id: 1 } }); // 删除(paranoid 模型 = 软删除)
await User.destroy({ where: { id: 1 }, force: true }); // 物理删除
// 关联查询:一个用户的多条微信授权
const withWechats = await User.findOne({ where: { id: 1 }, include: [{ model: WechatOauth, as: 'wechats' }] });
// 原生 SQL / 事务
const [rows2] = await this.app.model.query('SELECT 1 AS ok');
await this.app.model.transaction(async t => {
await User.create({ nickname: 'a' }, { transaction: t });
await User.create({ nickname: 'b' }, { transaction: t });
});
// 操作符:const { Op } = require('sequelize');
// ===== 系统配置:带 Redis 缓存,写入自动失效 =====
const appid = await this.ctx.service.config.get('wechat', 'appid'); // value_type=number/json/boolean 会自动转换
await this.ctx.service.config.set({ groupName: 'wechat', configKey: 'appid', configValue: 'wx123' });
const groupConfig = await this.ctx.service.config.getGroup('wechat'); // { appid: 'wx123', ... }
await this.ctx.service.config.remove('wechat', 'appid'); // 软删除 + 清缓存
// ===== 微信授权 =====
await this.ctx.service.wechat.bind({ userId: 1, appid: 'wx123', openid: 'o_abc', nickname: '微信昵称' });
const oauth = await this.ctx.service.wechat.findByOpenid('wx123', 'o_abc'); // 带关联用户
const user = await this.ctx.service.user.findByOpenid('wx123', 'o_abc'); // 直接拿用户
// ===== 扫描器长期 JWT(app/service/jwt.js)=====
const jwtToken = this.ctx.service.jwt.signScanner(scanner, { jti: 'uuid' }); // 签发
this.ctx.service.jwt.verifyScanner(jwtToken); // 校验(失败直接 401)
this.ctx.service.jwt.expiresAtOf(jwtToken); // 取过期时间(Date)
// ===== 设备业务(app/service/scanner.js)=====
// 扫码登录(注册 + 绑定 + 发令牌,一步到位;userId = 扫码确认的那个人)
const login = await this.ctx.service.scanner.loginByScan({
sn: 'SN-001', // 设备自报的 SN(不传则服务端生成 DEV-…)
name: '1 号线扫描枪',
userId: 1, // 来自 POST /api/wechat/confirm 的确认人
expiresIn: undefined, // 可选:秒数;不传用 config.jwt.deviceExpiresIn
});
login.token; // 长期 JWT(365d)
login.firstTime; // true = 本次才注册出这条记录
await this.ctx.service.scanner.heartbeat(scanner, this.ctx.ip); // 心跳:刷新 last_seen_at
await this.ctx.service.scanner.unbind({ sn: 'SN-001' }); // 管理侧解绑
// ===== 扫码信息(app/service/scan.js,scanner = 中控实例)=====
// 1. 中控上报通道(一个通道一行,重复上报只更新通道名)
await this.ctx.service.scan.reportChannels(scanner, [
{ channelId: 'CH-1', channelName: '1 号打包口' },
]);
// → { received, created, updated, invalid, errors, channels }
// 2. 中控上报扫码结果(同一中控+通道+条码+扫描时间(秒) 自动去重)
const ingested = await this.ctx.service.scan.ingest(scanner, [
{ barcode: '6901234567890', scanTime: '2026-10-16 10:20:30', channelId: 'CH-1' },
{ barcode: '6901234567890', scanTime: '2026-10-16 10:20:30', channelId: 'CH-1' }, // 重复 → 只入库一次
]);
// → { received: 2, inserted: 1, duplicated: 1, invalid: 0, unknownChannels: [] }
// 3. 查询(都带分页;记录默认按 scan_time 倒序)
await this.ctx.service.scan.listChannels({ scannerId: scanner.id, keyword: '' });
await this.ctx.service.scan.listRecords({ scannerId: scanner.id, channelId: 'CH-1', barcode: '690' , startTime: '2026-10-16', endTime: '2026-10-17' });
// 时间解析:'2026-10-16 10:20:30' / '2026-10-16T10:20:30' / 10 位秒时间戳 / 13 位毫秒时间戳 都支持(毫秒会被截断)
// ===== Redis:app.redis 即 ioredis 实例 =====
await this.app.redis.set('k', 'v');
await this.app.redis.setex('k', 60, 'v');
await this.app.redis.get('k');
// 项目封装(见 app/service/cache.js)
await this.ctx.service.cache.set('user:1', { id: 1 }, 60);
await this.ctx.service.cache.remember('user:1', 60, () => loadFromMysql());
说明
- MySQL 通过
egg-sequelize@6(Sequelize 6 + mysql2)访问,模型放在app/model/,表结构以sql/schema.sql为准(未开启sequelize.sync,避免误改表);需要同步表结构时可在启动钩子里显式调用app.model.sync()。 - Sequelize 是启动强依赖:插件在
beforeStart里会authenticate(),连不上数据库时应用启动会失败(重试 3 次后退出);Redis 用egg-redis@2(ioredis),配置了client.weakDependent: true,Redis 不可用不阻塞启动。 - 时间统一按
timezone: '+08:00'处理;表名/字段名下划线映射、created_at/updated_at 命名在config.sequelize.define中配置。 - 用户/微信授权/系统配置的
deleted_at为软删除:普通查询自动过滤,需物理删除时加force: true。 wechat_oauth用(appid, openid)唯一键防重;sys_config的唯一性在 service 层保证(原因见「数据表」一节的说明)。- 所有异常经
app/middleware/error_handler.js处理:/api/*、/health(或声明了Accept: application/json的请求)统一返回{ ok:false, message }(4xx 原消息、5xx 只回「服务器内部错误」);其它请求返回一行纯文本(正常情况下它们都被middleware/frontend.js接走了)。 - 没有模板 / 会话 / CSRF:
app/view/、egg-view-nunjucks、egg-session-redis、config.view、config.session全部已删除;接口一律 header 令牌鉴权,config.security.csrf.enable = false(没有基于 cookie 的表单了,CSRF 保护已无意义)。 - 前端的页面与样式在
../frontend/src/:公共样式styles/main.css(卡片 / 表单 / 表格 / 分页 / 徽标),每个页面一个views/*.vue;接口调用统一走api/client.ts(自动带令牌、401 清令牌)+api/web.ts(按接口分组)。 - 登录密码用
bcryptjs哈希(app/service/auth.js,成本因子 10);用户查询默认exclude: ['passwordHash'],任何接口/模板都不会输出哈希。 - 自助注册(接口):前端登录页「注册」tab →
POST /api/web/auth/register/code(发邮箱验证码)→POST /api/web/auth/register→service.auth.register()(user.create+setPassword,用户名/邮箱/手机号重复在 service 层抛 409,接口翻成友好文案)→ 成功直接下发用户 JWT(前端存本地即登录);邮箱必填,格式校验后统一小写入库; - 登录账号支持 用户名 / 手机号 / 邮箱(
service.user.findByAccount()的Op.or同时匹配username/phone/email);邮箱也能在个人中心修改(同样格式校验 + 小写归一 + 唯一性检查);用户列表的keyword也搜邮箱; - 注册开关
config.register.enable(环境变量REGISTER_ENABLED,默认开):关掉后发码与注册接口都返回 403「注册已关闭」;这是面向内部管理的服务,上线建议关闭并用npm run user:pass建号; - 注册必须验证邮箱(邮箱必填):两步——
POST /api/web/auth/register/code发 6 位验证码 →POST /api/web/auth/register带code校验通过才能建号。- 验证码存 Redis(
packs:verify:register:<email>,TTLEMAIL_CODE_TTL,默认 10 分钟);重发节流(SET NX,默认 60 秒);错试超过EMAIL_CODE_ATTEMPTS(默认 5 次)作废;注册成功才消费验证码(用户名/邮箱冲突时可改完重提,不用重新收码); - 发信走
app/service/mail.js:未配SMTP_HOST时是开发模式(验证码写服务端日志 + 在接口返回里带code,前端直接提示,仅本地/测试);配上SMTP_HOST/PORT/USER/PASSWORD/FROM后自动改用 nodemailer 真发信(依赖懒加载); - 验证码逻辑不抛异常,统一返回
{ ok, message },失败都是接口报错(Redis 不可用会提示“验证码服务暂不可用”而不是 500);
- 验证码存 Redis(
- 邮箱找回密码(发重置链接):前端「忘记密码?」页 →
POST /api/web/auth/forgot生成带令牌的链接并发到邮箱 → 邮件里的链接打开前端/reset?token=...设置新密码 →POST /api/web/auth/reset改哈希(不自动登录,要求用新密码再登一次)。- 令牌存 Redis(
app/service/password_reset.js):packs:reset:token:<sha256(令牌)>→ 用户 id(TTLEMAIL_RESET_TTL,默认 30 分钟)、packs:reset:user:<id>→ 当前令牌摘要、packs:reset:sent:<id>重发节流(SET NX,默认 60 秒);Redis 里只存摘要,不存令牌原文(泄库也拿不到可用的链接); - 一次性:重置成功后
consume()删掉令牌;重新申请会让旧链接立刻失效(同一用户只保留最新一条);校验失败的提交(密码太短/两次不一致/令牌不对)不会消费令牌; - 防账号枚举:邮箱格式不对才报错;邮箱未注册或账号被禁用时,提示与成功完全一致(“如果该邮箱已注册,链接已经发出”),并且不发信;
- 邮件正文由
service.mail.sendResetLink()生成(与验证码同一套开发模式/SMTP 逻辑:未配SMTP_HOST时链接写日志 + 接口返回url,前端直接给个可点链接,方便本地点开); - 链接地址默认取当前请求的 host,正式部署建议配
SITE_URL(有反代/多域名时更可靠); - 待加固(按需):JWT 是无状态的,重置密码后旧令牌在过期前仍然有效(要立即失效可给
users加password_changed_at,鉴权中间件里比对);
- 令牌存 Redis(
- 扫码登录(
app/service/wechat_login.js):前端登录页顶部是「登录 / 注册」两个 tab,扫码用右上角的三角形切换(挂在一个.panel-switch容器上,和输入框右边缘对齐;登录/扫码面板定成同高,切换时卡片高度不变):- 串码:服务端生成 6 位数字 + 字母随机串码(
WECHAT_CODE_LENGTH,字符集去掉了 0/O/1/I 等易混字符),写进 Redispacks:wechat:state:<code>=pending(TTLWECHAT_STATE_TTL); - 二维码内容 = 本站地址:
http://<域名>/wechat?spm=1.0.<code>.1(spm 格式由WECHAT_SPM_PATTERN决定);二维码图片本身用零依赖的qrcode-generator现场画成 SVG(GET /api/wechat/qrcode.svg?code=…)——不需要任何外链资源; - 完整时序(都是我们自己的接口,不需要第三方 JS/iframe):
- 电脑端调
GET /api/wechat/login(不带参数)拿code+qrUrl,前端登录页把它画成<img src="/api/wechat/qrcode.svg?code=…">→ 串码登记为pending; - 手机扫码打开前端路由
/wechat?spm=1.0.<code>.1:- 配了微信 → 前端页重定向到公众号网页授权(
oauth2/authorize,scope=snsapi_base静默拿 openid,state=<code>)→ 微信回调后端GET /api/wechat/callback→code换openid(WECHAT_API_BASE)→ 按(appid, openid)查wechat_oauth找账号 → 把 Redis 里串码的值改成用户 id → 再 302 回前端/wechat?ok=1; - 没配微信(本机默认)→ 前端页给「确认登录」按钮:要求手机端已登录(本地有占位令牌),点确认调
POST /api/wechat/confirm(带Authorization: Bearer <user JWT>)把串码的值改成用户 id;
- 配了微信 → 前端页重定向到公众号网页授权(
- 电脑端用
GET /api/wechat/login?code=…&wait=60长轮询取结果 →{ status:'confirmed', token, user }存本地即登录完成(前端登录页会自动跳首页);取走即删(一次性)。
- 电脑端调
- JWT 怎么用:
config.jwt.userExpiresIn(envUSER_JWT_EXPIRES,默认 7 天);前端把令牌存 localStorage,调接口时放Authorization: Bearer <token>(app/middleware/api_auth.js只认这个头,不读 cookie/session)。 - 长轮询(前端接口):
GET /api/wechat/login?code=<code>&wait=60—— 服务端把请求挂起最多WECHAT_POLL_WAIT秒(默认 60):- 有人扫码确认 → 立即返回
{ status:'confirmed', token, … }(靠 Redis 发布订阅packs:wechat:login:<code>唤醒,不是忙轮询;confirm()/ 微信回调写完状态后PUBLISH一次); - 到时间还没动静 / 串码已失效 → 返回
{ status:'refreshed', code:<新码>, spm, qrUrl, expiresIn, waited }—— 前端直接换二维码继续轮询,不用自己判断过期; wait=0或不传 → 不挂起,只回{ status:'pending' }(短轮询模式);- 客户端断开就立即结束挂起(2026-10-17 修):服务端会监听连接关闭(
res.on('close')),浏览器导航离开(例如登录页点「返回账号密码登录」)、关页签或前端abort()时立刻停止等待并释放订阅连接,不会白等满wait秒,也不会把串码换掉(登录页的脚本在pagehide时会abort()当前请求);日志里能看到[wechat] 客户端已断开,停止等待串码 XXXXXX; - ⚠️ 前端要自己设超时(服务端上限 60s,客户端建议 70s):
AbortController/AbortSignal.timeout(70000),超时就重发一次请求(或退化成短轮询);重启/热更也会断掉长连接,断了重试即可。反代/网关要把读超时调到 > 60s(nginxproxy_read_timeout 90s),否则会被代理提前切断;let code = null; async function loop() { const url = code ? `/api/wechat/login?code=${code}&wait=60` : '/api/wechat/login'; const ac = new AbortController(); const timer = setTimeout(() => ac.abort(), 70000); // 前端超时 > 服务端 wait let r; try { r = await (await fetch(url, { signal: ac.signal })).json(); } catch (err) { // 超时/断网 → 重试 return setTimeout(loop, 800); } finally { clearTimeout(timer); } const d = r.data; if (d.status === 'confirmed') return localStorage.setItem('token', d.token); if (d.status === 'refreshed') { code = d.code; img.src = d.qrUrl; } // 换新码 if (!code) { code = d.code; img.src = d.qrUrl; } // 首次拿码 loop(); }
- 有人扫码确认 → 立即返回
- 联调/自测(三个终端就能跑通整个扫码登录):
# ① 电脑端:拿登录码 curl -s http://127.0.0.1:7001/api/wechat/login # → {"ok":true,"data":{"code":"XBUBHP","spm":"1.0.XBUBHP.1","qrUrl":"/login/wechat/qrcode.svg?code=XBUBHP",...}} # ② 电脑端:挂在长轮询上等(25s 内有人确认就立即返回,没人扫就换新码) curl -s 'http://127.0.0.1:7001/api/wechat/login?code=XBUBHP&wait=60' # ③ 已登录的客户端(或用手机打开 /wechat?spm=1.0.XBUBHP.1):用登录码触发登录 curl -s -X POST http://127.0.0.1:7001/api/wechat/confirm \ -H 'Authorization: Bearer <用户JWT>' -H 'Content-Type: application/json' \ -d '{"code":"XBUBHP"}' # → ② 的请求会立即返回 {"data":{"status":"confirmed","token":"<JWT>",...}}POST /api/wechat/confirm的 鉴权完全走 header(app/middleware/api_auth.js:Authorization: Bearer <用户JWT>,也认X-Access-Token)——不读 session/cookie,所以小程序 / App / SPA 直接帯令牌就行,也不写 session;它返回 401(缺令牌)/ 403(账号被禁用)/ 422(码格式不对)/ 410(码失效、已过期或已用过);/api/*不过 CSRF,所以 curl 不用带 token。 - 不自动建号:扫码只对已绑定微信的账号生效(绑定关系在
wechat_oauth,可用POST /api/wechat/bind写入),未绑定会提示先用账号密码登录;账号被禁用(status != 1)拒绝登录; - 小程序接入(小程序里「扫码 → 直接登录电脑端」):接口都是 JSON,鉴权只看 header 里的
Authorization: Bearer <用户 JWT>,不认 cookie/session(app/middleware/api_auth.js);用户 JWT 用USER_JWT_EXPIRES(默认 7d)控制有效期,由登录接口/扫码登录接口下发。
返回:成功// 小程序侧:扫登录页上的二维码(内容 http://<域名>/wechat?spm=1.0.<码>.1) wx.scanCode({ success (scan) { // ① 先问一下这个码还在不在(可选,但能给出更好的提示) wx.request({ url: `https://<域名>/api/wechat/status?spm=${encodeURIComponent(scan.result)}`, success (r) { // r.data.data.status: pending(待扫)/ confirmed(已被确认)/ expired(没这个码) } }); // ② 确认登录:把扫到的整条地址丢进来就行(接口自己抽 6 位码) wx.request({ url: 'https://<域名>/api/wechat/confirm', method: 'POST', header: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + userJwt }, data: { spm: scan.result }, // 也可以传 { code: 'AB12CD' } success (r) { if (r.statusCode === 200 && r.data.data.status === 'confirmed') { wx.showToast({ title: '登录成功' }); // 电脑端那台浏览器已经进系统了 } else { wx.showToast({ title: r.data.message, icon: 'none' }); // 401/422/410 的错误原因 } } }); } });HTTP 200 { ok:true, data:{ status:'confirmed', code, spm, user:{ id, username, nickname } } }; 失败HTTP 401 status=unauthorized(没带/过期令牌)、422 bad_format(码格式不对)、410 expired(没这个码/已过期)、410 used(已被用过); - 设备专用:扫码登录 + 注册(
GET /api/device/login,app/controller/device.js):给「设备上不好敲账号密码、甚至出厂什么都不用配」的场景用—— 登录即注册:设备插上电直接要一个登录码显示在设备屏幕上,用已经登录的手机(小程序/网页)扫一下确认, 服务端这才把设备注册到那个账号名下(归属 = 确认登录的人),并把长期 JWT 发给设备 (默认 365 天,见config.jwt.deviceExpiresIn/ envDEVICE_JWT_EXPIRES; 设备可用?expiresIn=30d(或秒数)申请更短的,超上限 422):- 不需要凭据、也不需要预先注册(与
GET /api/wechat/login一样是公开接口); - 不带
code:发一张新登录码(此时库里还没有任何记录),返回{ status:'pending', expiresIn, code, spm, origin, qrContent, qrImageUrl, qrUrl, device:{ sn, name } }—— 域名不用设备自己拼:qrContent就是二维码里该编的完整网址(http://<域名>/wechat?spm=…),qrImageUrl是完整地址的现成 SVG(设备不会画二维码就直接拉这张图),qrUrl是它的相对路径,origin是本次用的域名; 域名取SITE_URL(config.email.siteUrl)——有反代/多域名、或设备走内网而扫码的手机要走公网时建议配上;没配就用设备请求时的 origin(设备访问服务用的那个地址); - 设备信息(可选):
?sn=(设备序列号)、name/vendor/model/firmware;发码时带上最省事 (服务端暂存packs:device:info:<code>,确认/换码时沿用),轮询时再带(补齐/覆盖)也行;不带 SN 时服务端注册那一步生成一个DEV-…并返回给设备保存; - 带
?code=&wait=N:长轮询(与/api/wechat/login完全同一套实现与上限WECHAT_POLL_WAIT,默认 60s):- 手机确认 → 立即返回
{ status:'confirmed', firstTime, sn, token, tokenType, expiresIn, expiresAt, scanner, user }; - 到时间没人扫 / 码已失效 →
{ status:'refreshed', code:<新码>, spm, qrContent, qrImageUrl, … }(设备换二维码后继续轮询); - 设备断开(重启/换页)→ 服务端立刻停止等待(
aborted,不写响应、也不换码); - 不带
wait就是短轮询,只查一次(pending时还带expiresIn剩余秒数);
- 手机确认 → 立即返回
- 确认仍走现有接口
POST /api/wechat/confirm(不为设备新增确认接口);用的也是同一套 6 位串码, 所以设备码同样能被GET /api/wechat/status查、也能被手机上的/wechat?spm=…页面消费; - 确认成功(就是「注册」发生的时刻,
service/scanner.js的loginByScan()):- 该 SN 没有记录 → 新建:绑到确认的用户,
firstTime: true(记录是在确认那一刻才建的); - 该 SN 已有记录且无主(历史数据里的
user_id = NULL)或曾被软删 → 由确认者认领(软删的restore()复活),firstTime: false; - 该 SN 已绑定到别的账号 → 403,拒绝(避免扫一下就把别人的设备换绑走);设备被禁用(
status=0)→ 403; - 无论哪条路径都会换发长期 JWT(
jti轮换 → 设备上一次的令牌立即失效);
- 该 SN 没有记录 → 新建:绑到确认的用户,
- 登录码一次性:被设备取走即删除(同一张码不能给第二台设备用,浏览器页面长轮询与设备长轮询谁先取走算谁的);
- 联调(新设备不需要先注册;第三终端是已登录的手机/小程序):
# ① 设备发码(拿 code / qrContent / qrImageUrl 显示二维码;带上自己的 SN 与名称) curl -s 'http://127.0.0.1:7001/api/device/login?sn=SN-NEW-01&name=门口扫码枪' # ② 设备挂长轮询(有人确认就立即返回;参数带上也行) curl -s 'http://127.0.0.1:7001/api/device/login?sn=SN-NEW-01&code=<登录码>&wait=60' # ③ 手机确认(现有接口,鉴权走 header,不认 cookie) curl -s -X POST http://127.0.0.1:7001/api/wechat/confirm \ -H 'Authorization: Bearer <用户JWT>' -H 'Content-Type: application/json' \ -d '{"code":"<登录码>"}' # → ② 立即返回 {"data":{"status":"confirmed","firstTime":true,"sn":"SN-NEW-01", # "token":"<长期JWT>","expiresIn":"365d","expiresAt":"...","scanner":{...},"user":{...}}} - 设备端逻辑(伪代码,轮询到
refreshed就换二维码继续):const sn = localStorage.getItem('sn') || 'SN-NEW-01'; // 设备自己的序列号(可固定) let code = null; for (;;) { const url = code ? `/api/device/login?code=${code}&wait=60&sn=${sn}` : `/api/device/login?sn=${sn}&name=门口扫码枪`; const r = await (await fetch(url)).json(); const d = r.data; if (d.status === 'confirmed') { saveToken(d.token); // 长期 JWT(365d),后续请求带 Authorization: Bearer saveSn(d.sn); // 服务端确认的 SN(没自带 SN 时以这个为准) break; } code = d.code; // pending / refreshed 都带回可用的码 showQrcode(d.qrContent); // 直接编 qrContent(已是完整网址,设备无需知道域名) }
- 不需要凭据、也不需要预先注册(与
- 未配
WECHAT_APPID/WECHAT_SECRET(本机默认):二维码照旧本地生成(内容是本站/wechat?spm=…),扫码面板不显示任何说明文字(只留二维码 + 「返回账号密码登录」),扫码后走「手机确认登录」降级路径;
- 串码:服务端生成 6 位数字 + 字母随机串码(
- 新增/重置登录账号:
npm run user:pass -- <账号> <密码> [昵称]。 - 设备身份只有长期 JWT 一种:列表/详情/
me接口不会返回token_jti(sanitize()兜底);secret_hash是历史字段(已不再写入)。 - 软删除的行仍占着唯一键:
scanners.sn是唯一键而deleted_at的软删行还在库里,所以扫码登录(loginByScan())带上已删除的一起查,命中就把那条记录复活(restore(),与scan.js里通道的处理一致),否则create会撞唯一键; - 前端「设备管理」页的解绑/删除按钮调
POST /api/web/devices/:id/unbind与DELETE /api/web/devices/:id;前端「测试页」提交后直接展示结果(含长期 JWT),刷新页签不会重复建设备(同 SN = 同一台,只换发令牌); - 扫描器接口
/api/scanner/{me,heartbeat}走app/middleware/scanner_auth.js的 JWT 鉴权;接口里的“缺令牌→401 / 被禁用→403 / jti 被轮换→401”语义见上文「扫描器通讯用的长期 JWT」; - 设备扫码登录
GET /api/device/login不需要任何凭据、也不需要设备预先注册:发码只写 Redis(库里不建任何东西), 确认成功那一刻(就是「注册」时刻)才按 SN 建/取记录、绑定到确认登录的用户、发长期 JWT;确认环节复用POST /api/wechat/confirm与同一套 6 位串码(service/wechatLogin),不新增确认接口、不新增 Redis key 空间;SN 已属于其他账号 → 403(不会把别人的设备扫走),无主记录(老接口注册出来的)由本次确认者认领; - 没有 CSRF:后端已关掉 CSRF(
config.security.csrf.enable = false),页面表单/会话都没了;扫描器用 JWT 调 JSON 接口不会遇到 403; - 扫码去重放在数据库唯一键 + 服务层预过滤两层:唯一键
(scanner_id, channel_id, barcode, scan_time)是最终保证,服务层先查一次再做批量插入(并发撞键时退化为逐条插入并计数),所以重复上报既不报错也不产生脏数据; - 扫码记录是流水表、不用软删除(
paranoid: false):软删除会让记录占用唯一键,导致同一条数据无法再入库;清理请按时间物理删除; - 中控上报遇到未登记的通道会自动补建一行(
channel_name留空 + WARN 日志),避免丢数据;若希望严格模式,可在app/service/scan.js的touchChannels()里改成抛错; - 前端「测试页」的「模拟中控上报」卡片用设备 SN + 长期 JWT 校验身份(验签 + 回查 + 比对
jti,与middleware/scannerAuth()同一条service.scanner.resolveByToken()),再走service.scan.*,等价于设备的POST /api/scan/channels+POST /api/scan/records(提交两次即可看到duplicated=1);令牌就是上一张卡片发下来的那枚,重新扫码登录会换新令牌(旧令牌立即失效); - 前端「测试页」的「模拟扫码授权(AJAX)」卡片:一个输入框(填登录码,或直接贴
/wechat?spm=…整条地址)+「查状态」「请求登录」两个按钮,AJAX 调接口并把返回的 JSON 原样显示,不跳转:- 「查状态」→
GET /api/wechat/status?code=…(无需登录):pending(待扫码)/confirmed(已被确认)/expired(没这个码); - 「请求登录」→
POST /api/wechat/confirm({ code }):data.status='confirmed'即授权成功,电脑端正在长轮询的请求会立即完成登录;已用过/不存在/格式错分别返回used/expired/bad_format; - 鉴权完全模仿小程序:AJAX 把用户 JWT 放在
Authorization: Bearer头里(fetch不带credentials),页面上也把这枚令牌显示出来方便贴到小程序里调试;
- 「查状态」→
- 鉴权总览:
/api/web/*、/api/wechat/confirm走app/middleware/api_auth.js(只认 header 里的用户令牌);/api/users*、/api/configs*、/api/scanners*走app/middleware/internal_auth.js(X-Internal-Token或白名单账号的 user JWT);/api/scanner/*、/api/scan/*走app/middleware/scanner_auth.js(设备长期 JWT);公开接口只有/api/info、/health、/api/wechat/{login,status,qrcode.svg,callback}、/api/device/login与/api/web/auth/*; - 密码等敏感信息放
config/config.local.js(已 gitignore)或环境变量,不要写进config.default.js。 - 生产环境请修改
config/config.default.js中的config.keys。