v6ole/H3ConuMS-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

初始化

Browse Source
This commit is contained in:
v6ole
2026-04-02 23:40:04 +08:00
commit 381ea7085d
107 changed files with 11858 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
系统设计文档.md
+441
View File
@@ -0,0 +1,441 @@
# H3C ONU设备管理系统 - 系统设计文档
## 项目概述
基于Python后端 + Vue前端的H3C OLT设备监控管理系统，用于监控4000+ ONU设备的在线状态，支持权限管理、数据导入、状态检查等功能。
## 设计讨论记录
**讨论时间**: 2026年4月1日
**参与人员**: 阿森、小柚（AI助手）
## 一、核心需求
### 1.1 设备状态监控
- 通过SSH连接H3C OLT设备查询ONU状态
- 支持不同插槽命令：`display onu slot 1`、`display onu slot 3`等
- 状态判断：返回结果包含"Up"为在线，"Offline"为离线
- 4000+设备MAC地址和物理位置信息管理
### 1.2 数据管理
- Excel表格导入（4000条记录）
- PostgreSQL数据库存储
- 设备信息包括：区域、学校名称、楼宇、场所类型、房间号、MAC地址、状态、备注
### 1.3 更新频率
- 自动更新：每30分钟
- 手动刷新：5分钟冷却限制
- 历史记录：保存90天
### 1.4 权限管理
- 多级用户权限（超级管理员、管理员、区域管理员、学校管理员、普通用户）
- Casdoor统一认证集成
- 基于RBAC的权限控制
- 设备信息变更审核流程
### 1.5 部署要求
- Docker Compose编排
- 外部PostgreSQL和Redis
- 环境变量配置（.env文件）
- 支持后续功能扩展（库存管理等）
## 二、系统架构
### 2.1 技术栈
**后端**:
- Python FastAPI
- PostgreSQL
- Paramiko (SSH)
- Celery + Redis (异步任务)
- Pandas (Excel处理)
- Casdoor SDK (认证)
**前端**:
- Vue 3 + Composition API
- Element Plus UI
- Axios
- Vue Router
- Pinia
### 2.2 部署架构
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Nginx反向代理 │ │ FastAPI后端 │ │ Celery Worker │
│ │◄──►│ │◄──►│ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Vue前端静态文件 │ │ PostgreSQL数据库 │ │ Redis │
│ │ │ (外部) │ │ (外部) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐
│ Casdoor │
│ 认证服务器 │
└─────────────────┘
```
## 三、数据库设计
### 3.1 核心表结构
#### olt_devices (OLT设备表)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | BIGSERIAL PRIMARY KEY | 主键 |
| ip_address | VARCHAR(45) | OLT设备IP地址 |
| username | VARCHAR(100) | SSH用户名 |
| password | TEXT | SSH密码（加密存储） |
| slot_command | VARCHAR(50) | 插槽命令，如"display onu slot 1" |
| description | TEXT | 设备描述 |
| created_at | TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | 更新时间 |
#### onu_devices (ONU设备表)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | BIGSERIAL PRIMARY KEY | 主键 |
| mac_address | VARCHAR(17) | MAC地址 (1484-7790-5200格式) |
| olt_id | BIGINT REFERENCES olt_devices(id) | 关联的OLT设备ID |
| slot_number | INTEGER | 插槽号 |
| port_number | INTEGER | 端口号 |
| region | VARCHAR(100) | 区域（共和乡） |
| school_name | VARCHAR(200) | 学校名称 |
| building | VARCHAR(100) | 楼宇 |
| location_type | VARCHAR(100) | 场所类型 |
| room_number | VARCHAR(50) | 房间号 |
| notes | TEXT | 备注 |
| created_at | TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | 更新时间 |
#### device_status_history (设备状态历史表)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | BIGSERIAL PRIMARY KEY | 主键 |
| onu_device_id | BIGINT REFERENCES onu_devices(id) | ONU设备ID |
| status | VARCHAR(20) | 状态（online/offline） |
| checked_at | TIMESTAMP | 检查时间 |
| response_data | TEXT | 原始响应数据 |
| created_at | TIMESTAMP | 创建时间 |
#### users (用户表 - Casdoor集成)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | BIGSERIAL PRIMARY KEY | 主键 |
| casdoor_id | VARCHAR(100) UNIQUE | Casdoor用户ID |
| username | VARCHAR(100) | 用户名 |
| email | VARCHAR(255) | 邮箱 |
| role | VARCHAR(50) | 角色 |
| assigned_area | VARCHAR(100) | 分配区域 |
| assigned_school | VARCHAR(200) | 分配学校 |
| is_active | BOOLEAN DEFAULT true | 是否激活 |
| last_login | TIMESTAMP | 最后登录 |
| sync_at | TIMESTAMP | 最后同步时间 |
| created_at | TIMESTAMP | 创建时间 |
#### permissions (权限表)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | BIGSERIAL PRIMARY KEY | 主键 |
| name | VARCHAR(100) | 权限名称 |
| code | VARCHAR(50) UNIQUE | 权限代码 |
| module | VARCHAR(50) | 所属模块 |
| description | TEXT | 权限描述 |
#### role_permissions (角色权限关联表)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| role_id | BIGINT | 角色ID |
| permission_id | BIGINT | 权限ID |
| PRIMARY KEY (role_id, permission_id) | | |
#### device_change_requests (设备变更请求表)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | BIGSERIAL PRIMARY KEY | 主键 |
| device_id | BIGINT REFERENCES onu_devices(id) | 设备ID |
| requested_by | BIGINT REFERENCES users(id) | 请求用户 |
| change_type | VARCHAR(50) | 变更类型 |
| current_data | JSONB | 当前数据 |
| requested_data | JSONB | 请求数据 |
| status | VARCHAR(20) | 状态 |
| reviewed_by | BIGINT REFERENCES users(id) | 审核人 |
| reviewed_at | TIMESTAMP | 审核时间 |
| change_reason | TEXT | 变更原因 |
| created_at | TIMESTAMP | 创建时间 |
## 四、API接口设计
### 4.1 认证相关
```
POST /api/auth/login # Casdoor登录回调
GET /api/auth/profile # 获取用户信息
POST /api/auth/logout # 退出登录
```
### 4.2 设备管理
```
GET /api/devices # 获取设备列表（分页、筛选）
GET /api/devices/{id} # 获取设备详情
GET /api/devices/{id}/history # 获取设备历史状态
POST /api/devices/import # 导入Excel文件
PUT /api/devices/{id} # 更新设备信息（管理员）
POST /api/devices/{id}/change-request # 提交变更请求
```
### 4.3 状态检查
```
POST /api/check/status # 手动触发状态检查
GET /api/check/progress # 获取检查进度
GET /api/check/history # 获取检查历史
GET /api/check/schedule # 获取定时任务配置
PUT /api/check/schedule # 更新定时任务配置
```
### 4.4 统计信息
```
GET /api/stats/summary # 获取统计摘要
GET /api/stats/trend # 获取趋势数据
GET /api/stats/area # 按区域统计
GET /api/stats/school # 按学校统计
```
### 4.5 权限管理
```
GET /api/users # 获取用户列表
GET /api/users/{id} # 获取用户详情
PUT /api/users/{id} # 更新用户信息
GET /api/roles # 获取角色列表
GET /api/permissions # 获取权限列表
GET /api/change-requests # 获取变更请求列表
PUT /api/change-requests/{id}/review # 审核变更请求
```
## 五、前端界面设计
### 5.1 页面结构
1. **登录页面** - Casdoor统一登录
2. **仪表板** - 统计卡片、图表、手动刷新
3. **设备列表** - 表格展示、筛选、搜索
4. **设备详情** - 详细信息、历史图表
5. **数据导入** - Excel上传、预览、历史
6. **审核中心** - 变更请求审核
7. **系统设置** - OLT设备管理、任务配置
8. **用户管理** - 用户列表、权限分配
### 5.2 权限控制
- **页面级权限**：路由守卫控制
- **组件级权限**：v-permission指令
- **数据级权限**：API过滤用户数据
- **操作级权限**：按钮显示控制
## 六、Casdoor集成方案
### 6.1 配置参数
```python
CASDOOR = {
"endpoint": "https://casdoor.example.com",
"client_id": "your_client_id",
"client_secret": "your_client_secret",
"certificate": "your_certificate",
"org_name": "your_org_name",
"app_name": "h3c-onu-ms",
"redirect_url": "http://localhost:8000/api/auth/callback"
}
```
### 6.2 登录流程
1. 前端重定向到Casdoor登录页
2. 用户登录后回调到系统
3. 后端验证code获取用户信息
4. 同步用户信息到本地数据库
5. 生成JWT令牌返回前端
### 6.3 权限映射
- Casdoor角色 → 系统角色（配置映射）
- Casdoor属性 → 分配区域/学校
- 支持动态权限同步
## 七、Docker部署配置
### 7.1 docker-compose.yml
```yaml
version: '3.8'
services:
backend:
build: ./backend
ports:
- "8000:8000"
environment:
- DATABASE_URL=postgresql://user:pass@host:5432/dbname
- REDIS_URL=redis://host:6379/0
- CASDOOR_CONFIG=${CASDOOR_CONFIG}
volumes:
- ./logs:/app/logs
depends_on:
- redis
restart: unless-stopped
celery-worker:
build: ./backend
command: celery -A app.celery_app worker --loglevel=info
environment:
- DATABASE_URL=postgresql://user:pass@host:5432/dbname
- REDIS_URL=redis://host:6379/0
volumes:
- ./logs:/app/logs
depends_on:
- redis
restart: unless-stopped
celery-beat:
build: ./backend
command: celery -A app.celery_app beat --loglevel=info
environment:
- DATABASE_URL=postgresql://user:pass@host:5432/dbname
- REDIS_URL=redis://host:6379/0
volumes:
- ./logs:/app/logs
depends_on:
- redis
restart: unless-stopped
frontend:
build: ./frontend
ports:
- "8080:80"
environment:
- VITE_API_BASE_URL=http://localhost:8000
restart: unless-stopped
nginx:
image: nginx:alpine
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf
- ./ssl:/etc/nginx/ssl
depends_on:
- backend
- frontend
restart: unless-stopped
redis:
image: redis:alpine
restart: unless-stopped
```
### 7.2 .env.example
```env
# 数据库配置
DATABASE_URL=postgresql://username:password@host:5432/dbname
REDIS_URL=redis://host:6379/0
# Casdoor配置
CASDOOR_ENDPOINT=https://casdoor.example.com
CASDOOR_CLIENT_ID=your_client_id
CASDOOR_CLIENT_SECRET=your_client_secret
CASDOOR_CERTIFICATE=your_certificate
CASDOOR_ORG_NAME=your_org
CASDOOR_APP_NAME=h3c-onu-ms
# 应用配置
SECRET_KEY=your-secret-key-here
DEBUG=false
ALLOWED_HOSTS=localhost,127.0.0.1
# SSH配置
SSH_TIMEOUT=30
SSH_MAX_CONNECTIONS=10
```
## 八、后续功能规划
### 8.1 库存管理模块
- 设备库存管理
- 出入库记录
- 库存预警
- 供应商管理
### 8.2 告警通知模块
- 设备离线告警
- 库存预警通知
- 支持邮件、企业微信、钉钉通知
- 告警规则配置
### 8.3 报表导出模块
- 设备状态报表
- 历史记录报表
- 统计图表导出
- 自定义报表模板
### 8.4 移动端适配
- 响应式移动端界面
- PWA支持
- 移动端专属功能
## 九、开发计划
### 9.1 第一阶段（基础功能）
1. 项目框架搭建
2. 数据库设计和迁移
3. Casdoor集成
4. 基础API开发
5. 前端框架搭建
### 9.2 第二阶段（核心功能）
1. Excel导入功能
2. SSH连接和状态检查
3. 设备列表和详情页
4. 定时任务调度
5. 基础权限控制
### 9.3 第三阶段（高级功能）
1. 权限管理系统
2. 变更审核流程
3. 统计图表
4. 系统设置页面
5. 性能优化
### 9.4 第四阶段（扩展功能）
1. 库存管理模块
2. 告警通知系统
3. 报表导出功能
4. 移动端适配
## 十、风险评估和应对
### 10.1 技术风险
1. **SSH连接稳定性**
- 风险：网络波动导致连接失败
- 应对：连接池、重试机制、超时设置
2. **性能问题**
- 风险：4000+设备查询性能
- 应对：异步处理、分批查询、缓存优化
3. **安全性**
- 风险：SSH凭证存储安全
- 应对：加密存储、访问控制、审计日志
### 10.2 业务风险
1. **数据准确性**
- 风险：设备状态误判
- 应对：多重验证、人工复核机制
2. **用户接受度**
- 风险：操作复杂度过高
- 应对：用户培训、简化流程、良好UI
## 十一、总结
本系统设计基于实际业务需求，采用现代化的技术栈和架构，具备良好的扩展性和维护性。通过Casdoor集成实现统一认证，基于RBAC的权限管理系统支持复杂的权限控制需求，Docker化部署确保环境一致性。
系统将分阶段实施，优先保证核心功能的稳定运行，逐步扩展高级功能。建议在开发过程中保持与业务人员的密切沟通，及时调整需求。
---
**文档版本**: v1.0
**最后更新**: 2026年4月1日
**下次评审**: 2026年4月15日