K1989CMS：一套自研的企业一体化管理系统

从门禁通行到食堂就餐，从访客预约到资产盘点，再到 AI 对话式管理

企业数字化建设，往往逃不开一套又一套的孤岛系统：门禁一套、食堂一套、访客登记一套、资产管理再买一套，数据各管各的，账号互不相通，管理员每天在几个后台之间来回切换。

这篇文章要介绍的 K1989CMS，就是针对这个痛点从零打磨的一套企业一体化管理系统：私有化部署、统一后台 + 移动端，把一家公司/园区日常运营中最常见的事务——门禁、就餐、人事、访客、资产、第三方平台集成——全部收敛到一个平台上。

一、它是什么：面向中小园区/楼宇的数字化运营平台

K1989CMS 定位为面向中小园区/楼宇的一体化数字化运营平台，可私有化部署到自己的服务器，覆盖六条业务线：

• 门禁通行：员工建档自动下发人脸至门禁平台，访客授权，离职/停用自动撤权，设备权限全局或按人下发。
• 就餐消费：本地与平台两种消费模式，员工钱包、充值、统一交易流水与报表。
• 人事组织：部门/员工管理，与钉钉/企微/飞书通讯录同步，员工状态流转联动门禁。
• 访客管理：预约、审批流、到访登记、人脸照片上传授权、移动端访客中心，访客可扫码自助签到。
• 资产管理：资产台账、出入库、维修保养计划、告警与统计报表，还内置了部署在资产主机上的巡检 Agent 与 EDR 端点安全。
• 第三方平台集成：通过"适配器"统一对接海康（门禁/消费平台）、钉钉、企业微信、飞书、阿里云/腾讯云短信，不直接绑定任何一家厂商。

此外还附带统一通知（站内/短信/邮件/IM 多渠道）、审批流、操作审计日志、等保测评材料包等能力。系统有五个入口：管理端、员工端（PC）、移动端（H5）、访客自助端（免登录）和门户页，一套账号体系贯通。

二、访客管理：预约到离场的一条龙

以访客业务为例，看看这套系统把一件事做得多完整：员工发起预约 → 部门主管/管理员审批 → 审批通过后自动向门禁平台下发通行权限 → 访客到前台扫码签到 → 系统记录通行日志 → 超时自动签退并回收凭证。整个生命周期由定时任务托管：预约提前 30 分钟提醒、白名单到期处理、超时访客自动过期并回收门禁、90 天前的旧记录自动清理，还有每 15 分钟一次的"门禁下发补偿重试"，防止下发失败漏掉。

访客侧也不用下载任何 App：前台/保安室张贴签到二维码，访客扫码即可自助确认到访；访客中心支持预约查询、二维码通行和通行记录查看。

三、技术架构：老牌稳定栈，但把工程细节做足了

技术选型没有追逐新潮，而是用了成熟稳定的组合：Python 3.12 + Flask 2.3 + SQLAlchemy 2.0（MySQL 8）+ Celery 5.3（Redis 7），前端为 Jinja2 服务端渲染 + Bootstrap 5 + Chart.js，移动端独立响应式模板。整体是经典的四层架构：表现层 → 路由层 → 服务层 → 数据层，路由禁止直连数据库，设备与外部平台操作统一走适配器。

工程细节上有几个值得说的点：

• Celery 任务体系 17 个定时任务，按访客/同步/EDR/报表/备份等分队列运行，独立队列隔离避免互相饿死；任务"软超时 540s + 硬超时 600s"，Worker 崩溃自动重回队列，Redis 分布式锁防重复执行。
• 适配器模式对接外部平台：海康、钉钉、企微、飞书、短信都继承同一个 BaseAdapter 接口，配置凭证即可切换启用，新增厂商只需注册一个适配器类。
• 多端业务闭环：管理端做治理、员工端做自助、移动端做随手办、访客端做自助、工作台免登（钉钉/企微/飞书内置浏览器打开即登录）。
• API 通道体系：对外 REST API v2、后台 AJAX、平台回调、Agent 通道、MCP webhook 分前缀隔离，附 Swagger 接口文档。

四、安全与合规：不是嘴上说说，是真做了等保材料包

企业系统最怕的是"裸奔"。K1989CMS 在安全上投入不小，并配套了等保二级/三级测评材料包（依据 GB/T 22239-2019 编制），包含审计日志需求规范、数据分类分级清单、访问控制矩阵、应急预案和自查报告框架：

• 认证与授权：密码 PBKDF2-SHA256 加盐存储，支持 TOTP 双因素认证，JWT 带 jti 黑名单（登出即失效），登录限流（fail-closed + 渐进延迟 + 锁定），RBAC 位掩码 + 行级数据权限（普通员工只能看自己，部门主管只能看本部门）。
• 数据保护：身份证、手机号等 PII 用 Fernet 字段级加密存储，列表/导出统一脱敏，备份文件加密，审计日志独立事务写入（主业务回滚也不影响审计落库）。
• Web 安全专项治理：XSS 输出编码、CSP（nonce + 报告收集）、CSRF 默认开启、越权审计——历轮安全审计把崩溃问题从 28 个修到 0，越权 0 复现。
• EDR 端点安全：这是比较特别的一块——系统自带部署在资产主机上的 Agent（Python/Go 双端），做进程/文件/网络基线比对、IOC 哈希比对、持久化项监控（计划任务/服务/Run 键）、勒索诱饵文件检测、登录失败快检；接 abuse.ch ThreatFox 威胁情报自动更新；管理员在告警中心可一键"终止进程/隔离文件"远程处置，服务端 + Agent 双重路径校验，全程审计。

五、AI 能力：内置 MCP，让 AI 帮你查数据、做审批

K1989CMS 内置了 MCP Server（模型上下文协议），把系统能力封装成 9 个业务工具：查询类 6 个（搜索员工/资产、查访客、查消费记录、查通知、仪表盘统计），写操作类 3 个（审批访客预约、资产报修、订单状态变更）。这意味着市面上的 AI 客户端（Cursor、Claude Desktop、豆包工作等）可以直接"连"进这套系统：

• 三种传输方式：stdio（编辑器本地直连）、Streamable HTTP（端口 8765，局域网可达）、SSE（端口 8766），Python 3.12 + 官方 mcp SDK 实测握手与工具调用全部通过。
• 多用户与权限继承：HTTP/SSE 通过请求头 X-MCP-User-Id 指定身份，AI 只是"某个真实用户的代理"，权限完全按该用户的 RBAC + 行级数据权限执行，不存在"机器人管理员"这种越权身份。
• 写操作二次确认：AI 请求审批/报修等写操作时，先返回"待确认 + token"，必须由原发起人回复"确认 token"才真正执行；token 一次性、300 秒有效，非原发起人确认直接拒绝。
• LLM 网关：兼容 OpenAI 协议，已实测接入 DeepSeek 调通；未配置网关时自动回退内置路由，不阻塞。

六、测试与质量：68 个测试文件、约 1079 个用例

项目测试套件目前有 68 个测试文件、约 1079 个测试用例（参数化后实际更多），用内存 SQLite 做到用例级隔离，覆盖消费双模式、门禁人脸同步、钱包交易、资产报表、集成适配器、安全专项（XSS/CSP/越权/CSRF）、TOTP 等。此前还做过一轮全接口健康扫描：828 条规则 × 6 种角色 × 4051 次请求冒烟，修复 48 处问题，崩溃从 28 降到 0，越权 0，两次回归全部通过。

这些验证脚本都沉淀在项目的 tools 目录里，可以随时复跑。

七、部署与运维：本地开发、Windows 服务化、Docker 三套方案

部署上给了清晰的梯子：

• 本地开发：Windows 一条命令 setup.ps1 完成环境检查→依赖→配置→建库→启动；Linux/macOS 用 setup.sh。
• Windows 生产主线：用 NSSM 把 Web（waitress）/ Celery Worker / Celery Beat 注册为三个系统服务，开机自启、崩溃自动拉起、日志轮转、依赖排序，配一个每日凌晨 4 点的 Worker 重启计划任务做内存回收。
• Docker Compose 备选：db / redis / app / celery_worker / celery_beat / nginx 六个服务一条命令拉起，适合 Linux 服务器。
• 代码托管：项目托管在 Gitee（gitee.com/thomasblog/k1989cmsv2），由原项目 gitee.com/thomasblog/k1989cms 优化演进而来——累计 1094 个文件变更（净增约 6.7 万行、净删约 19.2 万行），移除本地绑定的厂商 SDK，全面转向适配器模式，并新增了 MCP、EDR、消费业务闭环等核心能力。本地开发环境与远程仓库保持同步，日常通过 git 工作流维护。

八、快速开始

想自己跑起来，三分钟就能上手（Windows 示例）：

git clone https://gitee.com/thomasblog/k1989cmsv2.git
cd k1989cmsv2
.\setup.ps1                # 一键初始化并启动
# 浏览器打开 http://127.0.0.1:8888 即可登录

生产部署（Windows 服务化）完整步骤、密钥安全红线、故障排查手册见项目 docs 目录的部署文档；系统还附带技术架构、业务模块、安全等保、测试、MCP 说明共 6 篇文档加文档中心索引，基本做到了"文档跟着代码走"。

九、写在最后

K1989CMS 不是那种"为了演示而存在的项目"——它经历了多轮安全审计、接口健康扫描和回归验证，测试用例近 1100 个，文档、测试、安全材料齐备，是可以真正拿到内网里跑起来的形态。无论你是在给公司/园区选型一套一体化管理系统，还是想找一个安全实践扎实的开源项目来研究，它都值得一看。

项目地址：https://gitee.com/thomasblog/k1989cmsv2