FileHost/docs-site/en/guide/faq.md

FAQ

Forgot the admin password?

With docker exec access:

docker exec pichost reset-password
docker exec pichost reset-password <username>

Local: npm run reset-password. See Quick start.

Why can’t I regenerate the API token in the UI?

API_UPLOAD_TOKEN in the environment locks the token. Change env and restart. See Environment variables.

Hotlink / Referer errors?

Check the Referer whitelist (ALLOWED_REFERER_HOSTS or Settings). Referring sites must be listed; PicHost’s own hosts and dual-domain pair are allowed automatically.

Admin 404 / locked out after dual-domain setup?

Cause: With dual-domain enabled, PicHost returns 404 for every request whose Host is not the configured site or image hostname. Common triggers:

1. Saving dual-domain URLs while browsing via IP or an internal address
2. Reverse proxy “force hostname” or wrong Host header so PicHost sees a different host than configured

Recovery (when locked out):

docker exec pichost clear-domains
# Site URL only: docker exec pichost clear-domains --site

Local dev: npm run clear-domains. Then reopen admin via your previous IP/internal URL and reconfigure using the dual-domain guide.

Prevention: Read the risk confirmation when saving dual-domain settings; proxy must send Host $host and X-Forwarded-Proto. See Dual-domain separation.

Why can admin load on pages.dev / workers.dev / IP with dual-domain?

From v1.2.2: when dual-domain is on, PicHost returns 404 for Host values other than the configured site and image hostnames (localhost / 127.0.0.1 exempt in development). See Changelog.

If admin still loads:

1. Dual-domain not active (image URL set but site URL empty) — neither path split nor third-host blocking applies
2. Proxy rewrote Host to site hostname — e.g. Pages/Worker fetch(admin…) on the image hostname
3. Port 6892 exposed publicly — bypasses Cloudflare and Nginx server_name

Fix: configure both URLs in Settings; add a default server block; with orange cloud, allow only CF IPs on origin; do not full-proxy through Pages/Workers. See Dual-domain separation, Cloudflare deployment, and Changelog.

Can I deploy PicHost on Cloudflare Workers / Pages?

Not with the current codebase. PicHost needs node-server, SQLite, sharp, and local data/ — use Docker/VPS. Connecting the repo in “Create Worker” will not deploy successfully.

Recommended: run PicHost on origin; use proxied DNS (and optional R2 storage). Do not full-proxy the app through Pages/Workers.

Dual-domain: admin works but thumbnails break?

• Verify IMAGE_BASE_URL and proxy to the same instance
• Always open admin on the site hostname, not mixed with localhost
• See Dual-domain separation

Undeletable gallery items after v1.2 upgrade?

Likely orphan index rows (no file on disk). Startup sync removes them on restart. See v1.2 migration.

Do I still need data/blog/ after migration?

After migrate --apply, files live under data/images/blog/. Remove leftover empty dirs after backup if you like; dirs with non-image files are kept by the CLI.

Object storage only — run migrate?

No. Skip the CLI; startup sync focuses on local data/images/ scanning.

Replace old image URLs in posts?

Use data/mapping.json from migrate preview. Keys are storage paths, not full legacy URLs. See Migration.

Skip login during development?

DEV_BYPASS_ACCESS=true (local only). Use /setup for normal flows.

Docs vs README?

This VitePress site is the full guide; README is a short overview. Online: https://o96u.github.io/PicHost/

What should the GitHub repo About say?

For main:

• Description: Lightweight self-hosted image hosting — Docker, multi-user, gallery & API, local disk or S3-compatible storage.
• Website: https://o96u.github.io/PicHost/ (docs, not a live demo)

Do not claim the app runs on Cloudflare Pages/Workers. The cloudflare branch demo is pic.roven.cc.