跳到主要内容

备份与恢复

PlantPulse Studio 使用一个备份脚本和一个恢复脚本处理整个状态。 所有命令均在安装目录(/opt/kopens/plantpulse-studio-docker)中执行。

备份内容​

一个备份文件(dist/backup-<date>.tar.gz)中包含以下所有内容。

对象内容
PostgreSQL 完整转储用户账户 · 对话历史 · 观察器 · 通知已读状态 · 技能 · 部署历史 · 审计日志
工作区(workspaces/)按项目划分的实际源代码 · 聊天附件
构建产物(builds/)已部署应用的各版本（回滚时需要）
状态目录(state/)settings.json（环境配置） · 审计/使用量日志 · 自定义模板 · 品牌标识

PostgreSQL 的数据目录本身不包含在归档内——因为它被 SQL 转储取代。

备份文件是敏感资料

归档中包含所有用户的工作区，如果是旧安装迁移而来的， settings.json中可能残留 API 密钥。

  • 脚本会将备份文件权限设为 600（仅所有者可读），将 dist/ 目录权限设为 700。
  • 转移到外部介质或其他服务器时，也请保持此权限设置。 （使用诸如 scp -p、rsync -a、tar -p 等保留权限的选项）
  • 若转移出公司外部，建议另行加密。

执行备份​

cd /opt/kopens/plantpulse-studio-docker
bash bin/backup.sh
▶ PostgreSQL 덤프
▶ 파일 상태 아카이브(postgres 데이터 제외 — 덤프로 대체)
-rw------- 1 root root 78M ... dist/backup-20260728-031501.tar.gz
✅ 백업 완료 (보존 14개)
  • 结果文件：dist/backup-<YYYYMMDD-HHMMSS>.tar.gz
  • 保留策略：仅保留最近 14 个，旧文件自动删除（可通过 BACKUP_KEEP 调整）。
  • 必须能够连接外部 PostgreSQL 才能进行转储。
BACKUP_KEEP=30 bash bin/backup.sh     # 이번 실행부터 30개 보존
升级前务必执行手动备份

在镜像升级或大幅变更配置之前，请先运行一次 bash bin/backup.sh。

安装自动备份（推荐）​

安装 cron，使备份每天凌晨 03:30 运行。需要 root 权限。

sudo bash bin/install-backup-cron.sh
[backup-cron] 설치 완료 — 스케줄: '30 3 * * *', 보존 14개, 로그: dist/backup.log

如需更改时间或保留数量，

sudo BACKUP_CRON="0 4 * * *" BACKUP_KEEP=30 bash bin/install-backup-cron.sh

卸载时，

sudo bash bin/install-backup-cron.sh remove

可通过日志确认运行状态。

tail -50 /opt/kopens/plantpulse-studio-docker/dist/backup.log
ls -lh /opt/kopens/plantpulse-studio-docker/dist/backup-*.tar.gz

推荐运维周期​

周期任务
每日自动备份（cron） — 保留 14 天
每周将最新备份的 1 个复制到其他服务器或介质（保持权限）
每月检查 dist/ 容量和磁盘余量
每季度DRYRUN=1 恢复演练 — 见下文
升级前手动备份 1 次
只有确认“能恢复”的备份才算是备份

即使备份文件每天都在累积，实际能否恢复，不试一下是无法知道的。 请每季度进行一次演练。该演练是非破坏性的，因此在运行期间执行也是安全的。

恢复演练（非破坏性）​

仅检查归档结构和数据库可达性，不做任何修改。

DRYRUN=1 bash bin/restore.sh                 # 최신 백업 대상
DRYRUN=1 bash bin/restore.sh dist/backup-20260712-191858.tar.gz
▶ 아카이브 검증
  ppstudio.sql 12M · files.tar.gz 66M
▶ DRYRUN — DB 도달성만 확인
  ✅ DB 도달 OK
✅ DRYRUN 통과 — 실제 복구는 DRYRUN 없이 실행

执行恢复​

恢复是破坏性操作

当前数据库内容和整个数据目录将被覆盖为备份时的状态。 恢复之后创建的项目、对话和部署将丢失。

cd /opt/kopens/plantpulse-studio-docker

bash bin/restore.sh                                    # 최신 백업으로 복구
bash bin/restore.sh dist/backup-20260712-191858.tar.gz # 특정 시점으로 복구

在确认提示符处输入 restore 才能继续。

⚠ 현재 DB 와 /var/lib/pp-studio 파일 상태를 이 백업으로 덮어씁니다: dist/backup-...
계속하려면 'restore' 를 입력하세요:

脚本执行的顺序如下。

  1. 验证归档结构（确认转储和文件归档存在）
  2. 将当前文件状态自动备份到 dist/pre-restore-<date>.tar.gz
  3. 停止堆栈
  4. 恢复数据目录 → 恢复数据库
  5. 启动堆栈 → 检查健康状态

若要在自动化脚本中不带提示符运行，

FORCE=1 bash bin/restore.sh dist/backup-20260712-191858.tar.gz

恢复后健康检查未通过​

bash bin/logs.sh          # 서버 로그 확인
bash bin/status.sh

如需回滚，可依据步骤2创建的备份副本重新恢复。但请注意，备份副本仅包含文件状态（不包含数据库）。

bash bin/restore.sh dist/pre-restore-20260728-104233.tar.gz

迁移到其他服务器​

  1. 在新服务器上安装相同版本的堆栈（安装 或 隔离网络安装）。
  2. 将现有服务器的 .env 复制到新服务器（保持权限 600）。
  3. 将备份归档复制到新服务器的 dist/（保持权限 600）。
  4. 执行恢复。
cd /opt/kopens/plantpulse-studio-docker
DRYRUN=1 bash bin/restore.sh dist/backup-20260728-031501.tar.gz   # 먼저 리허설
bash bin/restore.sh dist/backup-20260728-031501.tar.gz
如果域名变更

迁移后如果访问地址发生变化，所有用户需要登出后重新登录一次—— 因为登录 Cookie 是签发时的主机专用，若保持不变，数据请求会返回 401。 详细信息请参考 域名与反向代理。

磁盘管理​

由于备份会完整包含工作区和构建产物，随着项目增多，备份会不断变大。

du -sh /opt/kopens/plantpulse-studio-docker/dist
du -sh /var/lib/pp-studio/*
df -h /var/lib/pp-studio
  • 要减少保留数量，请使用 BACKUP_KEEP 值重新安装 cron。
  • 已部署应用的旧版本，每个项目默认最多保留 10 个，超出部分自动清理 （当前正在服务的版本始终保留）。

相关文档​