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