# devices_py

**Repository Path**: ming916/devices_py

## Basic Information

- **Project Name**: devices_py
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-21
- **Last Updated**: 2026-03-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 设备监控系统

一个基于Python的设备监控系统，使用TCP通信实现设备心跳检测和数据传输，提供RESTful API接口供前端调用。

## 功能特性

- **TCP通信**：使用TCP/socket实现设备与服务器之间的通信
- **心跳检测**：设备超时未发送心跳包自动标记为离线
- **设备管理**：支持设备的添加、查询、更新和删除
- **用户管理**：支持用户注册、登录和权限管理
- **数据存储**：使用数据库存储设备信息和用户信息
- **RESTful API**：提供完整的API接口供前端调用
- **实时监控**：实时监控设备在线状态

## 技术栈

- **后端框架**：FastAPI
- **数据库**：SQLAlchemy ORM（支持SQLite、MySQL等）
- **认证**：JWT（JSON Web Tokens）
- **通信**：asyncio TCP服务器
- **API文档**：Swagger UI

## 项目结构

```
device_monitor/
├── api/              # API 路由与Schema
│   ├── __init__.py
│   ├── router.py     # 汇总路由
│   ├── deps.py       # 依赖（如 TCP Server 注入）
│   ├── schemas.py    # Pydantic 模型
│   └── routers/      # 按领域拆分的路由
│       ├── auth.py
│       ├── stores.py
│       ├── users.py
│       ├── devices.py
│       ├── device_data.py
│       └── websocket.py
├── config/           # 配置文件
│   ├── __init__.py
│   └── settings.py   # 应用配置
├── models/           # 数据库模型
│   ├── __init__.py
│   ├── database.py   # 数据库连接
│   └── models.py     # 数据模型
├── tcp_server/       # TCP服务器
│   ├── __init__.py
│   └── tcp_server.py # TCP服务器实现
├── utils/            # 工具函数
│   ├── __init__.py
│   └── auth.py       # 认证和权限
├── .env.example      # 环境变量示例
├── main.py           # 应用主入口
├── requirements.txt  # 依赖包
├── start.bat         # 启动脚本（Windows）
└── README.md         # 项目说明
```

## 安装和运行

### 1. 克隆项目

```bash
git clone <repository-url>
cd device_monitor
```

### 2. 配置环境变量

复制`env.example`文件为`.env`，并根据需要修改配置（`SECRET_KEY`、`DATABASE_URL`、`RSA_PUBLIC_KEY`/`RSA_PRIVATE_KEY` 必填）：

```bash
cp env.example .env
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

### 4. 数据库迁移（Alembic）

默认使用 MySQL（开发/生产一致）。在 `.env` 设置 `DATABASE_URL="mysql+pymysql://user:pwd@localhost:3306/device_monitor?charset=utf8mb4"` 后执行：

```bash
# 首次建表
alembic upgrade head

# 模型变更后生成新迁移
alembic revision --autogenerate -m "your message"
alembic upgrade head
```

如需本地 SQLite，可将 `DATABASE_URL` 改为 `sqlite:///./db`，再执行同样的迁移命令。

### 5. 启动应用

#### Windows

双击`start.bat`脚本或在命令行中执行：

```bash
start.bat
```

#### Linux/Mac

```bash
python main.py
```

### 6. 访问应用

- **API服务**：http://127.0.0.1:8000
- **API文档**：http://127.0.0.1:8000/docs
- **TCP服务器**：监听在配置的端口（默认为8888）

### 7. 生成 RSA 密钥（开发环境）

项目提供 `device_monitor/utils/auth.py` 中的 `generate_rsa_keys` 辅助函数，可在 Python 交互式环境中生成一对密钥并填入 `.env`：

```python
from utils.auth import generate_rsa_keys
keys = generate_rsa_keys()
print(keys["public_key"])
print(keys["private_key"])
```

## API接口

### 认证

- `POST /api/token` - 获取访问令牌
  - 请求体中的 `password` 必须为使用公钥加密后的十六进制字符串（参考上文 RSA 说明）

### 用户管理

- `GET /api/users/me` - 获取当前用户信息
- `GET /api/users` - 获取用户列表（仅超级用户）
- `POST /api/users` - 创建新用户（仅超级用户）
- `PUT /api/users/{user_id}` - 更新用户信息（仅超级用户）
- `DELETE /api/users/{user_id}` - 删除用户（仅超级用户）

### 设备管理

- `GET /api/devices` - 获取设备列表
- `POST /api/devices` - 创建新设备
- `GET /api/devices/{device_id}` - 获取设备详情
- `PUT /api/devices/{device_id}` - 更新设备信息
- `DELETE /api/devices/{device_id}` - 删除设备
- `GET /api/devices/{device_id}/status` - 获取设备状态

## 设备通信协议

### 连接流程

1. 设备连接到TCP服务器
2. 设备发送设备ID
3. 服务器验证设备ID，返回欢迎消息
4. 设备定期发送心跳包（建议每30秒发送一次）
5. 服务器接收数据并更新设备状态

### 心跳包格式

设备发送：
```
HEARTBEAT
```

服务器回复：
```
HEARTBEAT_ACK
```

### 数据传输

设备发送数据后，服务器会回复：
```
RECV_OK
```

## 数据库

默认使用SQLite数据库，数据库文件为`db`。可以在`.env`文件中修改数据库连接字符串，支持MySQL等其他数据库。

## 注意事项

1. **数据库迁移**: 首次运行请执行 `alembic upgrade head` 创建数据库表
2. **环境配置**: 务必配置 `.env` 文件，设置 `SECRET_KEY`、`RSA_PUBLIC_KEY`、`RSA_PRIVATE_KEY` 和 `DATABASE_URL`
3. **生产环境**: 
   - 修改`SECRET_KEY`为随机生成的字符串
   - 关闭`DEBUG`模式
   - 使用HTTPS协议部署
   - 限制CORS来源（不要使用 `*`）
4. **设备心跳**: 设备心跳间隔应小于配置的`HEARTBEAT_TIMEOUT`（默认为60秒）
5. **日志系统**: 应用启动时自动初始化日志系统，日志级别由`DEBUG`配置控制
6. **错误处理**: 所有异常都会被统一处理，返回标准化的错误响应

## 开发说明

### 运行开发服务器

```bash
python main.py
```

### 访问API文档

在浏览器中访问 http://127.0.0.1:8000/docs 可以查看和测试API接口。

### 健康检查

- **基础健康检查**: `GET /api/health` - 快速检查服务状态
- **详细健康检查**: `GET /api/health/detailed` - 检查数据库和TCP服务器状态

### 监控指标

- **Prometheus指标**: `GET /api/metrics` - 暴露Prometheus格式的监控指标
  - TCP连接数统计
  - 心跳和消息计数
  - 队列丢弃计数

### 运行测试

```bash
# 运行所有测试
pytest

# 运行特定测试文件
pytest tests/test_integration.py
pytest tests/test_health.py
pytest tests/test_permissions.py
```

## 许可证

MIT

## 迁移与索引（规划）

- 推荐引入 Alembic 管理迁移，跟踪模型变更。
- 为高频字段加索引：`devices.device_id`（已唯一）、`devices.store_id`、`devices.status`、`device_data.device_id`、`users.store_id`。
- 生产使用 MySQL 时，确保字符集 `utf8mb4`，连接串带 `charset=utf8mb4`。