把系统通知,送到用户真正会看的地方。
信咕咕是一个面向个人的统一消息中心。用户用唯一的 10 位信咕咕号接收消息;应用通过 HTTP API、Go SDK 或 CLI 安全投递。
5 分钟发送第一条消息
你需要一个开发者账号、一个应用和收件人的信咕咕号。API Key 只在创建或轮换时完整展示一次,请立即保存到安全的密钥系统。
- 1创建应用
登录开发者后台,在“应用”中创建接入。复制以
xs_live_开头的 API Key。 - 2取得收件人账号
让用户提供其 10 位信咕咕号。它相当于消息地址,不是登录凭证。
- 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"}
}'
首次投递返回 201 Created;相同应用在 24 小时内使用相同幂等键再次请求,会返回 200 OK 和原消息 ID。
核心概念
信咕咕号
用户注册后获得的唯一 10 位数字账号。它用于寻址,不可用于登录,也不应当视作秘密。
应用
开发者创建的消息来源。应用名称会作为消息“来源”显示,并拥有独立的启停状态和发送统计。
API Key
应用的投递凭证。仅能发送消息,不能读取用户消息或访问用户资料。应只保存在服务端。
消息等级
info、success、warning、error,用于客户端视觉提示和筛选。
终端用户和开发者使用不同的账号体系与令牌。开发者不能读取收件箱,终端用户也不能操作开发者应用。
创建对话流,打开成员交流
应用服务端使用 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 定义。
发送第一条消息
所有投递请求使用 JSON。标题适合表达“发生了什么”,正文补充上下文;结构化信息放入 metadata,方便后续跳转或排查。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
recipient_account | string | 是 | 10 位信咕咕号 |
title | string | 是 | 消息名称;会参与模糊搜索 |
body | string | 是 | 消息正文;会参与模糊搜索 |
level | string | 否 | info / success / warning / error |
metadata | object | 否 | 业务扩展字段,如订单号、主机名或跳转地址 |
幂等投递
通过 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 错误。
go get github.com/LaRysLuo/xinggu/sdk/gopackage 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://notify.skyloong.cc/downloads/xingugu/latest/xingugu-linux-amd64 -o xingugu
chmod +x xingugu
sudo install xingugu /usr/local/bin/xingugu
xingugu versioncurl -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" versioncurl -fL https://notify.skyloong.cc/downloads/xingugu/latest/xingugu-darwin-arm64 -o xingugu
chmod +x xingugu
sudo install xingugu /usr/local/bin/xingugu
xingugu versionIntel Mac 请下载 xingugu-darwin-amd64。同时提供 sha256sums.txt;查看全部下载
自动更新(v0.4.0 起)
xingugu update --check
sudo xingugu update --restart-serviceupdate 会自动识别系统与 CPU 架构,从信咕咕官方下载对应二进制,核对 SHA-256 后再替换当前程序。--check 只检查版本;--force 可重新安装相同版本;Linux 上的 --restart-service 会在更新完成后重启 xingugu-agent。
v0.3.0 及更早版本还没有 update 命令,需要先用下面的覆盖方式升级到 v0.4.0。此后的版本可以直接运行 xingugu update。
手动更新
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-agentARM64 服务器将文件名换成 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 - 从标准输入读取。
查看、搜索和筛选消息
客户端按页加载消息,并通过实时连接同步新消息、已读和删除事件。离线后重新连接时,以服务端消息列表恢复一致状态。
关键词同时匹配消息名称和正文,无需输入完整文本。
按应用来源名称模糊筛选,例如输入“监控”可匹配“服务器监控”。
按信息、成功、警告或错误组合缩小范围。
在一台设备标记已读或删除,其他在线设备会收到更新。
列表会分别显示当前筛选结果总数、账号全部消息数和未读消息数,筛选不会改变全局统计。
登录状态与多端会话
客户端会安全保存刷新令牌。只要你持续使用客户端,它会在访问令牌到期前自动刷新会话,因此无需每天重新登录。
支持多客户端同时登录
同一账号可在 Windows、macOS、iOS 和 Android 等多个客户端保持独立会话。单个设备退出不会让其他设备下线。
会话会滚动续期
有效使用会触发刷新令牌轮换,持续延长活跃会话。长时间不使用或令牌失效后,需要重新登录。
在公共或临时设备上使用后请主动退出。退出会撤销当前设备的刷新会话,并清除本地登录信息。
HTTP API
基础地址为 https://notify.skyloong.cc。成功响应统一使用 { "data": ... },错误响应统一使用 { "error": { "code": "...", "message": "..." } }。
消息投递
/ingest/v1/messages使用 X-API-Key 投递一条消息
用户消息
/api/v1/messages分页查询;支持 page、page_size、q、source、level、unread_only
/api/v1/messages/streamSSE 实时事件:message、message.read、message.deleted
/api/v1/messages/:id获取消息详情
/api/v1/messages/:id/read标记消息为已读
/api/v1/messages/:id删除自己的消息
开发者应用
/api/v1/developer/integrations列出应用与发送统计
/api/v1/developer/integrations创建应用并获得 API Key
/api/v1/developer/integrations/:id/status启用或停用应用
/api/v1/developer/integrations/:id/rotate-key轮换 API Key
用于代码生成、接口调试和自动化校验
错误、限流与重试
| 状态码 | 含义 | 建议 |
|---|---|---|
400 | 请求字段无效 | 检查账号、等级和 JSON 格式,不要自动重试 |
401 / 403 | 凭证无效或应用已停用 | 检查或轮换 API Key,不要自动重试 |
404 | 收件人不存在 | 让用户重新确认信咕咕号 |
429 | 超过速率限制 | 遵守 Retry-After,指数退避后重试 |
5xx | 服务临时不可用 | 带同一幂等键退避重试 |
单个应用默认限制为每分钟 120 次请求。批量或高频通知应在业务侧排队,并控制并发;不要通过多个 API Key 绕过限流。
Go SDK 会自动重试网络错误、HTTP 429 和 5xx,并在所有尝试中复用同一个幂等键。
轻量运维监控代理
xingugu watch 可以常驻服务器主动巡检,不需要额外部署 Prometheus。它会在连续故障达到阈值时发送告警,恢复后发送恢复通知,并对长期故障按设定间隔提醒。
HTTP 状态码、TCP 端口、DNS 解析和 TLS 证书有效期。
Linux 磁盘使用率、内存使用率和 1 分钟系统负载。
检查备份文件是否存在,以及是否超过允许时间未更新。
连续失败才告警,避免瞬时波动;发送失败会在下一轮重试。
创建配置
监控代理只连接 https://notify.skyloong.cc,agent.json 不支持也不需要 api_url。旧配置中如果存在该字段,请将它删除。
{
"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)。
| 类型 | 关键字段 | 判断规则 |
|---|---|---|
http | target、expected_status | 未指定状态码时,HTTP 200–399 为正常 |
tcp | target(host:port) | 指定端口可以建立 TCP 连接 |
dns | target | 域名至少解析出一个地址 |
tls | target、min_days | 证书有效且剩余天数不低于阈值 |
disk | path、max_percent | Linux 磁盘使用率低于阈值 |
memory | max_percent | Linux 内存使用率低于阈值 |
load | max_value | Linux 一分钟平均负载低于阈值 |
file | path、可选 max_age | 文件存在,且没有超过允许时间未更新 |
也可以运行 xingugu config example 生成包含全部八类检查的示例,再用以下命令校验:
xingugu config validate --config /etc/xingugu/agent.json
xingugu check --config /etc/xingugu/agent.json
xingugu watch --config /etc/xingugu/agent.json --dry-run开始持续监控
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 服务
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 -fagent.env 中只需要设置 XINGUGU_API_KEY=xs_live_xxx。注册后,退出 SSH 不会停止监控,服务器重启后会自动启动,进程异常退出也会自动重启。在 journalctl -f 中按 Ctrl+C 只会退出日志查看,不会停止服务。
启动失败排查
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常见问题
API Key 泄露了怎么办?+
立即在开发者后台轮换密钥,并更新服务端配置。旧密钥会失效。随后检查发送统计和日志,确认是否存在异常投递。
为什么出现重复消息?+
如果业务侧重试时没有复用相同的 X-Idempotency-Key,每次请求都会被视为新消息。使用稳定的业务事件 ID,或直接使用 Go SDK 的重试机制。
一个账号可以同时登录几台设备?+
支持多客户端同时登录,每台设备保持独立刷新会话。消息状态通过实时事件同步,离线设备重连后会恢复一致。
用户收不到消息时如何排查?+
先确认 API 响应、收件人信咕咕号和应用状态;再让用户清除筛选条件并刷新列表。HTTP 404 通常表示收件人账号不正确。
可以从浏览器直接调用投递 API 吗?+
不建议。浏览器中的 API Key 很容易被查看和滥用。请从你的后端调用信咕咕,再由前端调用你自己的受控接口。