PowerSync Docker镜像文档

镜像概述和主要用途

PowerSync 是一个同步引擎及SDK集合，用于构建本地优先（local-first）应用。其核心功能是保持客户端 SQLite 数据库与服务端数据库（PostgreSQL、MongoDB 或 MySQL）的实时同步，提供即时响应的用户界面和简化的状态传输能力。该 Docker 镜像封装了 PowerSync 服务端组件，便于快速部署和集成到现有系统中。

支持架构：amd64、arm64

核心功能和特性

多数据库同步：支持服务端 PostgreSQL、MongoDB、MySQL 与客户端 SQLite 之间的双向数据同步
本地优先架构：客户端数据存储于 SQLite，确保离线可用和低延迟访问，网络恢复后自动同步
实时响应 UI：通过本地数据访问实现即时响应的用户体验，减少网络依赖
简化状态传输：优化数据同步逻辑，降低客户端与服务端之间的状态管理复杂度
灵活部署：支持容器化部署，易于集成到各类开发和生产环境

使用场景和适用范围

本地优先应用开发：需同时支持在线/离线功能的移动应用、桌面应用或 Web 应用
低延迟数据访问：对用户界面响应速度要求高的场景，如实时分析、即时通讯工具
多端数据一致性：需在多个客户端设备间保持数据同步的应用（如协作工具、跨设备同步服务）
混合部署环境：需对接不同类型服务端数据库（PostgreSQL/MongoDB/MySQL）的系统

使用方法和配置说明

前提条件

准备 PowerSync 配置文件（config.yaml），详细格式参见 ***配置文档
确保 Docker 环境已安装并运行
（可选）创建自定义 Docker 网络以连接数据库等依赖服务

快速启动（docker run）

通过以下命令启动 PowerSync 服务实例：

bash
docker run \
  -p 8080:80 \  # 端口映射：主机8080端口映射到容器80端口
  -e POWERSYNC_CONFIG_B64="$(base64 -i ./config.yaml)" \  # 注入base64编码的配置文件
  --network my-local-dev-network \  # 连接到包含数据库的网络（如有）
  --name my-powersync \  # 容器名称
  journeyapps/powersync-service:latest  # 镜像名称及标签

参数说明：

-p 8080:80：容器内服务默认监听80端口，映射到主机8080端口供外部访问
-e POWERSYNC_CONFIG_B64：必填环境变量，值为 config.yaml 文件的 base64 编码字符串，用于配置服务端同步规则、数据库连接等核心参数
--network：若服务端数据库（如PostgreSQL）运行在其他容器中，需通过共同网络实现通信

Docker Compose 部署示例

参考 *** Docker Compose 示例，以下为简化版配置（含PostgreSQL依赖）：

yaml
version: '3.8'

services:
  powersync:
    image: journeyapps/powersync-service:latest
    ports:
      - "8080:80"
    environment:
      - POWERSYNC_CONFIG_B64=${POWERSYNC_CONFIG_B64}  # 从环境变量注入配置
    depends_on:
      - postgres
    networks:
      - app-network

  postgres:
    image: postgres:14
    environment:
      - POSTGRES_USER=powersync
      - POSTGRES_PASSWORD=secure_password
      - POSTGRES_DB=powersync_demo
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - app-network

networks:
  app-network:

volumes:
  postgres-data:

使用方法：

准备 config.yaml 并编码：export POWERSYNC_CONFIG_B64=$(base64 -i ./config.yaml)
启动服务：docker-compose up -d

配置文件说明

config.yaml 是 PowerSync 服务的核心配置，需包含数据库连接信息、同步规则、认证配置等。示例结构（详细配置参见 ***文档）：

yaml
database:
  type: postgres
  url: "postgresql://user:password@postgres:5432/dbname"
sync:
  rules:
    - table: "todos"
      columns: ["id", "title", "completed"]
      where: "user_id = auth.uid()"

配置文件需通过 base64 编码后注入环境变量 POWERSYNC_CONFIG_B64，编码命令：base64 -i ./config.yaml