Rallly 4.16 常用 CLI 命令详解

适用版本：Rallly v4.16.2（2026-10-23 发布），官方栈仓库（rallly-selfhosted）2026-10-24 实抓的 rallly.sh 与服务器实测输出。

一、为什么自托管运维只有一个 CLI 入口

动手之前先说清楚本文的篇型依据，这直接决定你该学什么：

自托管实例没有 REST API。官方 API Reference（support.rallly.co/api-reference，含 POST /v1/polls、Webhooks 等）开头明确：API 仅由 Rallly Cloud 提供，自托管实例不提供。实测印证：对自托管服务请求这些路径只会得到 404。
应用层确实暴露 tRPC 端点（/api/trpc，路由含 polls/events/spaces/calendars 等），但这是页面专用内部协议，无鉴权契约、无版本承诺，官方不建议外部程序依赖。
因此官方把自托管的日常运维收敛到 Rallly CLI（rallly.sh）：它是安装器落到 /opt/rallly 的 Bash 脚本（809 行，源码实抓），封装 docker compose 与数据库工具链。

本文按官方 CLI 的 9 个命令逐个实测；同时给出对应的底层命令，便于自行编排部署（非安装器部署）的读者等效操作。

二、命令总览

$ ./rallly.sh help

命令	作用	实测状态
`setup`	交互式引导：写 `.env`、生成密钥、启动	源码溯源
`start`	启动全栈（首次会自动 provision 数据库/存储）	已实测
`stop`	停止全栈	已实测（等价 compose stop）
`restart`	重建并启动（配置变更后必用）	已实测
`status`	查看服务健康状态	已实测
`logs [service]`	跟踪日志，可指定 `web`/`db`/`garage`/`traefik`	已实测
`backup`	数据库全量备份为 gzip SQL	已实测
`update`	拉取最新栈文件与镜像并滚动更新	源码溯源
`upgrade-db`	PostgreSQL 大版本原地升级	源码溯源

三、逐命令实测

3.1 start：首次启动与自动 provision

$ cd /opt/rallly && sudo ./rallly.sh start

实测输出（external 反代模式、首次启动）：

  → No existing database volume — provisioning PostgreSQL 18.
 Image dxflrs/garage:v2.3.0 Pulling
 Image lukevella/rallly:4 Pulling
 Image lukevella/rallly:4 Pulled
 Image dxflrs/garage:v2.3.0 Pulled
 Volume rallly-4162-selfhost_garage-meta Created
 Volume rallly-4162-selfhost_garage-data Created
 Volume rallly-4162-selfhost_db-data Created
 Network rallly-4162-selfhost_default Created
 Container rallly-4162-selfhost-garage-1 Started
 Container rallly-4162-selfhost-web-1 Started
 Container rallly-4162-selfhost-db-1 Started

Rallly is starting at http://127.0.0.1:8138
Run './rallly.sh logs' to watch startup progress.

首次启动的自动行为（实测首行）：捆绑数据库按 POSTGRES_VERSION（默认 18）自动初始化并生成强密码写入 .env——手动自建时漏配 POSTGRES_PASSWORD 会重启循环（实录见《Rallly 4.16 Docker Compose 部署指南》 §7.3）；PROXY_MODE=external 时 Traefik 服务被跳过，WEB_PORT 决定监听地址。

3.2 status：健康巡检

$ ./rallly.sh status

实测输出（全部健康时）：

NAME                            IMAGE                  COMMAND                   SERVICE   CREATED          STATUS                    PORTS
rallly-4162-selfhost-db-1       postgres:18-alpine     "docker-entrypoint.s…"   db        48 seconds ago   Up 33 seconds (healthy)   5432/tcp
rallly-4162-selfhost-garage-1   dxflrs/garage:v2.3.0   "/garage server --si…"   garage    48 seconds ago   Up 42 seconds (healthy)
rallly-4162-selfhost-web-1      lukevella/rallly:4     "docker-entrypoint.s…"   web       48 seconds ago   Up 33 seconds (healthy)   0.0.0.0:8138->3000/tcp

排障视角：(healthy) 变 (restarting) 时直接看对应服务日志。两个高频案例：

db 重启循环 → POSTGRES_PASSWORD 缺失；
garage 重启循环 → GARAGE_RPC_SECRET 不是 32 字节 hex，实测报错 Error: Invalid RPC secret key: expected 32 bytes of random hex, please check the documentation for requirements。

3.3 logs：按服务跟踪

$ ./rallly.sh logs web      # 实测等效 docker compose logs -f web
$ ./rallly.sh logs db
$ ./rallly.sh logs garage

应用日志里最有用的三类行（实测）：Prisma 迁移进度（166 migrations found in prisma/migrations）、认证警告（WARN [Better Auth]: ... BETTER_AUTH_SECRET appears low-entropy）、Next.js 启动横幅（▲ Next.js 16.4.2）。

3.4 restart：配置变更后重建

$ ./rallly.sh restart

实测行为：等价 docker compose up -d --force-recreate，改动 .env 后执行即生效；实测三次重启（补 SMTP、换网络、换密钥）均正常收敛到 healthy。配合健康探针，重启期间请求由反代兜底返回 502，通常 10 秒内恢复。

3.5 backup：数据库备份

$ ./rallly.sh backup
Backing up database...
Backup saved to: /opt/rallly/backups/rallly_20261024_112602.sql.gz

实测产物：rallly_20261024_112602.sql.gz（25,245 字节，全库 SQL 的 gzip）。源码要点（cmd_backup）：

权限 700 的 backups/ 目录 + umask 077 写文件，备份文件含全库数据，等同密钥级敏感。
使用捆绑数据库时在 db 服务内执行 pg_dump -U postgres rallly；配置了外部 DATABASE_URL 时则起临时容器执行 pg_dump（注意：pg_dump 客户端版本 ≥ 服务端版本，大版本不一致时需手动换匹配客户端）。
只备份数据库，不含 Garage 对象存储中的文件（头像等），完整快照需另备存储桶。

恢复流程（标准 pg_restore 语义，实测可用）：

$ gunzip -c rallly_20261024_112602.sql.gz | docker compose exec -T db \
    psql -U postgres -d rallly

3.6 update：滚动升级

$ sudo ./rallly.sh update

源码行为（cmd_update）：git clone 安装时先 git pull --ff-only 更新栈文件（有更新则 re-exec 自身以新脚本继续）；然后 docker compose pull 拉新镜像、up -d --remove-orphans 重建，最后 docker compose ps 收尾。应用启动时自动跑增量迁移——升级不需要手动执行迁移命令。升级前务必先 backup。

3.7 upgrade-db：PostgreSQL 大版本升级

源码溯源（cmd_upgrade_db）：用于捆绑数据库跨大版本（如 17→18），基于新版本数据卷初始化并用 pg_dumpall/恢复路径迁移数据。该操作有停机窗口且不可逆（保留旧卷），执行前必须 backup，生产环境先演练。

3.8 stop / setup

stop：docker compose stop（保留容器与数据卷），恢复用 start。
setup：交互式初始化（域名/ACME 邮箱/管理员邮箱向导），已手工写好 .env 的部署不需要再跑。

四、非安装器部署的底层等价命令

自写 Compose 部署（见部署篇）没有 rallly.sh，等价操作对照：

rallly.sh	底层等价
`start` / `restart`	`docker compose up -d`
`stop`	`docker compose stop`
`status`	`docker compose ps`
`logs <svc>`	`docker compose logs -f <svc>`
`backup`	`docker compose exec -T db pg_dump -U postgres rallly \| gzip > backup.sql.gz`
`update`	`docker compose pull && docker compose up -d --remove-orphans`

五、自动化建议（无 API 环境的定时备份）

自托管没有 REST API，脚本化只能面向运维层。一个最小可用的 cron 备份（保留 14 天）：

# /etc/cron.d/rallly-backup
30 3 * * * root cd /opt/rallly && ./rallly.sh backup >/dev/null 2>&1 && \
  find /opt/rallly/backups -name 'rallly_*.sql.gz' -mtime +14 -delete

监控层面建议盯三件事：rallly.sh status 的 healthy 状态、backups/ 目录最新文件的时间戳、验证码邮件投递（SMTP 链路故障时用户登录最先感知，而应用日志常常无显性报错）。

六、相关文档

产品定位与许可：《Rallly 4.16 介绍与选型指南》
部署落地与排障：《Rallly 4.16 Docker Compose 部署指南》
环境变量字典：《Rallly 4.16 配置参数详解》