PocketBase 0.40.5 配置参数详解

目标：系统梳理 PocketBase v0.40.5 的两大配置体系——serve 命令行参数与应用设置（Settings API），逐项给出真实默认值、修改方式与实测验证，并给出可直接落地的生产配置模板。全部命令与输出均在 Ubuntu 22.04.5 LTS 实测通过（服务以 systemd 托管、监听 8090，安装过程见《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（pocketbase serve 默认端口）
服务托管：systemd（pocketbase.service）
管理台：http://127.0.0.1:8090/_/；示例超级用户 admin@example.com / q1w2e3r4

二、前置条件

按《Ubuntu 22.04 安装 PocketBase 0.40.5 指南》完成安装，并确认服务健康：

systemctl is-active pocketbase
curl -s http://127.0.0.1:8090/api/health

实测输出：

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

本文操作均以 root 执行；用到超级用户 token 的 API 调用需先登录获取 token（见 3.3 节）。

三、参数查看与修改方式

3.1 两类配置体系

PocketBase 的配置分两类，作用面与生效方式不同：

配置体系	内容	查看方式	修改方式	生效时机
命令行参数	全局 flags + `serve` flags	`--help`	systemd 单元 `ExecStart` / 启动命令	需重启服务
应用设置（Settings）	邮件、S3、备份、日志、限流、批处理等运行时设置	管理台 Settings / `GET /api/settings`	管理台 UI / `PATCH /api/settings` / 部分 CLI 子命令	保存后即时生效

3.2 查看命令行参数

cd /opt/pocketbase && ./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.

serve 子命令自身还有 3 个专属参数：

./pocketbase serve --help

实测输出（Flags 部分）：

Flags:
  -h, --help              help for serve
      --http string       TCP address to listen for the HTTP server
                          (if domain args are specified - default to 0.0.0.0:80, otherwise - default to 127.0.0.1:8090)
      --https string      TCP address to listen for the HTTPS server
                          (if domain args are specified - default to 0.0.0.0:443, otherwise - default to empty string, aka. no TLS)
                          The incoming HTTP traffic also will be auto redirected to the HTTPS version
      --origins strings   CORS allowed domain origins list (default [*])

⚠️ 注意：serve 不带域名参数时默认只监听 127.0.0.1:8090（本机回环）；要让外网访问必须显式传 --http=0.0.0.0:8090 或传入域名参数（域名方式默认绑 0.0.0.0:80/443）。

3.3 查看应用设置（GET /api/settings）

应用设置需超级用户 token。先用超级用户集合 _superusers 的密码认证接口换取 token：

TOKEN=$(curl -s -X POST http://127.0.0.1:8090/api/collections/_superusers/auth-with-password \
  -H "Content-Type: application/json" \
  -d '{"identity":"admin@example.com","password":"q1w2e3r4"}' \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")
echo "$TOKEN" | head -c 40 && echo "...(token 已获取)"

实测输出：

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...(token 已获取)

鉴权说明：请求头 Authorization: <token> 或 Authorization: Bearer <token> 均可（两者实测均返回 200）；不带凭证访问设置接口返回 401——实测：

{"data":{},"message":"The request requires valid record authorization token.","status":401}

读取全部设置分组：

curl -s http://127.0.0.1:8090/api/settings -H "Authorization: $TOKEN" | python3 -m json.tool

实测输出（节选，保留分组骨架）：

{
    "superuserIPs": [],
    "smtp": {
        "enabled": false,
        "port": 587,
        "host": "smtp.example.com",
        ...
    },
    "backups": {
        "cron": "",
        "cronMaxKeep": 3,
        ...
    },
    "s3": { "enabled": false, ... },
    "meta": {
        "accentColor": "#1055c9",
        "appName": "Acme",
        "appURL": "http://localhost:8090",
        ...
    },
    "rateLimits": { "rules": [ ... ], "enabled": false },
    "trustedProxy": { "headers": [], "useLeftmostIP": false },
    "batch": { "enabled": false, "maxRequests": 50, "timeout": 3, "maxBodySize": 0 },
    "logs": { "maxDataSize": 0, "maxDays": 5, "minLevel": 0, "logIP": true, "logAuthId": false }
}

也可直接在管理台 http://127.0.0.1:8090/_/ → Settings 页分组查看，与 API 返回一一对应。

3.4 修改应用设置（PATCH /api/settings）

设置按分组整体提交：PATCH /api/settings，请求体只带要改的分组即可，返回修改后的完整设置。实测把应用名从默认 Acme 改为 PocketBase Demo：

curl -s -X PATCH http://127.0.0.1:8090/api/settings \
  -H "Authorization: $TOKEN" -H "Content-Type: application/json" \
  -d '{"meta":{"appName":"PocketBase Demo"}}' -o /dev/null -w "patch_http=%{http_code}\n"
curl -s http://127.0.0.1:8090/api/settings -H "Authorization: $TOKEN" \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['meta']['appName'])"

实测输出：

patch_http=200
PocketBase Demo

💡 说明：PATCH 是"按组覆盖"语义——提交 {"meta":{...}} 时该组内未带上的键会回落到默认值，改单个组时建议先 GET 取原组再改字段提交回去。

3.5 CLI 修改的设置项

superuser ips 子命令直接改超级用户 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

随后 GET /api/settings 立即返回 "superuserIPs": ["127.0.0.1", "10.0.0.0/24"]；不带参数执行 ./pocketbase superuser ips 可清空白名单（实测输出 Successfully cleared SuperuserIPs setting!）。

四、参数总览

4.1 全局命令行参数（所有子命令共享，来自实测 `--help`）

参数	类型/默认值	说明
`--dir`	string，默认 `pb_data`	数据目录（业务库、日志库、备份）
`--publicDir`	string，默认 `pb_public`	静态文件托管目录
`--hooksDir`	string，默认空（约定 `pb_hooks`）	JS hooks 目录
`--hooksWatch`	bool，默认 `true`	pb_hooks 文件变更自动重启（Windows 无效）
`--hooksPool`	int，默认 `15`	JS hooks 执行的 goja.Runtime 预热线程池大小
`--migrationsDir`	string，默认空（约定 `pb_migrations`）	自定义迁移文件目录
`--automigrate`	bool，默认 `true`	自动执行迁移
`--queryTimeout`	int，默认 `30`	默认 SELECT 查询超时（秒）
`--encryptionEnv`	string，默认空	存 32 字符加密密钥的环境变量名（加密应用设置）
`--indexFallback`	bool，默认 `true`	静态路径缺失时回落 index.html（SPA）
`--dev`	bool，默认 `false`	开发模式：控制台打印日志与 SQL
`-v, --version`	-	打印版本

4.2 `serve` 子命令参数

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

4.3 应用设置分组（GET /api/settings 返回的 9 组）

分组	关键键与默认值	作用
`meta`	appName `Acme`、appURL `http://localhost:8090`、senderName `Support`、senderAddress `support@example.com`、accentColor `#1055c9`、hideControls `false`	应用元信息与出站邮件发件人
`smtp`	enabled `false`、host `smtp.example.com`、port `587`、username 空、tls `false`、localName 空、authMethod 空	出站邮件通道
`s3`	enabled `false`、bucket/region/endpoint/accessKey 空、forcePathStyle `false`	文件存储切到 S3
`backups`	cron 空、cronMaxKeep `3`、内嵌 s3 同上	定时备份与备份外置存储
`logs`	maxDays `5`、minLevel `0`、logIP `true`、logAuthId `false`、maxDataSize `0`	请求日志策略
`rateLimits`	enabled `false`、rules 见 5.12、excludedIPs 空	接口限流
`batch`	enabled `false`、maxRequests `50`、timeout `3`、maxBodySize `0`	批量写接口
`trustedProxy`	headers `[]`、useLeftmostIP `false`	反代头信任与真实 IP 取值
`superuserIPs`	`[]`	超级用户 IP 白名单

表格解读：命令行参数管"进程怎么跑"（目录、监听、迁移），应用设置管"运行时行为"（邮件、存储、限流）——两者都需要覆盖才能完成一次完整的生产化配置。

五、核心参数分类详解

5.1 数据与目录参数（--dir / --publicDir）

--dir 改数据目录位置，--publicDir 改静态站点目录。实测在另一数据目录上启动（先复制数据目录）：

timeout 5 ./pocketbase --dir /opt/pb_data2 serve --http=127.0.0.1:8097 2>&1 | head -3

实测输出：

2026/10/21 09:34:22 Server started at http://127.0.0.1:8097
├─ REST API:  http://127.0.0.1:8097/api/
└─ Dashboard: http://127.0.0.1:8097/_/

pb_public 实测：创建 /opt/pocketbase/pb_public/index.html 后（服务重启一次使静态路由注册），GET / 直接返回该 HTML；访问不存在的路径 /missing-path 在默认 --indexFallback=true 下返回 200 与 index.html 内容（适配 SPA 前端路由）——实测：

GET /missing-path -> 200, type=text/html; charset=utf-8

5.2 服务监听参数（--http / --https / --origins）

--origins 控制 CORS：默认 [*] 放行所有来源；收窄后仅列表内来源会返回 CORS 头。实测以 --origins="https://app.example.com" 启动：

curl -s -o /dev/null -D - -H "Origin: https://app.example.com" http://127.0.0.1:8094/api/health | grep -i access-control
curl -s -o /dev/null -D - -H "Origin: https://evil.com" http://127.0.0.1:8094/api/health | grep -i access-control

实测输出（第二行无输出，即未返回 CORS 头）：

Access-Control-Allow-Origin: https://app.example.com

--https 需要同时给出证书可自动申请的域名参数（pocketbase serve example.com 形式），由内置 ACME 客户端自动签发；无域名时保持默认空值走纯 HTTP，由外部 Nginx/Caddy 统一终止 TLS 亦可。

5.3 JSVM hooks 参数（--hooksDir / --hooksWatch / --hooksPool）

在 WorkingDirectory 下创建 pb_hooks/main.pb.js，写入自定义路由：

routerAdd("GET", "/hello", (e) => {
  return e.json(200, { msg: "hello from pb_hooks" })
})

重启服务后实测：

curl -s http://127.0.0.1:8090/hello

实测输出：

{"msg":"hello from pb_hooks"}

无需显式传 --hooksDir——默认即约定目录 pb_hooks；默认 --hooksWatch=true 时改动钩子文件自动重启应用（开发期友好，生产可关闭）；--hooksPool=15 是 JS 运行时预热线程池，钩子逻辑重、并发高时可调大。

5.4 迁移参数（--automigrate / --migrationsDir）

默认 --automigrate=true：启动时自动执行核心与用户迁移。设为 false 后需手动 pocketbase migrate up。实测（对已全量应用的库执行）：

./pocketbase --dir pb_data migrate up

实测输出：

No new migrations to apply.

--migrationsDir 可把迁移文件挪出默认 pb_migrations；配合 pocketbase migrate collections 可把当前集合配置生成快照迁移文件（文件头带 /// <reference path="../pb_data/types.d.ts" />，内部为 migrate((app) => {...}) 结构），纳入版本管理。

5.5 超时与并发参数（--queryTimeout / batch 设置组）

--queryTimeout（默认 30 秒）约束 SELECT 类查询超时；batch 设置组控制批量写接口 /api/batch 的总开关与额度。实测先开启 batch 再批量创建 2 条记录：

curl -s -X PATCH http://127.0.0.1:8090/api/settings -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" -d '{"batch":{"enabled":true}}' -o /dev/null -w "patch_http=%{http_code}\n"
curl -s -X POST http://127.0.0.1:8090/api/batch -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"requests":[{"method":"POST","url":"/api/collections/posts/records","body":{"title":"第一篇"}},{"method":"POST","url":"/api/collections/posts/records","body":{"title":"第二篇"}}]}'

实测输出（节选）：

patch_http=200
[
    {
        "body": { "collectionId": "pbc_1125843985", "collectionName": "posts", "id": "g6t17yk57ag7ld3", "title": "第一篇", ... },
        "status": 200
    },
    {
        "body": { "collectionId": "pbc_1125843985", "collectionName": "posts", "id": "fx2a06ompd11kk5", "title": "第二篇", ... },
        "status": 200
    }
]

参数含义：maxRequests=50（单批次最多 50 个子请求）、timeout=3（批次整体超时秒）、maxBodySize=0（不限请求体大小）、enabled=false 默认关闭——未开启时调 /api/batch 直接 404，这是"接口不存在"排查时最容易被忽略的一点。

5.6 开发调试参数（--dev）

--dev 开启后控制台实时打印请求日志与 SQL 语句。实测启动输出（节选）：

[0.00ms] CREATE TABLE IF NOT EXISTS `_migrations` (file VARCHAR(255) PRIMARY KEY NOT NULL, applied INTEGER NOT NULL)
[0.00ms] SELECT (1) FROM `_migrations` WHERE `file`='1640988000_init.go' LIMIT 1
[0.00ms] SELECT `_collections`.* FROM `_collections` ORDER BY `rowid` ASC
[0.00ms] SELECT `_params`.* FROM `_params` WHERE `id`='settings'
2026/10/21 09:36:32 Server started at http://127.0.0.1:8095

⚠️ 注意：--dev 会把内部 SQL 全量打到控制台，仅排障时临时使用，生产长期开启影响性能且可能暴露敏感数据。

5.7 应用元信息设置（meta 组）

meta 组的 appName/appURL/senderName/senderAddress 会出现在系统邮件模板、OAuth2 回调提示与管理台标题里。默认值实测：appName: Acme、appURL: http://localhost:8090、senderName: Support、senderAddress: support@example.com、accentColor: #1055c9。生产建议把 appURL 改成真实对外地址（https://pb.example.com），否则发给用户的验证/重置邮件里的链接会指向 localhost。

5.8 SMTP 邮件设置（smtp 组）

默认 enabled=false，系统邮件（验证、密码重置等）退化为"打印到日志"模式。启用需填 host/port/username/password，tls=false 时用 STARTTLS（端口 587 常见），localName 为 EHLO 域名。改完可用管理台 Settings → Mail settings 的 "Send test email" 验证，无需真实发信对象即可测通道连通性。

5.9 文件存储 S3 设置（s3 组）

s3.enabled=true 后新上传的文件写入 S3 兼容对象存储（bucket/region/endpoint/accessKey/secret 必填，MinIO 等私有 S3 需把 forcePathStyle 设为 true）。已有本地文件不会被自动迁移，切换只对新上传生效。

5.10 备份设置（backups 组）与备份 API

backups 组默认：cron 空（不定时）、cronMaxKeep: 3（最多保留 3 份）。备份可直接走 API 创建与列出，实测：

curl -s -X POST http://127.0.0.1:8090/api/backups -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" -d '{"name":"demo_backup.zip"}' -w "http=%{http_code}\n"
curl -s http://127.0.0.1:8090/api/backups -H "Authorization: $TOKEN"
ls -lh /opt/pocketbase/pb_data/backups/

实测输出：

http=204
[
    {
        "modified": "2026-10-21 09:36:13.089Z",
        "key": "demo_backup.zip",
        "size": 226877
    }
]
total 228K
-rw-r--r-- 1 root root 222K Oct 21 09:36 demo_backup.zip
-rw-r--r-- 1 root root  236 Oct 21 09:36 demo_backup.zip.attrs

生产建议给 cron 配上表达式（如 0 2 * * *）并保留 cronMaxKeep 默认值，备份产物亦可外置到 S3（组内嵌 s3）。

5.11 日志设置（logs 组）与日志 API

默认：maxDays: 5（请求日志保留 5 天）、minLevel: 0、logIP: true（记录请求者 IP）、logAuthId: false、maxDataSize: 0。日志经 GET /api/logs 查询，实测最近一条请求日志：

{"id": "xkvd8wcnibegrrj", "created": "2026-10-21 09:53:46.999Z", "data": {"auth": "", "execTime": 41.147724, "method": "POST", "remoteIP": "127.0.0.1", "status": 200, "type": "request", "url": "/api/collections/_superusers/auth-with-password", "userAgent": "curl/7.81.0", "userIP": "127.0.0.1"}, "message": "POST /api/collections/_superusers/auth-with-password", "level": 0}

💡 说明：请求日志存于辅助库（auxiliary.db），与业务库 data.db 分离，调大 maxDays 主要增加辅助库体积，不影响业务库。

5.12 速率限制设置（rateLimits 组）

默认 enabled=false，内置 4 条预置规则（实测导出）：

{"label": "*:auth",    "duration": 3,  "maxRequests": 2}
{"label": "*:create",  "duration": 5,  "maxRequests": 20}
{"label": "/api/batch","duration": 1,  "maxRequests": 3}
{"label": "/api/",     "duration": 10, "maxRequests": 300}

label 支持接口路径前缀（/api/）与"集合:动作"标签（*:auth 指所有认证动作、*:create 指所有创建动作）；duration 为窗口秒数，excludedIPs 可豁免内网监控地址。实测开启并收紧为 /api/ 每 10 秒 3 次，连发 5 次：

req1=200 req2=200 req3=200 req4=429 req5=429

第 4 次起返回 429，规则即时生效；验证后还原默认规则并把 enabled 置回 false。

5.13 批处理设置（batch 组）

见 5.5 的实测；补充两点：maxBodySize=0 表示不限制批次请求体大小，有 WAF/反代的场景建议按业务收紧（如 10MB）；timeout=3 是批次整体处理时限，超时整批失败回滚。

5.14 信任代理设置（trustedProxy 组）

置于 Nginx/Caddy 反代之后时，headers 配置信任的取头规则（如 X-Forwarded-For），useLeftmostIP=false 取右侧第一个非受信 IP（防伪造）。默认 headers: []——不信任任何代理头，日志里的 userIP 将是反代地址而非真实客户端 IP，接反代后必须配置本组。

5.15 超级用户 IP 白名单（superuserIPs 组）

superuserIPs 非空时，仅列表内 IP/网段可登录超级用户与管理台。修改方式见 3.5 节 CLI 实测（superuser ips 设置/清空，运行中即时生效）。生产建议只放运维网段，例如 10.0.0.0/24。

5.16 应用设置加密（--encryptionEnv）

PocketBase 的应用设置（含 SMTP 密码、S3 密钥）默认明文存于数据库。开启加密：生成 32 字符密钥放进环境变量，启动时用 --encryptionEnv 指向该变量名：

openssl rand -hex 16   # 生成 32 字符密钥

实测完整验证流程（对复制出的数据目录）：带密钥启动并修改一次设置触发加密保存 → 停止后不带密钥再启动，实测报错：

2026/10/21 09:35:37 invalid settings db data or missing encryption key ""

⚠️ 注意：密钥丢失则已加密的设置无法解密，只能从备份恢复。生产环境把密钥放 /etc/pocketbase.env（chmod 600），systemd 单元用 EnvironmentFile= 引入，并纳入服务器凭据管理。

六、生产配置模板

适用场景：2C4G 内存、40GB+ SSD 云主机、日活 1 万以内的中小型 Web/移动应用后端（单机 PocketBase 实测空载内存仅 7.5MB，余量充足）。

systemd 单元（/etc/systemd/system/pocketbase.service）：

[Unit]
Description=PocketBase service
After=network.target

[Service]
Type=simple
User=root
LimitNOFILE=4096
Restart=always
RestartSec=5
WorkingDirectory=/opt/pocketbase
EnvironmentFile=/etc/pocketbase.env
ExecStart=/opt/pocketbase/pocketbase serve --http=0.0.0.0:8090 --queryTimeout=30

[Install]
WantedBy=multi-user.target

/etc/pocketbase.env（权限 600，密钥由 openssl rand -hex 16 生成）：

PB_ENC_KEY=<32字符密钥>

应用设置推荐值（PATCH /api/settings 逐组提交）：

{
  "meta": { "appName": "MyApp", "appURL": "https://pb.example.com", "senderName": "MyApp", "senderAddress": "no-reply@example.com" },
  "smtp": { "enabled": true, "host": "smtp.example.com", "port": 587 },
  "backups": { "cron": "0 2 * * *", "cronMaxKeep": 7 },
  "logs": { "maxDays": 7, "logIP": true },
  "rateLimits": { "enabled": true, "rules": [ { "label": "*:auth", "duration": 3, "maxRequests": 2 }, { "label": "/api/", "duration": 10, "maxRequests": 300 } ] },
  "batch": { "enabled": true, "maxRequests": 50, "timeout": 3 },
  "trustedProxy": { "headers": ["X-Forwarded-For"], "useLeftmostIP": false },
  "superuserIPs": ["10.0.0.0/24"]
}

逐项说明：appURL 必须是真实对外地址（邮件链接依赖它）；smtp.enabled 开启后系统邮件真正外发；backups.cron 每日 2 点备份并保留 7 份；限流开启默认规则即可拦截认证爆破（*:auth 3 秒 2 次）；trustedProxy.headers 按实际反代头填写；superuserIPs 收紧到运维网段。修改后用 GET /api/settings 复核：

curl -s http://127.0.0.1:8090/api/settings -H "Authorization: $TOKEN" | python3 -m json.tool | head -20

💡 说明：CLI/serve 参数改动（如换端口）需 systemctl daemon-reload && systemctl restart pocketbase；应用设置改动保存即生效，无需重启。

七、常见问题（FAQ）

Q1：改了配置没生效？

先分清改的是哪类：命令行参数（systemd ExecStart）必须 systemctl daemon-reload && systemctl restart pocketbase；应用设置（PATCH /api/settings）保存即生效。CLI 的 superuser ips 亦即时生效（3.5 节实测）。

Q2：开启 --encryptionEnv 后密钥忘了？

设置已加密，缺钥/错钥启动报 invalid settings db data or missing encryption key ""（5.16 节实测），无法明文读取；只能从 pb_data/backups/ 的备份恢复到未加密状态或换新密钥重配。务必把密钥托管在配置文件（600 权限）与凭据系统双份。

Q3：/api/batch 返回 404？

batch.enabled 默认 false，接口未开。PATCH 设置开启后再试（5.5 节实测完整流程）。

Q4：开了限流后健康检查也 429 了？

/api/ 前缀规则覆盖所有 API 包括 health。把监控拨测 IP 加入 rateLimits.excludedIPs，或为 health 类路径调高阈值。

Q5：如何确认设置真的写进去了？

一切以 GET /api/settings 返回为准（管理台 UI 与其同源）；涉及行为类的（限流、batch）按 5.5/5.12 节的实测方法用真实请求验证。

Q6：外网访问不了、日志里 IP 是反代地址？

前者检查 --http 是否绑 0.0.0.0 与防火墙；后者配置 trustedProxy 组（5.14 节）。

八、参考链接

官方文档 Settings API：https://pocketbase.io/docs/api-settings
官方文档 Going to production：https://pocketbase.io/docs/going-to-production
GitHub 仓库：https://github.com/pocketbase/pocketbase
站内延伸：《PocketBase 介绍与选型指南》、《Ubuntu 22.04 安装 PocketBase 0.40.5 指南》
本专栏系列：《PocketBase 0.40.5 常用 CLI 命令与工具详解》。

PocketBase 0.40.5 配置参数详解

PocketBase 0.40.5 配置参数详解

一、环境信息

二、前置条件

三、参数查看与修改方式

3.1 两类配置体系

3.2 查看命令行参数

3.3 查看应用设置（GET /api/settings）

3.4 修改应用设置（PATCH /api/settings）

3.5 CLI 修改的设置项

四、参数总览

4.1 全局命令行参数（所有子命令共享，来自实测 --help）

4.2 serve 子命令参数

4.3 应用设置分组（GET /api/settings 返回的 9 组）

五、核心参数分类详解

5.1 数据与目录参数（--dir / --publicDir）

5.2 服务监听参数（--http / --https / --origins）

5.3 JSVM hooks 参数（--hooksDir / --hooksWatch / --hooksPool）

5.4 迁移参数（--automigrate / --migrationsDir）

5.5 超时与并发参数（--queryTimeout / batch 设置组）

5.6 开发调试参数（--dev）

5.7 应用元信息设置（meta 组）

5.8 SMTP 邮件设置（smtp 组）

5.9 文件存储 S3 设置（s3 组）

5.10 备份设置（backups 组）与备份 API

5.11 日志设置（logs 组）与日志 API

5.12 速率限制设置（rateLimits 组）

5.13 批处理设置（batch 组）

5.14 信任代理设置（trustedProxy 组）

5.15 超级用户 IP 白名单（superuserIPs 组）

5.16 应用设置加密（--encryptionEnv）

六、生产配置模板

七、常见问题（FAQ）

八、参考链接

4.1 全局命令行参数（所有子命令共享，来自实测 `--help`）

4.2 `serve` 子命令参数