augustodelg/pocketbase

PocketBase 非官方容器镜像文档

1. 镜像概述和主要用途

1.1 镜像说明

本镜像为 非官方 PocketBase 容器镜像（⚠️ UNOFFICIAL ⚠️），基于 PocketBase 官方功能构建。PocketBase 是一款由 Go 语言开发的开源后端解决方案，集成了嵌入式数据库、用户认证、RESTful API 等核心能力，旨在简化后端服务搭建流程。

1.2 主要用途

• 提供 PocketBase 的容器化部署方式，简化环境配置与依赖管理
• 支持数据持久化存储，确保服务重启后数据不丢失
• 快速集成至 Docker 生态系统（如 Docker Compose、Kubernetes 等），适用于开发、测试及小型生产环境

2. 核心功能和特性

2.1 PocketBase 核心功能

• 嵌入式数据库：内置 SQLite 数据库，无需额外配置外部数据库
• 用户认证系统：支持***/密码、OAuth 等认证方式，内置权限管理
• RESTful API：自动生成数据模型的 CRUD API，支持过滤、排序、分页
• 实时订阅：基于 WebSocket 实现数据变更的实时推送
• 后台管理界面：提供可视化控制台，支持数据管理、用户配置等操作

2.2 容器镜像特性

• 轻量级：基于 Alpine 或官方 Go 基础镜像构建，镜像体积小
• 数据持久化：通过 Docker 数据卷挂载实现 /pb_data 目录持久化，避免数据丢失
• 即开即用：无需复杂配置，启动即可使用 PocketBase 全部功能
• 版本同步：镜像标签与 PocketBase 官方版本同步（如 :0.20.0 对应官方 0.20.0 版本）

3. 使用场景和适用范围

3.1 适用场景

• 小型 Web 应用后端：快速搭建具备数据存储、用户认证的后端服务
• 原型开发与演示：快速验证产品概念，减少后端开发周期
• 个人项目或创业项目：降低初期基础设施成本，专注业务逻辑开发
• 教育与学习：作为轻量级后端示例，学习 API 设计、数据库操作等基础

3.2 适用范围

• 开发环境、测试环境
• 小型生产环境（单实例部署，建议定期备份数据）
• 不建议用于高并发、大规模生产环境（非官方镜像，缺乏企业级支持）

4. 详细的使用方法和配置说明

4.1 前置要求

• 已安装 Docker Engine（20.10+ 版本）
• 如需使用 Docker Compose，需安装 Docker Compose v2+

4.2 Docker Run 快速启动

通过以下命令快速启动 PocketBase 容器，默认暴露 8090 端口并持久化数据：

bash
docker run --name pocketbase -p 8090:8090 -v pocketbase-data:/pb_data augustodelg/pocketbase:latest

参数说明：

• --name pocketbase：指定容器名称为 pocketbase
• -p 8090:8090：端口映射，将宿主机 8090 端口映射到容器 8090 端口（PocketBase 默认端口）
• -v pocketbase-data:/pb_data：数据卷挂载，使用命名卷 pocketbase-data 挂载容器内 /pb_data 目录（存储数据库及配置文件，实现数据持久化）
• augustodelg/pocketbase:latest：镜像名称及标签（latest 为最新版本，可指定具体版本如 :0.20.0）

4.3 Docker Compose 配置

创建 docker-compose.yml 文件，通过 Compose 管理服务：

yaml
version: '3.7'

services:
  pocketbase:
    image: augustodelg/pocketbase:latest  # 镜像及版本
    restart: unless-stopped  # 除非手动停止，否则自动重启容器
    ports:
      - "8090:8090"  # 端口映射
    volumes:
      - pocketbase-data:/pb_data  # 数据卷挂载，持久化数据

volumes:
  pocketbase-data:  # 定义命名卷，自动创建并管理

启动命令：

bash
docker-compose up -d  # 后台启动服务

停止命令：

bash
docker-compose down  # 停止服务（数据卷保留，数据不丢失）

4.4 配置说明

4.4.1 端口修改

如需修改访问端口，调整端口映射参数即可。例如，将宿主机端口改为 8080：

bash
# Docker Run
docker run --name pocketbase -p 8080:8090 -v pocketbase-data:/pb_data augustodelg/pocketbase:latest

# Docker Compose（修改 ports 字段）
ports:
  - "8080:8090"

4.4.2 数据备份

数据卷 pocketbase-data 存储所有持久化数据，备份方法：

bash
# 导出数据卷内容至本地目录
docker run --rm -v pocketbase-data:/source -v $(pwd):/backup alpine tar -czf /backup/pb_data_backup.tar.gz -C /source .

4.4.3 环境变量（可选）

当前镜像暂未定义额外环境变量，如需自定义 PocketBase 配置（如数据库路径、日志级别等），可参考 PocketBase 官方文档，通过启动命令附加参数实现，例如：

bash
# 启动时指定日志级别为 debug
docker run --name pocketbase -p 8090:8090 -v pocketbase-data:/pb_data augustodelg/pocketbase:latest serve --log-level debug

5. 注意事项

• 非官方镜像：本镜像为第三方维护，非 PocketBase 官方提供，生产环境使用前建议测试验证。
• 版本兼容性：镜像标签与 PocketBase 官方版本同步，升级时需注意版本间兼容性（参考 https://github.com/pocketbase/pocketbase/releases%EF%BC%89%E3%80%82
• 数据安全：定期备份 /pb_data 目录数据，避免因容器或卷损坏导致数据丢失。
• 项目地址：镜像源码及更新说明见 GitHub 项目：https://github.com/augustodelg/pocketbase-docker