# lock

**Repository Path**: ns6/lock

## Basic Information

- **Project Name**: lock
- **Description**: 基于 STM32F407ZGT6 + RT-Thread 的 WiFi 门禁控制系统
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-21
- **Last Updated**: 2026-07-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WiFi 门禁管理系统

基于 **STM32F407ZGT6 + RT-Thread** 的 WiFi 门禁控制系统，包含嵌入式设备端、Java 后端服务和 Web 前端三个部分。

## 项目结构

```
├── lock/          # 嵌入式设备端 (STM32F407 + RT-Thread)
├── backend/       # Java 后端服务 (Spring Boot 3.2 + Netty + MinIO)
├── frontend/      # Web 前端 (HTML/CSS/JS, 移动端优先)
├── Dockerfile     # Docker 镜像构建
├── docker-compose.yml  # Docker Compose 编排 (后端 + MinIO)
└── README.md
```

## 硬件平台

- **开发板**: RT-Spark 星火一号
- **主控芯片**: STM32F407ZGT6
- **WiFi 模块**: 板载 RW007 (SPI)

## 核心功能

- WiFi TCP 远程通信（自定义二进制协议）
- 考勤记录上传与 MinIO 对象存储
- 远程开门、用户管理、时间同步
- LCD 实时显示
- Web 管理后台（移动端优化）

## 快速开始

### 方式一: Docker Compose（推荐，云服务器部署）

```bash
# 1. 上传 backend/ frontend/ Dockerfile docker-compose.yml 到服务器同一目录
# 2. 启动 (自动构建镜像)
docker-compose up -d --build

# 3. 访问
#    前端:         http://服务器IP:8080
#    MinIO 控制台: http://服务器IP:9003
#    账号/密码:    minioadmin / minioadmin
```

### 方式二: 本地 Maven 运行

```bash
# 前提: JDK 17+, MinIO 已启动
cd backend
mvn package -DskipTests
java -jar target/lock-1.0-SNAPSHOT.jar
```

浏览器打开 `http://localhost:8080`

### 烧录设备固件

使用 RT-Thread Studio 打开 `lock/` 工程，编译后通过 ST-Link 烧录。
部署到云服务器后，需修改固件 `main.c` 中 `server_ip` 为云服务器公网 IP。

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `FRONTEND_PATH` | `d:/Software/...` | 前端静态文件路径 |
| `SERVER_PORT` | `8080` | HTTP 端口 |
| `TCP_PORT` | `2756` | TCP 设备通信端口 |
| `MINIO_ENDPOINT` | `http://127.0.0.1:9000` | MinIO 服务地址 |
| `MINIO_ACCESS_KEY` | `minioadmin` | MinIO 账号 |
| `MINIO_SECRET_KEY` | `minioadmin` | MinIO 密码 |
| `MINIO_BUCKET` | `attendance` | MinIO 存储桶 |
| `LOG_LEVEL` | `INFO` | 日志级别 |

## TCP 通信协议

设备与后端采用自定义二进制帧格式：

```
[length:2B LE][cmd:1B][data:NB][crc:4B CRC32-MPEG2]
```

## 技术栈

| 层级 | 技术 |
|------|------|
| 设备端 | STM32F407 + RT-Thread v4.1.1 + RW007 WiFi + lwIP |
| 后端 | Java 17 + Spring Boot 3.2 + Netty + MinIO SDK |
| 前端 | 原生 HTML/CSS/JS |

## 云服务器防火墙

部署前务必放行以下端口，否则外网无法访问：

| 端口 | 协议 | 用途 |
|------|------|------|
| 8080 | TCP | Web 前端 + REST API |
| 2756 | TCP | 设备 TCP 通信 (STM32 连接) |
| 9002 | TCP | MinIO API (调试用) |
| 9003 | TCP | MinIO 控制台 (调试用) |

**阿里云 / 腾讯云**: 在安全组规则中添加入方向放行。

**服务器本地防火墙** (CentOS/RHEL):
```bash
firewall-cmd --add-port=8080/tcp --permanent
firewall-cmd --add-port=2756/tcp --permanent
firewall-cmd --reload
```

**Ubuntu/Debian**:
```bash
ufw allow 8080/tcp
ufw allow 2756/tcp
```

## 内网穿透 (可选，如有云服务器可忽略，手机远程访问)

```bash
cpolar http 8080
```

前端 `api.js` 已内置 URL 自动检测，使用 cpolar/ngrok 穿透后无需手动修改任何配置，手机直接访问 cpolar 生成的公网地址即可。

## 常见问题

### Q: Docker 构建报 `backend/pom.xml: not found`
确保项目文件结构正确：
```
项目根目录/
├── Dockerfile
├── docker-compose.yml
├── .dockerignore
├── backend/
│   ├── pom.xml
│   └── src/
└── frontend/
    ├── index.html
    ├── css/
    └── js/
```
`docker-compose up --build` 必须在包含 `Dockerfile` 的目录下执行。

### Q: 前端能打开但收不到设备数据
检查：① 云服务器防火墙是否放行 **2756** 端口；② 固件 `main.c` 中 `server_ip` 是否已改为服务器公网 IP。

### Q: 板子连不上服务器 TCP
- 确认 WiFi 已连接（看串口日志）
- 确认防火墙 2756 端口已放行
- 固件中 IP 地址是**公网 IP**，不是服务器内网 IP