appleboy/gorush

gorush - 推送通知服务器

基于Go语言(Golang)的Gin框架开发的推送通知微服务器。

镜像概述和主要用途

gorush是一个轻量级的推送通知服务器，支持iOS(APNS)和Android(FCM/GCM)平台，提供高性能的推送服务。该服务器采用Go语言开发，使用Gin框架构建RESTful API，支持多平台推送、消息队列、统计监控等功能，适用于需要向移动设备发送推送通知的应用服务。

核心功能和特性

• 支持Google Cloud Messaging(Firebase Cloud Messaging)，适用于Android设备
• 支持HTTP/2 Apple Push Notification Service，适用于iOS设备
• 支持YAML配置文件管理
• 提供命令行工具发送单条通知
• 提供Web API接口发送批量推送通知
• 支持优雅重启和零停机部署
• 支持HTTP/2或HTTP/1.1协议
• 内置通知队列和多工作线程处理
• 提供通知统计功能，显示成功和失败计数
• 支持多种统计数据存储引擎：内存、Redis、BoltDB、BuntDB或LevelDB
• 支持iOS证书的p12或pem格式
• 提供系统状态和性能监控API
• 支持HTTP代理访问Google服务器(GCM)
• 支持失败通知重试机制
• 支持Prometheus指标暴露

支持平台

• APNS (Apple Push Notification Service)
• GCM (Google Cloud Messaging) / Firebase Cloud Messaging

使用场景和适用范围

• 移动应用后端推送服务
• 需要同时支持iOS和Android推送的服务
• 需要高并发推送处理能力的应用
• 需要推送统计和监控的服务
• 需要可靠推送和失败重试机制的场景

详细使用方法和配置说明

基本用法

下载二进制文件

可从https://github.com/appleboy/gorush/releases%E4%B8%8B%E8%BD%BD%E9%A2%84%E7%BC%96%E8%AF%91%E4%BA%8C%E8%BF%9B%E5%88%B6%E6%96%87%E4%BB%B6%E3%80%82

使用Go安装:

bash
$ go get -u -v github.com/appleboy/gorush

Linux系统:

bash
$ wget https://github.com/appleboy/gorush/releases/download/v1.7.3/gorush-v1.7.3-linux-amd64 -O gorush

OS X系统:

bash
$ wget https://github.com/appleboy/gorush/releases/download/v1.7.3/gorush-v1.7.3-darwin-amd64 -O gorush

Windows系统:

bash
$ wget https://github.com/appleboy/gorush/releases/download/v1.7.3/gorush-v1.7.3-windows-amd64.exe -O gorush.exe

命令行使用

  ________                              .__
 /  _____/   ____ _______  __ __  ______|  |__
/   \  ___  /  _ \\_  __ \|  |  \/  ___/|  |  \
\    \_\  \(  <_> )|  | \/|  |  /\___ \ |   Y  \
 \______  / \____/ |__|   |____//____  >|___|  /
        \/                           \/      \/

Usage: gorush [options]

服务器选项:
    -p, --port <port>                客户端连接端口 (默认: 8088)
    -c, --config <file>              配置文件路径
    -m, --message <message>          通知消息内容
    -t, --token <token>              设备令牌
    --title <title>                  通知标题
    --proxy <proxy>                  代理URL (仅用于GCM)
    --pid <pid path>                 进程ID文件路径
iOS选项:
    -i, --key <file>                 证书密钥文件路径
    -P, --password <password>        证书密钥密码
    --topic <topic>                  iOS主题
    --ios                            启用iOS推送 (默认: false)
    --production                     iOS生产环境模式 (默认: false)
Android选项:
    -k, --apikey <api_key>           Android API密钥
    --android                        启用Android推送 (默认: false)
通用选项:
    -h, --help                       显示帮助信息
    -v, --version                    显示版本信息

发送Android通知

使用以下命令发送单条Android通知：

bash
$ gorush -android -m="通知消息内容" -k="API密钥" -t="设备令牌"

参数说明：

• -m: 通知消息内容
• -k: Firebase Cloud Messaging API密钥
• -t: 设备令牌
• --title: 通知标题
• --proxy: 设置HTTP代理URL(仅用于GCM)

发送iOS通知

使用以下命令发送单条iOS通知：

bash
$ gorush -ios -m="通知消息内容" -i="证书文件路径" -t="设备令牌" -topic="APNs主题"

参数说明：

• -m: 通知消息内容
• -i: Apple推送通知证书路径(pem或p12文件)
• -t: 设备令牌
• --title: 通知标题
• --topic: 远程通知主题
• --password: 证书密码

默认使用APNs开发环境。如需使用生产环境，请添加-production标志：

bash
$ gorush -ios -m="通知消息内容" -i="证书文件路径" -t="设备令牌" -production

运行gorush Web服务器

确保配置文件存在(默认config.yml)，默认端口为8088：

bash
$ gorush -c config.yml

使用httpie工具获取API服务器状态：

bash
$ http -v --verify=no --json GET https://localhost:8088/api/stat/go

Web API

gorush提供以下API端点：

• GET /api/stat/go - 获取Golang运行时信息(cpu, 内存, gc等)
• GET /api/stat/app - 获取通知成功和失败统计
• GET /api/config - 获取服务器配置信息
• GET /sys/stats - 获取系统状态和性能统计
• GET /metrics - 获取Prometheus指标
• POST /api/push - 发送推送通知

GET /api/stat/go

返回Golang运行时信息，HTTP状态码200：

json
{
  "time": 1460686815848046600,
  "go_version": "go1.6.1",
  "go_os": "darwin",
  "go_arch": "amd64",
  "cpu_num": 4,
  "goroutine_num": 15,
  "gomaxprocs": 4,
  "cgo_call_num": 1,
  "memory_alloc": 7455192,
  "memory_total_alloc": 8935464,
  "memory_sys": 12560632,
  "memory_lookups": 17,
  "memory_mallocs": 31426,
  "memory_frees": 11772,
  "memory_stack": 524288,
  "heap_alloc": 7455192,
  "heap_sys": 8912896,
  "heap_idle": 909312,
  "heap_inuse": 8003584,
  "heap_released": 0,
  "heap_objects": 19654,
  "gc_next": 9754725,
  "gc_last": 1460686815762559700,
  "gc_num": 2,
  "gc_per_second": 0,
  "gc_pause_per_second": 0,
  "gc_pause": [
    0.326576,
    0.227096
  ]
}

GET /api/stat/app

返回通知成功和失败统计信息：

json
{
  "version": "v1.6.2",
  "queue_max": 8192,
  "queue_usage": 0,
  "total_count": 77,
  "ios": {
    "push_success": 19,
    "push_error": 38
  },
  "android": {
    "push_success": 10,
    "push_error": 10
  }
}

GET /sys/stats

返回系统状态和性能统计：

json
{
  "pid": 80332,
  "uptime": "1m42.428010614s",
  "uptime_sec": 102.428010614,
  "time": "2016-06-26 12:27:11.675973571 +0800 CST",
  "unixtime": 1466915231,
  "status_code_count": { },
  "total_status_code_count": {
    "200": 5
  },
  "count": 0,
  "total_count": 5,
  "total_response_time": "10.422441ms",
  "total_response_time_sec": 0.010422441000000001,
  "average_response_time": "2.084488ms",
  "average_response_time_sec": 0.0020844880000000002
}

GET /metrics

返回Prometheus监控指标，可用于系统监控和告警。

POST /api/push

发送推送通知的主要API端点。请求体需包含notifications数组，每个元素代表一个推送任务。

请求体参数

每个通知对象支持以下参数：

iOS alert payload

iOS通知alert对象支持以下参数：

Android notification payload

Android通知对象支持以下参数：

iOS示例

发送普通iOS通知：

json
{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 1,
      "message": "Hello World iOS!"
    }
  ]
}

带alert和badge的iOS通知：

json
{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 1,
      "badge": 5,
      "alert": {
        "title": "游戏邀请",
        "body": "Bob想和你玩扑克",
        "action-loc-key": "PLAY"
      }
    }
  ]
}

带自定义数据的iOS通知：

json
{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 1,
      "message": "Hello World iOS!",
      "data": {
        "key1": "welcome",
        "key2": 2
      }
    }
  ]
}

Android示例

发送普通Android通知：

json
{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 2,
      "message": "Hello World Android!",
      "title": "您有新消息"
    }
  ]
}

带notification payload的Android通知：

json
{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 2,
      "message": "Hello World Android!",
      "title": "您有新消息",
      "notification": {
        "icon": "myicon",
        "color": "#112244"
      }
    }
  ]
}

带自定义数据的Android通知：

json
{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 2,
      "message": "Hello World Android!",
      "title": "您有新消息",
      "data": {
        "Nick": "Mario",
        "body": "精彩比赛！",
        "Room": "PortugalVSDenmark"
      }
    }
  ]
}

发送多条不同平台的通知：

json
{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 1,
      "message": "Hello World iOS!"
    },
    {
      "tokens": ["token_c", "token_d"],
      "platform": 2,
      "message": "Hello World Android!"
    }
  ]
}

响应体

成功响应：

json
{
  "success": "ok"
}

错误响应状态码：

配置说明

gorush使用YAML格式的配置文件，默认路径为