🐶 HA Bark Notify —— 给 Home Assistant 装上「端到端加密 Bark 推送」
本帖最后由 Sanite_Ava 于 2026-6-20 21:02 编辑> GitHub：https://github.com/Hamster-Prime/ha-bark-notify
> 支持 HACS 安装 · MIT 开源 · 覆盖 Bark 全部推送参数
---
## 为什么做这个
用 HA 做智能家居自动化，推送通知是刚需。官方的 `mobile_app` 推送一来必须装官方 App，二来参数有限；Telegram Bot 虽然灵活，但不想对每条家里的提醒消息都依赖外部服务。
(https://bark.day.app) 是 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 |
---
## ✨ 截图
|插件主页|条目详情|
|---|---|
|!(https://github.com/user-attachments/assets/da82c04b-cd46-4eed-8039-e7ace2da1b2f)|!(https://github.com/user-attachments/assets/3bfaa02a-f5ab-44fa-b041-4414214bec13)|
!(https://github.com/user-attachments/assets/ae000a47-d3d8-4fed-b65b-5f971ba14c30)
|||
|---|---|
| !(https://github.com/user-attachments/assets/520508e8-c135-4b0b-b218-04b66f498b60) | !(https://github.com/user-attachments/assets/2c1956e9-ce6b-4165-9bc9-973d4ae604e6) |
| !(https://github.com/user-attachments/assets/eafcfe93-4d2b-4328-9e4b-b2ac92797ecc) | !(https://github.com/user-attachments/assets/eafcfe93-4d2b-4328-9e4b-b2ac92797ecc) |
---
## 安装方法（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。
---
## 用法示例
### 最简调用
```yaml
action: bark.send
data:
message: "洗衣机洗完了"
target_entity: sensor.bark_my_iphone_last_push_status# 换成你的设备实体
```
### 完整参数（覆盖 Bark 全部能力）
```yaml
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 设备实体>
```
### 推送失败时触发告警
```yaml
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 验证服务器可达：
```bash
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` 加：
```yaml
logger:
logs:
custom_components.bark: debug
```
---
## 致谢
感谢 [@Finb](https://github.com/Finb) 开发了 Bark 这个干净、无广告的 iOS 推送工具，以及整个 Home Assistant 和 HACS 社区。
---
项目地址：**https://github.com/Hamster-Prime/ha-bark-notify**
欢迎 Star / Issue / PR，有问题也可以在这里留言，我会尽量回复。 看上去挺不错的脚本 正好缺这个集成
页:
[1]