Polar Health Data (self-hosted)

polar-flow-server

面向 Polar 设备的可自托管健康分析服务——掌控自己的数据，根据自己的基线进行分析，并让 AI 助手读取数据。

完整文档 · MCP 服务 · 集成指南 · API 参考

功能介绍

你的手表对你的了解比你自己还多——而 Polar 的 API 只允许你查看最近 28–30 天的数据。本服务会同步所有数据，永久保存，并将其转化为答案：

1. 自动同步全部 13 个 Polar API 端点——睡眠、HRV、活动、锻炼、SpO2、ECG、皮肤温度等
2. 将所有数据存储在 PostgreSQL 中。你的数据、你的服务，你与数据之间没有云端介入
3. 计算个人基线（滚动平均值、IQR 异常界限），因此“这正常吗？”指的是“对你而言正常吗？”
4. 内置支持 OAuth 登录的 MCP 服务——问 Claude“我今天适合进行高强度训练吗？”，它会根据你夜间的 HRV 与个人基线进行回答
5. 管理员仪表板（HTMX）、REST API、每用户 API 密钥，并支持多用户

向 AI 询问你的身体状况（MCP）

内置的 Model Context Protocol 服务使用协议修订版 2026-07-28 和可流式传输的 HTTP，运行在主服务的 /mcp 路径下。十个精选工具涵盖一次性健康评估、睡眠、恢复、活动、锻炼、七种生物传感数据流、个人基线、模式/异常以及同步控制。

在可渲染 MCP Apps 的客户端（claude.ai、Claude Desktop、VS Code）中，询问“我的状态怎么样？”会在对话中显示一张真实的卡片：

连接方式是登录，而不是粘贴。 设置 BASE_URL 后，本服务本身就是 OAuth 2.1 授权服务：在 Claude Desktop 或 claude.ai 中将 https://your-server/mcp 添加为自定义连接器，点击 Connect，在自己的服务上登录，并批准授权页面。令牌按用户隔离，每小时过期，自动刷新，且可在“设置”中撤销所有已连接的应用。无头客户端仍可使用 API 密钥：

claude mcp add polar-health https://your-server.example.com/mcp \
  --transport http \
  --header "X-API-Key: pfk_your_key_here"

完整设置说明见 MCP 文档。

架构

Polar API → polar-flow SDK → Sync Service → PostgreSQL
                                                  ↓
                                           Admin Dashboard (HTMX)
                                                  ↓
                                             REST API

技术栈：

• Litestar（异步 Web 框架）
• SQLAlchemy 2.0（异步 ORM）
• PostgreSQL
• HTMX + Tailwind（管理界面）
• polar-flow SDK v1.5.0

不想运行服务？ 托管版本正在开发中——加入候补名单。自托管永远免费。

快速开始

选项 1：Docker（推荐）

# Pull and run
curl -O https://raw.githubusercontent.com/StuMason/polar-flow-server/main/docker-compose.prod.yml
docker-compose -f docker-compose.prod.yml up -d

# That's it. Open http://localhost:8000/admin

选项 2：从源代码安装

git clone https://github.com/StuMason/polar-flow-server.git
cd polar-flow-server
docker-compose up -d

设置

1. 打开 http://localhost:8000/admin
2. 从 admin.polaraccesslink.com 获取 Polar 凭据（将重定向 URI 设置为 http://localhost:8000/admin/oauth/callback）
3. 输入凭据并点击“Connect with Polar”
4. 点击“Sync Now”以拉取你的数据

服务每小时自动同步一次数据。

仪表板

/admin/dashboard 中的管理面板按标签页组织（移动端使用悬浮标签栏）：

• 概览 - 统计卡片（HRV、静息心率、SpO2、皮肤温度、步数、负荷、睡眠评分、警觉性等）、今日准备度建议，以及“今日速览”迷你图表（睡眠阶段、心率、步数）
• 趋势与基线 - 个人基线和检测到的模式
• 睡眠 - 睡眠评分和各阶段时长图表
• 心率 - 每日 HR、HRV 和 ANS 负荷图表、生物传感面板
• 训练负荷 - 活动和心肺负荷图表

图表支持选择 7/14/30 天的时间范围，并可导出 CSV。API 密钥可在设置页面管理，并跟踪速率限制。所有前端资源均已随项目提供——仪表板可离线运行，也可在没有 CDN 的局域网上运行。

同步的数据（13 个端点）

端点	数据
睡眠	评分、阶段（浅睡/深睡/REM）、时长
夜间恢复	HRV、ANS 负荷、恢复状态
每日活动	步数、距离、卡路里、活动时间
锻炼	运动、时长、心率区间、训练负荷
心肺负荷	负荷、耐受度、负荷比、状态
SleepWise 警觉性	每小时警觉性预测
SleepWise 就寝时间	最佳睡眠时间建议
活动采样	分钟级步数数据
连续心率	全天心率（5 分钟间隔）
SpO2	血氧测试（兼容设备）
ECG	心电图测试（兼容设备）
体温	连续体温
皮肤温度	夜间皮肤温度及相对基线的偏差

配置

必需的环境变量

变量	说明	必需
DATABASE_URL	PostgreSQL 连接字符串	是
ENCRYPTION_KEY	用于加密令牌的 32 字节 Fernet 密钥	是（生产环境）

生成加密密钥：

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

可选的环境变量

变量	说明	默认值
DEPLOYMENT_MODE	self_hosted 或 saas	self_hosted
SYNC_INTERVAL_HOURS	自动同步频率	1
SYNC_ON_STARTUP	服务启动时同步	false
SYNC_DAYS_LOOKBACK	要同步的历史天数	28
LOG_LEVEL	日志详细程度	INFO
API_KEY	主 API 密钥（绕过速率限制）	无

API 身份验证

API 端点需要身份验证。 健康数据绝不应公开访问。

身份验证方式

1. 用户 API 密钥（推荐）- 在管理仪表板中创建，或通过 OAuth 流程创建
2. 主 API 密钥 - 设置 API_KEY 环境变量以获得完整访问权限（绕过速率限制）

使用 API 密钥

# With per-user API key (includes rate limit headers)
curl -H "X-API-Key: pfk_your_api_key_here" \
  http://localhost:8000/api/v1/users/{user_id}/sleep?days=7

# Response headers include:
# X-RateLimit-Limit: 1000
# X-RateLimit-Remaining: 999
# X-RateLimit-Reset: 1704067200

速率限制

• 默认：每个 API 密钥每小时 1000 个请求
• 速率限制每小时重置
• 主 API 密钥（API_KEY 环境变量）不受速率限制
• 速率限制信息会在响应头中返回

OAuth 集成（SaaS / 多用户）

适用于需要与 polar-flow-server 集成的应用（例如 Laravel、移动应用、Web 前端）。

这使任何 Polar 用户都能将其账户连接到你的应用。

OAuth 流程

┌─────────────────┐     ┌─────────────────────┐     ┌─────────────────┐
│  Your App       │────▶│  polar-flow-server  │────▶│  Polar Flow     │
│  (Laravel etc)  │     │                     │     │  (OAuth)        │
│                 │◀────│                     │◀────│                 │
└─────────────────┘     └─────────────────────┘     └─────────────────┘

步骤 1：重定向用户以启动 OAuth

GET /oauth/start?callback_url=https://yourapp.com/callback&client_id=your-app-name

参数	必需	说明
callback_url	是	OAuth 完成后的重定向目标（你应用的回调端点）
client_id	否	你的应用标识符（在交换过程中验证）

步骤 2：用户在 Polar 上授权

用户会被重定向到 Polar，使用其凭据登录并授权你的应用。

步骤 3：用户被重定向到你的回调地址

https://yourapp.com/callback?code=TEMP_CODE_HERE

步骤 4：将临时代码交换为 API 密钥（服务器到服务器）

POST /oauth/exchange
Content-Type: application/json

{
  "code": "TEMP_CODE_HERE",
  "client_id": "your-app-name"
}

响应：

{
  "api_key": "pfk_abc123...",
  "polar_user_id": "12345678",
  "expires_at": null
}

步骤 5：存储并使用 API 密钥

为该用户存储 api_key 和 polar_user_id。使用 API 密钥发起所有数据请求：

curl -H "X-API-Key: pfk_abc123..." \
  "https://your-polar-server.com/api/v1/users/12345678/sleep?days=7"

Polar 管理后台设置

在 admin.polaraccesslink.com 中，将应用的重定向 URI 设置为：

https://your-polar-server.com/oauth/callback

密钥管理

# Get key info
GET /api/v1/users/{user_id}/api-key/info
X-API-Key: pfk_...

# Regenerate key (invalidates old key)
POST /api/v1/users/{user_id}/api-key/regenerate
X-API-Key: pfk_...

# Revoke key
POST /api/v1/users/{user_id}/api-key/revoke
X-API-Key: pfk_...

API 端点

# Health check (no auth required)
curl http://localhost:8000/health

# Get sleep data (last 7 days)
curl -H "X-API-Key: pfk_..." \
  "http://localhost:8000/api/v1/users/{user_id}/sleep?days=7"

# Get activity data
curl -H "X-API-Key: pfk_..." \
  "http://localhost:8000/api/v1/users/{user_id}/activity?days=7"

# Get nightly recharge (HRV)
curl -H "X-API-Key: pfk_..." \
  "http://localhost:8000/api/v1/users/{user_id}/recharge?days=7"

# Get exercises
curl -H "X-API-Key: pfk_..." \
  "http://localhost:8000/api/v1/users/{user_id}/exercises?days=30"

# Export summary
curl -H "X-API-Key: pfk_..." \
  "http://localhost:8000/api/v1/users/{user_id}/export/summary?days=30"

开发

# Install dependencies
uv sync --all-extras

# Start PostgreSQL
docker-compose up -d postgres

# Run server with hot reload
uv run uvicorn polar_flow_server.app:app --reload

# Run tests
uv run pytest

# Type check
uv run mypy src/polar_flow_server

# Lint
uv run ruff check src/

生产环境部署

部署到任何支持运行 Docker 的平台：

# Download and run
curl -O https://raw.githubusercontent.com/StuMason/polar-flow-server/main/docker-compose.prod.yml
docker-compose -f docker-compose.prod.yml up -d

Coolify、Railway、Render 等。 - 指向 GitHub 仓库，它会基于 Dockerfile 进行构建。

生产环境必需项：

• 设置 ENCRYPTION_KEY 环境变量（否则令牌无法在重启后保留）
• 将 DATABASE_URL 设置为你的 PostgreSQL 实例

数据库迁移会在启动时自动运行。

多租户

该服务开箱即支持多个用户：

• 每个表都包含 user_id 列
• 所有查询都按 user_id 进行范围限定
• 每位用户使用独立的 API 密钥，确保用户只能访问自己的数据
• 自托管：通常只有一位用户
• 多用户：多个用户使用同一代码库

构建所用技术

• polar-flow - 用于 Polar AccessLink API 的 Python SDK
• Litestar - 异步 Web 框架
• SQLAlchemy - 异步 ORM
• HTMX - 管理后台 UI 交互
• Tailwind CSS - 样式

许可证

MIT