Add mount-free Synology Photos API sources with bounded image cache
This commit is contained in:
渡口浪人
@@ -0,0 +1,65 @@
|
||||
# Synology Photos API 来源与 Ubuntu 迁移候选
|
||||
|
||||
本功能从 NAS 的 Photos API 按需读取照片，不需要 NFS、SMB 或 `/photos` 文件挂载。NAS 原照片不复制整库到 Server。
|
||||
|
||||
## 已支持与边界
|
||||
|
||||
- 新来源类型 `synology-photos`，与 `local` 挂载目录明确分开。
|
||||
- 共享空间 `SYNO.FotoTeam`、当前登录账号的个人空间 `SYNO.Foto`；不是任意 NAS 用户的个人空间。
|
||||
- 人物列表分批读取，照片按 ID 做 any 并集 / all 交集；无匹配时明确为空，不回退全库。
|
||||
- 支持目录相对路径、递归开关、日期文件夹 / 标题、方向及现有质量筛选。`.` 表示所选空间根目录；路径以 Photos 返回的目录名为准，不是 Ubuntu 绝对路径。
|
||||
- 图片使用经过实测的 `Thumbnail.get` v2、`size=xl`。原始文件名不代表下载的是原图。对 NAS 当前原图下载接口的探测被拒绝，原图下载**未宣称支持**。
|
||||
- 照片枚举 `Browse.Item.list` v7，人物 `Browse.Person.list` v3；每批 500 条，最多 100000 条，超过明确失败，界面目录上限仍由 `catalog_limit` 控制。不支持 NAS 未暴露或账号无权访问的相册。
|
||||
- 旧 `local` 来源保留挂载读取方式，不自动变成 API 来源。新建 / 编辑来源时可明确选择 API 类型。
|
||||
|
||||
## 安全与缓存
|
||||
|
||||
保持 HTTPS SHA-256 证书指纹校验，在同一 TLS socket 验证证书后才发送 SID。仅调用固定 API 与只读方法，不使用通用 RPC 转发、不跟随重定向。密码不持久化，会话文件保持 0600。会话过期返回明确重连提示；不保存密码以自动重登，也不对 NAS 原会话发 logout。权限不足与会话失效分开处理。
|
||||
|
||||
缓存为 `/data/cache/synology-photos`，默认总图片字节上限 256 MiB，可用 `SYNOLOGY_PHOTOS_CACHE_BYTES` 调整（环境配置最小 1 MiB），单张不超过应用 20 MiB 限制。只下载选中的图片。文件锁合并跨线程、跨进程下载，预留容量后写 0600 临时文件，完成长度核对及 Pillow 验证 / 解码后原子提交；超时、中断及无效数据清理临时文件，下次持锁读取清理进程异常退出遗留的 `.part`。按最近使用淘汰。缓存身份包含端点、会话摘要、空间、照片 ID、索引版本及缩略图缓存键，避免账号 / 空间混用。
|
||||
|
||||
容量上限针对图片和下载临时文件的逻辑字节，不含 SQLite、锁文件与文件系统元数据；并发串行缓存锁会等待正在进行的单张下载。网络 socket 超时 30 秒，流读取检查 90 秒期限，已阻塞的单次 socket 读取最多再等待其超时。
|
||||
|
||||
## Ubuntu 候选配置
|
||||
|
||||
正式代码在 `/home/developer/Documents/Projects/pigway-frame-flow` 的 `codex/synology-photos-api` 分支开发，不能以迁移临时解包目录作为开发仓库。
|
||||
|
||||
候选文件：`deploy/compose.ubuntu-photos-api.yml`。外部 `192.0.2.10:81`，内部 `18787`，UID/GID `10333:10333`，数据和配置固定为：
|
||||
|
||||
- `/srv/pigway/apps/pigway-frame-flow/data:/data`
|
||||
- `/srv/pigway/apps/pigway-frame-flow/config:/config`
|
||||
|
||||
无 `/photos` 绑定。`create_host_path: false` 防止在 T7 未挂载时悄悄创建目录；但仍需在启动前检查 `findmnt -T /srv/pigway` 的实际源设备。
|
||||
|
||||
`.env` 需从已确认的配置安全迁移，保留 Photos URL、证书 pin 与已有 Frame Flow / 相框鉴权；不要把密钥写入仓库。模板默认 `KOKONNA_WRITE_ENABLED=false`。创建 `data/tmp`，属主保持 10333:10333，`TMPDIR=/data/tmp`。Docker data-root 和 containerd root 也必须在 T7，不能仅检查 bind mount。
|
||||
|
||||
```sh
|
||||
# 仅检查候选配置；不会启动应用。
|
||||
FRAME_FLOW_IMAGE='<已验证的镜像标签>' docker compose -f deploy/compose.ubuntu-photos-api.yml config --quiet
|
||||
```
|
||||
|
||||
完整构建使用根目录 Dockerfile。若使用 `deploy/Dockerfile.runtime-update`，必须指定已审核的基础镜像，构建步骤会检查依赖锁与基础镜像相同；不相同时必须完整构建。本次依赖未新增，已比对现有 0.1.8 基础镜像的锁文件。
|
||||
|
||||
## 旧来源转换与恢复
|
||||
|
||||
**停止目标实例、复制数据、转换真实配置及切换部署均需另行授权，本次没有执行。**
|
||||
|
||||
1. 确认 T7 挂载，备份 NAS 原有完整 `/data`、`/config`、旧镜像及 Compose。SQLite 必须停服务后复制，或使用 SQLite backup API；不要只复制有活动 WAL 的主文件。
|
||||
2. 将备份恢复到上述 Server 目录，保持私密文件权限，创建 `data/tmp`。保留旧 NAS 备份直至切换验收。
|
||||
3. 对每个需要摆脱挂载的来源显式 dry run：
|
||||
|
||||
```sh
|
||||
python scripts/migrate-photos-api.py --database /data/frameflow.db --source family
|
||||
# 已获授权、目标服务已停止时才执行：
|
||||
python scripts/migrate-photos-api.py --database /data/frameflow.db --source family --apply --service-stopped
|
||||
```
|
||||
|
||||
工具保持来源 ID、任务引用、人物空间、any/all、目录、方向及筛选设置，只修改来源类型并关闭旧本地 `@eaDir` 预览开关；自动在同一数据目录生成 0600 SQLite 备份。转换不会验证该账号在 Photos 中是否可访问相同目录，必须再做真实只读预览。不要转换确实依赖挂载且 Photos 未收录的目录。
|
||||
4. 已获得单独授权后才停旧实例、以只读候选配置启动 Server，并逐个来源验收。没有授权前不执行 `compose up` 或开启真实写入。
|
||||
5. 回退时停止 Server，恢复已备份的数据库和配置（停服务时处理对应 WAL/SHM），恢复旧来源类型与 NAS 原部署，保证只有一个实例有写权限。原 NAS 照片不受缓存或来源转换影响。
|
||||
|
||||
## NFS 授权判断
|
||||
|
||||
API 来源的共享 / 个人空间取图已经可以完全不依赖 NFS，因此这条新取图链路不需要为 `192.0.2.10` 保留 DSM `photo` NFS 授权。但目前旧来源和待迁移配置没有全部切换验收，不能据此宣称迁移完成或旧本地来源已可脱离挂载。确认没有其他已批准用途后，可以单独授权删除该特定 NFS 规则；本次没有删除。
|
||||
|
||||
实际版本、镜像标识、通过 / 失败 / 未执行项见本任务验证记录。
|
||||
+5
-3
@@ -2,7 +2,7 @@
|
||||
"openapi": "3.1.0",
|
||||
"info": {
|
||||
"title": "Pigway Frame Flow API",
|
||||
"version": "0.1.8"
|
||||
"version": "0.1.9"
|
||||
},
|
||||
"paths": {
|
||||
"/api/v1/devices/{device_id}/widgets/selection": {
|
||||
@@ -15216,7 +15216,7 @@
|
||||
"version": {
|
||||
"type": "string",
|
||||
"title": "Version",
|
||||
"default": "0.1.8"
|
||||
"default": "0.1.9"
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
@@ -16332,6 +16332,7 @@
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"local",
|
||||
"synology-photos",
|
||||
"webdav",
|
||||
"google-drive",
|
||||
"alipan",
|
||||
@@ -16484,6 +16485,7 @@
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"local",
|
||||
"synology-photos",
|
||||
"webdav",
|
||||
"google-drive",
|
||||
"alipan",
|
||||
@@ -17412,7 +17414,7 @@
|
||||
"version": {
|
||||
"type": "string",
|
||||
"title": "Version",
|
||||
"default": "0.1.8"
|
||||
"default": "0.1.9"
|
||||
},
|
||||
"api_version": {
|
||||
"type": "string",
|
||||
|
||||
Reference in New Issue
Block a user