OpenUptime

Backup and restore

Everything OpenUptime stores lives in one Postgres database. Back that up, keep your .env next to it, and practise a restore before you need one. The commands below are for the Docker deployment from Self-host; the service is called postgres and the database, user and name are all openuptime.

Back up

docker compose exec -T postgres pg_dump -U openuptime -Fc openuptime > openuptime-$(date +%F).dump
  • -Fc writes the compressed custom format, which pg_restore can restore selectively. -T keeps Docker from adding terminal characters to the file.
  • Check that the file is readable: pg_restore --list openuptime-2026-10-17.dump | head (or run it through docker compose exec -T postgres pg_restore --list < file if you have no local Postgres tools).
  • Copy the file off the machine. A backup on the same disk does not survive the disk.
  • Keep .env as well, in a safe place. BETTER_AUTH_SECRET must be the same after a restore, or signed-in sessions and API keys stop working.
  • Schedule it, for example a daily cron job that runs the command above and deletes dumps older than you need.

Restore

A restore replaces data. Work through it in order, and stop if a step does not give the result described.

  1. Try it on a scratch database first. This proves the dump is good without touching live data:
    docker compose exec postgres createdb -U openuptime openuptime_check
docker compose exec -T postgres pg_restore -U openuptime -d openuptime_check --no-owner < openuptime-2026-10-17.dump
docker compose exec postgres psql -U openuptime -d openuptime_check -c 'select count(*) from monitor'
docker compose exec postgres dropdb -U openuptime openuptime_check
  2. Stop the app so nothing writes while you restore: docker compose stop openuptime. Postgres keeps running.
  3. Take one more dump of the current state with the backup command, under another file name. If the restore was a mistake, this is the way back.
  4. Restore over the live database. --clean --if-exists drops each object before recreating it, so this overwrites what is there:
    docker compose exec -T postgres pg_restore -U openuptime -d openuptime --clean --if-exists --no-owner < openuptime-2026-10-17.dump
  5. Start the app with docker compose start openuptime. Migrations newer than the dump are applied on start. Sign in and check your monitors and recent check history.

On a new server

Install Docker, copy your .env and docker-compose.yml, then docker compose up -d postgres and wait until it is healthy (docker compose ps). Restore with the command in step 4, then docker compose up -d. The empty database already exists, so --clean --if-exists is harmless there.

Good to know

  • A restore returns the database to the moment of the dump. Checks that ran since then are not in it, and incidents opened or resolved since then are lost.
  • Use a pg_restore of the same major Postgres version as the server, or newer. The Docker image pins the version, so using the container's own tools, as above, is always right.
  • On a hosted Postgres (Neon, Supabase, RDS) use the provider's backups or point-in-time recovery; the same pg_dump -Fc works against its connection string.

备份与恢复

OpenUptime 的所有数据都存放在一个 Postgres 数据库里。请备份它，把 .env 一并保存，并在真正需要之前演练一次恢复。下面的命令适用于自托管指南里的 Docker 部署：服务名为 postgres，数据库、用户名和库名都是 openuptime。

备份

docker compose exec -T postgres pg_dump -U openuptime -Fc openuptime > openuptime-$(date +%F).dump
  • -Fc 生成压缩的 custom 格式，pg_restore 可以按需恢复。-T 避免 Docker 往文件里混入终端字符。
  • 确认文件可读：pg_restore --list openuptime-2026-10-17.dump | head（本机没有 Postgres 工具时，可用 docker compose exec -T postgres pg_restore --list < 文件）。
  • 把文件拷贝到机器之外。放在同一块磁盘上的备份挡不住磁盘损坏。
  • 同时妥善保存 .env。恢复后 BETTER_AUTH_SECRET 必须保持不变，否则已登录的会话和 API 密钥会失效。
  • 设为定时任务，例如每天用 cron 执行上面的命令，并删除过旧的备份。

恢复

恢复会覆盖数据。请按顺序操作，任何一步结果与描述不符就先停下。

  1. 先在临时数据库里试一次。这样不碰线上数据也能证明备份可用：
    docker compose exec postgres createdb -U openuptime openuptime_check
docker compose exec -T postgres pg_restore -U openuptime -d openuptime_check --no-owner < openuptime-2026-10-17.dump
docker compose exec postgres psql -U openuptime -d openuptime_check -c 'select count(*) from monitor'
docker compose exec postgres dropdb -U openuptime openuptime_check
  2. 停止应用，避免恢复期间有写入：docker compose stop openuptime。Postgres 继续运行。
  3. 再备份一次当前状态，用另一个文件名。如果恢复是个错误，可以靠它退回。
  4. 恢复到线上数据库。--clean --if-exists 会先删除每个对象再重建，所以会覆盖现有数据：
    docker compose exec -T postgres pg_restore -U openuptime -d openuptime --clean --if-exists --no-owner < openuptime-2026-10-17.dump
  5. 启动应用：docker compose start openuptime。比备份更新的迁移会在启动时自动执行。登录后检查监控项和最近的检测记录。

恢复到新服务器

安装 Docker，复制 .env 和 docker-compose.yml，运行 docker compose up -d postgres 并等它变为 healthy（docker compose ps）。用第 4 步的命令恢复，再 docker compose up -d。空数据库已经存在，此时 --clean --if-exists 不会有副作用。

需要了解

  • 恢复会把数据库退回到备份那一刻：之后产生的检测记录不在其中，之后开启或解决的事件会丢失。
  • pg_restore 的主版本要不低于服务器的 Postgres 版本。Docker 镜像固定了版本，所以像上面那样使用容器自带的工具总是正确的。
  • 使用托管 Postgres（Neon、Supabase、RDS）时，请用服务商自己的备份或时间点恢复；同样的 pg_dump -Fc 也可以对它的连接串使用。

Last updated 2026-10-17最后更新：2026-10-17