Docker 数据备份与最小恢复流程

Source: ops/01-docker-data-backup-and-restore.md

文档日期：2026-07-08 适用范围：Gitea、TS3AudioBot，以及后续部署在 Docker 中的自建服务

1. 为什么先写备份

自建服务最怕的不是容器坏掉，而是数据目录丢失。容器、镜像、compose 文件都可以重建，真正不可替代的是：

数据库
配置文件
上传文件
用户权限
cookies 或 token
自定义插件
历史日志与运行状态

因此 Docker 服务的维护核心是先确认数据放在哪里，再确认如何恢复。

2. 需要备份的内容

2.1 Gitea

当前 Gitea 使用 Docker volume：

text

gitea-data -> /data

至少需要备份：

text

<Gitea app.ini>
<Gitea 数据库文件>
<Gitea 仓库目录>
<Gitea LFS 目录>
<Gitea 日志目录>

如果使用的是 Docker volume，可以先找出 volume 路径：

bash

docker volume inspect gitea_gitea-data

也可以用临时容器导出：

bash

docker run --rm \
  -v gitea_gitea-data:/data \
  -v "$PWD":/backup \
  alpine \
  tar -czf /backup/gitea-data-$(date +%F).tar.gz -C /data .

2.2 TS3AudioBot

当前 TS3AudioBot 使用宿主机目录挂载：

text

<TS3AudioBot compose 目录>/data -> <TS3AudioBot 数据目录>

至少需要备份：

text

ts3audiobot.toml
<TS3AudioBot 权限文件>
<TS3AudioBot 数据库文件>
<Bilibili cookies 文件>
plugins/<Bilibili 命令插件>
bots/default/
logs/

推荐命令：

bash

cd <TS3AudioBot compose 目录>
tar -czf ts3audiobot-data-backup-$(date +%F).tar.gz data

3. 备份命名规则

建议统一使用：

text

服务名-data-backup-YYYY-MM-DD.tar.gz

示例：

text

gitea-data-backup-2026-07-08.tar.gz
ts3audiobot-data-backup-2026-07-08.tar.gz

如果是重大调整前的备份，可以加说明：

text

gitea-data-before-https-2026-07-08.tar.gz

4. 恢复前检查

恢复前先确认三件事：

bash

docker ps
docker compose ps
ls -lh *.tar.gz

如果要覆盖旧数据，先停止服务：

bash

docker compose down

不要在服务运行中直接覆盖数据库文件。

5. Gitea 最小恢复流程

进入 compose 所在目录：

bash

cd <Gitea compose 目录>
docker compose down

用临时容器恢复 volume：

bash

docker run --rm \
  -v gitea_gitea-data:/data \
  -v "$PWD":/backup \
  alpine \
  sh -c 'rm -rf /data/* && tar -xzf /backup/gitea-data-backup-2026-07-08.tar.gz -C /data'

重启并验证：

bash

docker compose up -d
docker compose ps
curl -I http://127.0.0.1:<Gitea Web 端口>/

公网验证：

text

http://<服务器公网 IP>:<Gitea Web 端口>/

6. TS3AudioBot 最小恢复流程

进入项目目录：

bash

cd <TS3AudioBot compose 目录>
docker compose down

恢复数据：

bash

mv data data.broken.$(date +%F-%H%M)
tar -xzf ts3audiobot-data-backup-2026-07-08.tar.gz

重建并启动：

bash

docker compose up -d --build --force-recreate
docker logs --tail=120 ts3audiobot

TeamSpeak 内验证：

text

!plugin list
!bili BV1gK4y1a7yZ

7. 定期维护建议

每次改 docker-compose.yml 前先备份。
每次改 Gitea 域名、ROOT_URL、SSH_PORT 前先备份。
每次更新 TS3AudioBot 插件、cookies、权限文件前先备份。
备份文件不要只留在服务器本机，至少复制一份到本地或私有仓库外的安全位置。

8. 最小检查清单

text

[ ] compose 文件还在
[ ] 数据目录或 volume 还在
[ ] 最近一次备份可以解压
[ ] 恢复步骤已经写进文档
[ ] 恢复后有明确验证命令
[ ] 敏感文件没有提交到公开仓库