pocketbase-best-practices

PocketBase 最佳实践

PocketBase 是一个单二进制文件后端（SQLite + REST + 实时功能 + 身份验证），易于上手，但在大规模使用时也容易误用。本技能为 AI Agent 提供防护指南：9 个类别共 64 条规则，每条规则都包含错误与正确的代码示例，涵盖 Agent 实际会犯的错误——不安全的 API 规则、未建立索引的查询、失效的身份验证流程、N+1 次扩展查询，以及泄露的服务端句柄。

针对 PocketBase v0.40 和 JS SDK v0.28 更新（2026 年 8 月）。 适用于 v0.36 及更高版本。

规则优先级

每条规则都有一个影响级别：Critical = 安全漏洞或数据模型失效，High = 性能与正确性问题，Medium/Low = 运维方面的完善事项。规则发生冲突时，以影响级别较高的规则为准。

涵盖内容

类别	影响级别	帮助避免的问题
集合设计	Critical	字段类型错误、缺少索引、使用手动 ID 字符串而非关联
API 规则与安全	Critical	因访问规则为空或不正确导致的数据泄露、筛选器注入
身份验证	Critical	密码/OAuth2/OTP/MFA 流程失效、令牌处理不当
SDK 使用	High	客户端设置不当、错误被吞掉、请求取消问题
查询性能	High	N+1 次查询、获取过多数据、缺少分页
实时功能	Medium	订阅丢失、未通过身份验证的实时访问
文件处理	Medium	未验证的上传、文件 URL 错误、缺少缩略图
生产与部署	Medium	没有备份、没有速率限制、超级用户访问暴露
服务端扩展	High	Go/JSVM 钩子使用错误、事务误用、不安全的筛选器绑定

快速参考

集合设计（CRITICAL）

• coll-field-types：使用适当的字段类型（对象使用 json，枚举使用 select）
• coll-auth-vs-base：用户使用 auth 集合，非身份验证数据使用 base 集合
• coll-relations：使用关联字段，而非手动维护 ID 字符串
• coll-indexes：为频繁筛选或排序的字段创建索引
• coll-view-collections：复杂聚合使用视图
• coll-geopoint：使用带 lat/lng 的 json 字段存储坐标

API 规则（CRITICAL）

• rules-basics：始终设置 API 规则；留空 = 公开访问
• rules-filter-syntax：在规则中使用 @request.auth、@collection、@now
• rules-request-context：通过 @request.body、@request.query 访问请求数据；@request.context 的值：default/oauth2/otp/password/realtime/protectedFile
• rules-cross-collection：使用 @collection.name.field 执行跨集合检查
• rules-locked-vs-open：从锁定访问开始，再有选择地开放
• rules-strftime：日期运算使用 strftime('%Y-%m-%d', created)（v0.36+）

身份验证（CRITICAL）

• auth-password：使用 authWithPassword 进行邮箱/密码登录
• auth-oauth2：通过 Admin UI 配置 OAuth2 提供方；使用 ≥v0.38.2（已修复预先关联劫持问题）；提供方徽标由 listAuthMethods() 内联返回（v0.37+）
• auth-otp：分两步执行 requestOTP → authWithOTP；对 requestOTP 进行速率限制，绝不泄露邮箱是否存在
• auth-token-management：安全存储令牌，并在过期前刷新
• auth-mfa：为敏感应用启用 MFA
• auth-impersonation：代表用户执行管理操作时使用模拟身份

SDK 使用（HIGH）

• sdk-initialization：只初始化一次客户端，并重复使用该实例
• sdk-auth-store：React Native/SSR 使用 AsyncAuthStore
• sdk-error-handling：捕获 ClientResponseError，并检查状态码
• sdk-auto-cancellation：并发请求时禁用自动取消
• sdk-filter-binding：使用筛选器绑定以防止注入

查询性能（HIGH）

• query-expand：扩展关联以避免 N+1 次查询
• query-field-selection：只选择需要的字段
• query-pagination：大型数据集使用游标分页
• query-batch-operations：尽可能批量创建/更新

实时（中）

• realtime-subscribe：订阅特定记录或集合
• realtime-events：分别处理创建、更新和删除事件
• realtime-auth：实时功能会自动遵循 API 规则；密码更改时会取消身份验证；连接绝对时长上限约为 30 分钟（v0.38+）
• realtime-reconnection：实现重连逻辑——定期重连是设计如此，请重新同步状态，而不是试图阻止重连

文件处理（中）

• file-upload：使用 FormData 上传，并设置正确的内容类型
• file-serving：使用 pb.files.getURL() 获取文件 URL
• file-validation：在服务端验证文件类型和大小

部署（中）

• deploy-backup：定期备份 pb_data
• deploy-configuration：使用环境变量进行配置；注意 v0.40 的日志上限（Log.Data 约为 16 KB），并将 SQL 控制台（v0.39+）仅用于调试
• deploy-reverse-proxy：在生产环境中使用 nginx/caddy 作为反向代理
• deploy-sqlite-considerations：针对生产工作负载优化 SQLite
• deploy-rate-limiting：启用内置速率限制器（从 v0.36.7 起使用固定窗口）；前置 Nginx/Caddy，增强纵深防御
• deploy-scaling：提高 ulimit -n 以支持实时功能，设置 GOMEMLIMIT，启用设置加密
• deploy-superuser-ips：在生产环境中按 IP/CIDR 将超级用户访问列入白名单（v0.38+）；可通过 superuser ips 控制台命令恢复

服务端扩展（高）

• ext-go-setup：使用 app.OnServe() 注册路由；在钩子中使用 e.App，而非父作用域中的 app；v0.40 需要 Go 1.27（使用 encoding/json/v2——发布前请先测试）
• ext-js-setup：将 *.pb.js 放入 pb_hooks/；添加 /// <reference path="../pb_data/types.d.ts" />
• ext-hooks-chain：始终调用 e.Next()/e.next()；使用带 Id 的 Bind，以便稍后调用 Unbind
• ext-hooks-record-vs-request：使用 OnRecordEnrich 调整响应（包括实时响应）；HTTP 专用逻辑使用 OnRecordRequest
• ext-routing-custom：将路由置于 /api/{yourapp}/ 下；附加 RequireAuth() 中间件
• ext-transactions：在 RunInTransaction 中使用作用域内的 txApp；切勿捕获外部的 app
• ext-filter-binding-server：在 FindFirstRecordByFilter / FindRecordsByFilter 中使用 {:name} + dbx.Params 绑定用户输入
• ext-filesystem：对每个 NewFilesystem() / NewBackupsFilesystem() 句柄调用 defer fs.Close()
• ext-cron-jobs：使用 app.Cron().MustAdd(id, expr, fn) / cronAdd() 注册；使用稳定的 id，不要使用 __pb*__ 前缀
• ext-go-migrations：在 migrations/ 下放置带版本号的 .go 文件；设置 Automigrate: osutils.IsProbablyGoRun()
• ext-js-migrations：使用 pb_migrations/<unix>_*.js，并调用 migrate(upFn, downFn)；系统会根据文件名自动发现迁移
• ext-mailer：在发送时从 app.Settings().Meta 获取发件人；切勿发布 [email protected]；每次发送时创建邮件客户端
• ext-settings：在调用时通过 app.Settings() 读取设置；设置 PB_ENCRYPTION（32 个字符）以加密静态存储的 _params
• ext-testing：使用 tests.NewTestApp(testDataDir) + tests.ApiScenario；调用 defer app.Cleanup()，并断言 ExpectedEvents
• ext-compose-request-flow：通过组合式演练，展示各层（路由 → 事务 → 钩子 → enrich）中当前生效的 app 实例
• ext-go-custom-sqlite：仅在需要 FTS5/ICU 时使用 DBConnect；DBConnect 会被调用两次（data.db + auxiliary.db）
• ext-jsvm-scope：处理程序外的变量在运行时未定义——在处理程序内通过 require() 加载共享配置
• ext-jsvm-modules：在 goja 中仅支持 CJS（require()）；先打包 ESM；避免使用可变模块状态

示例提示词

使用这些提示词与 AI Agent 交互，体验这项技能：

构建新功能：

• “为包含商品、订单和评价的电商应用设计 PocketBase 模式”
• “为我的应用实现 Google 和 GitHub OAuth2 登录”
• “使用 PocketBase 订阅构建实时通知系统”
• “创建一个支持图片验证和缩略图预览的文件上传表单”

修复问题：

• “我的列表查询在 10 万条记录上很慢——请优化”
• “我的批量操作遇到了 403 错误”
• “修复我的帖子列表中的 N+1 查询问题：该列表在循环中加载作者数据”
• “我的实时订阅在几分钟后就停止工作”

安全审查：

• “审查我的 API 规则——用户只能访问自己的数据”
• “设置正确的访问控制：管理员管理所有内容，用户只能编辑自己的内容”
• “我的身份验证 Cookie 是否为 SSR 安全配置？”
• “审计我的集合规则，检查是否存在 IDOR 漏洞”

准备上线：

• “为 PocketBase 配置 Nginx，包括 HTTPS、速率限制和安全标头”
• “为我的 PocketBase 数据库设置自动备份”
• “针对约 500 个并发用户的生产负载优化 SQLite 设置”
• “使用 Docker Compose 和 Caddy 部署 PocketBase”

扩展 PocketBase：

• “添加一个自定义 Go 路由，在创建记录后发送 Slack 通知”
• “编写一个 pb_hooks 脚本，在用户注册前验证电子邮件域名”
• “在我的 Go 应用中使用自定义 SQLite 驱动设置 FTS5 全文搜索”
• “在多个 pb_hooks 文件之间共享配置对象，且不产生竞态条件”

详细规则

加载相关类别，查看包含代码示例的完整规则文档：

• 集合设计 - 模式设计模式、字段类型、关系、索引
• API 规则与安全 - 访问控制、筛选表达式、安全模式
• 身份验证 - 密码身份验证、OAuth2、MFA、令牌管理
• SDK 用法 - 客户端初始化、身份验证存储、错误处理、钩子
• 查询性能 - 分页、扩展、批量操作、避免 N+1 问题
• 实时功能 - SSE 订阅、事件处理、重新连接
• 文件处理 - 上传、提供文件、验证
• 生产与部署 - 备份、配置、反向代理、SQLite 优化
• 服务端扩展 - Go/JSVM 设置、事件钩子、自定义路由、模块、自定义 SQLite