PushBits 0.10.7 常用 CLI 命令详解

汇总 PushBits 0.10.7 命令行运维工具箱：官方 pbcli v0.0.8 全部子命令实测（应用与用户管理）、镜像内置 pbcli、自建 Synapse 注册账号命令、curl 等价 API 与 Alertmanager 联动，含交互式密码的脚本化方案，全部命令真实环境实测。

PushBitsPushBitsCLI命令命令行通知自托管2026/10/26

PushBits 0.10.7 常用 CLI 命令详解

目标：汇总 PushBits 0.10.7 日常运维的命令行工具箱——官方 CLI 客户端 pbcli 的安装与全部子命令实测、官方镜像内置 pbcli 的使用、自建 Synapse 侧的账号注册命令、curl 等价 API 调用与 Alertmanager 联动命令。全部命令与回显均来自真实环境实测（PushBits 0.10.7 容器 + 自建 Synapse，实测日期 2026-10-26）。

一、命令行工具全景

PushBits 没有内置 Web 管理界面，日常运维完全靠命令行。按使用频率整理：

工具用途来源
pbcli管理应用（增删改查）与用户（管理员）官方 CLI 仓库 github.com/PushBits/cli
curl发送/撤回通知、健康检查、CI/脚本集成系统自带，直调 REST API
register_new_matrix_user在自建 Synapse 上注册 PushBits 发送账号与用户 Matrix 账号Synapse 镜像内置
docker logs/docker inspect服务端排障Docker 标准命令
amtool构造 Alertmanager 告警测试联动Prometheus Alertmanager

二、pbcli 安装与版本

2.1 从 Release 下载（推荐）

pbcli 最新 Release 为 v0.0.8（2023-07 构建，实查 2026-10-26）。下载、校验、解压三步：

wget https://github.com/pushbits/cli/releases/download/v0.0.8/pbcli_0.0.8_linux_amd64.tar.gz
wget https://github.com/pushbits/cli/releases/download/v0.0.8/pbcli_0.0.8_checksums.txt
sha256sum -c pbcli_0.0.8_checksums.txt
tar -xzf pbcli_0.0.8_linux_amd64.tar.gz && sudo install -m 0755 pbcli /usr/local/bin/

实测回显（checksums 文件含全平台 7 行，只下载 amd64 包时其余行报 FAILED open or read 属正常，关键看本架构行为 OK）：

pbcli_0.0.8_linux_amd64.tar.gz: OK
sha256sum: pbcli_0.0.8_darwin_amd64.tar.gz: No such file or directory

解压产物三件：pbcli（约 6.2 MB）、README.md、LICENSE。验证版本：

pbcli version

实测回显：

pbcli v0.0.8

2.2 源码编译

官方 README 提供的 Go 编译途径（需本机 Go 工具链）：

go install github.com/pushbits/cli/cmd/...@latest

2.3 官方镜像内置 pbcli

ghcr.io/pushbits/server:0.10.7 镜像自带一份 pbcli（docker history 可见 COPY /usr/local/bin/pbcli，构建日期 2022-12）。容器内直接可用：

docker exec pushbits-0.10.7-server pbcli version

实测回显：

pbcli unknown

💡 说明：镜像内置版 version 显示 unknown（构建时未注入版本号 ldflags），属 2022 年的旧构建，与 v0.10.7 服务端 API 兼容可用；脚本化运维建议宿主机统一用 v0.0.8，避免两处版本漂移。

三、pbcli 全子命令实测

3.1 命令结构与认证方式

pbcli [全局选项] <application|user> <create|list|show|update|delete> [参数]

两条全局必填项：--url（实例地址）与 --username（登录用户名）；密码一律交互式输入，提示语为 Current password of user admin: 。实测管道喂密码无效：

$ echo "q1w2e3r4" | pbcli application list --url http://127.0.0.1:8140 --username admin
Current password of user admin: 
level=fatal msg="No password was supplied."

原因：pbcli 用 golang.org/x/term.ReadPassword 直接读 TTY（二进制符号实查），不走 stdin 管道。脚本化两种出路：expect 驱动 pty，或 Python pty.openpty() 应答提示（本文实测用后者驱动全部命令）。--help 输出里每个子命令都有单字母别名：application (a) 的 create (c)、delete (d)、update (u)、list (l)、show (s)，user (u) 同构。

3.2 application 子命令（应用=通知频道）

创建（返回 id 与 token，token 只在创建/show 时可见）：

pbcli application create cliapp --url http://127.0.0.1:8140 --username admin

实测回显：

{
	"id": 2,
	"name": "cliapp",
	"token": "Aw8zwuR80Orpq7H9sd8QvPhTQX4zhnh0smjaDZ1JHIZp2IJaaXpZwnfSbMgc9HG2"
}

列表：

pbcli application list --url http://127.0.0.1:8140 --username admin

实测回显：

[
	{
		"id": 1,
		"name": "clitest",
		"token": "AdIyrf49RP0huzNR5bzbUQdax7MeAGkD9A4av5erPBpnmEnaCIPoPrnGLpVtiWc1"
	}
]

详情（pbcli application show 1 --url ... --username admin）：返回与 list 同结构的单对象；删除（pbcli application delete 2 ...）：成功返回 {} 并回收 token，之后用该 token 发消息即 403。更新（pbcli application update <id> ...）：交互式修改应用属性。

3.3 user 子命令（管理员专用）

创建用户（需要管理员身份；两段交互提示——先输管理员当前密码，再为新用户设密码）：

pbcli user create tester2 @tester2:pushbits.local --url http://127.0.0.1:8140 --username admin

实测回显（两段提示原文）：

Current password of user admin: 
New password of user tester2: 
{
	"id": 3,
	"is_admin": false,
	"matrix_id": "@tester2:pushbits.local",
	"name": "tester2"
}

列表 / 详情 / 删除 / 更新：user list（实测返回含 is_admin、matrix_id 字段的数组）、user show <id>（实测回显与创建响应同构）、user delete <id>（实测返回 {}，同时删除其名下应用）、user update <id>（交互式改密码/属性，也是忘记用户密码后的标准改密途径——config.yml 里的 admin.password 只在首次建号生效，见配置篇）。

⚠️ 注意：matrix-id 必须是完整 @用户名:homeserver域名 格式；新建用户收通知的前提是该 Matrix 账号真实存在于 homeserver（自建 Synapse 注册见第五章），且用户在 Matrix 客户端里接受过 PushBits 发送账号的房间邀请。

3.4 实测常见报错

报错原因与处理
level=fatal msg="No password was supplied."密码没从 TTY 读到（管道/重定向喂入无效），改用真终端或 pty 方案
FATA ... 401 类用户名或密码错误
FATA ... 403 类非 admin 账号调用了 user 子命令（用户管理仅管理员可用）；或对不属于自己的应用操作

四、服务端与容器侧命令

服务本体没有管理子命令——server/容器入口启动即读配置监听（配置加载规则见配置篇）。容器排障常用四条：

# 1. 看启动/投递日志（含 "Sending notification to room" 等关键行）
docker logs --tail 50 pushbits-0.10.7-server

# 2. 核对实际生效的环境变量（env 优先级高于 config.yml）
docker inspect pushbits-0.10.7-server --format '{{json .Config.Env}}'

# 3. 健康检查（镜像内置 HEALTHCHECK 探 /health）
docker inspect pushbits-0.10.7-server --format '{{.State.Health.Status}}'

# 4. 改配置后重启生效
docker restart pushbits-0.10.7-server

五、Matrix 侧命令（自建 Synapse）

PushBits 依赖两个预先存在的 Matrix 账号：发送账号（matrix.username）与管理员的接收账号（admin.matrixid）。自建 Synapse 用镜像内置的注册命令（实测全程）：

docker exec pushbits-0.10.7-synapse register_new_matrix_user \
  -c /data/homeserver.yaml http://localhost:8008 \
  -u pushbits -p q1w2e3r4 --no-admin

实测回显：

Sending registration request...
Success!

要点：-c 指向生成的 homeserver.yaml（读取其中的 registration_shared_secret 免交互）；--no-admin 建普通账号，发送账号与管理员账号都建议普通权限； homeserver 地址写容器内地址 http://localhost:8008。观察发送账号的实际行为可看 Synapse 日志（实测样例）：

Logging in user @pushbits:pushbits.local on device PushBits
POST /_matrix/client/v3/login HTTP/1.1" "mautrix-go/v0.24.0 go/1.24.3"
POST /_matrix/client/v3/createRoom HTTP/1.1" "mautrix-go/v0.24.0 go/1.24.3"

六、curl 等价 API（CI/脚本场景）

pbcli 交互式密码不适合无人值守，脚本场景直调 REST API（Basic 认证或应用 token）。pbcli 命令与 curl 的对应关系（全部实测）：

操作pbclicurl 等价
应用列表pbcli application list ...curl -s -u admin:*** http://HOST:8140/application
建应用pbcli application create NAME ...curl -s -u admin:*** -X POST "http://HOST:8140/application?name=NAME"
删应用pbcli application delete ID ...curl -s -u admin:*** -X DELETE http://HOST:8140/application/ID
用户列表pbcli user list ...curl -s -u admin:*** http://HOST:8140/user
发通知—（pbcli 不做）curl -s -X POST "http://HOST:8140/message?token=$PB_TOKEN&message=TEXT&title=T&priority=1"
撤回通知—curl -s -X DELETE "http://HOST:8140/message/URL_ENCODED_ID?token=$PB_TOKEN"
健康检查—curl -s http://HOST:8140/health

发通知实测回显（message 走 query 或 JSON body 均可，token 为应用令牌；响应里的 id_url_encoded 供撤回直接复用）：

{"id":"$pZvfW8KJZRbU76Sbc0hFiQJJmZdSD-iPvNYlnSpMpU8","id_url_encoded":"%24pZvfW8KJZRbU76Sbc0hFiQJJmZdSD-iPvNYlnSpMpU8","appid":1,"message":"S9 resume OK","title":"ResumeTest","priority":1,"date":"2026-10-26T13:33:18Z"}

撤回实测：DELETE /message/%24pZvf...?token=... 返回 HTTP 200，Matrix 房间内会跟一条"消息已删除"的回复通知。

Markdown/HTML 格式与 priority 语义见安装篇 8.3 与配置篇 4.7；完整接口定义参考官方 OpenAPI 文档。

七、Alertmanager 联动命令

Alertmanager 侧把 webhook receiver 指向 PushBits 的 /alert?token=<应用token> 即完成对接（receiver 配置见配置篇 4.8）。测试联动最直接的是用 curl 模拟 Alertmanager 报文（配置篇有完整实测），官方文档则提供 amtool 构造真实告警的途径：

# 安装（官方文档方式）
go install github.com/prometheus/alertmanager/cmd/amtool@latest
# 向本机 Alertmanager 加一条测试告警，经 webhook 流入 PushBits
amtool alert add alertname=testmessage --annotation=title='My Title' --annotation=message='My Message'

八、常见问题（FAQ）

Q1：脚本里怎么用 pbcli？ 密码只能从 TTY 读。无人值守场景用 curl 直调 API（第六章）；确需 pbcli 时用 expect 或 Python pty 应答 Current password / New password 两类提示（注意 user create 是两段密码提示，漏答第二段会一直挂起）。

Q2：pbcli v0.0.8（2023-07）配 server 0.10.7 兼容吗？ 实测兼容——application/user 十个子命令全部正常工作。pbcli 处于 alpha 阶段（官方 README 标注），大版本升级 server 后建议回归一遍用户/应用命令。

Q3：pbcli 有 --password 参数吗？ 没有（v0.0.8 帮助与二进制符号实查），这是有意为之的安全设计：避免密码进 shell history/ps。别用 expect -c "send \"密码\"" 把密码写进脚本文件，配合环境变量或交互输入。

Q4：普通用户能管理别人的应用吗？ 不能。应用按用户隔离，user 子命令仅 admin 身份可用，越权实测返回 403。

Q5：镜像里的 pbcli 和 Release 版有什么差别？ 功能一致但版本旧（2022-12 构建，version 显示 unknown）。容器内临时救急可用（docker exec <容器> pbcli ...），宿主机长期运维装 v0.0.8。

九、参考链接