hertz_django/docs/使用手册.md

使用手册

一、环境要求

• Python 3.10+（建议 3.11/3.12）
• 操作系统：Windows（PowerShell）
• 可选：本地 Redis 服务（默认地址 redis://127.0.0.1:6379）

二、依赖安装

• 一次性使用镜像安装：

  在项目根目录终端执行：

  pip install -r requirements.txt -i https://hertz:hertz@hzpypi.hzsystems.cn/simple/

• 注：若提示依赖安装失败，请将机器码保存并联系管理员开通机器码注册

三、启动服务

• 通过脚本启动（支持端口参数）：
  • python start_server.py --port 8000
• 访问地址：
  • http://127.0.0.1:8000/
  • WebSocket：ws://127.0.0.1:8000/ws/
• 首次启动将自动执行：
  • 扫描并注册新应用到 INSTALLED_APPS 与 urls.py（start_server.py:173、start_server.py:98）。
  • 执行 makemigrations 与 migrate（start_server.py:1109）。
  • 初始化超级管理员/部门/菜单/角色等（start_server.py:877）。
  • 创建菜单生成器工具 generate_menu.py（start_server.py:780）。
  • 启动 daphne 并开启热重启监听（start_server.py:1016、start_server.py:1063）。

四、默认账号

• 超级管理员：
  • 用户名：hertz
  • 密码：hertz
• 普通用户
  • 用户名：demo
  • 密码：123456

五、常见配置说明

• CORS：通过 .env 配置 CORS_ALLOWED_ORIGINS 与 CORS_ALLOW_ALL_ORIGINS
• 静态与媒体：
  • 静态：STATICFILES_DIRS = [BASE_DIR / 'static']
  • 媒体：MEDIA_ROOT = BASE_DIR / 'media'（hertz_server_django/settings.py:209-216）。
• WebSocket：使用 channels 与 channels-redis，层配置读取 REDIS_URL（hertz_server_django/settings.py:302-309）。

六、问题排查

• daphne 或 watchdog 未安装：
  • 运行：pip install daphne watchdog -i https://pypi.tuna.tsinghua.edu.cn/simple（start_server.py:1235-1248 有依赖检查）。
• Redis 未运行：
  • 安装并启动 Redis，或调整 REDIS_URL 指向可用实例。

七、项目结构

• 核心配置：hertz_server_django/settings.py、hertz_server_django/urls.py
• 启动脚本：start_server.py
• 依赖清单：requirements.txt
• 静态资源：static/，媒体资源：media/
• 业务模块：hertz_studio_django_* 系列包（鉴权、日志、通知、监控、Wiki、AI、YOLO、代码生成等）。

八、快速启动

• 安装依赖：pip install -r requirements.txt -i https://hertz:hertz@hzpypi.hzsystems.cn/simple/
• 启动服务：python start_server.py --port 8000