一个带用户登录、图片上传、后台管理和几十张数据表的副业项目,如果按标准流程搭,部署清单大概是:PostgreSQL 一个、Redis 一个、认证服务一个、对象存储一个、管理后台一套,外加反向代理和进程守护。业务代码还没写,运维负担已经先到位了。对一个人维护的项目来说,这套组合的真正成本不是服务器账单,而是每次改表、加字段、调权限都要在几个系统之间来回切换。PocketBase 想解决的正是这一层摩擦:把数据库、认证、文件存储、实时 API 和可视化后台塞进一个可执行文件里,让你少维护几个进程。
PocketBase 是什么:一个可执行文件里的后端
PocketBase 是一个用 Go 写的开源后端,编译后是单个二进制文件。启动后它同时提供 REST API、实时订阅、用户认证、文件上传下载和管理后台,数据存在内嵌的 SQLite 里。官方部署文档的说法很直接:把可执行文件放到服务器上就能跑,不需要外部依赖。
它运行时会在可执行文件旁边生成两个目录:
pb_data:SQLite 数据库和上传的文件都在这里。官方建议把它加入.gitignore,因为它属于运行时数据。pb_migrations:集合(相当于表)结构变更的记录文件,可以提交到版本库,用于在不同环境之间同步 schema。
这两个目录分开,带来的直接好处是备份和迁移的边界很清楚:数据跟着 pb_data 走,结构跟着 pb_migrations 走。

用一个最小数据模型跑通全流程
与其抽象地讨论功能,不如用一个具体的例子走一遍。假设你要做一个投稿类的小应用,核心数据是一张 posts 集合和一个内置的 users 认证集合,要求:登录用户可以创建投稿,所有人可以浏览已发布的投稿,作者只能改自己的内容。
第一步:启动与创建集合
从 GitHub Releases 下载对应平台的压缩包,解压后进入目录执行 ./pocketbase serve(Windows 是 pocketbase.exe serve)。默认监听 127.0.0.1:8090,浏览器打开后会引导你创建第一个管理员账号。这个账号只用于进管理后台,和业务用户是两套体系。
进入后台后新建集合 posts,先加几个字段:
| 字段名 | 类型 | 说明 |
|---|---|---|
| title | text | 标题 |
| body | editor | 正文 |
| published | bool | 是否发布 |
| cover | file | 封面图,单文件 |
| author | relation | 关联到 users 集合 |
author 用 relation 类型指向内置的 users,这样后面写访问规则时可以直接引用关系字段。
第二步:配置访问规则
集合的 API Rules 是 PocketBase 里最值得花时间理解的部分。每条规则是一个过滤表达式,为空表示允许,非空则要求请求满足条件。对 posts 来说,一组最小可用的规则是:
List/View: published = true || @request.auth.id != "" && author = @request.auth.id
Create: @request.auth.id != ""
Update: author = @request.auth.id
Delete: author = @request.auth.id
第一行允许所有人看已发布的文章,同时允许登录用户看到自己未发布的草稿。后面三条把写操作绑定到当前登录用户,并校验 author 字段确实是本人。这种表达式写起来接近 SQL 的 where 子句,但不需要你单独维护一套权限中间件。
第三步:前端调用
PocketBase 官方提供了 JavaScript SDK,前端不需要自己封装登录态和请求头:
import PocketBase from 'pocketbase'
const pb = new PocketBase('https://your-domain.com')
// 登录
await pb.collection('users').authWithPassword('me@example.com', 'password')
// 创建投稿,author 自动带上当前用户
await pb.collection('posts').create({
title: '第一篇',
body: '...',
author: pb.authStore.model.id,
})
// 公开列表
const list = await pb.collection('posts').getList(1, 20, {
filter: 'published = true',
sort: '-created',
})
如果不想引 SDK,直接发 HTTP 请求也能用,认证走标准的 token 方式。实时订阅则通过 SDK 的 subscribe 方法或 SSE 端点接收变更通知。
整个流程里没有建表 SQL、没有 ORM 配置、没有单独的认证服务,对熟悉前端的人来说学习曲线主要集中在访问规则表达式上。
适合谁:单文件后端的甜蜜区
PocketBase 的定位不是替代 PostgreSQL 加一整套微服务,而是覆盖“一个人或小团队维护的中小规模应用”。综合官方文档和社区实践,比较稳妥的适用范围是:
适合的场景
- 独立开发者的 MVP、副业项目和内部工具。成本可控,部署只需要传一个文件加一个数据目录。
- 读多写少、并发不高的应用。典型如内容站、作品集、轻量社区、表单收集、管理面板背后的 API。
- 对数据自主权有要求、又不想自己拼装全套组件的项目。SQLite 文件在自己手里,备份就是复制目录。
- 需要快速验证数据模型的产品早期阶段。管理后台可以直接改集合结构,前端联调几乎零等待。
需要绕开的场景
- 写入密集的系统,比如日志采集、高频事件上报、分析平台。SQLite 使用 WAL 模式,同一时刻只允许一个写入者,写压力一上来就会成为瓶颈。
- 要求高可用和自动故障转移的业务。单进程架构意味着单点,官方也没有内置多节点复制。
- 需要水平扩展扛流量的场景。PocketBase 不是一个为水平扩展设计的系统,流量增长到单机上限后,横向加机器并不能直接解决问题。
- 需要商业 SLA 和厂商支持合同的企业应用。项目作者本人也在文档中提醒,PocketBase 仍在活跃开发中,不建议用于对稳定性要求极高的关键生产系统。这一点在选型时应该被认真对待,而不是被“单文件很方便”冲淡。
一个常见的误判是把“适合小项目”理解成“只适合玩具”。实际上不少内部工具和中小型线上应用跑在 PocketBase 上,关键区别在于写入模式和可用性要求,而不在项目是否“正式”。
扩展边界:什么时候写代码,什么时候换方案
PocketBase 不是一个封闭的黑盒。它提供两种扩展方式:Go 框架模式和 JavaScript 钩子。
Go 方式适合需要深度控制或性能敏感的逻辑。你可以把 PocketBase 当作库引入,注册自定义路由、在记录创建前后插入业务逻辑、操作文件系统。官方文档里的记录操作示例展示了 FindCollectionByNameOrId、NewRecord、Set、Save 这类调用,写法接近常规的 Go 后端开发。
JavaScript 方式适合不想引入 Go 工具链的团队。在 pb_hooks 目录放 .pb.js 文件,就能挂载钩子。比如在用户注册成功后发一封欢迎邮件,大致是:
onRecordAfterCreateSuccess((e) => {
const message = new MailerMessage({
from: { address: e.app.settings().meta.senderAddress },
to: [{ address: e.record.email() }],
subject: '欢迎',
html: '<p>感谢注册</p>',
})
e.app.newMailClient().send(message)
e.next()
}, 'users')
这套机制能覆盖大多数“加一点自定义逻辑”的需求:邮件通知、第三方 webhook、字段清洗、轻量计算。但它的边界也很清楚:
- 钩子运行在同一个进程里,复杂耗时的任务会挤占 API 的响应能力。重活应该外置到队列或独立服务。
- 它不是通用应用框架,缺少大型项目常见的分层、依赖注入和模块化约定。逻辑一多,代码组织要靠自己。
- 自定义路由和钩子的能力受版本影响,升级时需要留意变更说明。项目仍在 0.x 阶段,API 并非完全冻结。
判断标准可以简化成一句话:如果需求是“在现有数据流上加动作”,用钩子;如果需求开始变成“需要独立的计算层、消息队列或多服务协作”,那就不是 PocketBase 该继续扛的范围了。
备份、升级与部署的几件实事
单文件架构让运维变简单,但不等于可以不做运维。
备份:核心就是备份 pb_data 目录。SQLite 文件和上传文件都在里面,复制目录即可完成全量备份。生产环境建议用定时任务做快照,并在恢复流程上实际演练一次,而不是只确认备份文件存在。如果文件量很大,可以在后台设置里把文件存储切到 S3 兼容服务(如 Cloudflare R2、Backblaze B2),让 pb_data 只保留数据库和元数据。
升级:替换可执行文件并重启是常规操作,但升级前应查看 release notes,尤其是涉及集合结构、钩子 API 和认证行为的变更。pb_migrations 目录里保存了 schema 变更历史,跨版本迁移时它是重要的参考。升级前先备份 pb_data,这是最低要求。
部署:官方的最小生产方案就是把可执行文件放上服务器。实际使用时通常还会加一层反向代理处理 TLS 和域名,用进程管理工具保证重启后自动拉起,并把 pb_data 放在持久化磁盘上。如果使用容器,注意把数据目录挂载为卷,否则容器重建会丢数据。
排错:常见问题集中在三处。访问规则写错导致 403 或列表为空,可以在后台用 API Preview 逐条验证表达式;文件上传失败优先检查存储配置和反向代理的请求体大小限制;实时连接断开则要确认代理是否支持长连接和 SSE。
选型结论
回到开头那个问题:一个人维护的小项目,要不要上完整后端框架?PocketBase 给出的答案是把“完整”收进一个文件里,用约定换掉大量重复搭建。它在读多写少、规模可控、以快速交付为目标的场景里,能显著压低从零到上线的成本;在写入密集、高可用、需要水平扩展或商业支持的系统里,它不该被硬撑上去。
更实用的判断方式是看三个维度:写入压力是否在单机 SQLite 能承受的范围内,可用性要求是否允许单点,业务逻辑是否还停留在“加钩子”而不是“拆服务”。三个都过得去,PocketBase 值得作为首选试一试;任何一个过不去,就应该把它当成原型工具,而不是最终架构。至于它是否适合你的下一个项目,最省事的验证方法仍然是下载那个可执行文件,用一个真实的最小数据模型跑一遍,感受一下从建集合到前端调通的节奏,再决定要不要把生产数据交进去。

评论列表 (1条):
加载更多评论 Loading...