580 lines
20 KiB
Markdown
580 lines
20 KiB
Markdown
# 项目结构详细说明
|
|
|
|
## 后端目录结构 (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日
|
|
**维护人员**: 系统开发团队 |