release: v1.3.0 — 整站备份恢复、跨后端同步与任务中心
ci / ci (22, ubuntu-latest) (push) Canceled after 0s
GitHub Release / release (push) Canceled after 0s
Publish Docker image / build (linux/amd64, ubuntu-latest, amd64) (push) Canceled after 0s
Publish Docker image / build (linux/arm64, ubuntu-24.04-arm, arm64) (push) Canceled after 0s
Publish Docker image / merge (push) Canceled after 0s
ci / ci (22, ubuntu-latest) (push) Canceled after 0s
GitHub Release / release (push) Canceled after 0s
Publish Docker image / build (linux/amd64, ubuntu-latest, amd64) (push) Canceled after 0s
Publish Docker image / build (linux/arm64, ubuntu-24.04-arm, arm64) (push) Canceled after 0s
Publish Docker image / merge (push) Canceled after 0s
This commit is contained in:
O96u committed
1 parent
b05d572221
commit
f17d79b236
72 files changed
+4312
-559
No files matched your search
@@ -159,15 +159,12 @@ Version history and notable changes. The full log is also in the repo root [CHAN
|
||||
|
||||
### Changed
|
||||
|
||||
- All images under `data/images/`; legacy `blog/` / `twikoo/` need migration
|
||||
- All images under `data/images/`; parallel top-level folders beside `images` are no longer used
|
||||
|
||||
### 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
|
||||
|
||||
+10
-10
@@ -61,21 +61,21 @@ Recommended: run PicHost on origin; use **proxied DNS** (and optional **R2** sto
|
||||
- Always open admin on the **site hostname**, not mixed with `localhost`
|
||||
- See [Dual-domain separation](./domain-separation.md)
|
||||
|
||||
## Undeletable gallery items after v1.2 upgrade?
|
||||
## Undeletable gallery items?
|
||||
|
||||
Likely **orphan index** rows (no file on disk). Startup sync removes them on restart. See [v1.2 migration](./migration.md#step-2-startup-index-sync-automatic).
|
||||
Likely **orphan index** rows (no file on disk). Startup sync removes them on restart; you can also delete them from the gallery.
|
||||
|
||||
## Do I still need `data/blog/` after migration?
|
||||
## How do I back up or migrate the full site?
|
||||
|
||||
After `migrate --apply`, files live under `data/images/blog/`. Remove leftover empty dirs after backup if you like; dirs with non-image files are kept by the CLI.
|
||||
From v1.3.0, use **Storage → Backup & migration**, or CLI:
|
||||
|
||||
## Object storage only — run 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
|
||||
```
|
||||
|
||||
No. Skip the CLI; startup sync focuses on local `data/images/` scanning.
|
||||
|
||||
## Replace old image URLs in posts?
|
||||
|
||||
Use `data/mapping.json` from `migrate` preview. Keys are **storage paths**, not full legacy URLs. See [Migration](./migration.md#urls).
|
||||
Packages include the database and all images but **not** cloud storage secrets — re-enter them on the Storage page after restore. See [Storage → Backup & migration](./storage.md#backup--migration-v130).
|
||||
|
||||
## Skip login during development?
|
||||
|
||||
|
||||
@@ -33,10 +33,18 @@ See `docker-compose.yml` in the repository.
|
||||
## First-time setup
|
||||
|
||||
1. Open your instance URL (Docker default `http://<host>:6892`).
|
||||
2. Complete `/setup` with admin username and password.
|
||||
2. On `/setup`, choose **Create admin** or **Restore backup**:
|
||||
- **Create admin** — username, password, optional registration and dual-domain options.
|
||||
- **Restore backup** — upload a `.phost.tar.gz` full-site package (replaces current data; re-enter cloud storage secrets after restore).
|
||||
3. (Optional) Configure site URL, image URL, Referer rules — see [Environment variables](./configuration.md) and [Dual-domain separation](./domain-separation.md).
|
||||
4. Upload from the home page; use the top nav for **Gallery**, **Storage** (admin), **Settings**, and **API**.
|
||||
|
||||
| Create admin | Restore from backup |
|
||||
| :----------: | :-----------------: |
|
||||
|  |  |
|
||||
|
||||
For an already-initialized instance, use [Storage → Backup & migration](./storage.md#backup--migration-v130) instead of `/setup`.
|
||||
|
||||
## Sign in
|
||||
|
||||
Management pages (upload, gallery, settings, etc.) require login. Enter username and password, complete the verification challenge, then click **Sign in**.
|
||||
@@ -80,12 +88,6 @@ docker exec pichost clear-domains
|
||||
|
||||
Local: `npm run clear-domains`. See [FAQ — Admin 404 after dual-domain setup](./faq.md#admin-404--locked-out-after-dual-domain-setup).
|
||||
|
||||
## Upgrading to v1.2.0
|
||||
|
||||
If `data/` has legacy top-level folders next to `images` (e.g. `blog/`, `twikoo/`), read the [v1.2 migration guide](./migration.md) first.
|
||||
|
||||
Object-storage-only or files already under `data/images/` — pull the new image and restart.
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Local development](./local-dev.md)
|
||||
|
||||
@@ -12,16 +12,20 @@ Welcome to the PicHost user guide. This site is the single source of truth; the
|
||||
|
||||
## Screenshots
|
||||
|
||||
**main** has no public demo. Below are current product screenshots (v1.2.5+).
|
||||
**main** has no public demo. Below are current product screenshots (v1.3.0+).
|
||||
|
||||
| API | Gallery |
|
||||
| :-: | :-----: |
|
||||
| API | Gallery (detail) |
|
||||
| :-: | :--------------: |
|
||||
|  |  |
|
||||
|
||||
| Storage | Settings |
|
||||
| :-----: | :-------: |
|
||||
|  |  |
|
||||
|
||||
| First-time setup | Restore from backup |
|
||||
| :--------------: | :-----------------: |
|
||||
|  |  |
|
||||
|
||||
| Activity log |
|
||||
| :----------: |
|
||||
|  |
|
||||
|
||||
@@ -30,7 +30,6 @@ Open `http://localhost:3000/setup` to create the admin account. Data directory d
|
||||
| `npm run reset-password` | Reset password (optional username) |
|
||||
| `npm run slider` | Reset login verification to local slider |
|
||||
| `npm run clear-domains` | Clear site/image URL settings from DB (recover from dual-domain lockout) |
|
||||
| `npm run migrate` | Preview legacy dir migration (`-- --apply` to run) |
|
||||
|
||||
## Dev-only variables
|
||||
|
||||
@@ -53,4 +52,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. Live docs: <https://o96u.github.io/PicHost/>
|
||||
Sources live in `docs-site/`; screenshot sources are in `docs/screenshots/` (including `login.png`, `setup.png`, `setup-restore.png`, etc.), copied to `docs-site/public/screenshots/` before build. Live docs: <https://o96u.github.io/PicHost/>
|
||||
@@ -1,129 +0,0 @@
|
||||
# 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: [v1.2 迁移指南](/guide/migration)
|
||||
@@ -54,13 +54,48 @@ Copied links use **IMAGE_BASE_URL**. “Hide folder prefix” may shorten URLs;
|
||||
## Usage & gallery filter
|
||||
|
||||
- Per-backend usage on the Storage page
|
||||
- Gallery filters by **storage backend** and **upload source**; grid/list view toggle
|
||||
- Gallery filters by **storage backend** and **upload source**; grid/list view toggle; click a thumbnail for the detail modal (dimensions, storage path, link formats)
|
||||
|
||||
## Backup
|
||||
## Backup & migration (v1.3.0+)
|
||||
|
||||
Back up `data/images/`, `data/pichost.db`, and bucket objects.
|
||||
The **Backup & migration** panel has three action cards and a paginated **Recent jobs** table below:
|
||||
|
||||
Upgrading from v1.1.x with parallel folders: [v1.2 migration](./migration.md).
|
||||
| Feature | Description |
|
||||
| ------- | ------------- |
|
||||
| **Create site backup** | Export `.phost.tar.gz` with `pichost.db` and all images (including objects on cloud backends); shows estimated size and package contents |
|
||||
| **Restore from backup** | Upload locally or pick an existing package under `data/backups/`, preview, then confirm; skip or overwrite conflicting images |
|
||||
| **Cross-backend sync** | Copy images between configured backends and update the index; shows pending count/size, dry-run, optional delete-source and set-default |
|
||||
|
||||
|
||||
|
||||
- Exports are saved under `data/backups/`; only one backup/migration job may run at a time
|
||||
- Job list supports pagination; download exports, view restore summaries, retry failed sync jobs
|
||||
- Packages **do not** include cloud storage secrets — re-enter them on the Storage page after restore
|
||||
- Uninitialized instances can use the **Restore backup** tab on `/setup` (always overwrite mode)
|
||||
|
||||
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
Local development (project root):
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### Manual backup
|
||||
|
||||
You can still back up `data/images/`, `data/pichost.db`, and bucket objects directly; prefer the full-site export above.
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
Reference in new issue
Block a user