journeyapps/powersync-service

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 部署示例

参考 https://github.com/powersync-ja/self-host-demo%EF%BC%8C%E4%BB%A5%E4%B8%8B%E4%B8%BA%E7%AE%80%E5%8C%96%E7%89%88%E9%85%8D%E7%BD%AE%EF%BC%88%E5%90%ABPostgreSQL%E4%BE%9D%E8%B5%96%EF%BC%89%EF%BC%9A

yaml
version: '3.8'

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

  postgres:
    image: docker.xuanyuan.run/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:

使用方法：

1. 准备 config.yaml 并编码：export POWERSYNC_CONFIG_B64=$(base64 -i ./config.yaml)
2. 启动服务：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

遥测（Telemetry）

PowerSync 可能收集***的使用遥测数据，用于优化产品功能和路线图。遥测数据收集为可选功能，用户可选择退出。详情参见 遥测文档。

许可证信息

本镜像发布遵循 FSL-1.1-ALv2 许可证。
镜像包含的软件许可证详情参见 https://github.com/powersync-ja/powersync-service/blob/main/service/LICENSE%E3%80%82

注意：镜像可能包含基础系统组件（如Bash）及依赖库，其使用需遵守各自的许可证条款。用户应确保使用本镜像符合所有包含软件的许可要求。

获取支持

• 问题反馈：https://github.com/powersync-ja/powersync-service/issues
• 社区支持：***
• 邮件支持：***
• 官方文档：PowerSync 文档中心