- 工具菜单去掉「安装浏览器插件(企业策略:Chrome / Edge)」「卸载浏览器插件(企业策略)」, 删除 Services/ExtensionInstaller.cs(.reg 生成 + 提权导入 + 注册表校验) - 只保留「安装浏览器插件(Edge 应用商店)」与「复制插件路径(Chrome / 开发者模式)」; 商店弹窗去掉「审核中会 404」的说法,Chrome 用户直接引导到开发者模式 - 文档同步(桌面 README / 后端 README / extension README / STORE-SUBMISSION / keys README): 写清老机器上残留的 HKLM 策略怎么手工清理,避免和商店版同时注入 - extension:publish(.crx + updates.xml)保留,仅给内网/离线分发用 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
云仓视频溯源系统(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 首页统计(今日/昨日/近 N 天)
│ │ │ ├── device.js # /api/web/devices* 我的设备(列表/详情/通道/解绑/删除)
│ │ │ ├── record.js # /api/web/records 我的扫码记录(按自己设备过滤)
│ │ │ ├── admin_member.js # /api/web/admin/members[/:id]、/me 平台管理员名单(❗需平台管理员)
│ │ │ ├── admin_subject.js # /api/web/admin/subjects[/:id] 所有主体 + 改授权到期时间
│ │ │ ├── admin_order.js # /api/web/admin/orders[/:orderNo/confirm] 所有订单 + 确认订单
│ │ │ ├── admin_extension.js # /api/web/admin/extension Chrome 插件集中配置(❗需平台管理员)
│ │ │ ├── extension.js # /api/web/extension/config 插件读取的配置(公开只读,无令牌)
│ │ │ └── test.js # /api/web/test/{device-login,scan} 前端测试页的模拟接口(仅非生产环境注册)
│ │ ├── internal/ # 运维/内部(❗需内部令牌,挂在 middleware.internalAuth() 后面)
│ │ │ ├── user.js # /api/users* 用户 CRUD(含缓存)
│ │ │ ├── wechat.js # /api/internal/wechat-bindings* 网关绑定排查 / 强制解绑
│ │ │ ├── config.js # /api/configs* 系统配置读写
│ │ │ └── device.js # /api/scanners*、/api/scanner/{bind,unbind} 设备列表/详情/解绑/删除
│ │ ├── auth/ # 公开的登录接口(发码 / 查码,无需令牌)
│ │ │ └── wechat.js # /api/wechat/{status,qrcode.svg} 设备扫码登录的码
│ │ ├── 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)
│ │ ├── platform_admin.js # **平台管理员校验**(admin_members 启用 / INTERNAL_ADMIN_IDS;给 /api/web/admin/*)
│ │ ├── 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
│ │ ├── admin_member.js # admin_members(平台管理员)
│ │ ├── sys_config.js # sys_config
│ │ ├── scanner.js # scanners
│ │ ├── scan_channel.js # scan_channels
│ │ └── scan_record.js # scan_records(去重)
│ ├── service
│ │ ├── auth.js # 登录校验(bcrypt 密码比对)+ 自助注册
│ │ ├── admin_member.js # 平台管理员:名单维护 + isAdmin(admin_members / INTERNAL_ADMIN_IDS)
│ │ ├── mail.js # 发邮件(邮箱验证码 / 重置密码链接;开发模式只写日志)
│ │ ├── verify_code.js # 邮箱验证码:生成/发送/校验/消费(Redis 存储 + 重发节流)
│ │ ├── wechat_login.js # 设备扫码登录:二维码本地生成 / 串码状态机 / 长轮询
│ │ ├── 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)
│ │ └── wx_gateway.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 并保留旧实例继续服务。
一次性准备
-
本机:Node 18+、git、tar(Win10/11 自带 bsdtar)、OpenSSH Client(
ssh/scp)。 -
填写发布配置
config/deploy.config.local.cjs(该文件已被.gitignore忽略;若缺失可从模板复制):cd backend # 已存在则直接编辑;缺失时: Copy-Item config/deploy.config.example.cjs config/deploy.config.local.cjs -
服务器目录结构(首次发布时脚本会自动建
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 + EXE(长缓存) │ └── 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 级配置)。 -
服务端私有配置放在
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环境变量,缺少会启动失败(健康检查不通过,自动保留旧实例)。 -
可选:安装提交前检查钩子(禁止提交私有配置 / 运行期产物 / 版本记录):
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 |
删除指定备份包 |
发布说明:
⚠️
npm run deploy只发后端 + 前端 + nginx:桌面端安装包(npm run desktop:publish)和 Chrome 插件(npm run extension:publish)是两条独立命令,不会跟着 deploy 走(Edge 扩展已上架商店, 这条.crx+updates.xml链路现在只给内网/离线分发用)。 三者的远端目录互不重叠(/download/desktop/、/download/extension/),可以各自单独发布。
- 前端构建产物单独上传到
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(远端会先 sourceshared-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
npm run desktop:publish -- --target=Msi # 只出 MSI(不发 EXE)
-
--target=Both|Msi|Exe直接透传给desktop/installer/build.ps1 -Target; ⚠️ 客户端版本≤ 1.0.151有个 bug:优先下载 EXE,却拿 version.json 里的md5(MSI 的)去校验, 必然报「安装包 MD5 不一致」。给这些客户端发的第一个修复版必须只出 MSI (--target=Msi,此时 version.json 里没有downloadUrlExe,老客户端会回落到 MSI +md5,能正常升级), 等它们升上来之后再恢复Both。 -
版本默认取本地已有最高版本 + 1(补丁号),也可用
--version=指定; -
构建复用
desktop/installer/build.ps1 -Environment Production; -
上传到
deployRoot/download/desktop/(MSI + EXE),version.json传到deployRoot/download/(路径不能改:老客户端写死/download/version.json;先传安装包,再原子替换version.json); -
nginx 的
/download/静态托管该目录:version.json不缓存,安装包长缓存; -
desktop/installer/package.config.json的 ProductionserverBaseUrl必须是https://,安装包内嵌的接口 / 下载地址会跟着变; -
浏览器插件一起打进包:
extension/发布到<安装目录>\extension(开发者模式加载用); 正式分发:Edge 走加载项商店、Chrome 走开发者模式,客户端不再写企业策略(见下节); -
不会重启 Egg、不会重新发布后端、不会跑数据库迁移;
Chrome 插件正式包(.crx + updates.xml)
cd backend
npm run extension:bundle # 只压缩源码 → extension/dist(esbuild,体积约 1/3)
npm run extension:build # 压缩 + 打包(dry-run),产物在 extension/out
npm run extension:publish # 压缩 + 打包 + 上传 + 刷新 nginx
npm run extension:zip # 压缩 + 出商店上传包(extension/out/*.zip)
npm run extension:publish -- --version=1.2.0 --skip-nginx
- 打进去的是
extension/dist(压缩产物),不是源码:build-extension.cjs用 esbuild 逐文件 minify (不合并文件,importScripts('lib/rules.js')与各处路径原样有效);桌面端build.ps1在dotnet publish前也会自动跑一遍,csproj 打的同样是dist; - 只做 minify、不做混淆:MV3 的 CSP 禁止
eval/new Function,Chrome/Edge 商店也要求代码可读; - 用本机 Chrome/Edge 的
--pack-extension打包(找不到浏览器时用--browser=<路径>指定); - 产物:
YuncangTraceExtension-<version>.crx、updates.xml、extension-id.txt; - 上传到
deployRoot/download/extension/;nginx 对updates.xml关缓存(浏览器靠它自动升级),.crx文件名带版本号、走长缓存; - 扩展 ID 由
extension/keys/key.pem决定(首次运行自动生成,必须备份,换了 ID 就变); - ⚠️ 客户端已不再用企业策略装自建 CRX:Edge 扩展上架商店后该功能已下线,桌面端没有
「一键写策略」的入口。这条
updates.xml+.crx链路保留给内网/离线分发; - 正式分发:Edge 用桌面端「工具 → 安装浏览器插件(Edge 应用商店)」点「获取」;
Chrome 用「工具 → 复制插件路径(Chrome / 开发者模式)」到
chrome://extensions加载已解压的扩展程序; - 前置:.NET 8 SDK、WiX 5.0.2(
dotnet tool install --global wix --version 5.0.2)、Inno Setup 6(winget install --id JRSoftware.InnoSetup,出 EXE 用)、desktop/native/ffmpeg/ffmpeg.exe。
下载地址:<desktopBaseUrl>/download/desktop/YuncangTraceSetup-<版本>.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
前端顶栏的下载入口(2026-10-29)
网页端所有页面的右上角都有两个下载按钮(frontend/src/components/AppLayout.vue,与权限无关,登录后就能看到):
- 「桌面端 vX.Y.Z」→
version.json里的downloadUrlExe(EXE)/downloadUrl(MSI,老客户端) - 「Android 扫码台 vX.Y.Z」→
version.json里的downloadUrl(APK)
版本信息由 frontend/src/api/download.ts 直接 fetch 两个 version.json(注意:这两个路径返回的是
version.json 原文,不是 { ok, data } 包装,所以没走 api/client);还没发布过安装包时按钮置灰、点击提示,
不会跳到 404。nginx 里这两个路径是精确 location 反代到 Egg 的,安装包目录才是静态托管。
单元测试
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_DAILY_LIMIT |
10 |
每个邮箱每天最多发几封邮件(注册验证码 + 找回密码共用,超出提示「明天再试」) |
EMAIL_RESET_TTL |
1800 |
重置密码链接有效期(秒,默认 30 分钟) |
SITE_URL |
空 | 邮件里重置链接的站点地址(如 https://packs.example.com);不配则用当前请求的 host |
WX_GATEWAY_BASE |
https://gateway.gztbyc.com |
微信登录网关地址(登录页扫码 / 绑定微信 / 工作台扫码登入) |
WX_GATEWAY_APP_KEY |
空 | 网关应用的 appKey(gwk_…);不配 = 未开通,扫码接口 503 |
WX_GATEWAY_APP_SECRET |
空 | 网关应用的 appSecret(gws_…),只放服务端(验证回调签名) |
WX_GATEWAY_POLL_WAIT / WX_GATEWAY_SCENE_TTL / WX_GATEWAY_NOTIFY_SKEW |
55 / 660 / 300 |
网关扫码的长轮询上限(秒)/ 本地会话有效期(秒)/ 通知时间戳容差(秒) |
WECHAT_QR_CELL / WECHAT_QR_MARGIN |
6 / 4 |
二维码 SVG 的单元格像素 / 静默区格数(⚠️ 库的 margin 参数单位是像素,代码里已按格×单元格换算;<4 格会影响扫码) |
PAY_MOCK / PAY_CALLBACK_SECRET |
开发默认开 / 空 | 模拟支付回调(免签名)/ 回调签名密钥(X-Pay-Sign) |
PAY_AMOUNT_PER_DAY |
0 |
每天默认价格(0 = 不校验金额,内部测试用) |
PAY_ORDER_TTL |
7200 |
待支付订单有效期(秒):超时自动关闭,之后的回调/手工确认一律 409(与微信扫码支付二维码 2 小时有效期对齐) |
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 | 最近登录时间 |
| password_hash | varchar(100) | bcrypt 密码哈希(接口/页面都不外泄,查询时显式 exclude) |
| password_changed_at | datetime | 最近一次设置/重置密码的时间(可空);签发时间早于它的 user JWT 立即失效 |
| 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 | 时间戳与软删除 |
设备接入流程(只有一条链路):
- 拿令牌(也就是注册):
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)。
刷新令牌(自动续期,2026-10-19)
访问令牌(365 天)到期后,无人值守的后台服务没法自己登录,所以激活时同时下发刷新令牌:
- 刷新令牌是不透明随机串(32 字节 base64url);库里只存
sha256(scanners.refresh_token_hash),不存原文; - 有效期默认 730 天(
config.jwt.deviceRefreshExpiresIn,envDEVICE_REFRESH_EXPIRES);每次刷新都会轮换并顺延; - 接口:
POST /api/device/refresh,body{ refreshToken, sn? }(也认 headerX-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/web/auth/wechat-gateway/* |
| 手机确认登录 | /wechat?spm=… |
/api/wechat/confirm |
| 忘记 / 重置密码 | /forgot、/reset |
/api/web/auth/{forgot,reset} |
| 首页统计 | / |
/api/web/stats(`?days=7 |
| 设备管理 | /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/*};/api/web/admin/* 额外要 middleware.platformAdmin() |
| 运维 / 内部(运维脚本、后台系统) | app/controller/internal/ |
middleware.internalAuth()(X-Internal-Token 或白名单账号的 user JWT) |
/api/users*、/api/configs*、/api/scanners*、/api/scanner/{bind,unbind}、/api/internal/wechat-bindings* |
| 用户态(小程序 / 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/{status,qrcode.svg}、/api/wechat-gateway/notify(设备发码 GET /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_login/wx_gateway/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/internal/wechat-bindings?openid=&userId= |
微信登录网关的绑定关系(含已解绑的)+ 账号状态 |
| DELETE | /api/internal/wechat-bindings/: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 |
设备「扫码登录 + 注册」(扫码确认,下发长期 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: [](虚拟通道 CAM- 前缀豁免,见面单摄像头) |
| 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:当前中控上报的扫码记录 |
| GET | /api/scanner/label-cameras |
需扫描器 JWT:本机该跑的面单摄像头识别配置 → { revision, items, channels, warnings, scannedAt }。返回本主体、启用中工作台(散单和团购都支持)里被设为面单摄像头的绑定;items[] 带 workstationId/Name、wsType(1 散单 / 2 团购)、channelId/Name(本机的扫码通道;工作台没接扫码枪时是虚拟通道 CAM-<工作台id>,见下)、virtualChannel(true = 虚拟通道)、cameraId/Name、cameraChannelNo、streamType、nvr{host,port,username,password}。channels[] 是本机所有被工作台绑定的通道 + wsType(含虚拟通道),设备端用它决定扫码枪那条路的记录规则(散单取第一次、团购取最后一次)。revision 是内容指纹(含密码和通道模式),变了设备端就重建识别任务。RTSP 路径不在这里拼(要按录像机「首个数字通道号」换算,只有设备端问得到)。读接口,不挂 subjectActive |
| PUT | /api/web/workstations/:id/cameras/:cameraId/label |
设置/取消面单摄像头({ isLabelCamera: true/false },不传按设置)。散单、团购都可以;一台工作台最多一路,设新的会先清旧的;取消时顺手清理虚拟通道 |
扫码上报的两个接口都不会因为重复而报错(幂等):完全重复的条数计入 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, Scanner, 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 withScanners = await User.findOne({ where: { id: 1 }, include: [{ model: Scanner, as: 'scanners' }] });
// 原生 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'); // 软删除 + 清缓存
// ===== 微信绑定(网关绑定关系,app/service/wx_gateway.js)=====
const binding = await this.ctx.service.wxGateway.findBinding({ appKey, openid: 'o_abc' }); // 带用户
await this.ctx.service.wxGateway.forceUnbind(12); // 运维强制解绑
// ===== 扫描器长期 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_gateway_bindings用(app_key, 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校验通过才能建号。- 发码前先判邮箱是否已被占用:
service.user.findByEmail()用LOWER(email) = ?查(大小写不敏感)+paranoid: false(软删除账号仍占唯一键),命中就直接 409email_taken「该邮箱已被使用…」,一封邮件都不发;提交注册时再判一次(防止发码后被别人抢先注册); - 验证码存 Redis(
packs:verify:register:<email>,TTLEMAIL_CODE_TTL,默认 10 分钟);重发节流(SET NX,默认 60 秒);错试超过EMAIL_CODE_ATTEMPTS(默认 5 次)作废;注册成功才消费验证码(用户名/邮箱冲突时可改完重提,不用重新收码); - 每日发信上限:
packs:mailquota:<email>:<yyyy-MM-dd>(service/mail_quota.js),同一邮箱每天最多EMAIL_DAILY_LIMIT(默认 10)封,注册验证码与找回密码共用这个额度;超出返回 429daily_limit「该邮箱今天已发送 10 封邮件,达到上限,请明天再试」;按北京时间(UTC+8)切日,key 的 TTL 到当天 24 点自动过期。发信失败 / 被 60 秒节流拦下会把额度还回去; - 发信走
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>1EMAIL_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 盖成「服务器内部错误」,用户看不懂); -
每日发信上限(与注册验证码共用额度):同一邮箱每天最多
EMAIL_DAILY_LIMIT(默认 10)封,超出返回 429 +{ status:'daily_limit', message:'该邮箱今天已发送 10 封邮件,达到上限,请明天再试' },不生成令牌也不发信(防止被反复点击骚扰收件人 / 刷爆 SMTP 配额);按北京时间(UTC+8)切日; -
用户按邮箱查也走
service.user.findByEmail()(大小写不敏感 + 含软删除),避免换个大小写就绕过额度或漏发;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 秒容差:改密当秒新签发的令牌仍然可用,避免误杀);
-
- 扫码登录(微信登录网关,2026-10-28 起):登录页右上角三角形的扫码面板改为对接
微信登录网关。不再自己发 6 位串码、也不再依赖自家公众号回调
(旧的
GET /api/wechat/login已删除;/api/wechat/{qrcode.svg,status}只剩设备扫码登录在用)。- 配置(
config.wxGateway,全部走 env):WX_GATEWAY_BASE(默认https://gateway.gztbyc.com)、WX_GATEWAY_APP_KEY/WX_GATEWAY_APP_SECRET(网关管理台建应用时拿,只放服务端)、WX_GATEWAY_POLL_WAIT(长轮询上限,默认 55s)、WX_GATEWAY_SCENE_TTL(本地会话 TTL,默认 660s)、WX_GATEWAY_NOTIFY_SKEW(通知时间戳容差,默认 300s)、WX_GATEWAY_TIMEOUT(调网关超时,默认 8s)。 不配 appKey/appSecret → 扫码相关接口 503(未开通微信扫码登录),前端据此提示; - 网关管理台里必须把「服务端通知地址」配成
https://<本站域名>/api/wechat-gateway/notify(=config.wxGateway.notifyPath),这是扫码结果回到本站的唯一通道; - 完整时序(
service/wx_gateway.js):- 前端
POST /api/web/auth/wechat-gateway/qrcode→ 服务端向网关POST {网关}/api/auth/temp-code(header 带X-App-Key/X-App-Secret)拿临时码 + 授权页地址,同时把「这次扫码要干什么」 写进本地会话(Redispacks:wxgw:sess:<state>;state是我们自己的 32 位 hex,原样带给网关); - 前端把
qrUrl(/api/wechat-gateway/qrcode.svg?state=…)当图片显示 —— 二维码仍然是本地画 (qrcode-generator,零外链资源),内容就是网关给的pageUrl;桌面端(WPF)用同一张图的 GIF 版 (/api/wechat-gateway/qrcode.gif?state=…); - 用户用手机微信扫码 → 网关页点确认 → 网关静默授权(
snsapi_base)拿 openid → 带签名 POST 我们的notifyPath(event/appKey/openid/bindCode/state/timestamp/nonce/sign); - 服务端验签(密钥是
sha256(appSecret)的十六进制,签名串appKey.userId.bindCode.timestamp.nonce; 时间戳偏差 > 5 分钟直接 401)→ 按openid查wechat_gateway_bindings找到平台账号 → 把结果写回会话并PUBLISH唤醒长轮询(验签失败 401;会话已过期返回 200 +{ignored:'session_expired'}, 免得网关白重试); - 前端
GET /api/web/auth/wechat-gateway/login?state=&wait=55拿到{ status:'confirmed', token, user }—— 令牌是这一步当场签发的,Redis 里不落令牌;
- 前端
- 长轮询语义(
awaitSession()):pending(还在等,继续轮询)/confirmed(成功,取走即删)/failed(附message,例如「这个微信还没绑定平台账号」)/expired(会话没了 → 前端重新申请一张继续轮询); 客户端断开(切面板 / 关页签)→ 服务端立刻停止等待(aborted,不写响应);前端自己设 70s 超时; - 不自动建号:只有「已经绑定微信」的账号能扫码登录;绑定入口在个人中心(见下一条);
- 配置(
- 绑定微信(个人中心,2026-10-28 新增):
POST /api/web/me/wechat/qrcode(需令牌)申请scene=bind的网关二维码, 手机确认后网关回调 → 写wechat_gateway_bindings:UNIQUE(app_key, openid):一个微信只能绑一个账号;同一账号也只留一个微信(换绑要先解绑);GET /api/web/me/wechat/bindings→{ list, enabled }(enabled=false= 服务端没配网关,前端整块灰掉);GET /api/web/me/wechat/status?state=&wait=长轮询绑定结果(binding里是落库后的绑定关系);DELETE /api/web/me/wechat/bindings/:id解绑(只能删自己的,找不到 404);- 表结构:
wechat_gateway_bindings(迁移20261028120000):网关用的公众号 appid 我们并不掌握, 只有app_key+openid,所以单独一张表(旧的wechat_oauth/wechat_mp_accounts已于20261029100000删除); - 设备专用:扫码登录 + 注册(
GET /api/device/login,app/controller/device.js):给「设备上不好敲账号密码、甚至出厂什么都不用配」的场景用—— 登录即注册:设备插上电直接要一个登录码显示在设备屏幕上,用已经登录的手机(小程序/网页)扫一下确认, 服务端这才把设备注册到那个账号名下(归属 = 确认登录的人),并把长期 JWT 发给设备 (默认 365 天,见config.jwt.deviceExpiresIn/ envDEVICE_JWT_EXPIRES; 设备可用?expiresIn=30d(或秒数)申请更短的,超上限 422):- 不需要凭据、也不需要预先注册(公开接口);
- 不带
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:长轮询(上限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: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(已是完整网址,设备无需知道域名) }
- 新增/重置登录账号:
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(不会把别人的设备扫走),无主记录(老接口注册出来的)由本次确认者认领; - 扫码登入工作台:二维码按需生成(网关一次性临时码),手机微信确认后由网关回调落
workstation_login_records; 旧的工作台登录码(WSC-)与POST /api/web/workstation-login已废弃(见下文「工作台成员登录」); - 没有 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/web/admin/*再叠一层app/middleware/platform_admin.js(平台管理员);/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/{status,qrcode.svg}、/api/wechat-gateway/notify、/api/device/login与/api/web/auth/*; - 密码等敏感信息放
config/config.local.js(已 gitignore)或环境变量,不要写进config.default.js。 - 生产环境请修改
config/config.default.js中的config.keys。
平台管理员与平台管理台(2026-10-29)
两种「管理员」互不相干,别混:
| 谁 | 能干什么 | 存在哪 | |
|---|---|---|---|
| 主体管理员 | 某个主体里的 role=1 成员 |
只管自己那个主体:成员、设备、录像机、工作台、扫码记录、续期下单 | subject_members.role / subjects.admin_user_id |
| 平台管理员 | 平台的运营/管理人员 | 看所有主体与订单、改授权到期时间、确认订单、加别的平台管理员 | admin_members(+ INTERNAL_ADMIN_IDS 内置名单) |
数据表
| 表 | 说明 |
|---|---|
admin_members |
平台管理员:user_id(唯一,账号 id)+ name(显示名,不填取昵称/用户名)+ role(1 超级管理员 / 2 管理员)+ status(1 启用 / 0 停用)+ remark;软删除 |
迁移 20261029120000-create-admin-members:
- 建表 +
uk_admin_members_user(user_id唯一)+idx_admin_members_status; - 把内置管理员先塞进来(
users.username='admin',没有就id=1),保证升级后立刻能用; - ⚠️ 软删的行仍占着
user_id唯一索引,所以「查重 / 加回来」必须带paranoid: false(service/admin_member.js已处理:命中软删行就restore())。
谁是平台管理员(middleware/platform_admin.js)
满足其一即可,ctx.state.platformAdmin 记录通过方式:
admin_members里status=1的行(页面可自助维护);config.internal.adminIds(envINTERNAL_ADMIN_IDS,默认[1])——内置 / 救急入口: 就算把页面上的管理员全删了,也还能用它登录把入口加回来(前端会标「内置」且不给移除按钮)。
不通过 → 403 { status: 'not_platform_admin' }。这些接口都要 user JWT(apiAuth 之后才校验)。
接口(/api/web/admin/*,全部要求平台管理员)
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/web/admin/me |
当前账号是不是平台管理员 → { admin, builtin, user }(前端决定要不要显示「平台管理」菜单) |
| GET | /api/web/admin/members |
平台管理员列表(表里的 + 内置名单里表里没有的,后者 id=null、builtin=true) |
| POST | /api/web/admin/members |
添加 { account, name?, role?, remark? };account = 用户名 / 手机号 / 邮箱。账号不存在 404、已是管理员 409、账号被禁用 409 |
| DELETE | /api/web/admin/members/:id |
移除(软删;不能移除自己,也不能把最后一个启用的管理员删光) |
| GET | /api/web/admin/subjects?page=&pageSize=&keyword=&status=&expired= |
所有主体(带成员数 / 管理员账号 / 是否过期);keyword 模糊匹配主体名或备注;expired=1|0 只看已过期 / 未过期 |
| PUT | /api/web/admin/subjects/:id |
改授权到期时间:{ expireAt: '2027-01-01T00:00:00+08:00' } 直接设(可设成过去 = 立即到期),或 { extendDays: 30 } 顺延(未过期从原到期时间算、已过期从现在算);也可顺带改 remark / status |
| GET | /api/web/admin/orders?page=&pageSize=&keyword=&status=&subjectId= |
所有订单(带主体名 / 下单人);keyword 模糊匹配订单号、套餐名、主体名;status=0|1|2 |
| POST | /api/web/admin/orders/:orderNo/confirm |
确认订单(线下收款 / 手工补单):与支付回调走同一套 service.subjectOrder.payNotify(),所以「标记已支付 + 主体顺延 + 失效主体状态缓存 + 幂等」完全一致,只是渠道记成 manual、流水号 ADMIN-<时间戳> |
改授权到期时间后必须失效主体状态缓存(subjectState.invalidate),否则设备心跳 / 上报最多要等一个 TTL 才看到新期限 —— service/subject.js#setExpireAt() 已经做了。
Chrome 插件配置(集中下发)
插件只拉取执行,配置存在 sys_config(group='extension', config_key='config', value_type=json),不新建表。
| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| GET | /api/web/admin/extension |
平台管理员 | 当前配置(含 version / updatedAt / 已生成的正则 pattern) |
| PUT | /api/web/admin/extension |
平台管理员 | 保存 { enabled, hosts, prefixes, minDigits, maxDigits, urlTemplate, appUrlTemplate, downloadUrl };不收 pattern,正则由服务端拼;成功后 version + 1 |
| GET | /api/web/extension/config |
公开(可选 ?key=) |
插件读的副本;config.extension.appKey(env EXTENSION_APP_KEY)非空时要求 key 一致 |
- 单号正则 =
\b(?:<前缀用 \| 连接>)\d{min,max}\b(service/extension_config.js#buildPattern),前缀只允许大写字母/数字、1~8 位、最多 50 个; hosts是插件生效站点(glob,支持*.abc.com);留空按['*']处理;- 插件每 5 分钟拉一次,靠
version判断要不要更新(版本没变不写存储);GET /api/web/extension/config的返回在 Redis 缓存 1 小时(extension:config:public),后台PUT保存时立刻删缓存 —— 提交即生效,平时又不会每 5 分钟回源一次; - 发布新安装包不用清缓存:安装包地址由插件每次直接读 nginx 的
/download/version.json(nginx 对这个路径是 no-cache),不进这份 1 小时缓存;service/extensionConfig.invalidate()留给运维/发布脚本需要时手工调用; downloadUrl不用配:插件同步时优先读GET /download/version.json,永远用最新发布版本 (后台页面已不提供这个输入框;配置里的值只在 version.json 拉不到时兜底);- 生产若配了
CORS_ORIGINS白名单,记得把chrome-extension://<扩展ID>加进去(默认*不用管)。
前端(frontend/)
左侧菜单在平台管理员登录后会多出一组「平台管理」(components/AppLayout.vue):
| 菜单 | 路由 | 页面 | 干什么 |
|---|---|---|---|
| 主体管理 | /admin/subjects |
views/AdminSubjectsView.vue |
所有主体;「改到期时间」弹窗支持直接选时间或顺延 N 天(+7 / +30 / +90 / +1 年快捷按钮) |
| 订单管理 | /admin/orders |
views/AdminOrdersView.vue |
所有订单;待支付的可以「确认订单」(二次确认后立即续期) |
| 管理员 | /admin/members |
views/AdminMembersView.vue |
平台管理员列表 + 添加(按账号)+ 移除 |
- 是否显示这组菜单靠
GET /api/web/admin/me(composables/usePlatformAdmin.ts;非管理员 403 静默当 false); - 路由带
meta.platformAdmin,不是平台管理员会被守卫踢回首页(?denied=1); - 这三个页面
allowNoSubject: true—— 平台管理员可能一个主体都没有,不能因为「没主体」被挡走。
主体(租户)体系(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 |
workstation_login_records |
工作台成员登录记录:谁在什么时候登入 / 下线了哪台工作台(见「工作台成员登录」) |
| 业务表 | 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 |
成员列表(任何成员都能看,只读;带 isCreator 标记创建者) |
| POST | /api/web/subjects/:id/members |
按姓名快速添加成员 { name }(仅管理员,此时还没绑账号) |
| DELETE | /api/web/subjects/:id/members/:memberId |
移除成员(仅管理员;不能删创建者/管理员/自己,管理员要先取消管理员) |
| PUT | /api/web/subjects/:id/members/:memberId/role |
设/取消管理员 { role: 1|2 }(仅管理员;一个主体可多名管理员,创建者恒为管理员不能降级,不能改自己) |
| POST | /api/web/subjects/:id/members/:memberId/bind-qr |
生成「扫码绑定」二维码(仅管理员,走微信登录网关)→ { memberId, memberName, state, pageUrl, qrUrl, expiresIn };成员已绑真实账号时 409 |
| GET | /api/web/subjects/:id/members/:memberId/bind-qr/status?state=&wait= |
长轮询绑定结果(仅管理员)→ { status, memberName?, boundName?, autoCreated?, message? }(pending / confirmed / failed / expired) |
| POST | /api/web/subjects/:id/members/:memberId/unbind |
解除成员的账号绑定(仅管理员;绑错了/手机换人时用,自动建的临时账号会一并删除) |
角色规则(subject_members.role):
- 一个主体可以有多个管理员(
role=1没有唯一约束);subjects.admin_user_id只是创建者,同样恒为管理员; - 成员管理(加成员 / 扫码绑定 / 解除绑定 / 设·取消管理员 / 移除)只有管理员能做,普通成员只能看成员列表(只读);
- 创建者不能降级、不能移除;不能改自己的角色、不能删自己(避免管理员把自己锁死);
- 管理员不能直接移除,需先「取消管理员」;给未绑定账号的成员设为管理员,绑定后即为管理员。
成员扫码绑定(微信登录网关,2026-10-28)
管理员点「扫码绑定」出一张网关二维码,成员用手机微信扫码确认后按两种情形落地(service/subject.js#bindMemberWithWechat):
- 这个微信已经是某个平台账号的登录方式(
wechat_gateway_bindings里有它)→ 成员直接继承那个账号; 如果成员之前挂着一个自动建的临时账号,那个账号会被软删(连它的微信绑定一起清掉),subject_members.temp_user_id置空; - 这个微信还没有平台账号 → 服务端自动给这名成员建一个账号(用户名
member<成员id>、随机密码、昵称=成员姓名), 把微信绑成它的登录方式,并记在temp_user_id上;此后这名成员可以直接微信扫码登录; - 例外(都会变成会话里的
failed,弹窗直接显示原因):微信绑定的账号被禁用、这个账号已经是本主体成员(subject_members唯一键)、 成员已绑其他真实账号(先「解除绑定」再扫)。
旧的「6 位绑定码 + /wechat?bind=<码> 手机确认页」已删除(/api/subject/member-bind* 一并移除),
/api/wechat/qrcode.svg?mode=member 的 mode 参数也一起去掉。
续期套餐与订单(支付回调驱动)
续期不再是「自己输入天数」:前端先选套餐(天数 + 定价都在库里),点「生成订单」只落一笔待支付订单, 不会立刻续期;只有支付渠道回调确认后才把主体期限顺延(幂等,重复回调不重复续期)。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/web/subject-plans |
上架套餐 { list: [{ id, code, name, days, price, originalPrice, tag, description, pricePerDay }] }(任何登录用户可读) |
| GET | /api/web/subjects/:id/orders |
订单列表(成员可见,{ total, page, pageSize, list }) |
| POST | /api/web/subjects/:id/orders |
选套餐下单 { planId, remark? }(仅管理员)→ { orderNo, planId, planName, days, amount, status:0待支付, pending:true, payExpireAt, expired:false, … };金额只认套餐价,前端传的 amount/days 一律忽略 |
| GET | /api/web/subjects/:id/orders/:orderNo |
单笔订单(续期弹窗每 2s 轮询支付状态,pending=false 即停止;超时会被就地关闭成 status=2) |
| POST | /api/web/subjects/:id/orders/:orderNo/close |
关闭待支付订单(仅管理员;已支付 → 409) |
| POST | /api/pay/notify |
公开的渠道回调 { orderNo, transactionId?, amount?, channel?, paidAt? } → { duplicated, order };订单不存在 404、金额不符 422、签名错 400、超时失效 409 |
| POST | /api/internal/subject-orders/:orderNo/pay |
内部令牌:模拟支付成功(不需要签名),方便联调/补单;超时订单同样 409 |
待支付订单 2 小时自动失效(config.pay.orderTtl,env PAY_ORDER_TTL,默认 7200 秒):
支付截止时间 = created_at + TTL,响应里的 payExpireAt / expired / pending 就是给前端做倒计时和停止轮询用的
(pending=false 表示不用再轮询;expired 只在「还是待支付但已过截止时间」时为 true,
正常读一次就会被就地关成 status=2,这时看 status / statusText 即可)。超时订单会被置为 status=2(已关闭),
之后再到支付回调 / 手工确认,一律 409「订单已超时失效,请重新下单」(与微信扫码支付二维码 2 小时有效期一致)。
关单有三个触发点,互相兜底:
- 定时任务
app/schedule/subject_order_expire.js(每分钟一次,type: worker,逻辑幂等); - 读路径(订单详情 / 订单列表 / 平台订单列表)读到超时订单随手关掉;
payNotify()进门先判一次(含事务内兜底),避免回调与关单并发时把已失效订单续期。
订单会快照 plan_id / plan_code / plan_name,套餐后续改价或下架都不影响历史订单对账。
套餐表 subject_plans(迁移 20261021180000-create-subject-plans 内置三档,改价直接改库、不用发版):
| code | 天数 | 价格 | 备注 |
|---|---|---|---|
p30 |
30 | ¥99 | 短期试用 / 临时项目 |
p180 |
180 | ¥499 | 角标「推荐」,划线价 ¥594(≈¥2.77/天) |
p365 |
365 | ¥899 | 角标「最划算」,划线价 ¥1204(≈¥2.46/天) |
签名:配置了 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 '{"planId":1}'
# 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>"
成员绑定不再用 6 位码:改用微信登录网关的二维码,见上文「成员扫码绑定」(POST /api/web/subjects/:id/members/:memberId/bind-qr)。
主体上下文(统一处理)
- 业务接口除
apiAuth外必须再挂middleware.subjectAuth();它按X-Subject-Idheader(也认?subjectId=/ body.subjectId)解析主体:- 没带 → 400
{ status: 'subject_required' } - 不是该主体成员 / 主体不存在 → 404
- 主体被停用 → 403
subject_disabled;主体到期 → 403subject_expired(带expireAt) - 通过后写
ctx.state.subjectId / subject / subjectMember,service 一律用subjectId限定范围
- 没带 → 400
- 业务数据只给主体管理员:设备 / 录像机 / 摄像头 / 工作台 / 扫码记录这些接口在
subjectAuth之后 再挂middleware.subjectAdmin(),普通成员一律 403{ status: 'subject_forbidden' }(判定与subjectService.ensureAdmin一致:创建者或role=1)。 前端同步:左侧菜单只对管理员显示这几项,路由meta.adminOnly会把成员挡回首页;/api/web/stats与/api/web/pack-query不拦(首页概览 / 桌面端打包查询普通成员也要用)。GET /api/web/nvrs/:id/credential也不拦:按运单回放/下载录像要凭据,是打包现场日常动作, 普通成员可以取,但范围由nvr.credentialOf(id, subjectId)限定在当前主体(别的主体一律 404); 其余/nvrs管理接口仍然只给管理员。 - 登录(
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-gateway/qrcode.gif?state= |
桌面端(WPF)登录二维码的 GIF(不能渲染 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)。
面单摄像头 & 虚拟通道(CAM-<工作台id>)
工作台的面单摄像头(workstation_cameras.is_label_camera = 1,一台工作台最多一路,散单/团购都能设)
由桌面端拉 RTSP 识别条码,识别结果按「该工作台 + 本机通道」上报。记录规则按工作台类型分流
(下发里的 wsType):散单取第一次 + 立即上报,团购和扫码枪一样静默 5 秒取最后一次。
工作台没接扫码枪(没绑本机通道)也能用:GET /api/scanner/label-cameras 会顺手给它一条
虚拟通道,规则如下(实现在 app/lib/virtual-channel.js):
| 项 | 规则 |
|---|---|
| 通道 id | CAM-<工作台id>,与设备上报的真实通道(纯数字 / DESKTOP)不会冲突 |
| 通道名 | 面单摄像头·<摄像头名> |
| 创建 | 设备拉配置时幂等自愈(label_scan.ensureVirtualChannel),并绑到该工作台(回放定位靠 scanner+channel → 工作台) |
| 清理 | 取消面单摄像头、绑上真实扫码通道、删除工作台时自动清掉(workstation.releaseVirtualChannel) |
| 对账豁免 | POST /api/scan/channels 的 replace: true 不动 CAM- 前缀的通道(设备列表里永远没有它) |
| 前端 | 工作台详情里标记「虚拟」,不给解绑;人工绑定通道列表里也不出现 |
| 播报 | 虚拟通道没有对应的安卓扫码工位,所以不会通知安卓端播报 |
变更怎么通知到设备(labelScan.refresh)
设备端只有「启动拉一次 + 每分钟兜底」,秒级生效靠服务端主动推:
| 触发点 | 位置 |
|---|---|
| 设置/取消面单摄像头 | workstation.setLabelCamera |
| 解绑摄像头(可能是面单那路)/ 删除摄像头 | workstation.unbindCamera、camera.remove、camera.batchRemove |
| 摄像头停用/改名 | camera.update |
| 绑定/解绑上报通道(面单结果落点变了) | workstation.bindScanChannels、unbindScanChannel |
| 工作台改名/改类型/停用/删除 | workstation.update、workstation.remove |
实现:labelScan.notifyChanged(subjectId) 给本主体每台启用中的设备入队一条
labelScan.refresh edge 任务(edge_task.enqueue)。设备收到只是被「叫醒」,真正的配置仍以
GET /api/scanner/label-cameras 为准;入队失败只记日志(配置已落库,不能因为通知失败回滚)。
工作台成员登录(2026-10-24)
成员用手机微信扫管理员生成的二维码登入工作台(2026-10-28 起走微信登录网关,旧的 WSC- 登录码已废弃)。这张表同时回答两件事:
「现在这台工作台上是谁」和「某张运单打包时是谁」。
数据表
| 表 / 字段 | 说明 |
|---|---|
workstations.login_code |
已废弃(迁移 20261028121000 删除):扫码登入改走微信登录网关,二维码按需生成、一次有效 |
workstations.last_active_at |
最后活跃时间(扫码上报 / 有人登录时刷新) |
workstations.idle_timeout_sec |
多少秒不活跃自动下线所有成员(团购默认 3600、散单默认 1800) |
workstation_login_records |
一次登录一行:subject_id / workstation_id / user_id(+ member_id)/ name / type(1 扫码登录,预留扩展)/ login_code(历史字段,新记录为空)/ login_at / logout_at / status(1 在线 0 下线)/ logout_reason / login_ip |
- 索引:
(workstation_id, login_at)(运单回放定位「当时谁在线」)、(workstation_id, status)、(user_id, status)、(subject_id, login_at)、status(定时任务扫在线)。 name记登录当时的名字:是工作台所属主体的成员 → 成员姓名(= 工号);不是成员 → 用户自己设置的昵称。logout_reason:manual手动下线 /offline_all一键全部下线 /reset_code(旧版重置登录码,仅历史)/idle_timeout长时间不活跃 /relogin同一个人重新登录 /workstation_deleted工作台被删除。
接口
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/web/workstations/:id/login-qr |
生成扫码登入二维码(微信登录网关,scene=login)→ { workstationId, state, pageUrl, qrUrl, expiresIn };二维码一次有效 |
| GET | /api/web/workstations/:id/login-qr/status?state=&wait=25 |
长轮询扫码结果 → { status, workstation?, member?, name?, record? }(pending / confirmed / failed+message / expired);手机确认后网关回调落登录记录,同一账号重复登录旧记录按 relogin 下线 |
| GET | /api/web/workstations/:id/members?status=1&startTime=&endTime=&page=&pageSize= |
成员列表(status=1 只看在线,不传 = 含历史;startTime/endTime 按登录时间过滤)→ { list, total, page, pageSize, onlineCount } |
| POST | /api/web/workstations/:id/members/:recordId/offline |
手动下线某条在线记录(幂等,已下线返回 alreadyOffline: true) |
| POST | /api/web/workstations/:id/members/offline-all |
把该工作台所有在线成员下线(offline_all)→ { id, offline } |
| GET | /api/web/pack-query?code= |
每条 records[].packers = 该次扫码时还在线的人([{ id, userId, memberId, name, loginAt, logoutAt }]) |
鉴权:/login-qr、/login-qr/status、/members、/offline、/offline-all 与工作台其它接口一致(apiAuth + subjectAuth + subjectAdmin)。
登入本身发生在网关回调(/api/wechat-gateway/notify,公开但必须验签)里:openid → wechat_gateway_bindings → 平台账号 →
workstationLogin.loginByUser()(主体停用 → 403、过期 → 403、工作台停用 → 403 都会变成会话里的 failed + 原因)。
⚠️ 旧接口 POST /api/web/workstation-login({ code })与 POST /:id/login-code/reset 已删除。
自动下线
- 扫码上报(
POST /api/scan/records)成功后刷新相关工作台的last_active_at;有人登录也会刷新。 - 定时任务
app/schedule/workstation_idle_offline.js每分钟扫一次还在线的记录:now - (last_active_at || 该工作台最晚一条在线记录的 login_at) >= idle_timeout_sec→ 把该工作台所有在线记录下线(idle_timeout)。从没上报过条码的工作台按「最晚登录时间」算, 不会出现「刚建的工作台永远不下线」;工作台已删除则按workstation_deleted收尾。 - 默认值:团购 3600 秒、散单 1800 秒;
POST/PUT /api/web/workstations的idleTimeoutSec可改(60~86400 秒)。 只切类型且没传idleTimeoutSec时,自动套用新类型的默认值。
运单打包人员
GET /api/web/pack-query 的 records[].packers 来自 workstation_login_records:
login_at <= 扫码时间 <= (logout_at ?? 现在)(按秒比较,兼容设备上报的秒级扫码时间),
同一时刻多人同时在线就是多人打包(数组,可能为空)。
用户协议(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-29 移除)
自建的「小程序 code2Session 一键登录」已经整体下线,微信侧的接入统一走下面的微信登录网关:
- 删除的表:
wechat_mp_accounts(小程序 openid ↔ 平台账号)、wechat_oauth(自建公众号网页授权 + 运维手工维护的绑定关系); - 删除的接口:
POST /api/web/auth/wechat/{login,bind}、GET /api/web/auth/wechat/bindings、DELETE /api/web/auth/wechat/bindings/:id、GET /api/users/:id/wechats、GET /api/wechat/:appid/:openid、POST /api/wechat/bind、PUT /api/wechat/:id/tokens、DELETE /api/wechat/:id; - 删除的代码:
app/service/{wechat,wechat_mp}.js、app/controller/web/wechat_mp.js、app/model/{wechat_oauth,wechat_mp_account}.js、service/user.js#findByOpenid、service/wechatLogin.js#{login,exchangeCode,oauthAuthorizeUrl}、GET /api/wechat/callback; - 删除的环境变量:
WECHAT_APPID/WECHAT_SECRET/WECHAT_REDIRECT_URI/WECHAT_API_BASE/WX_MP_APPID/WX_MP_SECRET/WX_MP_MOCK; - 迁移:
20261029100000-drop-legacy-wechat-tables.js(down会按原结构重建两张空表)。
现在小程序只支持账号密码登录;/api/wechat/{status,qrcode.svg} + POST /api/wechat/confirm 仅剩设备扫码登录在用。
微信登录网关(扫码登录 / 绑定微信 / 工作台扫码登入,2026-10-28)
对接 gateway.gztbyc.com:二维码与「扫码确认」都由网关提供, 本服务只负责 申请临时码 → 验签收通知 → 落地自己的业务。
环境变量
| 变量 | 默认值 | 说明 |
|---|---|---|
WX_GATEWAY_BASE |
https://gateway.gztbyc.com |
网关地址(本地联调可指向假网关) |
WX_GATEWAY_APP_KEY |
空 | 网关应用标识(gwk_…);空 = 未开通,扫码接口一律 503 |
WX_GATEWAY_APP_SECRET |
空 | 网关应用密钥(gws_…),只放服务端,用来验证回调签名 |
WX_GATEWAY_POLL_WAIT |
55 |
长轮询最长挂起秒数(前端再留 70s 自己的超时) |
WX_GATEWAY_SCENE_TTL |
660 |
本地扫码会话有效期(秒,比网关临时码的 10 分钟略长) |
WX_GATEWAY_NOTIFY_SKEW |
300 |
通知 timestamp 允许偏差(秒) |
WX_GATEWAY_TIMEOUT |
8000 |
调网关接口的超时(毫秒) |
⚠️ 网关管理台必须把「服务端通知地址」配成 https://<本站域名>/api/wechat-gateway/notify。
接口
| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| POST | /api/wechat-gateway/notify |
签名 | 网关回调(X-Gateway-* / body 里的 sign);验签失败 401,会话过期 200 + {ignored:'session_expired'} |
| POST | /api/web/auth/wechat-gateway/qrcode |
公开 | 申请登录二维码 → { state, pageUrl, qrUrl, expiresIn };没配网关 503 |
| GET | /api/web/auth/wechat-gateway/login?state=&wait= |
公开 | 长轮询 → { status, token?, user?, message? }(pending / confirmed / failed / expired) |
| GET | /api/wechat-gateway/qrcode.svg?state= |
公开 | 会话里那张二维码的 SVG(本地画,零外链) |
| GET | /api/wechat-gateway/qrcode.gif?state= |
公开 | 同一张二维码的 GIF(桌面端 WPF 不能渲染 SVG) |
| POST | /api/web/me/wechat/qrcode |
user JWT | 申请「绑定微信」二维码(scene=bind)→ 同上结构 |
| GET | /api/web/me/wechat/status?state=&wait= |
user JWT | 长轮询绑定结果 → { status, binding? , message? } |
| GET | /api/web/me/wechat/bindings |
user JWT | { list, enabled }(enabled=false = 没配网关) |
| DELETE | /api/web/me/wechat/bindings/:id |
user JWT | 解绑(只能删自己的;找不到 404) |
| GET | /api/internal/wechat-bindings?openid=&userId= |
内部令牌 | 运维查绑定(含已解绑的),带账号状态(禁用/已删除) |
| DELETE | /api/internal/wechat-bindings/:id |
内部令牌 | 强制解绑任意绑定(微信绑在前员工账号上时兜底) |
| POST | /api/web/workstations/:id/login-qr |
+ 主体管理员 | 二维码(scene=login,purpose=workstation)→ 见「工作台成员登录」 |
| GET | /api/web/workstations/:id/login-qr/status?state=&wait= |
+ 主体管理员 | 长轮询扫码登入结果 |
| POST | /api/web/subjects/:id/members/:memberId/bind-qr |
+ 主体管理员 | 二维码(scene=bind,purpose=member)→ 见「成员扫码绑定」 |
| GET | /api/web/subjects/:id/members/:memberId/bind-qr/status?state=&wait= |
+ 主体管理员 | 长轮询成员绑定结果 |
实现要点
- 会话存 Redis(
packs:wxgw:sess:<state>,state是我们自己的 32 位 hex,原样传给网关):{ status, purpose, scene, pageUrl, tempCode, payload };没有 Redis 时退化为进程内 Map(只适合本地/单测, 多实例部署必须用 Redis,否则回调与轮询可能落在不同实例)。 - 长轮询用 Redis 发布订阅(
packs:wxgw:chan:<state>)唤醒:先SUBSCRIBE再查状态,避免「刚查完就被确认」漏掉; 客户端断开(res的close)会立刻结束等待,不白占连接。 - 验签:
HMAC-SHA256(key = sha256hex(appSecret), msg = appKey.userId.bindCode.timestamp.nonce), 与crypto.timingSafeEqual比较;appKey必须是本应用的,timestamp与当前时间差 >WX_GATEWAY_NOTIFY_SKEW直接拒绝。 - 落地:
purpose=login→openid查wechat_gateway_bindings→ 会话里只放userId,令牌等轮询时再签;purpose=bind→ 写/更新绑定关系(一个 openid 只能绑一个账号,一个账号只绑一个微信);purpose=workstation→workstationLogin.loginByUser()落workstation_login_records(失败原因写回会话);purpose=member→subject.bindMemberWithWechat():微信已有平台账号就直接继承(自动建的临时账号删除), 没有就自动给这名成员建号并把微信绑成它的登录方式(见「成员扫码绑定」)。
- 未绑定微信时
failed的文案是「请先用账号密码登录,在『个人中心 → 微信绑定』绑好后重新扫码」。
「这个微信已经绑了别的账号」怎么处理
绑定时按「原绑定账号是否还能用」分三种情况(handleBind / upsertBinding):
| 情况 | 处理 |
|---|---|
原账号正常(users.status = 1) |
拒绝,会话里给 failed:「这个微信已经绑定了其他账号(<昵称/用户名>):请用那个账号登录后在『个人中心 → 微信绑定』解绑,或联系管理员处理」。不会静默改绑——微信绑定就是登录凭证,不能让拿到微信的人抢走别人的账号 |
| 原账号已禁用或已删除 | 绑定已经"用不了",直接把微信改绑到当前账号(复用同一条 wechat_gateway_bindings 记录),日志 [wx-gateway] 微信 … 原绑定账号 … 不可用,改绑到 userId=… |
| 本人拿不到原账号(前员工 / 手机换人) | 运维用 GET /api/internal/wechat-bindings?openid= 查到这条绑定,再 DELETE /api/internal/wechat-bindings/:id 强制解绑;之后该微信可以重新绑给别人(解绑是软删,下次绑定会 restore 复用这条记录) |
成员扫码绑定(
purpose=member)遇到「微信已绑账号」时不改绑:微信是谁的就绑到谁身上(继承那个账号); 只有那个账号被禁用时才failed提示联系管理员,管理员可以先「强制解绑」再让成员重扫。
- 单测不走真网关:
mock(app, 'httpclient', ...)假装临时码接口,再用service.wxGateway.signOf(body)造合法签名 直接打/api/wechat-gateway/notify(见test/app/controller/wx-gateway.test.js)。