441 lines
13 KiB
Markdown
441 lines
13 KiB
Markdown
# 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日 |