Kopia 项目部署
一、功能概览
| 类别 | 说明 |
|---|---|
| 快照备份 | 每次备份生成一个时间点快照,可回溯到任意历史版本 |
| 增量与去重 | 只上传变化的数据块,跨快照、跨机器重复内容只存一份,节省空间与带宽 |
| 端到端加密 | 数据在客户端加密后才离开本机,存储端无法读取内容 |
| 压缩 | 支持多种压缩算法,可按目录或文件类型设置 |
| 多种存储后端 | 本地文件系统、网络共享、S3 兼容存储、Backblaze B2、Azure、Google Cloud、SFTP、WebDAV,以及通过 rclone 支持更多服务 |
| 策略管理 | 为目录设置备份计划、保留策略、忽略规则、压缩、前后置动作 |
| 图形界面 | 内置网页界面(服务器模式)与桌面应用,便于日常管理 |
| 仓库服务器 | 可作为集中式仓库,让多台机器的 Kopia 客户端把数据备份到这里 |
| 校验与维护 | 支持快照校验与自动维护,清理不再被引用的数据 |
二、核心概念(部署前必读)
| 概念 | 说明 |
|---|---|
| 仓库(Repository) | 保存备份数据的地方,可以是本地目录或云存储,由仓库密码加密 |
| 快照(Snapshot) | 某个目录在某个时间点的备份 |
| 策略(Policy) | 控制备份频率、保留多久、忽略哪些文件等行为的规则 |
| 来源(Source) | 备份的目录,格式为「用户@主机名:路径」 |
| 仓库服务器 | 让多个客户端共用同一个仓库的服务端模式 |
三种密码不要混淆(这是最常见的新手坑):
| 密码 | 作用 | 对应设置 |
|---|---|---|
| 仓库密码 | 加密和解锁备份数据本身 | 环境变量 KOPIA_PASSWORD |
| 网页界面密码 | 保护 Kopia 管理页面的登录 | 服务器用户名与服务器密码参数 |
| 云存储访问密钥 | 访问 S3、B2 等存储服务 | 创建仓库时填写 |
仓库密码一旦丢失,数据无法恢复,没有任何找回途径。 请保存在密码管理器,并离线备份一份。
三、部署方案选择
| 方案 | 适用场景 | 说明 |
|---|---|---|
| 命令行 + 定时任务 | 服务器、NAS 的无人值守备份 | 最灵活,配合 systemd 定时器或 cron |
| Docker 运行服务器模式 | 想要网页界面统一管理 | 本文重点,适合备份 Docker 主机与家庭服务器 |
| 桌面应用 | 个人电脑备份 | 图形界面,适合 Windows、macOS、Linux 桌面 |
| 仓库服务器 | 多台机器备份到同一处 | 客户端通过服务地址连接,集中管理 |
四、环境要求
- Linux、macOS 或 Windows 均可,本文以 Linux + Docker 为主
- Docker Engine 与 Docker Compose 插件
- 内存 512MB 以上,备份大目录时 CPU 与内存占用会升高
- 备份目标存储:本地磁盘(建议不要与源数据同盘)、NAS 或云存储账号
- 默认服务端口:51515
五、Docker Compose 部署(服务器模式 + 网页界面)
5.1 创建目录
mkdir -p ~/kopia/{config,cache,logs,repository,tmp}
cd ~/kopia
5.2 编写 .env
# .env
KOPIA_PASSWORD=请替换为强仓库密码
KOPIA_SERVER_USERNAME=admin@kopia
KOPIA_SERVER_PASSWORD=请替换为网页界面密码
注意:KOPIA_PASSWORD 是仓库密码,必须与创建或连接仓库时使用的密码一致,否则容器会在启动时反复报错重启。网页界面密码是另一个独立的密码。
5.3 编写 docker-compose.yml
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
hostname: kopia-server
restart: unless-stopped
user: "0:0"
command:
- server
- start
- --disable-csrf-token-checks
- --insecure
- --address=0.0.0.0:51515
- --server-username=${KOPIA_SERVER_USERNAME}
- --server-password=${KOPIA_SERVER_PASSWORD}
ports:
- "127.0.0.1:51515:51515"
environment:
KOPIA_PASSWORD: ${KOPIA_PASSWORD}
TZ: Asia/Shanghai
volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs
- ./repository:/repository
# 要备份的数据,只读挂载
- /home/user:/data/home:ro
- /var/lib/docker/volumes:/data/docker-volumes:ro
要点说明:
--insecure的意思是 Kopia 自己的监听口不启用 TLS,所以端口只绑定在本机 127.0.0.1,由反向代理提供 HTTPS,不要把 51515 直接暴露到公网。--disable-csrf-token-checks在经过反向代理时通常需要,否则网页操作可能被拒绝。更严格的环境请评估其安全影响。hostname要固定设置。Kopia 以「用户@主机名」标识备份来源,主机名变了,旧快照会被视为另一台机器,保留策略也不再共用。- 要备份的目录用只读方式挂载,避免误操作改动源数据。
- 想把仓库放在容器内的 /repository,请确认该目录对应的是不同于源数据的物理磁盘。
- 镜像标签建议固定到具体版本号,升级时再手动修改。
5.4 启动与首次使用
docker compose up -d
docker compose logs -f kopia
通过反向代理(见第七章)或本机隧道访问网页界面,用 .env 中设置的服务器用户名与密码登录。第一次会提示选择仓库类型,可选「创建新仓库」或「连接已有仓库」。
六、创建仓库
6.1 本地文件系统仓库
网页界面选择「Local Directory」,路径填容器内的 /repository,输入仓库密码。也可以用命令行:
docker compose exec kopia kopia repository create filesystem \
--path /repository --password "你的仓库密码"
6.2 S3 兼容对象存储
docker compose exec kopia kopia repository create s3 \
--bucket 存储桶名称 \
--prefix kopia/ \
--access-key 访问密钥ID \
--secret-access-key 访问密钥 \
--region 区域 \
--password "你的仓库密码"
使用非 AWS 的 S3 兼容服务时,另需通过 endpoint 参数填写服务地址(只填主机名,按服务商要求设置)。
建议:
- 云存储的访问密钥只授予该存储桶的读写权限,不要使用主账号密钥。
- 有条件时给存储桶开启版本控制或对象锁定,防止被误删或勒索软件加密后同步覆盖。
- 仓库不要放在与源数据同一块磁盘上,否则磁盘损坏时备份和原数据一起丢失。
6.3 其他后端
SFTP、WebDAV、Backblaze B2、Azure、Google Cloud 等后端的创建方式类似,请参阅官方文档中对应的子命令参数。
七、反向代理与 HTTPS
Caddy 示例:
backup.你的域名 {
encode zstd gzip
reverse_proxy 127.0.0.1:51515
}
安全建议:
- 管理界面能读取和恢复你的全部备份,务必使用强密码并限制访问来源,或仅在内网、VPN 下使用。
- 如果不需要远程管理,直接用 SSH 隧道转发本机端口访问,不对外暴露。
八、设置备份策略
在网页界面的「Policies」中为目录创建策略:
| 设置项 | 建议 |
|---|---|
| 备份计划 | 每天一次,业务低峰时段运行;重要数据可提高频率 |
| 保留策略 | 按需保留每日、每周、每月快照,并保留最近若干份,避免无限增长 |
| 压缩 | 选择速度较快的压缩算法,已压缩的媒体文件收益不大 |
| 忽略规则 | 排除缓存、临时文件、虚拟环境、下载目录等无需备份的内容 |
| 前后置动作 | 如备份数据库前先导出转储文件,需要在启动参数中启用动作功能 |
关于数据库备份:直接备份正在运行的数据库文件可能得到不一致的副本。推荐先用数据库自带工具导出转储文件,再让 Kopia 备份导出结果,或在备份前暂停相关容器。
使用命令行设置全局策略的示例:
kopia policy set --global --compression=zstd-fastest \
--keep-latest=3 --keep-daily=14 --keep-monthly=12
九、创建与恢复快照
9.1 手动创建快照
docker compose exec kopia kopia snapshot create /data/home
docker compose exec kopia kopia snapshot list
9.2 恢复
网页界面的「Snapshots」中可以浏览快照、下载单个文件,或恢复整个目录。命令行示例:
docker compose exec kopia kopia restore 快照ID /tmp/restore-test
9.3 校验
docker compose exec kopia kopia snapshot verify
9.4 恢复演练(强烈建议)
- 选一个有代表性的目录,恢复到一个临时位置。
- 对比关键文件的内容是否一致,能否正常打开。
- 在另一台没有安装过 Kopia 的机器上,只凭仓库位置和仓库密码连接仓库并恢复一次,确认真正的灾难恢复流程可行。
- 每隔一段时间重复演练。
十、仓库服务器模式(多机备份,可选)
让其他机器的 Kopia 客户端把数据备份到这台服务器上:
- 在服务器上为每个客户端添加用户(用户名格式为「用户@主机名」):
docker compose exec kopia kopia server users add 用户名@客户端主机名
- 为服务器启用 TLS 并记录证书指纹(官方文档对仓库服务器有专门说明,客户端连接时需要核对指纹,防止中间人攻击)。
- 客户端连接:
kopia repository connect server --url=服务地址 --server-cert-fingerprint=证书指纹
- 客户端各自创建和管理快照。
仓库服务器配置相对复杂,涉及 TLS、用户管理和访问控制,建议先阅读官方的仓库服务器文档,并在测试环境验证。
十一、不用 Docker 的命令行方案(可选)
适合服务器和 NAS 的无人值守备份,用 systemd 定时器驱动。
备份脚本示例(保存为可执行文件,如 /usr/local/bin/kopia-backup.sh):
#!/bin/bash
set -euo pipefail
export KOPIA_PASSWORD="你的仓库密码"
# 连接仓库(首次已创建)
kopia repository connect filesystem --path /mnt/backup/kopia-repo
# 备份目录
for dir in /etc /var/www /home; do
[ -d "$dir" ] && kopia snapshot create "$dir"
done
kopia repository disconnect
安全提醒:脚本中含有仓库密码,应设置严格权限(仅 root 可读),或改用环境文件、密钥管理方式传入。
再创建 systemd 服务与定时器,设置为每天运行。配置完成后手动触发一次测试,并查看日志确认成功。
十二、升级与维护
cd ~/kopia
docker compose pull
docker compose up -d
docker image prune
建议:
- 升级前先阅读发布说明。仓库格式有版本,新版本客户端升级仓库格式后,旧版本可能无法再读取,多台机器共用仓库时请统一升级。
- 固定镜像版本,不要无意中被动升级。
- 定期检查快照列表,确认定时备份真的在运行。
- 关注仓库空间占用,调整保留策略。
- 维护任务(清理无引用数据)由 Kopia 自动执行,保持服务器运行即可,也可手动触发。
备份你的备份配置
需要保存的内容:
| 内容 | 说明 |
|---|---|
| 仓库密码 | 最关键,丢失即无法恢复 |
| 仓库位置与存储访问信息 | 云存储的桶名、区域和密钥等 |
| config 目录 | 仓库连接配置与策略 |
| Compose 文件与 .env | 部署配置 |
遵循 3-2-1 原则:3 份副本(含原数据)、2 种介质、1 份异地。仓库放在云上或异地磁盘,本身就满足异地要求。
十三、常见问题排查
| 现象 | 可能原因 | 处理办法 |
|---|---|---|
| 容器反复重启,提示仓库密码无效 | KOPIA_PASSWORD 与仓库实际密码不一致,或首次启动尚未创建仓库 | 核对仓库密码;先用命令行创建仓库,或按需调整启动方式 |
| 网页界面能登录但操作被拒绝 | 经反向代理后 CSRF 校验失败 | 按第五章配置相关参数,并确认代理转发正确 |
| 把服务器密码当成仓库密码 | 两种密码混淆 | 分清两者:前者登录页面,后者解锁数据 |
| 换了主机名后找不到旧快照 | 来源标识是「用户@主机名」 | 固定 hostname,或在界面里查看旧主机名下的快照 |
| 恢复得到的数据库损坏 | 备份时数据库正在写入 | 先导出转储再备份,或暂停服务后备份 |
| 仓库越来越大 | 保留策略过宽,或备份了不需要的数据 | 收紧保留策略,增加忽略规则,运行维护 |
| 云存储报权限错误 | 访问密钥权限不足或区域填错 | 检查桶权限、区域与前缀 |
| 备份速度很慢 | 带宽或小文件过多、压缩太重 | 换更快的压缩算法,调整并发,考虑在低峰运行 |
| 无法挂载快照为文件系统 | 缺少 FUSE 设备或权限 | 给容器增加 FUSE 设备与必要能力,仅在确有需要时开启 |
| 校验提示数据缺失 | 存储端数据被改动或损坏 | 检查存储健康状态,必要时从其他副本恢复 |
十四、命令速查
# 启动 / 停止 / 日志
docker compose up -d
docker compose down
docker compose logs -f kopia
# 创建本地仓库
docker compose exec kopia kopia repository create filesystem --path /repository --password "仓库密码"
# 连接已有仓库
docker compose exec kopia kopia repository connect filesystem --path /repository
# 创建与查看快照
docker compose exec kopia kopia snapshot create /data/home
docker compose exec kopia kopia snapshot list
# 恢复与校验
docker compose exec kopia kopia restore 快照ID /tmp/restore-test
docker compose exec kopia kopia snapshot verify
# 设置全局策略
docker compose exec kopia kopia policy set --global --keep-latest=3 --keep-daily=14 --keep-monthly=12
# 升级
docker compose pull && docker compose up -d
- 点赞
- 收藏
- 关注作者
评论(0)