# zPublish **Repository Path**: cpsoft13/z-publish ## Basic Information - **Project Name**: zPublish - **Description**: 基于android系统的信息发布系统。实现低资源低带宽占用。目标单服务器支持上万台设备。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-04-23 - **Last Updated**: 2026-05-07 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 智播 zPublisher > 连锁门店广告屏幕内容管理与分发系统 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Rust](https://img.shields.io/badge/Rust-1.75+-orange.svg)](https://www.rust-lang.org) [![Vue](https://img.shields.io/badge/Vue-3-brightgreen.svg)](https://vuejs.org) [![Flutter](https://img.shields.io/badge/Flutter-3.0-blue.svg)](https://flutter.dev) ## 项目简介 智播（zPublisher）是一套面向连锁门店的广告屏内容管理与分发系统。管理后台编排广告节目 → 后端通过 BT P2P 分发素材 → 终端设备下载并定时播放，形成完整的内容分发闭环。 **核心链路：** ``` ┌──────────────────┐ ┌──────────────────────┐ ┌──────────────────┐ │ 管理后台 (Vue) │──────▶│ API (Rust/Axum) │◀─────▶│ 终端 (Flutter) │ │ 内容编排/排程 │ 5173 │ 设备/内容/分发/BT │ 9090 │ 播放/上报 │ └──────────────────┘ └──────────┬───────────┘ └──────────────────┘ │ ┌───────────▼───────────┐ │ SQLite / MySQL │ │ 业务数据 + 素材种子 │ └───────────┬───────────┘ │ ┌───────────▼───────────┐ │ Redis (可选) │ │ Swarm 状态缓存 │ └───────────────────────┘ 内容分发：HTTP API + BT P2P（全局 Swarm） 设备通信：MQTT 3.1.1（自研 Broker） ``` ![Dashboard](assets/screenshots/dashboard.png) *▲ 管理后台仪表盘 — 核心指标概览，右侧 QR 码可手机扫码进入配网页面* ![Device Setup](assets/screenshots/device-setup.png) *▲ 设备配网 — 手机扫描 TV 设备码，局域网下发配置完成自动注册* ![Schedules](assets/screenshots/schedules.png) *▲ 排程管理 — 按月日历视图，左侧设备树筛选，右侧排程编辑* ![BT Monitor](assets/screenshots/bt-monitor.png) *▲ BT Swarm 监控面板 — 实时种子列表与节点分布状态* ![Settings](assets/screenshots/settings.png) *▲ 用户与权限 — 用户列表、角色权限矩阵、系统设置三标签页* ## 核心功能 ### 内容管理 - **素材上传**：支持图片、视频、HTML 素材，100MB 上传限制 - **视频缩略图**：ffmpeg 自动生成 320x180 JPEG 缩略图 - **文件夹分组**：层级化文件夹组织素材 - **回收站**：软删除 + 可配置保留期（默认 30 天），支持手动恢复 ### 节目编排 - **Canvas 画布**：可视化拖拽设计节目布局 - **Zone 分区**：支持普通区域和文字区域，可自由调整位置和大小 - **组件管理**：每个区域可添加多个素材组件 - **节目缩略图**：自动生成节目预览图 ### 排程管理 - **日历视图**：可视化排程日历 - **时间范围**：支持按星期、日期范围、时间段设置 - **批量操作**：批量排程、批量替换 - **设备绑定**：一个排程可绑定多个设备 ### 设备管理 - **智能配网**：管理员手机扫描仪表盘 QR → 扫描 TV 设备码 → 局域网下发配置 → TV 自动注册 - **设备注册**：自动生成唯一设备码，支持绑定令牌验证 - **远程控制**：禁用/启用、重启、音量调节、截屏 - **在线监控**：MQTT LWT 实时在线状态检测 - **播放日志**：完整的播放记录和错误信息 - **设备截图**：远程截屏上传 ### BT P2P 内容分发 - **自动种子**：上传文件自动生成 .torrent（SHA-1 分片哈希） - **块级并行下载**：文件拆分为 4 块，不同设备并行下载 - **HTTP Range 请求**：`?range=start-end` 返回 206 Partial Content - **三角色协调**：`chunk_downloader` / `bt_seed` / `bt_wait` - **Swarm 监控**：实时查看每个内容的种子数、下载数、节点列表 - **CDN 回退**：无 Peer 时自动切换 HTTP 下载 - **Redis 持久化**：Swarm 状态持久化到 Redis（DB 回退） ### MQTT 设备通信 - **自研 Broker**：内置 MQTT 3.1.1 Broker，无需额外部署 - **持久连接**：双向通信替代 HTTP 心跳轮询 - **LWT 遗嘱**：设备离线自动检测 - **心跳响应**：包含节目数据、远程指令、排程信息、OTA 更新 - **播放状态**：实时上报播放进度和错误 ### OTA 升级管理 - **版本管理**：APK 版本上传，支持 version_code 和强制更新 - **终端检测**：设备心跳自动检测新版本 - **APK 下载**：专用下载端点 ### 权限与审计 - **角色权限**：基于数据库 KV 存储的权限矩阵 - **操作审计**：所有管理操作记录审计日志 - **活动日志**：统一视图（审计 + 发布 + 变更） ### 首次安装向导 - **自动检测**：首次启动自动进入 Web 安装向导，无需手动编辑配置 - **引导式配置**：分步配置数据库（SQLite/MySQL/PostgreSQL）、Redis、管理员账户、站点信息 - **连接验证**：提交前自动测试数据库和 Redis 连接可用性 - **数据库迁移**：自动执行 SQL migration，创建表结构和初始数据 - **管理员创建**：向导完成时自动创建管理员账户（bcrypt 哈希存储） - **原子写入**：配置验证通过后原子写入 config.toml，失败不影响现有配置 - **重启生效**：安装完成后一键重启进入正常模式 - **手动预配置**：高级用户可直接编辑 config.toml 设置 `setup.completed = true` 跳过向导 ### 设备扫码配网 - **仪表盘 QR**：管理后台仪表盘展示配网页面 QR 码，管理员手机扫码进入 - **TV 设备码扫描**：手机扫描 TV 屏幕上的 JSON 二维码（ip/port/device_code） - **局域网验证**：自动通过 HTTP GET 验证 TV 在同一局域网的可达性 - **绑定令牌**：服务端生成临时 JWT bind_token（10 分钟有效），手机通过局域网下发到 TV - **自动注册**：TV 收到配置后自动连接服务器并在下次心跳时完成注册 - **多设备配网**：配网完成后可"继续添加"下一台设备，支持批量配网 - **手动输入**：非 HTTPS 环境下摄像头不可用，可切换至手动输入模式直接填写设备信息 - **HTTPS 说明**：摄像头扫码需要 HTTPS 或 localhost 环境，生产部署建议配置 SSL 证书 ### 多端同步 - **播放对齐**：同一播放列表的设备对齐到相同节目项 - **sync_state**：实时跟踪每个设备的播放位置 ## 技术栈 | 层级 | 技术 | |------|------| | 后端 API | Rust + Axum | | 数据库 | SQLite（原型）/ MySQL（生产） | | 缓存 | Redis（可选） | | 设备通信 | MQTT 3.1.1（自研 Broker） | | 内容分发 | BT P2P（全局 Swarm） | | 管理后台 | Vue 3 + TypeScript + Tailwind CSS | | 终端播放 | Flutter / Android | | 视频处理 | ffmpeg（缩略图生成） | ## 快速开始 ### 环境要求 - Rust 1.75+ - Node.js 18+ - Flutter 3.0+（终端） ### 后端启动 ```bash # 克隆仓库 git clone https://gitee.com/cpsoft13/z-publish.git cd z-publish/backend # 编译运行（首次启动自动进入安装向导） cargo run -p zpublisher-api # 浏览器访问 http://localhost:9090 进入安装向导 # 完成数据库/Redis/管理员账户配置后，重启进入正常模式 # 或构建 Linux release 包 ./build.sh linux --clean # 产物: dist/zpublisher-api-0.1.0_linux_x86_64.tar.gz ``` ### 管理后台 ```bash cd web/admin npm install npm run dev # http://localhost:5173 npm run build # 生产构建 ``` ### 终端应用 ```bash cd mobile/player flutter pub get flutter run # 连接设备运行 ``` ### 配置 编辑 `backend/config.toml`： ```toml [server] port = 9090 public_url = "http://your-domain.com:9090" [database] type = "sqlite" url = "sqlite://data/zpublisher.db" [redis] url = "" # 留空禁用 [mqtt] enabled = true port = 1883 ``` ## 项目结构 ``` zPublish/ ├── backend/ # Rust 后端 │ ├── crates/ │ │ ├── zpublisher-api/ # 主服务（Axum + MQTT Broker + BT Tracker） │ │ ├── zpublisher-db/ # 数据库层（sqlx） │ │ ├── zpublisher-model/ # 共享数据模型 │ │ └── zpublisher-mqtt/ # MQTT 3.1.1 Broker │ ├── config.toml # 配置文件 │ ├── build-release.sh # Release 构建脚本 │ └── dist/ # 构建产物 ├── web/admin/ # Vue 3 管理后台 │ ├── setup.html # 安装向导入口 │ ├── setup/ # 安装向导 SPA │ └── src/ │ ├── views/ # 页面组件（仪表盘/门店/设备/素材/节目/排程/配网） │ ├── components/ # 通用组件 │ ├── api/ # API 客户端 │ └── i18n/ # 国际化（中/英） ├── mobile/player/ # Flutter 终端 │ └── lib/ │ ├── core/ # 核心模块（API、配置、BT 引擎） │ └── services/ # 业务服务 └── docs/ # 使用文档 ``` ## 文档 - [管理后台使用手册](docs/zh/admin-guide.md) — 全部功能模块操作说明 - [终端使用手册](docs/zh/terminal-guide.md) — Flutter 终端安装与使用 - [部署指南](wiki/07-OPERATIONS/deployment-guide.md) — 生产环境部署与运维 - [系统架构](wiki/03-ARCHITECTURE/system-overview.md) — 架构设计与技术决策 - [在线手册](http://localhost:9090/manual) — 管理后台内置使用手册（含部署与配网章节） ## License MIT