From 3453441754f2301df1b493d766ad9a497cdde368 Mon Sep 17 00:00:00 2001 From: v6ole Date: Fri, 22 May 2026 08:57:38 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E6=B8=85=E7=90=86=E6=97=A0=E7=94=A8?= =?UTF-8?q?=E6=96=87=E4=BB=B6=E5=B9=B6=E6=9B=B4=E6=96=B0=20CLAUDE.md=20?= =?UTF-8?q?=E8=87=B3=20v0.9.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 清理： - 删除含硬编码敏感信息的脚本（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 --- .gitignore | 3 + CLAUDE.md | 178 ++++++++---- OLT时间同步.md | 21 -- PROJECT_STRUCTURE.md | 580 -------------------------------------- QUICKSTART.md | 39 --- about.md | 37 --- backend/test_parser.py | 30 -- backend/token_jwt_key.pem | 28 -- run_celery.py | 28 -- setup.sh | 31 -- start-backend.sh | 8 - start-celery.sh | 18 -- start-frontend.sh | 7 - 13 files changed, 132 insertions(+), 876 deletions(-) delete mode 100644 OLT时间同步.md delete mode 100644 PROJECT_STRUCTURE.md delete mode 100644 QUICKSTART.md delete mode 100644 about.md delete mode 100644 backend/test_parser.py delete mode 100644 backend/token_jwt_key.pem delete mode 100755 run_celery.py delete mode 100644 setup.sh delete mode 100755 start-backend.sh delete mode 100755 start-celery.sh delete mode 100755 start-frontend.sh diff --git a/.gitignore b/.gitignore index f2b21cf..0464772 100644 --- a/.gitignore +++ b/.gitignore @@ -32,6 +32,9 @@ logs/ *.db *.sqlite +# Keys +*.pem + # Temp /tmp/ *.tmp diff --git a/CLAUDE.md b/CLAUDE.md index d9712a7..1ffce7e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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) ## MCP Tools: code-review-graph diff --git a/OLT时间同步.md b/OLT时间同步.md deleted file mode 100644 index f7a3a1f..0000000 --- a/OLT时间同步.md +++ /dev/null @@ -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行时可能会报错提示“找不到该配置”，直接忽略该报错即可，不影响后续命令执行。 \ No newline at end of file diff --git a/PROJECT_STRUCTURE.md b/PROJECT_STRUCTURE.md deleted file mode 100644 index cf04888..0000000 --- a/PROJECT_STRUCTURE.md +++ /dev/null @@ -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 -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规范 -- 提交信息格式: `(): ` -- 类型: 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日 -**维护人员**: 系统开发团队 \ No newline at end of file diff --git a/QUICKSTART.md b/QUICKSTART.md deleted file mode 100644 index 928fcf7..0000000 --- a/QUICKSTART.md +++ /dev/null @@ -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界面上显示 diff --git a/about.md b/about.md deleted file mode 100644 index 97f4241..0000000 --- a/about.md +++ /dev/null @@ -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 diff --git a/backend/test_parser.py b/backend/test_parser.py deleted file mode 100644 index 1117b7e..0000000 --- a/backend/test_parser.py +++ /dev/null @@ -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}") diff --git a/backend/token_jwt_key.pem b/backend/token_jwt_key.pem deleted file mode 100644 index ab68b12..0000000 --- a/backend/token_jwt_key.pem +++ /dev/null @@ -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----- diff --git a/run_celery.py b/run_celery.py deleted file mode 100755 index ffd0091..0000000 --- a/run_celery.py +++ /dev/null @@ -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']) diff --git a/setup.sh b/setup.sh deleted file mode 100644 index 0776bbc..0000000 --- a/setup.sh +++ /dev/null @@ -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" diff --git a/start-backend.sh b/start-backend.sh deleted file mode 100755 index fed18b1..0000000 --- a/start-backend.sh +++ /dev/null @@ -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 diff --git a/start-celery.sh b/start-celery.sh deleted file mode 100755 index e334829..0000000 --- a/start-celery.sh +++ /dev/null @@ -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 diff --git a/start-frontend.sh b/start-frontend.sh deleted file mode 100755 index 1321913..0000000 --- a/start-frontend.sh +++ /dev/null @@ -1,7 +0,0 @@ -#!/bin/bash -# 启动前端服务 - -echo "启动前端服务..." -cd frontend -npm install -npm run dev