Gotify项目中JSON消息扩展字段的多媒体集成方案

背景与问题场景

在基于Gotify构建的通知系统中，开发者常需要实现富媒体通知功能。典型场景如安防监控系统（示例中的Blueiris）触发告警时，需要同时推送事件图片到移动设备。原始问题暴露了两个技术痛点：

1. Android系统通知栏无法正确渲染Markdown格式的图片引用
2. 多扩展字段(extras)的JSON结构编排问题

核心解决方案

通过Gotify的扩展字段机制实现双通道图片传输：

1. 消息正文：采用Markdown语法内联图片，确保应用内展示效果
2. 通知扩展：通过client::notification.bigImageUrl字段提供系统级通知大图支持

正确JSON结构示例：

{
  "title": "监控告警",
  "message": "![告警截图](https://example.com/alert.jpg)",
  "priority": 5,
  "extras": {
    "client::display": {
      "contentType": "text/markdown"
    },
    "client::notification": {
      "bigImageUrl": "https://example.com/alert.jpg"
    }
  }
}

技术要点解析

1. 数据类型规范：

   • priority字段必须为整型数值
   • 图片URL需确保公网可访问性
   • 建议使用标准图片格式（JPG/PNG）

2. 字段作用域：

   • client::display控制应用内渲染行为
   • client::notification影响系统通知样式

3. 内容协商机制：

   • Markdown渲染需显式声明contentType
   • 同一资源建议同时提供内联和扩展两种引用方式

系统集成实践

以Blueiris监控系统为例的完整实现方案：

1. 文件输出层：

   • 配置告警动作输出PS1脚本模板
   • 保留系统变量插值功能（如&ALERT_PATH）

2. 媒体处理层：

   • 独立服务将图片发布到Web可访问位置
   • 确保URL规范化（去除特殊字符）

3. 执行控制层：

   • 使用PowerShell 7+运行时
   • 通过cURL发送结构化请求

典型PowerShell脚本示例：

$json = @{
    title = "&CAM &MEMO"
    message = "![监控截图](https://cdn.example.com/&ALERT_PATH)"
    priority = 5
    extras = @{
        "client::display" = @{ contentType = "text/markdown" }
        "client::notification" = @{ bigImageUrl = "https://cdn.example.com/&ALERT_PATH" }
    }
} | ConvertTo-Json

curl.exe -X POST -H "Content-Type: application/json" -d $json $webhookUrl

兼容性建议

1. 移动端适配：

   • Android系统通知对大图有尺寸限制（建议不超过2MB）
   • 考虑添加图片压缩环节

2. 安全增强：

   • 对图片URL实施签名验证
   • 设置合理的访问有效期

3. 错误处理：

   • 添加HTTP请求重试机制
   • 实现媒体上传的校验流程

该方案已在实际生产环境中验证，可稳定支持每分钟数十次告警事件的图片推送需求。开发者可根据具体业务场景调整媒体处理策略和通知优先级设置。