H3ConuMS-v2/README.md

# H3C ONU设备管理系统

基于Python FastAPI + Vue 3的H3C OLT设备监控管理系统，用于监控和管理4000+ ONU设备的在线状态。

## 功能特性

### 核心功能
- ✅ H3C OLT设备SSH连接和状态查询
- ✅ ONU设备在线状态监控（4000+设备）
- ✅ Excel数据导入和批量管理
- ✅ 定时自动状态检查（每30分钟）
- ✅ 手动刷新功能（5分钟冷却限制）
- ✅ 90天状态历史记录

### 权限管理
- ✅ Casdoor统一认证集成
- ✅ 基于RBAC的多级权限控制
- ✅ 区域/学校级别的数据隔离
- ✅ 设备信息变更审核流程
- ✅ 用户角色和权限管理

### 界面功能
- ✅ 响应式Web界面
- ✅ 设备列表表格展示
- ✅ 高级筛选和搜索
- ✅ 实时统计图表
- ✅ 设备详情和历史趋势
- ✅ 数据导入和管理界面

## 技术栈

### 后端
- **Python FastAPI** - 高性能异步Web框架
- **PostgreSQL** - 关系型数据库
- **Paramiko** - SSH连接库
- **Celery + Redis** - 异步任务队列
- **Pandas** - Excel数据处理
- **SQLAlchemy** - ORM框架
- **Casdoor SDK** - 统一认证

### 前端
- **Vue 3 + Composition API** - 前端框架
- **Element Plus** - UI组件库
- **Axios** - HTTP客户端
- **Vue Router** - 路由管理
- **Pinia** - 状态管理
- **ECharts** - 图表库

### 部署
- **Docker + Docker Compose** - 容器化部署
- **Nginx** - 反向代理
- **外部PostgreSQL/Redis** - 数据库服务

## 快速开始

### 环境要求
- Docker 20.10+
- Docker Compose 2.0+
- 外部PostgreSQL数据库
- 外部Redis服务
- Casdoor认证服务器

### 配置步骤

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd H3ConuMS2
   ```

2. **配置环境变量**
   ```bash
   cp deploy/.env.example deploy/.env
   # 编辑deploy/.env文件，配置数据库和Casdoor信息
   ```

3. **启动服务**
   ```bash
   cd deploy
   docker-compose up -d
   ```

4. **访问系统**
   - 前端界面: http://localhost:8080
   - API文档: http://localhost:8000/docs
   - 健康检查: http://localhost:8000/health

## 项目结构

```
H3ConuMS2/
├── backend/                    # Python后端代码
│   ├── app/
│   │   ├── api/              # API路由
│   │   ├── core/             # 核心配置
│   │   ├── models/           # 数据模型
│   │   ├── schemas/          # Pydantic模式
│   │   ├── services/         # 业务逻辑
│   │   ├── tasks/            # Celery任务
│   │   └── utils/            # 工具函数
│   ├── alembic/              # 数据库迁移
│   ├── tests/                # 测试代码
│   ├── requirements.txt      # Python依赖
│   └── Dockerfile           # 后端Dockerfile
├── frontend/                  # Vue前端代码
│   ├── public/               # 静态资源
│   ├── src/
│   │   ├── api/              # API调用
│   │   ├── assets/           # 资源文件
│   │   ├── components/       # 组件
│   │   ├── router/           # 路由配置
│   │   ├── stores/           # 状态管理
│   │   ├── views/            # 页面组件
│   │   └── utils/            # 工具函数
│   ├── package.json          # 前端依赖
│   └── Dockerfile           # 前端Dockerfile
├── deploy/                    # 部署配置
│   ├── docker-compose.yml    # Docker编排
│   ├── nginx.conf            # Nginx配置
│   └── .env.example          # 环境变量示例
├── docs/                      # 文档
│   ├── api/                  # API文档
│   ├── deployment/           # 部署文档
│   └── user-guide/           # 用户指南
├── scripts/                   # 脚本文件
│   ├── init-db.sh            # 数据库初始化
│   ├── backup.sh             # 数据备份
│   └── monitor.sh            # 系统监控
└── 系统设计文档.md            # 详细设计文档
```

## 数据库初始化

1. **创建数据库**
   ```sql
   CREATE DATABASE h3c_onu_ms;
   CREATE USER h3c_user WITH PASSWORD 'your_password';
   GRANT ALL PRIVILEGES ON DATABASE h3c_onu_ms TO h3c_user;
   ```

2. **运行迁移**
   ```bash
   cd backend
   alembic upgrade head
   ```

3. **初始化数据**
   ```bash
   python scripts/init_data.py
   ```

## 配置说明

### Casdoor配置
1. 在Casdoor中创建应用
2. 配置回调地址: `http://your-domain/api/auth/callback`
3. 获取Client ID、Client Secret和Certificate
4. 在.env文件中配置Casdoor参数

### OLT设备配置
1. 通过系统界面添加OLT设备
2. 配置SSH连接信息（IP、用户名、密码）
3. 设置插槽命令（如`display onu slot 1`）

### 权限配置
1. 在Casdoor中配置用户角色
2. 在系统中配置角色权限映射
3. 分配用户区域和学校权限

## 开发指南

### 后端开发
```bash
cd backend
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

### 前端开发
```bash
cd frontend
npm install
npm run dev
```

### 测试
```bash
# 后端测试
cd backend
pytest

# 前端测试
cd frontend
npm run test
```

## API文档

启动后端服务后，访问以下地址查看API文档：
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

## 监控和日志

### 健康检查
```
GET /health
```

### 指标监控
```
GET /metrics
```

### 日志查看
```bash
# 查看后端日志
docker-compose logs backend

# 查看Celery日志
docker-compose logs celery-worker

# 查看Nginx日志
docker-compose logs nginx
```

## 故障排除

### 常见问题

1. **SSH连接失败**
   - 检查网络连通性
   - 验证SSH凭证
   - 检查防火墙设置

2. **数据库连接失败**
   - 检查数据库服务状态
   - 验证连接字符串
   - 检查网络权限

3. **Casdoor登录失败**
   - 检查Casdoor服务状态
   - 验证应用配置
   - 检查回调地址配置

### 日志级别
- DEBUG: 开发环境详细日志
- INFO: 生产环境常规日志
- ERROR: 错误信息记录

## 贡献指南

1. Fork项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建Pull Request

## 许可证

本项目采用MIT许可证 - 查看LICENSE文件了解详情。

## 联系方式

- 项目维护者: [Your Name]
- 问题反馈: [GitHub Issues]
- 文档更新: [GitHub Wiki]

## 更新日志

### v1.0.0 (计划中)
- 基础设备监控功能
- Casdoor认证集成
- 权限管理系统
- Docker化部署

---

**重要提示**: 生产环境部署前，请务必修改默认密码和密钥，并配置适当的防火墙规则。