企业官网建设流程全解析

从API Key到第一次数据请求：Open Wearables开发者门户实战教程

【免费下载链接】open-wearablesSelf-hosted platform to unify wearable health data through one AI-ready API.项目地址: https://gitcode.com/gh_mirrors/op/open-wearables

Open Wearables 是一个自托管的穿戴设备健康数据统一平台，通过一个 AI-ready API 聚合 Garmin、Oura、Apple Health 等 15+ 厂商的睡眠、心率、运动数据。本教程带你在 5 分钟内完成从零到一：登录开发者门户（Developer Portal）、创建第一个 API Key，并发出第一次成功的数据请求。

1. 五分钟跑起来：Docker 一键部署

所有后续操作的前提是平台已在本地运行。整个过程只有三步：

1. 克隆仓库并进入目录：

git clone https://gitcode.com/gh_mirrors/op/open-wearables cd open-wearables

2. 复制环境变量模板（后端 + 前端）：

cp ./backend/config/.env.example ./backend/config/.env cp ./frontend/.env.example ./frontend/.env

3. 启动服务：

docker compose up -d

启动完成后会得到三个关键地址（完整步骤见 快速入门文档）：

💡 首次启动会用ADMIN_EMAIL/ADMIN_PASSWORD环境变量自动创建管理员账号（默认admin@admin.com）。登录后请第一时间在Settings → Change Password修改默认密码。

2. 创建你的第一个 API Key：只显示一次

API Key 是调用 REST API 的"通行证"。进入http://localhost:3000登录开发者门户后，路径是固定的：

Settings → Credentials → API Keys → Create API Key

给它起个名字（比如my-first-key），确认后对话框会展示完整密钥——这里有两个新手最容易踩的坑：

• ⚠️密钥只显示一次。Open Wearables 只存储密钥的哈希值，之后再也查不到。门户列表里只会显示sk-a1b2c3d…这样的一段前缀帮你认人。看到就立刻复制保存。
• 🔄 如果不小心弄丢了，不用慌：点Rotate会生成一个新密钥，旧密钥立即失效，把用到旧密钥的地方更新即可。

创建成功后，Credentials 页面顶部还能直接复制API Base URL，本地就是http://localhost:8000/api/v1。更多凭据管理细节见 Credentials 文档。

📌 同一个页面下半部分还能创建Application（app_id+app_secret），那是给移动端 SDK 用的凭据，和 API Key 不是一回事。

3. 第一个数据请求：用 API Key 鉴权

现在到了见证时刻。Open Wearables 使用自定义请求头鉴权——注意，不是常见的Authorization: Bearer格式：

curl http://localhost:8000/api/v1/users \ -H "X-Open-Wearables-API-Key: sk-a1b2c3d4e5f60718293a4b5c6d7e8f90"

把sk-...换成你刚复制的密钥。返回结构如下（用户列表采用页码分页）：

{ "items": [], "total": 0, "page": 1, "limit": 20, "pages": 0, "has_next": false }

看到total: 0也是完全正常的——新实例还没有用户。如果你看到401 Unauthorized，说明请求头拼写或密钥有误。

4. 让请求返回真实数据：种子数据与 Timeseries

想让返回结果里有内容？开发者门户内置了种子数据生成器，无需写任何脚本：

1. 进入Settings → Seed Data
2. 选择一个预设，新手推荐Minimal (Quick)（5 次运动 + 5 段睡眠，几秒跑完），或者更真实的Active Athlete
3. 点击生成，数据通过 Celery 在后台落库

生成后回到 API 发两个请求：

① 获取用户列表（total不再是 0，记下某个user_id）：

curl http://localhost:8000/api/v1/users \ -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

② 拉取该用户的时序健康数据（心率、步数等，需指定时间范围）：

curl "http://localhost:8000/api/v1/users/{user_id}/timeseries?start_time=2025-01-01T00:00:00Z&end_time=2025-02-01T00:00:00Z&types=steps" \ -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

数据类端点统一返回data + pagination + metadata结构，翻页时用上一页的next_cursor作为cursor参数继续拉取。完整参数说明（resolution、provider、filter_by_priority等）可以直接在 Swagger UI 里点选调试，端点源码位于 timeseries.py。

5. 快速排错清单：401、404 和空数据怎么办

6. 下一步：把穿戴数据接进你的应用

第一次请求成功后，你已经掌握了 Open Wearables 的完整接入链路。接下来推荐按这个顺序探索开发者门户（概览文档）：

• Users页面：创建终端用户、分享连接链接，把真实穿戴设备（Oura、Garmin 等）接入平台
• Webhooks页面：注册回调地址，新数据入库时实时推送事件给你的服务（Webhooks 指南）
• Syncs页面：监控每个用户、每个厂商的同步状态
• Settings → Priorities：多家设备数据重叠时，决定谁的优先级更高

从 API Key 到第一次数据请求，你已经跨过了接入穿戴健康数据最难的一步。剩下的，就是把心率和睡眠数据变成你的产品功能 🚀

【免费下载链接】open-wearablesSelf-hosted platform to unify wearable health data through one AI-ready API.项目地址: https://gitcode.com/gh_mirrors/op/open-wearables