如何备份 Multica 自建实例的 PostgreSQL 数据（含 pg_dump 陷阱）

如果你的 Multica 是自建实例，在升级版本之前应该先对 PostgreSQL 做一次完整导出：官方文档明确指出迁移是 forward-only 的，因此备份是升级前唯一的回退依据。本文按 self-host-quickstart 中 “Back up Postgres first” 一节的写法，给出官方推荐的导出命令，并解释为什么不能把 pg_dump 直接管道给 gzip。

适用前提：

• 通过 Docker Compose 运行的自建实例（docker-compose.selfhost.yml），postgres 容器处于运行状态；
• 执行机器上已安装 Docker 与 Compose v2（docker compose 形式，文档明确不支持 legacy 的 docker-compose v1）。

备份前确认数据位置与凭据

Multica 自建栈的 PostgreSQL 容器使用 pgvector/pgvector:pg17 镜像，需要 pgcrypto 与 pg_trgm 扩展（见 SELF_HOSTING.md 的 Architecture 一节）。数据存放在命名卷 multica_pgdata 中，映射到容器内 /var/lib/postgresql/data（见 docker-compose.selfhost.yml）。

有两点直接影响备份命令：

1. 用户名和库名以 .env 为准。 compose 文件中两者默认值都是 multica（${POSTGRES_USER:-multica}、${POSTGRES_DB:-multica}）。如果你改过 .env 中的 POSTGRES_USER / POSTGRES_DB，命令中的 -U multica multica 要换成你自己的值——官方文档的原话是：改过默认值时，用 .env 里自己的 POSTGRES_USER / POSTGRES_DB。
2. 区分“停服务”和“删卷”。 docker compose down 保留 pgdata 和 backend_uploads 两个卷，数据还在；加上 -v 会删除这些卷，数据库数据一并消失。文档警告：除非你本来就打算抹掉整个实例，否则不要执行 docker compose down -v。

执行备份

在 multica 仓库目录（能访问 docker-compose.selfhost.yml 的目录）执行官方给出的命令：

docker compose -f docker-compose.selfhost.yml exec -T postgres \
  pg_dump -U multica multica > multica-backup.sql && gzip multica-backup.sql

这条命令做的事：

• exec -T postgres 在运行中的 postgres 容器内执行 pg_dump，不需要在宿主机安装 PostgreSQL 客户端；
• pg_dump -U multica multica 以 multica 用户导出 multica 库，输出重定向到当前目录的 multica-backup.sql；
• && 保证只有 pg_dump 自身成功（退出码为 0）时才执行 gzip 压缩。

命令正常走完后，当前目录下应有一份 multica-backup.sql.gz。

pg_dump 陷阱：为什么不能直接管道给 gzip

一个常见的“省事”写法是把导出直接压缩：

# 错误写法：导出失败时整条管道仍然以 0 退出
docker compose -f docker-compose.selfhost.yml exec -T postgres \
  pg_dump -U multica multica | gzip > multica-backup.sql.gz

官方文档对这个陷阱的说明是：shell 报告的管道退出状态是最后一条命令（这里是 gzip）的退出码，所以即使 pg_dump 导出失败，整条管道照样以 0 退出——留下一个格式完全合法、但里面什么都没有的 20 字节压缩包（文档中给出的失败产物示例）。你以为备份成功，文件里实际没有任何数据。

先重定向到 .sql 文件再压缩的写法正是为了规避这一点：pg_dump 自己的退出码成为整条命令的判定依据，导出失败时 && 之后的 gzip 根本不会执行，也就不会产出一个看起来正常的空压缩包。

据此判断备份是否成功：按正确写法执行后，如果命令链未走到 gzip（出现非零退出码），说明导出失败，先检查 pg_dump 的报错（例如用户名/库名与 .env 不一致），修复后重新执行，不要归档任何“半成品”压缩包。

备份时机与边界

• 升级前先备份。 官方把这条备份命令放在升级流程（docker compose pull + up -d）之前的位置，原因就是迁移 forward-only，没有回滚命令。
• Kubernetes 部署的对照边界。 如果你用的是 Helm 部署，数据在 PVC 中：helm -n multica uninstall multica 保留 PVC 与 Secret，而 kubectl delete namespace multica 会删除包括 PostgreSQL 数据和 uploads 在内的一切（见 SELF_HOSTING.md 的 Tearing down 一节）。本文的 docker compose exec 导出路径只覆盖 Docker Compose 部署，K8s 部署文档未给出对应的导出命令。
• 官方文档目前只给出备份命令，没有提供从 dump 文件恢复的操作流程；本文覆盖备份这一侧。