息知推送渠道配置指南#
本教程将指导你如何在 MagicPush（魔法推送）中配置 息知 推送渠道，实现向微信推送消息通知。
概述#
什么是息知？
息知（XiZhi）是一个极简微信消息通知接口，永久免费，无推送数量限制计划。
- 官网：xz.qqoq.net
| 特点 | 说明 |
|---|---|
| 推送目标 | 个人微信（单点推送）或频道成员（频道推送） |
| 鉴权方式 | Key（在息知官网获取） |
| 配置复杂度 | 低，仅需粘贴 Key |
| 消息格式 | text、markdown |
| 频率限制 | 每分钟不超过 30 条（触发限流），微信方日调用上限 10 万次 |
⚠️ 重要限制：息知在微信卡片中仅显示标题，完整内容需要点击查看。
前置条件#
- 拥有微信号（用于接收推送）
- 已访问 息知官网 获取 Key
- 已部署并登录 MagicPush 管理后台
第一步：在息知官网获取 Key#
方式一：单点推送 Key#
- 访问 息知官网
- 页面中会直接显示你的 「单点 Key」
- 点击 「复制」 按钮
📌 单点 Key 示例：
xxxxxx
💡 说明：单点推送将消息发送到个人微信。
方式二：频道 Key#
- 访问 息知官网
- 找到 「频道管理」 部分
- 创建一个频道，获取 「频道 Key」
📌 频道 Key 示例：
yyyyyy
💡 说明：频道推送将消息发送到频道所有成员。需要让其他用户关注你的频道，他们才能收到消息。
至此，你已获得配置所需的信息：
| 配置项 | 示例值 | 来源 |
|---|---|---|
| 单点 Key | xxxxxx | 息知官网首页 |
| 频道 Key | yyyyyy | 息知官网 → 频道管理 |
第二步：在 MagicPush 中添加渠道#
2.1 进入渠道管理#
- 登录 MagicPush 管理后台（默认地址
http://<服务器IP>:3000） - 点击左侧导航 「渠道管理」
- 点击右上角 「+ 绑定渠道」 按钮#
2.2 选择渠道类型#
在弹出的对话框中，从渠道类型下拉列表中选择 「息知」。
2.3 填写配置信息#
根据选择的推送模式，填写对应字段：
单点推送配置#
| 字段 | 说明 | 示例 |
|---|---|---|
| 推送模式 | 选择「单点推送」 | 单点推送 |
| 单点 Key | 从息知官网获取 | xxxxxx |
频道推送配置#
| 字段 | 说明 | 示例 |
|---|---|---|
| 推送模式 | 选择「频道推送」 | 频道推送 |
| 频道 Key | 从息知官网频道管理获取 | yyyyyy |
💡 推送模式说明：
- 单点推送：消息发送到个人微信（只有你自己收到）
- 频道推送：消息发送到频道所有成员（所有关注该频道的用户都会收到）
- 需要先让其他用户关注你的频道，他们才能收到消息
填写完成后，给渠道起一个易于辨识的名称（如「息知微信通知」），点击 「保存」。
2.4 测试连通性#
渠道创建成功后，在渠道卡片右侧的下拉菜单中，点击 「测试」 按钮。
- ✅ 如果微信收到「这是一条来自魔法推送的测试消息」，说明配置成功
- ❌ 如果测试失败，请参考下方常见问题排查#
💡 提示：微信接收消息可能有 1-2 分钟延迟，请耐心等待。
第三步：使用推送#
3.1 通过 API 推送#
创建渠道后，可以通过 MagicPush 的标准 API 进行推送：
bash
curl -X POST http://<服务器IP>:3000/api/push/<渠道ID> \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <你的API Token>" \
-d '{
"title": "系统告警",
"content": "服务器 CPU 使用率超过 90%，请及时处理",
"type": "markdown"
}'支持的消息类型（type 参数）：
| type 值 | 说明 |
|---|---|
text | 纯文本消息（默认） |
markdown | Markdown 格式消息 |
⚠️ 重要：息知在微信卡片中仅显示标题，
content完整内容需要点击查看。
3.2 Markdown 消息示例#
息知支持以下 Markdown 语法：
markdown
## 系统告警通知！
**服务器**：192.168.1.100
**告警级别**：⚠️ 高
> 时间：2024-06-01 14:00
> CPU使用率：95%
请立即处理！技术细节#
消息长度限制#
- 标题 + 内容：建议在 1024 字符以内（微信卡片显示限制）
频率限制#
| 限制项 | 数值 |
|---|---|
| 每分钟推送 | 不超过 30 条（触发限流） |
| 微信方日调用上限 | 10 万次 |
| 永久免费 | ✅ 无推送数量限制计划 |
常见问题#
Q: 发送消息返回「Key 不能为空」错误？
原因：Key 字段未填写。
解决：
- 访问 息知官网
- 复制单点 Key 或频道 Key
- 粘贴到 MagicPush 对应字段中#
Q: 微信没有收到推送消息？
原因：可能有多种情况。
解决：
- 确认微信关注了息知公众号（单点推送）
- 确认已关注你的频道（频道推送）
- 检查是否开启了消息通知（微信设置 → 新消息通知）
- 消息可能有 1-2 分钟延迟，请耐心等待
- 检查息知官网，查看消息发送记录#
Q: 提示「发送频率过高」？
原因：触发了频率限制（30 条/分钟）。
解决：
- 降低推送频率，合并多条消息为一条
- 使用其他推送渠道（如企业微信、钉钉等）分散推送#
Q: 频道推送如何配置？
解决：
- 在息知官网创建频道
- 将频道 Key 分享给其他用户
- 其他用户关注频道后，填写频道 Key 到 MagicPush
- 推送消息时，所有频道成员都会收到#
Q: 微信卡片中只显示标题，不显示内容？
原因：这是息知在微信中的已知限制。
解决：
- 将重要信息放在
title字段中 content字段的内容需要点击卡片查看- 可以考虑使用其他渠道（如 PushPlus、Server酱）来获得更好的展示效果#
Q: 单点推送和频道推送应该选哪个？
| 场景 | 推荐模式 |
|---|---|
| 只有自己需要接收 | 单点推送 |
| 需要多人接收 | 频道推送 |
| 需要更高频率 | 使用其他渠道（企业微信、钉钉等） |