release: v1.3.0 — 整站备份恢复、跨后端同步与任务中心

2026-09-07 17:05:12 +08:00
1 parent b05d572221
commit f17d79b236
@@ -159,15 +159,12 @@ PicHost 版本历史与重要变更说明。完整记录亦见仓库根目录 [C

 ### 变更

- 图片统一存放在 `data/images/`；遗留 `blog/`、`twikoo/` 等并列目录需迁移
+- 图片统一存放在 `data/images/`；不再使用与 `images` 并列的顶层目录

 ### 新增

- CLI：`docker exec pichost migrate` / `migrate --apply`
 - 启动时自动同步图片索引（扫描磁盘、归一化遗留 key、清理孤儿记录）

-详见 [v1.2 迁移](./migration.md)。
-
 ---

 ## [1.1.x] 摘要
@@ -62,21 +62,21 @@ docker exec pichost clear-domains
 - 后台请用 **网站域名** 打开，不要用 `localhost` 混用
 - 见 [双域名分离](./domain-separation.md)

-## 升级 v1.2 后图库有删不掉的记录？
+## 图库有删不掉的记录？

-可能是 **孤儿索引**（有记录无文件）。重启后启动同步会自动清理；也可手动删除仅索引项。见 [v1.2 迁移](./migration.md#第二步启动时自动同步索引)。
+可能是 **孤儿索引**（有记录无文件）。重启后启动同步会自动清理；也可在图库中手动删除。

-## 遗留 `data/blog/` 目录还要吗？
+## 如何备份与迁移整站？

-执行 `migrate --apply` 后文件已迁入 `data/images/blog/`。若原目录只剩空壳或非图片文件，可自行备份后删除；迁移脚本不会删除仍含非图片文件的目录。
+v1.3.0 起在 **存储** 页使用「备份与迁移」面板，或 CLI：

-## 只用对象存储需要跑 migrate 吗？
+```bash
+docker exec pichost backup-export
+docker exec pichost backup-restore /data/backups/pichost-xxx.phost.tar.gz
+docker exec pichost storage-sync --from local --to s3-xxx --dry-run
+```

-不需要。图片在桶内时跳过 CLI；启动同步主要面向本地 `data/images/` 磁盘扫描。
-
-## 如何替换博客里的旧图片 URL？
-
-使用 `data/mapping.json`（`migrate` 预览时生成）批量替换旧 key。注意映射的是 **存储 key**，不是完整旧站 URL。见 [迁移指南](./migration.md#外链与直链)。
+备份包含数据库与全部图片，**不含** 云存储密钥；恢复后请在存储页重新填写。详见 [存储 → 备份与迁移](./storage.md#备份与迁移v130)。

 ## 开发时如何跳过登录？

@@ -33,10 +33,18 @@ docker compose up -d
 ## 首次设置

 1. 访问实例 URL（Docker 默认 `http://<主机>:6892`）。
-2. 在 `/setup` 填写管理员用户名与密码。
+2. 在 `/setup` 选择 **创建管理员** 或 **从备份恢复**：
+   - **创建管理员**：填写用户名与密码，可选开放注册、双域名等。
+   - **从备份恢复**：上传 `.phost.tar.gz` 整站备份包（覆盖当前数据；云存储密钥需恢复后重新填写）。
 3. （可选）配置网站域名、图片域名、防盗链等 — 详见 [环境变量](./configuration.md) 与 [双域名分离](./domain-separation.md)。
 4. 登录后可在首页上传图片；顶栏可进入 **图库**、**存储**（管理员）、**设置**、**API**。

+| 创建管理员 | 从备份恢复 |
+| :--------: | :--------: |
+| ![首次设置](/screenshots/setup.png) | ![从备份恢复](/screenshots/setup-restore.png) |
+
+已初始化实例请使用 [存储 → 备份与迁移](./storage.md#备份与迁移v130) 恢复，而非 setup 页。
+
 ## 登录

 访问上传、图库、设置等管理页面前需登录。在登录卡片中填写用户名与密码，完成人机验证后点击 **登录**。
@@ -83,12 +91,6 @@ docker exec pichost clear-domains

 本地：`npm run clear-domains`。详见 [常见问题 — 双域名配置后后台 404](./faq.md#双域名配置后后台-404-进不去)。

-## 升级到 v1.2.0
-
-若 `data/` 下存在与 `images` 并列的遗留目录（如 `blog/`、`twikoo/`），升级前请阅读 [v1.2 迁移指南](./migration.md)。
-
-仅对象存储、或图片已在 `data/images/` 下时，拉取新镜像并重启即可。
-
 ## 下一步

 - [本地开发](./local-dev.md) — `npm run dev` 与 `.env`
@@ -12,9 +12,9 @@

 ## 截图预览

-**main** 分支暂无公网演示，以下为当前产品界面（v1.2.5+）。
+**main** 分支暂无公网演示，以下为当前产品界面（v1.3.0+）。

-| API | 图库 |
+| API | 图库（详情） |
 | :-: | :-: |
 | ![API](/screenshots/api.png) | ![图库](/screenshots/gallery.png) |

@@ -22,6 +22,10 @@
 | :------: | :--------: |
 | ![存储管理](/screenshots/storage.png) | ![设置与偏好](/screenshots/settings.png) |

+| 首次设置 | 从备份恢复 |
+| :------: | :--------: |
+| ![首次设置](/screenshots/setup.png) | ![从备份恢复](/screenshots/setup-restore.png) |
+
 | 操作日志 |
 | :------: |
 | ![操作日志](/screenshots/logs.png) |
@@ -30,7 +30,6 @@ npm run dev
 | `npm run reset-password` | 重置密码（可选用户名） |
 | `npm run slider` | 将登录验证重置为本地滑块 |
 | `npm run clear-domains` | 清除数据库中的网站域 / 图片域配置（双域名锁死时恢复） |
-| `npm run migrate` | 预览遗留目录迁移（加 `-- --apply` 执行） |

 ## 开发专用环境变量

@@ -53,4 +52,4 @@ npm run docs:build    # 构建静态站点
 npm run docs:preview  # 预览构建结果
 ```

-文档源码在 `docs-site/`；截图源文件在 `docs/screenshots/`（含 `login.png` 登录页），构建前会复制到 `docs-site/public/screenshots/`。在线文档：<https://o96u.github.io/PicHost/>
+文档源码在 `docs-site/`；截图源文件在 `docs/screenshots/`（含 `login.png`、`setup.png`、`setup-restore.png` 等），构建前会复制到 `docs-site/public/screenshots/`。在线文档：<https://o96u.github.io/PicHost/>
@@ -1,176 +0,0 @@
-# v1.2.0 本地磁盘迁移指南
-
-v1.2.0 起，**所有本地图片文件**统一放在 `data/images/` 下；SQLite `images` 表中的 `key` 也以 `images/` 开头。旧版在 `data/blog/`、`data/twikoo/` 等与 `images` **并列的顶层目录**不再符合新模型。
-
-迁移分 **两步**：先用手动 CLI **搬文件**，再由服务 **启动时自动同步索引**。
-
---
-
-## 从其它图床迁入（EasyImage / 兰空 / Chevereto 等）
-
-**没有**单独的「一键从外链拉取」或「对接某某图床 API」工具。从 **PicHost 旧版** 或其它自托管图床迁入，走的是同一套 **本地文件迁移**：
-
-1. 在旧图床服务器上找到图片**物理目录**（整目录拷贝，不要只拷数据库）。
-2. 把该目录放到 PicHost 的 `data/` 下，作为与 `images` **并列的顶层文件夹**（文件夹名任意，会保留为 `images/{文件夹名}/...`）。
-3. 执行 `migrate` / `migrate --apply`，再重启 PicHost。
-
-### 常见来源示例
-
-| 来源 | 典型图片目录（在旧服务器上） | 放入 PicHost 后示例 |
-| ---- | ---------------------------- | ------------------- |
-| PicHost v1.1.x | `data/blog/`、`data/twikoo/` | 已在 `data/` 下，直接 `migrate` |
-| EasyImage / EasyImages | `i/` 或安装目录下的 `upload/` | 拷到 `data/easyimage/` 再 `migrate` |
-| 兰空图床 (Lsky) | `public/uploads/` 等 | 拷到 `data/lsky/` 再 `migrate` |
-| Chevereto 等 | `images/` 或 `content/` | 拷到 `data/chevereto/` 再 `migrate` |
-| 任意自定义目录 | 你的顶层文件夹名 | 拷到 `data/你的目录名/` 再 `migrate` |
-
-脚本会扫描 `data/` 下**除 `images` 外所有顶层目录**里的图片，不限于 `blog` / `twikoo`。子目录结构会原样保留在 `images/{顶层名}/` 下。
-
-### 操作示例（Docker）
-
-```bash
-# 在宿主机：把从旧图床打包的目录放进挂载卷（名称自定）
-# 例如：./data/easyimage/2026/01/photo.jpg
-
-docker exec pichost migrate          # 预览
-docker exec pichost migrate --apply
-# 重启容器 → 启动日志会补全 SQLite 索引
-```
-
-### 说明与限制
-
- **只迁移文件**：旧图床的账号、Token、外链 URL **不会**自动导入；`mapping.json` 里的 key 是「旧磁盘相对 key → 新 key」，**不是**旧站完整 URL，替换外链需自行对照。
- **对象存储**：若旧图床图片在 S3/R2 桶里，请用桶工具同步到本地 `data/某目录/`，或直接在 PicHost **存储**页配置同一桶（不经过本 CLI）。
- **已直接在 `data/images/` 下**：无需 `migrate`，重启后启动同步会自动建索引。
-
---
-
-## 存储结构对比
-
-### 迁移前（v1.1.x 常见）
-
-```
-/data
-├── pichost.db
-├── blog/
-│   └── 2026/08/TeKJ2fD6cB6j.webp
-├── twikoo/
-│   └── xxx.webp
-└── images/          # 可能已有部分新图
-    └── ...
-```
-
-SQLite 中 `key` 可能是 `blog/2026/08/TeKJ2fD6cB6j.webp`（与磁盘顶层目录一致）。
-
-### 迁移后（v1.2.0）
-
-```
-/data
-├── pichost.db
-├── mapping.json     # CLI 生成：旧 key → 新 key（供替换外链）
-└── images/
-    ├── blog/
-    │   └── 2026/08/TeKJ2fD6cB6j.webp
-    ├── twikoo/
-    │   └── xxx.webp
-    └── ...            # 新上传：images/随机ID.webp 或 images/年/月/随机ID.webp
-```
-
-对应 `key`：`images/blog/2026/08/TeKJ2fD6cB6j.webp`。
-
---
-
-## 第一步：CLI 迁移磁盘文件
-
-在 **升级镜像之前或之后**均可执行；建议在升级前完成，并先备份整个 `data/` 目录。
-
-### Docker
-
-```bash
-# 预览：列出待迁移文件，写入 data/mapping.json（旧 key → 新 key）
-docker exec pichost migrate
-
-# 确认无误后执行文件移动
-docker exec pichost migrate --apply
-```
-
-### 本地开发
-
-```bash
-npm run migrate              # 预览
-npm run migrate -- --apply   # 执行
-```
-
-### 脚本行为
-
-| 项目 | 说明 |
-| ---- | ---- |
-| 扫描范围 | `data/` 下**除 `images` 外所有顶层目录**（不限于 blog/twikoo） |
-| 迁移目标 | `data/images/{原顶层目录名}/{相对路径}` |
-| 图片类型 | `.jpg` `.jpeg` `.png` `.webp` `.gif` `.svg` `.ico` |
-| 伴随文件 | 若存在同名的 `.meta.json` 会一并移动 |
-| 非图片文件 | 不移动；若目录内仍有其它文件，**保留原目录**不删除 |
-| 映射表 | `data/mapping.json`，例如 `"blog/foo.webp": "images/blog/foo.webp"` |
-
-脚本路径：`server/cli/migrate-to-single-images.mjs`。
-
---
-
-## 第二步：启动时自动同步索引
-
-每次 PicHost 启动（`npm run dev`、Docker 容器启动）会自动执行，**无需手动命令**。日志示例：
-
-```text
-[INFO] 开始同步图片索引：扫描本地磁盘 {"path":".../data/images/"}
-[INFO] 磁盘扫描完成：已补全缺失索引 {"inserted":3}
-[INFO] 开始归一化遗留图片路径（如 blog/ → images/blog/）
-[INFO] 遗留路径归一化完成：无需调整
-[INFO] 开始校验索引与磁盘一致性，清理无文件的孤儿记录
-[INFO] 孤儿索引清理完成：未发现孤儿记录
-[INFO] 开始修复存量 Content-Type 元数据
-[INFO] Content-Type 修复完成：无需修复
-[INFO] 图片索引同步结束
-```
-
-| 步骤 | 作用 |
-| ---- | ---- |
-| 扫描 `data/images/` | 磁盘上有、索引里没有 → **补全** `images` 表 |
-| 归一化遗留 key | 将 `blog/...` 等旧 key 更新为 `images/blog/...`（文件已在正确路径时） |
-| 清理孤儿索引 | 索引里有记录、磁盘无文件 → **删除**幽灵记录（避免图库出现删不掉的项） |
-| 修复 Content-Type | 修正错误的 `application/octet-stream` |
-
-CLI 只负责**搬文件**；索引对齐、遗留 key、孤儿记录由启动同步处理。执行 `migrate --apply` 后**重启一次**服务即可。
-
---
-
-## 推荐升级流程
-
-1. **备份** `data/`（含 `pichost.db` 与各目录）。
-2. `docker exec pichost migrate` 预览，检查输出与 `mapping.json`。
-3. `docker exec pichost migrate --apply` 执行迁移。
-4. 拉取 / 部署 **v1.2.0** 镜像并重启容器。
-5. 查看启动日志，确认「图片索引同步结束」无报错。
-6. 用 `mapping.json` 批量替换博客、Twikoo 等外链中的旧路径（若需要）。
-
-仅使用对象存储、或图片早已全部在 `data/images/` 下时，**跳过第一步**；第二步仍会在启动时运行，通常几秒内完成且无变更日志。
-
---
-
-## 外链与直链
-
-| 场景 | 说明 |
-| ---- | ---- |
-| 旧 key | `blog/TeKJ2fD6cB6j.webp` |
-| 新 key | `images/blog/TeKJ2fD6cB6j.webp` |
-| 隐藏目录模式 | 若开启「隐藏 images 前缀」，短链可能为 `/TeKJ2fD6cB6j.webp`；服务按文件名反查索引 |
-| 替换建议 | 以 `mapping.json` 为准；或重新在图库复制新链接 |
-
---
-
-## 相关命令
-
-| 命令 | 说明 |
-| ---- | ---- |
-| `docker exec pichost migrate` | 预览磁盘迁移 |
-| `docker exec pichost migrate --apply` | 执行磁盘迁移 |
-| `docker exec pichost reset-password` | 重置密码（与迁移无关） |
@@ -56,17 +56,53 @@ PicHost 支持 **本地磁盘** 与 **S3 兼容对象存储**（Cloudflare R2、
 ## 用量与筛选

 - 存储页展示各后端用量（本地扫描目录，对象存储查询 API）
- 图库可按 **存储后端**、**上传来源** 筛选，支持网格/列表视图切换
+- 图库可按 **存储后端**、**上传来源** 筛选，支持网格/列表视图切换；点击图片打开详情弹窗（尺寸、存储路径、多格式链接复制）

-## 备份
+## 备份与迁移（v1.3.0+）

-请同时备份：
+存储页 **备份与迁移** 面板包含三张功能卡与下方 **最近任务** 列表：

- `data/images/`（本地后端）
- `data/pichost.db`
- 各云桶中的对象
+| 能力 | 说明 |
+| ---- | ---- |
+| **创建站点备份** | 导出 `.phost.tar.gz`，含 `pichost.db` 与全部图片（含云存储中的对象）；展示预计体积与备份包含项 |
+| **从备份恢复** | 本地上传或选择 `data/backups/` 内已有包，预检后确认；可选跳过/覆盖冲突图片 |
+| **跨后端同步** | 在已配置后端间拷贝图片并更新索引；展示待迁移数量与体积，支持预检、删源、设默认 |

-从 v1.1.x 升级且存在 `data/blog/` 等并列目录时，见 [v1.2 迁移](./migration.md)。
+![备份与迁移](/screenshots/storage.png)
+
+- 导出文件保存在 `data/backups/`；后端同一时间仅允许一个进行中的备份/迁移任务
+- 任务列表支持分页，可下载导出包、查看恢复结果、重试失败的同步任务
+- 备份包 **不含** 云存储 Access Key / Secret Key，恢复后请在存储页重新填写
+- 未初始化实例可在 **setup** 页 **从备份恢复** 标签上传整站包（始终覆盖模式）
+
+![从备份恢复（setup）](/screenshots/setup-restore.png)
+
+### CLI
+
+```bash
+# 导出整站备份
+docker exec pichost backup-export
+
+# 从备份恢复（默认跳过冲突图片）
+docker exec pichost backup-restore /data/backups/pichost-xxx.phost.tar.gz
+docker exec pichost backup-restore /data/backups/pichost-xxx.phost.tar.gz --overwrite
+
+# 跨后端同步
+docker exec pichost storage-sync --from local --to s3-xxx --dry-run
+docker exec pichost storage-sync --from local --to s3-xxx --set-default
+```
+
+本地开发（项目根目录）：
+
+```bash
+npm run backup-export
+npm run backup-restore -- data/backups/pichost-xxx.phost.tar.gz
+npm run storage-sync -- --from local --to s3-xxx --dry-run
+```
+
+### 手动备份
+
+仍可同时备份 `data/images/`（本地后端）、`data/pichost.db` 与各云桶中的对象；推荐使用上文整站导出。

 ## 相关