release: v1.2.3 — 修复简短图片链接在按年/月存储下 404

开启简短链接时纯文件名直链先经 SQLite 索引反查完整 key，不再误解析为扁平 images/文件名路径。

.github/repository-metadata.json

@@ -1,6 +1,6 @@
 {
-  "description": "Self-hosted image hosting for your NAS / home server — Nuxt admin UI, local disk storage, server-side WebP compression, referer protection, Twikoo/EasyImage compatible.",
+  "description": "Lightweight self-hosted image hosting — Docker, multi-user, gallery & API, local disk or S3-compatible storage.",
-  "homepage": "https://github.com/O96u/PicHost#readme",
+  "homepage": "https://o96u.github.io/PicHost/",
   "topics": [
     "docker",
     "image-hosting",

.github/workflows/docs.yml

@@ -7,6 +7,8 @@ on:
       - 'docs-site/**'
       - 'docs/screenshots/**'
       - '.github/workflows/docs.yml'
+      - 'package.json'
+      - 'package-lock.json'
   workflow_dispatch:
 
 permissions:
@@ -21,6 +23,10 @@ concurrency:
 jobs:
   build:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
     steps:
       - name: Checkout
         uses: actions/checkout@v7
@@ -50,6 +56,9 @@ jobs:
   deploy:
     needs: build
     runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

CHANGELOG.md

@@ -4,6 +4,28 @@
 
 ## [Unreleased]
 
+## [1.2.3] - 2026-08-30
+
+### 修复
+
+- 开启「简短图片链接」且按年/月分组时，纯文件名直链（如 `/xxx.webp`）误解析为 `images/xxx.webp` 导致 404；现先经 SQLite 索引反查完整 key
+
+## [1.2.2] - 2026-08-30
+
+### 修复
+
+- 双域名：设置页保存时误清空管理域（`site_base_url`）；仅改图片域时保护已有网站域配置
+- 双域名：设置 API 配置值与 request origin fallback 混淆，导致「当前生效」显示错误
+- 双域名：未配置的第三 Host（`pages.dev`、裸 IP 等）可绕过 Host 隔离访问后台
+
+### 改进
+
+- 设置 API 拆分 `siteBaseUrl` / `imageBaseUrl`（配置值）、`effective*`（直链）、`runtime`（当前访问检测）
+- `PATCH /api/settings` 增加 `domainSeparation` 字段与保存校验
+- 设置页：检测地址展示、关闭双域名确认、反代 Host 不一致警告；首次设置不再自动填入 origin
+- Host 中间件：双域名开启时对未知 Host 返回 404（开发 `localhost` 例外）
+- 文档站：新增 [更新日志](https://o96u.github.io/PicHost/guide/changelog)；重写 Cloudflare 部署说明；同步 FAQ / 双域名文档
+
 ## [1.2.1] - 2026-08-29
 
 ### 新增

app/pages/logs.vue

@@ -100,9 +100,12 @@ function storageIcon(storage: ActivityLogStorage | null) {
 }
 
 function publicPathFromKey(key: string) {
-  if (!hideFolderInUrl.value) return key
+  if (hideFolderInUrl.value) {
-  const slash = key.lastIndexOf('/')
+    const slash = key.lastIndexOf('/')
-  return slash >= 0 ? key.slice(slash + 1) : key
+    return slash >= 0 ? key.slice(slash + 1) : key
+  }
+  const prefix = 'images/'
+  return key.startsWith(prefix) ? key.slice(prefix.length) : key
 }
 
 function imageUrl(key: string) {
@@ -115,10 +118,10 @@ function imageUrl(key: string) {
 async function loadImageLinkBase() {
   try {
     if (isAdmin.value) {
-      const data = await $fetch<{ imageBaseUrl: string, hideFolderInUrl: boolean }>('/api/settings', {
+      const data = await $fetch<{ effectiveImageBaseUrl: string, hideFolderInUrl: boolean }>('/api/settings', {
         credentials: 'include'
       })
-      imageLinkBase.value = data.imageBaseUrl
+      imageLinkBase.value = data.effectiveImageBaseUrl
       hideFolderInUrl.value = data.hideFolderInUrl
       return
     }

app/pages/settings/index.vue

@@ -14,10 +14,17 @@ interface SettingsResponse {
   imageBaseUrl: string
   imageBaseUrlConfigured: string
   imageBaseUrlSource: SettingSource
+  effectiveImageBaseUrl: string
   siteBaseUrl: string
   siteBaseUrlConfigured: string
   siteBaseUrlSource: SettingSource
+  effectiveSiteBaseUrl: string
   domainSeparation: boolean
+  runtime: {
+    currentOrigin: string
+    currentHost: string
+    hostRole: 'site' | 'image' | 'unknown' | 'single'
+  }
   hideFolderInUrl: boolean
   hideFolderInUrlSource: SettingSource
   storageUseDatePath: boolean
@@ -46,6 +53,8 @@ const hideFolderInUrlDraft = ref(false)
 const storageUseDatePathDraft = ref(true)
 const allowRegistrationDraft = ref(false)
 const domainSeparationDraft = ref(false)
+const disableDomainSeparationOpen = ref(false)
+const pendingDomainSeparationDisable = ref(false)
 
 interface ReleaseCheckResponse {
   currentVersion: string
@@ -60,8 +69,8 @@ const hasServerChanges = computed(() => {
   if (!settings.value) return false
   return refererDraft.value !== settings.value.allowedRefererHosts
     || domainSeparationDraft.value !== settings.value.domainSeparation
-    || siteBaseUrlDraft.value !== (settings.value.domainSeparation ? settings.value.siteBaseUrlConfigured : '')
+    || siteBaseUrlDraft.value !== (settings.value.domainSeparation ? settings.value.siteBaseUrl : '')
-    || imageBaseUrlDraft.value !== settings.value.imageBaseUrlConfigured
+    || imageBaseUrlDraft.value !== settings.value.imageBaseUrl
     || hideFolderInUrlDraft.value !== settings.value.hideFolderInUrl
     || storageUseDatePathDraft.value !== settings.value.storageUseDatePath
     || allowRegistrationDraft.value !== settings.value.allowRegistration
@@ -101,8 +110,8 @@ function errorStatus(error: unknown): number {
 function applySettings(data: SettingsResponse) {
   settings.value = data
   refererDraft.value = data.allowedRefererHosts
-  siteBaseUrlDraft.value = data.domainSeparation ? data.siteBaseUrlConfigured : ''
+  siteBaseUrlDraft.value = data.domainSeparation ? data.siteBaseUrl : ''
-  imageBaseUrlDraft.value = data.imageBaseUrlConfigured
+  imageBaseUrlDraft.value = data.imageBaseUrl
   hideFolderInUrlDraft.value = data.hideFolderInUrl
   storageUseDatePathDraft.value = data.storageUseDatePath
   allowRegistrationDraft.value = data.allowRegistration
@@ -130,25 +139,49 @@ function handlePatchError(error: unknown, fallback: string) {
   toast.add({ title: fallback, color: 'error' })
 }
 
+function fillDetectedSiteOrigin() {
+  if (settings.value?.runtime.currentOrigin) {
+    siteBaseUrlDraft.value = settings.value.runtime.currentOrigin
+  }
+}
+
 function onDomainSeparationDraftChange(next: boolean | 'indeterminate') {
   const enabled = next === true
-  domainSeparationDraft.value = enabled
+  if (!enabled && domainSeparationDraft.value) {
-  if (!enabled) {
+    pendingDomainSeparationDisable.value = true
-    siteBaseUrlDraft.value = ''
+    disableDomainSeparationOpen.value = true
     return
   }
-  if (!siteBaseUrlDraft.value && import.meta.client) {
+  domainSeparationDraft.value = enabled
-    siteBaseUrlDraft.value = window.location.origin
+}
-  }
+
+function confirmDisableDomainSeparation() {
+  domainSeparationDraft.value = false
+  siteBaseUrlDraft.value = ''
+  disableDomainSeparationOpen.value = false
+  pendingDomainSeparationDisable.value = false
+}
+
+function cancelDisableDomainSeparation() {
+  disableDomainSeparationOpen.value = false
+  pendingDomainSeparationDisable.value = false
 }
 
 async function saveServerSettings() {
   if (!isAuthenticated.value || !hasServerChanges.value) return
 
+  if (domainSeparationDraft.value) {
+    if (!siteBaseUrlDraft.value.trim() || !imageBaseUrlDraft.value.trim()) {
+      toast.add({ title: t('settings.domainSeparationRequired'), color: 'error' })
+      return
+    }
+  }
+
   savingServer.value = true
   try {
     await patchSettings({
       allowedRefererHosts: refererDraft.value,
+      domainSeparation: domainSeparationDraft.value,
       siteBaseUrl: domainSeparationDraft.value ? siteBaseUrlDraft.value : '',
       imageBaseUrl: imageBaseUrlDraft.value,
       hideFolderInUrl: hideFolderInUrlDraft.value,
@@ -375,6 +408,20 @@ watch(isAuthenticated, async (authed, prev) => {
                   </a>
                 </p>
 
+                <p
+                  v-if="settings.runtime.currentOrigin"
+                  class="text-xs text-muted"
+                >
+                  {{ t('settings.runtimeDetected', { url: settings.runtime.currentOrigin }) }}
+                </p>
+
+                <p
+                  v-if="domainSeparationDraft && settings.runtime.hostRole === 'unknown'"
+                  class="rounded-lg border border-error/25 bg-error/5 px-3 py-2.5 text-xs leading-relaxed text-error"
+                >
+                  {{ t('settings.hostRoleUnknown') }}
+                </p>
+
                 <div
                   v-if="domainSeparationDraft"
                   class="grid gap-4 sm:grid-cols-2"
@@ -393,17 +440,28 @@ watch(isAuthenticated, async (authed, prev) => {
                     <p class="text-xs leading-relaxed text-muted">
                       {{ t('settings.siteBaseUrlHint') }}
                     </p>
-                    <UInput
+                    <div class="flex gap-2">
-                      v-model="siteBaseUrlDraft"
+                      <UInput
-                      :placeholder="t('settings.siteBaseUrlPlaceholder')"
+                        v-model="siteBaseUrlDraft"
-                      class="w-full font-mono text-sm"
+                        :placeholder="t('settings.siteBaseUrlPlaceholder')"
-                    />
+                        class="min-w-0 flex-1 font-mono text-sm"
+                      />
+                      <UButton
+                        v-if="settings.runtime.currentOrigin"
+                        :label="t('settings.fillDetectedOrigin')"
+                        color="neutral"
+                        variant="outline"
+                        size="sm"
+                        class="shrink-0"
+                        @click="fillDetectedSiteOrigin"
+                      />
+                    </div>
                     <p
-                      v-if="settings.siteBaseUrl"
+                      v-if="settings.effectiveSiteBaseUrl"
                       class="truncate text-xs text-muted"
-                      :title="settings.siteBaseUrl"
+                      :title="settings.effectiveSiteBaseUrl"
                     >
-                      {{ t('settings.siteBaseUrlActive', { url: settings.siteBaseUrl }) }}
+                      {{ t('settings.siteBaseUrlActive', { url: settings.effectiveSiteBaseUrl }) }}
                     </p>
                   </div>
 
@@ -427,11 +485,11 @@ watch(isAuthenticated, async (authed, prev) => {
                       class="w-full font-mono text-sm"
                     />
                     <p
-                      v-if="settings.imageBaseUrl"
+                      v-if="settings.effectiveImageBaseUrl"
                       class="truncate text-xs text-muted"
-                      :title="settings.imageBaseUrl"
+                      :title="settings.effectiveImageBaseUrl"
                     >
-                      {{ t('settings.imageBaseUrlActive', { url: settings.imageBaseUrl }) }}
+                      {{ t('settings.imageBaseUrlActive', { url: settings.effectiveImageBaseUrl }) }}
                     </p>
                   </div>
                 </div>
@@ -459,11 +517,11 @@ watch(isAuthenticated, async (authed, prev) => {
                     class="w-full font-mono text-sm"
                   />
                   <p
-                    v-if="settings.imageBaseUrl"
+                    v-if="settings.effectiveImageBaseUrl"
                     class="truncate text-xs text-muted"
-                    :title="settings.imageBaseUrl"
+                    :title="settings.effectiveImageBaseUrl"
                   >
-                    {{ t('settings.imageBaseUrlActive', { url: settings.imageBaseUrl }) }}
+                    {{ t('settings.imageBaseUrlActive', { url: settings.effectiveImageBaseUrl }) }}
                   </p>
                 </div>
               </div>
@@ -570,6 +628,29 @@ watch(isAuthenticated, async (authed, prev) => {
         </div>
       </section>
     </AppShell>
+
+    <UModal
+      :open="disableDomainSeparationOpen"
+      :title="t('settings.disableDomainSeparationTitle')"
+      :description="t('settings.disableDomainSeparationDesc')"
+      @update:open="(v) => { if (!v) cancelDisableDomainSeparation() }"
+    >
+      <template #footer>
+        <div class="flex justify-end gap-2">
+          <UButton
+            :label="t('common.cancel')"
+            color="neutral"
+            variant="outline"
+            @click="cancelDisableDomainSeparation"
+          />
+          <UButton
+            :label="t('settings.disableDomainSeparationConfirm')"
+            color="warning"
+            @click="confirmDisableDomainSeparation"
+          />
+        </div>
+      </template>
+    </UModal>
   </div>
 </template>
 

app/pages/setup.vue

@@ -49,11 +49,12 @@ onMounted(async () => {
     await router.replace('/')
     return
   }
-  if (import.meta.client) {
-    siteBaseUrl.value = window.location.origin
-  }
 })
 
+const detectedOriginPlaceholder = computed(() =>
+  import.meta.client ? window.location.origin : ''
+)
+
 async function submit() {
   if (!canSubmit.value || loading.value) return
 
@@ -217,7 +218,7 @@ async function submit() {
               </p>
               <UInput
                 v-model="siteBaseUrl"
-                :placeholder="t('setup.siteBaseUrlPlaceholder')"
+                :placeholder="detectedOriginPlaceholder || t('setup.siteBaseUrlPlaceholder')"
                 class="w-full font-mono text-sm"
               />
             </div>

docs-site/.vitepress/config.ts

@@ -1,4 +1,5 @@
 import { defineConfig } from 'vitepress'
+import { withMermaid } from 'vitepress-plugin-mermaid'
 
 const docsBase = 'https://o96u.github.io/PicHost'
 
@@ -16,7 +17,8 @@ const zhSidebar = [
     items: [
       { text: '环境变量', link: '/guide/configuration' },
       { text: '反向代理', link: '/guide/reverse-proxy' },
-      { text: '双域名分离', link: '/guide/domain-separation' }
+      { text: '双域名分离', link: '/guide/domain-separation' },
+      { text: 'Cloudflare / CF 优选', link: '/guide/cloudflare-deployment' }
     ]
   },
   {
@@ -31,6 +33,7 @@ const zhSidebar = [
   {
     text: '升级',
     items: [
+      { text: '更新日志', link: '/guide/changelog' },
       { text: 'v1.2 迁移', link: '/guide/migration' },
       { text: '常见问题', link: '/guide/faq' }
     ]
@@ -51,7 +54,8 @@ const enSidebar = [
     items: [
       { text: 'Environment variables', link: '/en/guide/configuration' },
       { text: 'Reverse proxy', link: '/en/guide/reverse-proxy' },
-      { text: 'Dual-domain separation', link: '/en/guide/domain-separation' }
+      { text: 'Dual-domain separation', link: '/en/guide/domain-separation' },
+      { text: 'Cloudflare deployment', link: '/en/guide/cloudflare-deployment' }
     ]
   },
   {
@@ -66,17 +70,25 @@ const enSidebar = [
   {
     text: 'Upgrade',
     items: [
+      { text: 'Changelog', link: '/en/guide/changelog' },
       { text: 'v1.2 migration', link: '/en/guide/migration' },
       { text: 'FAQ', link: '/en/guide/faq' }
     ]
   }
 ]
 
-export default defineConfig({
+export default withMermaid(
+  defineConfig({
   base: '/PicHost/',
   title: 'PicHost',
   description: '自托管图床文档 · Self-hosted image hosting docs',
   head: [['link', { rel: 'icon', href: '/PicHost/favicon.ico' }]],
+  vite: {
+    optimizeDeps: {
+      // mermaid → fastdom 为 CJS；dev 模式须预构建，否则整站白屏
+      include: ['mermaid', 'fastdom']
+    }
+  },
   locales: {
     root: {
       label: '简体中文',
@@ -126,4 +138,5 @@ export default defineConfig({
       text: '在 GitHub 上编辑此页'
     }
   }
-})
+  })
+)

docs-site/en/guide/changelog.md

@@ -0,0 +1,121 @@
+# Changelog
+
+Version history and notable changes. The full log is also in the repo root [CHANGELOG.md](https://github.com/O96u/PicHost/blob/main/CHANGELOG.md).
+
+---
+
+## [1.2.3] — 2026-08-30
+
+### Fix
+
+- **Short links + date-based storage**: bare filename URLs (e.g. `https://host/xxx.webp`) no longer map to flat `images/xxx.webp`; SQLite index resolves the full `images/YYYY/MM/xxx.webp` key so thumbnails and short links work again
+
+---
+
+## [1.2.2] — 2026-08-30
+
+> **Restart the service** after upgrading so middleware and API updates take effect.
+
+### Dual-domain settings & Host isolation
+
+#### Fixes
+
+| Issue | Description |
+| ----- | ----------- |
+| Site URL cleared by mistake | Saving Settings could write an empty `site_base_url` when disabling dual-domain or editing only the image URL |
+| Config vs effective URL mixed | `GET /api/settings` used to blend DB values with `request.origin`, confusing the Settings UI |
+| Third-host bypass | Unlisted hosts (`pages.dev`, bare IP, old image domains) were not blocked by middleware |
+
+#### Improvements
+
+**Settings API (`GET /api/settings`)**
+
+| Field | Meaning |
+| ----- | ------- |
+| `siteBaseUrl` / `imageBaseUrl` | **Configured** values (DB → env), no request fallback |
+| `effectiveSiteBaseUrl` / `effectiveImageBaseUrl` | **Link generation**, falls back to request origin when unset |
+| `runtime.currentOrigin` | Detected access URL (display only, not saved) |
+| `runtime.hostRole` | `site` / `image` / `unknown` / `single` |
+
+**Save API (`PATCH /api/settings`)**
+
+- New body field `domainSeparation` (`true` / `false`)
+- `domainSeparation: true` requires both URLs with different hostnames
+- `domainSeparation: false` allows clearing the site URL
+- Without `domainSeparation`, cannot clear `siteBaseUrl` while dual-domain is active
+
+**Settings / setup UI**
+
+- Form uses configured values; “Active” line shows `effective*`
+- Shows detected access URL; **no longer** auto-fills `window.location.origin`
+- “Use detected URL” button (opt-in)
+- Confirmation modal when disabling dual-domain
+- Warning when `hostRole === 'unknown'` with dual-domain on
+
+**Host middleware**
+
+- When dual-domain is on, unlisted hosts get **404** at the app layer (all methods)
+- `localhost` / `127.0.0.1` exempt in development
+- Complements Nginx `default_server` — use both layers in production
+
+#### Docs
+
+- Rewrote [Cloudflare deployment](./cloudflare-deployment.md)
+- Updated [Dual-domain separation](./domain-separation.md) for third-host blocking
+- Added this changelog page
+
+#### Upgrade notes
+
+- **No** database migration or CLI step
+- If the site URL was cleared earlier: re-enter it in **Settings**, or set `SITE_BASE_URL` in env and restart
+- Production: match proxy `server_name` to Settings; keep a default server block
+
+---
+
+## [1.2.1] — 2026-08-29
+
+### Added
+
+- Slide puzzle login captcha
+- VitePress docs site on GitHub Pages
+- `npm run docs:dev` / `docs:build` / `docs:preview`
+
+### Fixed
+
+- Gallery not refreshing after delete on stats page
+- Pagination jump with `type="number"` input
+- Copy-link format preference not persisting off home route
+- Captcha UI alignment
+
+### Improved
+
+- README trimmed; details moved to docs
+- Dual-domain docs: unknown Host risk, Cloudflare guide
+
+---
+
+## [1.2.0] — 2026-08-28
+
+### Changed
+
+- All images under `data/images/`; legacy `blog/` / `twikoo/` need migration
+
+### Added
+
+- CLI: `docker exec pichost migrate` / `migrate --apply`
+- Startup index sync (disk scan, legacy key normalization, orphan cleanup)
+
+See [v1.2 migration](./migration.md).
+
+---
+
+## [1.1.x] summary
+
+| Version | Highlights |
+| ------- | ---------- |
+| 1.1.5 | API upload preview fix; file existence check before serve |
+| 1.1.4 | Date-based storage paths; site host blocks image URLs |
+| 1.1.3 | Dual-domain (`SITE_BASE_URL` / `IMAGE_BASE_URL`); Host middleware |
+| 1.1.0 | Multi storage backends (S3 / R2) |
+
+Older entries: [GitHub CHANGELOG](https://github.com/O96u/PicHost/blob/main/CHANGELOG.md).

docs-site/en/guide/cloudflare-deployment.md

@@ -0,0 +1,236 @@
+# Cloudflare & preferred-edge deployment
+
+In dual-domain mode, PicHost distinguishes **site** vs **image** traffic from the request **Host** (and `X-Forwarded-Host` from a trusted reverse proxy). Cloudflare orange cloud, preferred-edge IPs, Workers, and Pages are all fine — as long as the hostname identity reaching PicHost stays correct.
+
+> **One-line rule:** The network path may change; the hostname identity must not — `admin → admin`, `img → img`, never `img → admin`.
+
+See [Dual-domain separation](./domain-separation.md) for middleware behavior and [Reverse proxy](./reverse-proxy.md) for general proxy requirements.
+
+---
+
+## Quick checklist
+
+| # | Check | Expected |
+| - | ----- | -------- |
+| 1 | Browser hostname | `admin.*` or `img.*`; do not mix IP / `pages.dev` |
+| 2 | Pages / Worker in the middle | Image host must **not** `fetch(admin…)` |
+| 3 | Reverse-proxy upstream | Both hostnames → `http://127.0.0.1:6892` |
+| 4 | Nginx `proxy_set_header Host` | `$host` (preserve client hostname) |
+| 5 | PicHost settings | `SITE_BASE_URL` / `IMAGE_BASE_URL` match `server_name` |
+| 6 | Port `6892` | Reachable only from localhost or internal proxy |
+
+---
+
+## Recommended layout
+
+Both hostnames go through Cloudflare (proxied) and **independently** reverse-proxy to one PicHost instance:
+
+```mermaid
+flowchart TB
+  internet[Internet]
+  cf[Cloudflare proxied]
+  admin[admin.example.com]
+  img[img.example.com]
+  panel[1Panel / Nginx]
+  app[PicHost :6892]
+
+  internet --> cf
+  cf --> admin
+  cf --> img
+  admin --> panel
+  img --> panel
+  panel --> app
+```
+
+```env
+SITE_BASE_URL=https://admin.example.com
+IMAGE_BASE_URL=https://img.example.com
+```
+
+```text
+admin.example.com → http://127.0.0.1:6892
+img.example.com   → http://127.0.0.1:6892
+```
+
+You do **not** need separate ports for “frontend / backend / images” — one PicHost instance on port `6892` is enough.
+
+### Site hostname ≠ frontend domain
+
+| Hostname | Serves |
+| -------- | ------ |
+| `admin.example.com` | Admin UI, login, settings, gallery, API, upload |
+| `img.example.com` | Image delivery, hotlinks, CDN |
+
+Use **site / image hostname**, not “frontend / backend”. PicHost does **not** require `frontend :3000 + backend :6892` in production.
+
+---
+
+## Orange cloud & preferred edge
+
+**DNS Proxied (orange cloud)** is normal and recommended:
+
+```text
+admin.example.com, img.example.com
+  A/CNAME → origin → Proxied
+```
+
+Opening `admin.example.com` should yield `Host: admin.example.com` at PicHost; `img.example.com` should yield `Host: img.example.com`.
+
+**Preferred-edge** setups (alternate IPs, entry hostnames) are also fine. Preferred routing may change the path to Cloudflare’s edge, but must **not** rewrite the image hostname’s origin identity to the site hostname:
+
+```text
+admin → CF → admin.example.com → origin → PicHost
+img   → CF → img.example.com   → origin → PicHost
+```
+
+---
+
+## 6. Typical bad topologies
+
+These patterns break Host isolation even when the browser still shows the image hostname:
+
+### ❌ Bad 1: Image host fetches site host
+
+```mermaid
+flowchart LR
+  user[User on img.example.com]
+  worker[Pages / Worker]
+  admin[fetch admin.example.com]
+  app[PicHost]
+
+  user --> worker --> admin --> app
+```
+
+The last hop has `Host: admin.example.com`, so PicHost treats it as site traffic — `https://img.example.com/` may show the admin UI. This is **Host rewrite**, not a cache bug.
+
+### ❌ Bad 2: Preferred proxy upstreams to site host
+
+```text
+img.example.com → preferred hostname → admin.example.com → origin
+```
+
+Even for routing only, using the site hostname as upstream breaks image isolation.
+
+### ❌ Bad 3: Public exposure of port 6892
+
+```text
+any host / IP:6892 → PicHost
+```
+
+Users can bypass Cloudflare and Nginx `server_name` rules. Port `6892` should be reachable only from `127.0.0.1` or an internal reverse proxy.
+
+### ✅ Correct pattern
+
+```text
+admin → admin → PicHost
+img   → img   → PicHost
+```
+
+Do **not** use Pages / Workers as a **full-site reverse proxy** for PicHost (extra `pages.dev` / `workers.dev` entry points). PicHost needs `node-server`, SQLite, `sharp`, and local `data/` — it **cannot** run as a Node app on Pages/Workers. Keep Docker/VPS for the app; use orange-cloud DNS and optional R2 on CF.
+
+---
+
+## Workers / Pages guidance
+
+If you only need headers, auth, Referer rules, logging, or cache — and PicHost remains your origin:
+
+| Prefer | Avoid |
+| ------ | ----- |
+| `img.example.com` → **Worker Route** → existing `img` origin | `img` → Worker → `fetch(admin.example.com)` |
+
+Cloudflare recommends [Routes](https://developers.cloudflare.com/workers/configuration/routing/routes/) when an external origin already exists, rather than [Custom Domains](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/) used to chain cross-host `fetch()`.
+
+Code like this on the image hostname is a smoking gun:
+
+```js
+fetch(`https://admin.example.com${url.pathname}`)
+```
+
+---
+
+## Nginx / 1Panel layout
+
+Two `server` blocks, same upstream. Critical line: `proxy_set_header Host $host;`
+
+```nginx
+server {
+    server_name admin.example.com;
+    location / {
+        proxy_pass http://127.0.0.1:6892;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        client_max_body_size 12m;
+    }
+}
+
+server {
+    server_name img.example.com;
+    location / {
+        proxy_pass http://127.0.0.1:6892;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    }
+}
+
+# Reject bare IP and unknown hostnames (strongly recommended)
+server {
+    listen 80 default_server;
+    listen 443 ssl default_server;
+    server_name _;
+    return 444;
+}
+```
+
+With orange cloud, restrict the origin firewall to **[Cloudflare IP ranges](https://www.cloudflare.com/ips/)** only.
+
+---
+
+## Two-layer Host protection
+
+Use reverse proxy and application layers **together**:
+
+| Layer | Role |
+| ----- | ---- |
+| **Nginx default server** | Reject bare IP, `pages.dev`, and other undeclared hostnames |
+| **PicHost middleware (v1.2.x+)** | When dual-domain is on, unconfigured hosts get 404 at the app (`localhost` / `127.0.0.1` exempt in development) |
+
+Even with app-layer blocking, keep a default server at the proxy to reduce junk traffic to PicHost.
+
+---
+
+## X-Forwarded-Host
+
+PicHost may consult `X-Forwarded-Host` behind a reverse proxy, but that header is **forgeable** by clients. Therefore:
+
+- Do not expose port `6892` publicly
+- Only trusted proxies should reach the app
+- Prefer keeping `Host` correct from the first hop
+
+---
+
+## Troubleshooting: admin UI on image hostname?
+
+**Inspect the proxy chain first — do not purge CF cache first.**
+
+Cache issues usually mean stale JS/CSS/images or occasional 404s. If `/`, `/login`, and `/settings` work **reliably** on the image host, the Host was almost certainly rewritten.
+
+```text
+① Browser hostname?
+② Pages / Worker / preferred proxy in the middle?
+③ What URL does the proxy fetch?
+④ Does it fetch admin.example.com?
+⑤ Which Host does 1Panel / PicHost see?
+```
+
+---
+
+## Related
+
+- [Dual-domain separation](./domain-separation.md)
+- [Reverse proxy](./reverse-proxy.md)
+- [Environment variables](./configuration.md)
+- [FAQ](./faq.md)

docs-site/en/guide/configuration.md

@@ -9,8 +9,8 @@ Configure PicHost via environment variables (Docker / `.env`) or the in-app **Se
 | API upload token | Env → SQLite | **Yes** (cannot regenerate in UI) |
 | WebP quality | SQLite → env → default 80 | No |
 | Referer whitelist | SQLite → env | No |
-| Site / image base URL | SQLite → env → request origin | No |
+| Site / image base URL | SQLite → env (configured in API); links use `effective*` or request origin | No |
-| Hide `images/` prefix | SQLite → env → default false | No |
+| Short image links | SQLite → env → default false | No |
 | Date-based paths | SQLite → env → default true | No |
 | Global auto-delete days | SQLite → env → default 0 | No |
 
@@ -33,11 +33,13 @@ Comma-separated Referer whitelist. Own hostnames are allowed automatically. Opti
 - **Site URL**: admin UI, API, Twikoo upload
 - **Image URL**: copied links and public image URLs
 
-Single-domain: set `IMAGE_BASE_URL` only or leave empty (request origin). Dual-domain: hostnames must differ — see [Dual-domain separation](./domain-separation.md). Values must match proxy `server_name`; do not use `localhost`, IP, or unlisted hostnames for production admin access.
+Single-domain: set `IMAGE_BASE_URL` only or leave empty (request origin). Dual-domain: hostnames must differ — see [Dual-domain separation](./domain-separation.md) and [Cloudflare deployment](./cloudflare-deployment.md). Values must match proxy `server_name`; do not use `localhost`, IP, or unlisted hostnames for production admin access.
+
+In **Settings**, enable dual-domain explicitly and fill both URLs; disabling clears the site URL (with confirmation). Configured values vs effective link URLs are separate in the API — see [Changelog](./changelog.md#1-2-2-2026-08-30).
 
 ### `HIDE_FOLDER_IN_URL`
 
-`true` hides the `images/` prefix in public URLs.
+`true`: short links (domain + filename only), e.g. `img.example.com/a8K3xP.webp`. `false`: keep date or custom folders, e.g. `img.example.com/2026/08/a8K3xP.webp`. Public URLs never expose the internal `images/` prefix; legacy `/images/...` paths still work.
 
 ### `STORAGE_USE_DATE_PATH` / `STORAGE_LAYOUT`
 

docs-site/en/guide/domain-separation.md

@@ -16,6 +16,8 @@ Set during `/setup` or in **Settings**:
 - **Site URL**: `https://admin.example.com`
 - **Image URL**: `https://pic.example.com`
 
+Setup and Settings **do not** auto-fill the site URL from `window.location.origin`; use manual input or “Use detected URL”. Disabling dual-domain requires confirmation and clears the site URL. Saves include `domainSeparation: true/false`. See [Changelog](./changelog.md#1-2-2-2026-08-30).
+
 ## Nginx example
 
 ```nginx
@@ -53,36 +55,42 @@ server {
 
 ## Security notes
 
-### Middleware only splits the two configured hostnames
+### Middleware isolation and third hosts
 
 PicHost uses the request **Host** (and `X-Forwarded-Host` when proxied) to decide site vs image domain:
 
 - **Image host**: non-image paths (e.g. `/`, `/settings`) → 404
 - **Site host**: image URL paths (e.g. `/images/...`) → 404
+- **Unconfigured third hosts** (e.g. `*.pages.dev`, bare IP, old image domains): **from v1.2.x the app returns 404 for all methods** (`localhost` / `127.0.0.1` are exempt in development for `npm run dev`)
 
-If the Host is **neither** the configured site nor image hostname (e.g. `localhost`, the server **public IP**, Cloudflare **Pages** `*.pages.dev`, **Workers** `*.workers.dev`, or any other unlisted name), **the app does not block the request today** — admin and API may still be reachable. This is not about hyphenated or long domain names; it is an extra entry point outside your dual-domain pair.
+This is independent of hyphenated or long domain names. Older versions did not block third hosts; rely on a reverse-proxy default server as a complement in production.
 
 **Production recommendations:**
 
-1. Configure `server_name` only for the site and image hosts; add a **default server** to reject other Host values and bare IP access (see Nginx example above)
+1. Configure `server_name` only for the site and image hosts; add a **default server** to reject other Host values and bare IP access (see Nginx example above; complements app-layer blocking)
 2. With Cloudflare **orange-cloud** DNS, restrict the origin firewall to **[Cloudflare IP ranges](https://www.cloudflare.com/ips/)** so traffic cannot bypass the CDN
 3. Sign in only on the **site hostname** from Settings; do not mix `localhost`, IP, or unlisted domains
-4. Do **not** put Cloudflare Pages / Workers in front of PicHost as a **full-site reverse proxy** (extra `pages.dev` / `workers.dev` entry points worsen this issue)
+4. Do **not** put Cloudflare Pages / Workers in front of PicHost as a **full-site reverse proxy** (`IMAGE_BASE_URL` may point at a CDN URL, but the app itself should run on Docker/VPS)
-5. PicHost **cannot** run as-is on Pages/Workers (needs `node-server`, SQLite, `sharp`, local `data/`). Keep Docker/VPS; use orange-cloud DNS and optional R2 storage on CF
+5. If you must proxy at the edge, preserve the client **`Host` or `X-Forwarded-Host`** or host isolation will fail
+6. PicHost **cannot** run as-is on Pages/Workers (needs `node-server`, SQLite, `sharp`, local `data/`). Keep Docker/VPS; use orange-cloud DNS and optional R2 storage on CF
 
 ### Cloudflare orange cloud (incl. preferred edge IPs)
 
-**Recommended:** both `admin.example.com` and `pic.example.com` **DNS Proxied** → origin Nginx / 1Panel → port `6892`, SSL **Full (strict)** (origin cert or Cloudflare Origin Certificate).
+Full guide: [Cloudflare deployment](./cloudflare-deployment.md).
+
+**Recommended:** both `admin.example.com` and `pic.example.com` **DNS Proxied** → origin Nginx / 1Panel → port `6892`, SSL **Full (strict)**.
 
 | Feature | Notes |
 | ------- | ----- |
 | Orange-cloud CDN | Compatible with dual-domain; preserve `Host` and `X-Forwarded-Proto` on origin |
-| DNS “preferred IP” setups | Only changes which CF edge IP clients hit; Host stays your real domain |
+| DNS “preferred IP” setups | Only changes which CF edge IP clients hit; origin identity must stay **admin → admin**, **img → img** |
 | R2 storage | Add an R2 backend under **Storage**; independent of orange cloud |
 | `cloudflare` Git branch | R2-focused deployment line; still Docker, **not** Workers hosting |
 
 **Do not confuse** “Create Worker” in the CF dashboard (Git + `wrangler deploy`) with deploying PicHost — the repo uses `nitro.preset: 'node-server'` and is not Workers-ready.
 
+**Do not** chain the image hostname to `fetch(admin…)` via Pages/Workers — that rewrites Host and breaks isolation ([bad topologies](./cloudflare-deployment.md#6-typical-bad-topologies)).
+
 See [Reverse proxy](./reverse-proxy.md#cloudflare-orange-cloud) for origin hardening.
 
 ## FN NAS · Lucky reverse proxy
@@ -152,7 +160,7 @@ Always open admin on the **site hostname**, not `localhost` (cookies and Host mu
 | `http://admin.pichost.test:3000/images/...` or `/2026/08/xxx.webp` | **404** (use image host) |
 | `http://pic.pichost.test:3000/` | **404** (image host has no admin) |
 | `http://pic.pichost.test:3000/images/...` | Image served |
-| `http://localhost:3000/` or `http://127.0.0.1:3000/` | **Admin still loads** (third Host — isolation skipped; OK for dev only; block at proxy in production) |
+| `http://localhost:3000/` or `http://127.0.0.1:3000/` | **Admin still loads** (development exception; block unconfigured hosts at proxy in production) |
 
 After upload, copied links should use `pic.pichost.test`; gallery thumbnails should load.
 

docs-site/en/guide/faq.md

@@ -21,11 +21,15 @@ Check the **Referer whitelist** (`ALLOWED_REFERER_HOSTS` or Settings). Referring
 
 ## Why can admin load on pages.dev / workers.dev / IP with dual-domain?
 
-Dual-domain isolation only splits paths on the **configured site and image hostnames**. Other Host values (`localhost`, public IP, Cloudflare **Pages** `*.pages.dev`, **Workers** `*.workers.dev`, etc.) are **not blocked today**, so admin may appear on unexpected URLs.
+**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](./changelog.md#1-2-2-2026-08-30).
 
-Common cause: **full-site reverse proxy** via Pages/Workers on top of orange-cloud DNS, or an origin that accepts any Host / bare IP.
+If admin still loads:
 
-Fix: use only the two configured domains; add a default `server_name` block; with orange cloud, allow only CF IPs on the origin. See [Security notes](./domain-separation.md#security-notes).
+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](./domain-separation.md#middleware-isolation-and-third-hosts), [Cloudflare deployment](./cloudflare-deployment.md), and [Changelog](./changelog.md#1-2-2-2026-08-30).
 
 ## Can I deploy PicHost on Cloudflare Workers / Pages?
 
@@ -62,3 +66,12 @@ Use `data/mapping.json` from `migrate` preview. Keys are **storage paths**, not
 ## 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](https://pic.roven.cc).

docs-site/en/guide/index.md

@@ -6,8 +6,9 @@ Welcome to the PicHost user guide. This site is the single source of truth; the
 
 1. [Quick start](./getting-started.md) — Docker and first-time setup
 2. [Environment variables](./configuration.md) — Production config vs in-app settings
-3. [Storage](./storage.md) — Backends and URL modes
+3. [Changelog](./changelog.md) — Version history and upgrade notes
-4. [API](./api.md) — REST endpoints and tokens
+4. [Storage](./storage.md) — Backends and URL modes
+5. [API](./api.md) — REST endpoints and tokens
 
 ## Screenshots
 

docs-site/en/guide/local-dev.md

@@ -51,4 +51,4 @@ npm run docs:build
 npm run docs:preview
 ```
 
-Sources live in `docs-site/`; screenshot sources are in `docs/screenshots/` (including `login.png`), copied to `docs-site/public/screenshots/` before build.
+Sources live in `docs-site/`; screenshot sources are in `docs/screenshots/` (including `login.png`), copied to `docs-site/public/screenshots/` before build. Live docs: <https://o96u.github.io/PicHost/>

docs-site/en/guide/reverse-proxy.md

@@ -41,18 +41,18 @@ See [Dual-domain separation](./domain-separation.md).
 
 ## Cloudflare orange cloud
 
-Run PicHost on **your server / Docker** (port `6892`). On Cloudflare:
+See [Cloudflare deployment](./cloudflare-deployment.md).
 
 | Practice | Notes |
 | -------- | ----- |
 | **Proxied DNS** | Both admin and image hostnames → origin proxy to `6892`, SSL **Full (strict)** |
-| Preferred edge IPs | Compatible; Host remains your real domain |
+| Preferred edge IPs | Compatible; keep **admin → admin**, **img → img** on origin |
 | **R2** | Object storage backend in **Storage**; not the same as hosting the app on Pages |
 | Origin firewall | Allow only [Cloudflare IPs](https://www.cloudflare.com/ips/); do not expose `6892` publicly |
 
 **Avoid:**
 
-- **Cloudflare Pages** (`*.pages.dev`) or **Workers** (`*.workers.dev`) as a **full-site reverse proxy** to PicHost — extra hostnames can bypass dual-domain isolation ([Security notes](./domain-separation.md#security-notes))
+- **Cloudflare Pages** (`*.pages.dev`) or **Workers** (`*.workers.dev`) as a **full-site reverse proxy**, or chaining the image host to `fetch(admin…)` — rewrites Host and bypasses dual-domain isolation ([guide](./cloudflare-deployment.md))
 - “Create Worker” from Git on this repo — `node-server` preset is not Workers-ready
 
 ## Origin hardening (dual-domain)

docs-site/guide/changelog.md

@@ -0,0 +1,121 @@
+# 更新日志
+
+PicHost 版本历史与重要变更说明。完整记录亦见仓库根目录 [CHANGELOG.md](https://github.com/O96u/PicHost/blob/main/CHANGELOG.md)。
+
+---
+
+## [1.2.3] — 2026-08-30
+
+### 修复
+
+- **简短图片链接 + 按年/月分组**：纯文件名直链（如 `https://域名/xxx.webp`）不再误当成 `images/xxx.webp`，改为经 SQLite 索引反查 `images/年/月/xxx.webp`，缩略图与短链恢复正常
+
+---
+
+## [1.2.2] — 2026-08-30
+
+> 升级后请**重启服务**使中间件与 API 生效。
+
+### 双域名配置与 Host 隔离
+
+#### 修复
+
+| 问题 | 说明 |
+| ---- | ---- |
+| 管理域被误清空 | 设置页保存时，关闭双域名或仅改图片域可能把 `site_base_url` 写成空字符串，导致 UI 切回单域、管理域「消失」 |
+| 配置与生效 URL 混淆 | `GET /api/settings` 的 `siteBaseUrl` / `imageBaseUrl` 曾混入当前请求的 `origin`，设置页「当前生效」与数据库配置难以区分 |
+| 第三 Host 绕过隔离 | `pages.dev`、裸 IP、旧图片域等未纳入配置的 Host 此前不被中间件拦截，后台/API 可能仍可访问 |
+
+#### 改进
+
+**设置 API（`GET /api/settings`）**
+
+| 字段 | 含义 |
+| ---- | ---- |
+| `siteBaseUrl` / `imageBaseUrl` | **配置值**（DB → 环境变量），不含 request fallback |
+| `effectiveSiteBaseUrl` / `effectiveImageBaseUrl` | **直链生成用**，未配置时回退到当前请求 origin |
+| `runtime.currentOrigin` | 检测到的当前访问地址（仅展示，不写入配置） |
+| `runtime.hostRole` | `site` / `image` / `unknown` / `single` |
+
+**保存 API（`PATCH /api/settings`）**
+
+- 新增 body 字段 `domainSeparation`（`true` / `false`），显式表达是否启用双域名
+- `domainSeparation: true` 时网站域与图片域**均必填**，且主机名不能相同
+- `domainSeparation: false` 时允许清空网站域
+- 未传 `domainSeparation` 且双域名已配置时，**禁止**单独把 `siteBaseUrl` 置空
+
+**设置页 / 首次设置**
+
+- 表单回填配置值；「当前生效」显示 `effective*` 字段
+- 展示「检测到当前访问」地址，**不再**自动写入 `window.location.origin`
+- 提供「填入检测地址」按钮（用户主动点击才填）
+- 关闭双域名需确认弹窗
+- 双域名开启且 `hostRole === 'unknown'` 时显示反代绕过警告
+
+**Host 中间件**
+
+- 双域名开启时，非 site/image 的 Host **应用层一律 404**（所有 HTTP 方法）
+- 开发环境 `localhost` / `127.0.0.1` 例外，便于 `npm run dev`
+- 与 Nginx `default_server` **互补**，建议两层都配置
+
+#### 文档
+
+- 重写 [Cloudflare / CF 优选部署](./cloudflare-deployment.md)（精简结构、检查清单、双层防护）
+- 更新 [双域名分离](./domain-separation.md) 第三 Host 与应用层拦截说明
+- 新增本页 **更新日志**
+
+#### 升级说明
+
+- **无需**数据库迁移或 CLI 操作
+- 若管理域此前已被误清空：在 **设置** 中重新填写网站域，或设置环境变量 `SITE_BASE_URL` 后重启
+- 生产双域名部署：确认反代 `server_name` 与设置一致；建议保留 Nginx default server
+
+---
+
+## [1.2.1] — 2026-08-29
+
+### 新增
+
+- 登录滑动拼图验证（缺口对齐）；验证与登录分两步
+- VitePress 文档站（`docs-site/`），部署至 GitHub Pages
+- `npm run docs:dev` / `docs:build` / `docs:preview`
+
+### 修复
+
+- 统计页删除图片后图库不刷新
+- 分页跳转输入框在 `type="number"` 下无法跳转
+- 非首页路由下复制链接格式偏好不持久化
+- 滑动验证 UI：滑块垂直居中、缺口尺寸与滑块一致
+
+### 改进
+
+- README 精简，详细说明迁入文档站
+- 双域名文档补充未知 Host 风险与 Cloudflare 部署说明
+
+---
+
+## [1.2.0] — 2026-08-28
+
+### 变更
+
+- 图片统一存放在 `data/images/`；遗留 `blog/`、`twikoo/` 等并列目录需迁移
+
+### 新增
+
+- CLI：`docker exec pichost migrate` / `migrate --apply`
+- 启动时自动同步图片索引（扫描磁盘、归一化遗留 key、清理孤儿记录）
+
+详见 [v1.2 迁移](./migration.md)。
+
+---
+
+## [1.1.x] 摘要
+
+| 版本 | 要点 |
+| ---- | ---- |
+| 1.1.5 | API 上传后预览偶发失败修复；出图前校验文件存在 |
+| 1.1.4 | 按年/月分组存储；网站域禁止直链出图 |
+| 1.1.3 | 双域名分离（`SITE_BASE_URL` / `IMAGE_BASE_URL`）；Host 中间件 |
+| 1.1.0 | 多存储后端（S3 / R2 等） |
+
+更早版本见 [GitHub CHANGELOG](https://github.com/O96u/PicHost/blob/main/CHANGELOG.md)。

docs-site/guide/cloudflare-deployment.md

@@ -0,0 +1,240 @@
+# Cloudflare / CF 优选部署说明
+
+PicHost 双域名模式下，应用根据请求 **Host**（及可信反代转发的 `X-Forwarded-Host`）区分**管理域**与**图片域**。使用 Cloudflare 橙云、优选线路、Workers 或 Pages 时，只要最终到达 PicHost 的 Host 身份不变，即可正常工作。
+
+> **一句话原则：** 网络线路可以改变，请求的域名身份不能改变 — `admin → admin`，`img → img`，不要 `img → admin`。
+
+基础概念见 [双域名分离](./domain-separation.md)；反代通用要求见 [反向代理](./reverse-proxy.md)。
+
+---
+
+## 快速检查清单
+
+部署或排错时，按顺序确认：
+
+| # | 检查项 | 期望 |
+| - | ------ | ---- |
+| 1 | 浏览器地址栏域名 | `admin.*` 或 `img.*`，不要用 IP / `pages.dev` 混用 |
+| 2 | 中间是否经过 Pages / Worker | 图片域**不得** `fetch(admin…)` |
+| 3 | 反代 upstream | 两个域名均指向 `http://127.0.0.1:6892` |
+| 4 | Nginx `proxy_set_header Host` | `$host`（保持客户端域名） |
+| 5 | PicHost 设置 | `SITE_BASE_URL` / `IMAGE_BASE_URL` 与 `server_name` 一致 |
+| 6 | 端口 `6892` | 仅本机或内网反代可达，不对公网裸露 |
+
+---
+
+## 推荐拓扑
+
+两个域名经 Cloudflare（橙云）后，**各自独立**反代到同一 PicHost 实例：
+
+```mermaid
+flowchart TB
+  internet[Internet]
+  cf[Cloudflare 橙云]
+  admin[admin.example.com]
+  img[img.example.com]
+  panel[1Panel / Nginx]
+  app[PicHost :6892]
+
+  internet --> cf
+  cf --> admin
+  cf --> img
+  admin --> panel
+  img --> panel
+  panel --> app
+```
+
+```env
+SITE_BASE_URL=https://admin.example.com
+IMAGE_BASE_URL=https://img.example.com
+```
+
+```text
+admin.example.com → http://127.0.0.1:6892
+img.example.com   → http://127.0.0.1:6892
+```
+
+不需要为「前端 / 后端 / 图片」开不同端口；一个 PicHost 实例、一个内部端口（默认 `6892`）即可。
+
+### 管理域 ≠ 前端域名
+
+| 域名 | 用途 |
+| ---- | ---- |
+| `admin.example.com` | 后台、登录、设置、图库、API、上传 |
+| `img.example.com` | 图片直链、外链、CDN 分发 |
+
+更准确的说法是**管理域 / 图片域**，而非「前端 / 后端」。PicHost 生产环境也**不需要** `前端 :3000 + 后端 :6892` 这种拆分。
+
+---
+
+## Cloudflare 橙云与 CF 优选
+
+**橙云（DNS Proxied）** 是正常且推荐的方式：
+
+```text
+admin.example.com、img.example.com
+  A / CNAME → 源站 → Proxied
+```
+
+用户访问 `admin.example.com` 时，PicHost 应收到 `Host: admin.example.com`；访问 `img.example.com` 时应收到 `Host: img.example.com`。
+
+**CF 优选**（优选 IP、优选域名、边缘入口）同样可用。优选可以改变用户到 Cloudflare 边缘的路径，但**不能**把图片域的回源身份变成管理域。两个域名应保持平行、独立的回源链：
+
+```text
+admin → CF → admin.example.com → 源站 → PicHost
+img   → CF → img.example.com   → 源站 → PicHost
+```
+
+---
+
+## 六、典型错误拓扑
+
+以下方案会破坏 Host 隔离，即使浏览器地址栏仍显示图片域：
+
+### ❌ 错误 1：图片域 fetch 到管理域
+
+```mermaid
+flowchart LR
+  user[用户 img.example.com]
+  worker[Pages / Worker]
+  admin[fetch admin.example.com]
+  app[PicHost]
+
+  user --> worker --> admin --> app
+```
+
+最后一跳 Host 变成 `admin.example.com`，PicHost 会认为这是管理域 — `https://img.example.com/` 可能看到后台。这是 **Host 被改写**，不是缓存问题。
+
+### ❌ 错误 2：优选回源到管理域
+
+```text
+img.example.com → 优选域名 → admin.example.com → 源站
+```
+
+即使只为改善线路，只要 upstream 使用管理域，图片域隔离即失效。
+
+### ❌ 错误 3：公网直接暴露 6892
+
+```text
+任意域名 / IP:6892 → PicHost
+```
+
+用户可绕开 Cloudflare 与 Nginx 的 `server_name` 限制。`6892` 应仅允许 `127.0.0.1` 或内网反代访问。
+
+### ✅ 正确做法
+
+```text
+admin → admin → PicHost
+img   → img   → PicHost
+```
+
+**不要** Pages / Workers **整站反代** PicHost（会多出 `pages.dev` / `workers.dev` 等第三入口）。PicHost 依赖 `node-server`、SQLite、`sharp` 与本地 `data/`，**不能**作为 Node 应用直接部署到 Pages/Workers；应用本体继续 Docker/VPS 部署，CF 侧用橙云 DNS + 可选 R2 即可。
+
+---
+
+## Workers / Pages 使用建议
+
+若只需改响应头、鉴权、防盗链、日志或缓存，且源站仍是自己的 PicHost：
+
+| 推荐 | 不推荐 |
+| ---- | ------ |
+| `img.example.com` → **Worker Route** → 原 `img` 源站 | `img` → Worker → `fetch(admin.example.com)` |
+
+Cloudflare 对已有外部源站的场景更推荐 [Routes](https://developers.cloudflare.com/workers/configuration/routing/routes/)（在现有 proxied 域名与源站之前运行），而非用 [Custom Domain](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/) 把 Worker 当作跨域 fetch 的中转。
+
+Worker 中若出现：
+
+```js
+fetch(`https://admin.example.com${url.pathname}`)
+```
+
+即基本可确定隔离被破坏。
+
+---
+
+## Nginx / 1Panel 配置
+
+两个 `server` 块，upstream 相同，**关键行**是 `proxy_set_header Host $host;`：
+
+```nginx
+server {
+    server_name admin.example.com;
+    location / {
+        proxy_pass http://127.0.0.1:6892;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        client_max_body_size 12m;
+    }
+}
+
+server {
+    server_name img.example.com;
+    location / {
+        proxy_pass http://127.0.0.1:6892;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    }
+}
+
+# 拒绝裸 IP 与未配置域名（强烈建议）
+server {
+    listen 80 default_server;
+    listen 443 ssl default_server;
+    server_name _;
+    return 444;
+}
+```
+
+橙云部署时，源站防火墙建议**仅放行 [Cloudflare IP 段](https://www.cloudflare.com/ips/)**，避免绕过 CDN 直连。
+
+---
+
+## 双层 Host 防护
+
+生产环境建议反代层与应用层**互补**，而非二选一：
+
+| 层级 | 作用 |
+| ---- | ---- |
+| **Nginx default server** | 拒绝裸 IP、`pages.dev` 等未在 `server_name` 中声明的 Host |
+| **PicHost 中间件（v1.2.x+）** | 双域名开启时，非 site/image 的 Host 应用层返回 404（开发环境 `localhost` / `127.0.0.1` 例外） |
+
+即使应用层已拦截第三 Host，仍建议在反代配置 default server — 减少无效流量到达 PicHost。
+
+---
+
+## X-Forwarded-Host 说明
+
+PicHost 在反代场景会参考 `X-Forwarded-Host` 识别请求域名，但**不能无条件信任**该 Header（客户端可伪造）。因此：
+
+- 不要让 `6892` 对公网裸露
+- 确保只有可信反代能到达应用
+- 首选方案仍是让 `Host` 从第一跳起就保持正确
+
+---
+
+## 排查：图片域能看到后台？
+
+**先查反代链，不要先清 CF 缓存。**
+
+缓存问题通常表现为旧 JS/CSS/图片或偶发 404；若图片域能**稳定**访问 `/`、`/login`、`/settings`，几乎都是 Host 被改写。
+
+```text
+① 浏览器实际域名？
+② 是否经过 Pages / Worker / 优选反代？
+③ 代理最终 fetch 的 URL？
+④ 是否 fetch 到 admin.example.com？
+⑤ 1Panel / PicHost 最终收到的 Host？
+```
+
+---
+
+## 相关
+
+- [双域名分离](./domain-separation.md) — 中间件行为与本地测试
+- [反向代理](./reverse-proxy.md) — 单域名与源站加固
+- [环境变量](./configuration.md) — `SITE_BASE_URL`、`IMAGE_BASE_URL`
+- [常见问题](./faq.md) — Pages / Workers 与第三 Host

docs-site/guide/configuration.md

@@ -9,8 +9,8 @@ PicHost 支持通过环境变量（Docker / `.env`）与后台 **设置** 页配
 | API 上传 Token | 环境变量 → SQLite | **是**（设了则后台无法重新生成） |
 | WebP 质量 | SQLite → 环境变量 → 默认 80 | 否（未在 DB 存时读 env） |
 | 防盗链白名单 | SQLite → 环境变量 | 否 |
-| 网站 / 图片域名 | SQLite → 环境变量 → 当前请求 | 否 |
+| 网站 / 图片域名 | SQLite → 环境变量（设置 API 配置值）；直链生成另用 `effective*` 或请求 origin | 否 |
-| 隐藏 `images/` 前缀 | SQLite → 环境变量 → 默认 false | 否 |
+| 简短图片链接 | SQLite → 环境变量 → 默认 false | 否 |
 | 按年/月分组存储 | SQLite → 环境变量 → 默认 true | 否 |
 | 全局自动删除天数 | SQLite → 环境变量 → 默认 0 | 否 |
 
@@ -33,11 +33,13 @@ PicHost 支持通过环境变量（Docker / `.env`）与后台 **设置** 页配
 - **网站域名**：管理后台、API、Twikoo 上传入口
 - **图片域名**：复制链接与直链使用的公网地址
 
-双域名分离需两者主机名不同，详见 [双域名分离](./domain-separation.md)。填写后须与反代 `server_name` 一致；**勿**通过 `localhost`、IP 或未配置的域名访问生产后台。
+双域名分离需两者主机名不同，详见 [双域名分离](./domain-separation.md) 与 [Cloudflare / CF 优选部署](./cloudflare-deployment.md)。填写后须与反代 `server_name` 一致；**勿**通过 `localhost`、IP 或未配置的域名访问生产后台。
+
+在后台 **设置** 中保存时须显式勾选「启用后台与图片域名分离」，并同时填写两个域名；关闭双域名会清除网站域配置（需确认）。设置 API 返回的配置值与「当前生效」直链地址已分离，详见 [更新日志](./changelog.md#1-2-2-2026-08-30)。
 
 ### `HIDE_FOLDER_IN_URL`
 
-`true` 时直链隐藏 `images/` 前缀（如 `images/2026/08/a.webp` → `/2026/08/a.webp` 或仅文件名，取决于路径模式）。
+`true` 时使用简短图片链接（仅域名 + 文件名，如 `img.example.com/a8K3xP.webp`）；`false` 时保留日期或自定义目录（如 `img.example.com/2026/08/a8K3xP.webp`）。对外 URL **不会** 暴露内部 `images/` 前缀；旧版含 `images/` 的直链仍兼容。
 
 ### `STORAGE_USE_DATE_PATH` / `STORAGE_LAYOUT`
 

docs-site/guide/domain-separation.md

@@ -19,6 +19,8 @@
 - **网站域名**：`https://admin.example.com`
 - **图片域名**：`https://pic.example.com`
 
+首次设置与系统设置**不会**自动把当前浏览器地址写入网站域；可手动填写或点击「填入检测地址」。关闭双域名需确认，且会清除网站域配置。保存时 API 会收到 `domainSeparation: true/false` 字段。详见 [更新日志](./changelog.md#1-2-2-2026-08-30)。
+
 ## Nginx 示例
 
 ```nginx
@@ -56,36 +58,42 @@ server {
 
 ## 安全与注意事项
 
-### 中间件只隔离「已配置的两个域名」
+### 中间件隔离与第三 Host
 
 PicHost 根据请求 **Host**（反代会转发为 `X-Forwarded-Host`，应用会一并识别）判断当前是网站域还是图片域：
 
 - **图片域**：非图片路径（如 `/`、`/settings`）→ 404
 - **网站域**：图片直链路径（如 `/images/...`）→ 404
+- **未配置的第三 Host**（如 `*.pages.dev`、裸 IP、旧图片域）：**v1.2.x 起应用层一律 404**（开发环境 `localhost` / `127.0.0.1` 例外，便于 `npm run dev`）
 
-若 Host **既不是网站域也不是图片域**（例如 `localhost`、服务器 **公网 IP**、Cloudflare **Pages** 的 `*.pages.dev`、**Workers** 的 `*.workers.dev`、或其它未在设置里填写的域名），**当前版本不会拦截**，后台与 API 仍可能被访问。这与域名是否带 `-`、长短无关，而是多了一条未纳入双域名配置的入口。
+这与域名是否带 `-`、长短无关；此前版本对第三 Host 不拦截，需依赖反代 default server 封堵。
 
 **生产环境建议：**
 
-1. 反代层仅为网站域、图片域配置 `server_name`，并增加 **default server** 拒绝其它 Host 与裸 IP（见上方 Nginx 示例）
+1. 反代层仅为网站域、图片域配置 `server_name`，并增加 **default server** 拒绝其它 Host 与裸 IP（见上方 Nginx 示例，与应用层拦截互补）
 2. 使用 Cloudflare **橙云** 时，源站防火墙 **仅放行 [Cloudflare IP 段](https://www.cloudflare.com/ips/)**，避免绕过 CDN 直连源站
 3. **仅使用** 设置中的网站域名登录后台，不要用 `localhost`、IP 或未配置的域名混用
-4. **不要** 用 Cloudflare Pages / Workers 对 PicHost **整站反代**（会多出 `pages.dev` / `workers.dev` 等第三入口，且易出现上述绕过）
+4. **不要** 用 Cloudflare Pages / Workers 对 PicHost **整站反代**（会多出 `pages.dev` / `workers.dev` 等第三入口；`IMAGE_BASE_URL` 可填 CDN 公网地址，但应用本体应 Docker/VPS 部署）
-5. PicHost **不能** 作为 Node 应用直接部署到 Pages/Workers（依赖 `node-server`、SQLite、`sharp` 与本地 `data/`）；应用请继续 Docker/VPS 部署，CF 侧用橙云 DNS + 可选 R2 存储即可
+5. 若必须在边缘做反代，须保留客户端 **`Host` 或 `X-Forwarded-Host`**，否则 Host 隔离会失效
+6. PicHost **不能** 作为 Node 应用直接部署到 Pages/Workers（依赖 `node-server`、SQLite、`sharp` 与本地 `data/`）；应用请继续 Docker/VPS 部署，CF 侧用橙云 DNS + 可选 R2 存储即可
 
 ### Cloudflare 橙云（含 DNS 优选）
 
-**推荐架构：** `admin.example.com` 与 `pic.example.com` 均 **DNS Proxied（橙云）** → 源站 Nginx / 1Panel 反代 `6892`，SSL 模式 **Full (strict)**（源站可用 Cloudflare Origin Certificate）。
+完整说明见专章：[Cloudflare / CF 优选部署](./cloudflare-deployment.md)。
+
+**推荐：** `admin.example.com` 与 `pic.example.com` 均 **DNS Proxied（橙云）** → 源站 Nginx / 1Panel 反代 `6892`，SSL 模式 **Full (strict)**。
 
 | 能力 | 说明 |
 | ---- | ---- |
 | 橙云 CDN | 与 PicHost 双域名兼容；回源须保留 `Host`、`X-Forwarded-Proto` |
-| DNS 优选 | 仅改变用户连到 CF 边缘的 IP，Host 仍为正式域名，无额外配置 |
+| DNS 优选 | 仅改变用户连到 CF 边缘的 IP；**admin → admin、img → img** 的回源身份不能变 |
 | R2 对象存储 | 在 **存储** 页添加 R2 后端即可，与是否橙云无关 |
 | `cloudflare` Git 分支 | R2 专用部署线，仍是 Docker 运行，**不是** Workers 托管 |
 
 **勿混淆：** CF 控制台「创建 Worker」并连接本仓库 **无法** 直接部署 PicHost；`npm run build` + `wrangler deploy` 与当前 `node-server` 预设不兼容。
 
+**勿用 Pages/Worker 把图片域 `fetch` 到管理域** — 会破坏 Host 隔离（详见 [Cloudflare 部署说明 · 典型错误拓扑](./cloudflare-deployment.md#六典型错误拓扑)）。
+
 反代与源站加固详见 [反向代理](./reverse-proxy.md#cloudflare-橙云)。
 
 ## 飞牛 NAS · Lucky 反向代理
@@ -157,7 +165,7 @@ npm run dev
 | `http://admin.pichost.test:3000/images/...` 或 `/2026/08/xxx.webp` | **404**（请用图片域直链） |
 | `http://pic.pichost.test:3000/` | **404**（正常，图片域不提供后台） |
 | `http://pic.pichost.test:3000/images/...` | 能出图 |
-| `http://localhost:3000/` 或 `http://127.0.0.1:3000/` | **能打开后台**（第三 Host，隔离不生效；仅开发可接受，生产须用反代封禁） |
+| `http://localhost:3000/` 或 `http://127.0.0.1:3000/` | **能打开后台**（开发环境例外；生产须用反代封禁未配置 Host） |
 
 上传一张图后，复制链接应指向 `pic.pichost.test` 域名；在后台图库中缩略图也应能正常显示。
 
@@ -169,4 +177,4 @@ npm run dev
 - 单域名部署可不启用分离，仅配置 `IMAGE_BASE_URL` 或使用默认当前访问域名
 - 配置了 Referer 防盗链时，网站域与图片域会自动加入白名单，无需手写两个域名
 
-单域名反代要点见 [反向代理](./reverse-proxy.md)。英文版：[Dual-domain separation](/en/guide/domain-separation)
+单域名反代要点见 [反向代理](./reverse-proxy.md)。

docs-site/guide/faq.md

@@ -22,11 +22,15 @@ docker exec pichost reset-password 用户名
 
 ## 双域名下为什么用 pages.dev / workers.dev / IP 也能进后台？
 
-PicHost 双域名隔离**只对已配置的网站域、图片域做路径分流**；其它 Host（`localhost`、公网 IP、Cloudflare Pages 的 `*.pages.dev`、Workers 的 `*.workers.dev` 等）**当前不会拦截**，因此可能出现「奇怪地址也能开后台」。
+**v1.2.2 起：** 双域名开启时，PicHost 中间件会对**未配置的网站域、图片域之外**的 Host 返回 **404**（开发环境 `localhost` / `127.0.0.1` 例外）。详见 [更新日志](./changelog.md#1-2-2-2026-08-30)。
 
-常见原因：在橙云之外又用 **Pages/Workers 整站反代** 到源站，或源站未限制 `server_name` / 允许裸 IP 访问。
+若仍能访问，常见原因：
 
-处理：仅用正式两个域名访问；反代加 default server；橙云时源站只放行 CF IP。详见 [双域名分离 · 安全与注意事项](./domain-separation.md#安全与注意事项)。
+1. **未启用双域名**（仅配置了图片域、网站域为空）— 隔离与第三 Host 拦截均不生效
+2. **反代把 Host 改成管理域** — 例如 Pages/Worker 对图片域 `fetch(admin…)`，PicHost 看到的是管理域
+3. **源站裸暴露 `6892`** — 绕过 Cloudflare 与 Nginx `server_name`
+
+处理：在设置中正确配置双域名；反代加 default server；橙云时源站只放行 CF IP；勿用 Pages/Workers 整站反代。详见 [双域名分离](./domain-separation.md#中间件隔离与第三-host)、[Cloudflare 部署](./cloudflare-deployment.md) 与 [更新日志](./changelog.md#1-2-2-2026-08-30)。
 
 ## 能把 PicHost 部署到 Cloudflare Workers / Pages 吗？
 
@@ -63,3 +67,12 @@ PicHost 双域名隔离**只对已配置的网站域、图片域做路径分流*
 ## 文档与仓库 README 哪个为准？
 
 **本 VitePress 文档站** 为完整用户指南；README 保留摘要与快速开始。在线地址：<https://o96u.github.io/PicHost/>
+
+## GitHub 仓库 About 怎么写？
+
+**main** 分支建议：
+
+- **Description**：`Lightweight self-hosted image hosting — Docker, multi-user, gallery & API, local disk or S3-compatible storage.`
+- **Website**：`https://o96u.github.io/PicHost/`（文档站，非图床演示）
+
+勿写「部署在 Cloudflare Pages/Workers」—— PicHost 应用跑在 Docker/VPS；**cloudflare** 分支在线演示为 [pic.roven.cc](https://pic.roven.cc)。

docs-site/guide/index.md

@@ -6,8 +6,9 @@
 
 1. [快速开始](./getting-started.md) — Docker 部署与首次设置
 2. [环境变量](./configuration.md) — 生产环境配置与后台设置对照
-3. [存储](./storage.md) — 多后端与直链模式
+3. [更新日志](./changelog.md) — 版本变更与升级说明
-4. [API](./api.md) — REST 接口与 Token
+4. [存储](./storage.md) — 多后端与直链模式
+5. [API](./api.md) — REST 接口与 Token
 
 ## 截图预览
 

docs-site/guide/local-dev.md

@@ -51,4 +51,4 @@ npm run docs:build    # 构建静态站点
 npm run docs:preview  # 预览构建结果
 ```
 
-文档源码在 `docs-site/`；截图源文件在 `docs/screenshots/`（含 `login.png` 登录页），构建前会复制到 `docs-site/public/screenshots/`。
+文档源码在 `docs-site/`；截图源文件在 `docs/screenshots/`（含 `login.png` 登录页），构建前会复制到 `docs-site/public/screenshots/`。在线文档：<https://o96u.github.io/PicHost/>

docs-site/guide/migration.md

@@ -174,5 +174,3 @@ CLI 只负责**搬文件**；索引对齐、遗留 key、孤儿记录由启动
 | `docker exec pichost migrate` | 预览磁盘迁移 |
 | `docker exec pichost migrate --apply` | 执行磁盘迁移 |
 | `docker exec pichost reset-password` | 重置密码（与迁移无关） |
-
-英文版：[v1.2 migration guide](/en/guide/migration)

docs-site/guide/reverse-proxy.md

@@ -41,18 +41,18 @@ IMAGE_BASE_URL=https://pic.example.com
 
 ## Cloudflare 橙云
 
-PicHost 应用运行在 **自有服务器 / Docker**（端口 `6892`），Cloudflare 侧推荐：
+详见专章：[Cloudflare / CF 优选部署](./cloudflare-deployment.md)。
 
 | 做法 | 说明 |
 | ---- | ---- |
-| **DNS 橙云** | `admin` / `pic` 两个子域 Proxied → 源站反代 `6892`，SSL **Full (strict)** |
+| **DNS 橙云** | `admin` / `img` 两个子域 Proxied → 源站反代 `6892`，SSL **Full (strict)** |
-| **DNS 优选** | 与 PicHost 兼容；Host 仍为正式域名 |
+| **DNS 优选** | 与 PicHost 兼容；须保持 **admin → admin、img → img** 回源 |
 | **R2** | 在存储页作对象后端，非 Pages 托管应用 |
 | **源站防火墙** | 仅放行 [Cloudflare IP](https://www.cloudflare.com/ips/)，禁止公网直连 `6892` |
 
 **不建议：**
 
-- 用 **Cloudflare Pages**（`*.pages.dev`）或 **Workers**（`*.workers.dev`）对 PicHost **整站反代** — 会多出第三 Host，且可能绕过双域名隔离（见 [双域名分离 · 安全与注意事项](./domain-separation.md#安全与注意事项)）
+- 用 **Cloudflare Pages**（`*.pages.dev`）或 **Workers**（`*.workers.dev`）对 PicHost **整站反代**，或让图片域 **fetch 到管理域** — 会改写 Host、绕过双域名隔离（见 [Cloudflare 部署说明](./cloudflare-deployment.md)）
 - 在 CF 控制台「从 Git 创建 Worker」部署本仓库 — 当前为 `node-server` 预设，无法直接 `wrangler deploy`
 
 ## 源站安全（双域名推荐）

i18n/locales/en.json

@@ -198,8 +198,15 @@
     "imageBaseUrlSingleHint": "No trailing slash; leave empty to use the current request host; single-domain setups do not need a site URL",
     "imageBaseUrlPlaceholder": "https://pic.example.com",
     "imageBaseUrlActive": "Active: {url}",
-    "hideFolderInUrl": "Hide folder in image URLs",
+    "runtimeDetected": "Detected current access: {url} (will not be saved automatically)",
-    "hideFolderInUrlHint": "Links become /file.webp without folder or date paths; legacy full paths still work. Identical filenames under different subpaths may collide on short URLs",
+    "fillDetectedOrigin": "Use detected URL",
+    "hostRoleUnknown": "Current Host does not match configured domains; reverse-proxy bypass may be possible",
+    "disableDomainSeparationTitle": "Disable domain separation",
+    "disableDomainSeparationDesc": "This clears the site URL and keeps only the image URL. Continue?",
+    "disableDomainSeparationConfirm": "Disable",
+    "domainSeparationRequired": "Both site and image URLs are required when domain separation is enabled",
+    "hideFolderInUrl": "Use short image links",
+    "hideFolderInUrlHint": "When on, links are only domain + filename, e.g. img.example.com/abc.webp. When off, date or custom folders are kept, e.g. img.example.com/2026/08/abc.webp",
     "storageUseDatePath": "Group uploads by year/month",
     "storageUseDatePathHint": "When enabled, files are stored as images/2026/08/file.webp; when disabled, as images/file.webp. Applies only to new uploads after enabling",
     "badgeEnv": ".env",

i18n/locales/zh-CN.json

@@ -198,8 +198,15 @@
     "imageBaseUrlSingleHint": "末尾不加 /；留空则使用当前访问域名；单域名部署无需填写网站域名",
     "imageBaseUrlPlaceholder": "https://pic.example.com",
     "imageBaseUrlActive": "当前生效：{url}",
-    "hideFolderInUrl": "隐藏直链目录前缀",
+    "runtimeDetected": "检测到当前访问：{url}（不会自动写入配置）",
-    "hideFolderInUrlHint": "开启后直链为 /xxx.webp，不含 images/ 或日期路径；旧完整路径仍可用。子路径下若存在同名文件，短链可能冲突",
+    "fillDetectedOrigin": "填入检测地址",
+    "hostRoleUnknown": "当前访问 Host 与配置不一致，可能存在反代绕过风险",
+    "disableDomainSeparationTitle": "关闭域名分离",
+    "disableDomainSeparationDesc": "将清除管理域名配置，仅保留图片域名。确定继续？",
+    "disableDomainSeparationConfirm": "确认关闭",
+    "domainSeparationRequired": "启用域名分离时需同时填写网站域名与图片域名",
+    "hideFolderInUrl": "使用简短图片链接",
+    "hideFolderInUrlHint": "开启后链接仅含域名与文件名，例如 img.example.com/abc.webp；关闭后保留日期或自定义目录，例如 img.example.com/2026/08/abc.webp",
     "storageUseDatePath": "上传目录按年/月分组",
     "storageUseDatePathHint": "开启后保存为 images/2026/08/xxx.webp；关闭则为 images/xxx.webp。仅影响启用后的新上传",
     "badgeEnv": ".env",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "pichost",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Self-hosted image hosting for your NAS / home server — Nuxt admin UI, local disk or S3-compatible storage, server-side WebP compression, referer protection, Twikoo/EasyImage compatible.",
   "homepage": "https://github.com/O96u/PicHost#readme",
   "repository": {
@@ -53,8 +53,10 @@
     "@nuxt/eslint": "^1.16.0",
     "@types/node": "^22.15.0",
     "eslint": "^10.6.0",
+    "mermaid": "^11.17.2",
     "typescript": "^6.0.3",
     "vitepress": "^1.6.4",
+    "vitepress-plugin-mermaid": "^2.0.17",
     "vitest": "^3.2.4",
     "vue-tsc": "^3.3.5"
   }

server/api/settings/index.patch.ts

@@ -23,7 +23,7 @@ import {
   parseAutoDeleteDays,
   parseWebpQuality,
   setGlobalAutoDeletePolicy,
-  validateDomainSeparationPair
+  validateSettingsDomainPatch
 } from '../../utils/env'
 
 interface SettingsPatchBody {
@@ -31,6 +31,7 @@ interface SettingsPatchBody {
   allowedRefererHosts?: unknown
   siteBaseUrl?: unknown
   imageBaseUrl?: unknown
+  domainSeparation?: unknown
   hideFolderInUrl?: unknown
   storageUseDatePath?: unknown
   autoDeleteDays?: unknown
@@ -71,6 +72,11 @@ export default defineEventHandler(async (event) => {
     setSetting(SETTINGS_ALLOWED_REFERER_HOSTS, normalized)
   }
 
+  const existingSite = normalizeSiteBaseUrl(getSetting(SETTINGS_SITE_BASE_URL) ?? '')
+  const existingImage = normalizeImageBaseUrl(getSetting(SETTINGS_IMAGE_BASE_URL) ?? '')
+  let nextSite = existingSite
+  let nextImage = existingImage
+
   if (body.siteBaseUrl !== undefined) {
     const configured = normalizeSiteBaseUrl(
       typeof body.siteBaseUrl === 'string' ? body.siteBaseUrl : ''
@@ -79,11 +85,11 @@ export default defineEventHandler(async (event) => {
       createApiError(
         event,
         'INVALID_REQUEST',
-        'SITE_BASE_URL 需为 http(s) 地址，或留空使用当前请求域名',
+        'SITE_BASE_URL 需为 http(s) 地址，且末尾不加 /',
         400
       )
     }
-    setSetting(SETTINGS_SITE_BASE_URL, configured)
+    nextSite = configured
   }
 
   if (body.imageBaseUrl !== undefined) {
@@ -98,22 +104,36 @@ export default defineEventHandler(async (event) => {
         400
       )
     }
-    setSetting(SETTINGS_IMAGE_BASE_URL, configured)
+    nextImage = configured
   }
 
-  if (body.siteBaseUrl !== undefined || body.imageBaseUrl !== undefined) {
+  const domainSeparationProvided = body.domainSeparation !== undefined
-    const siteConfigured = normalizeSiteBaseUrl(
+  const wantSeparation = domainSeparationProvided
-      getSetting(SETTINGS_SITE_BASE_URL) ?? ''
+    ? Boolean(body.domainSeparation)
-    )
+    : null
-    const imageConfigured = normalizeImageBaseUrl(
+
-      getSetting(SETTINGS_IMAGE_BASE_URL) ?? ''
+  const patchError = validateSettingsDomainPatch({
-    )
+    existingSite,
-    if (siteConfigured && imageConfigured) {
+    existingImage,
-      const pairError = validateDomainSeparationPair(siteConfigured, imageConfigured)
+    nextSite,
-      if (pairError) {
+    nextImage,
-        createApiError(event, 'INVALID_REQUEST', pairError, 400)
+    wantSeparation,
-      }
+    siteBaseUrlProvided: body.siteBaseUrl !== undefined
-    }
+  })
+  if (patchError) {
+    createApiError(event, 'INVALID_REQUEST', patchError, 400)
+  }
+
+  if (wantSeparation === false) {
+    nextSite = ''
+  }
+
+  if (body.siteBaseUrl !== undefined || body.domainSeparation !== undefined) {
+    setSetting(SETTINGS_SITE_BASE_URL, nextSite)
+  }
+
+  if (body.imageBaseUrl !== undefined) {
+    setSetting(SETTINGS_IMAGE_BASE_URL, nextImage)
   }
 
   if (body.autoDeleteDays !== undefined) {

server/middleware/00-host-isolation.ts

@@ -1,9 +1,17 @@
-import { shouldBlockImageHostRequest, shouldBlockSiteHostImageRequest } from '../utils/host-isolation'
+import {
+  shouldBlockImageHostRequest,
+  shouldBlockSiteHostImageRequest,
+  shouldBlockUnknownHostRequest
+} from '../utils/host-isolation'
 
 const HOST_ISOLATION_CACHE_CONTROL = 'private, no-cache, max-age=0'
 
 export default defineEventHandler((event) => {
-  if (shouldBlockImageHostRequest(event) || shouldBlockSiteHostImageRequest(event)) {
+  if (
+    shouldBlockUnknownHostRequest(event)
+    || shouldBlockImageHostRequest(event)
+    || shouldBlockSiteHostImageRequest(event)
+  ) {
     setHeader(event, 'Cache-Control', HOST_ISOLATION_CACHE_CONTROL)
     throw createError({ statusCode: 404, statusMessage: 'Not Found' })
   }

server/utils/env.test.ts

@@ -8,6 +8,7 @@ import {
   getAutoDeleteDays,
   getAutoDeleteDaysSource,
   getRefererSource,
+  getSettingsPayload,
   getSiteBaseUrl,
   getSiteBaseUrlConfigured,
   getSiteBaseUrlSource,
@@ -17,13 +18,15 @@ import {
   isAutoDeleteDaysEnvConfigured,
   isRefererEnvConfigured,
   isWebpQualityEnvConfigured,
-  validateDomainSeparationPair
+  validateDomainSeparationPair,
+  validateSettingsDomainPatch
 } from './env'
 import {
   getSetting,
   SETTINGS_ALLOWED_REFERER_HOSTS,
   SETTINGS_API_UPLOAD_TOKEN,
   SETTINGS_AUTO_DELETE_DAYS,
+  SETTINGS_IMAGE_BASE_URL,
   SETTINGS_SITE_BASE_URL,
   SETTINGS_WEBP_QUALITY,
   generateApiUploadToken
@@ -255,3 +258,65 @@ describe('validateDomainSeparationPair', () => {
     )).toBeNull()
   })
 })
+
+describe('validateSettingsDomainPatch', () => {
+  const dualExisting = {
+    existingSite: 'https://admin.example.com',
+    existingImage: 'https://pic.example.com'
+  }
+
+  it('requires both URLs when enabling domain separation', () => {
+    expect(validateSettingsDomainPatch({
+      ...dualExisting,
+      nextSite: '',
+      nextImage: 'https://pic.example.com',
+      wantSeparation: true,
+      siteBaseUrlProvided: true
+    })).toContain('同时填写')
+  })
+
+  it('blocks clearing site without explicit disable when dual domain is active', () => {
+    expect(validateSettingsDomainPatch({
+      ...dualExisting,
+      nextSite: '',
+      nextImage: 'https://pic.example.com',
+      wantSeparation: null,
+      siteBaseUrlProvided: true
+    })).toContain('不能单独清空管理域名')
+  })
+
+  it('allows clearing site when explicitly disabling domain separation', () => {
+    expect(validateSettingsDomainPatch({
+      ...dualExisting,
+      nextSite: '',
+      nextImage: 'https://pic.example.com',
+      wantSeparation: false,
+      siteBaseUrlProvided: true
+    })).toBeNull()
+  })
+})
+
+describe('getSettingsPayload configured vs effective', () => {
+  afterEach(() => {
+    vi.clearAllMocks()
+    delete process.env.SITE_BASE_URL
+    delete process.env.IMAGE_BASE_URL
+  })
+
+  it('returns configured site URL without request fallback', () => {
+    vi.mocked(getSetting).mockImplementation((key) => {
+      if (key === SETTINGS_SITE_BASE_URL) return 'https://admin.example.com'
+      if (key === SETTINGS_IMAGE_BASE_URL) return 'https://pic.example.com'
+      return null
+    })
+    vi.stubGlobal('getRequestURL', () => new URL('https://pages.dev'))
+
+    const event = mockEvent()
+    const payload = getSettingsPayload(event)
+
+    expect(payload.siteBaseUrl).toBe('https://admin.example.com')
+    expect(payload.effectiveSiteBaseUrl).toBe('https://admin.example.com')
+    expect(payload.runtime.currentHost).toBe('pages.dev')
+    expect(payload.runtime.hostRole).toBe('unknown')
+  })
+})

server/utils/env.ts

@@ -465,12 +465,102 @@ export function validateDomainSeparationPair(
   return null
 }
 
+export type RequestHostRole = 'site' | 'image' | 'unknown' | 'single'
+
+export function getIsolationRequestHost(event: H3Event): string {
+  const requestUrl = getRequestURL(event, {
+    xForwardedHost: true,
+    xForwardedProto: true
+  })
+  return requestUrl.hostname.toLowerCase()
+}
+
+export function validateSettingsDomainPatch(input: {
+  existingSite: string
+  existingImage: string
+  nextSite: string
+  nextImage: string
+  wantSeparation: boolean | null
+  siteBaseUrlProvided: boolean
+}): string | null {
+  const {
+    existingSite,
+    existingImage,
+    nextSite,
+    nextImage,
+    wantSeparation,
+    siteBaseUrlProvided
+  } = input
+
+  const hadDualDomain = (() => {
+    const siteHost = hostnameFromBaseUrl(existingSite)
+    const imageHost = hostnameFromBaseUrl(existingImage)
+    return Boolean(siteHost && imageHost && siteHost !== imageHost)
+  })()
+
+  if (wantSeparation === true) {
+    if (!nextSite || !nextImage) {
+      return '启用域名分离时需同时填写网站域名与图片域名'
+    }
+    return validateDomainSeparationPair(nextSite, nextImage)
+  }
+
+  if (wantSeparation === false) {
+    return null
+  }
+
+  if (siteBaseUrlProvided && !nextSite && existingSite && hadDualDomain) {
+    return '已启用域名分离时不能单独清空管理域名，请显式关闭域名分离'
+  }
+
+  if (nextSite && nextImage) {
+    return validateDomainSeparationPair(nextSite, nextImage)
+  }
+
+  return null
+}
+
+export function getRequestRuntime(event: H3Event) {
+  const requestUrl = getRequestURL(event, {
+    xForwardedHost: true,
+    xForwardedProto: true
+  })
+  const currentHost = requestUrl.hostname.toLowerCase()
+  const currentOrigin = requestUrl.origin
+
+  if (!isDomainSeparationActive(event)) {
+    return {
+      currentOrigin,
+      currentHost,
+      hostRole: 'single' as const
+    }
+  }
+
+  const siteHost = hostnameFromBaseUrl(getSiteBaseUrlConfigured(event))
+  const imageHost = hostnameFromBaseUrl(getImageBaseUrlConfigured(event))
+
+  let hostRole: RequestHostRole = 'unknown'
+  if (currentHost === siteHost) {
+    hostRole = 'site'
+  } else if (currentHost === imageHost) {
+    hostRole = 'image'
+  }
+
+  return {
+    currentOrigin,
+    currentHost,
+    hostRole
+  }
+}
+
 export function getSettingsPayload(event: H3Event) {
   const config = useRuntimeConfig(event)
   const webpQuality = getWebpQuality(event)
   const allowedRefererHosts = getAllowedRefererHostsRaw(event)
-  const siteBaseUrl = getSiteBaseUrl(event)
+  const siteBaseUrlConfigured = getSiteBaseUrlConfigured(event)
-  const imageBaseUrl = getImageBaseUrl(event)
+  const imageBaseUrlConfigured = getImageBaseUrlConfigured(event)
+  const effectiveSiteBaseUrl = getSiteBaseUrl(event)
+  const effectiveImageBaseUrl = getImageBaseUrl(event)
   const autoDeleteDays = getAutoDeleteDays(event)
   const appVersion = config.appVersion as string
   const domainSeparation = isDomainSeparationActive(event)
@@ -488,13 +578,16 @@ export function getSettingsPayload(event: H3Event) {
     allowedRefererHosts,
     refererSource: getRefererSource(),
     refererEnvFallback: getRefererHostsFromEnv(),
-    siteBaseUrl,
+    siteBaseUrl: siteBaseUrlConfigured,
-    siteBaseUrlConfigured: getSiteBaseUrlConfigured(event),
+    siteBaseUrlConfigured,
     siteBaseUrlSource: getSiteBaseUrlSource(event),
-    imageBaseUrl,
+    imageBaseUrl: imageBaseUrlConfigured,
-    imageBaseUrlConfigured: getImageBaseUrlConfigured(event),
+    imageBaseUrlConfigured,
     imageBaseUrlSource: getImageBaseUrlSource(event),
+    effectiveSiteBaseUrl,
+    effectiveImageBaseUrl,
     domainSeparation,
+    runtime: getRequestRuntime(event),
     hideFolderInUrl,
     hideFolderInUrlSource,
     storageUseDatePath,
@@ -507,8 +600,8 @@ export function getSettingsPayload(event: H3Event) {
     env: {
       webpQuality,
       refererConfigured: allowedRefererHosts.length > 0,
-      siteBaseUrl,
+      siteBaseUrl: effectiveSiteBaseUrl,
-      imageBaseUrl,
+      imageBaseUrl: effectiveImageBaseUrl,
       hideFolderInUrl,
       appVersion
     }

server/utils/host-isolation.test.ts

@@ -2,7 +2,8 @@ import { describe, expect, it } from 'vitest'
 import type { H3Event } from 'h3'
 import {
   shouldBlockImageHostRequest,
-  shouldBlockSiteHostImageRequest
+  shouldBlockSiteHostImageRequest,
+  shouldBlockUnknownHostRequest
 } from './host-isolation'
 
 function mockEvent(): H3Event {
@@ -96,6 +97,18 @@ describe('shouldBlockSiteHostImageRequest', () => {
     })).toBe(true)
   })
 
+  it('blocks public image paths on site host', () => {
+    const event = mockEvent()
+    expect(shouldBlockSiteHostImageRequest(event, {
+      separationActive: true,
+      siteHost,
+      requestHost: siteHost,
+      method: 'GET',
+      pathname: '/2026/08/demo.webp',
+      hideFolder: false
+    })).toBe(true)
+  })
+
   it('blocks legacy date short paths on site host', () => {
     const event = mockEvent()
     expect(shouldBlockSiteHostImageRequest(event, {
@@ -130,3 +143,71 @@ describe('shouldBlockSiteHostImageRequest', () => {
     })).toBe(false)
   })
 })
+
+describe('shouldBlockUnknownHostRequest', () => {
+  const imageHost = 'image.example.com'
+  const siteHost = 'admin.example.com'
+
+  it('does not block when separation is inactive', () => {
+    const event = mockEvent()
+    expect(shouldBlockUnknownHostRequest(event, {
+      separationActive: false,
+      requestHost: 'pages.dev',
+      siteHost,
+      imageHost
+    })).toBe(false)
+  })
+
+  it('blocks unconfigured third host when separation is active', () => {
+    const event = mockEvent()
+    expect(shouldBlockUnknownHostRequest(event, {
+      separationActive: true,
+      requestHost: 'pages.dev',
+      siteHost,
+      imageHost
+    })).toBe(true)
+  })
+
+  it('blocks admin paths on image host when host is unconfigured', () => {
+    const event = mockEvent()
+    expect(shouldBlockUnknownHostRequest(event, {
+      separationActive: true,
+      requestHost: 'old-img.example.com',
+      siteHost,
+      imageHost
+    })).toBe(true)
+  })
+
+  it('allows configured site host', () => {
+    const event = mockEvent()
+    expect(shouldBlockUnknownHostRequest(event, {
+      separationActive: true,
+      requestHost: siteHost,
+      siteHost,
+      imageHost
+    })).toBe(false)
+  })
+
+  it('allows configured image host', () => {
+    const event = mockEvent()
+    expect(shouldBlockUnknownHostRequest(event, {
+      separationActive: true,
+      requestHost: imageHost,
+      siteHost,
+      imageHost
+    })).toBe(false)
+  })
+
+  it('allows localhost in development', () => {
+    const previous = process.env.NODE_ENV
+    process.env.NODE_ENV = 'development'
+    const event = mockEvent()
+    expect(shouldBlockUnknownHostRequest(event, {
+      separationActive: true,
+      requestHost: 'localhost',
+      siteHost,
+      imageHost
+    })).toBe(false)
+    process.env.NODE_ENV = previous
+  })
+})

server/utils/host-isolation.ts

@@ -8,6 +8,20 @@ import {
 } from './env'
 import { requestPathToImageKey } from './serve-image'
 
+const DEV_LOCAL_HOSTS = new Set(['localhost', '127.0.0.1'])
+
+function getIsolationRequestHost(event: H3Event): string {
+  const requestUrl = getRequestURL(event, {
+    xForwardedHost: true,
+    xForwardedProto: true
+  })
+  return requestUrl.hostname.toLowerCase()
+}
+
+function isDevLocalHost(host: string): boolean {
+  return process.env.NODE_ENV === 'development' && DEV_LOCAL_HOSTS.has(host)
+}
+
 export function getConfiguredSiteHost(event: H3Event): string | null {
   return hostnameFromBaseUrl(getSiteBaseUrlConfigured(event))
 }
@@ -16,6 +30,30 @@ export function getConfiguredImageHost(event: H3Event): string | null {
   return hostnameFromBaseUrl(getImageBaseUrlConfigured(event))
 }
 
+/** 双域名开启时，拒绝未配置的第三 Host（开发环境 localhost 例外） */
+export function shouldBlockUnknownHostRequest(
+  event: H3Event,
+  options?: {
+    requestHost?: string
+    separationActive?: boolean
+    siteHost?: string | null
+    imageHost?: string | null
+  }
+): boolean {
+  const separationActive = options?.separationActive ?? isDomainSeparationActive(event)
+  if (!separationActive) return false
+
+  const siteHost = options?.siteHost ?? getConfiguredSiteHost(event)
+  const imageHost = options?.imageHost ?? getConfiguredImageHost(event)
+  if (!siteHost || !imageHost) return false
+
+  const requestHost = (options?.requestHost ?? getIsolationRequestHost(event)).toLowerCase()
+  if (requestHost === siteHost || requestHost === imageHost) return false
+  if (isDevLocalHost(requestHost)) return false
+
+  return true
+}
+
 export function shouldBlockImageHostRequest(
   event: H3Event,
   options?: {
@@ -34,19 +72,16 @@ export function shouldBlockImageHostRequest(
   const imageHost = options?.imageHost ?? getConfiguredImageHost(event)
   if (!imageHost) return false
 
-  const requestUrl = options?.requestHost
+  const requestHost = (options?.requestHost ?? getIsolationRequestHost(event)).toLowerCase()
-    ? null
-    : getRequestURL(event, {
-        xForwardedHost: true,
-        xForwardedProto: true
-      })
-  const requestHost = (options?.requestHost ?? requestUrl?.hostname ?? '').toLowerCase()
   if (requestHost !== imageHost) return false
 
   const method = (options?.method ?? getMethod(event)).toUpperCase()
   if (method !== 'GET' && method !== 'HEAD') return true
 
-  const pathname = options?.pathname ?? requestUrl?.pathname ?? ''
+  const pathname = options?.pathname ?? getRequestURL(event, {
+    xForwardedHost: true,
+    xForwardedProto: true
+  }).pathname
   const hideFolder = options?.hideFolder ?? isHideFolderInUrl(event)
   return requestPathToImageKey(pathname, {
     hideFolder
@@ -71,19 +106,16 @@ export function shouldBlockSiteHostImageRequest(
   const siteHost = options?.siteHost ?? getConfiguredSiteHost(event)
   if (!siteHost) return false
 
-  const requestUrl = options?.requestHost
+  const requestHost = (options?.requestHost ?? getIsolationRequestHost(event)).toLowerCase()
-    ? null
-    : getRequestURL(event, {
-        xForwardedHost: true,
-        xForwardedProto: true
-      })
-  const requestHost = (options?.requestHost ?? requestUrl?.hostname ?? '').toLowerCase()
   if (requestHost !== siteHost) return false
 
   const method = (options?.method ?? getMethod(event)).toUpperCase()
   if (method !== 'GET' && method !== 'HEAD') return false
 
-  const pathname = options?.pathname ?? requestUrl?.pathname ?? ''
+  const pathname = options?.pathname ?? getRequestURL(event, {
+    xForwardedHost: true,
+    xForwardedProto: true
+  }).pathname
   const hideFolder = options?.hideFolder ?? isHideFolderInUrl(event)
   return requestPathToImageKey(pathname, {
     hideFolder

server/utils/image-public-path.test.ts

@@ -2,13 +2,16 @@ import { describe, expect, it } from 'vitest'
 import {
   isBareImageFilename,
   isHiddenImageDatePath,
-  toPublicImagePath
+  storageKeyToPublicPath,
+  toPublicImagePath,
+  toStorageKeyFromPublicPath
 } from './image-public-path'
 
 describe('toPublicImagePath', () => {
-  it('returns key unchanged when hideFolder is false', () => {
+  it('strips internal images/ prefix when hideFolder is false', () => {
-    expect(toPublicImagePath('images/2026/08/a.webp', false)).toBe('images/2026/08/a.webp')
+    expect(toPublicImagePath('images/2026/08/a.webp', false)).toBe('2026/08/a.webp')
-    expect(toPublicImagePath('images/a.webp', false)).toBe('images/a.webp')
+    expect(toPublicImagePath('images/a.webp', false)).toBe('a.webp')
+    expect(toPublicImagePath('images/blog/a.webp', false)).toBe('blog/a.webp')
   })
 
   it('returns basename when hideFolder is true', () => {
@@ -18,6 +21,29 @@ describe('toPublicImagePath', () => {
   })
 })
 
+describe('storageKeyToPublicPath', () => {
+  it('removes images/ prefix only', () => {
+    expect(storageKeyToPublicPath('images/2026/08/a.webp')).toBe('2026/08/a.webp')
+  })
+})
+
+describe('toStorageKeyFromPublicPath', () => {
+  it('maps public relative paths to storage keys', () => {
+    expect(toStorageKeyFromPublicPath('2026/08/a.webp')).toBe('images/2026/08/a.webp')
+    expect(toStorageKeyFromPublicPath('blog/a.webp')).toBe('images/blog/a.webp')
+    expect(toStorageKeyFromPublicPath('a.webp')).toBe('images/a.webp')
+  })
+
+  it('accepts legacy full storage keys', () => {
+    expect(toStorageKeyFromPublicPath('images/2026/08/a.webp')).toBe('images/2026/08/a.webp')
+  })
+
+  it('rejects invalid paths', () => {
+    expect(toStorageKeyFromPublicPath('')).toBeNull()
+    expect(toStorageKeyFromPublicPath('../../../etc/passwd')).toBeNull()
+  })
+})
+
 describe('isHiddenImageDatePath', () => {
   it('accepts YYYY/MM/file paths', () => {
     expect(isHiddenImageDatePath('2026/08/demo.webp')).toBe(true)

server/utils/image-public-path.ts

@@ -1,9 +1,30 @@
 import { basename } from 'node:path'
+import { DEFAULT_FOLDER, validateImageKey } from './image-key'
 
-/** 对外 URL 路径：可选隐藏目录前缀（输出纯文件名） */
+/** 存储 key → 对外 URL 路径（不含域名） */
+export function storageKeyToPublicPath(key: string): string {
+  const prefix = `${DEFAULT_FOLDER}/`
+  if (key.startsWith(prefix)) return key.slice(prefix.length)
+  return key
+}
+
+/**
+ * 对外 URL 路径：
+ * - hideFolder=true：仅文件名（img.com/a8K3xP.webp）
+ * - hideFolder=false：去掉内部 images/ 前缀（img.com/2026/08/a.webp）
+ */
 export function toPublicImagePath(key: string, hideFolder: boolean): string {
-  if (!hideFolder) return key
+  if (hideFolder) return basename(key)
-  return basename(key)
+  return storageKeyToPublicPath(key)
+}
+
+/** 公开相对路径 → 存储 key；legacy 完整 key（含 images/）仍接受 */
+export function toStorageKeyFromPublicPath(publicPath: string): string | null {
+  const raw = publicPath.replace(/^\/+/, '')
+  if (!raw) return null
+  if (validateImageKey(raw)) return raw
+  const candidate = `${DEFAULT_FOLDER}/${raw}`
+  return validateImageKey(candidate) ? candidate : null
 }
 
 const HIDDEN_DATE_PATH_PATTERN

server/utils/serve-image-path.test.ts

@@ -1,10 +1,31 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi, afterEach } from 'vitest'
+import { findImageKeyByDatePath, findImageKeyByFilename } from './image-index'
 import { requestPathToImageKey } from './serve-image'
 
+vi.mock('./image-index', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('./image-index')>()
+  return {
+    ...actual,
+    findImageKeyByFilename: vi.fn(actual.findImageKeyByFilename),
+    findImageKeyByDatePath: vi.fn(actual.findImageKeyByDatePath)
+  }
+})
+
 describe('requestPathToImageKey hide folder', () => {
-  it('resolves bare filename to default folder flat key', () => {
+  afterEach(() => {
+    vi.mocked(findImageKeyByFilename).mockReset()
+    vi.mocked(findImageKeyByDatePath).mockReset()
+  })
+
+  it('resolves bare filename via index when hide folder is enabled', () => {
+    vi.mocked(findImageKeyByFilename).mockReturnValue('images/2026/08/demo.webp')
     expect(requestPathToImageKey('/demo.webp', { hideFolder: true }))
-      .toBe('images/demo.webp')
+      .toBe('images/2026/08/demo.webp')
+  })
+
+  it('does not guess flat images/name when hide folder is enabled', () => {
+    vi.mocked(findImageKeyByFilename).mockReturnValue(null)
+    expect(requestPathToImageKey('/demo.webp', { hideFolder: true })).toBeNull()
   })
 
   it('resolves hidden date path to default folder key', () => {
@@ -19,14 +40,16 @@ describe('requestPathToImageKey hide folder', () => {
       .toBe('images/demo.webp')
   })
 
-  it('does not resolve short paths when hide folder is disabled', () => {
+  it('resolves public paths when hide folder is disabled', () => {
     expect(requestPathToImageKey('/2026/08/demo.webp', { hideFolder: false }))
-      .toBeNull()
+      .toBe('images/2026/08/demo.webp')
+    expect(requestPathToImageKey('/blog/demo.webp', { hideFolder: false }))
+      .toBe('images/blog/demo.webp')
     expect(requestPathToImageKey('/demo.webp', { hideFolder: false }))
-      .toBeNull()
+      .toBe('images/demo.webp')
   })
 
-  it('accepts flat full key when hide folder is disabled', () => {
+  it('accepts legacy full key when hide folder is disabled', () => {
     expect(requestPathToImageKey('/images/demo.webp', { hideFolder: false }))
       .toBe('images/demo.webp')
   })

server/utils/serve-image.ts

@@ -8,6 +8,7 @@ import {
 } from './env'
 import { findImageKeyByDatePath, findImageKeyByFilename } from './image-index'
 import { validateImageKey } from './image-key'
+import { isBareImageFilename, toStorageKeyFromPublicPath } from './image-public-path'
 import { buildPublicImageUrl } from './image-response'
 import { createImageStream, headImage } from './storage'
 import { getBackendRowForKey } from './storage/resolver'
@@ -80,16 +81,28 @@ export function requestPathToImageKey(
   options?: { hideFolder?: boolean }
 ): string | null {
   const raw = decodeURIComponent(pathname).replace(/^\/+/, '')
+  if (!raw) return null
+
   if (validateImageKey(raw)) return raw
 
-  if (options?.hideFolder) {
+  // 简短链接：纯文件名须先走索引反查，不能猜成 images/文件名（与按年/月存储冲突）
+  if (options?.hideFolder && isBareImageFilename(raw)) {
     const byFilename = findImageKeyByFilename(raw)
     if (byFilename && validateImageKey(byFilename)) return byFilename
-
+    return null
-    const byDatePath = findImageKeyByDatePath(raw)
-    if (byDatePath && validateImageKey(byDatePath)) return byDatePath
   }
 
+  const fromPublic = toStorageKeyFromPublicPath(raw)
+  if (fromPublic) return fromPublic
+
+  if (!options?.hideFolder) return null
+
+  const byFilename = findImageKeyByFilename(raw)
+  if (byFilename && validateImageKey(byFilename)) return byFilename
+
+  const byDatePath = findImageKeyByDatePath(raw)
+  if (byDatePath && validateImageKey(byDatePath)) return byDatePath
+
   return null
 }