LogoPaperX 文档

Bark 推送通知使用文档

概述

Bark 是一个免费的 iOS 推送通知应用，本系统集成了 Bark 推送功能，可以在特定事件发生时（如题目导入完成、错误检测、查重完成等）向您的 iPhone 设备发送通知。

功能特性

  • ✅ 题目导入成功通知
  • ✅ 自定义通知铃声
  • ✅ 通知分组管理
  • ✅ 测试连接功能
  • 🔜 后台错误检测通知
  • 🔜 查重结果通知

配置步骤

1. 安装 Bark App

在 iPhone 上打开 App Store，搜索并安装 Bark 应用（免费）。

2. 获取设备密钥

  1. 打开 Bark App
  2. 首次打开会自动生成一个设备密钥
  3. 点击复制按钮，复制您的设备密钥（Device Key）

3. 配置系统

  1. 登录题库管理系统

  2. 点击侧边栏的 "推送配置" 菜单

  3. 填写以下信息：

    • 服务器地址: https://bark-worker.1060139133.workers.dev（已配置好）
    • 设备密钥: 粘贴您从 Bark App 复制的密钥
    • 启用推送通知: 开启开关
    • 默认铃声（可选）: 例如 minuet, bell, chime
    • 默认分组（可选）: 例如 题库系统

  4. 点击 "测试通知" 按钮

  5. 检查您的 iPhone 是否收到测试通知

  6. 点击 "保存配置" 按钮

开发者使用指南

发送通知的方式

方法一：使用 API 路由（推荐）

// 发送通知
await fetch("/api/notifications/bark/send", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "通知标题",
    body: "通知内容",
    group: "分组名称", // 可选
    sound: "铃声名称", // 可选
  }),
})

方法二：直接使用服务函数

import { sendBarkNotification } from '@/lib/bark-service'

const result = await sendBarkNotification({
  serverUrl: 'https://bark-worker.1060139133.workers.dev',
  deviceKey: 'your_device_key',
  options: {
    title: '通知标题',
    body: '通知内容',
    // 可选参数
    subtitle: '副标题',
    sound: 'minuet',
    group: '题库系统',
    badge: 1,
  },
})

if (result.success) {
  console.log('通知发送成功')
} else {
  console.error('通知发送失败:', result.message)
}

API 接口文档

GET /api/notifications/bark

获取当前的 Bark 配置。

响应示例:

{
  "id": "uuid",
  "server_url": "https://bark-worker.1060139133.workers.dev",
  "device_key": "your_device_key",
  "is_active": true,
  "default_sound": "minuet",
  "default_group": "题库系统",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

POST /api/notifications/bark

保存或更新 Bark 配置。

请求体:

{
  "server_url": "https://bark-worker.1060139133.workers.dev",
  "device_key": "your_device_key",
  "is_active": true,
  "default_sound": "minuet",
  "default_group": "题库系统"
}

POST /api/notifications/bark/test

测试 Bark 连接。

请求体:

{
  "server_url": "https://bark-worker.1060139133.workers.dev",
  "device_key": "your_device_key"
}

响应示例:

{
  "success": true,
  "message": "Connection successful! Notification sent to your device."
}

POST /api/notifications/bark/send

发送 Bark 通知（使用已保存的配置）。

请求体:

{
  "title": "通知标题",
  "subtitle": "副标题（可选）",
  "body": "通知内容",
  "sound": "铃声名称（可选）",
  "group": "分组名称（可选）",
  "badge": 1,
  "level": "active"
}

通知参数说明

| 参数 | 类型 | 说明 | |------|------|------| | title | string | 推送标题 | | subtitle | string | 推送副标题（可选） | | body | string | 推送内容（必填） | | markdown | string | Markdown 格式的推送内容（可选，会覆盖 body） | | level | string | 推送中断级别：active（默认）、timeSensitive（时效性）、passive（仅添加到列表）、critical（重要警告） | | volume | number | 重要警告的音量，范围 0-10 | | badge | number | 推送角标数字 | | sound | string | 铃声名称，如 minuet、bell、chime | | icon | string | 自定义图标 URL | | group | string | 消息分组 | | url | string | 点击推送时跳转的 URL |

常用场景示例

题目导入成功通知

await fetch("/api/notifications/bark/send", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "题目导入成功",
    body: `文件: example.tex\\n章节: 第一章\\n题型: 单选题`,
    group: "题目导入",
  }),
})

错误检测通知

await fetch("/api/notifications/bark/send", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "检测到错误",
    body: `发现 ${errorCount} 个错误\\n请及时处理`,
    group: "错误检测",
    level: "timeSensitive",
    badge: errorCount,
  }),
})

查重完成通知

await fetch("/api/notifications/bark/send", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "查重任务完成",
    body: `发现 ${duplicateCount} 个重复题目\\n总计扫描 ${totalCount} 个题目`,
    group: "查重检测",
    sound: "bell",
  }),
})

推送失败处理

推送通知失败不应该影响主要业务逻辑。建议使用 try-catch 处理：

try {
  await fetch("/api/notifications/bark/send", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      title: "通知标题",
      body: "通知内容",
    }),
  }).catch(err => {
    console.error("Failed to send notification:", err)
  })
} catch (error) {
  // 通知失败不影响主流程
  console.error("Notification error:", error)
}

数据库表结构

CREATE TABLE bark_config (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    server_url TEXT NOT NULL,
    device_key TEXT NOT NULL,
    is_active BOOLEAN DEFAULT true,
    default_sound TEXT,
    default_group TEXT,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

故障排查

1. 测试通知失败

  • 检查设备密钥是否正确
  • 确认服务器地址是否可访问
  • 检查 iPhone 网络连接
  • 确认 Bark App 已安装并正常运行

2. 没有收到通知

  • 检查"启用推送通知"开关是否打开
  • 确认 is_active 字段为 true
  • 查看浏览器控制台是否有错误日志
  • 检查 iPhone 的通知权限设置

3. 通知延迟

  • Bark 推送依赖 APNs（Apple Push Notification service），可能存在延迟
  • 检查网络连接质量
  • 自建服务器可能比官方服务器更快

相关资源

技术支持

如遇到问题，请检查：

  1. 浏览器控制台的错误日志
  2. 服务器日志（如果有访问权限）
  3. Bark App 的通知历史记录

如需进一步帮助，请联系系统管理员。