本帖最后由 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:
action: bark.send
data:
message: "洗衣机洗完了"
target_entity: <你的 Bark 设备实体或 config entry id>
完整参数（覆盖 Bark 全部能力）
action: bark.send
data:
message: "洗衣机洗完了" # 必填，推送正文
title: "家务提醒" # 推送标题
subtitle: "次要说明" # 副标题
# markdown: "# 标题\n正文" # 传了 markdown 会忽略 message
level: timeSensitive # critical / active / timeSensitive / passive
volume: 7 # 仅 level=critical 生效，0-10
badge: 1 # App 角标数字
sound: minuet # 铃声名（在 Bark App 内预览）
icon: https://example.com/i.png # 自定义图标 URL（自动缓存）
image: https://example.com/p.jpg # 推送图片
group: home # 通知分组
call: false # true = 重复响铃（接电话式提醒）
url: https://example.com # 点击推送跳转的 URL
action: alert # 点击推送时弹出操作弹窗
copy: "复制内容" # 下拉推送时复制到剪贴板
auto_copy: false # 是否自动复制
is_archive: true # 是否保存到 Bark 历史记录
ttl: 86400 # 历史记录有效期（秒），到期自动删除
id: "washer-001" # 用相同 id 再次推送会更新通知，不新增
# delete: true # 配合 id 使用，删除指定通知
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 统一管理连接生命周期，避免连接泄漏。
文件结构
custom_components/bark/
├── manifest.json # HA 集成元信息（域名、版本、依赖）
├── hacs.json # HACS 商店元信息
├── const.py # 全部常量（DOMAIN、CONF_*、运行时 key）
├── bark_api.py # 【核心】BarkClient + BarkPayload + 错误类
│ # + encrypt_payload（纯 Python，不依赖 HA）
├── config_flow.py # UI 配置流程（用户步骤 + 重配置）
├── __init__.py # async_setup_entry/unload_entry + 运行时状态
├── entity.py # BarkEntity 基类 + 设备绑定 + redact_key
├── button.py # button.test_push 实体
├── sensor.py # last_push_status + last_push_time 诊断传感器
├── service.py # bark.send 服务的 schema + handler
├── services.yaml # bark.send 字段描述（HA UI 自动生成表单）
└── translations/
├── en.json # 英文翻译
└── 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 加：
logger:
logs:
custom_components.bark: debug
致谢
感谢 @Finb 开发了 Bark 这个干净、无广告的 iOS 推送工具，以及整个 Home Assistant 和 HACS 社区。
项目地址：https://github.com/Hamster-Prime/ha-bark-notify 欢迎 Star / Issue / PR，有问题也可以在这里留言，我会尽量回复。 | 
发表于 2026-6-20 20:46:28
