# MicroDoorAccess

**Repository Path**: java110/microdooraccess

## Basic Information

- **Project Name**: MicroDoorAccess
- **Description**: HC门禁系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-13
- **Last Updated**: 2026-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MicroDoorAccess 门禁控制系统

运行在 Ubuntu 18.04 + Python 3.6 上的门禁控制系统：PyQt5 触摸屏界面实时展示相机画面与识别结果，串口接收人脸识别相机结果（`PASS:姓名`/`FAIL`），识别通过后通过 GPIO / C 动态库 / 串口继电器三种驱动方式开锁，SQLite 存储人员与通行日志，并提供 HTTP REST（openapi/console）与 MQTT 远程接入能力。

技术栈：Python 3.6、PyQt5、OpenCV、pyserial、ctypes、SQLite3、Flask、paho-mqtt。

## 目录结构

```
MicroDoorAccess/
├── main.py                      # 入口：--ui / --console / --openapi / --mqtt 可组合启动，缺省全开
├── requirements.txt             # 依赖清单（Python 3.6 版本锁定）
├── dc-core/                     # 核心包：common（响应/鉴权/DB/日志/异常）+ config（config.ini）
├── models/ schemas/ repositories/ services/   # 分层架构（单向依赖）
├── dc-view/                     # 接入层：ui / console / openapi / mqtt
├── drivers/                     # 硬件驱动：串口、门锁(gpio/clib/serial)、语音
├── threads/                     # 串口监听线程、视频线程
├── scripts/                     # 启动脚本 + serial_mock.py 串口模拟器
├── docs/                        # 部署说明 / API 文档
├── data/                        # SQLite 数据库（运行时生成）
└── libs/                        # 厂商 C 动态库（部署时放置 vendor_lock.so）
```

## 安装

项目使用 **Python 3.6 独立虚拟环境**（`venv/`）运行，与全局 Python 隔离。

```bash
# 1. 确认本机已有 Python 3.6 解释器（Ubuntu 18.04 自带，其他系统参考 docs/部署说明.md）
python3.6 --version

# 2. 一键初始化虚拟环境（创建 venv/ → 升级 pip/setuptools → 安装依赖 → 自检）
./scripts/setup_venv.sh

# 3. （可选）强制重建虚拟环境
./scripts/setup_venv.sh --reinstall
```

> 手动方式：`python3.6 -m venv venv && venv/bin/pip install -r requirements.txt`

> 注意：目录名 dc-core / dc-view 含连字符，无法直接 import，`main.py` 启动时会自动注册 `dc_core` / `dc_view` 模块别名，**请始终通过 `main.py` 或 `scripts/` 脚本启动**，不要直接 `import dc_view.xxx`。

## 运行

所有 `scripts/start_*.sh` 均自动使用虚拟环境解释器 `venv/bin/python3`，虚拟环境缺失时会提示先执行 `scripts/setup_venv.sh`。

```bash
# 全模式（UI + console + openapi + mqtt）——最简单，直接看 UI 面板
./scripts/start_all.sh

# 仅启动本地触摸屏 UI
./scripts/start_ui.sh

# 仅启动内部管理控制台（HTTP + Web 管理页，默认 127.0.0.1:8000）
./scripts/start_console.sh

# 仅启动对外 API（默认 127.0.0.1:8001）
./scripts/start_openapi.sh

# 仅启动 MQTT 接入
./scripts/start_mqtt.sh
```

等价手动命令（直接使用虚拟环境解释器）：`venv/bin/python3 main.py [--ui/--console/--openapi/--mqtt]`，缺省为全模式。

启动后：

- **UI 面板**：待机页显示摄像头画面 + 识别结果浮层（PASS 绿 / FAIL 红）+ 设备状态栏；顶部可切换"人员管理"（增删改查）、"系统设置"
- **Web 管理控制台**：浏览器打开 `http://127.0.0.1:8000/`，登录口令默认 `123456`（`[admin].password`），管理页免登录
- **对外 API**：请求头 `X-API-Key: microdoor-access-key`（`[http].api_key`）

## 配置

配置文件：`dc-core/config/config.ini`（或通过 Web/UI 设置页修改，保存后写回 ini）。

关键配置：

| 节 | 说明 | 默认 |
| ---- | ---- | ---- |
| `[serial]` | 人脸识别相机串口 | `/dev/ttyUSB0` @ 9600 |
| `[camera]` | 摄像头设备号/分辨率/帧率 | device 0, 640x480, 20fps |
| `[lock]` | 开锁方式 `gpio`/`clib`/`serial` 及参数 | serial |
| `[admin]` | 管理员口令 / Token 密钥 | 123456 |
| `[http]` | console/openapi 监听地址端口、API Key | 127.0.0.1:8000/8001 |
| `[mqtt]` | broker 地址、设备 ID、主题前缀、TLS | door001 |
| `[voice]` | 语音播报（sound 播放 wav / tts 播报） | sound |

## 调试（无硬件环境）

```bash
# 串口模拟器：模拟相机发送 PASS:姓名 / FAIL（默认 /dev/ttyUSB0）
venv/bin/python3 scripts/serial_mock.py
venv/bin/python3 scripts/serial_mock.py --port /dev/ttyUSB1 --loop 5

# 无摄像头时 UI 自动显示"摄像头离线"占位，不影响使用
# 无门锁硬件时开锁自动降级失败并记录日志，系统不崩溃
```

## 常见问题

- **串口打不开**：检查设备权限（`sudo usermod -aG dialout $USER`）与 `[serial].port` 配置
- **GPIO 开锁失败**：Ubuntu 下 GPIO 需要 root 或 udev 设备组权限
- **clib 开锁**：将厂商 `vendor_lock.so` 放入 `libs/`，未放置自动降级为 serial
- **数据库重置**：`rm -f data/microdoor.db*` 后重启
- **日志**：`logs/app.log`（按天滚动，保留 7 天）

## 相关文档

- `docs/部署说明.md`：完整部署与硬件准备
- `docs/API文档.md`：console / openapi 接口说明