跳到主要内容

备份与恢复

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 个，超出部分会自动清理 (当前正在服务的版本始终保留)。

相关文档​