如何用 curl 发送第一个 Boop 事件：让 iPhone 立刻收到推送的入门教程

Boop 是一个开源的自托管通知收件箱（self-hosted notification inbox）：当你的应用里发生了一件事，Boop 就会把这条Boop 事件推送到你的 iPhone。本教程带你从零开始部署 Boop，并用一行curl 发送 Boop 事件，体验 Boop 事件推送通知的完整流程——全程只需一个 Go 二进制、一个 SQLite 文件、一个 Docker 容器。

1. 先搞懂：Boop 事件是怎么到达 iPhone 的

从上面的架构图可以看到，整条链路非常简洁：

1. 你的脚本 / 应用（curl、CI、后端服务）用POST /api/v1/events把 JSON 事件发给Boop server；
2. server 把事件存进SQLite，同时通过Apple APNs直接推送；
3. iOS 端 App收到推送后，用设备凭据从你的 server 拉取完整事件详情。

没有中间账号体系、没有遥测、没有托管中转。完整架构数据见 docs/architecture/boop.architecture.json，交互版可打开 docs/architecture/index.html 本地查看。

💡 关键点：推送走的是 APNs 直连，所以要让 iPhone 收到通知，需要配置 Apple 的.p8密钥（第 5 节讲）。没配置时，事件照常入库、可在 Web UI 查看，只是跳过推送。

2. 最快部署方法：Docker 一键启动 Boop

在服务器上执行：

git clone https://gitcode.com/gh_mirrors/boop2/boop cd boop cp .env.example .env mkdir -p data && chown 1000:1000 data # Linux 主机需要；容器以 uid 1000 运行 docker compose up -d --build

浏览器打开http://localhost:8080，首次访问会进入设置向导：检查 server、配置 APNs、配对手机、创建第一个项目、发送测试通知。

数据都保存在./data/boop.db，备份时复制这个文件即可。.env里各配置项的说明可查看 .env.example，容器编排定义见 docker-compose.yml。

3. 创建项目并复制 API Key

在 Web UI 中创建一个项目，复制它的API key（只展示一次！）。

• 项目 key 形如boop_proj_...，只能创建事件，不能读事件、不能管理设备——泄露风险可控；
• 如果设置了BOOP_ADMIN_USER/BOOP_ADMIN_PASSWORD，Web UI 会先出现登录页。

4. 用 curl 发送第一个 Boop 事件

最小可用命令，一条即可：

curl -i http://localhost:8080/api/v1/events \ -H "Authorization: Bearer boop_proj_..." \ -H "Content-Type: application/json" \ -d '{"title": "Hello from curl", "level": "info", "source": "curl"}'

一切正常的话，你会收到：

HTTP/1.1 201 Created {"id": "evt_w4zosnovd6huj6dh", "created_at": "2026-08-28T14:10:46.716098000Z"}

然后去 Web UI 收件箱（或配好 APNs 后的 iPhone）确认——你的第一个 Boop 事件已经送达了。🎉

官方把这套 curl 请求称作"quick check"，并规定它必须是任何 Boop 客户端都能精确复现的最小请求，规范全文见 integration-llms.md。

发送丰富的 Boop 事件

title是唯一的必填字段（1–200 字符），其他字段按需用：

curl http://localhost:8080/api/v1/events \ -H "Authorization: Bearer boop_proj_..." -H "Content-Type: application/json" \ -d '{ "title": "KeyError", "body": "key :can_palette? not found", "level": "error", "source": "error_tracker", "fingerprint": "uini-keyerror", "data": { "exception": {"type": "KeyError", "message": "key :can_palette? not found"}, "tags": {"environment": "production"} } }'

各字段速查（完整规则见 integration-llms.md）：

关于level：等级定义在 server/internal/events/levels/levels.go，其中critical会触发更醒目的时效性（time-sensitive）推送。传错等级会直接报错，不会静默降级。

5. 让 iPhone 真正收到推送：配置 APNs + 配对

curl 发送只是"入库"，推送给 iPhone 还需要两步。

5.1 配置 Apple APNs 密钥

1. 在 Apple Developer 门户为 Boop iOS 构建创建 App identifier，并启用Push Notifications；
2. 在 Keys 下创建 APNs 认证密钥，下载.p8（只能下载一次），记下 Key id 和 Team id；
3. 把.p8放到./secrets/apns.p8，取消 docker-compose.yml 中 secrets 挂载的注释；
4. 在.env填APNS_TEAM_ID、APNS_KEY_ID、APNS_BUNDLE_ID、APNS_PRIVATE_KEY_PATH=/run/secrets/apns.p8；
5. 重启：docker compose up -d，Settings 页面应显示APNs · Configured。

⚠️ Xcode 调试版安装的 App 记得把APNS_ENVIRONMENT设为sandbox。

5.2 用二维码配对 iPhone

1. Web UI 打开Devices → Pair iPhone，出现一次性二维码（10 分钟有效、单次使用）；
2. 在自己签名构建的 Boop iOS App 里点Pair server扫码；
3. 允许通知。App 会向 APNs 注册并把 token 上报给你的 server；
4. 回到 Web UISettings → Send test notification，手机"叮"一声就大功告成。📱

iOS 端的构建与配对细节见 ios/README.md。

6. curl 常见错误排查速查

另外两个高频疑问：

• iPhone 没收到推送？推送是异步的，201只代表入库成功；先检查 Settings 里 APNs 是否 Configured、设备是否完成配对，也可在事件详情页查看 push 投递记录（GET /api/v1/events/:id/deliveries）。
• 事件很吵想屏蔽？用 Silence 规则按fingerprint/title/source匹配，事件照常入库但不再推送，管理入口在 Settings → Silences。

7. 进阶：把 curl 变成一行式工作流

写脚本时可以把命令包成 shell 函数，例如：

boop() { curl -fsS "$BOOP_URL/api/v1/events" -H "Authorization: Bearer $BOOP_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"title\": \"$1\", \"body\": \"${2:-}\", \"level\": \"${3:-info}\"}"; } pg_dump mydb > backup.sql && boop "Backup complete" "" success || boop "Backup failed" "$(tail -1 backup.log)" error

GitHub Actions、cron、任意 CI 系统都可以照此接入。如果你要写其他语言的正式客户端，直接把 integration-llms.md 丢给 LLM 即可——它就是官方的人读版客户端规范。

小结

用 3 分钟回顾一下本文路线：

• ✅docker compose up -d --build启动 Boop（一个容器、一个 SQLite 文件）；
• ✅ Web UI 创建项目、复制boop_proj_API key；
• ✅ 一条 curlPOST /api/v1/events发送第一个 Boop 事件，看到201 Created；
• ✅ 配置.p8+ 扫码配对 iPhone，实现真正的 Boop 事件推送通知。

从此，你的备份、部署、CI 里任何值得注意的事，都能实时出现在手机通知栏。🚀