信咕咕文档
开发者后台
信咕咕 · XINGUGU

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

信咕咕是一个面向个人的统一消息中心。用户用唯一的 10 位信咕咕号接收消息;应用通过 HTTP API、Go SDK 或 CLI 安全投递。

01创建应用获取 API Key
→
02指定收件人10 位信咕咕号
→
03投递消息API / SDK / CLI
01 · 快速开始

5 分钟发送第一条消息

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

  1. 1
    创建应用

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

  2. 2
    取得收件人账号

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

  3. 3
    调用投递接口

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

cURL
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"}
  }'
成功响应

首次投递返回 201 Created;相同应用在 24 小时内使用相同幂等键再次请求,会返回 200 OK 和原消息 ID。

02 · 基础

核心概念

#

信咕咕号

用户注册后获得的唯一 10 位数字账号。它用于寻址,不可用于登录,也不应当视作秘密。

◇

应用

开发者创建的消息来源。应用名称会作为消息“来源”显示,并拥有独立的启停状态和发送统计。

⌁

API Key

应用的投递凭证。仅能发送消息,不能读取用户消息或访问用户资料。应只保存在服务端。

!

消息等级

info、success、warning、error,用于客户端视觉提示和筛选。

角色隔离

终端用户和开发者使用不同的账号体系与令牌。开发者不能读取收件箱,终端用户也不能操作开发者应用。

03 · 授权

两种取得咕咕号的方式

直接寻址始终可用:用户可像提供邮箱地址一样填写咕咕号,不需要先授权应用。需要免填登录体验时,应用也可以登记回调地址,通过信咕咕客户端让用户明确授权并自动取得号码。API Key 必须始终由应用服务端保管。

用户提供 10 位信咕咕号
→
你的服务保存账号与业务用户的绑定
→
信咕咕校验 API Key 并投递

推荐的绑定流程

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

可选:客户端授权登录

  1. 创建应用时登记精确的授权回调地址。
  2. 生成随机 state 和 S256 PKCE challenge,再打开 xingugu://authorize。
  3. 用户在客户端确认后,你的回调会收到一次性 code;拒绝时收到 error=access_denied。
  4. 使用原始 PKCE verifier 调用 POST /oauth/v1/token,换取用户明确提供的咕咕号。

开放平台快捷账号

你的服务端完成手机号或邮箱验证后,携带应用 API Key 调用 POST /open/v1/quick-accounts。手机号与邮箱二选一,同时必须传入 display_name;已有标识会返回原咕咕号,没有则创建当前仅支持快捷 code 登录的账号。对于昵称仍为“快捷账号”的历史账号,再次调用时会自动补齐昵称,已有真实昵称不会被覆盖。

curl -X POST /open/v1/quick-accounts \
  -H "X-API-Key: xs_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"phone":"13800138000","display_name":"张三"}'

使用一次性 CODE 拉起客户端

  1. 你的服务端读取已保存的咕咕号,调用 POST /open/v1/quick-codes。
  2. 打开响应中的 xingugu://quick-login?client_id=...&code=...。
  3. 客户端展示应用和目标账号;用户确认后消费 code 并建立客户端登录会话。
API Key 只能保存在服务端

快捷 code 两分钟有效、只能使用一次并绑定签发应用。不要在第三方客户端本地直接调用创建账号或签发 code 接口。

授权不是投递门槛

授权登录只用于减少手动填写。即使没有授权关系,只要用户主动提供了咕咕号,应用仍可按号码正常投递。

不要把 API Key 放进客户端

移动端、网页前端和桌面客户端都可能泄露静态密钥。消息应由你的服务端发送;公开客户端通过你自己的后端发起请求。

开放平台 · 对话流

创建对话流,打开成员交流

应用服务端使用 API Key,按稳定的业务编号创建或更新对话流,并传入已有咕号构建成员。返回的 No 与聊天记录保持不变。

curl -X POST https://notify.skyloong.cc/open/v1/conversations \
  -H "X-API-Key: xs_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"external_no":"order-001","title":"订单咨询",
       "owner_account":"1234567890",
       "member_accounts":["1234567891","1234567892"]}'

首次创建返回 201、created=true;同一应用的 external_no 后续调用返回 200,并同步标题与完整成员名单。也可以使用 PUT /open/v1/conversations/:no 提交 title 和 member_accounts,或使用 GET 查询资料。

成员名单采用完整同步

遗漏的普通成员会移除;所有者自动保留且不能更换。已有成员保留已读进度,新成员从当前消息位置计算未读。名单最多 100 个咕号;未知咕号会使整个操作失败。

解散或移除整条对话流

curl -X DELETE https://notify.skyloong.cc/open/v1/conversations/63c3b89f-1dfa-47b8-89de-2431acaf420e \
  -H "X-API-Key: xs_live_xxx"

无需请求体。成功返回 204 No Content,无响应体;不存在、已删除或不属于当前应用的 No 返回 404。与创建、更新共用每应用每分钟 120 次写操作限额。

解散会永久删除历史

对话流、成员、所有消息和图片在同一事务内删除,无法恢复。原成员收到变更事件,客户端刷新列表并清除不可访问的聊天记录;旧 No 和拉起链接失效。删除后可用原 external_no 重新创建,但会生成新 No,不会恢复旧消息。

如果只想移除某些成员,用 PUT 提交剩余成员的完整名单;所有者会自动保留。

拉起客户端打开指定对话流

把响应中的 data.launch_uri 放入用户点击的链接,或使用系统打开 URL 功能。格式如下:

xingugu://conversation?no=63c3b89f-1dfa-47b8-89de-2431acaf420e

需要已安装支持此功能的新版客户端。已登录成员直接进入聊天;未登录时先登录再打开;非成员会收到错误提示。链接不包含登录凭据。快捷账号可以先通过已有的一次性 CODE 登录。

应用仅能管理自己创建的对话流,开放接口不读取聊天正文或图片。API Key 放在服务端。详细字段和错误响应见 OpenAPI 定义。

04 · 消息投递

发送第一条消息

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

字段类型必填说明
recipient_accountstring是10 位信咕咕号
titlestring是消息名称;会参与模糊搜索
bodystring是消息正文;会参与模糊搜索
levelstring否info / success / warning / error
metadataobject否业务扩展字段,如订单号、主机名或跳转地址

幂等投递

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

建议的幂等键
order:20260920-001:shipped
deployment:payment-api:2.4.1
alert:server-01:disk-c:20260920T1030
05 · Go SDK

Go SDK

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

go get github.com/LaRysLuo/xinggu/sdk/go
main.go
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)
}

自定义地址与重试

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

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

06 · CLI

命令行工具

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

直接安装(推荐)

curl -fL https://notify.skyloong.cc/downloads/xingugu/latest/xingugu-linux-amd64 -o xingugu
chmod +x xingugu
sudo install xingugu /usr/local/bin/xingugu
xingugu version
curl -fL https://notify.skyloong.cc/downloads/xingugu/latest/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://notify.skyloong.cc/downloads/xingugu/latest/xingugu-windows-amd64.exe `
  -OutFile "$installDir\xingugu.exe"
& "$installDir\xingugu.exe" version
curl -fL https://notify.skyloong.cc/downloads/xingugu/latest/xingugu-darwin-arm64 -o xingugu
chmod +x xingugu
sudo install xingugu /usr/local/bin/xingugu
xingugu version

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

自动更新(v0.4.0 起)

Linux
xingugu update --check
sudo xingugu update --restart-service

update 会自动识别系统与 CPU 架构,从信咕咕官方下载对应二进制,核对 SHA-256 后再替换当前程序。--check 只检查版本;--force 可重新安装相同版本;Linux 上的 --restart-service 会在更新完成后重启 xingugu-agent。

第一次升级说明

v0.3.0 及更早版本还没有 update 命令,需要先用下面的覆盖方式升级到 v0.4.0。此后的版本可以直接运行 xingugu update。

手动更新

Linux x86-64
curl -fL https://notify.skyloong.cc/downloads/xingugu/latest/xingugu-linux-amd64 \
  -o /tmp/xingugu
chmod +x /tmp/xingugu
sudo install /tmp/xingugu /usr/local/bin/xingugu
xingugu version
sudo systemctl restart xingugu-agent

ARM64 服务器将文件名换成 xingugu-linux-arm64。覆盖二进制不会修改 /etc/xingugu/agent.json;使用 systemd 时更新后需要重启服务。

Go 开发者

go install github.com/LaRysLuo/xinggu/sdk/go/cmd/xingugu@latest

配置并发送

$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"}'
命令用途常用选项
xingugu send发送消息--to --title --body --level --metadata --json
xingugu health检查 API 可用性--api-url --json
xingugu check执行一次运维巡检--config --notify --json
xingugu watch持续监控并发送故障/恢复通知--config --dry-run
xingugu config生成或校验监控配置example validate
xingugu update检查并安全安装 CLI 更新--check --force --restart-service
xingugu version显示版本—

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

07 · 客户端

查看、搜索和筛选消息

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

⌕
模糊搜索

关键词同时匹配消息名称和正文,无需输入完整文本。

◎
来源筛选

按应用来源名称模糊筛选,例如输入“监控”可匹配“服务器监控”。

≡
等级筛选

按信息、成功、警告或错误组合缩小范围。

✓
跨设备同步

在一台设备标记已读或删除,其他在线设备会收到更新。

分页统计

列表会分别显示当前筛选结果总数、账号全部消息数和未读消息数,筛选不会改变全局统计。

08 · 会话

登录状态与多端会话

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

支持多客户端同时登录

同一账号可在 Windows、macOS、iOS 和 Android 等多个客户端保持独立会话。单个设备退出不会让其他设备下线。

会话会滚动续期

有效使用会触发刷新令牌轮换,持续延长活跃会话。长时间不使用或令牌失效后,需要重新登录。

共享设备提示

在公共或临时设备上使用后请主动退出。退出会撤销当前设备的刷新会话,并清除本地登录信息。

09 · API 参考

HTTP API

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

消息投递

POST/ingest/v1/messages

使用 X-API-Key 投递一条消息

用户消息

GET/api/v1/messages

分页查询;支持 page、page_size、q、source、level、unread_only

GET/api/v1/messages/stream

SSE 实时事件:message、message.read、message.deleted

GET/api/v1/messages/:id

获取消息详情

POST/api/v1/messages/:id/read

标记消息为已读

DELETE/api/v1/messages/:id

删除自己的消息

开发者应用

GET/api/v1/developer/integrations

列出应用与发送统计

POST/api/v1/developer/integrations

创建应用并获得 API Key

PATCH/api/v1/developer/integrations/:id/status

启用或停用应用

POST/api/v1/developer/integrations/:id/rotate-key

轮换 API Key

YAML
下载 OpenAPI 规范

用于代码生成、接口调试和自动化校验

↓
10 · 可靠性

错误、限流与重试

状态码含义建议
400请求字段无效检查账号、等级和 JSON 格式,不要自动重试
401 / 403凭证无效或应用已停用检查或轮换 API Key,不要自动重试
404收件人不存在让用户重新确认信咕咕号
429超过速率限制遵守 Retry-After,指数退避后重试
5xx服务临时不可用带同一幂等键退避重试

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

SDK 已处理临时故障

Go SDK 会自动重试网络错误、HTTP 429 和 5xx,并在所有尝试中复用同一个幂等键。

11 · 运维

轻量运维监控代理

xingugu watch 可以常驻服务器主动巡检,不需要额外部署 Prometheus。它会在连续故障达到阈值时发送告警,恢复后发送恢复通知,并对长期故障按设定间隔提醒。

↗
网络服务

HTTP 状态码、TCP 端口、DNS 解析和 TLS 证书有效期。

▥
服务器资源

Linux 磁盘使用率、内存使用率和 1 分钟系统负载。

◷
文件新鲜度

检查备份文件是否存在,以及是否超过允许时间未更新。

✓
告警抑制与恢复

连续失败才告警,避免瞬时波动;发送失败会在下一轮重试。

创建配置

服务地址固定

监控代理只连接 https://notify.skyloong.cc,agent.json 不支持也不需要 api_url。旧配置中如果存在该字段,请将它删除。

/etc/xingugu/agent.json
{
  "recipient_accounts": ["1234567890", "9876543210"],
  "interval": "30s",
  "failure_threshold": 2,
  "recovery_threshold": 1,
  "repeat_interval": "6h",
  "checks": [
    {"name":"网站","type":"http","target":"https://example.com/healthz","expected_status":200},
    {"name":"MySQL","type":"tcp","target":"127.0.0.1:3306"},
    {"name":"根分区","type":"disk","path":"/","max_percent":85},
    {"name":"内存","type":"memory","max_percent":90},
    {"name":"证书","type":"tls","target":"example.com:443","min_days":14}
  ]
}

recipient_accounts 可以填写一个或多个接收人的 10 位信咕咕号,故障、恢复、持续故障和启动通知都会发给列表内的所有人。旧版单值字段 recipient_account 仍然兼容;如果两个字段同时存在,CLI 会合并并自动去重。

全局字段作用默认值
recipient_accounts接收通知的信咕咕号数组;持续监控和通知巡检至少需要一个—
interval每轮检查间隔,不得小于 1 秒30s
failure_threshold连续失败多少次后发送故障通知2
recovery_threshold连续成功多少次后发送恢复通知1
repeat_interval故障未恢复时的重复提醒间隔6h
checks检查项数组,至少需要一个;每项名称必须唯一—

时间值使用 500ms、30s、5m、2h 等格式。每个检查项都支持 name、type 和可选的 timeout(默认 5s)。

类型关键字段判断规则
httptarget、expected_status未指定状态码时,HTTP 200–399 为正常
tcptarget(host:port)指定端口可以建立 TCP 连接
dnstarget域名至少解析出一个地址
tlstarget、min_days证书有效且剩余天数不低于阈值
diskpath、max_percentLinux 磁盘使用率低于阈值
memorymax_percentLinux 内存使用率低于阈值
loadmax_valueLinux 一分钟平均负载低于阈值
filepath、可选 max_age文件存在,且没有超过允许时间未更新

也可以运行 xingugu config example 生成包含全部八类检查的示例,再用以下命令校验:

Shell
xingugu config validate --config /etc/xingugu/agent.json
xingugu check --config /etc/xingugu/agent.json
xingugu watch --config /etc/xingugu/agent.json --dry-run

开始持续监控

Shell
export XINGUGU_API_KEY='xs_live_xxx'
xingugu watch --config /etc/xingugu/agent.json

启动成功后会立即向所有接收人发送一条“信咕咕监控已启动”消息,包含主机名、检查项数量、检查间隔和启动时间。随后按配置间隔持续检查。

前台命令不是后台服务

直接运行 xingugu watch 时,按 Ctrl+C 会停止监控,SSH 断开也可能使进程退出。生产服务器请注册为 systemd 服务。

密钥独立保存

配置文件只包含收件人和检查项。API Key 应放在权限为 600 的环境文件或密钥系统中,不要写进 JSON 或命令行。

注册为 systemd 服务

Linux
sudo install -d -m 750 /etc/xingugu
sudo curl -fL https://notify.skyloong.cc/downloads/xingugu/examples/xingugu-agent.json \
  -o /etc/xingugu/agent.json
sudo curl -fL https://notify.skyloong.cc/downloads/xingugu/examples/agent.env.example \
  -o /etc/xingugu/agent.env
sudo curl -fL https://notify.skyloong.cc/downloads/xingugu/examples/xingugu-agent.service \
  -o /etc/systemd/system/xingugu-agent.service

sudo vi /etc/xingugu/agent.json
sudo vi /etc/xingugu/agent.env
sudo useradd --system --no-create-home --shell /sbin/nologin xingugu 2>/dev/null || true
sudo chown root:xingugu /etc/xingugu/agent.json
sudo chmod 640 /etc/xingugu/agent.json
sudo chown root:root /etc/xingugu/agent.env
sudo chmod 600 /etc/xingugu/agent.env

sudo systemctl daemon-reload
sudo systemctl enable --now xingugu-agent
sudo systemctl status xingugu-agent --no-pager -l
sudo journalctl -u xingugu-agent -f

agent.env 中只需要设置 XINGUGU_API_KEY=xs_live_xxx。注册后,退出 SSH 不会停止监控,服务器重启后会自动启动,进程异常退出也会自动重启。在 journalctl -f 中按 Ctrl+C 只会退出日志查看,不会停止服务。

启动失败排查

Linux
sudo systemctl status xingugu-agent.service --no-pager -l
sudo journalctl -u xingugu-agent.service -b -n 50 --no-pager
command -v xingugu
ls -l /usr/local/bin/xingugu
ls -l /etc/xingugu/agent.json /etc/xingugu/agent.env
id xingugu

出现 Failed to run 'start' task: No such file or directory 时,通常是 /etc/xingugu/agent.env、/etc/xingugu/agent.json、/usr/local/bin/xingugu 或 xingugu 系统用户缺失。修复后运行 systemctl restart xingugu-agent,状态应显示 active (running)。

修改配置后,先执行 xingugu config validate --config /etc/xingugu/agent.json,再执行 systemctl restart xingugu-agent 使配置生效。

完整 JSON、环境文件模板和强化后的 systemd 单元均可直接下载。磁盘、内存和负载检查面向 Linux;HTTP、TCP、DNS、TLS 和文件检查可跨平台使用。

在 CI/CD 中主动通知

部署完成后通知
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
12 · 帮助

常见问题

API Key 泄露了怎么办?+

立即在开发者后台轮换密钥,并更新服务端配置。旧密钥会失效。随后检查发送统计和日志,确认是否存在异常投递。

为什么出现重复消息?+

如果业务侧重试时没有复用相同的 X-Idempotency-Key,每次请求都会被视为新消息。使用稳定的业务事件 ID,或直接使用 Go SDK 的重试机制。

一个账号可以同时登录几台设备?+

支持多客户端同时登录,每台设备保持独立刷新会话。消息状态通过实时事件同步,离线设备重连后会恢复一致。

用户收不到消息时如何排查?+

先确认 API 响应、收件人信咕咕号和应用状态;再让用户清除筛选条件并刷新列表。HTTP 404 通常表示收件人账号不正确。

可以从浏览器直接调用投递 API 吗?+

不建议。浏览器中的 API Key 很容易被查看和滥用。请从你的后端调用信咕咕,再由前端调用你自己的受控接口。

已复制