← 返回总览 / 访客门禁管理系统 · TK-Visitor-Gate 🏢 展示 📖 说明书 🕘 日志 技术架构说明
📐 Architecture

访客门禁管理系统 · TK-Visitor-Gate

访客门禁管理系统官网 · 产品介绍与在线预约演示

📁 服务汇总 🌐 http://119.145.17.34:5102 🕑 更新于 2026-10-25
1

项目定位

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 一份结论。

点击查看全文 ⤢
2

技术架构

Architecture
01页面层
页面,鉴权
访客与员工双端页面

首页、访客预约、进度查询、审批列表、通行凭证、预约成功页、二维码页、账户通行证、管理后台、开发者模式共 12 页面,访客链路免登录、管理链路强制登录

点击查看全文 ⤢
02接口层
接口,路由
54 条业务接口

预约创建查询取消、审批与批量审批、二维码与访客链接、刷卡刷脸记录、三维归因查询、单门远开与批量远开、门禁与人脸同步、建号授权离职、账户池加号与三档回收、可见性配置、开发者批量能力、管理员管理

点击查看全文 ⤢
03设置蓝图
蓝图,拆分
独立注册的 Flask 蓝图

首页卡片增删改、公告读写、站点设置读写共 7 路由,从主应用拆出后路径保持不变

点击查看全文 ⤢
04业务核心
编排,审批
审批即编排

一次审批通过会依次执行账户确定、分时记账、门禁分时授权、人脸授权、新号入库、二维码获取、令牌生成、分配留痕八步,任一步失败即如实返回不继续

点击查看全文 ⤢
05C3 客户端
集成,重试
双通道加会话复用

无签名通道优先、签名通道回退,全局单例会话复用 TCP 连接,幂等 GET 查询配两次重试,签名按参数名排序拼密钥做摘要

点击查看全文 ⤢
06数据层
存储,原子
JSON 文件加原子写入

预约、账户、分配记录、二维码记录、门禁与人脸缓存、可见性配置、站点设置、公告、首页卡片、任务摘要共 11 类文件,写时先落临时文件再同步改名

点击查看全文 ⤢
07鉴权装饰器
鉴权,权限
路由层统一收口

登录装饰器管全部管理链路,超管装饰器管开发者模式与管理员管理,超管身份只认唯一的管理员账号

点击查看全文 ⤢
08后台任务
异步,任务
批量开门与批量审批异步化

任务字典存状态与逐步日志,完成后落盘任务摘要保留最近 50 条,进度接口轮询不阻塞请求

点击查看全文 ⤢
09韧性横向层
韧性,降级
超时重试降级三件套

对外请求统一超时,幂等查询重试两次,平台故障时预约照收审批照做、发码授权如实报错待恢复重发

点击查看全文 ⤢
3

模块组成

Modules
文件 / 目录类型说明
index.html 文件 26.0 KB
源码与素材清单
文件 / 目录类型说明
index.html 文件 26.0 KB
4

数据流转

Data Flow
开发者自测 → 批量造单 → 批量审批 → 一键收回授权 → 测试数据清零

主链是预约到回收的八步闭环,开门与查询是两条独立短链,三条链共用账户与分配两份真相源 任何一步对外调用失败都如实返回调用方,不伪造成功,失败数据留在原地等重试或人工处理

点击查看全文 ⤢
5

接口与集成

API
/
GET

首页

点击查看全文 ⤢
/login
GET/POST

登录与鉴权

点击查看全文 ⤢
/logout
GET

退出清会话

点击查看全文 ⤢
/visitor
GET

访客预约页

点击查看全文 ⤢
/track
GET/POST

进度查询页

点击查看全文 ⤢
/approve
GET

审批列表页

点击查看全文 ⤢
/visit//
GET

访客通行凭证页

点击查看全文 ⤢
/reservation/done/
GET

预约成功页

点击查看全文 ⤢
/qr/
GET

二维码页

点击查看全文 ⤢
/pass/
GET

账户通行证页

点击查看全文 ⤢
/admin
GET

管理后台

点击查看全文 ⤢
/dev
GET

开发者模式

点击查看全文 ⤢
/api/reservation
POST

创建预约

点击查看全文 ⤢
/api/reservation/status
POST

进度查询

点击查看全文 ⤢
/api/my-reservations
POST

我的预约

点击查看全文 ⤢
/api/reservation/cancel
POST

自助取消

点击查看全文 ⤢
/api/approve/
POST

审批通过或拒绝

点击查看全文 ⤢
/api/approve/batch
POST

批量审批

点击查看全文 ⤢
/api/qr/
GET

二维码数据

点击查看全文 ⤢
/api/visitor-link/
GET

访客访问链接

点击查看全文 ⤢
/api/emp-pass
GET

账户通行证数据

点击查看全文 ⤢
/api/door-record
GET

刷卡记录查询

点击查看全文 ⤢
/api/face-record
GET

刷脸记录查询

点击查看全文 ⤢
/api/visitor-door-swipe/
GET

单条分配归因

点击查看全文 ⤢
/api/visitor-swipe-query
GET

按访客归因

点击查看全文 ⤢
/api/emp-access-record
GET

按账号归因

点击查看全文 ⤢
/api/search-visitor
GET

按姓名手机搜访客

点击查看全文 ⤢
/api/open-door
POST

单门远开

点击查看全文 ⤢
/api/open-all-doors
POST

批量远开任务

点击查看全文 ⤢
/api/open-all-task/
GET

远开进度

点击查看全文 ⤢
/api/sync-doors
GET

同步门禁缓存

点击查看全文 ⤢
/api/doors
GET

门禁列表

点击查看全文 ⤢
/api/door-visitor-visibility
GET/POST

访客页门禁可见性

点击查看全文 ⤢
/api/face-devs-visibility
GET/POST

访客页人脸可见性

点击查看全文 ⤢
/api/sync-face-devs
POST

同步人脸设备

点击查看全文 ⤢
/api/face-devs
GET

人脸设备列表

点击查看全文 ⤢
/api/face-authorize
POST

人脸授权

点击查看全文 ⤢
/api/create-emp
POST

创建门禁账户

点击查看全文 ⤢
/api/authorize-emp
POST

门禁授权

点击查看全文 ⤢
/api/unified-authorize
POST

门禁加人脸统一授权

点击查看全文 ⤢
/api/quit-emp
POST

人员离职

点击查看全文 ⤢
/api/emp-info
GET

人员信息查询

点击查看全文 ⤢
/api/emp-permissions/
GET

账户权限查询

点击查看全文 ⤢
/api/add-account
POST

账户池加号

点击查看全文 ⤢
/api/recycle/
POST

回收预约账户

点击查看全文 ⤢
/api/recycle-all
POST

一键全回收

点击查看全文 ⤢
/api/recycle-expired
POST

过期账户回收

点击查看全文 ⤢
/api/dev/batch-create
POST

批量造预约

点击查看全文 ⤢
/api/dev/batch-approve
POST

批量审批

点击查看全文 ⤢
/api/dev/task/
GET

开发任务进度

点击查看全文 ⤢
/api/dev/tasks
GET

开发任务列表

点击查看全文 ⤢
/api/dev/reservations
GET

批量单查询

点击查看全文 ⤢
/api/dev/revoke
POST

一键收回授权

点击查看全文 ⤢
/api/admin/create
POST

新建管理员

点击查看全文 ⤢
/api/admin/toggle/
POST

启停管理员

点击查看全文 ⤢
/api/admin/toggle-approve/
POST

审批权开关

点击查看全文 ⤢
/api/home-card
POST/PUT/DELETE

首页卡片管理

点击查看全文 ⤢
/api/announcement
GET/POST

公告读写

点击查看全文 ⤢
/api/site-settings
GET/POST

站点设置读写

点击查看全文 ⤢
6

部署形态

Deployment
服务端口固定 5102,公网地址已验证在线,本机回环同样返回正常

服务端口固定 5102,公网地址已验证在线,本机回环同样返回正常

点击查看全文 ⤢
部署于管理服务器内网目录,整体搬迁只需复制目录并配好运行环境

部署于管理服务器内网目录,整体搬迁只需复制目录并配好运行环境

点击查看全文 ⤢
运行方式为虚拟环境加启动脚本,不依赖系统全局包,不污染宿主

运行方式为虚拟环境加启动脚本,不依赖系统全局包,不污染宿主

点击查看全文 ⤢
由 Leon-Control 统一托管,走重启接口换新进程,禁止手动杀进程

由 Leon-Control 统一托管,走重启接口换新进程,禁止手动杀进程

点击查看全文 ⤢
重启前必做语法检查,重启后必验首页与核心接口,写链路用隔离方式验证

重启前必做语法检查,重启后必验首页与核心接口,写链路用隔离方式验证

点击查看全文 ⤢
代码仓库为 Gitea 上 TK-QR-Gate 仓库 main 分支,当前基线以提交号为准

代码仓库为 Gitea 上 TK-QR-Gate 仓库 main 分支,当前基线以提交号为准

点击查看全文 ⤢
每次优化先建干净基线再动手,基线不含运行数据,回滚只认提交号

每次优化先建干净基线再动手,基线不含运行数据,回滚只认提交号

点击查看全文 ⤢
门禁平台经公网映射双端口到达,无签名通道与签名通道各司其职

门禁平台经公网映射双端口到达,无签名通道与签名通道各司其职

点击查看全文 ⤢
运行时数据全部落在数据目录,Git 明确排除,换机器不需要迁移数据库

运行时数据全部落在数据目录,Git 明确排除,换机器不需要迁移数据库

点击查看全文 ⤢
静态资源随包发布,模板共 9 个,内网断外网照常可用

静态资源随包发布,模板共 9 个,内网断外网照常可用

点击查看全文 ⤢
健康检查只看三样,首页可达、核心接口可调、缓存时间新鲜,三样缺一即告警

健康检查只看三样,首页可达、核心接口可调、缓存时间新鲜,三样缺一即告警

点击查看全文 ⤢
联系方式只留脱敏后的公开口径,原始号码与账号不进任何配置与文档

联系方式只留脱敏后的公开口径,原始号码与账号不进任何配置与文档

点击查看全文 ⤢
快照机制为每次内容变更自动建版本,元数据齐全,可按版本回滚后重新发布

快照机制为每次内容变更自动建版本,元数据齐全,可按版本回滚后重新发布

点击查看全文 ⤢
日志页同时展示内容变更与部署记录,变更看提交信息,部署看版本环境说明

日志页同时展示内容变更与部署记录,变更看提交信息,部署看版本环境说明

点击查看全文 ⤢
附件与图片走站内上传接口存放,不引用外部图床,断外网照常显示

附件与图片走站内上传接口存放,不引用外部图床,断外网照常显示

点击查看全文 ⤢
部署验证只看源站四入口,不看代理缓存,缓存命中不算验证通过

部署验证只看源站四入口,不看代理缓存,缓存命中不算验证通过

点击查看全文 ⤢
回滚操作只认快照编号,不认时间描述,编号可在日志页点击复制

回滚操作只认快照编号,不认时间描述,编号可在日志页点击复制

点击查看全文 ⤢
配图与视频位全部留显式占位,素材到位后按后台配置接入,不写死地址

配图与视频位全部留显式占位,素材到位后按后台配置接入,不写死地址

点击查看全文 ⤢
© 2026 Leyon WorkStation · 访客门禁管理系统 · TK-Visitor-Gate 🏢 展示 📖 说明书 🕘 日志 ← 返回项目总览