Hertz System 文档

Appearance

常见问题 ​

收集了在本地开发与生产部署 Hertz System 过程中最容易遇到的一些问题。若未覆盖你的场景，可以结合《后端项目部署及运行》《后端总体文档》《Docker 部署》等章节排查。

一、安装与环境相关 ​

Q1：安装依赖时提示权限不足或全局 Python 被污染？ ​

**A：**请务必使用虚拟环境或 Conda 环境隔离依赖：

bash
# venv 方式（推荐）
python -m venv venv
venv\Scripts\activate        # Windows
# 或
source venv/bin/activate      # Linux / macOS

pip install --upgrade pip
pip install -r requirements.txt

Q2：启动后端时报数据库连接错误（MySQL 相关）？ ​

请依次检查：

  • .env 中是否已正确设置：
    • USE_REDIS_AS_DB=False
    • DB_NAME=hertz_server
    • DB_USER / DB_PASSWORD / DB_HOST / DB_PORT
  • MySQL 是否已创建对应库与用户（参考《后端总体文档》中的 MySQL 初始化脚本）。
  • 防火墙或云安全组是否放行了 3306 端口（如数据库在独立主机上）。

Q3：Redis 相关报错（redis.exceptions.ConnectionError 等）如何处理？ ​

  • 开发环境：
    • 确认本机 Redis 已启动：redis-cli ping 应返回 PONG。
    • 检查 .env 中 REDIS_URL 与实际端口/密码是否一致。
  • 若暂时不想安装 Redis，可在开发环境将 USE_REDIS_AS_DB=True 配合 SQLite 使用，或根据实际配置调整。

二、运行与启动相关 ​

Q4：python start_server.py 或 runserver 提示端口被占用？ ​

  • 换一个端口，例如：
bash
python manage.py runserver 0.0.0.0:8080
  • 或查找并停止占用 8000 端口的进程：
bash
# Linux
sudo lsof -i:8000

# Windows（PowerShell）
netstat -ano | findstr 8000

Q5：启动后访问 /api/ 一直 404？ ​

  • 确认启动命令无报错，且 start_server.py 已正确完成迁移与初始化。
  • 确认 hertz_server_django/urls.py 中已挂载各模块路由（参考《后端总体文档》“项目结构及运行流程说明”）。
  • 若通过 Nginx / Docker 访问，检查反向代理或端口映射是否指向了 8000 端口。

三、功能与权限相关 ​

Q6：登录后部分菜单/页面缺失？ ​

  • 首次部署建议执行：python start_server.py，以同步菜单与基础权限配置。
  • 使用默认超级管理员账号 hertz / hertz 登录，检查角色是否具备对应菜单权限。
  • 若是新加模块，请确认：
    • 后端已生成对应菜单记录；
    • 前端已在 admin_menu.ts / user_menu_ai.ts 中登记路由与菜单。

Q7：AI 助手无法使用或报模型相关错误？ ​

  • 确认 Ollama 或对应大模型服务已在后端服务器上启动。
  • 检查 .env 或后端配置中的模型地址、API Key 等是否正确。
  • 通过后端 AI 模块的测试接口或 curl 命令，单独验证大模型可用性。

Q8：YOLO 检测/训练性能较差或任务失败？ ​

  • 优先在具备 GPU 的环境中部署 YOLO 训练模块，并确认 ultralytics 能识别 GPU。
  • 适当降低输入图像分辨率、批大小等参数。
  • 确认数据集结构、标注格式与后端 hertz_studio_django_yolo 模块要求一致。

四、部署与前端联调相关 ​

Q9：前端接口报跨域（CORS）或始终 404？ ​

  • 开发环境：
    • VITE_API_BASE_URL 应指向后端基础地址（不包含 /api），如：http://127.0.0.1:8000。
    • Vite 代理或 Axios 会在此基础上追加 /api/...。
  • 生产环境：
    • 后端需启用 django-cors-headers，并在 .env 中配置 CORS_ALLOWED_ORIGINS。
    • 或使用 Nginx 将 /api/ 代理到后端，此时前端只需访问同域的 /api/...。

Q10：WebSocket 握手失败（实时检测 / 系统监控无数据）？ ​

  • 确认后端已使用 Daphne 或兼容 ASGI 的服务启动。
  • 反向代理（如 Nginx）必须保留：
    • Upgrade、Connection、Sec-WebSocket-Key 等关键头。
  • 在 .env 中将前端实际访问域名加入 ALLOWED_HOSTS。

五、账号与安全相关 ​

Q11：默认账号是什么？上线时需要注意什么？ ​

  • 初始化后系统会创建：
    • 普通用户：demo / 123456
    • 超级管理员：hertz / hertz
  • 强烈建议上线前：
    • 修改默认密码；
    • 关闭注册入口或接入企业内部认证（如 SSO）。

Q12：如何集成企业内部 SSO 或统一认证？ ​

  • 在 hertz_studio_django_auth 中自定义认证后端或中间件，对接：
    • OAuth2 / OpenID Connect；
    • Casdoor、Keycloak 等现成解决方案。
  • 保留现有 JWT 颁发逻辑，只是将登录入口改为企业认证后的回调。

若以上仍未解决你的问题，建议按照以下顺序排查：

  1. 查看后端日志与前端控制台错误信息；
  2. 对照《后端总体文档》《后端项目部署及运行》检查环境变量与端口；
  3. 在 FAQ 中补充你定位到的新问题，形成团队内部的“问题手册”。