v6ole/H3ConuMS-v2

Fork 0

Files

T

v6ole 381ea7085d 初始化

2026-04-02 23:40:04 +08:00

13 KiB

Raw Blame History

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 页面结构

登录页面 - Casdoor统一登录
仪表板 - 统计卡片、图表、手动刷新
设备列表 - 表格展示、筛选、搜索
设备详情 - 详细信息、历史图表
数据导入 - Excel上传、预览、历史
审核中心 - 变更请求审核
系统设置 - OLT设备管理、任务配置
用户管理 - 用户列表、权限分配

5.2 权限控制

页面级权限：路由守卫控制
组件级权限：v-permission指令
数据级权限：API过滤用户数据
操作级权限：按钮显示控制

六、Casdoor集成方案

6.1 配置参数

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 登录流程

前端重定向到Casdoor登录页
用户登录后回调到系统
后端验证code获取用户信息
同步用户信息到本地数据库
生成JWT令牌返回前端

6.3 权限映射

Casdoor角色 → 系统角色（配置映射）
Casdoor属性 → 分配区域/学校
支持动态权限同步

七、Docker部署配置

7.1 docker-compose.yml

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

# 数据库配置
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 第一阶段（基础功能）

项目框架搭建
数据库设计和迁移
Casdoor集成
基础API开发
前端框架搭建

9.2 第二阶段（核心功能）

Excel导入功能
SSH连接和状态检查
设备列表和详情页
定时任务调度
基础权限控制

9.3 第三阶段（高级功能）

权限管理系统
变更审核流程
统计图表
系统设置页面
性能优化

9.4 第四阶段（扩展功能）

库存管理模块
告警通知系统
报表导出功能
移动端适配

十、风险评估和应对

10.1 技术风险

SSH连接稳定性
- 风险：网络波动导致连接失败
- 应对：连接池、重试机制、超时设置
性能问题
- 风险：4000+设备查询性能
- 应对：异步处理、分批查询、缓存优化
安全性
- 风险：SSH凭证存储安全
- 应对：加密存储、访问控制、审计日志

10.2 业务风险

数据准确性
- 风险：设备状态误判
- 应对：多重验证、人工复核机制
用户接受度
- 风险：操作复杂度过高
- 应对：用户培训、简化流程、良好UI

十一、总结

本系统设计基于实际业务需求，采用现代化的技术栈和架构，具备良好的扩展性和维护性。通过Casdoor集成实现统一认证，基于RBAC的权限管理系统支持复杂的权限控制需求，Docker化部署确保环境一致性。

系统将分阶段实施，优先保证核心功能的稳定运行，逐步扩展高级功能。建议在开发过程中保持与业务人员的密切沟通，及时调整需求。

文档版本: v1.0 最后更新: 2026年4月1日 下次评审: 2026年4月15日

13 KiB Raw Blame History Unescape Escape