跳转到主要内容

通知系统

测试通知 - /api/notifications/test​

  • 端点: /api/notifications/test

  • 方法: POST

  • 描述: 发送测试通知（简单、基于模板或电子邮件）以验证通知配置。

  • 认证: 需要管理员会话和 CSRF 令牌

  • 请求体: 简单测试：

    {
      "type": "simple",
      "ntfyConfig": {
        "url": "https://ntfy.sh",
        "topic": "test-topic",
        "accessToken": "optional-access-token"
      }
    }

模板测试：

{
  "type": "template",
  "ntfyConfig": {
    "url": "https://ntfy.sh",
    "topic": "test-topic",
    "accessToken": "optional-access-token"
  },
  "template": {
    "title": "Test Title",
    "message": "Test message with {variable}",
    "priority": "default",
    "tags": "test"
  }
}

电子邮件测试：

{
  "type": "email"
}

  • 响应: 简单测试：

    {
      "message": "Test notification sent successfully"
    }

模板测试：

{
  "success": true,
  "message": "Test notifications sent successfully via NTFY and Email",
  "channels": ["NTFY", "Email"]
}

电子邮件测试：

{
  "message": "Test email sent successfully"
}

测试电子邮件内容显示：

  • SMTP 服务器主机名和端口
  • 连接类型（普通 SMTP、STARTTLS 或直接 SSL/TLS）
  • SMTP 认证要求状态
  • SMTP 用户名（仅在需要认证时显示）
  • 接收者邮箱
  • 用于电子邮件的发件人地址和发件人姓名
  • 测试时间戳
  • 错误响应:
    • 401: 未授权 - 无效会话或 CSRF 令牌
    • 400: 需要 NTFY 配置，配置无效或电子邮件未配置
    • 500: 发送测试通知失败，包含错误详情
  • 注意事项:
    • 支持简单测试消息、基于模板的通知和电子邮件测试
    • 模板测试使用示例数据替换模板变量
    • 在测试消息中包含时间戳
    • NTFY 测试使用存储的 NTFY 配置；不使用客户端提供的 NTFY URL
    • 存储时使用 accessToken 字段进行认证
    • 对于模板测试，向 NTFY 和电子邮件（如果已配置）发送通知
    • 电子邮件测试需要设置 SMTP 配置
    • 测试电子邮件端点在读取 SMTP 配置之前清除请求缓存，确保外部脚本可以更新配置并在测试电子邮件中立即反映出来
    • 模板测试和每日摘要立即发送绕过每个备份抑制

预览通知模板 - /api/notifications/preview​

  • 端点: /api/notifications/preview
  • 方法: POST
  • 描述: 使用生产 Markdown 渲染器渲染通知模板但不发送。主体包括 kind（success、warning、overdueBackup 或 dailySummaryEmail）和正在编辑的模板。每日摘要预览使用当前真实快照；其他类型使用确定性示例值。电子邮件 HTML 适用于沙盒 iframe。成功、警告/错误和过期还返回 NTFY 负载（ntfyMessage）；任何 GFM 表格标题都被省略，正文行是纯文本。
  • 身份验证：需要有效会话和CSRF令牌

检查过期备份 - /api/notifications/check-overdue​

  • 端点: /api/notifications/check-overdue

  • 方法: POST

  • 描述: 手动触发过期备份检查并发送通知。

  • 身份验证：需要有效的会话和 CSRF 令牌

  • 响应：

    {
      "message": "Overdue backup check completed",
      "statistics": {
        "totalBackupConfigs": 5,
        "checkedBackups": 5,
        "overdueBackupsFound": 2,
        "notificationsSent": 2
      }
    }

  • 错误响应:

    • 500: 检查过期备份失败

  • 注意事项:

    • 手动触发过期备份检查
    • 返回检查过程的统计信息
    • 为发现的过期备份发送通知

通知渠道警报 - /api/notification-channel-alerts​

  • 端点：/api/notification-channel-alerts

  • 方法：GET、POST

  • 描述：列出已登录管理员未解决的电子邮件和 NTFY 投递失败记录，或清除所列渠道的警报，直到记录新的失败为止。

  • 身份验证：需要管理员会话。POST 还需要在 X-CSRF-Token 标头中包含 CSRF 令牌。

  • 请求体 (POST)：

    {
      "channels": ["email", "ntfy"]
    }

channels 必须包含 email 和 ntfy 中的一个或两个。

  • 响应：

    {
      "alerts": [
        {
          "channel": "email",
          "error": "SMTP authentication failed",
          "latestTimestamp": "2026-09-23 22:10:00",
          "failureCount": 3,
          "settingsTab": "email",
          "host": "smtp.gmail.com"
        }
      ]
    }

每条警报包含 channel、error（最多 500 个字符）、latestTimestamp、failureCount 和 settingsTab（email 或 ntfy）。电子邮件警报可能包含 host。NTFY 警报可能包含 topic。

  • 错误响应：
    • 400 INVALID_CONFIGURATION：POST 请求体缺失，或 channels 为空或包含未知值
    • 500 INTERNAL_ERROR：读取或清除警报失败
  • 注意事项：
    • GET 返回对该管理员仍处于失败状态的渠道
    • POST 为当前未解决的每个所列渠道记录一次针对该管理员的清除操作，然后返回剩余的警报
    • 后续的失败会再次显示该渠道，即使错误文本未更改
    • 后续该渠道的成功投递会使其保持隐藏状态
    • 清除标记存储在配置中，且不包含机密信息

清除过期时间戳 - /api/notifications/clear-overdue-timestamps​

  • 端点: /api/notifications/clear-overdue-timestamps

  • 方法: POST

  • 描述: 清除所有过期备份通知时间戳，允许再次发送通知。

  • 身份验证：需要有效的会话和 CSRF 令牌

  • 响应：

    {
      "message": "Overdue backup notification timestamps cleared successfully"
    }

  • 错误响应:

    • 500: 清除过期备份时间戳失败

  • 注意事项:

    • 清除所有过期备份通知时间戳
    • 允许再次发送通知
    • 用于测试通知系统