Bark Worker

bark-worker 是 Finb/bark-server 的 Cloudflare Workers 独立实现。项目使用 TypeScript、Hono 和 Cloudflare D1，面向个人 Bark 服务，在免费套餐限制内保持 Bark HTTP API、APNs 推送和 MCP notify 工具兼容。

设备数据存储在 D1 中，无需配置 Workers KV、Durable Objects、R2、Queues 或 Containers。首次部署请参阅 部署手册。

主要能力

• 支持 Bark App 使用的旧版注册和推送 URL。
• 支持 POST /register、POST /push 和批量推送。
• 支持 /mcp 与 /mcp/:device_key。
• 使用 D1 保存 device_key → device_token。
• 使用 Web Crypto 生成 APNs ES256 JWT。
• 自动限制请求体、批量并发和设备数量。
• 自动监测上游；行为相关文件变化时暂停同步并创建兼容性审查 Issue。
• 提供 Bbolt 导出、恢复和 D1 导入工具。

API

方法	路径	用途
GET	/	返回 ok。
GET	/ping	返回 Bark 兼容的 pong JSON。
GET	/healthz	运行状态检查。
GET	/info	返回版本、Git SHA、上游 SHA 和设备数量。
GET、POST	/register	注册或更新设备。
GET	/register/:device_key	检查设备 key。
POST	/push	Bark V2 单设备或批量推送。
GET、POST	/:device_key/...	Bark 旧版路径推送。
POST	/mcp、/mcp/:device_key	MCP Streamable HTTP JSON 响应。

完整参数见 API V2 和 MCP。

免费额度设计

• 每次普通推送执行一次 D1 主键读取和一次 APNs 请求。
• 批量推送默认最多 40 个设备，同时最多建立 6 个 APNs 请求。
• 请求正文默认最多 64 KiB；APNs payload 严格限制为 4096 字节。
• 新安装默认最多注册 16 个设备。已有 key 不受该数量限制，可以继续更新 token。
• APNs JWT 在 Worker isolate 中复用 50 分钟，不占用 D1 或 KV 配额。

注册模式

REGISTRATION_MODE 支持以下值：

• open：允许已有 key 更新 token，也允许新设备注册。
• existing-only：只允许已有 key 更新 token。
• closed：禁止所有注册写入；GET /register/:device_key 仍可检查 key。

首次配置 Bark App 时使用 open。完成设备注册或旧数据导入后，生产环境建议改为 existing-only。

请求保护与费用边界

注册、推送、MCP 和 /info 等接口在访问数据库或 APNs 前调用 REQUEST_LIMITER。默认限制同一 IP 在单个 Cloudflare 节点每分钟最多 120 次请求；本地、测试和生产环境使用独立计数器。绑定缺失或限流服务出错时返回 503，超限时返回 429 并附带 Retry-After: 60。GET /、GET /ping 和 GET /healthz 不访问数据库，仍可用于健康检查。

限流用于降低滥用风险，不能作为全账户费用上限。需要阻止 Workers 和 D1 超额计费时，应保留 Workers Free 套餐；额度耗尽后操作会失败。付费套餐按超额用量计费，预算告警只通知、不停止用量。不要为此项目启用独立计费产品。

版本预览 URL 默认禁用，避免历史实现绕过当前入口保护。正式 Worker 地址仍用于 Bark App 和部署验收。

部署

部署前需要 Cloudflare 账户、两个 D1 数据库和已认证的 Wrangler。按照 部署手册 创建资源、配置 APNs secret、运行迁移并验证公开端点。

pnpm install
pnpm build
pnpm exec wrangler deploy --env staging
pnpm exec wrangler deploy --env production

wrangler.jsonc 是 Worker 配置的唯一事实来源。不要在 Cloudflare Dashboard 中长期维护与仓库不同的变量或绑定。

从原版 Bark 迁移

项目提供只读 Bbolt 导出工具。工具不会覆盖已有输出文件，也不会在日志中打印 device token。

go -C tools/bark-db run . export -input /path/to/bark.db -output devices.bark-export.json
node scripts/device-export-to-d1.mjs devices.bark-export.json devices.bark-backup.sql
pnpm exec wrangler d1 execute DB --env production --remote --file devices.bark-backup.sql

详细停止条件、校验和回滚步骤见 迁移手册。

本地开发

pnpm install
pnpm dev
pnpm build

功能由维护者人工验证；CodeQL 独立扫描，不作为部署或依赖合并的前置条件。

上游同步

upstream/UPSTREAM.lock.json 固定上游仓库、精确 SHA、受监控文件哈希和提取后的接口契约。

• 文档或测试变化且语义文件未变化时，定时工作流可以安全更新锁文件。
• 路由、数据库接口、APNs 或服务启动逻辑所在文件变化时，工作流创建 Issue，并阻止该次同步更新与部署。
• 维护者审查差异并完成必要适配后，按精确提交更新锁文件；尚未审查的变化继续阻断。

维护规则见 上游同步说明。

依赖自动维护

Dependabot 每天检查 npm、Go module 和 GitHub Actions 依赖。自动合并使用维护 App 为本仓库签发的短期令牌，只处理同仓库、非草稿的 Dependabot PR，并核对依赖文件范围、签名与当前 head SHA。

更新无需人工批准，不等待 CodeQL 或构建结果。合并产生的 push 事件触发独立扫描及现有发布工作流；发布继续遵守 AUTO_DEPLOY_ENABLED 设置。每 6 小时自动核对开放 PR，补偿遗漏事件。

安全

• APNS_PRIVATE_KEY 只存放在 Cloudflare secret 或临时部署文件中。
• 日志不记录完整 URL、device key、device token、Authorization 或通知正文。
• Basic Auth 用户名、密码和 MCP_SESSION_SECRET 必须使用 Worker secret。
• 仓库启用独立 CodeQL 扫描、Dependabot 和 GitHub Secret Scanning。

安全问题请按照 SECURITY.md 私下报告。

许可证与归属

项目采用 MIT License。Bark API 行为和 APNs 配置以 Finb/bark-server 为兼容目标；初始 TypeScript 兼容层源自 MIT 项目 frankwei98/bark-serverless。代码来源与归属见 NOTICE，上游跟踪范围见 UPSTREAM。