Skip to content

FAQ

Jump to bottom
github-actions[bot] edited this page Sep 15, 2026 · 37 revisions

常见问题 (FAQ)

中文 · English

本文档按功能分类整理了 GalleryVault 的常见问题与排错指引。

快速分类索引

一、安装与部署排错

1. 跨网段或反代访问时，提交操作报「Cross-origin request rejected」？

这是系统的 CSRF 防护机制在校验客户端来源与服务端 Host。当请求经过 Nginx、Caddy 或 Cloudflare 等外部反代时，反代需正确透传 Host，不要剥掉 Origin（例如 Nginx 中配置 proxy_set_header Host $http_host;）。Origin: null（file://、沙箱 iframe）或无 Origin 却带会话 Cookie、又没有 CSRF token 的 API 变更请求会 403。若客户端 IP 处于私网反代网段后，请在 docker-compose.yml 中配置 TRUSTED_PROXIES 白名单。详细配置见 部署指南 → 安全加固。

2. 如何修改外部访问端口或绑定自定义域名？

在 docker-compose.yml 中修改前端服务 galleryvault-frontend 的端口映射（例如 "8888:80"）。如需绑定独立域名与启用 HTTPS，推荐在宿主机使用 Nginx 或 Caddy 终结 TLS 并反代至前端容器端口。

3. 数据库容器报错 Operation not permitted 无法启动？

PostgreSQL 官方容器固定运行在容器内 postgres 用户（UID 999）。请确保不要将宿主机的 ./db-data 目录整体 chown 给其他普通用户。若已误改属主，请在宿主机执行 chown -R 999:999 ./db-data 恢复。

4. 扫描 7z 压缩包是否会将全部图片解压到磁盘？

不会把整包解到库目录。 扫描只索引图片成员；阅读单页时在内存中解出那一张（固实压缩包也按页，不把前面页累加进限额）。单页未压缩大小上限 128MB，超限拒读（该页 404）。非图片文件留在压缩包里。.cbr / .rar 还需要宿主机安装 unrar 或 libarchive，否则扫库失败。

5. 升级到 PostgreSQL 18 后数据库容器起不来？

官方 postgres:18-alpine 把数据放在 /var/lib/postgresql 下的版本子目录。仓库 docker-compose.yml 已把宿主 ./db-data 挂到 /var/lib/postgresql，不要再设置 PGDATA，也不要继续挂旧路径 /var/lib/postgresql/data（目录非空检查会让容器退出）。新安装直接 docker compose up -d 即可。详见 部署指南 → 存储拓扑。

二、凭据、Cookie 与安全

1. 修改管理员密码后，所有设备都需要重新登录吗？

是的。这是主动设计的安全机制：修改密码会使系统内当前所有持久化会话凭据即时作废，所有已登录设备均需重新进行身份验证。

2. 加密密钥丢失了该如何恢复？

静态加密使用的是高强度 AES-256-GCM 算法。密钥一旦遗失在数学上不可逆逆向。请参阅 静态加密 → 密钥丢失的恢复 进行灾备重置。

3. 顶栏出现 Cookie / 探活告警？

系统会在启动时及每隔 30 分钟后台自动探活凭证：

  • Cookie 已失效（红条）：会话已过期，请在「系统设置 → ExHentai」中重新填入最新凭证并点击「测试登录」。
  • 无里站权限（红条）：当前账户无对应访问权限或 igneous 配置有误，可检查配置或切换为 e-hentai.org 表站域名。
  • IP 封禁（红条）：源站提示 IP banned / 暂时限制，换出口或等解封；不要当成缺 igneous。
  • 探活失败（橙条）：网络或站点异常，Cookie 未必失效。 在红条状态下系统会暂停云端同步，防止损坏本地数据。

4. 为什么不建议在 docker-compose.yml 中配置凭证环境变量？

系统以 PostgreSQL 数据库作为凭据配置的唯一可信数据源（SSOT）。若在环境变量中硬编码，容易发生环境与库中配置不一致的静默异常，因此统一在 Web 设置界面安全保存（启用 ENCRYPTION_KEY 时自动加密落库）。

三、下载调度与并发控制

1. 遇到 ExHentai 302 临时挑战告警并自动全局暂停？

这是服务端的动态频控防护机制。检测到 302 挑战后，系统会自动挂起全部下载队列以保护您的账号免遭封禁。后台探针会默认每 10 分钟自动静默探活一次，一旦服务端解除限制，下载队列将自动恢复，无需人工干预。

2. 官方归档整包下载失败重试或断点续传会重复扣除 GP 吗？

绝不会。生成归档任务后，系统会将专属下载 URL 持久化保存在任务元数据中。后续无论是网络中断续传（HTTP Range）还是失败重试，均直接复用该 URL，绝不重新向云端申请打包或二次扣费。

3. 下载报错 image download request failed 如何排查？

这通常是由外部网络抖动、H@H 分布式节点暂时离线或代理断流引起的瞬时故障，系统已内置指数退避重试机制（30 秒至 6 小时自动重试）。可在宿主机查看诊断日志：

docker logs galleryvault-backend --since 6h | grep -E "download task failed|page download failed"
  • ReadTimeout：个别 H@H 节点传输过慢，慢速看门狗会自动跳过；无节点 key 时会解析页面 HTML 换节点。
  • ConnectTimeout / RemoteProtocolError：代理链路不稳定。建议检查代理节点，或在设置中适度下调 page_concurrency（并发页数）。

4. 点击了暂停按钮，为什么当前任务还在继续？

点击暂停后，系统立即停止向工作池派发新页面与新任务，已处于传输中的单张图片会在其自身生命周期内完成传输并安全落盘，避免产生损坏的半截文件。

四、库管理、查重与版本追踪

1. 从设置中移除了某个库根目录，里面的画廊会从系统消失吗？

不会。从设置中移除路径仅代表后续不再对该路径进行自动扫描。已索引的画廊元数据仍安全保存在数据库中。

2. 在本地删除了画廊，能否找回？

  • 若删除时未勾选「同时从磁盘删除文件」，画廊会进入系统的「回收站」，可在回收站界面一键撤回恢复。
  • 若已勾选「彻底从磁盘删除」：先标进回收站，磁盘文件全部删成功后才从索引移除。删盘失败会留在回收站（不是「记录没了、文件还在」）。任一副本路径不在扫描根白名单内则整本跳过，不删其余合法文件。
  • 只读挂载导致删盘失败时，DB 行保留，toast 与日志会提示。

3. 新版本已下载完成，为什么「更新画廊」页面依然显示该条目？

当检测到新 GID 的完整画廊已存在于本地库时，点击「立即检测」会自动安全清理旧版本的本地残留并关闭对应更新项。若该项目曾被手动标记为「忽略」，则不会自动执行清理。

4. 跨 GID 查重的作用与机制是什么？

  • 聚类打分机制：针对网络上同一作品由不同汉化制作组翻译、不同压制画质或多次上传导致云端分配不同 GID 的情况，算法自动剥离同人展会前缀（如 (C100)、(COMIC1☆15)）、汉化组与社团方括号标签（如 [某汉化组]）以及版本后缀（如 [DL版]、[中国翻訳]），提取核心标题与 artist 画师命名空间，基于加权编辑距离与词元相似度进行多维度同源作品聚类打分。
  • 云端对比与一键决策：在「管理 → 查重 → 跨GID重复」中，系统将本地已入库画廊（标明真实页数、磁盘路径与画质）与 ExHentai 收藏夹中未入库的云端画廊并排对比展示。用户可直观比对并勾选保留最佳版本，一键批量取消冗余云端收藏、删除本地重复画廊，或标记忽略误报分组。

5. 归档或下载保存时报「File name too long」/「[Errno 36]」错误如何解决？

  • 原因解析：Linux ext4 及主流文件系统对单文件名限制为 255 字节（Bytes）。中文、日文在 UTF-8 下每个字符占用 3 字节，若按字符数截断极易在超长标题时超出 255 字节上限，并在创建临时打包文件（如 .cbz.partial）时触发 [Errno 36] File name too long。
  • 现行规范与英文固定命名：
    • 系统全面采用 243 字节截断规范（为 .cbz.partial 预留 12 字节后缀缓冲，确保总名 ≤ 255 字节），并将目录名上限设为 247 字节。
    • 冷归档 CBZ 强制采用英文/罗马音 canonical 规则（gid-gallery.title.cbz），不仅彻底消灭超长异常，还能跨 Linux/Windows/Mac 以及 NFS/SMB/WebDAV 协议与网盘备份工具无缝兼容，杜绝编码乱码。
  • 历史归档修复（宿主脚本）： 该脚本在仓库根 scripts/repair_cbz_filenames.py，没有打进 backend 镜像。在克隆了完整仓库的宿主机上跑： 
    python scripts/repair_cbz_filenames.py --target-dir /path/to/archive --dry-run
python scripts/repair_cbz_filenames.py --target-dir /path/to/archive
    容器内清洗 sidecar / GID 用 repair_cold_archives.py（见下条）。

6. 本地画廊或冷库 CBZ 存在前导 GID 冗余污染（如 [12345] 12345-标题）如何批量清洗与修复？

  • 产生原因：部分第三方移动端导出、外部爬虫或多次手动迁移命名时，可能在文件/目录名前端产生重复的前缀堆叠（如 [12345] 12345-画廊名 或 12345-12345-画廊名），导致扫库时识别出畸形标题或冷库索引混乱。
  • 修复方案（Docker 一行命令）：系统内置了全量清洗脚本 repair_cold_archives.py。该脚本支持自动剥离冗余 GID 前缀，并分片批量回查 ExHentai GData 官方接口洗白重构 .galleryvault.json 索引： 
    # 演练预览：
docker compose exec backend python /app/galleryvault/scripts/repair_cold_archives.py --archive-dir /archive --dry-run

# 正式执行清洗重构：
docker compose exec backend python /app/galleryvault/scripts/repair_cold_archives.py --archive-dir /archive
    详细参数请参阅 备份与恢复 → 离线全量修复与元数据清洗工具。

7. 冷存储多根目录（archive_roots）如何工作？如何安全清理下载源目录？

  • 多根负载均衡：在「设置 → 资料库」中支持配置多个冷存储归档挂载点（archive_roots，每行一个路径）。系统在执行冷归档时自动通过 statvfs 探测各路径的剩余可用空间，自动将新打包的 CBZ 写入容量最充裕的磁盘。单卷上限 500 页且 2GiB，超限打成冷目录。
  • 安全反向清理：在设置页存储面板点击「清理已归档源目录」（POST /api/system/purge-archived-sources）。系统具备完善的防御机制：严格比对冷热两端 GID，主动排除正在下载或处于等待队列（pending / downloading）中的活跃画廊，仅安全删除已在冷库中完整归档为 CBZ 的本地散图解压源文件夹，并即时同步扣减物理磁盘用量。

8. 画廊出现缺页、坏图或打不开如何排查与修复？

  • 进入「管理 → 缺页体检」（#/integrity），点击「扫描缺页与坏图」。
  • Magic Header 二进制校验：系统以 2 并发深度读取文件头（最多 20 字节）校验 JPEG FF D8 FF、PNG 89 50 4E 47、GIF 47 49 46 38、WebP RIFF....WEBP 魔数与 4/8 位补零命名规范，可精准揪出传输截断残图、403/503 HTML 错误页伪装的坏图与错乱序列。
  • 一键差量修复：体检完成后标红列出异常项，点击「修复」或「全选并修复」。系统仅差量重下损坏页与确实缺失的页面，已完好的图片坚决不重复下载，自动继承原画质，瞬间自愈并最大程度节约账号配额。

五、阅读器、标签与客户端生态

1. 为什么有些标签没有中文翻译？

标签翻译来自 EhTagTranslation/Database。未收录的词保持原文。在 设置 → 标签 点「立即更新」，进度在日志页看，按钮不在日志页。

2. 阅读器翻页后返回画廊库，此前的搜索条件还会保留吗？

完整保留。阅读器具有完整的状态保持上下文，无论在阅读器内翻阅多少页，返回详情或列表时所有的多标签筛选、排序规则与页码均保持一致。

3. 如何通过第三方阅读客户端（如 Tachiyomi / Mihon / Panels）访问？

系统开放了标准的 OPDS 目录服务（GET /api/opds）。在移动端客户端中添加 OPDS 源，输入您的访问地址并使用 HTTP Basic 认证（用户名为 galleryvault，密码为您的管理员登录密码）即可直接连接本地书库。

4. 将应用「添加到主屏幕」（PWA）是否会将画廊离线下载到本地？

不会。PWA 模式仅将前端界面外壳与静态样式缓存在设备端，以提供宛如原生 App 的流畅体验。画廊图片与元数据均按需在线流式加载，不会大量吞噬手机存储空间。

5. Telegram Bot 能做什么？命令在哪看？

在「设置 → Telegram」填 token / chat ID / 允许的 user ID 后，启动会自动注册客户端指令菜单。聊天中粘贴画廊 URL 即可入队；/queue 用 InlineKeyboard 操作队列；/status /storage /quota /cookie 探活；/search /info /random 查本地库（含封面）。完整命令表见 系统设置 → Telegram bot 控制命令。

📖 GalleryVault

开始

使用

运维

Clone this wiki locally