Features

功能特性

中文 · English

本文档系统化阐述 GalleryVault 的核心架构、功能矩阵与设计亮点。

---

核心专精与架构设计

GalleryVault 并非通用型电子书工具，而是专门针对画廊数字资产、高保真元数据体系与分布式同步需求打造的私有归档系统。

┌─────────────────────────────────────────────────────────────┐
│  前端 SPA  :8000                                             │
│  Browse · Discover · Library · Series · Tags · Downloads     │
│  Favorites · Manage(recycle/dup/integrity/archive) · Reader  │
└──────────────┬───────────────────────────────▲──────────────┘
               │ /api 反代                     │
┌──────────────▼───────────────────────────────┴──────────────┐
│  FastAPI  127.0.0.1:8001                                     │
│  扫描 Ehviewer/CBZ  ·  下载/Archive  ·  收藏同步  ·  查重    │
└──────────────┬──────────────────────────────────────────────┘
               │
               ▼
          PostgreSQL（可选字段加密）

---

详细功能矩阵

1. 本地画廊资产管理与高保真解析

• Ehviewer 目录零侵入直读：扫描原生 <gid>-<标题>/ 目录结构，解析 .ehviewer（SpiderInfo V2；可读无标记 V1）恢复 gid、token 与各页 pToken。标题、分类、标签不在 SpiderInfo 里，由目录名 / .galleryvault.json / gdata 补全。无需解压或改名。
• 多元归档格式支持：兼容 CBZ、CBR（内嵌 ComicInfo.xml）、JHenTai 逐页目录的 metadata JSON（不扫归档 ametadata），以及冷库 CBZ/目录内的 .galleryvault.json。
• 7z / PDF 与无 gid 本地库：.7z 扫描只收图片成员（不把非图片解到库目录），阅读按页在内存解压，单页上限 128MB；.pdf 抽内嵌图（单图超 128MB 跳过）。没有 gid 的纯图目录也能浏览、打星。
• 冷热分层存储架构：支持将新下载的活跃工作区（热存储）与只读归档硬盘（冷存储）解耦挂载，支持随时按需向冷库迁移归档。
• 本地画廊自定义组织：支持基于本地自定义列表、星级评分与私有阅读笔记进行个性化分类管理，完全独立于外部站点。

2. 智能生命周期追踪与副本治理

• 重传版本自动检测（Updates）：自动化比对云端画廊重传或版本更迭事件（识别云端重新发布分配的新 GID），支持一键下载最新版并自动清理本地旧版残余。
• 收藏夹跨 GID 智能聚类查重：针对不同汉化组、不同压制画质或多次重复收藏，基于作品特征进行跨 GID 智能聚类，直观呈现对比差异，支持一键移除重复项。
• 同 GID 多副本清理策略：当同一画廊因多盘挂载或路径重复入库时，根据预设策略（保留已有/页数多/体积大/最新或手动）自动治理，避免磁盘空间浪费。
• 标题多模式渲染：全站支持「日文原生 / 英文 / 目录名」三档独立显示切换，且与下载目录的命名规则彻底解耦。

3. 云端元数据深度联动

• 元数据批量缓存（gdata）：使用自有凭证高效拉取画廊分类、详细标签及评分，内置智能缓存池避免高频重复请求。
• 10 个收藏夹独立监控：每个夹可选「增量下载」、「仅监控」或「强制下载」，另有独立轮询间隔；定时检查时检测新项并按模式入队。
• 多站点自适应兼容：基础 URL 仅允许 exhentai.org、e-hentai.org 或其子域（任意反代主机名会 422）；表站模式下自动暂停里站专属条目的标签同步，杜绝误判误删。
• 凭据状态实时探活：系统启动及周期性后台自动探活凭证有效性，顶栏即时直观提示状态并引导维护，避免下载因静默失效而中断。
• 发现页在线探索（Discover）：在 Web 界面直观浏览热门、关注与榜单，支持一键入库或同步至云端收藏。

4. 稳健的并发调度流水线与自愈机制

• 双模下载引擎：
  • 分页并发流式下载：细粒度并发控制、实时进度看板与单页断点续传（仅补全缺失页）。
  • 官方整包归档下载：支持官方 Zip 归档通道，通过 GP 配额换取极速打包，支持单连接流式传输与 Range 断点续传，且重试绝不重复扣除 GP。
• 慢速节点与超时看门狗：具备单图总超时、预热期与最低传输速率三维看门狗，自动踢除迟钝的 H@H 节点并切换新链路，杜绝单个慢任务卡死整个队列。
• 指数退避故障自愈：遇到网络瞬时抖动、代理断流或服务端波动时，自动执行指数退避重试（30 秒至 6 小时递增，最多 10 次），无需人工干预。
• 302 防爬挑战静默防护：检测到服务端 302 临时挑战时，自动挂起下载队列以保护账号凭据，后台探针以可配置周期（默认 10 分钟）静默探活，限制解除后自动无缝恢复。
• 增量即时写入：下载完成的画廊立即完成元数据入库与封面生成，无需触发全量扫盘。

5. 沉浸式阅读与开放生态

• 全模式阅读器：
  • 阅读排版：支持从右向左（RTL 日漫模式）、从左向右（LTR）、垂直连续滚动（条漫/瀑布流）以及双页并排阅读。
  • 翻页与导航：支持键盘快捷键、点击热区、G 键快速跳页与预加载机制，末页自动跳转下一画廊；条漫模式用滚轮/触控垂直滚动（方向键与左右热区不翻页）。
• 动图自适应幻灯片：探测 GIF/WebP 的 duration_ms（各帧 delay 之和，二进制扫描，封顶 120 秒），轮播间隔取 max(用户设定, 时长 + 150ms)；启动后自动全屏，退出全屏即停止。
• 多标签多维组合检索：深度集成 EhTagTranslation 多语言数据库，支持标签建议、多标签 AND/OR 逻辑组合、-tag 排除语法以及中文输入反向联想（例如输入「长发」自动联想 long hair）。
• 开放 OPDS 目录协议：内置标准 OPDS 规范端点（GET /api/opds），支持 HTTP Basic 认证，可直接连接 Tachiyomi、Mihon、Panels 等第三方移动端阅读器。
• 完整操作历史与回收站：用户手动删除或磁盘离线的画廊进入安全回收站，提供全流程操作审计与一键找回。

6. 安全与部署

• AES-256-GCM 数据库静态加密：支持配置 ENCRYPTION_KEY 环境变量，自动将数据库中的 Cookie、令牌与密码哈希进行高强度字段级静态加密存储。
• 10 年持久化免登会话：Web 会话 Cookie 签名密钥自动持久化落库，容器重启或系统升级后无感维持登录态；修改管理员密码可瞬间吊销所有已登录设备凭据。
• 安全隔离与非 root 降权：支持配置 PUID / PGID 环境变量实现 NAS 环境安全降权运行；内置 CSRF 防护（含 Origin: null / 无 Origin 带 Cookie）与反向代理受信网段（TRUSTED_PROXIES）白名单；压缩包单页解压上限 128MB，防止解压炸弹。
• 开箱即用容器化栈：多架构 Docker 镜像（AMD64 / ARM64），内置 PostgreSQL 18 与 Alembic 自动迁移，单命令部署即用。

7. Telegram Bot 运维图库

• 指令菜单自动注册：配置 bot token 后启动即向 Telegram 注册客户端 / 菜单，中英文案跟随通知语言。
• 下载与队列：聊天中直接粘贴画廊 URL（首尾多余斜杠也可）立即入队；/queue 带 InlineKeyboard 暂停、重试、取消；/pause /resume 与 Web 下载页同一全局暂停开关。
• 系统探活：/status 队列概括、/storage 磁盘用量、/quota 图像配额与 GP、/cookie Cookie 有效性，展示对齐 Web 端。
• 本地图库：/search 检索翻页、/info /random 发送详情与封面（与 Web 相同的 5 级封面降级链）、/scan 触发扫库、/fav_sync /fav_download /fav_check 收藏夹自动化。