docs/operations.md

Rama main · réplica de lectura del repositorio original.

# 日常维护与用户备份

## 每日维护

ImageSilo 在单进程内复用一个低频维护循环，不启动外部进程、任务队列或第二个服务：

- 启动后异步清理一次超时临时文件；完整巡检此后按 `app_settings.maintenance_hour` 的 UTC 小时每天执行一次。
- 清理超过 24 小时的上传临时文件。
- 只删除“SQLite 中没有图片记录”且超过 24 小时的孤儿正式文件和缩略图。
- SQLite 有记录但正式文件缺失时只报告，绝不自动删除数据库记录。
- 文件删除失败会写结构化告警；文件保留，下一次每日维护自动重试。
- 每次记录图片数、存储量、别名数、Go heap、RSS、goroutine 和四类内存索引规模。
- 每日维护不会自动重建索引、限速、重启或强制 GC。

管理员可以在“系统”或“设置”页面手动巡检、查看缺失文件，并在确认后手动重建缓存。完整重建期间图片读取继续使用旧索引；成功后一次性替换。

## 备份

应用本身不实现备份、压缩包或云端上传。SQLite 数据库、WAL、正式图片、缩略图和临时目录共同位于 `/data`，一致备份必须覆盖整个目录。

推荐步骤：

1. 停止反向代理写流量或进入维护窗口。
2. 停止 ImageSilo 容器，确认进程已经退出。
3. 复制整个 `/data`，或对 `/data` 所在本地文件系统创建一致性快照。
4. 启动容器并确认 `/readyz`、管理员登录、标准 URL 和历史别名正常。

不要只复制 `imagesilo.db`，也不要在容器持续写入时分别复制数据库和图片目录。恢复时先停止容器，用完整备份替换整个 `/data`，确认数字 UID/GID `10001:10001` 具有读写权限，再启动同版本镜像验证；升级前必须先完成上述备份。