HealthyApps Help Center

将 Apple Health 数据同步到 MQTT

将健康数据发布到 MQTT 代理。

Last updated: February 5, 2026

On this page

MQTT 自动化允许您自动将健康数据发布到 MQTT 代理。这对于与 IoT 平台、家庭自动化系统或任何支持 MQTT 消息传递的服务集成非常理想。

概述

MQTT 自动化将您的健康数据作为 JSON 消息发布到 MQTT 代理上的指定 MQTT 主题。数据会根据您的同步频率设置，在自动化运行时发送。

使用场景:

  • 与 IoT 平台集成（Home Assistant、OpenHAB 等）
  • 将健康数据发布到基于 MQTT 的仪表板
  • 实时健康监控系统
  • 自定义家庭自动化集成
  • 数据记录和分析平台

主要功能:

  • 仅支持 JSON 格式（针对 MQTT 优化）
  • 支持已认证和匿名连接
  • 可配置的主题结构
  • 客户端 ID 管理
  • 可选的用户名/密码认证

限制

  • 健康数据访问: iPhone 锁定时，应用不允许访问健康数据。自动化仅在设备解锁期间运行。这可能会影响数据的新鲜度。请参阅手动同步说明以保持数据最新。

  • 后台处理: iOS 限制后台处理以保持电池寿命。自动化依赖于后台应用刷新，在以下情况下可能不会立即运行:

    • 应用的后台应用刷新已禁用
    • 设备处于低电量模式
    • 设备长时间处于非活动状态
    • 系统资源受限
    • 多个应用竞争后台执行时间

  • 仅支持 JSON 格式（无法更改）

  • 需要 MQTT 代理（本地或基于云）

先决条件

  • MQTT 代理（例如 Mosquitto、HiveMQ、AWS IoT Core 等）
  • 与 MQTT 代理的网络连接
  • 代理 IP 地址或主机名
  • 端口号
  • 可选: 如果代理需要认证，则提供用户名和密码

配置

从主导航转到自动导出屏幕，然后点击"新建自动化"并选择"MQTT"作为自动化类型。

自动化名称

输入自动化的描述性名称（例如"Home Assistant MQTT"、"云 MQTT 代理"）。

通知

配置何时接收通知:

  • 缓存更新时通知 - 缓存数据更新时接收通知
  • 运行时通知 - 每次自动化发布数据时接收通知

代理配置

IP 地址

输入 MQTT 代理的 IP 地址或主机名。

示例:

  • 192.168.1.100（本地 IP 地址）
  • mqtt.example.com（主机名）
  • broker.hivemq.com（云 MQTT 代理）
  • localhost（如果在同一设备上运行，不建议用于 iOS）

注意: 对于网络上的本地代理使用 IP 地址，对于基于云的代理使用主机名。确保代理可以从您的设备访问。

端口

输入 MQTT 代理的端口号。

注意: 默认端口是 1883。

主题

输入将发布健康数据的 MQTT 主题。这是订阅者将用于接收您的健康数据的主题。

主题示例:

  • health/data
  • home/health/metrics
  • user/health/export
  • hae/automation-name

主题最佳实践:

  • 使用正斜杠（/）创建主题层次结构
  • 使用指示数据类型的描述性名称
  • 避免空格和特殊字符
  • 考虑为多个自动化包含自动化名称

注意: 主题名称区分大小写。确保订阅者使用完全相同的主题名称。

客户端 ID

输入此 MQTT 连接的唯一客户端 ID。这会将您的设备标识给 MQTT 代理。

客户端 ID 示例:

  • health-export-iphone
  • hae-client-001
  • ios-health-app

用户名（可选）

输入 MQTT 代理认证的用户名。如果代理不需要认证，请留空。

密码（可选）

输入 MQTT 代理认证的密码。如果代理不需要认证，请留空。

数据类型设置

数据类型

选择要导出的健康数据类型:

  • 健康指标 - 步数、心率、睡眠和其他健康测量值
  • 锻炼 - 运动和健身活动
  • 症状 - 健康症状和状况
  • 心电图 - 心电图读数
  • 心率通知 - 高/低心率事件
  • 心理状态 - 情绪和心理状态条目（iOS 18.0+）
  • 周期跟踪 - 月经周期和生殖健康数据
  • 药物 - 药物日志和依从性（iOS 26.0+）

健康指标配置

选择健康指标时:

选择健康指标 - 选择要包含的特定指标。您可以选择所有可用指标或选择特定指标。

提示: 仅选择所需的指标可减少消息大小和处理时间。

首选来源 - 配置当多个来源提供相同指标时哪些数据源优先。

锻炼配置

选择锻炼时:

包含路线数据 - 切换为开启以包含具有位置数据的锻炼路线。

包含锻炼指标 - 切换为开启以包含锻炼期间收集的健康指标（心率、卡路里等）。

时间分组（锻炼指标） - 使用导出版本 2 且启用包含锻炼指标时:

  • 分钟 - 按分钟分组锻炼指标
  • 秒 - 按秒分组锻炼指标

导出设置

导出格式

注意: MQTT 自动化仅支持 JSON 格式。此设置无法更改，会自动设置为 JSON。

导出版本

为锻炼数据选择导出版本:

  • 版本 1 - 旧格式
  • 版本 2 - 具有增强锻炼数据的当前格式

注意: 导出版本主要影响锻炼数据结构（如果您正在导出锻炼）。

日期范围

选择何时导出数据:

  • 默认 - 同步前一天的完整数据加上当前日期和时间之前的数据
  • 自上次同步 - 每次同步时，导出自上次导出运行以来直到当前日期和时间的所有数据
  • 今天 - 同步当前日期到当前时间的所有数据
  • 昨天 - 同步前一天的完整所有数据
  • 过去 7 天 - 同步过去七天的完整数据

汇总数据

使用 JSON 格式和健康指标数据类型时，切换汇总数据开启或关闭。

  • 开启 - 提供聚合数据摘要（默认）
  • 关闭 - 尽可能提供非聚合数据，显示单个数据点

时间分组

启用汇总数据时，选择应如何聚合数据。

汇总数据

为健康指标切换汇总数据开启或关闭。

  • 开启 - 提供聚合数据摘要（默认）
  • 关闭 - 尽可能提供非聚合数据

注意: 此设置仅适用于健康指标数据类型。

同步频率

配置自动化应多久向 MQTT 发布一次数据:

选择一个数字和间隔。

测试和验证

手动测试

  1. 在自动化配置屏幕中点击"手动导出"
  2. 选择日期范围
  3. 点击"导出"以发布消息
  4. 使用 MQTT 客户端订阅您的主题并验证消息已接收

使用 MQTT 客户端

要验证消息正在发布:

  1. 设置 MQTT 客户端
  2. 使用相同的凭据连接到 MQTT 代理
  3. 订阅您的主题
  4. 从应用触发手动导出
  5. 验证消息出现在 MQTT 客户端中

查看活动日志

  1. 在自动化配置屏幕中点击"查看活动日志"
  2. 查看最近的自动化运行
  3. 检查连接错误或发布失败
  4. 验证发布时间戳

消息格式

MQTT 消息以 JSON 格式发布。消息负载遵循标准导出 JSON 格式:

{
  "data": {
    "metrics": [...],
    "workouts": [...],
    ...
  }
}

消息发布时包含:

  • 主题: 在自动化中配置的主题
  • QoS: 最多一次传递
  • 保留: 消息不保留
  • 负载: 包含健康数据的 JSON 字符串

故障排除

常见问题

连接失败

  • 验证代理 IP 地址/主机名是否正确
  • 检查端口是否正确以及代理是否在该端口上监听
  • 确保与代理的网络连接
  • 验证防火墙规则允许连接到代理
  • 检查代理是否需要 TLS/SSL

认证失败

  • 验证用户名和密码是否正确
  • 如果提供了凭据，检查代理上是否启用了认证
  • 确保用户有权发布到指定主题

未收到消息

  • 验证主题名称是否完全匹配（区分大小写）
  • 检查订阅者是否连接到同一代理
  • 确保订阅者订阅了正确的主题
  • 验证自动化已启用并正在运行
  • 检查活动日志中的发布错误

消息大小过大

  • 减少所选健康指标的数量
  • 使用不太细粒度的聚合选项
  • 考虑为不同的数据类型拆分为多个自动化

提示和最佳实践

  1. 主题组织:

    • 使用分层主题结构（例如 health/metrics、health/workouts）
    • 在主题中包含设备或自动化标识符
    • 记录您的主题结构以便于参考

  2. 消息大小:

    • 保持消息大小合理以避免 MQTT 代理限制
    • 使用不太细粒度的聚合以减少数据量
    • 考虑将大型数据集拆分为多个消息

  3. 监控:

    • 使用应用中的活动日志跟踪发布成功

  4. 云代理:

    • 使用云 MQTT 代理（AWS IoT、HiveMQ Cloud 等）时:
      • 遵循其特定的连接要求
      • 检查其消息大小和速率限制
      • 验证主题命名约定