release: v1.2.8 — 双域名保存确认与 clear-domains 恢复

启用双域名时以确认框提示锁死风险与恢复方式，不再强制校验 Host。
新增 clear-domains 运维 CLI 与相关文档。

docs-site/guide/changelog.md

@@ -4,6 +4,20 @@ PicHost 版本历史与重要变更说明。完整记录亦见仓库根目录 [C
 
 ---
 
+## [1.2.8] — 2026-09-04
+
+### 改进
+
+- **双域名**：保存 / 初始化时弹出风险确认（含锁死说明与 `clear-domains` 恢复方式），不再强制校验当前 Host
+
+### 新增
+
+- **运维 CLI**：`clear-domains` 清除数据库域名配置（`docker exec pichost clear-domains`）
+
+### 文档
+
+- FAQ 与双域名、反代文档补充恢复步骤
+
 ## [1.2.7] — 2026-09-03
 
 ### 新增

docs-site/guide/domain-separation.md

@@ -72,10 +72,21 @@ PicHost 根据请求 **Host**（反代会转发为 `X-Forwarded-Host`，应用
 
 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` 等第三入口；`IMAGE_BASE_URL` 可填 CDN 公网地址，但应用本体应 Docker/VPS 部署）
-5. 若必须在边缘做反代，须保留客户端 **`Host` 或 `X-Forwarded-Host`**，否则 Host 隔离会失效
-6. PicHost **不能** 作为 Node 应用直接部署到 Pages/Workers（依赖 `node-server`、SQLite、`sharp` 与本地 `data/`）；应用请继续 Docker/VPS 部署，CF 侧用橙云 DNS + 可选 R2 存储即可
+3. **保存前**阅读设置 / 初始化页的风险确认；若通过 IP、内网或未正确传递 Host 的反代保存，可能锁死后台；恢复见下方「已锁死时的恢复」
+4. **仅使用** 设置中的网站域名登录后台，不要用 `localhost`、IP 或未配置的域名混用
+5. **不要** 用 Cloudflare Pages / Workers 对 PicHost **整站反代**（会多出 `pages.dev` / `workers.dev` 等第三入口；`IMAGE_BASE_URL` 可填 CDN 公网地址，但应用本体应 Docker/VPS 部署）
+6. 若必须在边缘做反代，须保留客户端 **`Host` 或 `X-Forwarded-Host`**（Lucky/NPM「强制域名」须与 PicHost 配置一致），否则 Host 隔离会失效或保存后被锁死
+7. PicHost **不能** 作为 Node 应用直接部署到 Pages/Workers（依赖 `node-server`、SQLite、`sharp` 与本地 `data/`）；应用请继续 Docker/VPS 部署，CF 侧用橙云 DNS + 可选 R2 存储即可
+
+### 已锁死时的恢复
+
+若已误保存导致 IP / 内网地址全站 404：
+
+```bash
+docker exec pichost clear-domains
+```
+
+本地：`npm run clear-domains`。清除后请用网站域名重新配置，并确认反代 `Host` 头正确。
 
 ### Cloudflare 橙云（含 DNS 优选）
 

docs-site/guide/faq.md

@@ -20,6 +20,24 @@ docker exec pichost reset-password 用户名
 
 检查 **防盗链白名单**（`ALLOWED_REFERER_HOSTS` 或设置页）。引用图片的站点域名需在白名单中；PicHost 自身域名与双域名场景下的网站域、图片域会自动放行。
 
+## 双域名配置后后台 404 / 进不去？
+
+**原因：** 启用双域名后，PicHost 会对**未配置的网站域、图片域之外**的 Host 全站返回 404。常见触发方式：
+
+1. 通过 IP 或内网地址打开设置，保存了公网网站域 / 图片域
+2. 反代「强制域名」或 Host 头配置错误，PicHost 收到的 Host 与设置中的网站域不一致
+
+**恢复（已锁死时）：**
+
+```bash
+docker exec pichost clear-domains
+# 仅清除网站域：docker exec pichost clear-domains --site
+```
+
+本地开发：`npm run clear-domains`。执行后用原来的 IP / 内网地址刷新即可重新进入后台，再按文档正确配置双域名。
+
+**预防：** 保存双域名时注意确认框中的风险提示；反代须 `proxy_set_header Host $host;` 并保留 `X-Forwarded-Proto`。详见 [双域名分离](./domain-separation.md#中间件隔离与第三-host)。
+
 ## 双域名下为什么用 pages.dev / workers.dev / IP 也能进后台？
 
 **v1.2.2 起：** 双域名开启时，PicHost 中间件会对**未配置的网站域、图片域之外**的 Host 返回 **404**（开发环境 `localhost` / `127.0.0.1` 例外）。详见 [更新日志](./changelog.md#1-2-2-2026-08-30)。

docs-site/guide/getting-started.md

@@ -73,6 +73,16 @@ docker exec pichost reset-password 用户名
 
 本地开发：`npm run reset-password` 或 `npm run reset-password -- 用户名`
 
+## 双域名配置锁死
+
+若启用双域名后通过 IP / 内网地址无法进入后台：
+
+```bash
+docker exec pichost clear-domains
+```
+
+本地：`npm run clear-domains`。详见 [常见问题 — 双域名配置后后台 404](./faq.md#双域名配置后后台-404-进不去)。
+
 ## 升级到 v1.2.0
 
 若 `data/` 下存在与 `images` 并列的遗留目录（如 `blog/`、`twikoo/`），升级前请阅读 [v1.2 迁移指南](./migration.md)。

docs-site/guide/local-dev.md

@@ -29,6 +29,7 @@ npm run dev
 | `npm test` | 单元测试 |
 | `npm run reset-password` | 重置密码（可选用户名） |
 | `npm run slider` | 将登录验证重置为本地滑块 |
+| `npm run clear-domains` | 清除数据库中的网站域 / 图片域配置（双域名锁死时恢复） |
 | `npm run migrate` | 预览遗留目录迁移（加 `-- --apply` 执行） |
 
 ## 开发专用环境变量

docs-site/guide/reverse-proxy.md

@@ -63,7 +63,7 @@ IMAGE_BASE_URL=https://pic.example.com
 2. **禁止公网暴露 6892** — 仅本机或内网反代访问；公网只开 80/443
 3. **橙云时限制源站来源 IP** — 仅 Cloudflare 回源 IP 段
 
-双域名场景下 PicHost **不会** 拒绝未配置的 Host；上述措施由运维层补齐。
+**v1.2.2 起**，双域名开启时 PicHost 应用层也会对**未配置的网站域、图片域之外**的 Host 全站返回 404（与反代 default server 互补，而非替代）。误配置导致锁死时执行 `docker exec pichost clear-domains` 恢复，见 [常见问题](./faq.md#双域名配置后后台-404-进不去)。
 
 ## Caddy 示例