MP配合 VoceChat 实现消息通知完整教程

本文最后更新于9 天前，其中的信息可能已经过时，如有错误请发送邮件到859811039@qq.com

本教程核心逻辑：通过 VoceChat 的 Webhook 接收端，对接 MP的自定义 Webhook 发送端。

一、前置准备（必做）

服务状态：MP（建议最新版，支持「自定义 Webhook」）、VoceChat 均正常运行
网络要求：两者可互通（Docker 部署建议同一网络；公网部署需开放 VoceChat 80/443 端口）
工具准备：浏览器（操作后台）、记事本（暂存 Webhook 地址/密钥）

二、VoceChat 安装教程（两种方式可选）

2.1 飞牛应用商店安装（适合飞牛NAS用户）【推荐这个】

飞牛NAS用户可通过应用商店快速安装，无需手动配置环境，步骤如下：

准备工作：确保飞牛NAS正常运行，已创建用于安装应用的存储空间
登录飞牛NAS管理界面，点击左侧菜单中的【应用中心】
在应用商店搜索框中输入「VoceChat」，找到对应应用后点击【下载】
选择应用安装位置（建议放在容量较大的存储空间），点击【下一步】
确认安装信息无误后，点击【确定】，等待安装完成（约1-3分钟）
首次配置： ① 安装完成后VoceChat会自动启动，若首次访问出现「not found」错误，进入应用设置，删除路由配置中的「/」后点击保存 ② 点击【打开】进入VoceChat配置页面，设置服务器名称、管理员账号和密码 ③ 根据需求配置注册策略（开放注册/邀请制），完成后即可正常使用

2.2 Docker版本安装（通用跨平台）【以下不建议你尝试，除非你懂】

适合大多数系统（Windows/Linux/macOS），需先安装Docker环境，步骤如下：

步骤1：安装Docker环境（以Debian 11为例，其他系统可参考官方文档）

# 更新系统包并安装依赖
apt update
apt install -y curl
# 安装Docker
curl -fsSL https://get.docker.com | bash
# 启动Docker并设置开机自启
systemctl start docker
systemctl enable docker
# 关闭防火墙避免端口拦截（可选，也可手动开放3000/443端口）
ufw disable
systemctl stop iptables
systemctl stop nftables

步骤2：快速启动VoceChat（基础版，HTTP访问）

适合内网使用，无需域名，直接通过IP+端口访问：

# 启动VoceChat容器（amd64架构）
docker run -d --restart=always \
  -p 3000:3000 \
  --name vocechat-server \
  privoce/vocechat-server:latest

# 若为arm64架构（如树莓派、ARM版NAS），替换镜像为：
# docker run -d --restart=always \
#   -p 3000:3000 \
#   --name vocechat-server \
#   privoce/vocechat-server:latest-arm64

访问方式：浏览器输入 http://你的服务器IP:3000，进入后完成管理员账号配置即可。

步骤3：启用域名+HTTPS（进阶版，公网推荐）

需提前准备域名，可自动申请免费SSL证书，步骤如下：

# 1. 创建数据目录（用于存储证书和配置文件）
mkdir data

# 2. 启动容器并配置HTTPS（替换domain.com为你的域名）
docker run -d --restart=always \
  -p 443:443 \
  --name vocechat-server \
  -v ./data:/home/vocechat-server/data \
  privoce/vocechat-server:latest \
  --network.bind "0.0.0.0:443" \
  --network.domain "domain.com" \
  --network.tls.type "acme_tls_alpn_01" \
  --network.tls.acme.cache_path "/home/vocechat-server/data/cert"

访问方式：浏览器输入 https://你的域名，即可通过HTTPS安全访问VoceChat。

Docker常用命令（维护用）

# 停止VoceChat服务
docker stop vocechat-server

# 查看服务日志（排查问题用）
docker logs -f vocechat-server

# 升级VoceChat（更新镜像）
docker stop vocechat-server
docker rm vocechat-server
docker pull privoce/vocechat-server:latest
# 重新执行之前的启动命令（如基础版/HTTPS版命令）

# 备份数据
cp -rf ~/.vocechat-server/data ~/.vocechat-server/backup

三、步骤 1：VoceChat 端创建 Webhook（获取推送地址）【推荐这个】

支持「频道 Webhook」（多人共享，推荐）和「私聊 Webhook」（个人接收），操作流程类似，以下以频道为例。

1.1 创建频道 Webhook

登录 VoceChat，进入目标频道（可新建「MoviePilot 通知」频道）
点击频道左下角【设置】→ 左侧【集成】→ 【机器人%Webhook】→ 【新增】
配置基础信息（直接按以下填写）：
1. （Name）名称：【这里可以自定义填写】MoviePilot 通知
2. Webhook URL (Optional)【VoceChat机器人Webhook地址设置为：http://ip:port/api/v1/message/?token=moviepilot，其中moviepilot修改为实际配置中实际的API_TOKEN的值（在mp里面的【设定】~【系统】~【api令牌】)，ip:port为实际MoviePilot的IP地址和端口，有配置穿透就填穿透的地址ip或者域名】
点击【保存】：
1. Webhook URL（示例）：https://你的VoceChat域名/webhook/channel/xxxxxx【http(s)://ip:port/api/v1/message/?token=moviepilot】和上面一样
2. Webhook Secret
点击【新建api key】，里面可以随便填写，然后点击【完成】，复制上面的密钥

1.2 私聊 Webhook（个人接收，可选）

点击 “+” → 【新建频道或者新建私有频道】→ 【”频道名称”，这里可以随便填写】
上面配置好以后，进去会有“编辑频道”，点击进去概况这个选项里面就有id，记住频道id，这个id是一个数字，后面配置有用。

四、步骤 2：MoviePilot 端配置自定义 Webhook（核心步骤）【推荐这个方式简单】

2.1 进入通知配置页面

登录 MoviePilot 后台 → 左侧【设置】→ 【通知】→ 【添加通知】
选择vocechat

2.2 核心配置项（直接复制填写，无多余空格）

配置项	填写的内容	说明
类型	mp里面的看你自己情况勾选	自定义勾选
通知名称	MoviePilot-VoceChat	自定义填写，方便识别
地址	你搭建的vocechat地址【飞牛里面搭建的填写你的穿透vocechat地址加端口】	核心地址，错误会导致推送失败
机器人密钥	上面新建密钥复制的粘贴进去	错误就不能通知
频道ID	上面创建频道叫你记住的ID	错误就不能通知

2.5 保存配置

确认所有配置项填写无误后，点击【保存】，完成 MoviePilot 端配置。

五、步骤 3：测试通知是否生效（必做）

回到 vocechat频道或者机器人哪里，尝试发信息，然后等待几秒
回到mp看看日志是否有收到信息
验证结果：打开 VoceChat 对应频道/私聊，若收到测试消息，说明基础配置成功
进阶验证（可选）：手动触发 MoviePilot 事件（如下载一部电影、刮削媒体），确认真实通知正常推送

六、进阶优化（可选，提升体验）【以下不建议，除非你懂】

5.1 多频道分类推送（电影/剧集分开通知）

VoceChat 新建 2 个频道：「MP-电影通知」「MP-剧集通知」，分别生成 Webhook URL
MP 重复步骤 2，添加 2 个自定义 Webhook 配置：
1. 配置 1：Webhook URL 填「电影通知」频道地址，事件过滤仅勾选「电影相关事件」
2. 配置 2：Webhook URL 填「剧集通知」频道地址，事件过滤仅勾选「剧集相关事件」

5.2 旧版 MP 适配（无自定义请求体）

若 MP 版本过旧，无法自定义 JSON 请求体，可部署 Python 转发脚本转换格式。

步骤 1：创建转发脚本（直接复制保存为 mp_forward.py）

from flask import Flask, request, jsonify
import requests
import json

app = Flask(__name__)

# 【替换为你的 VoceChat 配置】
VOCECHAT_WEBHOOK_URL = "https://你的VoceChat域名/webhook/channel/xxxxxx"  # 替换为你的 Webhook URL
VOCECHAT_SECRET = "你的 Webhook Secret（无则留空）"

@app.route('/moviepilot-forward', methods=['POST'])
def forward_notice():
    # 接收 MoviePilot 原始通知
    mp_data = request.get_json()
    if not mp_data:
        return jsonify({"status": "error", "msg": "无通知数据"}), 400

    # 解析原始数据
    event = mp_data.get("event", "未知事件")
    message = mp_data.get("text", "无内容")
    notice_time = mp_data.get("time", "")

    # 构造 VoceChat 支持的格式
    vocechat_payload = {
        "content": f"### 🎬 MoviePilot 通知（转发）\n**事件类型**：{event}\n**内容**：{message}\n**时间**：{notice_time}",
        "type": "rich",
        "from": "MoviePilot",
        "avatar": "https://raw.githubusercontent.com/jxxghp/MoviePilot/main/web/src/assets/logo.png"
    }

    # 推送至 VoceChat
    headers = {"Content-Type": "application/json"}
    if VOCECHAT_SECRET:
        headers["Authorization"] = f"Bearer {VOCECHAT_SECRET}"

    response = requests.post(
        VOCECHAT_WEBHOOK_URL,
        data=json.dumps(vocechat_payload),
        headers=headers
    )

    return jsonify({
        "status": "success" if response.status_code == 200 else "error",
        "vocechat_code": response.status_code
    })

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000, debug=False)  # 端口 5000 可自定义

步骤 2：部署脚本

安装依赖：pip install flask requests
运行脚本：python moviepilot_forward.py
MP 配置：Webhook URL 改为 http://脚本部署IP:5000/moviepilot-forward，其他请求头配置不变

5.3 添加 @ 提醒（指定用户接收）

在消息体 content 中添加 @用户名 即可，示例：

{
  "content": "### 🎬 MoviePilot 通知\n@管理员 新电影下载完成！\n**标题**：{{title}}\n**分辨率**：{{resolution}}\n**时间**：{{time}}",
  "type": "rich",
  "from": "MoviePilot",
  "avatar": "https://raw.githubusercontent.com/jxxghp/MoviePilot/main/web/src/assets/logo.png"
}

七、常见问题排查（快速解决）

问题现象	可能原因	解决方法（可直接复制命令/配置）
测试发送成功，VoceChat 未收到	1. VoceChat Webhook 触发事件未留空；2. URL 错误；3. 网络不通	1. 清空 VoceChat Webhook 触发事件；2. 重新复制 URL 核对；3. 检查防火墙/容器网络
MP 显示 404 错误	Webhook URL 错误（域名/路径/端口错）	重新复制 VoceChat Webhook URL，确保无多余空格
MP 显示 500 错误	1. VoceChat 服务异常；2. Secret 错误	1. 重启 VoceChat：`docker restart vocechat容器名`；2. 核对 Secret 或暂时删除鉴权头测试
Docker 容器间网络不通	容器未加入同一网络	1. 创建共享网络：`docker network create mp-vocechat-net`2. 连接容器：`docker network connect mp-vocechat-net moviepilot容器名docker network connect mp-vocechat-net vocechat容器名`
通知内容乱码	未指定 UTF-8 编码	请求头 Content-Type 改为：`application/json; charset=utf-8`

八、核心总结

核心要点：VoceChat 触发事件留空、MP 必加 JSON 请求头、消息体格式正确【现在没有这么麻烦】
部署效率：基础配置 10 分钟完成，进阶功能按需添加
核心价值：自动推送 MoviePilot 关键事件，无需手动查看，媒体管理更高效