Hertz System 文档

Appearance

后端完整文档（Hertz Server Django） ​

1. 项目简介 ​

  • 后端采用 Django + Django REST Framework + Channels/Daphne，提供 REST API 与 WebSocket 实时通信。
  • 模块化设计涵盖认证与权限、验证码、通知公告、日志、知识库、系统监控、AI 对话、代码生成、Sklearn 推理、语义分割、YOLO 检测与训练等。
  • YOLO 能力完善：hertz_studio_django_yolo（检测、模型与数据集管理、ONNX 导出）与 hertz_studio_django_yolo_train（训练任务调度与日志管理）。

2. 环境要求（系统与依赖） ​

  • 操作系统：Windows / Linux / macOS
  • Python：3.8+（推荐 3.12.3）
  • 数据库：SQLite（开发）或 MySQL 5.7+（生产）
  • 缓存与会话：Redis 5.0+
  • 其他：Git、可选 Node.js 18+（前端）
  • 主要后端依赖（节选，详见 requirements.txt）：
    • Django==5.2.6、djangorestframework==3.14.0、channels==4.0.0、daphne==4.0.0
    • drf-spectacular（OpenAPI 文档）、django-cors-headers（CORS）
    • redis、django-redis、python-decouple
    • ultralytics（YOLO）、opencv-python、numpy、scikit-learn

3. 下载与目录结构说明 ​

  • 克隆代码：
    • git clone <repository-url>
    • cd yolo
  • 核心后端结构：
    • hertz_server_django/ 主项目配置（settings.py、urls.py、asgi.py、wsgi.py)
    • 应用模块（均已挂载到主路由，参考 hertz_server_django/urls.py:23）：
      • hertz_studio_django_auth/ 认证与权限
      • hertz_studio_django_captcha/ 图形验证码
      • hertz_studio_django_notice/ 通知系统
      • hertz_studio_django_log/ 日志审计
      • hertz_studio_django_wiki/ 知识库管理
      • hertz_studio_django_system_monitor/ 系统监控
      • hertz_studio_django_ai/ AI 对话（Ollama 集成）
      • hertz_studio_django_codegen/ 代码生成（Mako 模板与权限同步）
      • hertz_studio_django_sklearn/ Sklearn 模型推理
      • hertz_studio_django_segmentation/ 语义分割
      • hertz_studio_django_yolo/ YOLO 检测与模型/数据集管理
      • hertz_studio_django_yolo_train/ YOLO 训练任务管理
      • hertz_demo/ 示例与首页
    • 公共工具：hertz_studio_django_utils/（responses、crypto、email、validators、yolo/Train 等）
    • 文档与说明：docs/ 与 shared/
    • 数据库文件（开发）：data/db.sqlite3

4. 创建虚拟环境与安装依赖 ​

  • Python venv：
    • Windows：
      • python -m venv venv
      • venv\Scripts\activate
    • Linux/macOS：
      • python3 -m venv venv
      • source venv/bin/activate
  • 安装依赖：
    • pip install --upgrade pip
    • pip install -r requirements.txt

5. 数据库与环境变量配置 ​

  • 环境变量（.env 示例，请勿暴露真实密钥与密码）：

    • DEBUG=True
    • SECRET_KEY=your-secret-key
    • ALLOWED_HOSTS=localhost,127.0.0.1
    • USE_REDIS_AS_DB=True（开发使用 SQLite + Redis；生产通常 False + MySQL）
    • REDIS_URL=redis://127.0.0.1:6379/0
    • 如使用 MySQL（当 USE_REDIS_AS_DB=False）：
      • DB_NAME=hertz_server
      • DB_USER=root
      • DB_PASSWORD=your_password
      • DB_HOST=localhost
      • DB_PORT=3306
    • 可选：CORS 与邮箱配置（生产环境务必替换为安全凭据）
      • CORS_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
      • EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
      • EMAIL_HOST=smtp.example.com
      • EMAIL_PORT=465
      • EMAIL_USE_SSL=True
      • EMAIL_HOST_USER=your@example.com
      • EMAIL_HOST_PASSWORD=your_app_password
    • 认证白名单（中间件控制，不需要登录的 URL 正则）：
      • NO_AUTH_PATTERNS=^/api/auth/login/?$,^/api/auth/register/?$,^/api/auth/email/code/?$,^/api/auth/send-email-code/?$,^/api/auth/password/reset/?$,^/api/captcha/.*$,^/api/docs/.*$,^/api/redoc/.*$,^/api/schema/.*$,^/admin/.*$,^/static/.*$,^/media/.*$,^/demo/.*$,^/websocket/.*$,^/api/system/.*$

  • MySQL 初始化：

    • CREATE DATABASE hertz_server CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
    • CREATE USER 'Hertz_user'@'localhost' IDENTIFIED BY 'your_password';
    • GRANT ALL PRIVILEGES ON hertz_server.* TO 'Hertz_user'@'localhost';
    • FLUSH PRIVILEGES;

6. Redis 配置 ​

  • 基本配置（redis.conf）：
    • bind 127.0.0.1
    • port 6379
    • maxmemory 256mb
    • maxmemory-policy allkeys-lru
  • 连接测试：redis-cli ping
  • 生产部署建议设置 requirepass 并限制绑定地址

7. 启动服务 ​

  • 推荐方式（自动迁移与初始化、支持热重启）：
    • python start_server.py
  • 开发模式：
    • python manage.py runserver 0.0.0.0:8000
  • ASGI（生产，示例）：
    • daphne -b 0.0.0.0 -p 8000 hertz_server_django.asgi:application
  • 访问：
    • 后端 API 前缀：/api/
    • YOLO 检测：/api/yolo/
    • YOLO 训练：/api/yolo/train/
    • WebSocket：按各模块的 routing.py 配置路径
    • API 文档：/api/docs/（Swagger）、/api/redoc/、/api/schema/（OpenAPI JSON）

8. 常见问题说明 ​

  • Redis 连接错误：确认服务运行；或在 .env 临时设置 USE_REDIS_AS_DB=True，并检查 REDIS_URL。
  • 端口占用：更换端口（如 :8080），或结束占用进程。
  • 菜单/权限缺失：运行 python start_server.py 同步；清理前端缓存后重新登录。
  • WebSocket 握手失败：反向代理需保留 Upgrade 与 Connection 头；ALLOWED_HOSTS 包含前端域名。
  • 跨域或 404：前端 VITE_API_BASE_URL 指向后端 /api/ 前缀，后端启用 CORS 或同域代理。
  • YOLO 训练性能：优先使用 GPU；降低图像分辨率；确认 ultralytics 安装。
  • MySQL 中文乱码：数据库与表使用 utf8mb4_unicode_ci。
  • 热重启频繁：调整文件监听范围；忽略训练输出目录（例如在 .gitignore 中忽略 hertz_studio_django_utils/yolo/Train/runs/）。

9. 项目结构及运行流程说明 ​

  • 主路由：在 hertz_server_django/urls.py:23-71 中挂载各应用路由（例如 path('api/yolo/train/', include('hertz_studio_django_yolo_train.urls'))）。
  • 统一响应：hertz_studio_django_utils/responses/HertzResponse.py:11 提供统一 success/code/message/data 格式。
  • 认证逻辑：hertz_studio_django_auth/utils/middleware/auth_middleware.py:8 自定义 AuthMiddleware + JWT；白名单由 NO_AUTH_PATTERNS 控制。
  • YOLO 检测流程（简要）：
    • 前端上传文件或提供路径 → 后端 hertz_studio_django_yolo/views.py 处理 → 生成检测结果与历史记录 → 可选告警推送与 ONNX 导出。
  • YOLO 训练流程（简要）：
    • 获取训练选项：GET /api/yolo/train/options/（数据集列表、版本与可用权重尺寸）。
    • 创建训练：POST /api/yolo/train/jobs/start/ → 创建 TrainingJob → training_manager.start_job_async 异步执行。
    • 查看任务与日志：GET /api/yolo/train/jobs/、GET /api/yolo/train/jobs/{pk}/、GET /api/yolo/train/jobs/{pk}/logs/?offset=0&max=65536。
    • 取消与下载：POST /api/yolo/train/jobs/{pk}/cancel/、GET /api/yolo/train/jobs/{pk}/download/。
    • 删除任务：POST /api/yolo/train/jobs/{pk}/delete/。
  • API 文档：drf-spectacular（配置参考 hertz_server_django/settings.py 中 SPECTACULAR_SETTINGS），入口见 hertz_server_django/urls.py:68-70。
  • 静态与媒体：开发环境下由 hertz_server_django/urls.py:73-76 提供；生产建议使用反向代理与静态文件收集。
  • CORS：请检查 django-cors-headers 中间件与 CORS_ALLOWED_ORIGINS、CORS_ALLOW_ALL_ORIGINS 的配置（见 hertz_server_django/settings.py）。