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

chore: 清理无用文件并更新 CLAUDE.md 至 v0.9.0

Browse Source 
清理：
- 删除含硬编码敏感信息的脚本（run_celery.py, start-celery.sh）
- 删除冗余开发脚本（setup.sh, start-backend.sh, start-frontend.sh）
- 删除冗余文档（about.md, PROJECT_STRUCTURE.md, QUICKSTART.md, OLT时间同步.md）
- 删除调试文件（backend/test_parser.py）
- 删除 JWT 密钥文件（backend/token_jwt_key.pem）
- .gitignore 添加 *.pem 忽略规则

CLAUDE.md 更新：
- 版本号 v0.8.0 → v0.9.0
- 新增 v0.9.0 功能：操作记录日志、OLT时间同步、IMC集成
- 补全 API 端点文档（从5个分类扩展到13个分类、50+端点）
- 添加 More 分页标记清理经验教训
- 添加提交前清理文件规则
- 更新项目结构和快速启动指南

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
v6ole
2026-05-22 08:57:38 +08:00
parent b5d542a725
commit 3453441754
13 changed files with 132 additions and 876 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+3
View File
@@ -32,6 +32,9 @@ logs/
*.db
*.sqlite
# Keys
*.pem
# Temp
/tmp/
*.tmp
CLAUDE.md
+129 -49
View File
@@ -4,8 +4,8 @@
这是一个基于 Python FastAPI + Vue 3 的 H3C OLT 设备监控管理系统，用于监控 4000+ ONU 设备的在线状态。
**当前版本**: v0.8.0
**开发状态**: 核心功能已完成，权限与运维功能完善中
**当前版本**: v0.9.0
**开发状态**: 核心功能已完成，运维增强功能持续迭代
**已实现功能**：
- ✅ SSH 连接 H3C OLT 设备查询 ONU 状态（支持 More 分页、终端控制字符清理）
@@ -18,7 +18,7 @@
- ✅ OLT 管理（增删改查、批量导入、区域动态同步）
- ✅ OLT 端口管理（查看端口状态、开关端口）
- ✅ 重复 MAC 检测与清除
- ✅ 新设备发现与信息补全
- ✅ 新设备发现与信息补全（扫描发现 → 补全信息 → 入库）
- ✅ 快速扫描（多线程并发）
- ✅ 环路检测
- ✅ 系统设置（管理员可配置检查间隔，显示下次扫描时间/扫描中状态）
@@ -26,6 +26,9 @@
- ✅ 每日状态快照（凌晨1点聚合，用于趋势图性能优化）
- ✅ 审计日志（全量操作记录、筛选查询、CSV 导出）
- ✅ 设备更换记录（MAC 地址更换历史，与库存序列号联动）
- ✅ 操作记录日志（查看指定设备的上下线事件历史）
- ✅ OLT 时间同步（NTP 服务器配置同步到所有 OLT）
- ✅ IMC 网管服务集成（ONU 远程重启、光功率查询）
- ✅ iOS PWA 主屏幕支持（standalone 模式 safe area 适配）
**技术栈**：
@@ -45,15 +48,72 @@
### 设备管理
- `GET /api/devices` - 获取设备列表（分页、筛选）
- `GET /api/devices/{id}` - 获取设备详情
- `PUT /api/devices/{id}` - 更新设备信息
- `GET /api/devices/{id}/events` - 获取设备上下线事件记录
- `POST /api/devices/{id}/reboot` - 远程重启 ONU（IMC）
- `GET /api/devices/{id}/optical-power` - 获取 ONU 光功率（IMC）
### 状态检查
- `POST /api/check/status` - 手动触发状态检查
- `POST /api/check/status` - 手动触发全量状态检查（Celery 异步）
- `GET /api/check/status/{task_id}` - 查询检查任务进度
- `POST /api/check/scan/{olt_id}` - 扫描单台 OLT（预览，不入库）
- `POST /api/check/discover/{olt_id}` - 扫描单台 OLT 并入库新设备
### OLT 管理
- `GET /api/olt/devices` - OLT 设备列表
- `POST /api/olt/devices` - 新增 OLT
- `PUT /api/olt/devices/{id}` - 编辑 OLT
- `DELETE /api/olt/devices/{id}` - 删除 OLT
- `GET /api/olt/regions` - 获取 OLT 区域列表
- `POST /api/olt/quick-scan` - 多线程快速扫描所有 OLT
- `GET /api/olt/ports/{olt_id}` - 获取 OLT 端口状态
- `POST /api/olt/ports/{olt_id}/toggle` - 开关 OLT 端口
- `POST /api/olt/sync-ntp` - 同步 NTP 时间服务器配置
- `POST /api/olt/loopback-detection` - 环路检测
- `GET /api/olt/new-devices` - 获取新发现设备列表
- `PUT /api/olt/new-devices/{id}` - 补全新设备信息
- `DELETE /api/olt/new-devices/{id}` - 忽略新设备
### 数据导入
- `POST /api/import/upload` - 上传并导入 Excel 文件
- `GET /api/import/template` - 下载导入模板
### 统计信息
- `GET /api/stats/summary` - 获取统计摘要（总数、在线、离线）
- `GET /api/stats/summary` - 获取统计摘要
- `GET /api/stats/trend` - 7天趋势数据
- `GET /api/stats/region-distribution` - 区域分布
### 权限管理
- `GET /api/roles` - 角色列表
- `POST /api/roles` - 创建角色
- `PUT /api/roles/{id}` - 编辑角色
- `DELETE /api/roles/{id}` - 删除角色
- `GET /api/permissions` - 权限列表
### 用户管理
- `GET /api/users` - 用户列表
- `PUT /api/users/{id}` - 编辑用户
- `DELETE /api/users/{id}` - 删除用户
### 库存管理
- `GET /api/inventory/materials` - 物料列表
- `POST /api/inventory/materials` - 新增物料
- `GET /api/inventory/serial-devices` - 序列号设备
- `POST /api/inventory/stock-in` - 入库
- `POST /api/inventory/stock-out` - 出库
- `POST /api/inventory/check` - 盘点
### 审计日志
- `GET /api/audit/logs` - 审计日志列表（筛选、分页）
- `GET /api/audit/logs/export` - 导出审计日志 CSV
### 设备更换记录
- `GET /api/devices/{id}/replacements` - 查看设备更换历史
- `GET /api/replacements` - 全量更换记录列表
### 系统设置
- `GET /api/settings` - 获取系统设置
- `PUT /api/settings` - 更新系统设置
### 系统
- `GET /health` - 健康检查
@@ -147,11 +207,18 @@
### 开发规则
#### 提交前清理
- 每次提交前必须清理项目中不需要的文件
- 包括：测试文件（`test_*.py`）、调试脚本、不再使用的 shell 脚本、冗余 markdown 文档
- 检查是否有硬编码的敏感信息（密码、密钥、token）
- 检查 `.gitignore` 是否覆盖了所有不应提交的文件（`*.pem`、`.env`、`__pycache__` 等）
#### 环境配置
- 开发环境使用 `.env.development`
- 生产环境使用 `.env.production`
- 不提交 `.env` 文件到 Git
- 提供 `.env.example` 模板
- 敏感信息（数据库密码、Casdoor 密钥等）仅通过环境变量注入
#### 测试要求
- 核心业务逻辑需要单元测试
@@ -328,6 +395,21 @@ healthcheck:
start_period: 40s
```
### More 分页标记清除不能使用 `[^\n]*` 删除整行
**问题**：`_clean_output` 中 `---- More ----[^\n]*` 会将 `---- More ----` 及其后同行所有内容删除。当 OLT 输出的 More 提示与下一页第一条设备数据出现在同一行时（如 `---- More ----\r\r 1484-778f-aa60 ...`），该设备行会被错误丢弃，导致部分设备扫描不到。
**规则**：仅移除 More 标记文本本身，保留同行后续内容：
```python
# 错误：删除整行
output = re.sub(r'---- More ----[^\n]*', '', output)
# 正确：仅移除标记文本
output = re.sub(r'---- More ----', '', output)
```
此问题在 OLT `172.16.0.18`（大化县新城初中）上发现：93 台设备仅解析出 90 台，丢失 3 台。
---
## 项目结构
@@ -336,27 +418,32 @@ healthcheck:
H3ConuMS2/
├── backend/ # Python 后端
│ ├── app/
│ │ ├── api/ # API 路由
│ │ ├── api/v1/ # API 路由
│ │ ├── core/ # 核心配置
│ │ ├── middleware/ # 中间件（权限、审计）
│ │ ├── models/ # 数据模型
│ │ ├── schemas/ # Pydantic 模式
│ │ ├── services/ # 业务逻辑
│ │ ├── tasks/ # Celery 任务
│ │ └── utils/ # 工具函数
│ │ ├── services/ # 业务逻辑（SSH、IMC、导入等）
│ │ └── tasks/ # Celery 任务
│ ├── alembic/ # 数据库迁移
│ └── tests/ # 测试代码
├── frontend/ # Vue 前端
│ ├── scripts/ # 初始化脚本
│ └── templates/ # Excel 导入模板
├── frontend/ # Vue 3 前端
│ └── src/
│ ├── api/ # API 调用
│ ├── components/ # 组件
│ ├── api/ # API 调用封装
│ ├── components/ # 公共组件
│ ├── composables/ # 组合式函数
│ ├── router/ # 路由
│ ├── stores/ # 状态管理
│ ├── views/ # 页面
│ └── utils/ # 工具函数
│ ├── stores/ # Pinia 状态管理
│ ├── styles/ # 主题样式
│ ├── utils/ # 工具函数
│ └── views/ # 页面组件
├── deploy/ # 部署配置
│ ├── docker-compose.yml
│ └── nginx.conf
└── docs/ # 文档
│ ├── nginx/
│ └── scripts/
├── docs/ # 文档
└── docker-compose.yml # 主部署文件
```
---
@@ -393,44 +480,38 @@ H3ConuMS2/
### 快速启动
**后端**：
**Docker 部署（推荐）**：
```bash
# 1. 配置环境变量
cp backend/.env.example backend/.env
# 编辑 .env 填入实际配置
# 2. 启动所有服务
docker compose up -d
# 3. 初始化数据库
docker compose exec backend python scripts/init_db.py
```
**本地开发**：
```bash
# 后端
cd backend
python -m venv venv
source venv/bin/activate
python -m venv venv && source venv/bin/activate
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
```
npm install && npm run dev
**Celery Worker**：
```bash
# Celery Worker
cd backend
celery -A app.core.celery_app worker --loglevel=info
```
celery -A celery_worker.celery_app worker --loglevel=info
**Celery Beat**：
```bash
# Celery Beat
cd backend
celery -A app.core.celery_app beat --loglevel=info
```
**Docker 部署**：
```bash
# 配置环境变量
cp backend/.env.example backend/.env
# 启动所有服务
docker-compose up -d
# 初始化数据库
docker-compose exec backend python scripts/init_db.py
celery -A celery_worker.celery_app beat --loglevel=info --schedule=/tmp/celerybeat-schedule
```
### 数据库迁移
@@ -438,7 +519,7 @@ docker-compose exec backend python scripts/init_db.py
```bash
# 创建迁移
alembic revision --autogenerate -m "描述"
/home/v6ole/pyproject/H3ConuMS2/CLAUDE.md
# 执行迁移
alembic upgrade head
@@ -488,8 +569,7 @@ alembic downgrade -1
- [Vue 3 文档](https://vuejs.org/)
- [Element Plus 文档](https://element-plus.org/)
- [Casdoor 文档](https://casdoor.org/)
- [项目详细设计](./系统设计文档.md)
- [开发计划](./开发计划.md)
- [现场ONU故障排查指南](./docs/现场ONU故障排查指南.md)
<!-- code-review-graph MCP tools -->
## MCP Tools: code-review-graph
OLT时间同步.md
-21
View File
@@ -1,21 +0,0 @@
H3C OLT 批量配置脚本（直接复制执行）
```
system-view
undo ntp-service unicast-server 172.16.0.254
ntp-service unicast-server 172.16.1.252
clock timezone Beijing add 08:00:00
quit
save force
```
作用说明：
第2行：删掉旧的内网 NTP（172.16.0.254，因为它用的是本地假时间）。
第3行：指向新配好的 Windows 时间服务器（172.16.1.252，它直连国家授时中心）。
第4行：把设备显示时区改成北京时间（东八区），解决时间少8小时的问题。
第6行：强制保存配置，防止重启丢失（加 force 是为了跳过确认提示，方便批量执行）。
验证方法：
全部刷完等大概 1到2分钟后，执行以下两条命令看结果：
display clock
display ntp-service sessions
display clock 必须看到带有 Beijing 字样，且时间与当前实际北京时间一致。
display ntp-service sessions 必须看到 172.16.1.252 前面带有 [12345] 标记，且 offset（偏差）在几毫秒以内。
注意：如果某些 OLT 之前没有配过 172.16.0.254，执行第2行时可能会报错提示“找不到该配置”，直接忽略该报错即可，不影响后续命令执行。
PROJECT_STRUCTURE.md
-580
View File
@@ -1,580 +0,0 @@
# 项目结构详细说明
## 后端目录结构 (backend/)
```
backend/
├── app/ # 主应用目录
│ ├── __init__.py
│ ├── main.py # FastAPI应用入口
│ ├── api/ # API路由
│ │ ├── __init__.py
│ │ ├── v1/ # API版本1
│ │ │ ├── __init__.py
│ │ │ ├── auth.py # 认证相关API
│ │ │ ├── devices.py # 设备管理API
│ │ │ ├── check.py # 状态检查API
│ │ │ ├── stats.py # 统计API
│ │ │ ├── users.py # 用户管理API
│ │ │ ├── import.py # 数据导入API
│ │ │ └── system.py # 系统设置API
│ │ └── dependencies.py # 依赖注入
│ ├── core/ # 核心配置
│ │ ├── __init__.py
│ │ ├── config.py # 应用配置
│ │ ├── security.py # 安全相关
│ │ ├── database.py # 数据库配置
│ │ ├── casdoor.py # Casdoor配置
│ │ └── celery_app.py # Celery配置
│ ├── models/ # SQLAlchemy模型
│ │ ├── __init__.py
│ │ ├── base.py # 基础模型
│ │ ├── device.py # 设备相关模型
│ │ ├── user.py # 用户相关模型
│ │ ├── permission.py # 权限相关模型
│ │ └── history.py # 历史记录模型
│ ├── schemas/ # Pydantic模式
│ │ ├── __init__.py
│ │ ├── device.py # 设备模式
│ │ ├── user.py # 用户模式
│ │ ├── auth.py # 认证模式
│ │ └── common.py # 通用模式
│ ├── services/ # 业务逻辑服务
│ │ ├── __init__.py
│ │ ├── device_service.py # 设备服务
│ │ ├── ssh_service.py # SSH连接服务
│ │ ├── check_service.py # 状态检查服务
│ │ ├── import_service.py # 数据导入服务
│ │ ├── user_service.py # 用户服务
│ │ ├── permission_service.py # 权限服务
│ │ └── casdoor_service.py # Casdoor服务
│ ├── tasks/ # Celery任务
│ │ ├── __init__.py
│ │ ├── check_tasks.py # 状态检查任务
│ │ ├── import_tasks.py # 数据导入任务
│ │ └── notification_tasks.py # 通知任务
│ ├── utils/ # 工具函数
│ │ ├── __init__.py
│ │ ├── excel_parser.py # Excel解析工具
│ │ ├── ssh_utils.py # SSH工具函数
│ │ ├── validators.py # 数据验证
│ │ ├── encryption.py # 加密工具
│ │ └── logger.py # 日志配置
│ └── middleware/ # 中间件
│ ├── __init__.py
│ ├── auth_middleware.py # 认证中间件
│ ├── permission_middleware.py # 权限中间件
│ └── logging_middleware.py # 日志中间件
├── alembic/ # 数据库迁移
│ ├── versions/ # 迁移版本
│ ├── env.py
│ └── alembic.ini
├── tests/ # 测试代码
│ ├── __init__.py
│ ├── conftest.py # 测试配置
│ ├── test_api/ # API测试
│ ├── test_services/ # 服务测试
│ └── test_utils/ # 工具测试
├── scripts/ # 脚本文件
│ ├── init_db.py # 数据库初始化
│ ├── create_admin.py # 创建管理员
│ └── backup_data.py # 数据备份
├── requirements/ # 依赖管理
│ ├── base.txt # 基础依赖
│ ├── dev.txt # 开发依赖
│ └── prod.txt # 生产依赖
├── logs/ # 日志目录
├── static/ # 静态文件
├── Dockerfile # Docker构建文件
├── docker-entrypoint.sh # Docker入口脚本
├── requirements.txt # 依赖文件
├── .env.example # 环境变量示例
└── pyproject.toml # Python项目配置
```
## 前端目录结构 (frontend/)
```
frontend/
├── public/ # 静态资源
│ ├── index.html # 主HTML文件
│ ├── favicon.ico # 网站图标
│ └── robots.txt # 搜索引擎配置
├── src/ # 源代码
│ ├── main.js # 应用入口
│ ├── App.vue # 根组件
│ ├── api/ # API调用
│ │ ├── index.js # API配置
│ │ ├── auth.js # 认证API
│ │ ├── device.js # 设备API
│ │ ├── check.js # 状态检查API
│ │ ├── user.js # 用户API
│ │ └── import.js # 数据导入API
│ ├── assets/ # 资源文件
│ │ ├── css/ # 样式文件
│ │ │ ├── main.css # 主样式
│ │ │ ├── variables.css # CSS变量
│ │ │ └── components.css # 组件样式
│ │ └── images/ # 图片资源
│ ├── components/ # 公共组件
│ │ ├── common/ # 通用组件
│ │ │ ├── Layout/ # 布局组件
│ │ │ │ ├── AppLayout.vue
│ │ │ │ ├── Header.vue
│ │ │ │ ├── Sidebar.vue
│ │ │ │ └── Footer.vue
│ │ │ ├── Table/ # 表格组件
│ │ │ │ ├── DataTable.vue
│ │ │ │ └── Pagination.vue
│ │ │ ├── Form/ # 表单组件
│ │ │ │ ├── SearchForm.vue
│ │ │ │ └── FilterForm.vue
│ │ │ ├── Chart/ # 图表组件
│ │ │ │ ├── StatusChart.vue
│ │ │ │ └── TrendChart.vue
│ │ │ └── Dialog/ # 对话框组件
│ │ │ ├── ConfirmDialog.vue
│ │ │ └── ImportDialog.vue
│ │ └── business/ # 业务组件
│ │ ├── Device/ # 设备相关组件
│ │ ├── User/ # 用户相关组件
│ │ └── System/ # 系统相关组件
│ ├── router/ # 路由配置
│ │ ├── index.js # 路由主文件
│ │ ├── routes.js # 路由定义
│ │ └── guards.js # 路由守卫
│ ├── stores/ # 状态管理 (Pinia)
│ │ ├── index.js # Store配置
│ │ ├── auth.js # 认证状态
│ │ ├── device.js # 设备状态
│ │ ├── user.js # 用户状态
│ │ └── system.js # 系统状态
│ ├── views/ # 页面组件
│ │ ├── Auth/ # 认证页面
│ │ │ ├── Login.vue # 登录页面
│ │ │ └── Callback.vue # 回调页面
│ │ ├── Dashboard/ # 仪表板
│ │ │ └── index.vue # 仪表板主页
│ │ ├── Device/ # 设备管理
│ │ │ ├── List.vue # 设备列表
│ │ │ ├── Detail.vue # 设备详情
│ │ │ └── Import.vue # 数据导入
│ │ ├── Check/ # 状态检查
│ │ │ ├── Status.vue # 状态页面
│ │ │ └── History.vue # 检查历史
│ │ ├── User/ # 用户管理
│ │ │ ├── List.vue # 用户列表
│ │ │ ├── Profile.vue # 用户资料
│ │ │ └── Permission.vue # 权限管理
│ │ ├── System/ # 系统设置
│ │ │ ├── OltConfig.vue # OLT配置
│ │ │ ├── TaskConfig.vue # 任务配置
│ │ │ └── Audit.vue # 审核中心
│ │ └── Error/ # 错误页面
│ │ ├── 404.vue # 404页面
│ │ └── 500.vue # 500页面
│ ├── utils/ # 工具函数
│ │ ├── auth.js # 认证工具
│ │ ├── request.js # 请求工具
│ │ ├── permission.js # 权限工具
│ │ ├── format.js # 格式化工具
│ │ ├── validate.js # 验证工具
│ │ └── storage.js # 存储工具
│ ├── directives/ # 自定义指令
│ │ ├── permission.js # 权限指令
│ │ └── loading.js # 加载指令
│ └── plugins/ # 插件
│ ├── element-plus.js # Element Plus插件
│ └── echarts.js # ECharts插件
├── tests/ # 测试文件
│ ├── unit/ # 单元测试
│ └── e2e/ # 端到端测试
├── .env.development # 开发环境变量
├── .env.production # 生产环境变量
├── .env.example # 环境变量示例
├── package.json # 项目配置
├── package-lock.json # 依赖锁文件
├── vite.config.js # Vite配置
├── index.html # HTML入口
└── Dockerfile # Docker构建文件
```
## 部署目录结构 (deploy/)
```
deploy/
├── docker-compose.yml # Docker Compose配置
├── docker-compose.dev.yml # 开发环境配置
├── docker-compose.prod.yml # 生产环境配置
├── nginx/ # Nginx配置
│ ├── nginx.conf # 主配置文件
│ ├── conf.d/ # 站点配置
│ │ └── h3c-onu-ms.conf # 应用配置
│ └── ssl/ # SSL证书
├── scripts/ # 部署脚本
│ ├── deploy.sh # 部署脚本
│ ├── backup.sh # 备份脚本
│ ├── restore.sh # 恢复脚本
│ └── monitor.sh # 监控脚本
├── config/ # 配置文件
│ ├── backend.env # 后端环境变量
│ ├── frontend.env # 前端环境变量
│ └── celery.env # Celery环境变量
└── .env.example # 环境变量示例
```
## 文档目录结构 (docs/)
```
docs/
├── api/ # API文档
│ ├── overview.md # API概述
│ ├── auth.md # 认证API文档
│ ├── device.md # 设备API文档
│ ├── check.md # 状态检查API文档
│ └── user.md # 用户API文档
├── deployment/ # 部署文档
│ ├── requirements.md # 环境要求
│ ├── installation.md # 安装指南
│ ├── configuration.md # 配置说明
│ ├── docker.md # Docker部署
│ └── troubleshooting.md # 故障排除
├── user-guide/ # 用户指南
│ ├── getting-started.md # 快速开始
│ ├── device-management.md # 设备管理指南
│ ├── data-import.md # 数据导入指南
│ ├── permission-guide.md # 权限管理指南
│ └── faq.md # 常见问题
├── development/ # 开发文档
│ ├── setup.md # 开发环境搭建
│ ├── architecture.md # 架构说明
│ ├── coding-standards.md # 编码规范
│ ├── testing.md # 测试指南
│ └── contributing.md # 贡献指南
└── images/ # 文档图片
```
## 脚本目录结构 (scripts/)
```
scripts/
├── database/ # 数据库脚本
│ ├── init.sql # 初始化SQL
│ ├── backup.sh # 数据库备份
│ ├── restore.sh # 数据库恢复
│ └── migrate.sh # 迁移脚本
├── monitoring/ # 监控脚本
│ ├── health-check.sh # 健康检查
│ ├── log-rotate.sh # 日志轮转
│ └── alert.sh # 告警脚本
├── deployment/ # 部署脚本
│ ├── build.sh # 构建脚本
│ ├── deploy.sh # 部署脚本
│ └── rollback.sh # 回滚脚本
└── utils/ # 工具脚本
├── cleanup.sh # 清理脚本
├── generate-cert.sh # 证书生成
└── update-config.sh # 配置更新
```
## 环境变量说明
### 后端环境变量 (.env)
```bash
# 应用配置
APP_NAME=H3C-ONU-MS
APP_ENV=production
DEBUG=false
SECRET_KEY=your-secret-key-here
# 数据库配置
DATABASE_URL=postgresql://user:password@host:5432/dbname
DATABASE_POOL_SIZE=20
DATABASE_MAX_OVERFLOW=40
# Redis配置
REDIS_URL=redis://host:6379/0
REDIS_POOL_SIZE=10
# 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
# SSH配置
SSH_TIMEOUT=30
SSH_MAX_CONNECTIONS=10
SSH_RETRY_COUNT=3
# 任务配置
CHECK_INTERVAL=1800 # 30分钟（秒）
MANUAL_COOLDOWN=300 # 5分钟（秒）
HISTORY_RETENTION=90 # 90天
# 日志配置
LOG_LEVEL=INFO
LOG_FILE=/app/logs/app.log
LOG_ROTATION=10MB
LOG_RETENTION=30
```
### 前端环境变量 (.env)
```bash
# 应用配置
VITE_APP_TITLE=H3C ONU设备管理系统
VITE_APP_VERSION=1.0.0
# API配置
VITE_API_BASE_URL=http://localhost:8000
VITE_API_TIMEOUT=30000
# Casdoor配置
VITE_CASDOOR_ENDPOINT=https://casdoor.example.com
VITE_CASDOOR_CLIENT_ID=your_client_id
VITE_CASDOOR_ORG_NAME=your_org
VITE_CASDOOR_APP_NAME=h3c-onu-ms
# 功能开关
VITE_ENABLE_SSO=true
VITE_ENABLE_WEBSOCKET=true
VITE_ENABLE_ANALYTICS=false
```
## 开发工作流
### 1. 环境准备
```bash
# 克隆项目
git clone <repository-url>
cd H3ConuMS2
# 后端环境
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements/dev.txt
# 前端环境
cd ../frontend
npm install
```
### 2. 数据库初始化
```bash
# 创建数据库
createdb h3c_onu_ms
# 运行迁移
cd backend
alembic upgrade head
# 初始化数据
python scripts/init_data.py
```
### 3. 启动开发服务
```bash
# 启动后端
cd backend
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
# 启动前端（新终端）
cd frontend
npm run dev
# 启动Celery Worker（新终端）
cd backend
celery -A app.core.celery_app worker --loglevel=info
# 启动Celery Beat（新终端）
cd backend
celery -A app.core.celery_app beat --loglevel=info
```
### 4. 访问应用
- 前端开发服务器: http://localhost:5173
- 后端API服务器: http://localhost:8000
- API文档: http://localhost:8000/docs
- 管理界面: http://localhost:8000/admin
## 代码规范
### Python代码规范
- 遵循PEP 8规范
- 使用Black进行代码格式化
- 使用isort进行导入排序
- 使用Flake8进行代码检查
- 使用mypy进行类型检查
### Vue代码规范
- 使用ESLint + Prettier
- 遵循Vue官方风格指南
- 使用TypeScript进行类型检查
- 组件使用PascalCase命名
- 单文件组件结构规范
### Git提交规范
- 使用Conventional Commits规范
- 提交信息格式: `<type>(<scope>): <subject>`
- 类型: feat, fix, docs, style, refactor, test, chore
- 示例: `feat(device): 添加设备导入功能`
## 测试策略
### 单元测试
```bash
# 后端单元测试
cd backend
pytest tests/unit/
# 前端单元测试
cd frontend
npm run test:unit
```
### 集成测试
```bash
# 后端集成测试
cd backend
pytest tests/integration/
# API测试
pytest tests/api/
```
### 端到端测试
```bash
# 前端E2E测试
cd frontend
npm run test:e2e
```
## 部署流程
### 开发环境部署
```bash
cd deploy
docker-compose -f docker-compose.dev.yml up -d
```
### 生产环境部署
```bash
# 构建镜像
docker-compose -f docker-compose.prod.yml build
# 启动服务
docker-compose -f docker-compose.prod.yml up -d
# 查看日志
docker-compose -f docker-compose.prod.yml logs -f
```
### 持续集成/持续部署
1. 代码推送到Git仓库
2. 自动运行测试
3. 构建Docker镜像
4. 推送到镜像仓库
5. 部署到服务器
6. 运行健康检查
## 监控和告警
### 应用监控
- 健康检查端点: `/health`
- 性能指标: `/metrics` (Prometheus格式)
- 请求统计: 中间件记录
- 错误跟踪: Sentry集成
### 系统监控
- 服务器资源使用率
- 数据库连接池状态
- Redis内存使用情况
- 网络连接状态
### 告警规则
- 设备离线率超过阈值
- 系统资源使用率过高
- 服务不可用
- 安全相关事件
## 安全考虑
### 数据安全
- SSH密码加密存储
- 数据库连接加密
- 敏感信息环境变量管理
- 定期数据备份
### 应用安全
- CSRF保护
- XSS防护
- SQL注入防护
- 速率限制
- 输入验证
### 访问安全
- 基于角色的访问控制
- 会话管理
- 双因素认证支持
- 登录尝试限制
## 性能优化
### 数据库优化
- 合理使用索引
- 查询优化
- 连接池配置
- 定期清理历史数据
### 缓存策略
- Redis缓存热点数据
- 浏览器缓存静态资源
- CDN加速前端资源
### 异步处理
- Celery处理耗时任务
- WebSocket实时更新
- 批量操作优化
## 扩展性设计
### 水平扩展
- 无状态API服务
- 数据库读写分离
- Redis集群支持
- 负载均衡配置
### 功能扩展
- 插件化架构设计
- 模块化代码组织
- 配置驱动功能开关
- API版本管理
## 维护计划
### 日常维护
- 日志监控和分析
- 数据库备份验证
- 系统更新和补丁
- 性能监控和优化
### 定期维护
- 每月安全审计
- 每季度性能评估
- 每年架构评审
- 数据归档和清理
## 文档更新
- API变更及时更新文档
- 部署流程变更记录
- 故障处理经验总结
- 用户反馈整理
---
**文档版本**: v1.0
**最后更新**: 2026年4月1日
**维护人员**: 系统开发团队
QUICKSTART.md
-39
View File
@@ -1,39 +0,0 @@
# H3C ONU设备管理系统 - 快速开始
## 项目状态
✅ 第一阶段：基础框架已完成
## 已完成功能
- ✅ 后端 FastAPI 框架
- ✅ 前端 Vue 3 框架
- ✅ SSH 连接和 ONU 状态解析
- ✅ 数据库模型设计
- ✅ Docker 配置
## 快速启动
### 1. 配置环境变量
```bash
cp backend/.env.example backend/.env
# 编辑 backend/.env 配置数据库等信息
```
### 2. 启动后端
```bash
./start-backend.sh
```
### 3. 启动前端
```bash
./start-frontend.sh
```
### 4. 访问系统
- 前端：http://localhost:5173
- 后端 API：http://localhost:8000
- API 文档：http://localhost:8000/docs
## 下一步开发
参考 `开发计划.md` 继续第一阶段第2周任务
1. 定期检测还需要加入环路检测功能，并且将环路的状态记录到数据库中，在OLT界面上显示
about.md
-37
View File
@@ -1,37 +0,0 @@
# H3C ONU 管理系统
H3C ONU 管理系统（H3ConuMS）是一套面向校园网络运维团队的 ONU 设备集中管理平台，支持对接多台 H3C OLT 设备，实现大规模 ONU 的状态监控、信息管理与运维操作。
## 主要功能
**设备监控**
系统通过 SSH 定期轮询 OLT 设备，自动采集所有 ONU 的在线状态、光功率、距离、端口等信息，并以列表和卡片两种视图展示。支持手动触发刷新，状态变化实时可见。
**设备管理**
支持按区域、学校、楼宇、场所类型等维度对 ONU 设备进行分类管理。可通过 Excel 批量导入设备信息，也可在界面中逐条编辑。设备更换时记录完整的 MAC 地址变更历史。
**OLT 管理**
统一管理多台 OLT 设备的连接信息，支持端口级别的设备发现。OLT 扫描到的新设备会进入待入库列表，由运维人员补全信息后正式纳管。
**统计分析**
提供实时在线率统计、7 天趋势折线图、区域分布饼图等可视化报表，帮助运维团队快速掌握全网设备健康状况。
**权限管理**
基于 Casdoor 统一认证，支持管理员、区域管理员、学校管理员、普通用户等多级角色，数据访问范围按角色自动隔离。
**审计日志**
记录所有用户的写操作，包括设备编辑、更换、导入、权限变更等，保留 90 天供追溯查询。
## 技术栈
| 层级 | 技术 |
|------|------|
| 后端 | Python · FastAPI · SQLAlchemy · Celery · Redis |
| 前端 | Vue 3 · Element Plus · ECharts |
| 数据库 | PostgreSQL |
| 认证 | Casdoor（OIDC） |
| 部署 | Docker Compose · Nginx |
## 版本
当前版本：v0.8.0
backend/test_parser.py
-30
View File
@@ -1,30 +0,0 @@
"""测试 ONU 状态解析"""
import re
def parse_onu_status(output: str):
"""解析 ONU 状态"""
devices = {}
lines = output.split('\n')
for line in lines:
mac_match = re.search(r'([0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4})', line, re.IGNORECASE)
if mac_match:
mac = mac_match.group(1).lower()
if 'Up' in line:
devices[mac] = 'online'
elif 'Offline' in line:
devices[mac] = 'offline'
return devices
# 测试数据
test_output = """
1484-7790-5200 12 <1000 Onu1/0/1:1 WA6520H-EGPON/A 106/ Up N/A
1484-7790-4e20 13 <1000 Onu1/0/1:2 WA6520H-EGPON/A 106/ Up N/A
1484-7790-3900 N/A N/A Onu1/0/1:3 N/A N/A Offline N/A
"""
result = parse_onu_status(test_output)
print("解析结果:")
for mac, status in result.items():
print(f" {mac}: {status}")
backend/token_jwt_key.pem
-28
View File
@@ -1,28 +0,0 @@
-----BEGIN CERTIFICATE-----
MIIE2TCCAsGgAwIBAgIDAeJAMA0GCSqGSIb3DQEBCwUAMCYxDjAMBgNVBAoTBWFk
bWluMRQwEgYDVQQDDAtjZXJ0X3drMWVlZjAeFw0yNTEyMTAxMDAzMzVaFw00NTEy
MTAxMDAzMzVaMCYxDjAMBgNVBAoTBWFkbWluMRQwEgYDVQQDDAtjZXJ0X3drMWVl
ZjCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAK78ajnNnwnutdZ48l92
hmqa2c8lP1IcpyB7CYVTKurQxSz5iQorYOVhR1UzluSpU8yiPPeFyTRD0pH+DzqG
otc+Alvxnka5DfP1z/P0asogkALJXouRR+YtUY6i1oo5tKlDbIGJNO2aQcOOak9b
YoqSRd9y/pq/bPjte7oww29hGQc03LgbNXmIb9n5NGznWCte1c88NUrTz9Dlpn2H
r3ncOmHpqpzg5NtXughnHsF4YCF+pPIgWlC0C6MtKk0fuJysCY5wpuA620pGL4zO
6QFv920MiWsdVWxcNo0aNQkXKGjEcy3LraXux2k/sH+E0e3GRXGhWYnkrK7i8kg+
V+Nm1YFgyGbY7V3yZ0mXPxb+iMlIvz885ViGsRnKqlR0pN1v8NbmzXPu9EkAO3wi
T/L4fxnETW1hd/ph+AdQ0jEpeyAMRjcl3kMjauOBqfU/THl7L6aUMXB3d05+JK0Y
uTc1nrZ0Qjh/5EG5XyvRSuKNVxpCB1XcAlAaBTuE5art6jQkCJINvFoOjoHZB65K
HJVvfMtMuVr7dLSbYOPHH6YJB2fUijNKoXnclAbxldX3fEALsC/SW7zMFF+3FThg
Seq3OEpNdbkRlQp5sORHeTkWtMO9A60GHvTqDamIqppC4fk71zIRpmEPlfGsOno5
gNhH8+NKH5Cvmfj4s7/S98D/AgMBAAGjEDAOMAwGA1UdEwEB/wQCMAAwDQYJKoZI
hvcNAQELBQADggIBAJLW6zjDKZdkfq00r88lM1IxaxRWmUEPQjINOa0GZH/DyAtd
fgYf35AN+NDEiIiDnJQTR3N8jbX1JySDClEOzv3wLXRiKhWcX8z4HOoieNmMu9lZ
6pf1lEaMX8WNxB475nfOueEEyHegbsbfpmYM/aVAiSxaKb87if7uDnxJeGqK2Ba0
c3LJnQ+H87gcAb84G78KXn/XwjRtwaf+Gy06EzycEnckEeN0vni0pRdw8coSudcX
726Kb+kZ4961G/XxQx4fKX+E4lXkx1CdxPBAws/uOjfciLnuVdT4yp6URXJKRw+/
R+flPtfvHXNDXB8BHj9ul4UJ4oSHGppx0BR80CmWWNDVdaoO+o0WieFOXG2U2PB+
p2pleJzckTDuOh5wIe2GFj9WKZTIn4S7ZA6hS5j5ea4bOX5m6cxXVaS5FPHHfHcN
FyUOEE4f61tv9omsFyl23YD/gmQzotFY+5YPS8DTb1soSzydKQODCq7SobyK8QFo
3FnOw1cnKuWDZbqkZS6TYHFc3doNaH77bBxgSgIBPlJewd98eZZCv+m8/mCOXCbo
+7HOgmOHJ1cOEtweCtgrCc2VNvV0w6RSwcZ+WmUAZMajvyEqikVVQzR2LtOOhOyr
REkkNRAX3PX69GDQLM9QSgGLv0f6nA5uTX9SFj71Iik6YAuUsvIK6uPpn/2B
-----END CERTIFICATE-----
run_celery.py
-28
View File
@@ -1,28 +0,0 @@
#!/usr/bin/env python
import sys
import os
# 切换到项目根目录
os.chdir('/home/v6ole/pyproject/H3ConuMS2')
# 设置 PYTHONPATH
sys.path.insert(0, '/home/v6ole/pyproject/H3ConuMS2/backend')
# 设置环境变量
os.environ['SECRET_KEY'] = 'your-secret-key-change-this'
os.environ['DATABASE_URL'] = 'postgresql://H3C_onu_ms:nEHBFFpBsJfiZp3N@10.10.10.14:5432/H3C_onu_ms'
os.environ['REDIS_URL'] = 'redis://:redis_c4FFJQ@10.10.10.14:6379'
os.environ['CASDOOR_ENDPOINT'] = 'https://casdoor.dhdx.fun'
os.environ['CASDOOR_CLIENT_ID'] = '2289912424bcea5f9859'
os.environ['CASDOOR_CLIENT_SECRET'] = 'cfa97de106762c8293901a8daef11e04f1b10043'
os.environ['CASDOOR_REDIRECT_URL'] = 'http://10.10.10.14:5173/callback'
os.environ['CASDOOR_ORG_NAME'] = 'dahua'
os.environ['CASDOOR_APP_NAME'] = 'H3ConuMS'
os.environ['CASDOOR_CERTIFICATE'] = 'token_jwt_key.pem'
# 加载 celery app
from celery_worker import celery_app
# 运行 worker
if __name__ == '__main__':
celery_app.worker_main(['worker', '--loglevel=info'])
setup.sh
-31
View File
@@ -1,31 +0,0 @@
#!/bin/bash
# 快速启动脚本
echo "=== H3C ONU 设备管理系统 ==="
echo ""
# 检查虚拟环境
if [ ! -d "backend/venv" ]; then
echo "创建虚拟环境..."
cd backend && python3 -m venv venv && cd ..
fi
# 激活虚拟环境
source backend/venv/bin/activate
# 检查依赖
if ! python -c "import fastapi" 2>/dev/null; then
echo "安装依赖..."
pip install -r backend/requirements.txt
fi
# 初始化数据库
echo "初始化数据库..."
python backend/scripts/init_db.py
echo ""
echo "✅ 初始化完成！"
echo ""
echo "启动服务："
echo " 后端: cd backend && uvicorn app.main:app --reload"
echo " 前端: cd frontend && npm run dev"
start-backend.sh
-8
View File
@@ -1,8 +0,0 @@
#!/bin/bash
# 启动开发环境
echo "启动后端服务..."
cd backend
source venv/bin/activate 2>/dev/null || python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
start-celery.sh
-18
View File
@@ -1,18 +0,0 @@
#!/bin/bash
cd /home/v6ole/pyproject/H3ConuMS2
export PYTHONPATH=/home/v6ole/pyproject/H3ConuMS2/backend
# 设置环境变量
export SECRET_KEY="your-secret-key-change-this"
export DATABASE_URL="postgresql://H3C_onu_ms:nEHBFFpBsJfiZp3N@10.10.10.14:5432/H3C_onu_ms"
export REDIS_URL="redis://:redis_c4FFJQ@10.10.10.14:6379"
export CASDOOR_ENDPOINT="https://casdoor.dhdx.fun"
export CASDOOR_CLIENT_ID="2289912424bcea5f9859"
export CASDOOR_CLIENT_SECRET="cfa97de106762c8293901a8daef11e04f1b10043"
export CASDOOR_REDIRECT_URL="http://10.10.10.14:5173/callback"
export CASDOOR_ORG_NAME="dahua"
export CASDOOR_APP_NAME="H3ConuMS"
export CASDOOR_CERTIFICATE="token_jwt_key.pem"
exec /home/v6ole/pyproject/H3ConuMS2/backend/venv/bin/celery -A celery_worker.celery worker --loglevel=info
start-frontend.sh
-7
View File
@@ -1,7 +0,0 @@
#!/bin/bash
# 启动前端服务
echo "启动前端服务..."
cd frontend
npm install
npm run dev