Backup and restore
This page explains how to back up the database and attachments daily with the bundled scripts/backup.sh, and how to restore with scripts/restore.sh.
What to back up
| Content | Location | Backed up by the script |
|---|---|---|
| PostgreSQL database | GONGGONG_DATABASE_URL | Yes, pg_dump custom format |
| Attachments | $GONGGONG_DATA_DIR/attachments/ | Yes, as a tar.gz |
| Data encryption key | GONGGONG_DATA_KEY | No; keep it safe separately |
| Managed artifacts (files of prototypes, canvases, etc.) | $GONGGONG_DATA_DIR/artifacts/ | No; back up yourself if needed |
| Uploaded avatars | $GONGGONG_DATA_DIR/avatars/ | No; back up yourself if needed |
| Force-synced file contents | $GONGGONG_DATA_DIR/sync/ | No; back up yourself if needed |
| Base-branch mirrors | $GONGGONG_DATA_DIR/mirrors/ | No; re-fetched from the repository if lost |
| Client installers | $GONGGONG_DATA_DIR/downloads/ | No; can be uploaded again |
Other contents of the data directory
backup.sh only archives attachments/. If your team uses artifacts or force sync, we recommend adding artifacts/, avatars/, and sync/ to your own file backups too (for example, a periodic rsync to a backup disk). They are also encrypted with GONGGONG_DATA_KEY.
Keep the key and the backups apart
Attachments, diffs, and run details are encrypted with GONGGONG_DATA_KEY. Without the key, that part of the backup can't be decrypted; but if the key sits next to the backups, anyone who gets the backups can decrypt everything. Keep the key separately in a secrets manager or on offline media.
Daily backups
Environment variables read by the script:
| Variable | Description |
|---|---|
GONGGONG_BACKUP_DIR | Backup output directory (required) |
GONGGONG_DATABASE_URL | Database connection string; if unset, built from GONGGONG_DB / GONGGONG_PG_PORT, same as the server |
GONGGONG_DATA_DIR | Server data directory, default .gonggong-dev/data |
You need to be able to run pg_dump (the same major version as the server's PostgreSQL, or newer).
Run it once by hand:
cd /srv/gonggong
sudo -u gonggong env \
GONGGONG_BACKUP_DIR=/var/backups/gonggong \
GONGGONG_DATA_DIR=/var/lib/gonggong \
GONGGONG_DATABASE_URL='postgres://gonggong:<密码>@127.0.0.1:5432/gonggong' \
bash scripts/backup.sh(<密码> = the database password.) Each run produces a pair of files named by timestamp:
gonggong-20260923-033000.dump
attachments-20260923-033000.tar.gzThe script keeps the latest 7 backups, plus the latest backup of each of the last 7 dates that have backups (set GONGGONG_BACKUP_KEEP to change the 7, e.g. lower it when disk is tight), and deletes the rest automatically. So a backup taken before a release isn't pushed out by later backups the same day. An attachment archive is kept or deleted together with the database backup of the same timestamp, and files whose names weren't generated by the script are left alone (the script doesn't read the system parameter 「服务器备份(每日)保留」 (Keep daily server backups for)). Files are first written as .part temporaries and renamed when complete, so a failure midway never leaves a half-written backup that looks complete.
Run it daily at 3:30 a.m. with cron:
30 3 * * * GONGGONG_BACKUP_DIR=/var/backups/gonggong GONGGONG_DATA_DIR=/var/lib/gonggong GONGGONG_DATABASE_URL=postgres://gonggong:<密码>@127.0.0.1:5432/gonggong /srv/gonggong/scripts/backup.sh >> /var/log/gonggong-backup.log 2>&1TIP
Ideally put the backup directory on a separate disk and sync it off-site regularly. Also check the backup directory's access permissions: message bodies, run cards, and so on are in plaintext in the backups.
With a Docker Compose deployment
backup.sh needs direct access to the database and the data directory, but in a compose deployment the database port isn't published and the data lives in Docker volumes. You can export the database with docker compose exec -T db pg_dump -U gonggong --format=custom gonggong > gonggong-<时间戳>.dump (<时间戳> = timestamp) and back up the data volume; the data.key in the data volume is the encryption key and must likewise be kept apart from the backups.
Restore
restore.sh restores the backup with a given timestamp into the currently configured database and data directory, using the same environment variables as the backup.
- Stop the server:bash
sudo systemctl stop gonggong - Make sure the target database exists (on a new machine, first create an empty database as in Deploy from source).
- List the available backups and restore:bash
ls /var/backups/gonggong sudo -u gonggong env \ GONGGONG_BACKUP_DIR=/var/backups/gonggong \ GONGGONG_DATA_DIR=/var/lib/gonggong \ GONGGONG_DATABASE_URL='postgres://gonggong:<密码>@127.0.0.1:5432/gonggong' \ bash scripts/restore.sh 20260923-033000 - Make sure the server uses the
GONGGONG_DATA_KEYfrom the time of the backup, then start it:bashsudo systemctl start gonggong
What the restore does:
- The database is restored with
pg_restore --clean --if-existsin a single transaction; objects with the same names in the target database are replaced, and any error rolls back the whole thing. - The attachments directory is deleted entirely first, then extracted from the backup.
- If there's no attachment backup for that timestamp (no attachments existed yet), only the database is restored.
WARNING
Restoring overwrites the current data; messages, runs, and attachments after the backup point are lost. Daemon bindings on members' machines are stored in the database, so after restoring an older backup, machines bound after that point need to be bound again.