Usage EN

Usage Guide

中文 · English

Direct Chapters: Browsing & Library · Gallery Details & Reader · Download Management · Favorites & Updates · Library Maintenance · Settings

GalleryVault is built as a single-page application (SPA) using hash routing (such as #/library, #/gallery/7), meaning page navigation, browser refresh, and history traversal require no extra server round-trips.

Desktop top nav: Browse, Discover, Library, Series, Tags, Downloads, Favorites, Manage. History / Settings / Logs live under More. Manage lands on the recycle bin (#/recycle) with tabs: Recycle, Duplicate copies (#/duplicates), Favorite duplicates (#/duplicates/favorites), Cross-GID (#/duplicates/cross-gid), Integrity (#/integrity), Cold archive (#/archive). #/favorites/manage still opens favorite duplicates (legacy alias). Mobile uses a flat hamburger menu.

The top banner stacks a yellow global-pause bar, a red Cookie-expired / no-access / IP-banned warning, and image quota alerts when necessary. Probe failures (network/site; Cookie may still be valid) use an orange bar. The bell next to 🎲 serves as the in-app notification center (download completions/failures/retarget, library scan results, archive start/ok/fail, and cookie expired/no-access/IP-banned, polled every 15 seconds, visible even without Telegram; the Cookie red bar remains; one-click "Clear"; timestamps follow the container TZ, not truncated UTC).

---

First-Run Wizard (#/welcome)

Right after initial deployment (while the default password is still active), logging in automatically directs to the three-step #/welcome wizard:

1. Change default password: Replace the built-in password p1a2s3s4 with a strong master password (mandatory, can also be modified later in Settings).
2. Connect ExHentai: Select your base URL (ExHentai, E-Hentai, or a subdomain of those hosts; any other hostname is rejected) and fill in ipb_member_id / ipb_pass_hash / igneous cookies, verifiable via "Test login" (optional; see Configuring ExHentai Cookies below).
3. Fill library: Click "Scan library" or "Check all folders" to begin indexing (optional).

Completed steps receive a ✓ indicator. Click "Finish setup" to enter the main interface. Configured instances will not force this wizard upon login, though you can revisit it at any time by navigating directly to #/welcome.

Recommended Workflow

For optimal metadata accuracy and minimal network bandwidth consumption, follow this recommended sequence:

1. Configure Account Cookies (Optional but Recommended): Connect your ExHentai account via the welcome wizard or Settings and verify login connectivity.
2. Cache Favorites Metadata First: Navigate to Favorites & Updates (#/favorites) and click "Check all folders" (or configure periodic polling) to pre-warm remote metadata and cover images into local database storage.
3. Scan Local Library: Place your local gallery archives into the ./library directory and click "Scan library" in Browsing & Library. Local archives will match against pre-cached cloud metadata with high fidelity.
4. Deduplication & Maintenance: Open Library Maintenance → Duplicate copies (#/duplicates) for same-GID extra copies; favorite-folder dupes are #/duplicates/favorites (legacy #/favorites/manage still works).
5. Incremental Tracking & Reading: Enable desired favorite folders with "Incremental download" to track fresh uploads automatically; read locally in Gallery Details & Reader with search context retention across multiple reading modes.

Configuring ExHentai Cookies

Connecting with ExHentai, synchronizing favorite folders, fetching tags, or downloading galleries requires your browser session cookies:

1. Obtain Cookies:
   • Log into E-Hentai or ExHentai using your desktop browser;
   • Press F12 to open Developer Tools, then navigate to the Application (Chrome/Edge) or Storage (Firefox) tab;
   • Expand Cookies on the left panel and select the site domain;
   • Locate and copy values for the following three keys:
     • ipb_member_id: User ID (numeric string);
     • ipb_pass_hash: Password hash (32-character hexadecimal string);
     • igneous: Secret access token required for exhentai.org (requires account access permissions).
2. Fill into GalleryVault:
   • Navigate to step 2 of the #/welcome wizard or open the ExHentai section in Settings (#/settings);
   • Keep the base URL as https://exhentai.org (or switch to https://e-hentai.org if your account lacks sadpanda clearance);
   • Paste the values into their corresponding fields (cookies are masked and never echoed back).
3. Test Connectivity & Health Probes:
   • Click Test login to verify cookie validity immediately;
   • The service automatically runs a connectivity probe on startup and every 30 minutes thereafter;
   • Cookie expiry, no ExHentai access, or an IP ban shows a red top banner linking to Settings. Probe failures caused by network/site issues show an orange bar (the Cookie may still be valid).

Security Note: Cookies contain sensitive session credentials. Never commit them to git repositories, public documentation, or unencrypted logs. GalleryVault supports AES-256-GCM database encryption at rest via ENCRYPTION_KEY (see Encryption at rest).

Documentation Chapters

The usage guide is divided into the following dedicated chapters:

• Browsing & Library (Library):

  • Browse (#/browse) — Default landing grid, continue reading cards, keyboard navigation, and global instant search; landscape gallery card covers are no longer cropped, using blurred background padding. Card covers prioritize EH remote-covers cache with immediate 0.jpg fallback and background fetching on cache miss; favorites checks immediately skip existing covers.
  • Discover (#/discover) — Browse ExHentai online, Popular / Watched / Toplist feeds, and cursor pagination.
  • Series (#/series) — Doujinshi/Manga default filtering with pagination, event prefix stripping, score-based auto grouping; includes undownloaded cloud favorites with badges and one-click downloads, manual GID/favorite additions, cloud exclusions, and scan auto-rebuild.
  • Library (#/library) — Multi-index sorting, mutually exclusive reading status filters, AND/OR multi-tag filtering with -tag exclusions, batch actions, and deletion safety guards.
  • Local Lists (#/library) — Independent local lists lifecycle, decoupled from ExHentai cloud favorites.
  • Tags (#/tags) — Tag namespace strips, frequency analysis, and EhTag Chinese search suggestions.
  • History (#/history) — Reading history timeline and progress management.

• Gallery Details & Reader (Reading):

  • Gallery Detail (#/gallery/) — Progress-aware thumbnail pagination, direct ExHentai links, tag sync, quality tier inference, and CBZ export.
  • Reader (#/reader//) — Streamed page rendering, LTR / RTL Manga / Double-page / Webtoon modes, pinch-to-zoom, G jump prompt, F image fullscreen, and persistent search context.

• Download Management (Downloads):

  • Downloads (#/downloads) — Batch URL/GID queueing, automatic re-upload version following, live progress, global pause, GP/quota gauges, and exponential backoff self-healing.
  • Archive Downloads (ExHentai archive) — Official zip channel, GP balance preview, HTTP Range resumption, and automatic fallback to page-by-page.

• Favorites & Updates (Favorites):

  • Favorites (#/favorites) — Monitoring 10 favorite folders, automatic metadata application, skip heuristic, folder search, and batch moves.
  • Favorite duplicates (#/duplicates/favorites) — Multi-version dupes in favorite folders; legacy #/favorites/manage still works.
  • Gallery Updates (#/updates) — Intelligent re-upload detection (GID changes), background download, and automatic superseded local copy cleanup.
  • "download favorites" vs. "enabled" — Logical matrix of global scheduled scanning versus per-folder enablement.
  • The Three Modes — Incremental download, watch only, and force download mechanics.

• Library Maintenance (Manage):

  • Duplicate copies (#/duplicates) — Same-GID extra copies, favorite dupes, cross-GID.
  • Recycle Bin (#/recycle) — User deleted vs scan missing, restore, purge.
  • Integrity (#/integrity) — Missing/corrupt pages and incremental repair.
  • Cold archive (#/archive) — Pack CBZ, cancel, purge archived sources.
  • Logs (#/logs) — Background tasks and runtime logs.

• Settings (Settings):

  • Settings (#/settings) — Storage directory paths, download watchdog thresholds, collapsible sections and disk usage snapshot, title preferences, Telegram bot controls, PWA, themes, and OPDS / third-party reader configuration.
  • What Needs the Network — Detailed network access classification matrix (ExHentai, GitHub, local-only, and local-first operations).

---

Old Anchor Migration Table

If you have bookmarked specific section anchors from earlier versions of Usage-EN.md, refer to this table for their new locations:

Old Anchor	Target Document	New Section Anchor
#browse-browse	Browsing & Library (Library)	Browse (#/browse)
#discover-discover	Browsing & Library (Library)	Discover (#/discover)
#系列作品series	Browsing & Library (Library)	Series (#/series)
#history-history	Browsing & Library (Library)	History (#/history)
#first-run-wizard-welcome	Usage Guide (Usage)	First-Run Wizard (#/welcome)
#library-library	Browsing & Library (Library)	Library (#/library)
#local-lists-library	Browsing & Library (Library)	Local Lists (#/library)
#duplicate-copies-duplicates	Library Maintenance (Manage)	Duplicate Copies (#/duplicates)
#recycle-bin-recycle	Library Maintenance (Manage)	Recycle Bin (#/recycle)
#missing-pages-integrity	Library Maintenance (Manage)	Missing Pages (#/integrity)
#gallery-detail-galleryid	Gallery Details & Reader (Reading)	Gallery Detail (#/gallery/)
#reader-readeridpage	Gallery Details & Reader (Reading)	Reader (#/reader//)
#tags-tags	Browsing & Library (Library)	Tags (#/tags)
#downloads-downloads	Download Management (Downloads)	Downloads (#/downloads)
#logs-logs	Library Maintenance (Manage)	Logs (#/logs)
#favorites-favorites	Favorites & Updates (Favorites)	Favorites (#/favorites)
#manage-favorites-favoritesmanage	Library Maintenance (Manage)	Favorite duplicates (#/duplicates/favorites)
#gallery-updates-updates	Favorites & Updates (Favorites)	Gallery Updates (#/updates)
#archive-downloads-exhentai-official-zip-channel	Download Management (Downloads)	Archive Downloads (ExHentai archive)
#download-favorites-vs-enabled	Favorites & Updates (Favorites)	"download favorites" vs. "enabled"
#the-three-modes	Favorites & Updates (Favorites)	The Three Modes
#settings-settings	Settings (Settings)	Settings (#/settings)
#what-needs-the-network	Settings (Settings)	What Needs the Network