Kopia 项目部署

举报
yd_229065422 发表于 2026/11/16 12:05:45 2026/11/16
【摘要】 一、功能概览类别说明快照备份每次备份生成一个时间点快照,可回溯到任意历史版本增量与去重只上传变化的数据块,跨快照、跨机器重复内容只存一份,节省空间与带宽端到端加密数据在客户端加密后才离开本机,存储端无法读取内容压缩支持多种压缩算法,可按目录或文件类型设置多种存储后端本地文件系统、网络共享、S3 兼容存储、Backblaze B2、Azure、Google Cloud、SFTP、WebDAV...

一、功能概览

类别 说明
快照备份 每次备份生成一个时间点快照,可回溯到任意历史版本
增量与去重 只上传变化的数据块,跨快照、跨机器重复内容只存一份,节省空间与带宽
端到端加密 数据在客户端加密后才离开本机,存储端无法读取内容
压缩 支持多种压缩算法,可按目录或文件类型设置
多种存储后端 本地文件系统、网络共享、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 恢复演练(强烈建议)

  1. 选一个有代表性的目录,恢复到一个临时位置。
  2. 对比关键文件的内容是否一致,能否正常打开。
  3. 在另一台没有安装过 Kopia 的机器上,只凭仓库位置和仓库密码连接仓库并恢复一次,确认真正的灾难恢复流程可行。
  4. 每隔一段时间重复演练。

十、仓库服务器模式(多机备份,可选)

让其他机器的 Kopia 客户端把数据备份到这台服务器上:

  1. 在服务器上为每个客户端添加用户(用户名格式为「用户@主机名」):
docker compose exec kopia kopia server users add 用户名@客户端主机名
  1. 为服务器启用 TLS 并记录证书指纹(官方文档对仓库服务器有专门说明,客户端连接时需要核对指纹,防止中间人攻击)。
  2. 客户端连接:
kopia repository connect server --url=服务地址 --server-cert-fingerprint=证书指纹
  1. 客户端各自创建和管理快照。

仓库服务器配置相对复杂,涉及 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

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。