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

初始化

Browse Source
This commit is contained in:
v6ole
2026-04-02 23:40:04 +08:00
commit 381ea7085d
107 changed files with 11858 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
PROJECT_STRUCTURE.md
+580
View File
@@ -0,0 +1,580 @@
# 项目结构详细说明
## 后端目录结构 (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日
**维护人员**: 系统开发团队