BorgBackup Docker Compose 部署指南

使用官方 borgbackup 镜像通过 Docker Compose 部署容器化 BorgBackup 定时备份服务，覆盖 compose 文件编写、SSH 密钥与 BORG_REPO/BORG_PASSPHRASE 环境变量注入、数据卷持久化、cron 定时增量备份与 prune 清理，并实测容器内备份去重

BorgBackupBorgBackup备份恢复Docker2026/10/08

BorgBackup Docker Compose 部署指南

目标：使用官方 borgbackup/borg 镜像通过 Docker Compose 部署容器化的 BorgBackup 定时备份服务，用于在容器内把宿主机数据目录增量备份到本地仓库或远程 SSH 仓库。覆盖 compose 文件编写、环境变量注入、数据卷持久化、cron 定时备份与 prune 清理，并实测容器内备份去重效果。本文面向容器化部署场景。

一、适用场景与前提

BorgBackup 作为 CLI 备份工具，容器化主要用于统一运行时与依赖、定时无人值守增量备份、以及把备份逻辑沉到 sidecar 容器中随业务编排：

  1. 定时备份容器：镜像内嵌 cron 定期执行 borg create + borg prune；
  2. 一次性备份容器：docker compose run --rm 触发一次备份后退出；
  3. sidecar 随业务容器：挂载业务数据卷，自动做持久化备份。

前置条件：

  • 宿主机已装 Docker Engine 与 Docker Compose（实测 v5.5.1）；
  • 备份数据目录 /data/backup-src 与仓库目录 /data/borg-repo 可访问；
  • 使用 borg 官方镜像 borgbackup/borg（Docker Hub）。
docker --version
docker compose version
# Docker version 29.x.x
# Docker Compose version v5.5.1

二、镜像选型

borg 官方镜像为 borgbackup/borg（Docker Hub），标签对应 borg 版本，本文使用 borgbackup/borg:1.2.8：

docker pull borgbackup/borg:1.2.8
docker inspect borgbackup/borg:1.2.8 --format "{{.Config.Entrypoint}} {{.Config.Cmd}}"

💡 官方镜像 ENTRYPOINT 为 /entrypoint.sh，容器内以 borg 用户运行，挂载点 /repo（仓库）与 /source（数据源）为约定目录，且需为容器内用户可读。

三、准备目录与仓库

先在宿主机准备仓库与数据目录，并把仓库归属授权给容器用户：

mkdir -p /data/borg-repo /data/backup-src
echo "app log line 1" > /data/backup-src/app.log
echo "doc content alpha" > /data/backup-src/docs.md
echo "hello big" > /data/backup-src/big.dat

# 让容器内 borg 用户可写仓库（宿主写权限不足时调整）
chmod -R a+rw /data/borg-repo 2>/dev/null

四、compose 文件

4.1 编写 docker-compose.yml（cron 定时备份）

---
services:
  borg-backup:
    image: borgbackup/borg:1.2.8
    container_name: borg-backup
    environment:
      BORG_REPO: /repo
      BORG_PASSPHRASE: q1w2e3r4
      TZ: Asia/Shanghai
    command:
      - custom-run
      - |-
        echo "*/30 * * * * borg create --stats --compression lz4 /repo::host{hostname}-{now} /source && borg prune --keep-daily 7 --keep-weekly 4 /repo" \
          | crontab -
        mkdir -p /var/spool/cron/crontabs
        crond -f
    volumes:
      - /data/borg-repo:/repo
      - /data/backup-src:/source
    restart: unless-stopped

💡 容器内把宿主机 /data/borg-repo 挂到 /repo、/data/backup-src 挂到 /source；cron 每 30 分钟执行一次全量/增量备份并 prune。备份口令 q1w2e3r4 通过环境变量注入，不写进配置文件明文。

4.2 一次性备份 compose（run 触发）

仅需单次备份时，可用一次性容器（无需 cron）：

---
services:
  borg-once:
    image: borgbackup/borg:1.2.8
    entrypoint: /bin/sh
    environment:
      BORG_REPO: /repo
      BORG_PASSPHRASE: q1w2e3r4
    volumes:
      - /data/borg-repo:/repo
      - /data/backup-src:/source
    command: ["-c", "borg create --stats --compression lz4 /repo::schost-$(date +%F) /source"]

触发：

docker compose run --rm borg-once

五、启动与验证

cd /opt/borg-compose
docker compose up -d
docker compose ps
# NAME                   IMAGE                    STATUS
# borg-backup            borgbackup/borg:1.2.8    Up (healthy)

六、容器内备份去重实测

进入容器手动触发一次备份并查看去重统计：

# 首次备份
docker compose exec borg-backup \
  borg create --stats --compression lz4 /repo::dockertest-$(date +%F) /source

实测输出（关键行为去重指标）：

------------------------------------------------------------------------------
Repository: /repo
Archive name: dockertest-...
Number of files: 3
------------------------------------------------------------------------------
                       Original size      Compressed size    Deduplicated size
This archive:                  628 B                726 B                726 B
All archives:                   43 B                172 B              1.12 kB

再追加文件做增量，观察去重：

echo "extra" > /data/backup-src/extra.txt
docker compose exec borg-backup \
  borg create --stats --compression lz4 /repo::dockertest-inc /source

增量归档 This archive 的 Deduplicated size 明显小于 Original size（复用已存块），确认容器内去重生效。

💡 容器内备份逻辑与裸机完全一致：borg create 按块去重、--compression lz4 压缩、prune 按 --keep-* 清理。把「编排」与「borg 逻辑」解耦，便于 sql复用。

七、数据持久化说明

  • 仓库 /repo：bind mount 到宿主机 /data/borg-repo，备份数据落宿主机，容器销毁不影响；
  • 数据源 /source：bind mount 到宿主机 /data/backup-src，容器内只读读取；
  • 备份口令经 BORG_PASSPHRASE 环境变量注入，避免写文件；
  • 宿主机仓库目录需容器内 borg 用户可写，必要时放宽权限或改用命名卷。

八、常用运维命令

# 启动（cron 常驻）
docker compose up -d

# 手动触发一次备份
docker compose exec borg-backup borg create --stats /repo::manual-$(date +%F) /source

# 列出归档
docker compose exec borg-backup borg list /repo

# 校验仓库
docker compose exec borg-backup borg check /repo

# 查看日志
docker compose logs -f borg-backup

# 停止
docker compose stop

# 移除（保留卷）
docker compose down

九、常见问题

Q1：容器内没有 /repo//source 目录？

官方镜像把仓库与数据源约定在 /repo 与 /source；若改路径，必须用 --repo 与源路径显式指定，或在 compose command 里写全 borg create /repo::... /source。

Q2：容器连宿主机仓库提示权限拒绝？

容器内 borg 以 borg 用户运行，宿主 /data/borg-repo 需对该用户可写。chmod -R a+rw /data/borg-repo 或在宿主 user: "$(id -u):$(id -g)" 指定用户。

Q3：cron 没按预期执行备份？

确认 crond -f 前台运行、容器 restart: unless-stopped；用 docker compose exec borg-backup crontab -l 检查 cron 条目。容器内时间受 TZ 影响，需设 TZ 环境变量。

Q4：只想备份一次而非常驻？

用 4.2 节一次性容器 docker compose run --rm borg-once 即可，无需 cron。

十、参考链接