Ubuntu 22.04 安装 PushBits 0.10.7 指南

目标：在 Ubuntu 22.04 服务器上从零安装 PushBits 0.10.7 推送通知中继服务：官方 Release 二进制下载与校验、专用系统用户与目录布局、config.yml 核心配置、systemd 托管开机自启、健康检查与「建应用→发消息→Matrix 收信」全链路验证。本文全部命令与回显均来自真实环境实测（Matrix 投递链路对接一台自建 Synapse homeserver 完成）。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
软件版本：PushBits v0.10.7（当前官方最新稳定版，GitHub Releases 2025-05-29 发布，实查日期 2026-10-26）
部署布局：
- 二进制：/opt/pushbits/server（Release tar 包平铺结构，仅含 server、README.md、LICENSE 三个文件）
- 运行用户：系统用户 pushbits（nologin）
- 配置文件：/opt/pushbits/config.yml（程序从工作目录加载 config.yml，故配置放在工作目录内）
- 数据目录：/var/lib/pushbits/（SQLite 库文件 pushbits.db）
- 服务单元：/etc/systemd/system/pushbits.service
监听端口：8080（HTTP API，可改）
外部依赖：一台可访问的 Matrix homeserver（默认 https://matrix.org，也可自建 Synapse 等，用于投递通知）与一个专用发送账号；管理员的 Matrix ID（接收管理通知）
前置软件：curl、wget、ca-certificates

⚠️ 注意：官方文档站写明"目前唯一支持的安装途径是 Docker 或 Podman"，但官方 Releases 同步发布 linux amd64/arm64 二进制与 checksums，本指南按该官方产物走裸机安装路径，全部步骤实测可复现。

二、前置条件

安装前先确认系统具备下载与解压能力，并规划好 Matrix 侧的两个前置账号：

更新索引并安装基础工具（curl/wget 用于下载与验证，ca-certificates 保证 HTTPS 正常）：

apt-get update && apt-get install -y curl wget ca-certificates

实测验证（版本随补丁更新略有差异，能正常输出版本即具备条件）：

curl --version | head -1

实测回显：

curl 7.81.0 (x86_64-pc-linux-gnu) libcurl/7.81.0 OpenSSL/3.0.2 zlib/1.2.11 brotli/1.0.9 zstd/1.4.8 libidn2/2.3.2 libpsl/0.21.0 (+libidn2/2.3.2) libssh/0.9.6/openssl/zlib nghttp2/1.43.0 librtmp/2.3 OpenLDAP/2.5.20

准备 Matrix 侧前置（取值方法）：PushBits 首次启动前必须有可用的 Matrix 账号体系，需准备：
- 发送账号：一个专用于发通知的 Matrix 账号（如用户名 pushbits），记录其用户名与密码——PushBits 用它登录 homeserver 给所有人发消息；
- 管理员的 Matrix ID：管理员接收系统通知的 Matrix ID，完整格式为 @用户名:homeserver域名（如 @admin:matrix.org）；本文演示按 admin/q1w2e3r4 与 pushbits/q1w2e3r4 两套演示账号书写（演示口令，生产必须更换），homeserver 地址以官方默认 https://matrix.org 书写；若使用自建 homeserver，将配置中的 homeserver 地址与 Matrix ID 域名一并替换为自建实例的值即可，其余步骤完全一致。

💡 技术拓展：Matrix 账号的注册方式不止一种——公共 homeserver（matrix.org）网页注册、自建 homeserver 的 register_new_matrix_user 命令注册、以及开启开放注册后的 API 注册。本文按"已有可用账号"推进，自建 homeserver 的搭建不在本篇范围内。无论哪种来源的账号，PushBits 侧只关心 homeserver 地址、用户名、密码三项。

三、版本选型说明

本文锁定 v0.10.7（撰写时的最新稳定版，2026-10-26 实查 GitHub Releases）。0.x 阶段版本间可能存在配置/API 不兼容变更，生产环境务必锁定具体版本，升级前先读 Release Notes。
官方 Release 产物清单（v0.10.7 实查）：server_0.10.7_linux_amd64.tar.gz、server_0.10.7_linux_arm64.tar.gz、server_0.10.7_checksums.txt。按主机架构选包：uname -m 输出 x86_64 选 amd64、aarch64 选 arm64。
官方另有 ghcr.io 镜像（ghcr.io/pushbits/server），容器化部署见本专栏 Compose 篇；本篇走二进制路径。

四、官方 Release 下载与校验

创建源码/安装包暂存目录，下载 v0.10.7 的 amd64 包与 checksums 文件并校验完整性：

mkdir -p /opt/src && cd /opt/src
wget https://github.com/pushbits/server/releases/download/v0.10.7/server_0.10.7_linux_amd64.tar.gz
wget https://github.com/pushbits/server/releases/download/v0.10.7/server_0.10.7_checksums.txt

下载完成后校验 checksums（checksums.txt 包含 amd64/arm64 两行，只下载了 amd64 包时 arm64 行会报 FAILED open or read，可忽略；重点看 amd64 行为 OK）：

sha256sum -c server_0.10.7_checksums.txt

实测回显：

sha256sum: server_0.10.7_linux_arm64.tar.gz: No such file or directory
sha256sum: WARNING: 1 listed file could not be read
server_0.10.7_linux_amd64.tar.gz: OK
server_0.10.7_linux_arm64.tar.gz: FAILED open or read

⚠️ 注意：若 wget 直连 GitHub 下载缓慢或超时，可走代理下载：wget -x http://192.168.1.62:7897 <URL>（内网代理按实际环境替换）；本文实测当时直连可用（约 78 KB/s，7 MB 包约 88 秒）。ls -la 确认包大小为 7028701 字节，与校验 OK 双重确认文件完整。

💡 技术拓展：完整性校验方式不止 checksums 一种——GitHub Release 页面对资产自带 HTTPS 传输保障，checksums.txt 防「下载截断/被篡改」；更严格的场景可叠加 GPG 签名验证或对比 Release 页面展示的 SHA256 值。本方案实际采用官方 checksums.txt + sha256sum -c，轻量且够用。

五、安装步骤（目录布局与系统用户）

5.1 解压并查看包内容

mkdir -p /opt/src/extract && tar -xzf server_0.10.7_linux_amd64.tar.gz -C extract && ls -la extract/

实测回显：

total 18224
drwxr-xr-x 2 root root     4096 Oct 26 11:40 .
drwxr-xr-x 3 root root     4096 Oct 26 11:40 ..
-rw-r--r-- 1 1001  118      785 May 29  2025 LICENSE
-rw-r--r-- 1 1001  118     4333 May 29  2025 README.md
-rwxr-xr-x 1 1001  118 18639280 May 29  2025 server

包为平铺结构：server 即主程序二进制（约 17.8 MB），无嵌套目录；属主显示为 tar 内保留的构建者 uid/gid，文件时间即 Release 构建日（2025-05-29）。

5.2 创建专用系统用户

遵循最小权限原则，创建无登录 shell 的系统用户：

useradd --system --user-group --home-dir /opt/pushbits --shell /usr/sbin/nologin pushbits
getent passwd pushbits

实测回显：

pushbits:x:999:999::/opt/pushbits:/usr/sbin/nologin

5.3 安装二进制与数据目录

mkdir -p /opt/pushbits /etc/pushbits /var/lib/pushbits
install -m 0755 /opt/src/extract/server /opt/pushbits/server
cp /opt/src/extract/README.md /opt/src/extract/LICENSE /opt/pushbits/
chown -R pushbits:pushbits /opt/pushbits /var/lib/pushbits
ls -la /opt/pushbits/

实测回显：

total 18224
drwxr-xr-x 2 pushbits pushbits     4096 Oct 26 11:40 .
drwxr-xr-x 1 root     root         4096 Oct 26 11:40 ..
-rw-r--r-- 1 pushbits pushbits      785 Oct 26 11:40 LICENSE
-rw-r--r-- 1 pushbits pushbits     4333 Oct 26 11:40 README.md
-rwxr-xr-x 1 pushbits pushbits 18639280 Oct 26 11:40 server

验证程序可执行并确认版本号（在 /opt/pushbits 工作目录内执行，程序启动即打印版本）：

cd /opt/pushbits && timeout 5 ./server 2>&1 | head -2

实测回显：

level=info msg="Starting PushBits v0.10.7"
level=fatal msg="M_LIMIT_EXCEEDED (HTTP 429): Too Many Requests"

⚠️ 注意：上面第二行 fatal 是因为实验环境里 Matrix homeserver 正在限流登录请求，属「Matrix 连通性」问题而非二进制问题——它恰好证明程序已跑通到「连接 homeserver」这一步。空目录直接运行还会因为缺 config.yml 报错，下一章先写配置。

六、配置说明（config.yml）

6.1 配置加载规则

PushBits 启动时从当前工作目录加载 config.yml（无命令行参数指定路径的能力，--version/--help 也不被识别，直接进入配置加载）。在错误目录运行时的真实报错（排障实录）：

level=info msg="Starting PushBits v0.10.7"
Failed to find configuration config.yml
panic: MatrixID is required, but blank

goroutine 1 [running]:
github.com/pushbits/server/internal/configuration.Get()
	/home/runner/work/server/server/internal/configuration/configuration.go:113 +0x16b
main.main()
	/home/runner/work/server/server/cmd/pushbits/main.go:59 +0x32

因此 systemd 单元必须设置 WorkingDirectory=/opt/pushbits。所有配置项也可用 PUSHBITS_ 前缀的环境变量覆盖（如 PUSHBITS_HTTP_PORT），键名按下划线逐级拼接。

6.2 写入最小可用配置

创建 /opt/pushbits/config.yml（账号取值方法见第二章第 2 步；演示口令，生产必须更换）：

debug: false

http:
    listenaddress: ""
    port: 8080
    trustedproxies: []
    certfile: ""
    keyfile: ""

database:
    dialect: "sqlite3"
    connection: "/var/lib/pushbits/pushbits.db"

admin:
    name: "admin"
    password: "q1w2e3r4"
    matrixid: "@admin:matrix.org"

matrix:
    homeserver: "https://matrix.org"
    username: "pushbits"
    password: "q1w2e3r4"

security:
    checkhibp: false

crypto:
    argon2:
        memory: 131072
        iterations: 4
        parallelism: 4
        saltlength: 16
        keylength: 32

formatting:
    coloredtitle: false

alertmanager:
    annotationtitle: title
    annotationmessage: message

repairbehavior:
    resetroomname: true
    resetroomtopic: true

逐项说明：

debug：调试日志开关；生产保持 false。开启后 gin 路由表与 SQL 语句都会打到日志（排障时临时打开）。
http.port：API 监听端口，默认 8080；listenaddress 留空表示监听所有网卡。certfile/keyfile 配 TLS 证书路径——官方建议把 PushBits 放在反代之后，由反代终止 TLS，故本篇留空。
database.dialect/connection：存储方言与连接参数；sqlite3 时 connection 是库文件路径（本文放 /var/lib/pushbits/pushbits.db），也可换 mysql/postgres（connection 相应写 DSN 连接串）。
admin.name/admin.password：首次启动自动创建的管理员用户名/密码（登录管理 API 用）。
admin.matrixid：管理员的 Matrix ID，PushBits 会把「用户创建、应用 token 变动」等管理事件投递到该账号，属必填项，缺失时启动即 panic。
matrix.homeserver/username/password：发送账号三要素——PushBits 以此账号登录 homeserver 建房间、发消息，三项都必填。
security.checkhibp：创建/修改密码时是否对接 Have I Been Pwned 校验弱口令，默认关。
crypto.argon2：密码哈希 KDF 参数，默认值（memory 131072 KB/iterations 4/parallelism 4）安全且够用，无特殊需求不要动。
formatting.coloredtitle：按消息 priority 给 Matrix 消息标题着色（<0 灰、0-3 默认、4-10 黄、10-20 橙、>20 红）。
alertmanager.*：Alertmanager webhook 接入时从告警 annotations 里取标题/正文的键名。
repairbehavior.*：发现通知房间名/话题被改后是否自动重置回 PushBits 设定值。

赋权并校验文件归 pushbits 用户所有：

chown pushbits:pushbits /opt/pushbits/config.yml && ls -l /opt/pushbits/config.yml

实测回显：

-rw-r--r-- 1 pushbits pushbits 739 Oct 26 11:51 /opt/pushbits/config.yml

七、systemd 托管（开机自启）

创建服务单元 /etc/systemd/system/pushbits.service：

[Unit]
Description=PushBits push notification relay server
Documentation=https://pushbits.github.io/docs/
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=pushbits
Group=pushbits
WorkingDirectory=/opt/pushbits
ExecStart=/opt/pushbits/server
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/pushbits

[Install]
WantedBy=multi-user.target

单元要点：WorkingDirectory 决定 config.yml 能否被找到；ProtectSystem=strict 把整个文件系统挂为只读、仅 ReadWritePaths=/var/lib/pushbits 放行数据库写入，NoNewPrivileges 禁止提权——三行构成基本沙箱；Restart=on-failure 保证异常退出 5 秒后自动拉起（homeserver 短暂不可达时自动重试）。

启用并启动：

systemctl daemon-reload
systemctl enable pushbits
systemctl start pushbits

实测回显（enable 一步）：

Created symlink /etc/systemd/system/multi-user.target.wants/pushbits.service → /etc/systemd/system/pushbits.service.

确认运行状态：

systemctl status pushbits --no-pager -l | head -12

实测回显：

● pushbits.service - PushBits push notification relay server
     Loaded: loaded (/etc/systemd/system/pushbits.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2026-10-26 11:40:51 UTC; 7s ago
       Docs: https://pushbits.github.io/docs/
   Main PID: 2688 (server)
      Tasks: 9 (limit: 19553)
     Memory: 133.4M
        CPU: 502ms
     CGroup: /system.slice/pushbits.service
             └─2688 /opt/pushbits/server

💡 说明：常驻内存约 130 MB 是正常水位——Argon2 参数里 memory=131072（128 MB）会在密码哈希时预分配内存，加上 Go 运行时开销。1 核 1 GB 以上的服务器均可流畅运行。

八、安装验证（健康检查 + 全链路实测）

8.1 健康检查端点

/health 是无认证的健康检查端点，返回 HTTP 200 与空 JSON 对象：

curl -s http://localhost:8080/health
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/health

实测回显：

{}
200

8.2 管理员账号验证（Basic 认证）

用首次启动自动创建的 admin 账号登录用户列表接口，确认管理员已就位：

curl -s -u admin:q1w2e3r4 http://localhost:8080/user

实测回显：

[{"id":1,"name":"admin","is_admin":true,"matrix_id":"@admin:pushbits.local"}]

💡 说明：回显中 Matrix ID 的域名部分为本文实验对接的自建 homeserver（pushbits.local）；实际部署时会显示你在 config.yml 里配置的 admin.matrixid。另注意：首次启动日志里若看到 Priviledged user admin already exists.（官方拼写即如此）表示管理员账号沿用上次创建的记录——PushBits 只在首次启动时按 config.yml 的 admin 段创建管理员，之后修改 admin.password 配置不会改已存在账号的密码（改密走 PUT /user API，见本专栏 API 篇）。

8.3 建应用 + 发消息 + Matrix 收信全链路

创建一个名为 server-monitor 的应用（即消息频道），拿到 token：

curl -s -u admin:q1w2e3r4 -X POST "http://localhost:8080/application?name=server-monitor&strict_compatibility=false"

实测回显：

{"id":5,"token":"Ap3GDiTJp432JQIdhgyFo4HlLhxcjehYifYlBrkJQeokfim7oCZomhjNMgmmPnL9","name":"server-monitor"}

用该 token 发送一条告警消息（message 必填，title/priority 可选）：

curl -s --header "Content-Type: application/json" --request POST \
  --data '{"message":"磁盘使用率已达 92%，请尽快处理","title":"【告警】/dev/sda1 磁盘水位","priority":4}' \
  "http://localhost:8080/message?token=Ap3GDiTJp432JQIdhgyFo4HlLhxcjehYifYlBrkJQeokfim7oCZomhjNMgmmPnL9"

实测回显：

{"id":"$JwU0zPOGTGDRGePTFcefzT9ho9XaCG4R-kFQBqoZZVc","id_url_encoded":"%24JwU0zPOGTGDRGePTFcefzT9ho9XaCG4R-kFQBqoZZVc","appid":5,"message":"磁盘使用率已达 92%，请尽快处理","title":"【告警】/dev/sda1 磁盘水位","priority":4,"date":"2026-10-26T11:45:04.739922647Z"}

再发一条 Markdown 格式消息（extras.client::display.contentType 指定格式）：

curl -s --header "Content-Type: application/json" --request POST \
  --data '{"message":"备份任务完成，详情请见 [运行报告](https://example.com/report)","title":"每日备份","extras":{"client::display":{"contentType":"text/markdown"}}}' \
  "http://localhost:8080/message?token=Ap3GDiTJp432JQIdhgyFo4HlLhxcjehYifYlBrkJQeokfim7oCZomhjNMgmmPnL9"

实测回显：

{"id":"$HjbgLFHMhHMpH5Kcne5GUjHiuwF6de7M4EafUhOxkPk","id_url_encoded":"%24HjbgLFHMhHMpH5Kcne5GUjHiuwF6de7M4EafUhOxkPk","appid":5,"message":"备份任务完成，详情请见 [运行报告](https://example.com/report)","title":"每日备份","priority":0,"extras":{"client::display":{"contentType":"text/markdown"}},"date":"2026-10-26T11:45:04.769011862Z"}

判定投递成功的三个证据（全部来自实测）：

响应里的 id 是 $ 开头的 Matrix 事件 ID——PushBits 只有在 homeserver 接受消息后才拿到该 ID 并返回；
响应同时给出 id_url_encoded，供后续 DELETE /message/{id} 撤回消息直接使用；
homeserver 侧日志可见 PushBits 发送账号的登录与建房间行为（以自建 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" [0 dbevts]
POST /_matrix/client/v3/createRoom HTTP/1.1" "mautrix-go/v0.24.0 go/1.24.3" [0 dbevts]

管理员在自己的 Matrix 客户端（Element 等）登录 @admin:... 账号后，会收到来自 PushBits 发送账号的房间邀请，接受即可看到上述两条通知——首次部署务必在客户端里接受一次邀请，房间才会出现在会话列表。

💡 技术拓展：消息格式除 text/plain、text/html、text/markdown 三种 contentType 外，消息体还有 priority 优先级通道（整数，配合 formatting.coloredtitle 影响标题颜色）；Gotify 报文里的 extras 键位设计与 PushBits 完全兼容（官方明确"inspired by Gotify's message extras"），因此原打向 Gotify 的脚本只需换 URL 与 token 即可平移到 PushBits。

九、方案对比与选择建议

维度	本篇：Release 二进制 + systemd	官方途径：ghcr.io 镜像（见 Compose 篇）
获取方式	GitHub Releases tar.gz + sha256 校验	镜像仓库拉取
升级方式	换二进制重启（配置/数据库留在原位）	换镜像 tag 重建
环境依赖	无（单二进制，仅需 glibc）	需要 Docker/Podman
与 Matrix 官方支持口径	官方未文档化但产物完整可用（本文实测背书）	官方文档明确支持
适用场景	无容器环境的传统服务器、对启动链路要细粒度掌控	已有容器平台、追求标准化交付

关键差异/如何选：能上容器就用官方镜像（与官方支持口径一致、升级回滚干净）；宿主机无容器运行时或要纳入既有 systemd 运维体系时用本篇的二进制路径，本文已实测其完整可用。

十、常见问题（FAQ）

Q1：启动即报 panic: MatrixID is required, but blank 怎么办？ 配置里 admin.matrixid 没填或 config.yml 没被找到（工作目录不对）。确认 systemd 单元 WorkingDirectory=/opt/pushbits，并核对 config.yml 的 admin.matrixid 已填完整 Matrix ID（@用户名:域名）。

Q2：启动报 Failed to find configuration config.yml？ 程序只从当前工作目录加载配置。在正确目录运行（cd /opt/pushbits && ./server），或用 systemd 的 WorkingDirectory 指定。不会读 /etc/pushbits/ 下的文件——该目录仅适合放你自己引用的副本。

Q3：服务反复重启（activating ↔ failed 循环），日志出现 level=fatal msg="M_LIMIT_EXCEEDED (HTTP 429): Too Many Requests"？ Matrix homeserver 对登录接口限流，而 Restart=on-failure 让 PushBits 每 5 秒重试登录，持续触发限流形成死循环。处理：systemctl stop pushbits 等限流窗口过去（Synapse 默认约 1–4 分钟），再 systemctl start pushbits。频繁重启调试配置时尤其要注意。

Q4：systemctl start 后服务 active 但 curl /health 连不上？ 检查监听端口是否被改（http.port）、listenaddress 是否误设为仅本机地址，以及防火墙（ufw status/iptables -L -n）是否放行 8080。

Q5：忘记 admin 密码怎么办？ config.yml 里的 admin.password 只在首次建号时生效。改密走 PUT /user/{id} 管理 API（本专栏 API 篇有实测示例）；若所有管理员凭据都丢失，最彻底的办法是停服后删除 SQLite 库重建（rm /var/lib/pushbits/pushbits.db，注意会清空全部用户与应用）。

Q6：首次启动后立刻创建应用返回 [] 且应用列表为空？ 实测发现服务刚启动的短窗口内（约半分钟内）POST /application 偶发返回 200 + [] 且未落库，稍后重试即恢复正常；判断应用是否创建成功以 GET /application 列表为准，不要只看 POST 响应。

十一、升级与卸载

升级：下载新版 tar.gz 并校验 → 停服 systemctl stop pushbits → 替换 /opt/pushbits/server 二进制 → systemctl start pushbits。SQLite 库与配置不受影响；0.x 阶段升级前务必读目标版本 Release Notes，先在测试机验证 config.yml 兼容性。

降级：同升级流程，把二进制换回旧版即可（SQLite schema 若已被新版迁移，回退前先备份 /var/lib/pushbits/ 整目录）。

卸载：

systemctl disable --now pushbits
rm /etc/systemd/system/pushbits.service
systemctl daemon-reload
rm -rf /opt/pushbits /var/lib/pushbits /opt/src
userdel pushbits

十二、参考链接

官方文档站 Getting Started：https://pushbits.github.io/docs/ （查询日期 2026-10-26）
v0.10.7 Release 与产物列表：https://github.com/pushbits/server/releases/tag/v0.10.7 （查询日期 2026-10-26）
配置样例 config.example.yml：https://github.com/pushbits/server/blob/main/config.example.yml （查询日期 2026-10-26）
环境变量说明（PUSHBITS_ 前缀规则）：官方文档站 Configuration 节（查询日期 2026-10-26）
站内关联：《PushBits 0.10.7 介绍与选型指南》、Compose 部署与配置参数详解见本专栏后续篇目