高性能、轻量级推送通知服务器gorush快速使用指南

gorush 是一个用 Go 语言编写的 高性能、轻量级推送通知服务器，支持 Apple APNs（iOS）、Firebase FCM（Android）和 Huawei HMS（鸿蒙/安卓） 三大平台。它提供 Web API、gRPC、命令行等多种调用方式，适用于微服务架构中的消息推送场景。

以下是完整使用指南，涵盖安装、配置、启动和发送通知等核心操作。

一、核心特性

✅ 支持 APNs（HTTP/2）、FCM（Firebase Cloud Messaging）、HMS（Huawei Mobile Services）
✅ 提供 RESTful API 和 gRPC 接口
✅ 内置 Prometheus 指标（/metrics）
✅ 支持 队列 + 多 Worker 并发推送
✅ 支持 YAML 配置文件 或 命令行参数
✅ 可运行于 Docker、Kubernetes、AWS Lambda、本地二进制
✅ 支持 TLS 自动签发（Let's Encrypt）
✅ 支持 失败重试、异步回调（feedback_hook_url）

二、快速开始（Docker 方式）

1. 拉取镜像

docker pull appleboy/gorush

2. 创建最小配置文件 `config.yml`

core:
  port: "8088"
  worker_num: 4
  queue_num: 8192

android:
  enabled: true
  credential: '{"type":"service_account","project_id":"your-project-id",...}'  # FCM JSON 凭据内容（base64 或直接字符串）

ios:
  enabled: true
  key_path: "/etc/gorush/key.p8"   # 或使用 key_base64
  key_type: "p8"
  key_id: "YOUR_KEY_ID"
  team_id: "YOUR_TEAM_ID"
  production: false  # 设为 true 表示生产环境

💡 注意：

Android 使用 FCM 服务账号 JSON（从 Firebase 控制台下载）

iOS 使用 .p8 密钥文件（从 Apple Developer → Keys 下载）

3. 启动容器

docker run -d \
  --name gorush \
  -p 8088:8088 \
  -v $(pwd)/config.yml:/app/config.yml \
  -v $(pwd)/key.p8:/etc/gorush/key.p8 \
  appleboy/gorush \
  -c /app/config.yml

三、发送推送通知（通过 Web API）

请求地址

POST http://localhost:8088/api/push
Content-Type: application/json

示例 1：发送 iOS 通知（platform=1）

{
  "notifications": [
    {
      "tokens": ["device_token_1", "device_token_2"],
      "platform": 1,
      "message": "Hello from Gorush!",
      "title": "New Message",
      "badge": 1,
      "sound": "default",
      "category": "MESSAGE"
    }
  ]
}

示例 2：发送 Android (FCM) 通知（platform=2）

{
  "notifications": [
    {
      "tokens": ["fcm_device_token"],
      "platform": 2,
      "message": "Hello Android!",
      "title": "Gorush",
      "data": {
        "custom_key": "custom_value"
      }
    }
  ]
}

示例 3：发送 Huawei (HMS) 通知（platform=3）

{
  "notifications": [
    {
      "tokens": ["hms_device_token"],
      "platform": 3,
      "message": "Hello Huawei!",
      "title": "Gorush"
    }
  ]
}

🔑 Platform 编码：

1 = iOS

2 = Android (FCM)

3 = Huawei (HMS)

四、关键配置说明（`config.yml`）

1. 核心配置（`core`）

core:
  port: "8088"
  worker_num: 0        # 默认 = CPU 核数
  queue_num: 8192
  sync: false          # 是否同步返回错误（默认异步）
  feedback_hook_url: "https://your-server.com/hook"  # 失败回调

2. Android (FCM)

android:
  enabled: true
  credential: '{"project_id":"xxx",...}'  # 直接嵌入 JSON 字符串
  # 或使用 key_path: "/path/to/service-account.json"
  max_retry: 2

3. iOS (APNs)

ios:
  enabled: true
  key_path: "key.p8"
  key_type: "p8"
  key_id: "ABC123"
  team_id: "TEAM123"
  production: false   # false = 开发环境，true = 生产环境
  max_concurrent_pushes: 100

4. 统计存储（可选）

stat:
  engine: "redis"
  redis:
    addr: "localhost:6379"

五、命令行方式（适合测试）

发送单条 iOS 通知

gorush \
  -ios \
  -m "Test message" \
  -i key.p8 \
  --key-id ABC123 \
  --team-id TEAM123 \
  -t "your_device_token" \
  --production

发送单条 Android 通知

export GOOGLE_APPLICATION_CREDENTIALS="service-account.json"
gorush -android -m "Hello" -t "fcm_token"

六、监控与状态接口

接口	说明
`GET /api/stat/go`	Go 运行时状态（内存、协程等）
`GET /api/stat/app`	推送统计（成功/失败次数）
`GET /sys/stats`	HTTP 请求统计（响应时间、状态码）
`GET /metrics`	Prometheus 指标（需启用）
`GET /healthz`	健康检查

示例：

curl http://localhost:8088/api/stat/app
# 返回：
# { "success_tasks": 120, "failure_tasks": 3, "ios": { "push_success": 80 }, "android": { "push_success": 40 } }

七、其他部署方式

1. Kubernetes

官方提供 Helm Chart 和 YAML 示例：
👉 https://github.com/appleboy/gorush/tree/master/k8s

2. AWS Lambda

支持原生 Go Lambda 部署，适合事件驱动型推送：

make build_linux_lambda
# 上传 release/linux/lambda/gorush 到 Lambda

3. 二进制直接运行

# 下载预编译二进制（Linux）
wget https://github.com/appleboy/gorush/releases/latest/download/gorush-linux-amd64 -O gorush
chmod +x gorush
./gorush -c config.yml

八、安全建议

不要暴露公网：建议通过内网或 API 网关访问
启用 TLS：在 core.ssl 中配置证书，或使用 auto_tls 自动申请 Let's Encrypt
隐藏 Token：设置 log.hide_token: true 防止日志泄露设备令牌
限制并发：通过 worker_num 和 queue_num 防止资源耗尽

📚 官方资源

GitHub: https://github.com/appleboy/gorush
文档（含完整配置示例）: README
在线 Demo: https://gorush.netlify.app/ （可用于测试 FCM token）
Docker Hub: https://hub.docker.com/r/appleboy/gorush

总结

gorush 是一个 生产就绪、多平台兼容、易于部署 的推送服务器，特别适合：

微服务架构中统一处理推送
需要高并发、低延迟的场景
希望避免依赖第三方 SaaS 推送服务（如极光、个推）

只需一个 config.yml + 一条 docker run，即可搭建自己的推送中心！