🐶 HA Bark Notify —— 给 Home Assistant 装上「端到端加密 Bark 推送」

GitHub：https://github.com/Hamster-Prime/ha-bark-notify
支持 HACS 安装 · MIT 开源 · 覆盖 Bark 全部推送参数

---

为什么做这个

用 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 原生互通，已用官方脚本字节级验证
🌐 自定义服务端	默认 api.day.app，也支持自建 bark-server
🛠 强类型 bark.send 服务	完整覆盖 Bark 全部 20 个推送参数，voluptuous schema 自动校验
🧪 配置即测试	填完表单自动发一条验证推送，坏配置当场暴露
🔔 一键测试按钮	设备页 button.test_push，调试排障最顺手
📊 诊断传感器	last_push_status（success/failed）+ last_push_time，方便接自动化
🛡 隐私保护	Key 以 SHA-256 哈希存储；日志自动脱敏（仅显示前4+后4位）；每次加密随机 IV

---

✨ 截图

插件主页	条目详情

---

安装方法（HACS）

1. HACS → Integrations → 右上角 ⋮ → Custom repositories
2. 填入 https://github.com/Hamster-Prime/ha-bark-notify，Category 选 Integration
3. HACS 搜索 Bark → Download
4. 完全重启 Home Assistant（必须重启，不能只 reload）
5. 设置 → 设备与服务 → 添加集成 → 搜索 "Bark"
6. 填入设备名称、服务器地址、设备 Key（Bark App 首页 URL 最后一段）
7. 提交后手机会收到一条测试推送，收到即成功

多台设备：重复步骤 5-7，每台设备各建一个 entry。

---

用法示例

最简调用

action: bark.send
data:
  message: "洗衣机洗完了"
  target_entity: sensor.bark_my_iphone_last_push_status  # 换成你的设备实体

完整参数（覆盖 Bark 全部能力）

action: bark.send
data:
  message: "洗衣机洗完了"
  title: "家务提醒"
  subtitle: "大概需要晾 2 小时"
  level: timeSensitive          # critical / active / timeSensitive / passive
  volume: 7                     # 仅 level=critical 时有效，0-10
  badge: 1
  sound: minuet
  icon: https://example.com/icon.png
  image: https://example.com/photo.jpg
  group: home
  call: false                   # true = 重复响铃（接电话式提醒）
  url: https://example.com
  copy: "复制到剪贴板的内容"
  is_archive: true
  ttl: 86400                    # 历史记录有效期（秒）
  id: "washer-001"              # 相同 id 再次推送会更新通知，不新增
  target_entity: <Bark 设备实体>

推送失败时触发告警

trigger:
  - platform: state
    entity_id: sensor.bark_my_iphone_last_push_status
    to: "failed"
action:
  - service: notify.admin
    data:
      message: "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 统一管理连接生命周期，避免连接泄漏。

---

文件结构（给想看代码的人）

custom_components/bark/
├── bark_api.py      # 核心：BarkClient + AES加密 + 错误类（不依赖 HA）
├── config_flow.py   # UI 配置流程 + 重配置
├── __init__.py      # setup/unload + 运行时状态
├── entity.py        # BarkEntity 基类 + 设备绑定
├── button.py        # button.test_push 实体
├── sensor.py        # 诊断传感器（status + time）
├── service.py       # bark.send 服务 schema + handler
├── services.yaml    # bark.send 字段描述（HA UI 自动读取）
└── translations/    # 中英文翻译

核心逻辑 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 加：

logger:
  logs:
    custom_components.bark: debug

---

致谢

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

---

项目地址：https://github.com/Hamster-Prime/ha-bark-notify

欢迎 Star / Issue / PR，有问题也可以在这里留言，我会尽量回复。

看上去挺不错的脚本

正好缺这个集成