v6ole/H3ConuMS-v2

Fork 0

Files

T

v6ole 381ea7085d 初始化

2026-04-02 23:40:04 +08:00

20 KiB

Raw Blame History

项目结构详细说明

后端目录结构 (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)

# 应用配置
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)

# 应用配置
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. 环境准备

# 克隆项目
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. 数据库初始化

# 创建数据库
createdb h3c_onu_ms

# 运行迁移
cd backend
alembic upgrade head

# 初始化数据
python scripts/init_data.py

3. 启动开发服务

# 启动后端
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): 添加设备导入功能

测试策略

单元测试

# 后端单元测试
cd backend
pytest tests/unit/

# 前端单元测试
cd frontend
npm run test:unit

集成测试

# 后端集成测试
cd backend
pytest tests/integration/

# API测试
pytest tests/api/

端到端测试

# 前端E2E测试
cd frontend
npm run test:e2e

部署流程

开发环境部署

cd deploy
docker-compose -f docker-compose.dev.yml up -d

生产环境部署

# 构建镜像
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

持续集成/持续部署

代码推送到Git仓库
自动运行测试
构建Docker镜像
推送到镜像仓库
部署到服务器
运行健康检查

监控和告警

应用监控

健康检查端点: /health
性能指标: /metrics (Prometheus格式)
请求统计: 中间件记录
错误跟踪: Sentry集成

系统监控

服务器资源使用率
数据库连接池状态
Redis内存使用情况
网络连接状态

告警规则

设备离线率超过阈值
系统资源使用率过高
服务不可用
安全相关事件

安全考虑

数据安全

SSH密码加密存储
数据库连接加密
敏感信息环境变量管理
定期数据备份

应用安全

CSRF保护
XSS防护
SQL注入防护
速率限制
输入验证

访问安全

基于角色的访问控制
会话管理
双因素认证支持
登录尝试限制

性能优化

数据库优化

合理使用索引
查询优化
连接池配置
定期清理历史数据

缓存策略

Redis缓存热点数据
浏览器缓存静态资源
CDN加速前端资源

异步处理

Celery处理耗时任务
WebSocket实时更新
批量操作优化

扩展性设计

水平扩展

无状态API服务
数据库读写分离
Redis集群支持
负载均衡配置

功能扩展

插件化架构设计
模块化代码组织
配置驱动功能开关
API版本管理

维护计划

日常维护

日志监控和分析
数据库备份验证
系统更新和补丁
性能监控和优化

定期维护

每月安全审计
每季度性能评估
每年架构评审
数据归档和清理

文档更新

API变更及时更新文档
部署流程变更记录
故障处理经验总结
用户反馈整理

文档版本: v1.0
最后更新: 2026年4月1日
维护人员: 系统开发团队

20 KiB Raw Blame History

项目结构详细说明

后端目录结构 (backend/)

前端目录结构 (frontend/)

部署目录结构 (deploy/)

文档目录结构 (docs/)

脚本目录结构 (scripts/)

环境变量说明

后端环境变量 (.env)

前端环境变量 (.env)

开发工作流

1. 环境准备

2. 数据库初始化

3. 启动开发服务

4. 访问应用

代码规范

Python代码规范

Vue代码规范

Git提交规范

测试策略

单元测试

集成测试

端到端测试

部署流程

开发环境部署

生产环境部署

持续集成/持续部署

监控和告警

应用监控

系统监控

告警规则

安全考虑

数据安全

应用安全

访问安全

性能优化

数据库优化

缓存策略

异步处理

扩展性设计

水平扩展

功能扩展

维护计划

日常维护

定期维护

文档更新

20 KiB

Raw Blame History