数据、备份与升级

哪些数据需要保留

数据	内容	保留方式
数据库	账户、文件记录、公开路径、副本关系和插件配置	SQLite 可用内置备份；PostgreSQL 使用数据库工具备份
应用文件	插件包、运行设置、未完成任务所需文件	与数据库一起保存
图片内容	本地目录中的文件或远端存储对象	本地可随内置备份保存；远端另行保护
部署配置	Compose、.env、目录映射	单独保留

派生缓存可以重建。仅复制图片目录无法恢复账户、公开路径和副本关系；运行中也不要手动清空可能被任务使用的临时目录。

创建内置备份

仅 SQLite 支持，由 Owner 在 系统 页面操作。

范围	内容
包含	数据库、运行设置、插件包、上传与任务暂存文件、插件声明的本地存储目录、加密密钥
不包含	S3 等远端对象、派生缓存、Compose 与 .env

内置本地存储会声明其目录；外部插件需支持同一目录声明协议才能自动纳入备份。内置备份不是整个磁盘或应用目录的完整副本。

1. 在系统页面的备份区域点击创建备份。
2. 等待完成，确认列表中的时间和大小。
3. 下载到服务器之外的位置，并另行保存部署配置。

Docker 默认将备份保存在宿主机 ./data/backups。备份期间应用进入维护状态，等待在途请求和后台任务结束后制作快照，再恢复服务；慢任务可能延长等待。

备份包包含加密密钥和插件凭证，应作为敏感文件保存。 插件凭证在包内加密保存，但解密密钥也在同一个包中。

从内置备份恢复

1. 先备份当前部署，确认目标版本兼容。
2. 在系统页面上传备份，或选择列表中的已有备份。
3. 核对提示并确认恢复，完成后重新登录。
4. 检查存储源状态，并抽查本地和远端图片。

上传备份只会将文件加入列表，点击恢复才会进入维护状态并替换数据。

项目	恢复后的行为
数据库与应用设置	替换为备份内容，不与当前数据合并
本地图片	放入 DATA_DIR/originals/<存储源 ID>，自动更新对应存储源路径；不写回原来的外部目录
插件凭证	使用备份内的密钥解密，再用目标部署的 ENCRYPTION_KEY 重新加密
账户与登录状态	使用备份中的账户和密码；浏览器会话失效，上传令牌保留
远端图片	不恢复远端对象，也不撤销远端的删除或修改

目标部署可以使用不同的加密密钥，无需手动改成备份时的值。恢复后继续保留目标部署的密钥。

恢复前的应用数据会保留在同级的 app.before-restore-<随机 ID> 目录（Docker 默认布局）。确认恢复正常后可自行删除；原来位于应用目录之外的本地图片目录也不会自动删除。

当前要求备份包中的应用版本与目标版本一致，并检查数据库结构兼容性。相同版本号的开发提交也可能存在结构差异，不能保证任意开发提交之间互相恢复。

PostgreSQL 与手动备份

PostgreSQL 不支持上述内置备份与恢复。手动备份时：

1. 停止 Picloom，使数据库记录与本地文件不再变化。
2. 使用数据库工具备份 PostgreSQL，同时保存应用数据目录及本地存储目录。SQLite 手动备份则保存停机后的数据库与这些文件。
3. 单独保留 Compose、.env 和目录映射，再启动 Picloom。

不要直接复制运行中的 PostgreSQL 数据目录作为完整备份。手动恢复应成套还原数据库与文件，并使用对应的原 ENCRYPTION_KEY；它与内置恢复的自动重新加密不同。

远端对象需要存储服务自身的备份或版本保护。仅恢复 Picloom 的数据库无法找回远端已删除的图片。

升级

先备份，再在部署目录拉取新镜像并重建容器：

docker compose pull
docker compose up -d

保留原数据目录、目录映射和 .env，尤其是 ENCRYPTION_KEY。自行构建镜像时，按 从源码构建镜像 更新。

升级后检查登录、上传和已有图片访问是否正常。若出现数据库结构校验错误，不要手改校验值绕过；保留数据并核对版本兼容性。切回旧镜像不等于回退数据库，需要恢复时应使用与备份兼容的版本。

主题数据

主题包位于数据目录的 themes/，草稿和启用快照保存在 site-settings.json。应用升级不会覆盖这些文件。

SQLite 应用备份包含主题包和站点配置，仅恢复包含当前格式配置快照的备份。PostgreSQL 不支持应用内备份恢复，应随数据库一起备份上述目录和文件。页面异常时先按恢复默认页面进入后台。