把系统通知，送到用户真正会看的地方。

5 分钟发送第一条消息

你需要一个开发者账号、一个应用和收件人的信咕咕号。API Key 只在创建或轮换时完整展示一次，请立即保存到安全的密钥系统。

1. 1
   创建应用

   登录开发者后台，在“应用”中创建接入。复制以 xs_live_ 开头的 API Key。

2. 2
   取得收件人账号

   让用户提供其 10 位信咕咕号。它相当于消息地址，不是登录凭证。

3. 3
   调用投递接口

   向 /ingest/v1/messages 发送 JSON。首次成功返回 HTTP 201。

curl https://notify.skyloong.cc/ingest/v1/messages \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: xs_live_xxx" \
  -H "X-Idempotency-Key: order-20260920-001" \
  -d '{
    "recipient_account": "1234567890",
    "title": "订单已发货",
    "body": "你的包裹已由顺丰揽收。",
    "level": "info",
    "metadata": {"order_id": "20260920-001"}
  }'

核心概念

应用如何获得投递授权

当前版本采用“用户提供信咕咕号 + 开发者应用凭证”的直接寻址方式，适合告警、内部系统和一对一通知。信咕咕号像邮箱地址一样可交付给可信应用，但 API Key 必须始终由应用服务端保管。

推荐的绑定流程

1. 在你的产品中提供“信咕咕号”输入框，并明确说明消息用途。
2. 校验它是 10 位数字，但不要根据前端校验推断账号一定存在。
3. 首次绑定时发送一条测试消息，让用户在客户端确认接收成功。
4. 在你的数据库中保存业务用户 ID 与信咕咕号的映射；不要保存用户密码或登录令牌。
5. 提供解绑入口，并在用户解绑后停止投递。

发送第一条消息

所有投递请求使用 JSON。标题适合表达“发生了什么”，正文补充上下文；结构化信息放入 metadata，方便后续跳转或排查。

幂等投递

通过 X-Idempotency-Key 传入稳定的业务事件 ID，例如订单号与事件名的组合。相同应用下的相同键在 24 小时内只创建一条消息。

order:20260920-001:shipped
deployment:payment-api:2.4.1
alert:server-01:disk-c:20260920T1030

Go SDK

官方 Go SDK 无第三方依赖，内置随机幂等键、临时错误重试、Retry-After 支持、上下文取消和结构化 API 错误。

package main

import (
  "context"
  "log"

  xinshu "github.com/LaRysLuo/xinggu/sdk/go"
)

func main() {
  client, err := xinshu.NewClient("xs_live_xxx")
  if err != nil {
    log.Fatal(err)
  }

  result, err := client.Send(context.Background(), xinshu.Message{
    RecipientAccount: "1234567890",
    Title:            "部署完成",
    Body:             "production v2.4.1 已成功发布",
    Level:            xinshu.LevelSuccess,
    Metadata: map[string]any{
      "service": "payment-api",
      "version": "2.4.1",
    },
  })
  if err != nil {
    log.Fatal(err)
  }
  log.Printf("message_id=%s duplicate=%t", result.MessageID, result.Duplicate)
}

自定义地址与重试

client, err := xinshu.NewClient(
  "xs_live_xxx",
  xinshu.WithBaseURL("http://127.0.0.1:8080"),
  xinshu.WithMaxRetries(3),
)

默认每次 Send 都会生成随机幂等键，并在内部重试时复用。要跨进程去重，请使用 xinshu.WithIdempotencyKey("your-business-key")。

命令行工具

CLI 适合部署脚本、定时任务和服务器巡检。预编译文件是独立可执行程序，不需要安装 Go 或其他运行时。密钥只从环境变量读取，避免进入 Shell 历史与进程参数。

直接安装（推荐）

curl -fL https://github.com/LaRysLuo/xinggu/releases/latest/download/xingugu-linux-amd64 -o xingugu
chmod +x xingugu
sudo install xingugu /usr/local/bin/xingugu
xingugu version

curl -fL https://github.com/LaRysLuo/xinggu/releases/latest/download/xingugu-linux-arm64 -o xingugu
chmod +x xingugu
sudo install xingugu /usr/local/bin/xingugu
xingugu version

$installDir = "$env:LOCALAPPDATA\Xingugu\bin"
New-Item -ItemType Directory -Force $installDir | Out-Null
Invoke-WebRequest `
  https://github.com/LaRysLuo/xinggu/releases/latest/download/xingugu-windows-amd64.exe `
  -OutFile "$installDir\xingugu.exe"
& "$installDir\xingugu.exe" version

curl -fL https://github.com/LaRysLuo/xinggu/releases/latest/download/xingugu-darwin-arm64 -o xingugu
chmod +x xingugu
sudo install xingugu /usr/local/bin/xingugu
xingugu version

Intel Mac 请下载 xingugu-darwin-amd64。Release 同时提供 sha256sums.txt；查看全部下载 ↗

Go 开发者

配置并发送

$env:XINGUGU_API_KEY = 'xs_live_xxx'
$env:XINGUGU_RECIPIENT = '1234567890'

xingugu send `
  --title '磁盘空间不足' `
  --body 'server-01 剩余空间低于 10%' `
  --level warning `
  --metadata '{"host":"server-01","disk":"C:"}'

export XINGUGU_API_KEY='xs_live_xxx'
export XINGUGU_RECIPIENT='1234567890'

xingugu send \
  --title '磁盘空间不足' \
  --body 'server-01 剩余空间低于 10%' \
  --level warning \
  --metadata '{"host":"server-01","disk":"/data"}'

退出码：0 成功，1 网络或 API 错误，2 参数或配置错误。正文可传 --body - 从标准输入读取。

查看、搜索和筛选消息

客户端按页加载消息，并通过实时连接同步新消息、已读和删除事件。离线后重新连接时，以服务端消息列表恢复一致状态。

登录状态与多端会话

客户端会安全保存刷新令牌。只要你持续使用客户端，它会在访问令牌到期前自动刷新会话，因此无需每天重新登录。

HTTP API

基础地址为 https://notify.skyloong.cc。成功响应统一使用 { "data": ... }，错误响应统一使用 { "error": { "code": "...", "message": "..." } }。

错误、限流与重试

单个应用默认限制为每分钟 120 次请求。批量或高频通知应在业务侧排队，并控制并发；不要通过多个 API Key 绕过限流。

运维接入

推荐用 CLI 连接监控脚本、CI/CD 和计划任务；长期运行的服务使用 Go SDK。密钥应注入环境变量或密钥管理服务，不要写入仓库。

export XINGUGU_API_KEY="$XINGUGU_DEPLOY_KEY"
export XINGUGU_RECIPIENT="1234567890"

if deploy-production; then
  xingugu send --title "部署成功" \
    --body "payment-api ${GIT_COMMIT} 已上线" \
    --level success --json
else
  xingugu send --title "部署失败" \
    --body "请检查 CI 日志" \
    --level error --json
  exit 1
fi

健康检查

xingugu health --json
# 或
curl -fsS https://notify.skyloong.cc/healthz

自托管环境可设置 XINGUGU_API_URL，或为单次命令传入 --api-url。

常见问题