power-sync-docker容器启动失败探查

PowerSync Docker 容器反复重启时的排查思路与高频原因说明

#status / growing #type / debug

[!info] related notes

相关概念: PowerSync, Docker, docker创建开发测试数据库

power-sync-docker容器启动失败探查

遇到容器一直处于 Restarting 状态，说明 PowerSync 服务在启动后立刻遇到了致命错误导致进程退出，然后 Docker 的重启策略又尝试把它拉起来，周而复始。

要解决这个问题，唯一的真相在日志里。不过，针对 PowerSync 这个同步引擎，结合你目前运行的 Postgres 数据库，有几个非常经典的“坑”大概率是导致崩溃的原因。

我们可以按以下步骤来排查和解决：

1. 揪出报错的真凶（查看日志）

这是最重要的一步。在你的终端执行以下命令，看看 PowerSync 临死前到底输出了什么错误：

Bash

docker logs dailyuse-dev-powersync

(如果日志太多，可以加个 --tail 50 只看最后 50 行)

通常你会在日志底部看到一个 FATAL 或 ERROR 级别的提示。

2. 排查 PowerSync 的高频踩坑点

如果你在日志里看到了以下相关的错误，可以直接对号入座：

嫌疑 A：Postgres 没有开启逻辑复制 (Logical Replication)

PowerSync 能够实现多端数据同步的核心，就是监听 Postgres 的预写日志 (WAL)。如果你启动 dailyuse-dev-db 时使用的是默认的 Postgres 镜像，它默认是不开启逻辑复制的。PowerSync 一连上发现没开，就会直接报错退出。

如何修复： 检查你的 docker-compose.yml 文件中关于 Postgres 的配置。你需要确保它的启动命令带上了 wal_level=logical。

YAML

# docker-compose.yml 示例片段
services:
  db:
    image: postgres:16-alpine
    command: ["postgres", "-c", "wal_level=logical"] # 关键是这一句
    # …

嫌疑 B：数据库连接字符串 (URI) 写错了

虽然你的 Postgres 状态是 healthy，但如果 PowerSync 找不到它，依然会启动失败。新手最常犯的错误是在 PowerSync 的环境变量里把数据库地址写成了 localhost 或 127.0.0.1。在 Docker 的网络里，PowerSync 容器里的 localhost 指的是它自己，而不是宿主机。

如何修复： 检查 PowerSync 的环境变量（例如 PS_PG_URI 或类似配置）。域名必须使用数据库容器的名字（也就是 dailyuse-dev-db，或者你在 compose 文件中定义的服务名，比如 db）。

正确的格式类似这样：postgres://用户名:密码@dailyuse-dev-db:5432/你的数据库名

嫌疑 C：Postgres 还没准备好，PowerSync 就去连了

虽然 Docker ps 显示 Postgres 是 UP，但这俩可能是同时启动的。如果 PowerSync 启动过快，在 Postgres 完全初始化好（特别是首次启动建库时）之前就发起连接，也会失败退出。

如何修复： 虽然 Docker 的 Restarting 机制最终会等数据库就绪后让 PowerSync 连上（如果仅仅是时间差问题，它重启几次后应该会变成 UP），但更优雅的做法是在 docker-compose.yml 中为 PowerSync 添加 depends_on 检查：

YAML
```
depends_on:
  db:
    condition: service_healthy
```

你需要我帮你分析一下具体的错误原因吗？你可以把 docker logs dailyuse-dev-powersync 打印出来的最后几行报错信息发给我看看。

Docker MOC