Debian 环境下 Swagger 备份与恢复指南
一、先明确要备份的内容
- Swagger UI / Swagger Editor 静态站点目录：前端文件、主题、插件、自定义配置等，常见路径如 /usr/share/nginx/html、/var/www/swagger-ui、/opt/swagger-ui 或 /etc/swagger-ui（实际以你的部署为准）。
- 后端生成的 OpenAPI 规范文件：项目中的 swagger.json / swagger.yaml，或通过后端 /api-docs 端点导出的 JSON。
- 容器化部署的数据卷：若使用 Docker，需备份挂载的配置与静态资源卷。
- 浏览器端本地数据：仅当文档在浏览器侧做过个性化设置（如 localStorage/OAuth2 回调状态）时才需要，属于可选。
以上分类与路径示例可参考实际部署实践与工具文档说明。
二、手动备份步骤
- 备份后端或项目中的 OpenAPI 文件
- 直接复制本地文件：
sudo cp /path/to/swagger.json /path/to/backup/
sudo cp /path/to/swagger.yaml /path/to/backup/
- 从运行中的服务导出：
curl http://localhost:8080/api-docs > /path/to/backup/api-docs.json
- 备份 Swagger UI / Editor 静态站点目录
- 打包目录：
sudo tar -czvf swagger-ui-backup-$(date +%Y%m%d).tar.gz /usr/share/nginx/html
或（按你的实际路径调整）：
sudo tar -czvf swagger-ui-backup-$(date +%Y%m%d).tar.gz /var/www/swagger-ui
- 容器化场景的备份（Docker）
- 备份容器数据卷内容：
docker run --rm --volumes-from swagger-ui -v $(pwd):/backup alpine tar czf /backup/swagger-ui-backup-$(date +%Y%m%d).tar.gz /usr/share/nginx/html
- 浏览器端本地数据（可选）
- 在 Swagger UI 控制台导出 localStorage 内容为 JSON 文件，便于迁移个性化设置。
以上命令与路径示例可直接套用，注意替换为你的实际目录与服务端口。
三、自动化定时备份与远程同步
- 编写备份脚本 backup.sh（示例）
- 静态站点目录备份：
#!/bin/bash
set -e
SRC=“/usr/share/nginx/html”
DST=“/backup/swagger-ui”
DATE=$(date +“%Y%m%d”)
mkdir -p “$DST/$DATE”
tar -czf “$DST/swagger-ui-$DATE.tar.gz” -C “$SRC” .
- 导出后端 OpenAPI：
curl http://localhost:8080/api-docs > “$DST/api-docs-$DATE.json”
- 可选：远程同步到备份服务器（提前配置 SSH 免密）
rsync -av --delete /backup/ user@remote:/backup/swagger/
- 赋权：chmod +x /path/to/backup.sh
- 配置 Debian 定时任务（cron）
- 每天 02:00 执行：
0 2 * * * /path/to/backup.sh
- 查看任务：crontab -l；日志可查看系统日志或脚本输出。
以上做法基于 cron + rsync/tar 的通用备份方案，适合长期稳定运行。
四、恢复步骤
- 恢复静态站点目录
- 解压覆盖：
sudo tar -xzvf swagger-ui-backup-2025XXXX.tar.gz -C /usr/share/nginx/html
- 恢复 OpenAPI 文件
- 复制回项目或供后端加载：
sudo cp /backup/swagger.json /path/to/app/
sudo cp /backup/api-docs-2025XXXX.json /path/to/app/
- 容器化恢复
- 将备份包放到目标主机，重建容器并挂载恢复后的目录或数据卷。
- 浏览器端本地数据（可选）
- 在 Swagger UI 控制台将导出的 JSON 数据逐项写回 localStorage。
- 验证
- 访问 http://:/swagger-ui/ 或 /swagger-ui/index.html，确认接口列表、模型、认证配置正常。
以上恢复路径与验证方式对应前述备份项，确保文件落位正确并能被服务加载。
五、最佳实践与安全建议
- 定期与分层：建议每日增量、每周全量、每月归档；对备份文件进行AES-256 加密并妥善设置访问权限。
- 多地存放与离线副本：至少保留一份异地/离线副本，降低单点风险。
- 校验与演练：对备份做完整性校验并定期恢复演练，记录恢复时长与问题，持续优化流程。
- 版本化配置：将 swagger-config.yaml / 自定义主题 纳入 Git 管理，便于审计与回滚。
- 变更窗口：在升级或迁移前先做一次全量备份，变更后及时做验证备份。
以上实践可显著提升备份的可靠性与可恢复性。
