『HomeAssistant』综合讨论区

[插件集成] 🐶 HA Bark Notify —— 给 Home Assistant 装上「端到端加密 Bark 推送」的自定义集
  • 楼主 Hamster
  • 118352026-6-20 20:46:28
本帖最后由 Hamster 于 2026-6-20 20:59 编辑

用 HA 做智能家居自动化，推送通知是刚需。官方的 mobile_app 推送一来必须装官方 App，二来参数有限；Telegram Bot 虽然灵活，但不想对每条家里的提醒消息都依赖外部服务。
Bark 是 iOS 上一款小而美的推送工具——免费、无广告、开源、支持自建服务端，还有端到端加密（发出去的内容连 Bark 服务器和苹果 APNs 都看不到明文）。但 HA 一直没有一个像样的 Bark 集成：翻了一圈，能找到的要么参数残缺，要么还是老式 YAML notify 平台，要么加密根本没实现对。
于是干脆自己写了一个，从 config_flow 到加密到诊断传感器全部重来，做成了一个比较完整的 HACS 自定义集成。


功能一览
  • 📱 多设备独立配置 — 每台 iPhone / iPad 一个 config entry，互不干扰
  • 🔒 端到端 AES-128-CBC 加密 — 与 Bark iOS App 互通（密文连 Bark 服务器和苹果 APNs 都看不到，已用官方文档示例密文逐字节验证）
  • 🌐 自定义服务器 — 默认 https://api.day.app，也支持自建 bark-server 部署
  • 🛠 强类型 bark.send 服务 — 覆盖 Bark 全部 20 个推送参数（标题 / 正文 / Markdown / 铃声 / 中断级别 / 角标 / 图标 / 图片 / 分组 / 重复响铃 / 跳转 URL / 有效期 / 通知 ID …）
  • 🧪 配置时自动测试推送 — 填完表单即发一条验证推送，错误立即暴露，不让坏配置进 HA
  • 🔔 button.test_push 一键测试 — 设备页直接点按按钮即可触发测试推送，日常排障最方便
  • 📊 诊断传感器 — last_push_status（success / failed / unknown）+ last_push_time，自动化判活有依据
  • 🛡 隐私安全 — 设备 Key 在 HA 设备注册表里以 SHA-256 哈希存储；日志里 Key 自动脱敏（仅显示前 4 + 后 4 位）；每次加密推送生成随机 IV

安装方法（HACS）
  • HACS → Integrations → 右上角 ⋮ → Custom repositories
  • 填入 https://github.com/Hamster-Prime/ha-bark-notify，Category 选 Integration
  • HACS 搜索 Bark → Download
  • 完全重启 Home Assistant（必须重启，不能只 reload）
  • 设置 → 设备与服务 → 添加集成 → 搜索 "Bark"
  • 填入设备名称、服务器地址、设备 Key（Bark App 首页 URL 最后一段）
  • 提交后手机会收到一条测试推送，收到即成功
多台设备：重复步骤 5-7，每台设备各建一个 entry。


用法示例最简调用action:
  1. action: bark.send
  2. data:
  3.   message: "洗衣机洗完了"
  4.   target_entity: <你的 Bark 设备实体或 config entry id>
复制代码

完整参数（覆盖 Bark 全部能力）
  1. action: bark.send
  2. data:
  3.   message: "洗衣机洗完了"          # 必填，推送正文
  4.   title: "家务提醒"                # 推送标题
  5.   subtitle: "次要说明"             # 副标题
  6.   # markdown: "# 标题\n正文"       # 传了 markdown 会忽略 message
  7.   level: timeSensitive             # critical / active / timeSensitive / passive
  8.   volume: 7                        # 仅 level=critical 生效，0-10
  9.   badge: 1                         # App 角标数字
  10.   sound: minuet                    # 铃声名（在 Bark App 内预览）
  11.   icon: https://example.com/i.png  # 自定义图标 URL（自动缓存）
  12.   image: https://example.com/p.jpg # 推送图片
  13.   group: home                      # 通知分组
  14.   call: false                      # true = 重复响铃（接电话式提醒）
  15.   url: https://example.com         # 点击推送跳转的 URL
  16.   action: alert                    # 点击推送时弹出操作弹窗
  17.   copy: "复制内容"                 # 下拉推送时复制到剪贴板
  18.   auto_copy: false                 # 是否自动复制
  19.   is_archive: true                 # 是否保存到 Bark 历史记录
  20.   ttl: 86400                       # 历史记录有效期（秒），到期自动删除
  21.   id: "washer-001"                 # 用相同 id 再次推送会更新通知，不新增
  22.   # delete: true                   # 配合 id 使用，删除指定通知
  23.   target_entity: <Bark 设备实体>
复制代码


关于端到端加密
这是我觉得做得比较认真的地方，单独说一下。
Bark 支持 AES-128-CBC 推送加密：明文在本地加密后再发出，Bark 官方服务器和苹果 APNs 都只能看到密文，只有你的 iPhone 能解密。
实现上有几个坑：
  • 密钥派生：直接用密钥的 ASCII 字节（16字符=16字节=128位），没有 PBKDF2/HKDF，要和 Bark App 的实现完全一致
  • IV 随机：每次推送生成随机 IV，保证前向安全
  • PKCS7 padding：标准 CBC 模式必须的
为了确认互通性，我用 Bark iOS App 自己导出的 openssl enc -aes-128-cbc 命令，和集成产生的密文做了逐字节对比，完全一致后才上线。
⚠️ 注意：密钥必须是 16 个 ASCII 字符，不能用中文或 emoji（UTF-8 多字节会导致密钥长度不对）


设计上的几个取舍
这个集成做了一些与常见 HA 通知集成不同的选择，说一下原因：
为什么不用标准 notify.* 服务？
Bark 有 20 个参数，notify 平台的 data 字典没有类型校验，HA UI 也不补全。用独立的 bark.send 服务 + voluptuous schema，HA 可以自动生成表单、字段自动补全、参数错误立即报错，体验要好很多。
为什么不做自动重试？
Bark 官方服务有「5 分钟 1000 次错误请求封 IP 24 小时」的限制。自动重试在网络抖动时容易触发这个规则，所以选择分层报错、不重试，让用户自己决定。
Session 管理
复用 HA 共享的 aiohttp session，由 HA 统一管理连接生命周期，避免连接泄漏。


文件结构
  1. custom_components/bark/
  2. ├── manifest.json          # HA 集成元信息（域名、版本、依赖）
  3. ├── hacs.json              # HACS 商店元信息
  4. ├── const.py               # 全部常量（DOMAIN、CONF_*、运行时 key）
  5. ├── bark_api.py            # 【核心】BarkClient + BarkPayload + 错误类
  6. │                          #        + encrypt_payload（纯 Python，不依赖 HA）
  7. ├── config_flow.py         # UI 配置流程（用户步骤 + 重配置）
  8. ├── __init__.py            # async_setup_entry/unload_entry + 运行时状态
  9. ├── entity.py              # BarkEntity 基类 + 设备绑定 + redact_key
  10. ├── button.py              # button.test_push 实体
  11. ├── sensor.py              # last_push_status + last_push_time 诊断传感器
  12. ├── service.py             # bark.send 服务的 schema + handler
  13. ├── services.yaml          # bark.send 字段描述（HA UI 自动生成表单）
  14. └── translations/
  15.     ├── en.json            # 英文翻译
  16.     └── zh-Hans.json       # 简体中文翻译
复制代码

核心逻辑 BarkClient 完全不依赖 HA，可以单独测试。


常见问题
Q：没收到测试推送怎么办？
先确认 device key 是否正确（Bark App 首页 URL 最后一段），再用 curl 验证服务器可达：
curl "https://api.day.app/YOUR_KEY/测试"
Q：手机显示「Decryption Failed」？
加密密钥和 Bark App 内设置的不一致，或密钥不是 16 个纯 ASCII 字符。
Q：怎么同时给多台设备发？
在 bark.send 的 target 里传入多个实体 ID 列表，handler 会逐个推送。
Q：安装后找不到集成？
HACS 安装后必须完整重启 HA（Settings → System → Restart），不能只 reload，因为 Python 模块需要重新加载。
Q：调试时怎么看详细日志？
在 configuration.yaml 加：
  1. logger:
  2.   logs:
  3.     custom_components.bark: debug
复制代码


致谢
感谢 @Finb 开发了 Bark 这个干净、无广告的 iOS 推送工具，以及整个 Home Assistant 和 HACS 社区。


项目地址：https://github.com/Hamster-Prime/ha-bark-notify
欢迎 Star / Issue / PR，有问题也可以在这里留言，我会尽量回复。

评分

正序浏览 看全部 全部回复5
  • 6# xxx888
  • 2026-6-26 14:51:59
感谢大佬分享，论坛有你更精彩！
  • 5# chaobt
  • 2026-6-25 01:45:22
感谢大佬分享，论坛有你更精彩！
  • 地板 wjh1025
  • 2026-6-24 15:36:59
大佬，能不能把sensor的数值（会变化的）作为通知文本发送啊？
  • 板凳 s2233
  • 2026-6-21 19:03:45
本帖最后由 s2233 于 2026-6-28 18:51 编辑

👍👍 原来可以选择多人发送
  • 沙发 telanx
  • 2026-6-21 00:05:23
感谢大佬～

之前一直用的企业微信的消息，可以试试bark了。
回复 13收藏