PocketBase 的 Docker 镜像

---

快速开始

# 基本用法 - 在 8090 端口启动 PocketBase 服务器
docker run --rm -p 8090:8090 ghcr.io/muchobien/pocketbase:latest

# 在 http://localhost:8090/_/ 访问管理界面

[!TIP] 生产环境使用时，挂载卷以实现数据持久化：-v ./pb_data:/pb_data

特性

• 🚀 智能入口点：使用合理的默认值自动启动 PocketBase 服务
• 🔧 灵活的命令：运行任何 PocketBase 命令（migrate、superuser 等）
• 🌐 可配置的主机/端口：使用 PB_HOST 和 PB_PORT 环境变量
• 👤 自动超级用户：通过 PB_ADMIN_EMAIL 和 PB_ADMIN_PASSWORD 自动创建/更新超级用户
• 📦 多架构支持：支持 amd64、arm64 和 armv7
• 🛡️ 安全默认值：遵循 Docker 和 PocketBase 最佳实践

环境变量

[!NOTE] 更改 PB_PORT 时，请记住同时更新 Docker 端口映射（例如，端口 3000 对应 -p 3000:3000）。

使用示例

默认服务器

# 使用默认设置启动 PocketBase 服务器
docker run --rm -p 8090:8090 ghcr.io/muchobien/pocketbase:latest

自定义主机和端口

# 自定义端口
docker run --rm -p 3000:3000 -e PB_PORT=3000 ghcr.io/muchobien/pocketbase:latest

# 仅本地访问（安全考虑）
docker run --rm -p 8090:8090 -e PB_HOST=127.0.0.1 ghcr.io/muchobien/pocketbase:latest

# 自定义主机和端口
docker run --rm -p 9000:9000 -e PB_HOST=0.0.0.0 -e PB_PORT=9000 ghcr.io/muchobien/pocketbase:latest

自动创建超级用户

# 启动时自动创建超级用户
docker run --rm -p 8090:8090 \
-e PB_ADMIN_EMAIL=admin@example.com \
-e PB_ADMIN_PASSWORD=supersecret123 \
ghcr.io/muchobien/pocketbase:latest

# 带数据持久化
docker run -d --name pocketbase \
-p 8090:8090 \
-v $(pwd)/pb_data:/pb_data \
-e PB_ADMIN_EMAIL=admin@example.com \
-e PB_ADMIN_PASSWORD=supersecret123 \
ghcr.io/muchobien/pocketbase:latest

[!NOTE] 仅在使用默认服务行为（无自定义命令）时创建/更新超级用户。 内部使用 pocketbase superuser upsert，因此重启容器是安全的。

[!WARNING] 安全存储管理员凭据！生产环境中考虑使用 Docker secrets 或加密环境文件。

开发模式

# 启用开发模式并显示详细日志
docker run --rm -p 8090:8090 ghcr.io/muchobien/pocketbase:latest --dev

# 自定义端口的开发模式
docker run --rm -p 3000:3000 -e PB_PORT=3000 ghcr.io/muchobien/pocketbase:latest --dev

[!WARNING] 切勿在生产环境中使用 --dev 标志，因为它会在日志中暴露敏感信息。

PocketBase 命令

# 显示帮助
docker run --rm ghcr.io/muchobien/pocketbase:latest --help

# 显示版本
docker run --rm ghcr.io/muchobien/pocketbase:latest --version

# 运行数据库迁移
docker run --rm -v ./pb_data:/pb_data ghcr.io/muchobien/pocketbase:latest migrate

# 创建超级用户
docker run --rm -it -v ./pb_data:/pb_data ghcr.io/muchobien/pocketbase:latest superuser create

# 超级用户帮助
docker run --rm ghcr.io/muchobien/pocketbase:latest superuser --help

Shell 访问

# 访问 shell 进行调试或维护
docker run --rm -it --entrypoint /bin/sh ghcr.io/muchobien/pocketbase:latest

生产部署

以下是生产部署的示例配置。

使用 Docker Compose（推荐）

services:
  pocketbase:
    image: ghcr.io/muchobien/pocketbase:latest
    container_name: pocketbase
    restart: unless-stopped
    environment:
      # 可选：配置主机和端口（默认：0.0.0.0:8090）
      PB_HOST: 0.0.0.0
      PB_PORT: 8090
      # 可选：自动创建超级用户（生产环境推荐）
      PB_ADMIN_EMAIL: admin@yourdomain.com
      PB_ADMIN_PASSWORD: your-secure-password-here
      # 可选：启用设置加密（32 字符密钥）
      # https://pocketbase.io/docs/going-to-production/#enable-settings-encryption
      ENCRYPTION: $(openssl rand -hex 16)
      # 可选：设置时区
      TZ: Europe/Berlin
    ports:
      - "8090:8090" # 自定义端口时需同时更改端口和 PB_PORT："3000:3000"
    volumes:
      - ./pb_data:/pb_data
      - ./pb_public:/pb_public # 可选
      - ./pb_hooks:/pb_hooks # 可选
    # 可选：如果使用 ENCRYPTION 环境变量，添加加密标志
    command: ["--encryptionEnv", "ENCRYPTION"]
    healthcheck:
      test:
        [
          "CMD",
          "wget",
          "--no-verbose",
          "--tries=1",
          "--spider",
          "http://localhost:8090/api/health",
        ]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s

[!WARNING] 生产环境中务必使用卷进行数据持久化。不使用卷的情况下，容器停止时所有数据将丢失。

使用 Docker CLI

# 基本生产设置（默认：0.0.0.0:8090）
docker run -d \
  --name=pocketbase \
  -p 8090:8090 \
  -v $(pwd)/pb_data:/pb_data \
  -v $(pwd)/pb_public:/pb_public \
  -v $(pwd)/pb_hooks:/pb_hooks \
  --restart unless-stopped \
  ghcr.io/muchobien/pocketbase:latest

# 带自定义端口、主机、超级用户和加密
docker run -d \
  --name=pocketbase \
  -p 3000:3000 \
  -e PB_HOST=0.0.0.0 \
  -e PB_PORT=3000 \
  -e PB_ADMIN_EMAIL=admin@yourdomain.com \
  -e PB_ADMIN_PASSWORD=your-secure-password-here \
  -e ENCRYPTION=$(openssl rand -hex 16) \
  -v $(pwd)/pb_data:/pb_data \
  -v $(pwd)/pb_public:/pb_public \
  -v $(pwd)/pb_hooks:/pb_hooks \
  --restart unless-stopped \
  ghcr.io/muchobien/pocketbase:latest \
  --encryptionEnv ENCRYPTION

[!IMPORTANT] 生产部署时，使用强加密密钥并保护环境变量。

带日志的开发设置

docker run -d \
  --name=pocketbase-dev \
  -p 8090:8090 \
  -v $(pwd)/pb_data:/pb_data \
  ghcr.io/muchobien/pocketbase:latest \
  --dev

高级用法

本地构建镜像

# 使用特定的 PocketBase 版本构建
docker build --build-arg VERSION=0.22.21 -t my-pocketbase .

# 使用最新版本构建（使用 GitHub 最新发布版）
docker build --build-arg VERSION=0.23.0 -t my-pocketbase:0.23.0 .

# 不指定版本构建（使用 Dockerfile 中的默认版本）
docker build -t my-pocketbase:dev .

开发用 Docker Compose

services:
  pocketbase:
    build:
      context: .
      args:
        - VERSION=0.22.21
    container_name: pocketbase-dev
    environment:
      PB_HOST: 0.0.0.0
      PB_PORT: 8090
    ports:
      - "8090:8090"
    volumes:
      - ./pb_data:/pb_data
      - ./pb_public:/pb_public
      - ./pb_hooks:/pb_hooks
    command: ["--dev"]

数据库管理

[!IMPORTANT] 以下示例假设您已有运行中的 PocketBase 容器。

使用 Docker CLI 操作运行中的容器

# 首先，启动 PocketBase 容器（如果尚未运行）
docker run -d --name pocketbase -p 8090:8090 -v $(pwd)/pb_data:/pb_data ghcr.io/muchobien/pocketbase:latest

# 在运行中的容器中创建超级用户
docker exec -it pocketbase /usr/local/bin/pocketbase superuser create --dir /pb_data

# 在运行中的容器中运行迁移
docker exec pocketbase /usr/local/bin/pocketbase migrate --dir /pb_data

# 检查 PocketBase 版本
docker exec pocketbase /usr/local/bin/pocketbase --version --dir /pb_data

# 查看超级用户帮助
docker exec pocketbase /usr/local/bin/pocketbase superuser --help --dir /pb_data

使用 Docker Compose

# compose.yml - 您的运行配置
services:
  pocketbase:
    image: ghcr.io/muchobien/pocketbase:latest
    container_name: pocketbase
    ports:
      - "8090:8090"
    volumes:
      - ./pb_data:/pb_data

# 启动服务
docker compose up -d

# 通过 compose 执行管理命令
docker compose exec pocketbase pocketbase superuser create --dir /pb_data
docker compose exec pocketbase pocketbase migrate --dir /pb_data
docker compose exec pocketbase pocketbase --version --dir /pb_data
docker compose exec pocketbase pocketbase superuser --help --dir /pb_data

# 查看日志
docker compose logs pocketbase

# 停止服务
docker compose down

一次性管理（无需运行容器）

[!TIP] 当您需要在永久启动服务器前运行管理命令时使用此方法。

# 启动服务器前创建超级用户
docker run --rm -it -v $(pwd)/pb_data:/pb_data \
  ghcr.io/muchobien/pocketbase:latest superuser create

# 启动服务器前运行迁移
docker run --rm -v $(pwd)/pb_data:/pb_data \
  ghcr.io/muchobien/pocketbase:latest migrate

# 然后正常启动服务器
docker run -d --name pocketbase -p 8090:8090 -v $(pwd)/pb_data:/pb_data \
  ghcr.io/muchobien/pocketbase:latest

故障排除

常见问题

端口已被占用：

# 使用其他端口
docker run --rm -p 3000:3000 -e PB_PORT=3000 ghcr.io/muchobien/pocketbase:latest

卷权限问题：

[!WARNING] Linux 系统上，确保挂载卷的文件所有权正确。

# 确保正确的所有权（Linux/macOS）
sudo chown -R 1000:1000 ./pb_data ./pb_public ./pb_hooks

无法从容器外部连接：

# 确保 PB_HOST 设置为 0.0.0.0（默认值）
docker run --rm -p 8090:8090 -e PB_HOST=0.0.0.0 ghcr.io/muchobien/pocketbase:latest

更新 PocketBase：

# 拉取最新镜像
docker pull ghcr.io/muchobien/pocketbase:latest

# 停止并移除旧容器
docker stop pocketbase && docker rm pocketbase

# 使用新镜像启动（通过卷挂载保留数据）
docker run -d --name pocketbase -p 8090:8090 -v $(pwd)/pb_data:/pb_data ghcr.io/muchobien/pocketbase:latest

# 或使用 Docker Compose
docker compose pull
docker compose up -d

调试

# 查看容器日志
docker logs pocketbase

# 访问容器 shell
docker exec -it pocketbase /bin/sh

# 带调试日志运行
docker run --rm -p 8090:8090 ghcr.io/muchobien/pocketbase:latest --dev

镜像信息

支持的架构

此镜像支持多种架构。Docker 会自动为您的平台拉取正确的镜像：

可用标签

相关仓库

• https://github.com/pocketbase/pocketbase - PocketBase 官方仓库
• PocketBase 文档 - 官方文档