访客门禁管理系统 · TK-Visitor-Gate
访客门禁管理系统官网 · 产品介绍与在线预约演示
项目定位
Positioning大鹏投控企业园区的访客门禁二维码管理系统,把访客预约、员工审批、二维码生成、扫码通行、通行记录查询与账户回收装进同一个 Web 应用,对接达实 C3 门禁平台做真实开门与真实发码。
来访访客在手机上完成预约提交、进度自查与凭证出示,被访员在审批页完成通过驳回与批量处理,园区管理员在后台完成账户池、设备同步、授权下发与记录审计三类管控。
单 Flask 应用对外服务,共 64 路由,其中页面 12 条、管理与业务接口 54 条,另有 7 条设置类路由收敛在 settings 蓝图内注册。
达实 C3 门禁平台是唯一的外部强依赖,提供人员建号、门禁授权、人脸下发、二维码生成、刷卡与刷脸记录五类真实能力。
从访客预约、进度查询、凭证出示,到员工审批、批量审批、远程开门、一键全开,再到账户池分时借还、人脸设备授权、通行记录三维归因、站点设置与公告管理,共十大能力闭环。
门禁点位 404 个,其中启用 387 个,同步于 2026-10-22;人脸设备 60 台,同步于 2026-09-26;访客预约累计 34 条,全部为真实业务数据。
后端为 Python 3.12 加 Flask 3,单应用加一个 settings 蓝图,鉴权装饰器集中收敛在 auth 模块,状态枚举收敛在 constants 模块。
主应用 2699 行,数据层 942 行,C3 客户端 670 行,配置 43 行,鉴权 27 行,设置蓝图 95 行,常量 24 行,合计约 4500 行。
test_ux_round2 十项全过,test_ux_round3 五项全过,旧回归四十九项历史全过,证据链为脚本直跑输出而非人工自述。
管理员口令 PBKDF2 加盐哈希存储,旧明文口令登录成功即自动升级,库中无明文,会话密钥首次启动随机生成并落盘。
服务端口固定 5102,公网与本机同端口,venv 加启动脚本运行,由 Leon-Control 托管,走重启接口换新进程,不手动杀进程。
面向实施运维与二次开发者,先看架构总图与两张时序图建立心智模型,再按数据流、接口清单与部署形态逐段深入。
系统从单文件预约发码起步,先啃 C3 双通道签名与 16 位建号两块硬骨头,再把人脸授权、批量开门、记录归因逐一收编。
页面数字必须与缓存元信息对得上,授权窗口必须与填写值对得上,记录归因必须与分配时段对得上,三条对不上即视为缺陷。
说明书、架构页、展示站与日志页共用同一份底层结论,门禁数只有缓存同步一份结论,路由数只有代码统计一份结论,基线号只有 Git 一份结论。
技术架构
Architecture首页、访客预约、进度查询、审批列表、通行凭证、预约成功页、二维码页、账户通行证、管理后台、开发者模式共 12 页面,访客链路免登录、管理链路强制登录
预约创建查询取消、审批与批量审批、二维码与访客链接、刷卡刷脸记录、三维归因查询、单门远开与批量远开、门禁与人脸同步、建号授权离职、账户池加号与三档回收、可见性配置、开发者批量能力、管理员管理
首页卡片增删改、公告读写、站点设置读写共 7 路由,从主应用拆出后路径保持不变
一次审批通过会依次执行账户确定、分时记账、门禁分时授权、人脸授权、新号入库、二维码获取、令牌生成、分配留痕八步,任一步失败即如实返回不继续
无签名通道优先、签名通道回退,全局单例会话复用 TCP 连接,幂等 GET 查询配两次重试,签名按参数名排序拼密钥做摘要
预约、账户、分配记录、二维码记录、门禁与人脸缓存、可见性配置、站点设置、公告、首页卡片、任务摘要共 11 类文件,写时先落临时文件再同步改名
登录装饰器管全部管理链路,超管装饰器管开发者模式与管理员管理,超管身份只认唯一的管理员账号
任务字典存状态与逐步日志,完成后落盘任务摘要保留最近 50 条,进度接口轮询不阻塞请求
对外请求统一超时,幂等查询重试两次,平台故障时预约照收审批照做、发码授权如实报错待恢复重发
模块组成
Modules| 文件 / 目录 | 类型 | 说明 |
|---|---|---|
| index.html | 文件 | 26.0 KB |
源码与素材清单
| 文件 / 目录 | 类型 | 说明 |
|---|---|---|
| index.html | 文件 | 26.0 KB |
数据流转
Data Flow主链是预约到回收的八步闭环,开门与查询是两条独立短链,三条链共用账户与分配两份真相源 任何一步对外调用失败都如实返回调用方,不伪造成功,失败数据留在原地等重试或人工处理
接口与集成
API/首页
/login登录与鉴权
/logout退出清会话
/visitor访客预约页
/track进度查询页
/approve审批列表页
/visit// 访客通行凭证页
/reservation/done/预约成功页
/qr/二维码页
/pass/账户通行证页
/admin管理后台
/dev开发者模式
/api/reservation创建预约
/api/reservation/status进度查询
/api/my-reservations我的预约
/api/reservation/cancel自助取消
/api/approve/审批通过或拒绝
/api/approve/batch批量审批
/api/qr/二维码数据
/api/visitor-link/访客访问链接
/api/emp-pass账户通行证数据
/api/door-record刷卡记录查询
/api/face-record刷脸记录查询
/api/visitor-door-swipe/单条分配归因
/api/visitor-swipe-query按访客归因
/api/emp-access-record按账号归因
/api/search-visitor按姓名手机搜访客
/api/open-door单门远开
/api/open-all-doors批量远开任务
/api/open-all-task/远开进度
/api/sync-doors同步门禁缓存
/api/doors门禁列表
/api/door-visitor-visibility访客页门禁可见性
/api/face-devs-visibility访客页人脸可见性
/api/sync-face-devs同步人脸设备
/api/face-devs人脸设备列表
/api/face-authorize人脸授权
/api/create-emp创建门禁账户
/api/authorize-emp门禁授权
/api/unified-authorize门禁加人脸统一授权
/api/quit-emp人员离职
/api/emp-info人员信息查询
/api/emp-permissions/账户权限查询
/api/add-account账户池加号
/api/recycle/回收预约账户
/api/recycle-all一键全回收
/api/recycle-expired过期账户回收
/api/dev/batch-create批量造预约
/api/dev/batch-approve批量审批
/api/dev/task/开发任务进度
/api/dev/tasks开发任务列表
/api/dev/reservations批量单查询
/api/dev/revoke一键收回授权
/api/admin/create新建管理员
/api/admin/toggle/启停管理员
/api/admin/toggle-approve/审批权开关
/api/home-card首页卡片管理
/api/announcement公告读写
/api/site-settings站点设置读写
部署形态
Deployment服务端口固定 5102,公网地址已验证在线,本机回环同样返回正常
部署于管理服务器内网目录,整体搬迁只需复制目录并配好运行环境
运行方式为虚拟环境加启动脚本,不依赖系统全局包,不污染宿主
由 Leon-Control 统一托管,走重启接口换新进程,禁止手动杀进程
重启前必做语法检查,重启后必验首页与核心接口,写链路用隔离方式验证
代码仓库为 Gitea 上 TK-QR-Gate 仓库 main 分支,当前基线以提交号为准
每次优化先建干净基线再动手,基线不含运行数据,回滚只认提交号
门禁平台经公网映射双端口到达,无签名通道与签名通道各司其职
运行时数据全部落在数据目录,Git 明确排除,换机器不需要迁移数据库
静态资源随包发布,模板共 9 个,内网断外网照常可用
健康检查只看三样,首页可达、核心接口可调、缓存时间新鲜,三样缺一即告警
联系方式只留脱敏后的公开口径,原始号码与账号不进任何配置与文档
快照机制为每次内容变更自动建版本,元数据齐全,可按版本回滚后重新发布
日志页同时展示内容变更与部署记录,变更看提交信息,部署看版本环境说明
附件与图片走站内上传接口存放,不引用外部图床,断外网照常显示
部署验证只看源站四入口,不看代理缓存,缓存命中不算验证通过
回滚操作只认快照编号,不认时间描述,编号可在日志页点击复制
配图与视频位全部留显式占位,素材到位后按后台配置接入,不写死地址