pocketbase

PocketBase 技能

通过捆绑的 Python 脚本和参考资料，操作 PocketBase 后端项目（独立二进制文件或 Go 包模式）。

技能资源

优先使用此技能目录中的资源：

• scripts/ - 用于身份验证、集合、记录、备份和迁移模板生成的可执行辅助工具
• references/ - 可按需加载的详细后端文档
• assets/ - 迁移模板

优先查看 --help 输出和本指南。如果行为不明确，只阅读相关脚本文件。

0. 快速开始

模式检测

1. 如果 go.mod 包含 github.com/pocketbase/pocketbase -> Go 包模式
2. 否则 -> 独立模式

引导（PocketBase 未运行时）

1. 动态解析最新版本：

VERSION=$(curl -s https://api.github.com/repos/pocketbase/pocketbase/releases/latest | python3 -c "import sys,json; print(json.load(sys.stdin)['tag_name'].lstrip('v'))")
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
OS=$(uname -s | tr A-Z a-z)
curl -sL "https://github.com/pocketbase/pocketbase/releases/download/v${VERSION}/pocketbase_${VERSION}_${OS}_${ARCH}.zip" -o pb.zip
unzip -o pb.zip pocketbase && rm pb.zip

2. 创建超级用户：

./pocketbase superuser create [email protected] <password>

3. 配置 .env（并确保 .env 位于 .gitignore 中）：

PB_URL=http://127.0.0.1:8090
[email protected]
PB_SUPERUSER_PASSWORD=your-password

4. 启动服务：

nohup ./pocketbase serve --http=127.0.0.1:8090 > pb.log 2>&1 &

5. 健康检查：

python scripts/pb_health.py

截至 2026-02-27，最新稳定版本为 v0.36.5。

1. 设计与安全检查清单

你的模型先验可能包含 v0.23 之前的模式。在进行任何架构或钩子更改之前，请先验证以下内容。

v0.23+ 关键规则

• 使用 _superusers（而非 _admins）
• 使用集合 fields（而非 schema）
• 使用扁平字段属性（不使用 options 包装）
• 在迁移中使用类型化字段构造函数（TextField、SelectField、RelationField 等）
• 路由使用 {param} 路径语法（而非 :param）
• JSVM 钩子必须调用 e.next()；Go 钩子必须 return e.Next()
• @collection.* 筛选条件在可能匹配多行时应使用 ?=

API 规则默认值

• null -> 仅限超级用户
• "" -> 公开（包括未通过身份验证的用户）

默认使用 null，仅开放必要权限。

Go 模式检查

• 使用 API/Admin UI 修改集合；让 PocketBase 自动生成迁移
• 提交 pb_migrations/ 中生成的文件
• 在开发环境中配置 migratecmd.MustRegister(..., migratecmd.Config{Automigrate: true})
• 使用手动迁移时，确保存在空白导入：_ "yourmodule/migrations"
• 在手动 Go 迁移中分配规则时，使用 types.Pointer("...")

2. 核心操作

2.1 身份验证

超级用户身份验证：

python scripts/pb_auth.py

用户身份验证：

python scripts/pb_auth.py --collection users --identity [email protected] --password secret

2.2 集合

列出 / 获取：

python scripts/pb_collections.py list
python scripts/pb_collections.py get posts

创建 / 更新 / 删除：

python scripts/pb_collections.py create --file schema.json
python scripts/pb_collections.py update posts --file updates.json
python scripts/pb_collections.py delete posts

批量导入（建议用于多集合设置）：

python scripts/pb_collections.py import --file collections.json

重要：

• 不要创建新的 users 集合；请更新现有集合
• 当负载包含 API 规则时，使用 --file，避免 shell 引号问题
• 更新 fields 时，发送完整字段集（而非部分合并）

2.3 记录

python scripts/pb_records.py list posts --filter 'status="published"' --sort "-created" --expand "author"
python scripts/pb_records.py get posts <recordId>
python scripts/pb_records.py create posts --file record.json
python scripts/pb_records.py update posts <recordId> '{"status":"published"}'
python scripts/pb_records.py delete posts <recordId>

2.4 备份

python scripts/pb_backups.py list
python scripts/pb_backups.py create
python scripts/pb_backups.py restore <backupKey>
python scripts/pb_backups.py delete <backupKey>

恢复会替换所有数据；恢复前务必创建备份。

2.5 迁移

主要工作流（两种模式均适用）：

1. 启动 PocketBase
2. 通过 API/Admin UI 更改集合
3. 在 pb_migrations/ 中提交自动生成的迁移

手动生成迁移模板（仅用于种子数据 / 数据转换 / 原始 SQL）：

python scripts/pb_create_migration.py "backfill_user_slugs"
python scripts/pb_create_migration.py "seed_categories" --dir ./pb_migrations

3. 验证

架构或规则更改后，运行：

1. python scripts/pb_collections.py get <collection>
2. CRUD 冒烟测试（创建 / 列表 / 获取 / 更新 / 删除）
3. 使用非超级用户令牌测试规则

规则拒绝行为参考：

• listRule 被拒绝 -> 返回 200，且 items 为空
• viewRule 被拒绝 -> 返回 404
• createRule 被拒绝 -> 返回 400
• updateRule 被拒绝 -> 返回 404
• deleteRule 被拒绝 -> 返回 404
• 普通用户的规则为 null -> 返回 403

存在非 null API 规则或自定义钩子 / 路由时，必须进行 E2E 测试。使用 references/e2e-testing.md 和 scripts/pb_e2e_helpers.py。

最低 E2E 覆盖范围：

• 未通过身份验证的访问被拒绝
• 已通过身份验证的允许路径成功
• 跨用户访问被阻止
• 创建负载中的所有者身份伪造被阻止
• 验证 cascadeDelete 行为
• 验证自定义路由的身份验证强制执行
• 验证钩子的副作用

4. 参考索引

只阅读所需内容：

• 常见陷阱：references/gotchas.md
• API 规则：references/api-rules-guide.md
• 集合 API：references/collections-api.md
• 记录 API：references/records-api.md
• 身份验证 API：references/auth-api.md
• 迁移（JS）：references/migrations.md
• 字段类型：references/field-types.md
• 关联模式：references/relation-patterns.md
• 文件处理：references/file-handling.md
• JSVM 钩子：references/jsvm-hooks.md
• Go 设置：references/go-framework.md
• Go 迁移：references/go-migrations.md
• Go 钩子/路由：references/go-hooks-routes.md
• 端到端测试：references/e2e-testing.md

前端集成工作属于 pb-react-spa 技能。