PyMKUI

PyMKUI 是一个为 ZLMediaKit 设计的现代化 Web 管理界面，基于 Python 插件机制深度集成，提供直观、美观的流媒体服务器管理功能。

⚠️ 项目正处于快速迭代期，数据库结构频繁变动。每次更新代码后请先删除旧数据库：

bash rm data/pymkui.db

数据库将在下次启动时自动重建。

---

功能特性

• 🎬 视频流管理 — 查看、播放、停止流，获取截图
• 📡 拉流代理 — 多备用地址、按需/立即模式、自动故障切换、持久化恢复、在线编辑
• 🔄 转协议预设 — 保存多套转协议参数，拉流时一键加载，支持加载服务器默认值
• 👥 观众列表 — 实时查看每路流的在线观众及连接信息
• 📊 服务器监控 — CPU、内存、磁盘、网络实时图表
• ⚙️ 服务配置 — 在线读写 ZLMediaKit 配置项
• 🌐 在线推流 — 基于 WHIP 协议的浏览器端直播推流
• 🔗 网络连接 — 查看和管理当前所有 TCP/UDP 会话
• 📁 录像管理 — 录像文件分流、分日期浏览，支持检索、在线播放与下载，自动按策略清理过期文件
• 🧩 插件系统 — 内置可扩展 Python 事件钩子，支持用户自定义推流鉴权、录制回调、流上下线通知等业务逻辑，无需修改核心代码
• 🩺 视频质量探针 — 对推拉流实时采样分析，输出码率、帧率、GOP、音视频交织性等多维度质量指标，以折线图与打点图直观呈现，快速定位卡顿、花屏等异常

---

快速开始（Docker 一键部署）

已集成到 ZLMediaKit Docker 镜像中，无需手动配置：

docker run -id \
  -p 1935:1935 \
  -p 80:80 \
  -p 443:443 \
  -p 554:554 \
  -p 10000:10000 \
  -p 10000:10000/udp \
  -p 8000:8000/udp \
  -p 9000:9000/udp \
  zlmediakit/zlmediakit:master_py

启动后浏览器访问 http://<服务器IP>/，输入 api.secret 密钥即可登录。

端口说明

端口	协议	用途
80	TCP	HTTP（前端 + API）
443	TCP	HTTPS / WSS
1935	TCP	RTMP
554	TCP	RTSP
10000	TCP/UDP	RTP
8000	UDP	WebRTC
9000	UDP	SRT

---

手动部署（源码方式）

适用于自行编译 ZLMediaKit 并希望使用 PyMKUI 的场景。

项目结构

pymkui/
├─ frontend/          # 静态前端页面
├─ backend/           # Python 插件与 FastAPI 接口
│  ├─ mk_plugin.py    # ZLMediaKit Python 插件入口
│  ├─ py_http_api.py  # FastAPI HTTP API
│  ├─ database.py     # SQLite 数据库
│  ├─ config.py       # 路径配置
│  ├─ mk_logger.py    # 日志封装
│  └─ shared_loop.py  # asyncio 事件循环共享
├─ data/              # 运行时自动生成
│  └─ pymkui.db       # ⚠️ 升级时请删除
└─ README.md

步骤 1：安装 Python 依赖

需要 Python 3.10+

cd pymkui/backend
pip install -r requirements.txt

conda / venv 方式

# conda
conda create -n pymkui python=3.12 && conda activate pymkui
pip install -r requirements.txt

# venv (Linux/Mac)
python -m venv venv && source venv/bin/activate && pip install -r requirements.txt

# venv (Windows)
python -m venv venv && venv\Scripts\activate && pip install -r requirements.txt

步骤 2：编译 ZLMediaKit 时开启 Python 支持

# 安装 Python 相关依赖
apt-get update && apt-get install -y python3 python3-dev python3-pip
# cmake时指定开启python相关特性
cmake .. -DENABLE_PYTHON=ON

步骤 3：修改 config.ini

[python]
plugin=mk_plugin

[http]
rootPath=/path/to/pymkui/frontend

步骤 4：让 ZLMediaKit 找到 backend 模块

# Linux/Mac
export PYTHONPATH=/path/to/pymkui/backend:$PYTHONPATH

# Windows
set PYTHONPATH=C:\pymkui\backend;%PYTHONPATH%

步骤 5：启动并验证

# 启动 ZLMediaKit
./MediaServer

# 验证前端可访问
curl -sv http://localhost:80/login.html
# 应返回 HTTP/1.1 200 OK

---

界面展示

---

常见问题

问题	解决方法
zlm打印Python调用红色错误日志	同时更新zlm和pymkui至最新版本
/index/pyapi/* 返回未登录	正常现象，API 已通，完成登录即可
配了 rootPath 仍 404	确认路径指向 frontend/ 目录且 login.html 存在
启动报数据库错误	删除 data/pymkui.db 后重启

---

技术栈

层级	技术
前端	HTML5 + Tailwind CSS + Font Awesome
播放器	Jessibuca (FLV)、原生 HLS、WHEP (WebRTC)
后端	Python + FastAPI（内嵌于 ZLMediaKit Python 插件）
数据库	SQLite
服务器	ZLMediaKit (C++)

---

未来规划

• 🤖 AI 推理集成 — 对接 ONNX / TensorRT / OpenCV DNN，实现实时视频分析（目标检测、人脸识别等）

贡献

欢迎提交 Issue 和 Pull Request。

许可证

MIT License