Manage

库维护

中文 · English | 属于 使用指南 系列

顶栏「管理」落到 #/recycle。页内 tab：回收站、重复副本、收藏夹重复、跨 GID 重复、缺页体检、冷库归档。日志在顶栏「更多 → 日志」（#/logs）。

重复副本与查重（#/duplicates）

• 管理页三个查重 tab 是独立 hash（没有 ?tab=）：
  • 重复副本（#/duplicates）：同一画廊（同一 gid）出现在多个扫描目录时（如 EhViewer 下载目录 + CBZ 归档 + 手动复制），扫描会按重复副本策略（设置页 duplicate_policy）自动保留一份，并把其余副本记录在此标签。策略包括 keep_first（默认，已入库优先）、prefer_more_pages、prefer_newer、prefer_larger / prefer_smaller、manual（全部人工决定）。每组展示每个副本的缩略图、标签、页数、大小与发布时间（「当前保留」徽标标识当前索引指向）。支持「保留此副本」、「保留并删除其他副本」（删除前通过 Path.resolve() 校验路径严格处于扫描根目录内，防范路径穿越）、「忽略该组」。工具栏「扫描库」按钮可立即重新扫库并刷新列表（全局暂停时提示暂停而不启动扫描）；支持「全部 / 待处理 / 已忽略」药丸按钮筛选状态。
  • 收藏夹重复（#/duplicates/favorites）：针对收藏夹中同一作品的不同重传版本分组（归一化标题 + 画师）。支持批量取消收藏、取消收藏并删除本地画廊、或忽略该组。旧路由 #/favorites/manage 仍打开同一页。已忽略项在 #/favorites/ignored。
  • 跨GID重复（#/duplicates/cross-gid）：跨不同 GID 聚合本地已入库画廊与云端未入库收藏，识别同源重传（汉化 / 重传 / 无修等）：
    • 聚类打分机制：算法自动剥离同人展会前缀（如 (C100)、(COMIC1☆15)）、社团汉化组标签（如 [某某汉化组]）以及版本后缀（如 [DL版]、[中国翻訳]、[Digital]），提取规范化核心标题与 artist 画师命名空间，结合多维度字符串编辑距离与相似度加权打分进行同源作品聚类。
    • 云端对比与操作决策：在同一卡片组内，系统并排对比展示本地已入库副本（标注本地画廊 ID、磁盘路径、实际页数与画质）与 ExHentai 收藏夹中未入库的云端画廊（标注云端封面与发布日期）。用户可清晰比对画质与完整度，按需保留最佳版本，一键批量取消冗余云端收藏、删除本地冗余画廊，或对误报分组点击「忽略该组」（持久化忽略，后续扫库不再弹出）。扫库完成后由后台异步完成聚类并存入内存缓存，进页亚秒级加载，同时提供「刷新」按钮按需重新计算。

回收站（#/recycle）

• 顶栏「管理」入口默认落地点（也可在管理页内切标签；直接访问 #/recycle 仍可用）。两个分页：用户删除（库页删除且不删盘）与 扫描失踪（扫描时目录里找不到）。
• 勾选后 恢复 重新出现在库中（只恢复「用户删除」；扫描失踪幽灵本不会被直接弄回资料库）；彻底删除 会再确认是否删磁盘文件（删盘后扫描不会重新入库）。勾选删盘时先标进回收站，磁盘全部删成功后才从索引移除；删盘失败会留在回收站。任一副本路径不在扫描根白名单内则整本跳过，不删其余合法文件。
• 回收站里的本不会被当成「新版已在库」而硬删旧本。
• 高危操作二次确认与防越权保护：系统对批量与破坏性清理实施多层防护——历史记录清空（/api/history）与全局阅读进度重置（/api/galleries/progress）接口均强制要求附加 ?confirm=true 参数，前端必须弹窗二次确认；重复副本清理与文件物理删除严格校验绝对路径处于允许的根目录白名单内，且安全删除白名单已扩容纳入归档卷（archive_roots、archive_root 与 cold_storage_root），在彻底杜绝路径穿越（Path Traversal）越权风险的同时，支持在白名单约束下安全管理与清理冷归档卷内画廊；批量筛选删除严禁空筛选条件，杜绝因未传参导致的清空全库风险。

冷库归档（#/archive）

• 管理页最后一个 tab（#/archive）。需要先在设置 → 资料库填写 archive_roots（容器内路径，每行一个），并在 compose 里挂上对应卷（默认 ./archive:/archive 是注释掉的）。
• 开始归档：把已入库画廊打成 CBZ，按各归档根剩余空间选盘；路径 {cold}/cbz/{hh}/{ii}/{gid}-{DB 英文标题}.cbz（不跟 download_title）。.galleryvault.json 与 ComicInfo.xml 写进包内，不是放在 cbz 旁边。单卷上限 500 页且 2GiB（两者同时满足才打 CBZ），超限打成 {cold}/dir/{hh}/{ii}/{gid}/ 目录（不是切成多卷 CBZ）。进行中可 取消归档。
• 清理历史残留 / 清理已归档源目录残留文件：冷端已有完好 CBZ 后，删热目录里对应的解压源文件夹。会跳过 pending / downloading 任务。设置页存储表里也有同一按钮。进度在 #/logs。
• 不配归档根、不点开始，就不会自动打包，也不会删源。

缺页体检（#/integrity）

• 可通过顶栏「管理」页内标签切换进入（直接访问 #/integrity 仍可用）。列出已记录页数与已落盘页数不一致、或存在损坏图片的画廊（未填页数不算）。进入页面不会自动全盘扫描，避免大库卡顿。
• 扫描与修复拆分操作指引：
  • 扫描缺页与坏图（POST /api/galleries/integrity/scan）：点击工具栏「扫描」按钮触发后台巡检任务。系统采用 2 并发限速深度校验落盘文件：
    • Magic Header 校验：读取文件头（实现里最多 20 字节）校验 JPEG (FF D8 FF)、PNG (89 50 4E 47)、GIF (47 49 46 38) 与 WebP (RIFF....WEBP) 魔数，并验证 4 位 / 8 位补零命名规范。能精准捕获下载中途网络中断截断的半截残图、云端返回 403/503 HTML 错误页被误存为图片文件的伪损坏图、以及多零乱序错页；
    • 执行记录与状态：扫描结束将执行耗时、扫描文件总数及损坏画廊数量写入任务历史日志（#/logs）；全局暂停时页面给出暂停提示而不启动扫描。
  • 差量补页修复：
    • 扫描完成后，列表中标红高亮异常画廊，并展示记录总页数与实际磁盘有效图片数；
    • 用户可单独点击画廊卡片上的「修复」按钮，或使用工具栏的「全选并修复」进行批量差量自愈；
    • 修复任务由后台差量补全通道托管，系统仅重下缺失页与校验失败的损坏单页，已完好的图片坚决不重复拉取，自动继承画廊原画质档位（原图或降采样），在瞬间修复画廊完整性的同时，最大程度保护 ExHentai 账号配额与网络带宽。

日志页（#/logs）

分为两个标签页：

1. 后台任务活动（Task Activity）：展示后台任务（包括库扫描、标签同步、缩略图生成、收藏元数据同步、查重扫描、画廊更新检测，以及孤儿缩略图清理、缩略图周期播种、下载失败重试巡检、Cookie 健康巡检与存储容量校准等静默巡检维护任务）：
   • 进行中：每行 = 开始时间 · 任务名 · 进行中 · done/total · 进度条 · 描述 · 取消按钮；多任务可并排多行。
   • 已完成：开始时间 · 任务名 · 状态徽标（成功/失败/已取消）· 描述与原因 · 耗时 · 完成时间；已完成任务不再显示进度条。
   • 静默任务与自动化观测：除了前台显式触发的操作外，系统统一追踪并暴露各类定期静默巡检任务（如孤儿缩略图定时清理、定时补充缺失缩略图、失效下载任务退避重试巡检、Cookie 探活以及磁盘用量校准），无论是正在运行还是执行完毕，均能在活动面板清晰查验其耗时、执行明细与健康状态。
   • 空转任务历史抑制：针对高频后台轮询（如失效下载重试巡检），系统内置降噪逻辑——当检测到待重试任务为 0 时，自动跳过向 task_history 写入空转完成记录，避免无意义巡检日志刷屏淹没关键业务变动与真实错误。
2. 系统运行时日志（System Logs）：查看后端服务运行时的实时诊断日志（内存环形缓冲区）：
   • 动态调级：可在线切换全局日志级别（DEBUG / INFO / WARNING / ERROR），无需重启容器；
   • 实时筛选与搜索：支持按最低日志级别（INFO+ / WARN+ / ERROR+）筛选与文本关键字快速检索；
   • 异常堆栈与上下文：错误自动展示可展开的 Traceback 堆栈，并带请求 ID、Worker 协程上下文（gid / task_id）与敏感凭据自动脱敏（ipb_* Cookie、Telegram Token、密钥等安全遮蔽）；
   • 导出日志：工具栏「导出日志」下载 galleryvault.log（环形缓冲 + 落盘轮转文件，GET /api/system/logs/download，仅当前日志根内文件），便于把诊断归档发出；
   • 噪音过滤：httpx 成功请求（2xx/3xx，含 Telegram getUpdates 30s 长轮询）不进入本页；4xx/5xx 与业务 WARNING/ERROR（如 bot 轮询失败、通知发送失败）仍保留。

页面每 2~3 秒自动轮询刷新。设置里的「立即同步标签 / 立即生成 / 立即更新翻译」触发后也会在此留痕。

提示：跨容器看 Nginx / 后端 / 数据库原始输出，用 docker compose logs -f 或 docker logs galleryvault-backend --since 5m。仓库默认 compose 不含 Dozzle。