release: v1.2.0 — unified images/ storage and legacy migration

Consolidate local images under data/images/, add docker migrate CLI, startup index sync with orphan cleanup, and remove upload folder UI/API.
2026-08-28 17:18:03 +08:00
1 parent 3dee0437e6
commit 469d3be735
@@ -6,7 +6,7 @@

 | 分支 | 说明 |
 | ---- | ---- |
-| [**main**](https://github.com/O96u/PicHost/tree/main)（默认） | **v1.1.0** 主线：本地磁盘 + 多对象存储（R2 / COS / OSS / AWS）、`/storage` 管理页、混合直链 |
+| [**main**](https://github.com/O96u/PicHost/tree/main)（默认） | **v1.2.0**（开发中）主线：统一 `images/` 存储、多对象存储、[`/storage`](docs/README.md)、[`迁移指南`](migration-to-v1.2.md) |
 | [**cloudflare**](https://github.com/O96u/PicHost/tree/cloudflare) | **Cloudflare R2 专用线**：面向「只用 R2」的部署场景，配置更聚焦 R2 |

 - 需要多种云存储或完整管理界面 → 使用 **main**
@@ -14,7 +14,7 @@

 ## 截图一览

-以下为 **main（v1.1.0）** 界面截图。
+以下为 **main** 界面截图。

 | 文件 | 说明 |
 | ---- | ---- |
@@ -31,10 +31,12 @@

 | 文档 | 说明 |
 | ---- | ---- |
+| [migration-to-v1.2.md](migration-to-v1.2.md) | v1.2.0 本地磁盘迁移（CLI 搬文件 + 启动同步索引） |
+| [migration-to-v1.2.en.md](migration-to-v1.2.en.md) | v1.2.0 migration guide (English) |
 | [domain-separation.md](domain-separation.md) | 双域名分离推荐架构（Nginx / Lucky / 环境变量） |
 | [domain-separation.en.md](domain-separation.en.md) | Dual-domain deployment (English) |

-## 相关页面路由（main / v1.1.0）
+## 相关页面路由（main）

 | 路由 | 权限 | 说明 |
 | ---- | ---- | ---- |
@@ -0,0 +1,129 @@
+# v1.2.0 local disk migration guide
+
+From v1.2.0, **all local image files** live under `data/images/`; SQLite `keys` also start with `images/`. Legacy top-level folders next to `images` (e.g. `data/blog/`, `data/twikoo/`) are no longer used.
+
+Migration is **two steps**: run the **CLI** to move files on disk, then let **startup sync** align the SQLite index.
+
+---
+
+## Migrating from other image hosts (EasyImage, Lsky, Chevereto, …)
+
+There is **no** dedicated “pull from URLs” or “import via vendor API” tool. Moving from **legacy PicHost** or **another self-hosted** install uses the same **local file** workflow:
+
+1. Locate the **image files** on the old server (copy the tree, not just the database).
+2. Place them under PicHost `data/` as a **top-level folder** next to `images` (any name — it becomes `images/{name}/...`).
+3. Run `migrate` / `migrate --apply`, then restart PicHost.
+
+| Source | Typical path on old server | After copy into PicHost |
+| ------ | -------------------------- | ----------------------- |
+| PicHost v1.1.x | `data/blog/`, `data/twikoo/` | Already under `data/` → run `migrate` |
+| EasyImage(s) | `i/` or `upload/` | e.g. `data/easyimage/` → `migrate` |
+| Lsky | `public/uploads/` etc. | e.g. `data/lsky/` → `migrate` |
+| Chevereto etc. | `images/` or `content/` | e.g. `data/chevereto/` → `migrate` |
+| Custom | your folder name | `data/your-folder/` → `migrate` |
+
+The CLI scans **every top-level directory under `data/` except `images`**, not only `blog` / `twikoo`.
+
+**Limits:** files only — accounts, tokens, and old public URLs are not imported. `mapping.json` maps old **storage keys**, not full old-site URLs. For S3/R2-only legacy hosts, sync blobs to `data/…` or attach the bucket in PicHost **Storage** settings.
+
+---
+
+## Layout before and after
+
+### Before (typical v1.1.x)
+
+```
+/data
+├── pichost.db
+├── blog/
+│   └── 2026/08/TeKJ2fD6cB6j.webp
+├── twikoo/
+└── images/
+```
+
+Index keys might look like `blog/2026/08/TeKJ2fD6cB6j.webp`.
+
+### After (v1.2.0)
+
+```
+/data
+├── pichost.db
+├── mapping.json
+└── images/
+    ├── blog/
+    │   └── 2026/08/TeKJ2fD6cB6j.webp
+    └── twikoo/
+```
+
+Index key: `images/blog/2026/08/TeKJ2fD6cB6j.webp`.
+
+---
+
+## Step 1: CLI file migration
+
+Run **before or after** upgrading the image; backup `data/` first.
+
+```bash
+docker exec pichost migrate          # preview + mapping.json
+docker exec pichost migrate --apply  # move files
+```
+
+Local: `npm run migrate` / `npm run migrate -- --apply`.
+
+| Item | Behavior |
+| ---- | -------- |
+| Scan | Every top-level directory under `data/` **except `images`** |
+| Target | `data/images/{original-top-dir}/{relative-path}` |
+| Extensions | jpg, jpeg, png, webp, gif, svg, ico |
+| Sidecar | `.meta.json` next to an image is moved if present |
+| Other files | Not moved; parent directory kept if anything remains |
+| Mapping | `data/mapping.json` — old key → new key |
+
+Script: `server/cli/migrate-to-single-images.mjs`.
+
+---
+
+## Step 2: Startup index sync (automatic)
+
+Runs on every start (`npm run dev`, Docker). No manual command.
+
+```text
+[INFO] 开始同步图片索引：扫描本地磁盘 ...
+[INFO] 磁盘扫描完成：...
+[INFO] 开始归一化遗留图片路径 ...
+[INFO] 开始校验索引与磁盘一致性，清理无文件的孤儿记录
+[INFO] 图片索引同步结束
+```
+
+| Step | Purpose |
+| ---- | ------- |
+| Scan `data/images/` | Insert missing index rows for files on disk |
+| Normalize legacy keys | `blog/...` → `images/blog/...` when files are in place |
+| Purge orphans | Remove index rows with no file on disk |
+| Repair Content-Type | Fix `application/octet-stream` entries |
+
+The CLI only **moves files**. Index alignment runs at startup — **restart** after `migrate --apply`.
+
+---
+
+## Recommended upgrade flow
+
+1. Backup `data/`.
+2. `docker exec pichost migrate` — review output and `mapping.json`.
+3. `docker exec pichost migrate --apply`.
+4. Deploy v1.2.0 and restart.
+5. Check logs for successful index sync.
+6. Use `mapping.json` to update external URLs if needed.
+
+Skip step 1 if you only use object storage or everything is already under `data/images/`.
+
+---
+
+## URLs
+
+| Old key | `blog/TeKJ2fD6cB6j.webp` |
+| New key | `images/blog/TeKJ2fD6cB6j.webp` |
+
+With “hide folder” mode, short URLs like `/TeKJ2fD6cB6j.webp` may still resolve by filename. Use `mapping.json` for bulk replacements.
+
+Chinese version: [migration-to-v1.2.md](migration-to-v1.2.md)
@@ -0,0 +1,178 @@
+# 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` | 重置密码（与迁移无关） |
+
+英文版：[migration-to-v1.2.en.md](migration-to-v1.2.en.md)