# cluster_platform

**Repository Path**: yuturuishi/cluster_platform

## Basic Information

- **Project Name**: cluster_platform
- **Description**: 专为视频行为分析系统v5 rebekah（v5.305+）设计的集群管理平台
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 127
- **Forks**: 54
- **Created**: 2024-05-02
- **Last Updated**: 2026-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Python, WebSocket, rebekah, MySQL

## README

# Cluster Platform - 集群管理平台

## 简介
集群管理平台（简称cluster_platform） 专为视频行为分析系统 rebekah（v5.305+）设计的集群管理平台：一个 Web 控制台统一管理多个分布在内网/公网的 rebekah 节点。

**开源**：本项目以 MIT 协议开源，源码托管于 Gitee：<https://gitee.com/yuturuishi/cluster_platform>

**核心机制**：节点主动通过 WebSocket 连到平台注册，之后平台把所有管理操作封装成命令经同一条 WebSocket 下发、由节点在本地执行后回传结果。平台是纯无状态代理——不直连节点、不存业务数据，因此节点无需暴露任何端口，公网即可管理内网设备。

## 核心特性

- 🔗 **无端口要求**：节点主动外连注册，内网节点零端口暴露
- ⚡ **WebSocket 命令代理**：全部节点操作（增删改查、重启、升级、授权、文件传输）经 WS 通道转发
- 📹 **流媒体集成**：内置 ZLMediaKit，RTSP/HLS/FLV/WebRTC 多协议播放，按需拉起节点推流
- 🎬 **录像回放**：二级时间轴（24h 概览 + 3 分钟切片），录像文件经 WS 分块传输、支持 HTTP Range 拖动
- 💓 **心跳监控**：节点在线状态实时感知，心跳/注册/注册被拒分类型记录（心跳弹框可筛选），断线自动重连重注册
- 🔐 **安全认证**：注册 Token 校验 + 节点版本门槛 + 本地接口 Safe 密钥
- 🔑 **软件授权**：平台一键查看节点机器指纹、下发授权码

## 架构设计

```
┌──────────────────────────────┐
│         公网 cp_server       │
│  Web控制台 / REST / Daphne   │
│  MySQL  ·  ZLMediaKit        │
└──────────────┬───────────────┘
               │ WebSocket /ws/cluster（节点主动连）
┌──────────────┴───────────────┐
│        内网 rebekah 节点      │
│  AI分析 · 视频采集 · ZLM      │
│  ClusterClient(注册/心跳/命令)│
└──────────────────────────────┘
```

```
浏览器 ──HTTP──▶ cp_server ──WS command──▶ 节点本地接口 ──回包──▶ cp_server ──▶ 浏览器
```

## 目录结构

```
cluster_platform/
├── cp_server/               # 平台服务端（Django 5 + Channels）
│   ├── app/                 # 视图 / 模型 / WebSocket消费者 / NodeManager
│   ├── framework/           # Django 配置（settings / asgi / 路由）
│   ├── static/              # 静态资源
│   ├── templates/           # 页面模板
│   ├── config-windows.json  # Windows 配置模板
│   ├── config-linux.json    # Linux 配置模板
│   └── manage.py
├── cp_zlm/                  # 内置流媒体服务器 ZLMediaKit（win/linux-arm 多平台二进制）
├── cluster_platform.sql     # MySQL 建库脚本
└── README.md
```

## 功能一览

**平台管理**：控制面板 · 节点管理（详情/心跳/日志/升级/重启/授权）· 报警管理 · 用户管理 · 在线流 · 平台配置

**节点功能（经 WS 代理到节点本地）**：报警 · 视频 · 布控 · 音频 · 人脸 · 计划任务 · 报警存储 · 算法测试/业务/基础/行为算法 · 大模型 · 录像计划与回放

---

## 快速开始

### 环境要求

- Python 3.10+（Django 5 要求）
- MySQL 5.7+（生产推荐；SQLite 需自行改 settings.py）
- rebekah 节点 v5.305+

### 1. 安装

```bash
cd cp_server
python -m venv venv
venv\Scripts\activate              # Windows
source venv/bin/activate           # Linux
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 2. 数据库

```sql
CREATE DATABASE cluster_platform DEFAULT CHARACTER SET utf8mb4;
-- 然后导入根目录的 cluster_platform.sql
```

数据库连接在 `cp_server/framework/settings.py` 的 `DATABASES` 中修改。

### 3. 配置

将 `config-windows.json` 或 `config-linux.json` 复制为 `config.json`，按需修改（见[配置说明](#配置说明)）。

### 4. 启动

```bash
# ① 启动流媒体服务器（需要视频播放/录像功能时）
# Windows: cp_zlm/bin.x86.windows10/cp_zlm.exe
# Linux x86 / ARM: cp_zlm/bin.x86.gcc9.4 或 bin.arm.gcc9.4 下 ./cp_zlm

# ② 启动平台
cd cp_server
python manage.py runserver 0.0.0.0:9824
```

访问 `http://localhost:9824`，默认账号 `admin` / `admin888`。

---

## 节点接入

在每台 rebekah 节点的 `config.json` 中配置 `clusterServer` 并重启节点：

```json
{
    "clusterServer": {
        "enable": true,
        "address": "ws://平台IP:9824/ws/cluster",
        "token": "与平台 config.json 的 wsToken 一致",
        "timeout": 30,
        "reconnectInterval": 10,
        "heartbeatInterval": 30
    }
}
```

节点启动后自动注册、断线自动重连重注册，平台「平台节点管理」页出现卡片即为接入成功。节点版本低于 5.305 会被拒绝连接。

## 端口说明

| 端口 | 用途 |
|------|------|
| 9824 | 平台 Web + WebSocket（必须对外开放） |
| 9854 | ZLMediaKit RTSP |
| 9826 | ZLMediaKit HTTP（HLS/FLV 播放） |

## 配置说明（cp_server/config.json）

| 键 | 说明 |
|------|------|
| `host` / `adminPort` | 平台访问地址 / 端口 |
| `safe` | 平台 API 安全密钥 |
| `wsToken` | 节点注册令牌，须与节点端 `clusterServer.token` 一致 |
| `mediaRtspPort` / `mediaHttpPort` / `mediaSecret` | ZLMediaKit 对应参数，须与 cp_zlm 配置一致 |
| `uploadDir` / `storageDir` | 上传与存储目录 |
| `oem` | 平台名称 / Logo / 版权信息等品牌定制 |

---

## 技术栈

Django 5.0 · Channels 4.1 · Daphne 4.1 · MySQL/SQLite · ZLMediaKit · Bootstrap + jQuery

## 开源与许可

cluster_platform 以 **MIT 协议**开源，可自由用于学习、二次开发及商业用途，无需授权费用。

- 开源仓库（Gitee）：<https://gitee.com/yuturuishi/cluster_platform>
- 许可证：MIT License（详见仓库根目录 `LICENSE` 文件）

欢迎通过 Gitee Issue / Pull Request 提交问题反馈与改进建议。

## 更新日志

### v1.013 (2026-10-30)

**节点手动同步信息**
- 节点管理页「操作」列新增「同步信息」图标按钮（FA `fa-cloud-download`）
- 节点授权过期 / 换授权码 / 版本变化但**未重启、未重注册**时，点击即经现有 WS 命令通道向节点拉取最新 `discover_info` 并回写平台 DB，无需重启节点即可刷新授权状态、版本、描述等可变字段（心跳只刷新在线状态，旧逻辑下这些信息会永远不变）
- 节点须在线；离线节点提示失败，不影响其余操作
- 复用注册同款字段映射（`NodeManager.update_node_from_discover`），只更新可变字段，不动连接态（`ws_connected` / `client_ip` 等）
- 后端新增 `platform/node/sync`（30s 超时），节点端 `ClusterClient` 新增 `get_node_info` 命令分支（复用 `get_discover_info`）

### v1.012 (2026-09-22)

**生产部署增强**
- 支持 `DEBUG=False` 生产模式正常运行：静态资源改由 WhiteNoise 统一服务（开发/生产模式自动切换配置），关闭 DEBUG 不再出现样式、脚本、图标加载失败
- 部署无新增依赖（whitenoise 原已在 requirements 中），报警图片/视频等动态内容不受影响（仍走 `/storage/access` 直读磁盘）
- 运维须知：`DEBUG=False` 下静态资源在服务启动时建立索引，修改 `static/` 下的 css/js 后**必须重启服务**才能生效；否则响应头 Content-Length 与文件实际大小不一致，轻则拿到旧内容，重则页面永久挂起无法打开

**节点管理页升级**
- 新增列表视图：8 列信息表格（节点/状态/授权状态/版本/系统/网络地址/运行时间/操作），节点数量多时一眼全局，默认列表展示
- 保留原卡片视图，页头分段按钮一键切换；视图偏好存入浏览器 Cookie（1 年有效），下次进入自动按上次选择显示
- 修复图标缺失：项目 Font Awesome 为 4.6.3，替换 3 个高版本才有的图标（重启软件/网络地址/运行时间）

**后台亮色主题 + 移动端自适应**
- 全局配色升级：侧边栏由深色改为亮色（白底 + 浅蓝圆角激活态），顶栏/内容区/表格统一浅色系，风格与 rebekah_admin、rebucca 后台对齐
- 后台支持手机浏览器访问：侧边栏改抽屉式（汉堡按钮 + 半透明遮罩，点菜单项自动收起、Esc 可关），内容区全宽，宽表格横向滑动且单元格不折行，表单与工具条自动堆叠，输入框 16px 避免 iOS 聚焦放大
- 修复移动端此前点汉堡无反应的问题（custom.js 已有抽屉开合逻辑，但遮罩元素与配套样式缺失）
- 新增静态资源 `static/css/cp_admin.css`（模板在 custom.css 之后加载）；登录页同步适配窄屏
- 侧栏当前页高亮修复：点子菜单进入页面后，当前项以「浅蓝底 + 主色文字」胶囊样式标出，所在子菜单自动展开、所属一级菜单同步亮起（URL 带 query 参数同样生效）
- 修复桌面折叠态（70px 图标栏）弹出二级菜单透明的问题：展开态的透明底规则优先级过高压过弹层白底，页面内容透过弹层显示，现恢复为实心白卡 + 阴影

**控制面板细节修复**
- CPU/内存卡片右上角图标改用 Font Awesome 4.6.3 已有字形（`fa-bolt` / `fa-hdd-o`），原 `fa-microchip`、`fa-memory` 为高版本才有的图标，渲染为空白


### v1.011 (2026-09)

**远程运维增强**
- 节点升级改为指令下发即成功（不再同步等待升级完成，避免节点重启导致的误报失败）
- 远程重启软件/系统改为指令下发即成功，离线节点给出明确提示
- 节点断线重连自愈：注册失败自动重试，解决 AI 盒子重启后偶发永久离线
- 节点卡片新增软件授权功能：经 WS 通道读取机器指纹、下发授权码，授权弹框展示授权码状态/授权天数/生效与过期时间/绑定指纹与标记等信息

**节点连接可观测性**
- 心跳表增加记录类型（心跳/注册/注册被拒），注册与版本拒绝事件入库，心跳弹框支持类型筛选，重连时间线一目了然
- 后端输出统一接入 logging 文件日志（原先 print 仅打控制台，日志文件无记录）

**存量部署升级**（v1.010 及以下 → v1.011 需手动执行增量 SQL）：

```sql
ALTER TABLE cp_node_heart
  ADD COLUMN `type` varchar(20) NOT NULL DEFAULT 'heartbeat' AFTER `client_ip`,
  ADD COLUMN `msg` varchar(200) NULL AFTER `type`;
```

### v1.009 (2026-04-28)

**录像播放器升级**
- 升级为二级时间轴：一级显示24小时概览，二级显示小时内20个3分钟切片
- 支持部分录像渐变色显示，新增"部分录像"图例
- 选中小时/播放切片高亮标识
- 连续播放间隔从60秒对齐为180秒（与后端切片一致）

**报警详情修复**
- 修复报警详情弹框只显示一张图片的问题（节点编号含`.`时路径分割错误）

### v1.007 (2026-03-31)

**UI 全面升级**
- 新增平台报警管理功能
- 首页控制面板美化，现代化卡片设计
- 配置页面重新设计，与首页风格统一
- 侧边栏颜色风格优化，深灰蓝+蓝色系
- 登录页面调整，与系统风格保持一致
- 9个统计卡片统一高度和布局，图标缩小优化

**WebSocket 深度优化**
- 修复 15+ 个功能和性能 bug
- 使用 RLock 替代 Lock 解决死锁问题
- 优化心跳机制，批量写入减少数据库压力
- 命令队列增加大小限制，防止内存泄漏

**数据库 & 路由**
- 默认从 SQLite 切换到 MySQL

---

## 常见问题

**节点连接**

- 注册被拒：节点日志出现 `authentication failed` → `wsToken` 不一致；`version not supported` → 节点版本低于 5.301
- 节点频繁掉线：默认心跳超时 60 秒（`NodeManager._heartbeat_timeout`），公网-内网链路延迟高时可适当调大，或调小节点端 `clusterServer.heartbeatInterval` 增加余量
- 同一 node_code 重复注册（如盒子断网恢复重连）时，新连接直接顶替旧连接，不会出现旧连接占位导致新连接注册失败
- 节点重连后命令执行失败：重连后须重新注册成功才能接收命令（v1.011 起节点端注册失败会自动重试）

**视频与录像**

- 录像回放较慢是公网-内网架构的固有代价：录像文件经 WebSocket 由节点分块传至平台再转发浏览器，频繁回放建议直接访问节点本地管理端
- 录像时间轴空白：确认该流开启了录像计划（`is_record = 1`）、所选时间段确有录像文件、节点录像目录存在且权限正常
- 切片无法播放：节点离线、浏览器控制台有跨域报错、或录像已超过保留天数被清理

**部署与运维**

- cp_server 不必须部署公网，但公网部署可让内网节点主动外连、内网零端口暴露；节点与平台全在同一内网时也可内网部署
- 平台日志位于 `cp_server/log/`，文件名格式 `cp_server日期-时间.log`
- 升级 cp_server：备份数据库与 `config.json` → 拉取最新代码 → `pip install -r requirements.txt` → 如有 SQL 变更手动执行增量 SQL → 重启服务
- Safe 请求头：非浏览器端调用 API 时的安全校验字段，值须与 `config.json` 的 `safe` 一致