liufumingren 228723e0c3 设备端扫码上报 + 桌面端/Android 正式包发布脚手架
AndroidStation(原中控改造为纯设备端)
- 只做三件事:UDP 48899 被桌面端发现、TCP 8087 推送 USB 扫码结果、离线语音播报
- 扫码不再经过 UI:去掉逐键重绘,50ms 自动提交,同一码重复扫码也一律上报
- 离线语音种子(数字/字母/“开始打包”/欢迎语)随包安装,MediaPlayer 播放,启动把音量拉满
- 启动播报「欢迎使用溯源系统,初始化已经完成,扫码即可开始打包」
- 移除 Device Owner / 设备管理员 / lock task / 网络与 IP 设置等非普通应用能力(仅保留开机自启)
- 正式签名 keystore + release 签名配置,versionName/versionCode 可由打包脚本覆盖

发布脚手架
- backend/android_client:Android 正式包构建(build.ps1 + package.config.json)
- backend/scripts/deploy/publish-android.cjs + npm run android:build / android:publish
- 桌面端安装包改为 download/desktop,Android 为 download/android_client;
  version.json 仍走 /download/version.json(老客户端写死),新增 /download/android_client/version.json
- 谷歌插件随桌面端 MSI 安装到 <安装目录>\extension,工具菜单新增「复制谷歌插件地址」
- git-safety-check 增加仓库级禁区(keystore.properties / *.jks / local.properties)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-10-21 05:53:27 +08:00
..

云仓视频溯源系统(pack-service)

中文名(前端页面/邮件里显示的那个)在 config.siteName 里,默认「云仓视频溯源系统」,可用环境变量 SITE_NAME 覆盖 —— 要改名只改这一处(邮件用 app.config.siteName)。 pack-service 只作为技术标识保留:npm 包名、JWT issuer、日志目录、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         # 脚本共用的连接信息解析
│   ├── db-deploy.js         # **部署/升级一次执行**:建库 + 基线表 + 全部未执行迁移(npm run db:deploy [--check])
│   ├── init-db.js           # 执行单个 SQL 文件(npm run db:init [file]),给历史补丁用
│   ├── backfill-snapshot.js # 一次性回填:老扫码记录补工作台快照
│   ├── dedupe-scan-records.js # 一次性去重:24 小时内同一运单只留一条
│   └── set-password.js      # 创建用户/重置密码(npm run user:pass -- 账号 密码)
├── database
│   ├── config.cjs           # sequelize-cli 配置(与运行时同一份连接信息)
│   └── migrations/          # Sequelize 迁移(按文件名顺序,SequelizeMeta 记账,只跑没跑过的)
├── sql
│   ├── schema.sql           # 基线表(幂等,db:deploy 第 1 步执行)
│   └── migrations/          # 历史一次性 SQL 补丁(仅老库需要,保留不删)
├── 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. 建表 / 升级(**部署时只需这一条**:建库(有权限时) + 基线表 + 所有未执行的迁移,可反复执行)
npm run db:deploy
#   npm run db:deploy -- --check     # 只检查还剩哪些迁移没执行(CI / 上线前确认,不改库)
# 老版本的库照常补跑遗留 SQL 补丁(这些脚本都保留在 sql/migrations,新库不需要):
# 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(可当登录账号)
# npm run db:init sql/migrations/20261017_add_user_password_changed_at.sql   # users 增加 password_changed_at(改密后旧 JWT 失效)

# 4. 建一个登录账号(不存在会直接创建,密码 bcrypt 入库)
npm run user:pass -- admin 123456 管理员

# 5. 启动(默认 http://127.0.0.1:7300)
#    登录页:http://127.0.0.1:7300/login(用上面的账号登录)
npm run dev

# 想临时换端口:egg-bin dev --port 7400,或 $env:PORT=7400; npm run dev(默认端口在 config/config.default.js)

# 生产模式
npm start        # egg-scripts 后台启动
npm stop

验证:

curl -I http://127.0.0.1:7300/login      # 200:反代到前端 dev server(前端没起则 502 提示页)
curl    http://127.0.0.1:7300/health
curl    http://127.0.0.1:7300/api/users  # 401:内部接口要令牌(X-Internal-Token 或管理员 user JWT)
curl -H 'X-Internal-Token: <INTERNAL_TOKEN>' http://127.0.0.1:7300/api/users   # 200

后端只管接口:页面在 ../frontend/(npm run dev 起在 7301)。 联调推荐只开后端地址 http://127.0.0.1:7300(dev 环境自动把页面请求反代给前端);也可以直接开前端 7301(Vite 把 /api 反代到 7300)。

部署 / 升级(库结构)

一次执行,幂等,可反复跑:

cd backend
npm install
npm run db:deploy            # ① 建库(有权限时) ② 基线表 sql/schema.sql ③ 全部未执行的 database/migrations
npm run db:deploy -- --check # 只检查(列出未执行的迁移;有 pending 时退出码 1),适合上线前/CI 卡一道

生产库迁移(本地执行,目标 = 生产库)

生产 MySQL 账号是 packservice@localhost,只能从服务器本机登录,所以脚本会先建 SSH 隧道再跑同一套迁移:

npm run db:check:prod    # 只检查生产库还有哪些迁移没执行(不改库)
npm run db:deploy:prod   # 基线表 + 全部未执行迁移(幂等,可反复跑)
  • 连接信息来自本机 config/env.prod.sh(MYSQL_*),SSH 信息来自 config/deploy.config.local.cjs;
  • 隧道:127.0.0.1:<随机端口> → <服务器>:127.0.0.1:3306,执行完自动关闭;
  • 显式设置的 MYSQL_* 环境变量优先于 config.local.js(不会被本机开发库密码覆盖)。

规则(所有迁移脚本都保留在仓库里,不删不改):

位置 作用 什么时候跑
sql/schema.sql 基线 6 张表(CREATE TABLE IF NOT EXISTS,幂等) 每次 db:deploy 第 2 步自动跑
database/migrations/*.js 全部结构变更 / 数据回填(SequelizeMeta 记账) 每次 db:deploy 第 3 步自动跑,只跑没跑过的
sql/migrations/*.sql 历史一次性补丁(重建 users、加列、删旧 devices 表) 仅老库升级时手动补跑,新库已包含最终结构,重复执行会 Duplicate column
scripts/backfill-snapshot.js、scripts/dedupe-scan-records.js 一次性数据修复(需带参数,可 --dry-run) 按需手动,不是部署必跑

执行顺序固定为「基线表 → 迁移(按文件名升序)」,所以新库和老库走同一条命令,结果一致; 连接信息与运行时同源(环境变量 > config/config.prod.js(EGG_SERVER_ENV=prod)> config/config.local.js > 默认值)。

生产库如果由 DBA 预建、且应用账号没有建库权限,db:deploy 会打印一行「跳过建库」后继续,不影响后续迁移。

发布到服务器(npm run deploy)

参考 D:\wms 的双实例蓝绿发布:v1 / v2 两个目录轮流发布,新实例健康检查(/health)通过后才切 Nginx upstream,再停旧实例;失败会回滚 current.md 并保留旧实例继续服务。

一次性准备

  1. 本机:Node 18+、git、tar(Win10/11 自带 bsdtar)、OpenSSH Client(ssh / scp)。

  2. 填写发布配置 config/deploy.config.local.cjs(该文件已被 .gitignore 忽略;若缺失可从模板复制):

    cd backend
    # 已存在则直接编辑;缺失时:
    Copy-Item config/deploy.config.example.cjs config/deploy.config.local.cjs
    
  3. 服务器目录结构(首次发布时脚本会自动建 v1 / v2 / .deploy / shared-config):

    /www/wwwroot/packService/
    ├── current.md            # 内容只能是 v1 或 v2
    ├── nginx-upstream.conf   # 只有一行:proxy_pass http://127.0.0.1:7301;(API 端口)
    ├── front.conf            # nginx 前端静态 + /api、/health 反代 + /download 静态(自动维护)
    ├── frontend/             # 前端构建产物(nginx 直接托管)
    ├── frontend.prev/        # 上一版前端(回退用)
    ├── download/             # 安装包分发(nginx 直接托管)
    │   ├── version.json      # 桌面端版本信息(不缓存,客户端写死这个地址)
    │   ├── desktop/          # 桌面端 MSI(长缓存)
    │   └── android_client/   # Android APK + version.json
    ├── shared-config/        # 服务端私有配置(不随发布包走)
    │   └── env.prod.sh       # 启动前 source 的环境变量
    ├── v1/  v2/              # 两个后端发布目录
    └── .deploy/              # incoming / backups / state
    

    站点 vhost 里只需要 include 一次前端/反代配置:

    server {
        server_name pack.example.com;
    
        # 前端静态 + /api、/health 反代 + /download 静态,全部由 front.conf 维护
        include /www/wwwroot/packService/front.conf;
    }
    

    front.conf 由 npm run deploy 自动生成;nginx-upstream.conf 里的端口在发布健康检查通过后切换。 首次发布前先创建 current.md(内容 v1 或 v2);发布总是部署到另一个目录。

    生产站点强制 HTTPS:vhost 里对 $scheme != https 直接 return 301 https://$host$request_uri, 且 front.conf 的每个带 add_header 的 location 都会重复声明 Strict-Transport-Security (nginx 的 add_header 一旦在 location 内出现,就不再继承 server 级配置)。

  4. 服务端私有配置放在 shared-config/,不要改版本目录里的 config.default.js (后者是仓库代码,每次发布都会被覆盖)。shared-config/env.prod.sh 会在启动前被 source, 每次发布也会把 shared-config/config.prod.js、config.local.js(若存在)复制进目标版本目录。

    # /www/wwwroot/packService/shared-config/env.prod.sh(chmod 600)
    export JWT_SECRET='由 openssl rand -hex 32 生成的随机串'
    export MYSQL_HOST='127.0.0.1'
    export MYSQL_PORT='3306'
    export MYSQL_PASSWORD='...'
    export REDIS_HOST='127.0.0.1'
    export REDIS_PASSWORD='...'
    

    本项目已经准备好两份生产 env:

    文件 用途 是否提交
    backend/config/env.prod.sh 后端运行时变量(JWT_SECRET、MYSQL_*、REDIS_*、SITE_URL) 否(gitignore,本机权威副本,发布前自动上传到 shared-config/)
    frontend/.env.production 前端构建变量(VITE_*,不含密钥) 是

    改后端 env 后执行 npm run deploy 会自动上传并生效;改前端 env 后同样重新发布即可(deploy 会重新构建前端)。

    生产环境 config.default.js 会强制要求 JWT_SECRET 环境变量,缺少会启动失败(健康检查不通过,自动保留旧实例)。

  5. 可选:安装提交前检查钩子(禁止提交私有配置 / 运行期产物 / 版本记录):

    npm run setup:hooks
    

常用命令

命令 说明
npm run deploy:precheck 检查本地工具、SSH、远端目录 / Node / Nginx / 当前实例健康状态
npm run deploy 构建前端 → 打包 → 上传 → 解压安装 → 启动新实例 → 健康检查 → 切 Nginx → 停旧实例
npm run deploy:verify 查看当前版本 / 备份并冒烟探测 /、/health、/download/version.json
npm run deploy:version 查看远端活跃版本与最近一次发布记录(--history=20 看历史)
npm run deploy:smoke 只做冒烟探测
npm run deploy:inspect 只看 .deploy 状态与备份清单
npm run rollback 蓝绿回退到上一个版本目录(不重新解压,秒级切换)
npm run rollback -- --backup=backup-<时间戳>.tar.gz 用指定备份包恢复当前活跃目录
npm run deploy:cleanup-backups -- backup-xxx.tar.gz 删除指定备份包

发布说明:

  • 前端构建产物单独上传到 deployRoot/frontend,由 nginx 直接托管(SPA 回退到 index.html);上一版保留在 frontend.prev,npm run rollback 会连前端一起切回。 nginx 前端/反代配置由发布脚本写入 deployRoot/front.conf;Egg 只提供 /api、/health(FRONTEND_ENABLE=false)。 buildFrontend: false 时跳过前端构建与发布(适合前端完全独立部署)。
  • 生产发布不含「测试页」:前端 TestView 只在 dev 构建里注册路由与菜单(生产包不会产出该 chunk), 后端 /api/web/test/* 只在 env != prod 时注册,生产请求直接 404。
  • 发布包只包含 git 跟踪的源码;版本目录里的 config/config.prod.js、config/config.local.js、app/public/download、app/public/version 在清理前暂存、解压后放回,随后再用 shared-config/ 里的同名配置覆盖,保证所有版本配置一致。
  • 启动前会 source shared-config/env.prod.sh(JWT_SECRET、MYSQL_*、REDIS_* 等);不要编辑版本目录里的 config.default.js,它属于仓库代码,会被每次发布覆盖。
  • 每次发布会在 .deploy/backups/ 留一份旧代码备份(默认保留最近 5 个;node_modules / logs / run / temp、安装包目录和服务端私有配置不进备份,它们本身会被保留)。
  • 需要发布时顺带升级库结构,把 config/deploy.config.local.cjs 里的 remoteDbDeploy 改成 true(远端会先 source shared-config/env.prod.sh,再以 EGG_SERVER_ENV=prod 执行 npm run db:deploy;连接信息来自 MYSQL_* 环境变量或 config.prod.js)。

桌面端正式包(单独发布,不动后端)

改桌面端时只需要发安装包,不用重新发布后端:

cd backend
npm run desktop:build                 # 只构建(dry-run),产物在 desktop/installer/out
npm run desktop:publish               # 构建 + 上传 + 刷新 nginx
npm run desktop:publish -- --version=1.0.90 --notes="修复 xxx"
npm run desktop:publish -- --skip-nginx
  • 版本默认取本地已有最高版本 + 1(补丁号),也可用 --version= 指定;
  • 构建复用 desktop/installer/build.ps1 -Environment Production;
  • 上传到 deployRoot/download/desktop/(MSI),version.json 传到 deployRoot/download/ (路径不能改:老客户端写死 /download/version.json;先传 MSI,再原子替换 version.json);
  • nginx 的 /download/ 静态托管该目录:version.json 不缓存,MSI 长缓存;
  • desktop/installer/package.config.json 的 Production serverBaseUrl 必须是 https://,安装包内嵌的接口 / 下载地址会跟着变;
  • 谷歌插件一起打进包:extension/ 发布到 <安装目录>\extension,菜单「工具 → 复制谷歌插件地址」给出该 Windows 路径;
  • 不会重启 Egg、不会重新发布后端、不会跑数据库迁移;
  • 前置:.NET 8 SDK、WiX 5.0.2(dotnet tool install --global wix --version 5.0.2)、desktop/native/ffmpeg/ffmpeg.exe。

下载地址:<desktopBaseUrl>/download/desktop/YuncangTraceSetup-<版本>.msi 更新信息:<desktopBaseUrl>/download/version.json

Android 设备端正式包(单独发布,不动后端)

cd backend
npm run android:build                 # 只构建(dry-run),产物在 backend/android_client/out
npm run android:publish               # 构建 + 上传 + 刷新 nginx
npm run android:publish -- --version=1.0.2 --notes="扫码上报更稳"
npm run android:publish -- --skip-nginx
  • 构建复用 backend/android_client/build.ps1 -Environment Production(配置在 backend/android_client/package.config.json,和桌面端同一套路);
  • 版本默认取已有 APK / version.json 的最高版本 +1 补丁号;versionCode 由 x.y.z 换算(major*10000+minor*100+patch);
  • 上传到 deployRoot/download/android_client/:APK + version.json(nginx 对 version.json 单独关缓存);
  • 签名读 AndroidStation/keystore.properties + keystore/*.jks(不入库,发布机必须自行备份);
  • 前置:JDK 17(JAVA_HOME,或自动找 %LOCALAPPDATA%\Programs\EclipseAdoptium\jdk-* / Android Studio 的 jbr)、 Android SDK(AndroidStation/local.properties 的 sdk.dir 或 ANDROID_HOME)。

下载地址:<androidBaseUrl>/download/android_client/YuncangScan-<版本>.apk 更新信息:<androidBaseUrl>/download/android_client/version.json

单元测试

npm test          # 无需本机启动 MySQL / Redis
npm run cov

本地端口

  • 后端默认监听 7300:config.cluster.listen.port = Number(PORT || 7300),临时换口用 PORT=7400 npm run dev(PowerShell:$env:PORT=7400; npm run dev);

  • 二维码 / 邮件链接会自动跟随端口:二维码内容是 ctx.origin 拼的 http://<当前访问的 host:port>/wechat?spm=1.0.<码>.1,在哪个端口打开登录页,扫出来就是那个地址,不用改配置;邮件里的重置链接同理(config.email.siteUrl || ctx.origin),只有显式配了 SITE_URL 才需要跟着改;

  • 想同时跑两个实例(例如一边联调一边自测),给其中一个换端口 + 分日志:$env:PORT=7400; $env:LOG_DIR='logs-test'; npm run dev;

  • 多个实例共用同一套 MySQL / Redis(都读 config/config.local.js);

  • 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 申请更短的,不能更长
DEVICE_REFRESH_EXPIRES 730d 刷新令牌有效期(POST /api/device/refresh 轮换时顺延)
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 账号 / 密码(QQ 邮箱填「授权码」,不是登录密码;放 shared-config/env.prod.sh 或环境变量)
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) 昵称
email 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 最近登录时间
password_hash varchar(100) bcrypt 密码哈希(接口/页面都不外泄,查询时显式 exclude)
password_changed_at datetime 最近一次设置/重置密码的时间(可空);签发时间早于它的 user JWT 立即失效
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,唯一;库里不存令牌本体
refresh_token_hash varchar(128) 刷新令牌 sha256(不存原文;索引 idx_scanners_refresh_token_hash)
refresh_expires_at datetime 刷新令牌过期时间(每次刷新顺延)
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 时间戳与软删除

设备接入流程(只有一条链路):

  1. 拿令牌(也就是注册):GET /api/device/login(公开,无需任何凭据):
    • ① 不带参数 → 返回登录码 + 二维码地址(qrContent / qrImageUrl),此时库里还没有任何记录;
    • ② 手机用 POST /api/wechat/confirm 确认(已登录用户);
    • ③ 设备带 ?code=&wait=60 长轮询 → 这一边才注册:按 SN 建/取记录、绑定到确认登录的账号,并拿到长期 JWT;
  2. 用令牌:之后所有请求带 Authorization: Bearer <JWT>;GET /api/scanner/me 自检、POST /api/scanner/heartbeat 保活(刷新 last_seen_at)、/api/scan/* 上报;
  3. 令牌到期 / 设备重装:再扫一次码即可(不需要密钥:设备屏幕出码、人确认一下)—— 记录已存在时不重复建,只换发新令牌;
  4. 换人使用(设备转让):先由原账号在 /scanners 解绑(或管理侧 POST /api/scanner/unbind),新使用人再扫码登录即可认领;
  5. 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,env DEVICE_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)。

刷新令牌(自动续期,2026-10-19)

访问令牌(365 天)到期后,无人值守的后台服务没法自己登录,所以激活时同时下发刷新令牌:

  • 刷新令牌是不透明随机串(32 字节 base64url);库里只存 sha256(scanners.refresh_token_hash),不存原文;
  • 有效期默认 730 天(config.jwt.deviceRefreshExpiresIn,env DEVICE_REFRESH_EXPIRES);每次刷新都会轮换并顺延;
  • 接口:POST /api/device/refresh,body { refreshToken, sn? }(也认 header X-Refresh-Token); 不需要访问令牌(它可能已过期);成功返回新的 token + refreshToken(旧的立即失效)+ expiresIn/refreshExpiresIn;
  • 撤销:关闭设备服务(revokeToken)、同主体其它设备激活(踢下线)、禁用/删除设备都会把 refresh_token_hash 清掉,刷新令牌一并失效;
  • 桌面端后台服务在访问令牌剩余不足 7 天时自动调用,结果写 %ProgramData%\YuncangTrace\agent-token.json。

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 非空)的通道再次上报时会自动「复活」;
  • 全量对账(replace: true):桌面端的通道列表存在本地(channels.json),与本机设备是否在线无关 → replace: true 时该中控下不在列表里的通道会被软删,workstation_scan_channels 里对应绑定物理删除, 返回 { removed, unbound };channels: [] + replace: true 表示"通道已全部删除"。不带 replace 的老客户端行为不变;
  • 忽略 channel_id = 'DESKTOP':旧版桌面端会多报一个「本机中控」占位通道(从未有真实数据), 迁移 20261019230000-remove-legacy-desktop-channel 已清掉历史行,reportChannels() 也会直接跳过,避免老客户端重新写回。

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 服务端接收时间
subject_id bigint unsigned 所属主体(跟随中控)
workstation_id bigint unsigned 扫码当时绑定的工作台
workstation_snapshot json 扫码当时的工作台快照(录像机 / 摄像头 / 画布布局 / 录制范围)
created_at / updated_at datetime 时间戳

快照是 2026-10-18 才加的(迁移 20261018240000)。历史记录没有快照, 查回放时回落到「当前绑定」并打 snapshotMiss;想让历史数据也走快照,跑:

# 只补某个运单(跳过已有快照的)
npm run backfill:snapshot -- --code=79150895123619
# 全部缺快照的记录 / 连已有快照也覆盖成当前配置 / 只看不写
node scripts/backfill-snapshot.js
node scripts/backfill-snapshot.js --all
node scripts/backfill-snapshot.js --dry-run

⚠️ 补出来的快照 = 现在的工作台配置,不是当年的。只适合「配置没变过」的历史数据。 补快照用的是 app/lib/workstation-snapshot.js(与实时入库同一份逻辑)。

去重规则(唯一键 uk_scan_dedup = (scanner_id, channel_id, barcode, scan_time)):

  • 同一中控 + 同一通道 + 同一条码 + 同一扫描时间(秒) 只入库一次,重复上报不会报错,接口返回 duplicated 计数;
  • 同一运单号 24 小时内只保留一条(现场要求):主体内按 barcode 判断,跨中控/通道也算同一条; 后上报的扫描时间如果更新,就覆盖这条记录的 scan_time、通道与工作台快照(计入 updated); 如果上报的时间比库里那条旧(乱序/重试),则忽略(计入 suppressed),不会把时间改回过去; 距上一条超过 24 小时后重新扫,算一次新的上报;
  • 同一批里同一运单出现多次 → 只保留最晚的一条,其余忽略;
  • 上报前先用一次查询(按中控 + 通道 + 时间范围)捞出已存在的记录做精确去重,剩下的批量插入; 真出现并发撞唯一键时会自动退化成逐条插入,撞上的计入 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}

「测试页」只在 vite dev / 本地开发构建里存在:生产构建不产出 TestView 的 chunk, 路由与左侧菜单也一并去掉;后端 /api/web/test/* 只在 env != prod 时注册(生产请求返回 404)。

后端怎么把页面交出去(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:7300 一个地址就够(前端热更新照常生效); 前端没起来时会回一个 502 提示页,而不是白屏;
  • 生产:本仓库的发布脚手架默认由 nginx 直接托管 deployRoot/frontend,Egg 侧用 FRONTEND_ENABLE=false 关闭页面托管(只出 /api、/health);安装包由 nginx 静态托管 deployRoot/download。 如果仍想让 Egg 托管(例如没有 nginx),设置 FRONTEND_ENABLE=true 并在启动时用 FRONTEND_DIST 指向构建产物;找不到文件且请求要 HTML 时回退 index.html(SPA 深链不会 404)。
  • 单测(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, refreshToken, refreshExpiresIn, scanner, user },注册/绑定就发生在这一刻(SN 已属于别人 → 403)
POST /api/device/refresh 用刷新令牌换新访问令牌(无需访问令牌):body { refreshToken, sn? } → { sn, token, tokenType, expiresIn, refreshToken, refreshExpiresIn, refreshExpiresAt };两者都会轮换,旧的立即失效
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;返回 serverTime + subject(主体状态,读缓存),设备据此判断是否已续期
GET /api/scanners?page=&pageSize=&keyword=&userId=&status= 设备列表(带绑定账号;管理侧)
GET /api/scanners/:id 扫描器详情
DELETE /api/scanners/:id 软删除扫描器
POST /api/scan/channels 需扫描器 JWT(主体过期/停用 → 403 subject_expired / subject_disabled):中控上报通道,body: { channels: [{ channelId, channelName }], replace?: boolean }(单条也可)→ { created, updated, invalid, errors, removed, unbound }。replace: true = 全量对账:本中控下不在列表里的通道软删并解绑工作台,允许 channels: []
GET /api/scan/channels?page=&pageSize=&keyword=&status= 需扫描器 JWT:当前中控已登记的通道
POST /api/scan/records 需扫描器 JWT(主体过期/停用 → 403 subject_expired / subject_disabled):中控上报扫码,body: { records: [{ barcode, scanTime, channelId }] } → { received, inserted, updated, duplicated, suppressed, invalid, unknownChannels }(updated = 24 小时内同一运单被覆盖为最新扫描时间的条数;suppressed = 比库里已有记录更旧、被忽略的条数)
GET /api/scan/records?page=&pageSize=&channelId=&barcode=&startTime=&endTime= 需扫描器 JWT:当前中控上报的扫码记录

扫码上报的两个接口都不会因为重复而报错(幂等):完全重复的条数计入 duplicated, 同一运单号 24 小时内重复扫描的只保留一条:时间更新就覆盖(updated),更旧的上报忽略(suppressed); 单条非法(缺条码 / 时间非法 / 超长)会被跳过并计入 invalid + errors;整体为空数组才返回 422。 上报还支持 records 传 JSON 字符串(部分设备端会这么塞);上报成功会顺手刷新中控心跳与通道的 last_report_at, 遇到未登记的通道会自动补建一行(channel_name 留空,同时记 WARN 日志)。

主体期限与设备上报:设备所属主体过期/停用时,POST /api/scan/records、POST /api/scan/channels 返回 403(status = subject_expired / subject_disabled),设备端应暂停推送但保留本地积压; POST /api/scanner/heartbeat 不受期限拦截,返回体里的 subject.expired 是恢复依据 —— 续期后最多 1 分钟 设备就会自动恢复并补传(服务端按 设备+通道+条码+秒 去重,整批重发安全)。

主体状态走 service/subject_state.js 缓存(Redis 优先,不可用时退化为进程内 TTL), 心跳与上报判断都不额外查库;续期/停用后由写库方主动失效缓存(SUBJECT_STATE_CACHE_TTL,默认 30 秒)。

统一响应格式:成功 { "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>,TTL EMAIL_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);
  • 邮箱找回密码(发重置链接):前端「忘记密码?」页 → POST /api/web/auth/forgot 生成带令牌的链接并发到邮箱 → 邮件里的链接打开前端 /reset?token=... 设置新密码 → POST /api/web/auth/reset 改哈希(不自动登录,要求用新密码再登一次)。
    • 只存 Redis(缓存),不落库:users 表没有 token/过期时间列,也没有 reset 表(实测确认);重启 Redis / 清 packs:reset:* 会让未用的链接立即失效;

    • 三个 key(app/service/password_reset.js,前缀 config.cache.prefix):

      key 值 TTL(实测)
      packs:reset:token:<sha256(令牌)> 用户 id EMAIL_RESET_TTL,默认 1800s(30 分钟)
      packs:reset:user:<用户id> 该用户当前最新令牌的摘要 同上(用「旧链接立刻失效」)
      packs:reset:sent:<用户id> 1 EMAIL_CODE_RESEND,默认 60 秒(重发节流)
    • Redis 里只存令牌的 sha256 摘要,不存原文(泄库也拿不到可用的链接;令牌本身是 randomBytes(32) 的 64 位 hex);

    • 有效期是固定的 30 分钟(不滑动:verify() 不续期);一次性:重置成功后 consume() 删掉令牌;重新申请会让旧链接立刻失效(同一用户只保留最新一条);校验失败的提交(密码太短/两次不一致/令牌不对)不会消费令牌;

    • 重发节流 60 秒:命中时 /forgot 返回 429 + { ok:false, status:'throttled', message:'重置链接已发送,请 60 秒后再试' }(⚠️ 2026-10-17 修:以前抛 500,被 error_handler 盖成「服务器内部错误」,用户看不懂);Redis 写失败/发信失败 → 503 + status:'unavailable' | 'mail';

    • 防账号枚举:邮箱格式不对才报错;邮箱未注册或账号被禁用时,提示与成功完全一致(“如果该邮箱已注册,链接已经发出”),并且不发信;

    • 邮件正文由 service.mail.sendResetLink() 生成(与验证码同一套开发模式/SMTP 逻辑:未配 SMTP_HOST 时链接写日志 + 接口返回 url,前端直接给个可点链接,方便本地点开);

    • 链接地址默认取当前请求的 host,正式部署建议配 SITE_URL(有反代/多域名时更可靠);

    • 改密 / 重置密码后旧令牌立即失效(2026-10-17 已做):users 新增 password_changed_at(迁移 sql/migrations/20261017_add_user_password_changed_at.sql;老数据为 NULL = 不限制);service.user.setPassword()(注册/重置/脚本)与 auth.changePassword() 写这个时间;middleware/api_auth.js 与 middleware/internal_auth.js 比对 JWT 的 iat:iat 秒 < 改密秒 → 401 { status:'password_changed', message:'密码已修改,请重新登录' }(留 1 秒容差:改密当秒新签发的令牌仍然可用,避免误杀);

  • 扫码登录(app/service/wechat_login.js):前端登录页顶部是「登录 / 注册」两个 tab,扫码用右上角的三角形切换(三角形挂在卡片右上角,只在登录 ↔ 扫码之间切,注册面板不显示):
    • 串码:服务端生成 6 位数字 + 字母随机串码(WECHAT_CODE_LENGTH,字符集去掉了 0/O/1/I 等易混字符),写进 Redis packs:wechat:state:<code> = pending(TTL WECHAT_STATE_TTL);
    • 二维码内容 = 本站地址:http://<域名>/wechat?spm=1.0.<code>.1(spm 格式由 WECHAT_SPM_PATTERN 决定);二维码图片本身用零依赖的 qrcode-generator 现场画成 SVG(GET /api/wechat/qrcode.svg?code=…)——不需要任何外链资源;
    • 完整时序(都是我们自己的接口,不需要第三方 JS/iframe):
      1. 电脑端调 GET /api/wechat/login(不带参数)拿 code + qrUrl,前端登录页把它画成 <img src="/api/wechat/qrcode.svg?code=…"> → 串码登记为 pending;
      2. 手机扫码打开前端路由 /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;
      3. 电脑端用 GET /api/wechat/login?code=…&wait=60 长轮询取结果 → { status:'confirmed', token, user } 存本地即登录完成(前端登录页会自动跳首页);取走即删(一次性)。
    • JWT 怎么用:config.jwt.userExpiresIn(env USER_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(nginx proxy_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:7300/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:7300/api/wechat/login?code=XBUBHP&wait=60'
      
      # ③ 已登录的客户端(或用手机打开 /wechat?spm=1.0.XBUBHP.1):用登录码触发登录
      curl -s -X POST http://127.0.0.1:7300/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 / env DEVICE_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 轮换 → 设备上一次的令牌立即失效);
      • 登录码一次性:被设备取走即删除(同一张码不能给第二台设备用,浏览器页面长轮询与设备长轮询谁先取走算谁的);
      • 联调(新设备不需要先注册;第三终端是已登录的手机/小程序):
        # ① 设备发码(拿 code / qrContent / qrImageUrl 显示二维码;带上自己的 SN 与名称)
        curl -s 'http://127.0.0.1:7300/api/device/login?sn=SN-NEW-01&name=门口扫码枪'
        
        # ② 设备挂长轮询(有人确认就立即返回;参数带上也行)
        curl -s 'http://127.0.0.1:7300/api/device/login?sn=SN-NEW-01&code=<登录码>&wait=60'
        
        # ③ 手机确认(现有接口,鉴权走 header,不认 cookie)
        curl -s -X POST http://127.0.0.1:7300/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=…),扫码面板不显示任何说明文字(只留二维码 + 「返回账号密码登录」),扫码后走「手机确认登录」降级路径;
  • 新增/重置登录账号: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) 是最终保证,服务层先查一次再做批量插入(并发撞键时退化为逐条插入并计数),所以重复上报既不报错也不产生脏数据;另外同一运单号 24 小时内只保留一条,后上报的扫描时间更新时覆盖原记录(时间 + 工作台快照),旧上报不回退;
  • 扫码记录是流水表、不用软删除(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。

主体(租户)体系(2026-10-18)

业务数据(设备 / NVR / 摄像头 / 工作台 / 扫码记录 / 扫码通道)全部挂在主体下,接口按主体隔离。

数据表

表 说明
subjects 主体:name、admin_user_id(管理员,默认创建人)、expire_at(使用期限)、status、remark
subject_members 成员:subject_id + name(姓名,必填)+ user_id(绑定账号,可为空)+ role(1 管理员 / 2 成员)+ wechat_openid / bound_at
业务表 scanners / nvrs / cameras / workstations / scan_channels / scan_records 都有 subject_id

升级时(迁移 20261018230000-create-subject-tables)会给已有数据的账号各建一个主体(管理员=本人、期限 +365 天), 并把名下数据回填进去,保证旧数据不丢。

接口

方法 路径 说明
GET /api/web/subjects 我可进入的主体列表(含角色 / 成员数 / 是否过期 / trialDays)
POST /api/web/subjects 创建主体 { name, remark? } → 管理员=创建人,默认赠送 7 天(config.subject.trialDays,env SUBJECT_TRIAL_DAYS)
GET/PUT /api/web/subjects/:id 详情 / 改名·备注·续期 { name?, remark?, extendDays? }(仅管理员)
GET /api/web/subjects/:id/members 成员列表
POST /api/web/subjects/:id/members 按姓名快速添加成员 { name }(此时还没绑账号)
DELETE /api/web/subjects/:id/members/:memberId 移除成员(不能删管理员/自己)
POST /api/web/subjects/:id/members/:memberId/bind-code 生成成员绑定码({ code, bindUrl, qrUrl, expiresIn },10 分钟有效)
GET /api/subject/member-bind?code= 绑定码状态(公开,手机扫码页轮询)
POST /api/subject/member-bind/confirm 手机端确认绑定 { code }(需 user JWT)→ 该账号成为成员

续期订单与支付回调

下单不会立刻续期,只有支付渠道回调成功后才把主体期限顺延(幂等,重复回调不重复续期)。

方法 路径 说明
GET /api/web/subjects/:id/orders 订单列表(成员可见,{ total, page, pageSize, list })
POST /api/web/subjects/:id/orders 下单 { days, amount?, remark? }(仅管理员)→ { orderNo, days, amount, status:0待支付, ... };amount 不传时按 PAY_AMOUNT_PER_DAY 自动算,都没配则金额为空(不校验)
POST /api/pay/notify 公开的渠道回调 { orderNo, transactionId?, amount?, channel?, paidAt? } → { duplicated, order };订单不存在 404、金额不符 422、签名错 400
POST /api/internal/subject-orders/:orderNo/pay 内部令牌:模拟支付成功(不需要签名),方便联调/补单

签名:配置了 PAY_CALLBACK_SECRET 时,回调必须带 X-Pay-Sign = hex(HMAC-SHA256(secret, "orderNo\ntransactionId\namount")); 未配置密钥且 PAY_MOCK=true 时允许不带签名直接回调(开发/测试默认开启;生产默认关闭, 需要显式设 PAY_MOCK=true,否则回调返回 503 pay_not_configured)。

续期规则与 PUT /api/web/subjects/:id 的 extendDays 一致:未过期在原到期时间上顺延,已过期从当前时间起算; 回调成功后会主动失效主体状态缓存,设备下一次上报/心跳立即看到新期限。

模拟一次付费续期(本地/测试):

# 1) 下单(需要主体管理员用户令牌)
curl -X POST http://127.0.0.1:7300/api/web/subjects/1/orders \
  -H "Authorization: Bearer <user-jwt>" -H "Content-Type: application/json" \
  -d '{"days":30,"amount":99}'

# 2a) 模拟渠道回调(PAY_MOCK=true 时不需要签名)
curl -X POST http://127.0.0.1:7300/api/pay/notify \
  -H "Content-Type: application/json" \
  -d '{"orderNo":"<上一步的 orderNo>","transactionId":"TXN-1","amount":99}'

# 2b) 或者走运维接口(内部令牌)
curl -X POST http://127.0.0.1:7300/api/internal/subject-orders/<orderNo>/pay \
  -H "X-Internal-Token: <INTERNAL_TOKEN>"

二维码:GET /api/wechat/qrcode.svg?code=<码>&mode=member(内容是 <站点>/wechat?bind=<码>,前端扫码页显示「确认绑定」)。

主体上下文(统一处理)

  • 业务接口除 apiAuth 外必须再挂 middleware.subjectAuth();它按 X-Subject-Id header(也认 ?subjectId= / body.subjectId)解析主体:
    • 没带 → 400 { status: 'subject_required' }
    • 不是该主体成员 / 主体不存在 → 404
    • 主体被停用 → 403 subject_disabled;主体到期 → 403 subject_expired(带 expireAt)
    • 通过后写 ctx.state.subjectId / subject / subjectMember,service 一律用 subjectId 限定范围
  • 登录(POST /api/web/auth/login)的返回里带 subjects 列表,前端存下并记住上次使用的主体(localStorage.packs_subject_id)。
  • 设备(中控)没有「当前主体」概念:GET /api/device/login?subjectId= 可选,不传就用确认人可进入的第一个主体。

桌面端「设备服务」(本机作为扫码中控)

方法 路径 说明
GET /api/web/devices/active 本主体已绑定设备(开启前检查用)
POST /api/web/devices/activate 仅主体管理员;{ sn?, name? } → { device, token, tokenType, expiresIn, kicked[] }
POST /api/web/devices/:id/logout 关闭设备服务(轮换 jti → 该设备令牌立即 401)
GET /api/wechat/qrcode.gif?code=&mode= 同一张二维码的 GIF(桌面端 WPF 不能渲染 SVG;online.png 不需要)

「一个主体只允许一台设备在线」:activate 会把同主体下其他设备的 token_jti 全部轮换(旧 JWT 立即失效), 并在返回的 kicked 里列出被踢的设备;同一 SN 重复开启只是换发令牌,不会新建记录。 设备令牌用于设备侧上报:POST /api/scan/channels、POST /api/scan/records(scannerAuth + subjectActive, 不需要主体 header;所属主体过期/停用 → 403 subject_expired / subject_disabled)。

用户协议(2026-10-20)

三张表(迁移 20261020220000-create-agreement-tables,示例数据 20261020221000-seed-user-agreement):

表 用途
agreements 协议定义:code / name / required / current_version_id
agreement_versions 版本正文:version / content / content_type / status / published_at
user_agreements 用户同意记录:user_id + agreement_id + version_id 唯一,另存版本号快照与来源/IP/UA

接口:

  • GET /api/agreements/current(公开)→ 当前启用的协议 + 已发布版本正文(登录前展示)
  • POST /api/web/auth/login 增加 client / agreements:
    • client='mini_program' 时,必须带 agreements: [{ code, versionId }] 且版本等于当前版本, 否则 428 { ok:false, status:'agreement_required', data:{ agreements } };
    • 登录成功后按 user_id + agreement_id + version_id 落库(同一版本重复登录只更新 agreed_at / 来源),响应里带 agreements。
  • 强制范围由 AGREEMENT_ENFORCE 控制:默认 mini_program(只拦小程序客户端);all = 所有客户端;off = 不校验(仍记录主动提交的同意)。

没有管理界面,发布新版本直接执行 SQL(示例):

SET @aid = (SELECT id FROM agreements WHERE code = 'user_agreement');

INSERT INTO agreement_versions
  (agreement_id, version, title, summary, content, content_type, status, published_at, effective_at, created_at, updated_at)
VALUES
  (@aid, '1.1.0', '用户协议', '更新说明', '新的协议正文', 'text', 1, NOW(), NOW(), NOW(), NOW());

SET @vid = LAST_INSERT_ID();
UPDATE agreements SET current_version_id = @vid, updated_at = NOW() WHERE id = @aid;

发布后,小程序下次登录会收到 428 → 自动拉新正文、要求重新阅读并勾选;旧版本的同意记录保留。 查某个用户同意过哪些版本:

SELECT agreement_id, version_id, version, source, agreed_at
FROM user_agreements WHERE user_id = ? ORDER BY agreed_at DESC;

⚠️ 种子迁移里的协议正文是占位示例,正式上线前务必替换为法务确认后的文本。

微信小程序登录(2026-10-20)

独立的小程序登录模块:code2Session 换 openid → 按 openid 找绑定账号 → 未绑定则自动建账号。

数据表

表 用途
wechat_mp_accounts 小程序 openid 与平台账号的绑定:(appid, openid) 唯一,user_id 为空表示已解绑;另存 unionid / session_key / 最近登录

与公众号的 wechat_oauth 分开:小程序是「一个 openid 对一个平台账号」,解绑只清 user_id,记录保留。

配置

环境变量 说明
WX_MP_APPID / WX_MP_SECRET 小程序后台「开发设置」里的 AppID / AppSecret(必须配齐才会真调微信)
WX_MP_MOCK 生产要允许 mock 时显式设为 true;本地/单测未配 AppID 时默认允许 mock
WECHAT_API_BASE 微信接口地址(默认 https://api.weixin.qq.com,联调可改网关)

mock 模式:请求里 code 传 mock:<openid> 可直接指定 openid(固定账号,方便联调); 传其它 code 时按 sha1(code) 推导 openid。

接口

方法 路径 说明
POST /api/web/auth/wechat/login 公开;{ code, userInfo?, client?, agreements? } → 令牌 + 用户 + 主体列表 + firstTime + wechat 绑定信息
POST /api/web/auth/wechat/bind 需令牌;把当前微信绑到已有账号(openid 已属他人 → 409)
GET /api/web/auth/wechat/bindings 需令牌;当前账号的微信绑定列表
DELETE /api/web/auth/wechat/bindings/:id 需令牌;解绑(若是唯一登录方式 → 422,先设密码)

登录细节:

  • 未绑定过的 openid → 自动创建平台账号:用户名 wx_<openid 尾 12 位>(重名加随机后缀)、 随机密码(等于没有密码,需要用「找回密码」设置后才能密码登录),firstTime: true;
  • 已绑定 → 复用原账号,校验 users.status(禁用 → 403);
  • 与账号密码登录共用协议校验:client='mini_program' 未同意当前协议版本 → 428 agreement_required;
  • 签发令牌 / 记录同意 / 带主体列表的逻辑在 app/service/login.js(两种登录共用)。