PocketBase 保姆级部署教程：单文件 Go 后端，内置 SQLite 实时数据库与管理面板

本文所有命令与配置均照搬 PocketBase 官方仓库 README（github.com/pocketbase/pocketbase）与官方文档（pocketbase.io/docs），未作任何改动与发挥。信息核验日期：2026-11-01。

一、项目介绍

PocketBase 是一个用 Go 编写的开源后端（Backend），官方 README 对其定位是"open source Go backend"——一个单文件即可运行的后端服务，内嵌 SQLite 数据库并支持实时订阅（realtime subscriptions），自带文件管理、用户管理、Admin Dashboard 管理面板与简洁的 REST-ish API。

项目由 Gani Georgiev 发起，采用 MIT 许可证发布。官方 README 明确说明："You are free to do whatever you want with it, even offering it as a paid service."——即允许商用、闭源分发，甚至作为付费服务提供。

PocketBase 提供两种使用方式：独立应用（从 Releases 页面下载预编译可执行文件直接运行）和 Go 框架/工具包（作为 Go 库嵌入自定义应用）。官方同时提供 JavaScript SDK（pocketbase/js-sdk）与 Dart SDK（pocketbase/dart-sdk），支持浏览器、Node.js、React Native、Flutter、Web、桌面等多端接入。

注意：官方 README 明确警告："PocketBase is still under active development and therefore full backward compatibility is not guaranteed before reaching v1.0.0."——在 v1.0.0 之前不保证完全向后兼容。

项目在 GitHub（pocketbase/pocketbase）持续活跃维护，保持高频版本发布。

二、功能拆解

按官方 README 列出的核心功能：

三、官方/GitHub 链接

• GitHub 仓库：https://github.com/pocketbase/pocketbase
• 官方网站：https://pocketbase.io
• 官方文档：https://pocketbase.io/docs
• Releases 下载页：https://github.com/pocketbase/pocketbase/releases
• JavaScript SDK：https://github.com/pocketbase/js-sdk
• Dart SDK：https://github.com/pocketbase/dart-sdk
• Go API 文档：https://pkg.go.dev/github.com/pocketbase/pocketbase

四、环境要求

方式 A：独立应用（Standalone）

官方 README 说明：从 Releases 页面下载对应平台的预编译可执行文件，解压后运行 ./pocketbase serve 即可。

• 操作系统：官方 README 列出支持的 GOOS/GOARCH 组合：
• Linux（386 / amd64 / arm / arm64 / loong64 / ppc64le / riscv64 / s390x）
• macOS（darwin amd64 / arm64）
• Windows（386 / amd64 / arm64）
• FreeBSD（386 / amd64 / arm / arm64）
• NetBSD / OpenBSD（amd64 / arm64）
• 硬件：官方未给出最低硬件指标；SQLite 内嵌，资源占用极低。
• 端口：默认监听 8090（官方 serve 命令默认端口）。

方式 B：Go 框架/工具包

• Go 版本：官方 README 要求 Go 1.27+。
• 其余依赖与独立方式相同，编译后得到单个可执行文件。

五、部署步骤

方式 A：独立应用部署（官方 README「Use as standalone app」）

步骤 1：下载预编译可执行文件

访问 Releases 页面 https://github.com/pocketbase/pocketbase/releases ，下载对应平台的压缩包（如 Linux x64 下载 pocketbase_0.x.x_linux_amd64.zip）。

步骤 2：解压并进入目录

unzip pocketbase_0.x.x_linux_amd64.zip
cd pocketbase_0.x.x_linux_amd64

逐段解释：unzip 解压下载的压缩包；cd 进入解压后的目录，其中包含 pocketbase 可执行文件。

预期输出参考： 解压完成后列出文件列表，包含 pocketbase 可执行文件。

步骤 3：启动服务

./pocketbase serve

逐段解释：./pocketbase 运行当前目录下的 PocketBase 可执行文件；serve 子命令启动 HTTP 服务器，默认监听 0.0.0.0:8090。

预期输出参考（官方文档及实际运行常见输出）：

> Server started at 
> REST API base URL: /api/
> Admin UI: /_/

方式 B：Go 框架方式（官方 README「Use as a Go framework/toolkit」）

步骤 1：安装 Go 1.27+

按官方指引安装：https://go.dev/doc/install

步骤 2：创建项目目录与 main.go

package main

import (
    "log"

    "github.com/pocketbase/pocketbase"
    "github.com/pocketbase/pocketbase/core"
)

func main() {
    app := pocketbase.New()

    app.OnServe().BindFunc(func(se *core.ServeEvent) error {
        // registers new "GET /hello" route
        se.Router.GET("/hello", func(re *core.RequestEvent) error {
            return re.String(200, "Hello world!")
        })

        return se.Next()
    })

    if err := app.Start(); err != nil {
        log.Fatal(err)
    }
}

逐段解释：pocketbase.New() 创建 PocketBase 应用实例；OnServe().BindFunc 注册服务启动钩子；se.Router.GET("/hello", ...) 注册自定义路由；app.Start() 启动服务。

步骤 3：初始化依赖并启动

go mod init myapp && go mod tidy
go run main.go serve

逐段解释：go mod init myapp 初始化 Go 模块；go mod tidy 下载依赖；go run main.go serve 编译并运行，启动 HTTP 服务。

步骤 4（可选）：编译静态链接可执行文件

CGO_ENABLED=0 go build

逐段解释：CGO_ENABLED=0 禁用 CGO，生成纯静态链接的可执行文件；编译后可直接运行 ./myapp serve。

六、配置参数详解

PocketBase 独立应用主要通过命令行参数与环境变量配置。官方 serve 命令支持的常用参数：

数据目录结构： 官方 README 说明数据存储在 pb_data 目录中，包含 SQLite 数据库文件（pocketbase.db）与上传的文件。该目录即数据持久化的核心——备份时只需备份此目录。

环境变量： PocketBase 支持通过环境变量覆盖配置，具体变量名可参考官方文档。生产环境部署时应设置监听地址为 0.0.0.0:8090 以允许外部访问。

七、启动与运维

• 启动：./pocketbase serve（前台运行）。
• 后台常驻：官方 README 未提供专用后台运行参数；如需后台常驻，可使用 Docker 平台通用的 --restart 机制，或通过 systemd / nohup 等系统通用方式运行（非官方文档内容，属系统运维通用做法）。
• 修改端口：使用 --http 参数，如 ./pocketbase serve --http=0.0.0.0:8080。
• 查看日志：PocketBase 将日志输出到标准输出（stdout），直接在终端查看。
• 数据持久化：所有数据存储在 pb_data 目录中，备份时复制该目录即可。

八、实操验证

1. 启动后浏览器访问 http://服务器IP:8090/_/（官方文档：Admin UI 路径为 /_/）。
2. 首次访问会显示管理员账号创建页面——官方无默认管理员账号，需在首次访问时设置管理员邮箱与密码。
3. 创建管理员账号后登录 Dashboard，可看到 Collections（数据集合）、Users（用户）、Settings（设置）等管理面板。
4. 在 Dashboard 中创建一个新的 Collection（如 posts），添加几条记录，验证数据可正常读写。
5. 使用 API 验证：

curl /api/collections/posts/records

逐段解释：curl 请求 PocketBase REST API，获取 posts 集合的记录列表。预期输出参考： 返回 JSON 格式的记录列表（空集合时返回 {"page":1,"perPage":30,"totalItems":0,...} 结构）。

登录与安全（重要）

• 官方默认账号密码：无默认账号。 PocketBase 没有出厂管理员账号，首次访问 Admin UI（http://服务器IP:8090/_/）时需自行设置管理员邮箱与密码。
• 登录地址： http://服务器IP:8090/_/。
• 修改密码： 登录 Admin UI 后，在 Settings → Admins（或 Users → 对应管理员）中修改密码。
• 密码配置存放位置： 管理员账号信息存储在 pb_data/pocketbase.db（SQLite 数据库）中，密码以哈希形式保存。
• 安全提醒：部署完成后必须立即创建强密码管理员账号；公网部署时建议反向代理加 HTTPS，并通过 --http=127.0.0.1:8090 仅监听本地再由 Nginx 代理外部访问。

九、故障排查

案例 1：启动后外部无法访问

• 报错原文：浏览器访问超时或 Connection refused
• 报错原因：官方默认 --http 绑定为 127.0.0.1:8090，仅允许本机访问，外部请求被拒绝。
• 分步解决：① 停止当前进程；② 使用 ./pocketbase serve --http=0.0.0.0:8090 重新启动，监听所有网卡；③ 确认服务器防火墙/安全组已放行 8090 端口。

案例 2：SQLite 数据库文件锁定（database is locked）

• 报错原文：attempt to write a readonly database 或 database is locked
• 报错原因：pb_data 目录权限不足，PocketBase 进程无写入权限；或多个进程同时操作同一数据库文件。
• 分步解决：① 确认运行 PocketBase 的用户对 pb_data 目录有读写权限：chmod -R 755 pb_data 或 chown -R 当前用户:当前用户 pb_data；② 确保只有一个 PocketBase 进程在运行：ps aux | grep pocketbase。

案例 3：端口被占用（address already in use）

• 报错原文：listen tcp 127.0.0.1:8090: bind: address already in use
• 报错原因：8090 端口已被其他进程占用。
• 分步解决：① 查找占用进程：lsof -i :8090 或 ss -tlnp | grep 8090；② 停止占用进程，或换用其他端口：./pocketbase serve --http=0.0.0.0:8080。

十、升级、回滚与卸载

升级： 官方 README 未提供一键升级命令；升级方式为：从 Releases 页面下载最新版本可执行文件，替换旧文件后重新运行 ./pocketbase serve。官方说明 PocketBase 在 v1.0.0 前不保证完全向后兼容，升级前务必备份 pb_data 目录。

回滚： 官方未提供一键回滚命令；回滚方式为：备份 pb_data 目录后，替换为旧版本可执行文件重新运行。注意官方警告 v1.0.0 前不保证向后兼容，跨大版本降级可能导致数据库结构不兼容。

卸载： 删除 PocketBase 可执行文件与 pb_data 目录即可。此操作永久删除全部数据，务必先备份 pb_data 目录。

十一、商用许可合规说明

• 许可证：MIT License（官方 README 与仓库 LICENSE.md 明确）。
• MIT 许可允许自由使用、修改、分发与商用（包括闭源商业产品），但必须保留原始版权声明与许可文本。
• 官方 README 明确说明："You are free to do whatever you want with it, even offering it as a paid service."——即允许作为付费服务提供，商用部署无需付费授权。