# k1989cms
**Repository Path**: thomasblog/k1989cms
## Basic Information
- **Project Name**: k1989cms
- **Description**: Smart Office & IoT Platform 是一套集成了企业内部管理、物联网设备控制、人员组织管理于一体的综合性智能办公平台。系统采用模块化单体架构，通过统一身份认证实现"一套账号，通行所有业务与硬件"的目标，构建企业级数字底座。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-01-06
- **Last Updated**: 2026-07-29
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# K1989CMS 智能办公平台
[](https://gitee.com/thomasblog/k1989cms)
[](https://gitee.com/thomasblog/k1989cms/stargazers)
[](https://gitee.com/thomasblog/k1989cms/members)
让企业管理更智能、更高效！
---
## 📖 项目简介
K1989CMS 是一个基于 **Flask** 构建的企业级智能办公平台管理系统。它采用模块化设计，集成了资产管理、设备监控（IoT）、消费系统、访客管理、组织架构等核心业务模块，并提供强大的第三方系统集成能力，为企业提供一站式数字化管理解决方案。
本系统支持高性能的设备通信（TCP/UDP/WebSocket），并内置了完善的后台任务处理机制和监控告警功能。
### ✨ 核心特性
- 🏢 **全生命周期资产管理** - 覆盖采购、入库、领用、调拨、维修、报废全流程
- 📡 **多协议设备通信** - 支持 TCP/UDP/WebSocket，海量设备接入
- 🍽️ **智能消费系统** - 多餐厅/窗口管理、菜品菜单、订单支付、账户补贴
- 👤 **访客预约管理** - 在线预约、员工审批、白名单管理、签到记录
- 👥 **组织架构管理** - 树形结构、员工管理、权限控制（RBAC）
- 📊 **第三方平台集成** - 企业微信、钉钉、飞书等平台数据同步
- 🔐 **多层次安全防护** - JWT认证、API Key、数据加密、IP白名单
- 📈 **实时监控告警** - Prometheus监控、设备状态监控、系统性能监控
### 🏗️ 架构亮点
- **七层路由分层注册** - 88 个蓝图按 external_api/internal_api/internal_service/agent/admin/user/visitor 七层隔离注册，确保不同认证体系（HMAC/JWT/Session/设备签名）互不干扰
- **BaseService 统一基类** - 79 个服务类继承 BaseService，获得通用 CRUD、分页查询、事务管理、统一响应能力，子类只需定义 `_model` 类属性
- **多协议设备通信** - 12 个通信模块统一管理 TCP/UDP/WebSocket/HTTP 四协议，自适应心跳（连续成功增间隔/连续失败降间隔）、指数退避重连、4 级优先级消息广播
- **Python+Go 双版本 Agent** - Go 版为生产主力，蓝绿部署自动升级 + 三阶段回滚，心跳与命令解耦（3 秒命令轮询独立通道），跨平台 EDR 安全检测
- **启动期安全校验** - 8 项安全检查（密钥长度/唯一性/弱密钥/Redis 密码/Debug 模式），生产环境严格模式不通过则拒绝启动
- **延迟加载优化** - 扩展延迟加载 + SocketIO 代理 + 蓝图动态导入，避免 3-4s 冷启动开销
- **Celery 上下文自适应** - AutoContextTask 确保 Worker 子进程自动创建 Flask 上下文，分布式锁防多 Worker 重复执行
---
## 🚀 快速开始
### 环境要求
- **Python**: 3.8+
- **Redis**: 6.0+
- **MySQL**: 8.0+（需使用 InnoDB 引擎以支持外键约束）
- **操作系统**: **Windows**（生产环境必须）
- 项目依赖 ZK `zkemkeeper` COM 组件（门禁/考勤设备 SDK）和 `VideoSDK_Win64` DLL（视频监控）
- 见 [app/services/zk_sdk_native.py](./app/services/zk_sdk_native.py) 和 [app/VideoSDK_Win64/](./app/VideoSDK_Win64/)
- Linux/macOS 仅可用于"纯业务层 + 设备 TCP 通信降级模式"，不支持 COM SDK 完整功能
### 安装步骤
1. **克隆项目**
```bash
git clone https://gitee.com/thomasblog/k1989cms.git
cd k1989cms
```
2. **创建虚拟环境**
```bash
python -m venv venv
source venv/bin/activate # Linux/Mac
# 或
.\venv\Scripts\activate # Windows
```
3. **安装依赖**
```bash
pip install -r requirements.txt
```
4. **配置环境变量**
```bash
cp .env.example .env
# 编辑 .env 文件，配置数据库连接、Redis 密钥等
```
5. **初始化数据库**
```bash
# 方式一：使用 Flask CLI（推荐）
flask init
# 方式二：使用 main.py（会自动检查并初始化）
python main.py
```
6. **启动服务**
```bash
# 方式一：使用 main.py（开发推荐，支持自动数据库初始化）
python main.py
# 方式二：使用 Flask CLI 开发模式
flask run
# 方式三：使用 Flask CLI 生产模式
flask runserver
# 方式四：生产环境 - Windows（waitress，本项目主用）
waitress-serve --listen=0.0.0.0:5000 --threads=8 wsgi:application
# 方式五：生产环境 - Linux 备用（gunicorn，仅业务层不含 ZK COM SDK 时）
gunicorn -w 4 -b 0.0.0.0:5000 --timeout 120 wsgi:application
```
**启动方式说明**：
- `python main.py`：开发推荐，会自动检查数据库连接，如果表结构不存在会自动初始化
- `flask run`：标准的 Flask 开发服务器
- `flask runserver`：生产模式服务器，启用多线程
- `waitress-serve`：**Windows 生产环境推荐**，纯 Python WSGI 服务器，跨平台支持
- `gunicorn`：Linux 生产环境，本项目因依赖 ZK COM DLL 仅作为业务层备用方案
### 访问系统
- **Web 界面**: http://localhost:5000
- **管理后台**: http://localhost:5000/admin
- **用户中心**: http://localhost:5000/users
- **API 文档**: 查看路由文件获取接口信息
## 命令行工具
项目提供了丰富的命令行工具，用于管理应用、数据库和系统配置。
### 数据库管理命令
```bash
# 初始化数据库（创建表结构和默认数据）
flask init
# 重置数据库（危险操作，会删除所有数据）
flask reset
# 完整数据库设置（创建数据库、表结构、默认数据）
flask full_setup
```
### 应用运行命令
```bash
# 运行开发服务器
flask run
# 运行生产服务器（启用多线程）
flask runserver
# 直接使用 main.py 启动（推荐，支持自动初始化）
python main.py
```
### 其他命令
```bash
# 检查数据一致性
flask check_consistency
```
**命令说明**：
- `flask init`：初始化数据库表结构和默认数据（角色、管理员用户）
- `flask reset`：重置数据库，删除所有数据并重新初始化（需要确认）
- `flask full_setup`：完整的数据库设置流程，包括创建数据库、表结构、默认数据
- `flask check_consistency`：检查用户和员工数据的一致性
- `python main.py`：启动应用，会自动检查数据库连接和表结构，如果需要会自动初始化
**自动初始化功能**：
使用 `python main.py` 启动应用时，系统会自动执行以下检查：
1. 检查数据库连接是否正常
2. 检查数据库表结构是否存在
3. 如果表结构不存在，自动执行完整的数据库初始化
4. 初始化成功后，管理员密码会记录在 `docs/admin_account_info.md` 文件中
---
## 📁 项目结构
```
k1989cms/
├── agents/ # Agent 客户端（部署在被管理设备上）
│ ├── asset_management_agent.py # Python 版资产管理 Agent
│ ├── data_sync_agent.py # 数据同步 Agent
│ ├── device_monitor_agent.py # 设备状态监控 Agent
│ ├── device_sdk.py # 设备端 SDK
│ ├── edr_engine.py # EDR 安全检测引擎
│ └── asset_agent_go/ # Go 版 Agent（生产主力，含自动升级/EDR）
├── app/
│ ├── __init__.py # 应用工厂（create_app）
│ ├── celery_app.py # Celery 配置
│ ├── extensions.py # Flask 扩展初始化
│ ├── communication/ # 设备通信模块（TCP/UDP/WS/HTTP，12 个模块）
│ ├── config/ # 缓存配置
│ ├── constants/ # 权限常量
│ ├── models/ # 数据模型层（40+ 模型）
│ ├── routes/ # 路由层（七层分层注册，60+ 蓝图）
│ │ ├── admin/ # 管理员后台路由（30+ 蓝图）
│ │ ├── api/ # RESTful API 路由（v1/v2）
│ │ ├── auth/ # 认证路由
│ │ ├── user/ # 用户端路由
│ │ ├── visitor/ # 访客路由
│ │ ├── agent/ # Agent 通信路由
│ │ └── ...
│ ├── services/ # 业务逻辑层（79 个服务类）
│ ├── tasks/ # Celery 异步任务（20+ 定时任务）
│ ├── utils/ # 工具类（42 个模块）
│ └── views/ # 首页视图
├── config/ # 配置文件（多环境/安全校验）
├── docs/ # 项目文档（8 个分类）
├── static/ # 静态资源（CSS/JS/图片/二维码）
├── templates/ # Jinja2 模板（admin/user/visitor/auth）
├── tests/ # 测试代码（40+ 测试文件 + e2e）
├── scripts/ # 运维与检查脚本
├── utils/ # 根级工具脚本
├── main.py # 应用入口（Celery 进程管理）
├── wsgi.py # 生产环境 WSGI 入口（gunicorn 部署）
├── requirements.txt # Python 依赖
└── README.md # 项目说明
```
---
## 🛠️ 技术栈
### 后端技术
| 技术 | 版本 | 说明 |
|------|------|------|
| **Python** | 3.8+ | 后端开发语言 |
| **Flask** | 2.3.3 | Web 框架（应用工厂模式） |
| **SQLAlchemy** | 2.0.23 | ORM 数据库访问 |
| **MySQL** | 8.0+ | 关系型数据库（InnoDB 引擎） |
| **Redis** | 6.0+ | 缓存、消息队列、Celery Broker |
| **Celery** | 5.3.4 | 异步任务调度（20+ 定时任务） |
| **Gunicorn** | 21.2.0 | WSGI 服务器 |
| **Flask-JWT-Extended** | 4.5.3 | JWT 认证（access 1h / refresh 7d） |
| **Flask-SocketIO** | 5.3.6 | WebSocket 实时通信 |
| **Flask-SQLAlchemy** | 3.0.5 | SQLAlchemy 集成 |
| **Alembic** | 1.12.1 | 数据库迁移 |
| **cryptography** | 46.0.3 | Fernet 数据加密 |
| **Prometheus Client** | 0.19.0 | 性能指标采集 |
| **Sentry SDK** | 1.40.6 | 错误监控 |
### 设备通信技术
| 技术 | 端口 | 说明 |
|------|------|------|
| **TCP** | 5000 | 长连接，JSON 消息格式 |
| **UDP** | 5001 | 无连接，JSON 消息格式 |
| **WebSocket** | 5000 | Flask-SocketIO，JWT 强制认证 |
| **HTTP** | /api/devices/ | RESTful，设备主动拉取命令 |
| **MQTT** | - | QoS/Retain 支持 |
| **SNMP** | - | 网络设备监控 |
| **Modbus** | - | 工业设备通信 |
| **GB28181** | - | 视频监控协议 |
### Agent 技术
| 技术 | 说明 |
|------|------|
| **Go Agent** | 生产主力，蓝绿部署自动升级，心跳与命令解耦（3 秒命令轮询） |
| **Python Agent** | PyInstaller 打包，EDR 动态加载 |
| **EDR 引擎** | 跨平台安全检测（Windows/Linux/macOS） |
### 前端技术
| 技术 | 版本 | 说明 |
|------|------|------|
| **Bootstrap** | 5.3+ | UI 框架 |
| **jQuery** | 3.6+ | JavaScript 库 |
| **DataTables** | - | 表格组件 |
| **Chart.js** | - | 图表组件 |
| **SweetAlert2** | - | 弹窗组件 |
---
## 📡 API 文档
### 认证方式
系统使用 **JWT (JSON Web Token)** 进行身份认证。
请求需在 Header 中携带 Token：
```http
Authorization: Bearer
```
### 常用接口
| 模块 | 接口路径 | 方法 | 说明 |
|------|----------|------|------|
| **认证** | `/auth/login` | POST | 用户登录 |
| **资产** | `/api/v1/assets` | GET | 获取资产列表 |
| **设备** | `/admin/devices/api/` (管理后台) / `/api/v1/devices` (外部只读) | GET | 设备管理（管理后台API）和设备列表查询（外部只读API） |
| **用户** | `/api/v1/users` | GET | 获取用户列表 |
| **组织** | `/api/v1/departments/tree` | GET | 获取部门树 |
### WebSocket 连接
设备可通过 WebSocket 连接到服务器进行实时通信：
```javascript
// 设备端连接示例
const ws = new WebSocket('ws://localhost:5000/ws');
// 订阅设备特定消息
ws.send(JSON.stringify({
action: 'subscribe',
room: 'device_001'
}));
```
---
## 📊 核心功能模块
### 🏢 资产管理
- **硬件资产管理**：资产增删改查、生命周期管理、二维码管理
- **软件资产管理**：许可证管理、安装记录、使用统计
- **资产监控**：状态监控、告警管理、使用统计
- **资产维护**：维护计划、维护记录、维护提醒
- **资产转移**：转移申请、转移审批、转移记录
### 📡 设备管理
- **设备注册与配置**：设备注册、配置编辑、配置下发
- **设备监控与告警**：实时监控、历史数据、告警列表
- **设备控制**：远程控制、指令下发、状态查询
- **设备认证**：设备认证、权限管理、访问控制
### 👤 访客管理
- **访客预约**：在线预约、预约审批、预约记录
- **访客邀请**：访客邀请、邀请管理、邀请记录
- **访客通行**：通行记录、通行统计、通行报表
- **访客通知**：通知发送、通知记录、通知统计
- **白名单管理**：白名单创建、白名单编辑、白名单删除
### 🍽️ 消费管理
- **消费记录**：消费查询、消费统计、消费报表
- **消费账户**：账户余额、账户充值、账户明细
- **消费补贴**：补贴规则、补贴发放、补贴统计
- **消费支付**：支付方式、支付记录、支付统计
- **餐厅管理**：餐厅管理、窗口管理、菜品管理
### 👥 组织架构
- **部门管理**：部门树、部门编辑、部门删除
- **员工管理**：员工列表、员工详情、批量导入导出
- **多源同步**：同步配置、同步日志、同步状态
### 🔐 系统管理
- **用户管理**：用户列表、用户详情、用户编辑
- **角色管理**：角色列表、角色详情、权限分配
- **权限管理**：权限树、权限配置、权限测试
- **系统配置**：基本设置、安全设置、通知设置
- **操作日志**：日志查询、日志详情、日志导出
- **系统监控**：监控仪表板、性能图表、告警管理
- **数据备份**：备份列表、备份恢复、备份策略
### 📊 平台集成
- **第三方平台集成**：企业微信、钉钉、飞书等平台集成
- **组织架构同步**：部门同步、员工同步、通讯录同步
- **消息推送**：消息模板、消息发送、消息统计
- **单点登录**：OAuth 2.0、JWT令牌、会话管理
### 🤖 Agent 管理
- **Agent 配置**：配置模板、配置管理、配置下发
- **Agent 生成**：安装包生成、生成记录、下载管理
- **Agent 监控**：状态监控、日志查看、性能监控
**Agent 功能说明**：
- 支持多种设备类型的 Agent 部署
- 提供配置模板管理，支持批量配置下发
- 支持设备状态实时监控和日志收集
- 提供 Agent 安装包自动生成功能
### 📱 二维码服务
- **二维码生成**：访客二维码、资产二维码、设备二维码
- **二维码管理**：二维码列表、状态管理、有效期管理
- **二维码验证**：二维码扫描、二维码验证、验证记录
### 🔌 API 集成管理
- **API 密钥管理**：密钥生成、密钥管理、密钥权限
- **API 访问控制**：IP 白名单、访问频率、访问日志
- **API 文档**：接口文档、接口测试、接口版本
- **API 监控统计**：调用统计、错误统计、性能统计
### 📈 报表分析
- **报表生成**：报表模板、报表生成、报表导出
- **报表调度**：定时任务、调度管理、执行记录
- **报表分发**：分发配置、分发记录、分发统计
- **数据可视化**：图表展示、数据钻取、数据对比
### 📡 设备通信（IoT）
- **多协议支持**：TCP/UDP/WebSocket/HTTP
- **设备认证**：设备注册、认证、权限管理
- **心跳检测**：设备在线状态监控
- **消息广播**：支持向设备群发消息
- **重连机制**：自动重连和连接管理
### 🔐 安全防护
- **JWT 认证**：基于 Token 的身份认证
- **API Key 管理**：第三方应用访问控制
- **数据加密**：敏感数据加密存储
- **IP 白名单**：访问 IP 限制
- **操作日志**：完整的操作审计日志
### 📊 系统监控
- **Prometheus 监控**：性能指标采集
- **设备监控**：设备状态监控和告警
- **系统性能监控**：CPU、内存、磁盘监控
- **告警管理**：告警规则配置和通知
---
## 👤 用户端功能
用户端提供普通员工使用的功能模块，包括：
### 导航菜单
| 菜单项 | 路径 | 功能说明 |
|--------|------|----------|
| 首页 | `/users/` | 用户仪表盘，显示概览信息 |
| 资产管理 | `/assets/` | 查看个人资产、申请资产 |
| 盘点管理 | `/inventory/` | 盘点任务、盘点历史 |
| 消费管理 | `/consumption/` | 消费记录、钱包充值 |
| 访客管理 | `/visitors/` | 创建访客邀请、查看邀请记录 |
| 设备管理 | `/devices/` | 设备申请、设备监控 |
| 门禁记录 | `/user/access/records` | 查看个人通行记录 |
| 报表统计 | `/statistics/` | 数据统计报表 |
| 二维码扫描 | `/qrcode/scan` | 扫描二维码功能 |
---
## 🔧 配置说明
### 环境变量配置
项目使用 `.env` 文件管理环境变量，从 `.env.example` 复制并修改：
```bash
cp .env.example .env
```
主要配置项包括：
```bash
# 应用配置
FLASK_ENV=development # 运行环境：development/production
SECRET_KEY=your-secret-key-here # 应用密钥（必须配置，64位十六进制字符串）
DEBUG=True # 调试模式
# 数据库配置
DATABASE_URL=mysql+pymysql://USER:PASSWORD@HOST:PORT/DBNAME
# Redis 配置
REDIS_URL=redis://:password@localhost:6379/0 # Redis 连接地址（生产环境必须配置密码）
# JWT 配置
JWT_SECRET_KEY=your-jwt-secret # JWT 密钥（必须配置，64位十六进制字符串）
# 数据加密密钥
ENCRYPTION_KEY=your-encryption-key # 数据加密密钥（必须配置，44位Base64字符串，用于敏感数据加密）
```
### ⚠️ 数据库配置注意事项
#### MySQL 存储引擎配置（重要）
**问题说明**：
- 系统使用 SQLAlchemy 定义了大量的外键约束来保证数据完整性
- MySQL 的 `MyISAM` 存储引擎**不支持外键约束，建议使用InnoDB引擎**
**检查当前配置**：
```bash
mysql -u root -p -e "SHOW VARIABLES LIKE 'default_storage_engine';"
```
**预期结果**：
```
+------------------------+--------+
| Variable_name | Value |
+------------------------+--------+
| default_storage_engine | InnoDB |
+------------------------+--------+
```
---
## 📊 监控与日志
### Prometheus 监控
系统内置 Prometheus 监控端点，用于采集性能指标：
```bash
curl http://localhost:5000/prometheus/metrics
```
### 日志配置
系统日志默认保存在 `logs/app.log`，支持按日期切割。
---
## 🔐 安全建议
1. **环境变量**：生产环境务必修改 `SECRET_KEY`、`JWT_SECRET_KEY`、`ENCRYPTION_KEY` 和数据库密码
2. **密钥强制配置**：`SECRET_KEY`、`JWT_SECRET_KEY`、`ENCRYPTION_KEY` 必须在 `.env` 文件中配置，未配置将拒绝启动
3. **HTTPS**：启用 HTTPS 加密传输，防止数据泄露
4. **访问控制**：配置 Redis 访问密码，并使用防火墙限制 IP 访问
5. **API 限制**：在 Nginx 或 IIS 或代码层配置请求频率限制 (Rate Limiting)
6. **生产部署（Windows）**：使用 `waitress-serve --listen=0.0.0.0:5000 --threads=8 wsgi:application` 启动，避免使用 `app.run()`；推荐使用 [deploy/windows/install-services.ps1](./deploy/windows/install-services.ps1) 通过 NSSM 注册为 Windows 服务
7. **Celery 独立部署**：生产环境应独立启动 Celery Worker 和 Beat（NSSM 注册为 Windows 服务），不要依赖 `main.py` 自动管理
---
## 🤝 贡献指南
我们欢迎任何形式的贡献！
### 贡献流程
1. **Fork** 本仓库
2. 创建功能分支：`git checkout -b feature/new-feature`
3. 提交更改：`git commit -am 'Add new feature'`
4. 推送到远程：`git push origin feature/new-feature`
5. 提交 **Pull Request**
### 代码规范
- 遵循 [PEP 8](https://www.python.org/dev/peps/pep-0008/) 代码规范
- 添加适当的注释和文档字符串
- 编写单元测试
- 确保所有测试通过
---
## 📄 许可证
本项目基于 **MIT** 许可证开源。
---
## 🧪 测试
项目使用 pytest 进行单元测试和集成测试，包含 50+ 测试文件、900+ 测试函数，覆盖服务层、工具层、模型层、安全测试、加密测试及 E2E 测试。
### 运行测试
```bash
# 运行所有测试
pytest
# 运行特定测试文件
pytest tests/test_auth_service.py
# 查看测试覆盖率
pytest --cov=app --cov-report=html
```
---
## 🚀 部署
### 生产环境部署（Windows）
> ⚠️ **本项目仅支持 Windows 生产部署**，因依赖 ZK `zkemkeeper` COM 组件和 `VideoSDK_Win64` DLL。
> 详细部署说明请参考 [运维文档](./docs/运维文档/部署运维文档.md)。
#### 1. 环境准备
```powershell
# 安装系统依赖（管理员 PowerShell）
# - Python 3.9.2+：https://www.python.org/downloads/
# - MySQL 8.0+：https://dev.mysql.com/downloads/
# - Redis for Windows：https://github.com/microsoftarchive/redis/releases
# - NSSM（服务管理）：https://nssm.cc/download，解压到 C:\nssm\
# 注册 ZK zkemkeeper COM 组件（管理员 CMD）
cd C:\Path\To\SDK
regsvr32 zkemkeeper.dll
```
#### 2. 安装项目依赖
```powershell
cd D:\k1989cms
python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt
```
#### 3. 配置环境变量
```powershell
Copy-Item .env.example .env
notepad .env
```
**生产环境重要配置**：
```bash
FLASK_ENV=production
SECRET_KEY=<生成强密钥>
JWT_SECRET_KEY=<生成强密钥>
ENCRYPTION_KEY=<生成44位Base64密钥>
DEBUG=False
```
#### 4. 初始化数据库
```powershell
# 在 MySQL 中创建数据库
mysql -u root -p -e "CREATE DATABASE k1989cms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
# 初始化表结构和默认数据
flask full_setup
```
#### 5. 注册 Windows 服务（NSSM）
```powershell
# 管理员 PowerShell 中执行
.\deploy\windows\install-services.ps1 -ProjectRoot D:\k1989cms -VenvDir venv -Port 5000
```
此脚本会注册三个 Windows 服务：
- `k1989cms`：waitress Web 服务
- `k1989cms-celery`：Celery Worker 异步任务
- `k1989cms-celery-beat`：Celery Beat 定时任务调度
#### 6. 服务管理
```powershell
# 查看服务状态
Get-Service k1989cms, k1989cms-celery, k1989cms-celery-beat
# 启动/停止/重启
Start-Service k1989cms*
Stop-Service k1989cms*
Restart-Service k1989cms
# 查看实时日志
Get-Content D:\k1989cms\logs\k1989cms.log -Tail 50 -Wait
```
#### 7. 日常发版（零脚本依赖）
```powershell
# 一键发版：拉代码 → 备份 → 迁移 → 重启服务 → 健康检查
.\deploy\scripts\deploy.ps1
# 模拟发版（验证流程，不实际执行）
.\deploy\scripts\deploy.ps1 -DryRun
# 跳过数据库迁移（仅改业务代码时）
.\deploy\scripts\deploy.ps1 -SkipMigration
```
**发版影响**：服务重启约 2-5 秒中断。Windows 无 SIGHUP 信号，waitress 无法优雅重载，需 Restart-Service。
#### 8. 反向代理（可选）
如需 HTTPS 或 80 端口访问，可在 IIS 或 Nginx for Windows 配置反向代理到 `127.0.0.1:5000`。Nginx 配置参考 [deploy/nginx/k1989cms.conf](./deploy/nginx/k1989cms.conf)。
---
### Linux 备用部署（仅业务层，不含 ZK COM SDK）
> ⚠️ Linux 部署**不支持** ZK 设备 COM 通信和视频监控，仅适用于纯业务层 + 设备 TCP 降级模式。
参考 [Dockerfile](./Dockerfile) 和 [docker-compose.yml](./docker-compose.yml)，使用 gunicorn 启动。systemd 配置参考 [deploy/systemd/](./deploy/systemd/)。
---
## 📞 技术支持
### 项目地址
- **Gitee**: https://gitee.com/thomasblog/k1989cms
- **问题反馈**: https://gitee.com/thomasblog/k1989cms/issues
---
## 📚 文档
详细文档请查看 [docs](./docs) 目录：
- [产品需求文档](./docs/产品需求文档/)
- [技术设计文档](./docs/技术设计文档/) - 含系统架构、路由分层、服务层、设备通信、Agent架构等设计文档
- [开发文档](./docs/开发文档/) - 含开发环境搭建、项目结构说明、模块开发指南
- [运维文档](./docs/运维文档/) - 含部署、监控、备份恢复、故障排查
- [代码规范](./docs/代码规范/) - Python/前端/数据库/Git 提交规范
- [操作手册](./docs/操作手册/) - 管理员/用户/访客操作指南
- [审查交付物](./docs/审查交付物/) - 六步审查体系产物（14 份）
---
## 📋 更新日志
### v2.5.0 (2026-07-08)
#### 安全修复（14项）
- 修复 JWT 管理员鉴权因导入错误完全失效问题（jwt_decorators.py）
- 修复启动安全体检异常被 `except: pass` 吞掉问题（app/__init__.py）
- 修复 JWT 黑名单被 `verify_token` 绕过问题（auth_service.py）
- 修复安全中间件限流器因属性名不匹配失效问题（security_middleware.py）
- 修复 3 处路径遍历漏洞（attendance/report/backup）
- 修复 SSRF 漏洞（sensor_routes.py callback_url 无白名单）
- 修复 Building API 4 个端点无权限控制问题（organization_routes.py）
- 修复 71 处设备写操作使用 VIEW 权限问题（device_routes.py）
- 修复 API Key 完整明文返回前端问题（api_docs_routes.py）
- 修复 Agent 远程命令执行无沙箱问题（Python + Go 双版本）
- 修复 Agent 心跳/下载/状态接口无认证问题（asset_agent.py）
- 修复 13 处审计日志丢失风险，改为独立事务（IndependentLogService）
- 修复 TCP/WebSocket 连接池有效性检查失效问题（connection_pool.py）
- 修复 Ping 线程池扩容（8→32）支持更多设备并发检测（device_monitor.py）
#### 功能完整性修复（7项）
- 消费路由 `/payments` 重复注册导致路由覆盖问题（consumption_routes.py）
- WebSocket 连接池 `is_valid` 和 `close` 真实实现（connection_pool.py）
- Go Agent EDR 补全网络连接和登录尝试检测（edr/edr.go）
- 报表服务补全考勤/消费/访客/设备 4 类报表（report_service.py）
- 部门树查询验证，使用内存映射消除 N+1 问题（organization_service.py）
#### 深度功能修复（5项）
- Go Agent 命令执行沙箱（白名单+危险字符过滤+300s超时），与 Python Agent 对齐（updater.go）
- 前端 API 端点引用修复（考勤部门树 URL、员工离职 URL，共 3 处模板）
- 访客联动 API 端点补全（列表查询+重试联动，含服务层方法）
- `func.IF()` → `case()` 跨数据库兼容（考勤部门排名报表）
- `func.date_format()` → `extract()` 跨数据库兼容（资产月度趋势统计）
#### 部署就绪
- 新增 `wsgi.py` 生产环境 WSGI 入口，支持 gunicorn/uwsgi 部署
- `main.py` 生产环境警告，提示使用 gunicorn 替代 `app.run()`
- 修正 README 中不存在的 `deploy/gunicorn.conf.py` 引用
### v2.4.0 (2026-07-04)
#### 文档体系更新
- 基于全面代码分析，新增 4 份技术设计文档：路由分层架构、服务层架构设计、设备通信架构、Agent架构设计
- 重写项目结构说明文档（v3.0），准确反映七层路由、79 服务类、12 通信模块、40+ 数据模型架构
- 更新文档中心索引至 v8.0，修复技术设计文档中的失效引用
- 更新 README 技术栈，补充设备通信协议矩阵和 Agent 技术说明
#### 架构改进
- 修复 MySQL 版本要求不一致问题（统一为 8.0+）
- 完善 README 项目结构，补充 Go Agent、通信模块、Celery 任务等缺失内容
### v2.3.3 (2026-04-28)
#### 修复问题
- **BUG-001**: 修复访客审批功能异常（API URL路径错误）
- **BUG-002**: 修复员工端创建访客邀请失败（允许无employee记录的用户创建邀请）
- **BUG-005**: 修复用户端门禁记录页面404错误（蓝图URL前缀配置）
- **BUG-007**: 修复通行记录页面加载失败（模板block名称和API字段名错误）
- **BUG-008**: 添加用户端导航菜单门禁记录入口
#### 功能优化
- 完善用户端导航菜单，添加门禁记录入口
- 优化 `login_required` 装饰器，支持识别包含 `/api/` 的路径
- 完善通行记录API字段映射
---
**K1989CMS** - 让企业管理更智能、更高效！
Made with ❤️ by K1989 Team