基于PocketBasev0.22.2。

什么是 PocketBase

PocketBase 被设计为一个开源的 Go 语言后端，其核心理念是提供一个高度集成的“一体化”解决方案。它将传统后端开发中常见的多个独立组件整合到一个单一的可执行文件中，极大地简化了部署和管理。

其核心概念体现在以下几个方面：

  • 嵌入式数据库 (Embedded Database)：PocketBase 内置了 SQLite 数据库，这意味着它不需要独立的数据库服务器，所有数据都存储在一个本地文件中。这种设计带来了卓越的轻量级和便携性。
  • 实时订阅 (Realtime Subscriptions)：它支持实时数据更新，能够轻松实现聊天应用、通知系统等需要即时数据同步的功能。
  • 内置认证与文件管理 (Built-in Authentication & File Management)：PocketBase 提供开箱即用的用户身份验证系统和文件存储功能，省去了集成第三方服务的复杂性。
  • 便捷的管理后台 (Convenient Admin Dashboard UI)：它包含一个用户友好的 Web 管理界面，开发者可以通过它直观地管理数据、配置集合和设置权限。
  • 简洁的 REST-ish API (Simple REST-ish API)：PocketBase 自动为所有数据集合生成基于 REST 风格的 API 接口，方便前端和移动客户端进行数据交互。

这种将数据库、认证、文件存储和 API 等功能打包到一个可执行文件中的设计，显著降低了对外部依赖的需求。这种集成度极高的特性，使得 PocketBase 成为快速原型开发、小型到中型项目或需要快速部署和低运维成本的应用程序的理想选择。它有效减少了传统后端开发中常见的配置和集成开销，让开发者能够更专注于业务逻辑的实现。

此外，PocketBase 既可以作为一个独立的应用程序运行，通过其内置的 Web 服务器提供服务，也可以作为 Go 框架嵌入到更大的 Go 项目中，允许开发者进行更深度的定制和扩展。

为何选择 PocketBase

选择 PocketBase 的主要原因在于其“极简”与“全能”的完美结合。它提供了一个无需复杂设置即可快速启动的后端解决方案。

其最显著的优势之一是其完全便携性。PocketBase 不需要任何外部依赖，只需将预编译的可执行文件（Linux AMD64 版可执行文件体积仅 48MB）上传到服务器即可部署。这种特性极大地降低了部署的门槛和运维的复杂性。减少外部依赖意味着更少的配置错误、更快的启动时间以及更简单的故障排除。对于资源有限的开发者、需要快速迭代的项目或希望避免复杂基础设施管理的团队来说，这种便携性是一个巨大的优势，它将开发者的精力从繁琐的运维工作转移到核心业务逻辑的开发上。

PocketBase 基准测试

测试结果：https://github.com/pocketbase/benchmarks

什么时候不应选择 PocketBase

  • 需要大规模横向扩展和高可用性的应用：如果你的应用预计会有海量用户、需要跨多台服务器进行数据分片或高可用集群部署，PocketBase 的单服务器架构将成为瓶颈。
  • 对数据库规模有极高要求或需要复杂分布式事务的应用：尽管 SQLite 性能良好，但对于数据量非常庞大（数 GB 甚至 TB 级别）且需要复杂分布式事务支持的场景，传统的分布式关系型数据库或 NoSQL 数据库会是更好的选择。
  • 对版本稳定性有严格要求的生产关键型应用：如果你的项目对后端服务的版本稳定性有极高要求，且无法承受频繁手动迁移或潜在的破坏性变更，那么在 PocketBase 达到 v1.0.0 稳定版本之前，应谨慎选择。
  • 主要采用服务器端渲染 (SSR) 或传统模板引擎的应用：如果你的前端架构严重依赖服务器端渲染（如 Next.js SSR、PHP、Ruby on Rails 等）或 htmx 等工具，PocketBase 并非最佳选择，因为它与这些技术栈的集成存在固有的复杂性和性能挑战。
  • 需要无服务器函数（Serverless Functions）来处理业务逻辑的应用： 如果你的架构设计倾向于使用云函数来处理事件驱动的、无状态的业务逻辑，PocketBase 无法直接提供这种能力。
  • 需要高度定制化或复杂 SQL 查询的应用： 尽管 PocketBase 提供了视图集合和 API 规则，但对于需要频繁编写复杂、高度优化 SQL 查询或存储过程的场景，直接使用传统关系型数据库可能更灵活。

安装与配置

以二进制可执行文件方式操作。

  • 下载预编译可执行文件：https://github.com/pocketbase/pocketbase/releases，解压后进入目录，会看到一个可执行的 pocketbase 文件；

  • 启动服务：

    1
    ./pocketbase [--dev] [--encryptionEnv random32charstringxxxxxxxxxxxxxx] serve [--http 127.0.0.1:3000]
    • --dev：启用开发模式，在控制台打印日志和 SQL 语句；
    • --encryptionEnv：随机32个字符，用于加密应用设置内的关键数据（随机字符串可使用 openssl rand -hex 16 生成），开发模式下可以不用，但生产环境建议启用；
    • --http：服务监听的地址和端口。

  • 关键目录结构

    • pb_data：此目录用于存储应用程序的所有数据，包括 SQLite 数据库文件 (data.db)、本地备份文件和所有上传的文件。

      pb_data 包含敏感数据和运行时生成的文件，通常应将其添加到版本控制系统的 .gitignore 文件中，不应提交到代码仓库 。

    • pb_migrations：此目录包含 JavaScript 迁移文件，用于管理集合（collections）的结构变更。这些迁移文件可以安全地提交到版本控制系统中，以便团队协作和版本回溯。开发者也可以在此目录中编写自定义的迁移脚本，以实现更复杂的数据库结构或数据操作。
    • pb_public（可选目录）：如果此目录存在，PocketBase 将从其中提供静态内容，例如 HTML、CSS 文件和图片。这意味着 PocketBase 不仅可以作为后端服务，还能直接托管前端应用，实现真正的全栈一体化部署。

  • 默认路由

    • http://127.0.0.1:8090：如果 pb_public 目录存在，此路由将提供该目录中的静态内容，如 HTML、CSS 和 JavaScript 文件。这使得 PocketBase 能够直接托管前端单页应用（SPA（或简单的网站 。  
    • http://127.0.0.1:8090/_/：这是超级用户管理后台的访问地址。通过此界面，管理员可以直观地管理数据库集合、记录、用户、文件以及配置各种应用设置 。  
      PocketBase注册登录页
      PocketBase注册登录页
    • http://127.0.0.1:8090/api/：此路由是 PocketBase 提供的 REST 风格 API 的入口点。所有客户端与后端数据的交互都通过此接口进行，包括数据查询、修改、认证等操作。

数据建模：集合与字段

在 PocketBase 中，数据组织的核心是“集合”（Collections）。集合代表了应用程序中的不同数据类型，其底层由普通的 SQLite 表支持，这些表会根据集合的名称和定义的字段自动生成。集合中的单个条目称为“记录”（Record），对应于 SQL 表中的一行数据。开发者可以通过管理后台、Web API（仅限超级用户）或 Go/JavaScript 迁移脚本来管理集合和记录。

PocketBase默认的users集合
PocketBase默认的users集合

集合类型

PocketBase 提供了三种主要类型的集合，以适应不同的数据存储和访问需求：

PocketBase的集合类型
PocketBase的集合类型
  1. 基础集合（Base Collection）：
    • 这是最常用的默认集合类型。
    • 它用于存储任何通用应用程序数据，例如博客文章（articles）、产品信息（products）或用户帖子（posts）等。
  2. 视图集合（View Collection）：
    • 视图集合是只读的。
    • 其数据通过纯 SQL SELECT 语句填充，这使得开发者能够执行复杂的数据聚合或自定义查询，例如从多个表中联结数据并计算总评论数。
    • 需要注意的是，视图集合不接收实时事件，因为它们不支持创建、更新或删除操作。
  3. 认证集合（Auth Collection）：
    • 认证集合包含了基础集合的所有功能，并额外提供了一些特殊字段和功能，专门用于管理应用程序用户和各种认证选项。
    • 每个认证集合都包含一些不可重命名或删除的系统字段，如 username、email、emailVisibility、verified 和 password。
    • 开发者可以创建多个认证集合，例如为普通用户、经理、员工或客户分别设置不同的认证集合，每个集合都有自己的字段、独立的登录和记录管理端点。
    • 认证集合还支持基于角色（如通过 select 字段定义“员工”或“职员”角色）、关系（如通过 relation 字段实现记录所有权）和管理权限的访问控制。
    • 多种认证方式：用户名/密码方式、邮箱/密码方式 和 OAuth2方式。
    pocketbase-oauth2
    pocketbase-oauth2
    pocketbase-auth-methods
    pocketbase-auth-methods

PocketBase 提供了三种核心集合类型和多种预定义字段类型，并支持字段修饰符和 API 规则进行数据访问控制。这种设计表明 PocketBase 不仅仅是一个简单的键值存储，它提供了一套相对成熟的数据建模能力，足以支持各种常见的应用场景。预定义的字段类型和内置的访问控制机制，减少了开发者手动实现数据验证和权限逻辑的工作量。Auth 集合的特殊设计简化了用户管理，而 View 集合则提供了灵活的数据聚合能力。这种 “Schema-first” 和“规则驱动”的数据管理方式，使得开发者可以快速定义数据结构和访问权限，从而加速了后端开发。它将数据库管理、API 暴露和安全规则紧密结合，形成了一个内聚的开发环境，特别适合那些希望快速构建功能完备应用的团队。

常用字段类型介绍

除了 JSON 之外，所有集合字段默认都是非空（non-nullable）的。如果字段在数据中缺失，它们将使用其对应类型的零值作为默认值（例如，文本字段为空字符串，数字字段为 0）。所有字段特定的修饰符都通过 Web API 和记录的 Get/Set 方法支持 。

以下是 PocketBase 中常用字段类型的概览：

字段名称 描述 默认值
Plain text 存储字符串值 ""
Rich editor 存储 HTML 格式文本 ""
Number 存储数值（float64） 0
Bool 存储布尔值 false
Email 存储单个电子邮件地址字符串 ""
Url 存储单个 URL 字符串值 ""
DateTime 存储单个日期时间字符串值，遵循 RFC3399 格式 ""
Select 存储预定义列表中的单个或多个字符串值 "" 或
File 管理记录文件，数据库中只存储文件名 "" 或
Relation 存储对其他集合中记录的单个或多个引用 "" 或
JSON 存储任何序列化的 JSON 值 null
PocketBase的字段数据类型
PocketBase的字段数据类型

API 规则与权限控制

PocketBase 的 API 规则的之处在于它们不仅作为访问控制机制，还兼作数据过滤器。这使得开发者可以直接在数据库层面定义精细的权限和数据可见性逻辑。

API 规则概述

每个集合都有五个特定的规则，对应于不同的 API 操作：

  • listRule：控制记录的列表访问权限。
  • viewRule：控制单个记录的查看权限。
  • createRule：控制新记录的创建权限。
  • updateRule：控制现有记录的更新权限。
  • deleteRule：控制记录的删除权限。

此外，认证集合（Auth Collection）还拥有一个特殊的 manageRule，它允许一个用户（甚至可以是来自不同集合的用户）完全管理另一个用户的数据，例如更改其电子邮件或密码。

PocketBase认证类型集合的API规则
PocketBase认证类型集合的API规则

规则设置方式

  • “锁定” (null)：这是默认设置。当规则被“锁定”时，只有授权的超级用户才能执行相应的操作 。  
  • 空字符串：如果规则设置为空字符串，则任何人都可以执行该操作，包括超级用户、已认证用户和未认证的访客 。  
  • 非空字符串：当规则设置为非空字符串时，只有满足该字符串所定义的过滤表达式的用户（无论是否已认证）才能执行相应的操作 。
PocketBase的API规则、过滤器
PocketBase的API规则、过滤器

规则作为过滤器

PocketBase API 规则的独特之处在于它们也兼作记录（Record）过滤器。这意味着开发者可以直接在规则中定义数据过滤条件。例如，可以使用 status = "active" 这样的规则来确保 listRule 只返回集合中状态为 active 的记录，从而在数据库层面实现数据隔离和筛选 。

过滤器语法与特殊标识符、修饰符

PocketBase 的过滤器语法通常遵循 OPERAND OPERATOR OPERAND 的格式，提供了强大的数据查询和筛选能力。在 API 规则中，开发者可以使用以下三组字段来构建过滤表达式：

  • 集合 Schema 字段：包括所有集合自身的字段以及嵌套的关系字段，例如 someRelField.status!= "pending"。  
  • @request.*：用于访问当前请求的上下文数据，例如查询参数、请求体/表单字段以及当前认证用户的状态。这包括 @request.context（规则使用的上下文，如 default, oauth2, realtime）、@request.method（HTTP 请求方法）、@request.headers.*（请求头）、@request.query.*（查询参数）、@request.auth.*（当前认证模型，如 @request.auth.id!= ""）和 @request.body.*（提交的请求体参数）。需要注意的是，上传的文件不属于 @request.body，它们是独立评估的。
  • @collection.*：允许跨集合过滤，即针对与当前集合不直接相关的其他集合进行查询，但它们共享一个共同的字段值。例如，@collection.news.categoryId?= categoryId。

PocketBase 的过滤器语法还包含一系列特殊标识符和修饰符，以实现更复杂的逻辑：

  • @macros：一系列基于 UTC 的日期时间宏，如 @now（当前日期时间）、@yesterday、@monthStart 等，可用于构建时间相关的过滤条件，例如 @request.body.publicDate >= @now。
  • :isset 修饰符：仅适用于 @request.* 字段，用于检查客户端是否在请求中提交了特定数据。例如，@request.body.role:isset = false 可以用于禁止更改 role 字段。
  • :length 修饰符：用于检查数组字段（如多文件、多选、多关系字段）中项目的数量。例如，@request.body.someSelectField:length > 1。
  • :each 修饰符：适用于多选、文件和关系类型字段，可对字段数组中的每个项目应用条件。例如，@request.body.someSelectField:each ~ "create"。
  • :lower 修饰符：执行小写字符串比较，例如 @request.body.title:lower = "test"。它底层使用 SQLite 的 LOWER 函数。

文件上传与处理

PocketBase 提供了一套内置的文件上传和处理机制，简化了应用程序中文件存储和访问的管理。

文件存储机制

默认情况下，PocketBase 将所有上传的文件存储在本地文件系统的 pb_data/storage 目录中。对于大多数中小型应用而言，这是一个推荐的存储选项，因为它提供了快速的文件读写性能，并且易于操作和备份。开发者只需备份 pb_data 目录即可同时备份数据库和所有文件。

除了本地存储，PocketBase 也支持配置 S3 兼容的对象存储服务。这为需要更高可扩展性、持久性或地理分布存储的应用程序提供了灵活的选择。无论选择哪种存储方式，数据库中都只存储文件的名称（包含一个随机部分以确保唯一性），实际的文件内容则存储在文件系统或 S3 上。这种分离存储的策略，既保证了数据库的轻量化，又提供了文件存储的灵活性。

PocketBase的文件存储
PocketBase的文件存储

受保护文件的概念与使用

默认情况下，所有上传的文件，如果知道其完整的 URL（/api/files/<collection_name_or_id>/<record_id>/<file_name_and_random_string>），都是公开可访问的。对于大多数应用程序来说，这种公开访问方式是合理且安全的，因为文件名称中包含随机部分，难以猜测。

然而，对于包含敏感信息的文件，例如身份证件扫描件、合同副本等，开发者可能需要额外的安全措施来防止未经授权的访问。PocketBase 提供了“受保护文件”功能来满足这一需求。开发者可以在管理后台的字段选项中，将特定的文件字段标记为“受保护”（Protected）。

当文件字段被标记为“受保护”后，访问这些文件需要使用特殊的短期文件令牌。只有那些满足记录集合的 View API 规则的请求，才能成功访问或下载受保护的文件。这意味着文件访问权限与数据记录的访问权限紧密关联，确保了只有被授权的用户才能查看或下载相关联的敏感文件。

总结与展望

PocketBase 作为一个极简的 all-in-one 后端解决方案，在现代应用开发中展现出独特的价值。

编辑集合
编辑集合
创建索引
创建索引
创建记录
创建记录
接口文档
接口文档
日志设置
日志设置
日志详请
日志详请
应用设置
应用设置
邮件配置
邮件配置
数据备份
数据备份
导出集合
导出集合
导入集合
导入集合
系统管理员
系统管理员

PocketBase 的优势总结

  • 极简主义：它将数据库、认证、文件存储和 API 等核心后端功能整合到单个可执行文件中，极大地简化了部署和运维流程，无需复杂的外部依赖。
  • 功能全面：内置的 SQLite 数据库、实时订阅、用户认证与管理、文件处理以及自动生成的 REST-ish API，为开发者提供了一站式的后端服务。
  • 实时能力：支持实时订阅功能，使得构建动态的、数据即时同步的应用程序变得轻而易举。
  • 高度可扩展：PocketBase 既可以作为独立的应用程序快速部署，也可以作为 Go 框架嵌入到更大的 Go 项目中，允许开发者进行深度的定制和功能扩展。
  • 开发者友好：提供官方的 JavaScript 和 Dart SDK，极大地简化了客户端与后端 API 的交互。灵活强大的 API 规则系统，使得权限控制和数据过滤能够直接在后端层面高效实现。

潜在应用场景

基于其独特的优势，PocketBase 特别适用于以下场景：

  • 快速原型开发 (Rapid Prototyping)：其“开箱即用”的特性和极简的配置，使得开发者能够迅速搭建后端，验证产品想法。
  • 中小型 Web 应用和移动应用后端：对于用户量和数据规模在中等范围的应用，PocketBase 能够提供稳定且高效的后端支持，同时降低运维成本。
  • 内部工具和管理系统：由于其内置的管理后台和灵活的权限控制，非常适合开发企业内部使用的管理界面、数据看板或自动化工具。
  • 个人项目和 MVP (Minimum Viable Product) 开发：对于个人开发者或初创团队，PocketBase 提供了一个低成本、高效率的解决方案，帮助他们快速推出最小可行产品。

展望

PocketBase 作为一个活跃的开源项目，仍在积极开发中。官方明确指出，在达到 v1.0.0 之前，不保证完全的向后兼容性。这意味着项目会持续演进，并可能引入重大改进，但同时也要求用户在升级时保持警惕，并准备好进行必要的手动迁移步骤。

尽管 PocketBase 提供了强大的功能和极简的体验，但其版本稳定性表明它目前更适合那些能够承受一定程度的变更和维护成本的早期采用者或项目。开发者应持续关注其 GitHub 仓库的 CHANGELOG.md ，以便及时了解最新功能和潜在的迁移要求。随着项目的不断成熟，PocketBase 有望成为更多开发者构建高效、轻量级后端服务的首选。

参考资料
许可协议

本文采用 署名-非商业性使用-相同方式共享 4.0 国际 许可协议，转载请注明出处。

分享文章