PocketBase 0.40.5 常用 CLI 命令与工具详解

目标：完整梳理 PocketBase v0.40.5 单二进制内置 CLI——serve、superuser、migrate、update 四大子命令与全局参数，每个子命令配参数表与真实执行回显，并给出脚本化与排障注意事项。全部命令均在 Ubuntu 22.04.5 LTS 实测通过（安装与 systemd 托管见《Ubuntu 22.04 安装 PocketBase 0.40.5 指南》）。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（amd64）
PocketBase：v0.40.5（2026-10-21 官方最新稳定版）
安装目录：/opt/pocketbase；数据目录：/opt/pocketbase/pb_data
服务端口：8090；服务托管：systemd（pocketbase.service）
示例超级用户：admin@example.com / q1w2e3r4
迁移/升级实测辅助目录：/opt/migrate-test、/opt/upgrade-test

二、工具概览

PocketBase 没有独立的管理工具，所有 CLI 能力都内置于那一个 pocketbase 二进制，以子命令方式组织（交互式管理则走 /_/ 管理台，程序化调用走 REST API，三者数据同源）。

命令树（来自实测 ./pocketbase --help）：

子命令	作用	典型场景
`serve`	启动 Web 服务（默认 `127.0.0.1:8090`）	前台调试 / systemd 托管
`superuser`	管理超级用户（create/upsert/update/delete/ips/otp）	建号、重置密码、IP 白名单
`migrate`	执行数据库迁移脚本（up/down/create/collections/history-sync）	结构变更、快照集合配置
`update`	自动更新到最新版本	补丁跟进

子命令之外还有一组全局参数（--dir、--publicDir、--hooksDir、--dev、--encryptionEnv 等，逐项默认值见《PocketBase 0.40.5 配置参数详解》），紧跟在 pocketbase 与子命令之间使用，如 pocketbase --dir pb_data migrate up。

三、前置条件

确认二进制可执行、版本正确、服务健康：

cd /opt/pocketbase && ./pocketbase -v
systemctl is-active pocketbase
curl -s http://127.0.0.1:8090/api/health

实测输出：

pocketbase version 0.40.5
active
{"message":"API is healthy.","code":200,"data":{}}

💡 说明：pocketbase 不在系统 PATH 中，可直接用绝对路径 /opt/pocketbase/pocketbase，或 ln -s /opt/pocketbase/pocketbase /usr/local/bin/pocketbase 建软链后全局调用；本文统一在 /opt/pocketbase 目录内以 ./pocketbase 调用。所有子命令的操作对象（数据目录、迁移目录）默认相对当前工作目录解析，跨目录调用时建议显式带 --dir。

四、全局参数与版本查看

4.1 `--help`：全量命令与参数自述

./pocketbase --help

实测输出（全量）：

pocketbase CLI

Usage:
  pocketbase [command]

Available Commands:
  migrate     Executes app DB migration scripts
  serve       Starts the web server (default to 127.0.0.1:8090 if no domain is specified)
  superuser   Manage superusers
  update      Automatically updates the current app executable with the latest available version

Flags:
      --automigrate            enable/disable auto migrations (default true)
      --dev                    enable dev mode, aka. printing logs and sql statements to the console
      --dir string             the PocketBase data directory (default "pb_data")
      --encryptionEnv string   the env variable whose value of 32 characters will be used
                               as encryption key for the app settings (default none)
  -h, --help                   help for pocketbase
      --hooksDir string        the directory with the JS app hooks
      --hooksPool int          the total prewarm goja.Runtime instances for the JS app hooks execution (default 15)
      --hooksWatch             auto restart the app on pb_hooks file change; it has no effect on Windows (default true)
      --indexFallback          fallback the request to index.html on missing static path, e.g. when pretty urls are used with SPA (default true)
      --migrationsDir string   the directory with the user defined migrations
      --publicDir string       the directory to serve static files (default "pb_public")
      --queryTimeout int       the default SELECT queries timeout in seconds (default 30)
  -v, --version                version for pocketbase

Use "pocketbase [command] --help" for more information about a command.

4.2 `-v`：版本查看

./pocketbase -v

实测输出：

pocketbase version 0.40.5

⚠️ 注意：PocketBase 没有 version 子命令，只有 -v/--version 旗标。误用子命令形式的实测报错：

2026/10/21 09:28:30 unknown command "version" for "pocketbase"

五、serve 子命令详解

5.1 参数与默认行为

serve 参数表（来自实测 ./pocketbase serve --help，Flags 部分）：

参数	默认值	说明
`--http`	无域名参数时 `127.0.0.1:8090`；有域名参数时 `0.0.0.0:80`	HTTP 监听地址
`--https`	空字符串（不启用 TLS）；有域名参数时 `0.0.0.0:443`	HTTPS 监听地址，HTTP 自动跳转
`--origins`	`[*]`	CORS 允许来源列表

关键行为：不带任何参数的 pocketbase serve 只监听本机回环，适合调试；对外服务要么显式 --http=0.0.0.0:8090，要么传域名参数（serve example.com，此时自动申请/续期 HTTPS 证书并把 HTTP 301 到 HTTPS）。

5.2 启动与首启输出解读

前台启动（首次运行时输出最完整）：

timeout 8 ./pocketbase serve --http=0.0.0.0:8090

实测输出：

2026/10/21 09:29:06 Server started at http://0.0.0.0:8090
├─ REST API:  http://0.0.0.0:8090/api/
└─ Dashboard: http://0.0.0.0:8090/_/

(!) Launch the URL below in the browser if it hasn't been open already to create your first superuser account:
http://0.0.0.0:8090/_/#/pbinstall/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb2xsZWN0aW9uSWQiOiJwYmNfMzE0MjYzNTgyMyIsImV4cCI6MTc5MjU3Njc0NiwiaWQiOiIwdTdtZzM2cTZ0cjNnYmsiLCJyZWZyZXNoYWJsZSI6ZmFsc2UsInR5cGUiOiJhdXRoIn0.qwj3tCb_vBjDCfDmBeh1mS1z6getZIca6oPOBKwZIS4
(you can also create your first superuser by running: ./pocketbase superuser upsert EMAIL PASS)

三行结构化提示分别指向 REST API 根、管理台与首次超管安装链接（链接为一次性 JWT，过期失效，改用 CLI 建号更稳，见 6.2/6.3）。

启动验证：

curl -s http://127.0.0.1:8090/api/health

实测输出：

{"message":"API is healthy.","code":200,"data":{}}

5.3 生产托管形态

生产不建议前台跑，交给 systemd（单元文件、逐项说明与开机自启实测见《Ubuntu 22.04 安装 PocketBase 0.40.5 指南》第四节），ExecStart 即 serve 命令行；systemctl restart 对应前台场景的 Ctrl+C 后重启。运行日志从控制台转为 journal：

journalctl -u pocketbase --no-pager -n 4

实测输出：

Oct 21 09:29:52 pb-server systemd[1]: Started PocketBase service.
Oct 21 09:29:52 pb-server pocketbase[2822]: 2026/10/21 09:29:52 Server started at http://0.0.0.0:8090
Oct 21 09:29:52 pb-server pocketbase[2822]: ├─ REST API:  http://0.0.0.0:8090/api/
Oct 21 09:29:52 pb-server pocketbase[2822]: └─ Dashboard: http://0.0.0.0:8090/_/

5.4 端口占用报错

端口被占时 serve 直接退出并给出明确报错（服务已监听 8090 时再起一个实例实测）：

2026/10/21 09:49:54 listen tcp 127.0.0.1:8090: bind: address already in use

用 ss -ltn | grep 8090 定位占用方，或改 --http 换端口。

六、superuser 子命令详解

6.1 命令清单

./pocketbase superuser --help

实测输出（节选，保留命令清单）：

Manage superusers

Usage:
  pocketbase superuser [command]

Available Commands:
  create      Creates a new superuser
  delete      Deletes an existing superuser
  ips         Updates the superuser IPs whitelist setting (the IPs/subnets arguments must be space separated; leave empty to clear the whitelist restriction)
  otp         Creates a new OTP for the specified superuser
  update      Changes the password of a single superuser
  upsert      Creates, or updates if email exists, a single superuser

💡 说明：老版本教程中的 pocketbase admin 命令族在 v0.23 起已并入 superuser，网上旧文档命令对不上时先做此替换。

6.2 create：创建超级用户

./pocketbase superuser create admin@example.com q1w2e3r4

实测输出：

Successfully created new superuser "admin@example.com"!

邮箱已存在时报错退出（幂等场景请用 upsert）。所有 superuser 子命令的帮助都带用法示例，如 ./pocketbase superuser create --help 输出 Examples: superuser create test@example.com 1234567890。

6.3 upsert：创建或更新（幂等）

./pocketbase superuser upsert root@example.com q1w2e3r4

实测输出：

Successfully saved superuser "root@example.com"!

同邮箱再执行即为改密，适合放进初始化脚本重复执行。

6.4 update：改密码

./pocketbase superuser update root@example.com q1w2e3r4x
./pocketbase superuser update root@example.com q1w2e3r4

实测输出（两条各一行）：

Successfully changed superuser "root@example.com" password!
Successfully changed superuser "root@example.com" password!

💡 说明：忘记管理台密码时的标准自救命令，服务运行中执行即可，改完立即生效，无需重启。

6.5 delete：删除超级用户

./pocketbase superuser delete root@example.com

实测输出：

Successfully deleted superuser "root@example.com"!

6.6 ips：超级用户 IP 白名单

设置白名单（IP/网段空格分隔，可多个）：

./pocketbase superuser ips 127.0.0.1 10.0.0.0/24

实测输出：

Successfully updated SuperuserIPs setting:
├─ 127.0.0.1
└─ 10.0.0.0/24

不带参数执行即清空限制：

./pocketbase superuser ips

实测输出：

Successfully cleared SuperuserIPs setting!

💡 说明：白名单写入的是应用设置（superuserIPs 组），实测运行中服务即时读取新值，无需重启；生效范围是超级用户登录与管理台，应用用户不受影响。

6.7 otp：为超管生成一次性密码

./pocketbase superuser otp admin@example.com

实测输出（未开启 OTP 时的真实报错）：

2026/10/21 09:58:21 OTP auth is not enabled for the _superusers collection

⚠️ 注意：需先在管理台 _superusers 集合选项里启用 OTP（并配置 MFA/OTP 时长）后此命令才有产物；默认安装未开启，直接执行即得到上面回显。

七、migrate 子命令详解

7.1 命令清单

./pocketbase migrate --help

实测输出（全量）：

Supported arguments are:
- up            - runs all available migrations
- down [number] - reverts the last [number] applied migrations
- create name   - creates new blank migration template file
- collections   - creates new migration file with snapshot of the local collections configuration
- history-sync  - ensures that the _migrations history table doesn't have references to deleted migration files

Usage:
  pocketbase migrate [flags]

Flags:
  -h, --help   help for migrate

Global Flags:
      --automigrate            enable/disable auto migrations (default true)
      ...

💡 说明：serve 启动时默认自动执行迁移（--automigrate=true），migrate 子命令主要用于关闭自动迁移的场景、CI 初始化与集合配置快照管理。

7.2 up：执行迁移

cd /opt/migrate-test && cp -a /opt/pocketbase/pb_data .
./pocketbase --dir pb_data migrate up

实测输出：

No new migrations to apply.

7.3 collections：生成集合配置快照迁移

echo y | ./pocketbase --dir pb_data migrate collections

实测输出：

Do you really want to create migration "pb_migrations/1792575101_collections_snapshot.js"? (y/N) Successfully created file "pb_migrations/1792575101_collections_snapshot.js"

生成的快照为 JSVM 迁移文件，头部结构实测（节选）：

/// <reference path="../pb_data/types.d.ts" />
migrate((app) => {
  const snapshot = [
    {
      "createRule": null,
      "deleteRule": null,
      "fields": [
        ...

把 pb_migrations/ 纳入版本管理后，新环境用 migrate up 即可重建出完全相同的集合配置。

7.4 create：新建空白迁移模板

echo y | ./pocketbase --dir pb_data migrate create add_demo_field
cat pb_migrations/*_add_demo_field.js

实测输出：

Do you really want to create migration "pb_migrations/1792575122_add_demo_field.js"? (y/N) Successfully created file "pb_migrations/1792575122_add_demo_field.js"

/// <reference path="../pb_data/types.d.ts" />
migrate((app) => {
  // add up queries...
}, (app) => {
  // add down queries...
})

在模板的 up/down 回调里分别写正向与回滚操作。

7.5 down：回滚迁移

echo y | ./pocketbase --dir pb_data migrate down 1

实测输出：

1778828400_normalize_indexes.go
Do you really want to revert the last 1 applied migration(s)? (y/N) Reverted 1778828400_normalize_indexes.go

⚠️ 注意：down 会回滚已应用迁移（含二进制内置的核心迁移，如上例 normalize_indexes.go），schema 回滚不总是可逆且可能影响数据；执行前务必备份 pb_data，生产环境尽量只向前迁移。

7.6 history-sync：清理迁移历史

当 pb_migrations 里的文件被删除而历史表仍引用时，同步历史表：

./pocketbase --dir pb_data migrate history-sync

实测输出：

The _migrations table was synced with the available migrations.

7.7 交互确认的脚本化

collections、create、down 均有 (y/N) 确认提示，缺省回答即取消（实测不带管道执行时打印 The command has been cancelled 且不产生文件）。CI/脚本场景用 echo y | 前置喂入确认。

八、update 子命令详解

8.1 参数

./pocketbase update --help

实测输出（Flags 部分）：

Flags:
      --backup   Creates a pb_data backup at the end of the update process (default true)
  -h, --help     help for update

--backup 默认开启：更新过程结束时会自动对数据目录做一次 zip 备份。

8.2 已是最新版场景

cd /opt/pocketbase && echo y | ./pocketbase update

实测输出：

Fetching release information...
You already have the latest version 0.40.5.

8.3 真实升级实测（0.40.4 → 0.40.5）

在 /opt/upgrade-test 放入 v0.40.4 二进制后执行更新：

cd /opt/upgrade-test && ./pocketbase -v
echo y | ./pocketbase update
./pocketbase -v

实测输出（更新日志片段为程序实际打印内容）：

pocketbase version 0.40.4
- Other minor fixes _(godoc typos, normalized negative jsvm pool size, extra CORS wildcard subdomain checks to prevent misuse, support `Promise` as autocomplete suggestions return, autoexpand textarea scrollbar-gutter fix, etc.)_.
pocketbase version 0.40.5

更新产生的数据备份：

ls -lh pb_data/backups/

实测输出：

-rw-r--r-- 1 root root 225389 Oct 21 09:42 @update_v0.40.5.zip
-rw-r--r-- 1 root root    240 Oct 21 09:42 @update_v0.40.5.zip.attrs

⚠️ 注意：update 从 GitHub Releases 下载新包，需要服务器可直连 GitHub 且二进制目录可写；systemd 托管的服务更新二进制后需 systemctl restart pocketbase 切换进程。受限网络环境改用手动替换（下载新版 zip 解压覆盖后重启），见《Ubuntu 22.04 安装 PocketBase 0.40.5 指南》第六节。

九、注意事项

工作目录决定默认路径：pb_data/pb_migrations/pb_hooks/pb_public 均相对当前目录解析；跨目录调用务必显式 --dir，否则会"静默新建一套空数据目录"。
运行中执行 CLI 是安全的（个别除外）：superuser 族实测即时生效无需重启；migrate 会直接写数据库，虽有事务保护，仍建议在低峰或停服窗口执行，down 前必备份。
交互确认命令要喂 y：migrate collections/create/down 在无人值守终端会默认取消（实测 The command has been cancelled），脚本里统一 echo y | 前缀。
update 的两个前置：出网可达 GitHub、二进制目录可写；其自带 --backup 备份只覆盖数据目录，二进制回滚需自行保留旧版 zip。
命令对不上先查版本：v0.23 起 admin 命令族并入 superuser、Linux 发行包改 zip、无 version 子命令——照抄旧教程报错时先跑 ./pocketbase --help 对齐当前版本的命令树。

十、常见问题（FAQ）

Q1：执行 pocketbase version 报 unknown command？

版本查看用旗标不用子命令：./pocketbase -v（实测报错与正确输出见 4.2 节）。

Q2：superuser create 提示邮箱已存在？

说明账号已在。改密用 superuser update，"有则改无则建"用 superuser upsert（6.3/6.4 节实测）。

Q3：superuser otp 报 OTP auth is not enabled？

_superusers 集合默认未开 OTP。到管理台该集合的 Options 中启用 OTP/MFA 后重试（实测报错回显见 6.7 节）。

Q4：migrate collections 没生成文件就退出了？

交互确认被默认取消。确认提示 (y/N) 需显式回答，脚本用 echo y | ./pocketbase migrate collections（7.3/7.7 节实测）。

Q5：serve 报 bind: address already in use？

端口被占。ss -ltn | grep 8090 找占用进程，或改 --http=0.0.0.0:8091 换端口（实测报错见 5.4 节）。

Q6：update 一直卡在 Fetching release information？

出网受限导致下载阻塞。Ctrl+C 后改手动替换二进制：下载新版 zip → unzip -o 覆盖 → systemctl restart pocketbase（升级实测对照见 8.3 节与 B1 指南第六节）。

十一、参考链接

官方文档：https://pocketbase.io/docs
官方仓库：https://github.com/pocketbase/pocketbase
Releases（版本与更新日志）：https://github.com/pocketbase/pocketbase/releases
站内延伸：《PocketBase 介绍与选型指南》、《Ubuntu 22.04 安装 PocketBase 0.40.5 指南》、《PocketBase 0.40.5 配置参数详解》

PocketBase 0.40.5 常用 CLI 命令与工具详解

PocketBase 0.40.5 常用 CLI 命令与工具详解

一、环境信息

二、工具概览

三、前置条件

四、全局参数与版本查看

4.1 --help：全量命令与参数自述

4.2 -v：版本查看

五、serve 子命令详解

5.1 参数与默认行为

5.2 启动与首启输出解读

5.3 生产托管形态

5.4 端口占用报错

六、superuser 子命令详解

6.1 命令清单

6.2 create：创建超级用户

6.3 upsert：创建或更新（幂等）

6.4 update：改密码

6.5 delete：删除超级用户

6.6 ips：超级用户 IP 白名单

6.7 otp：为超管生成一次性密码

七、migrate 子命令详解

7.1 命令清单

7.2 up：执行迁移

7.3 collections：生成集合配置快照迁移

7.4 create：新建空白迁移模板

7.5 down：回滚迁移

7.6 history-sync：清理迁移历史

7.7 交互确认的脚本化

八、update 子命令详解

8.1 参数

8.2 已是最新版场景

8.3 真实升级实测（0.40.4 → 0.40.5）

九、注意事项

十、常见问题（FAQ）

十一、参考链接

4.1 `--help`：全量命令与参数自述

4.2 `-v`：版本查看