Hertz System 文档

Appearance

后端项目初始化及运行 ​

本页以 Windows 环境下的后端部署与运行 为主线，介绍从环境准备、机器码激活、依赖安装、Django 配置到服务启动与排错的完整流程。

系统要求 ​

操作系统： Windows 10 / 11（64 位）

Python 版本： 3.10 及以上（推荐 3.12.3）

数据库： SQLite（开发环境）或 MySQL 5.7+（生产环境，按需使用）

缓存： Redis 5.0+（可选，但推荐开启）

可选组件： ffmpeg（用于视频检测结果等多媒体能力）

快速开始（开发环境，Windows） ​

1. 克隆项目代码 ​

bash
git clone <HzGit 仓库地址，例如 http://hzgit.hzsystems.cn/hertz_django_studio/hertz_django>
cd hertz_django

仓库地址以实际项目为准，上面仅为示例。

2. 创建虚拟环境并安装依赖 ​

bash
# 创建虚拟环境并激活（Windows）
python -m venv venv
venv\Scripts\activate

# 升级 pip 并安装依赖（使用公司私有 PyPI 源）
python -m pip install --upgrade pip
pip install -r requirements.txt -i https://<username>:<password>@hzpypi.hzsystems.cn/simple/

用户名与密码加官网群获取。

3. 获取机器码并在激活系统登记 ​

bash
python get_machine_code.py

根据命令行输出，复制形如 HERTZ_STUDIO_XXXXXXXXXXXXXXXX 的机器码。

请将机器码发送给系统管理员，由管理员在激活系统中登记并为本机开通访问权限。普通用户无需直接登录激活后台。

4. （可选）按需安装功能插件库 ​

如果只启用部分功能模块，可以单独安装对应后端库，例如：

bash
pip install hertz-studio-django-yolo -i https://<username>:<password>@hzpypi.hzsystems.cn/simple/

5. 配置 Django 插件（按需） ​

在 hertz_server_django/settings.py 中，将需要启用的 App 加入 INSTALLED_APPS，例如：

python
INSTALLED_APPS += [
    "hertz_ai_chat_assistant",
    "hertz_knowledge_articles",
    # 其他按需启用的插件 App
]

示意：

在 settings.py 中启用插件 App

在 hertz_server_django/urls.py 中，为每个插件配置接口前缀，例如：

python
from django.urls import include, path

urlpatterns = [
    # ...
    path("api/xxx/", include("hertz_studio_django_xxx.urls")),
]

示意：

在 urls.py 中为插件配置 API 路由

6. 启动服务 ​

推荐使用启动脚本（会自动迁移数据库并完成初始化）：

bash
python start_server.py --port 8000

启动成功后，可通过以下地址访问：

  • 后端站点：http://127.0.0.1:8000/
  • WebSocket：ws://127.0.0.1:8000/ws/

首次启动自动执行的操作 ​

首次运行 start_server.py 时会自动完成一系列初始化工作（无需手动执行）：

  • 扫描并注册新应用到 INSTALLED_APPS 与 urls.py。
  • 自动执行数据库迁移命令：
    • python manage.py makemigrations
    • python manage.py migrate
  • 初始化基础数据：
    • 超级管理员账号
    • 部门
    • 菜单
    • 角色等基础数据
  • 生成菜单生成器工具 generate_menu.py。
  • 启动 daphne，并开启代码变更监听，实现热重启。

如果数据库连接、Redis 等配置不正确，首次启动可能失败，可结合报错信息参考下文“问题排查”小节。

默认账号 ​

系统首次初始化后，会创建以下默认账号（仅用于示例与快速体验）：

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

建议在生产环境中登录后 尽快修改默认密码，并根据实际需要新建正式账号与角色。

问题排查 ​

1）提示 daphne 或 watchdog 未安装 ​

如果启动脚本提示缺少 daphne 或 watchdog 相关模块，可在激活的虚拟环境中执行：

bash
pip install daphne watchdog -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后重新运行：

bash
python start_server.py --port 8000

2）Redis 未运行或连接失败 ​

  • 确认本地 Redis 服务已正确安装并启动（默认端口 6379）。
  • 如果使用远程 Redis，请在项目配置（如 .env 或 settings.py）中修改 REDIS_URL，例如：
env
REDIS_URL=redis://username:password@your_redis_host:6379/0

如启动日志中出现 ConnectionRefusedError 或 redis.exceptions.*，通常与 Redis 配置或网络连接有关。

3）视频检测结果无法展示 ​

若视频检测结果页面无画面或报错，一般是因为本地未配置好 ffmpeg 环境。

ffmpeg 压缩包所在位置

完成配置并重启命令行窗口后，再次启动服务即可。

项目结构概览 ​

常用目录与文件说明如下（以后端项目根目录为基准）：

  • 核心配置
    • hertz_server_django/settings.py
    • hertz_server_django/urls.py
  • 启动脚本
    • start_server.py
  • 依赖清单
    • requirements.txt
  • 静态资源
    • static/
  • 媒体资源
    • media/

不同团队可以根据需要扩展如 apps/、logs/ 等目录，以便更好地组织业务代码与日志。

快速启动（推荐流程） ​

本节为常用开发环境的一键流程汇总，方便新人快速上手：

  1. 创建并激活虚拟环境（可选但推荐）

    bash
    python -m venv venv
venv\Scripts\activate

  2. 安装依赖

    bash
    pip install -r requirements.txt -i https://<username>:<password>@hzpypi.hzsystems.cn/simple/

  3. 获取机器码并在激活系统中登记

    bash
    python get_machine_code.py

    将输出的机器码发送给系统管理员，由管理员在激活系统中完成登记和授权。

  4. 按需启用插件

    • 在 settings.py 的 INSTALLED_APPS 中注册所需 App。
    • 在 urls.py 中配置对应接口前缀路由。

  5. 启动服务并验证

    bash
    python start_server.py --port 8000

    浏览器访问：http://127.0.0.1:8000/，确认登录与基础功能可正常使用。