From 885534378b27e4b2f16412c1ba91eee9709a97ab Mon Sep 17 00:00:00 2001 From: YeomaiPC Date: Sun, 18 Oct 2026 21:35:59 +0800 Subject: [PATCH] =?UTF-8?q?=E8=87=AA=E8=BF=B0=E4=BF=AE=E6=94=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.en.md | 193 +++++++++++++++++++++++++++++++++++++++----------- README.md | 196 ++++++++++++++++++++++++++++++++++++++++----------- 2 files changed, 306 insertions(+), 83 deletions(-) diff --git a/README.en.md b/README.en.md index 922d2f2..4b0310e 100644 --- a/README.en.md +++ b/README.en.md @@ -4,32 +4,37 @@

PicHost

-

Lightweight personal image hosting · Simple uploads, clean management

+

Self-hosted image, video, and file management platform

-

Self-hosted / Multi-user / Docker / API / Twikoo · Local disk or object storage

+

Multi-user · WebP compression · HLS video · File hosting · Tags · Multi-backend storage · Full backup and migration

- version - CI + version Nuxt 4 - Docker + Docker + Windows x64 + FnOS x86 GPL-3.0

- Docs · Screenshots · Features · - Tech Stack · - Quick Start · + Deployment · + Development · + Documentation source · 简体中文

--- -## Screenshots +## Overview -**main** has no public demo. **cloudflare** branch live demo: [pic.roven.cc](https://pic.roven.cc) +PicHost is a media management platform for NAS devices, home servers, and small self-hosted deployments. It manages images, videos, and general-purpose files in one place, with multi-user access, tags, search, multiple storage backends, HLS video processing, full-site backup and restore, backend migration, and site-to-site synchronization. + +The first visit opens a web setup wizard. Administrators can either create an account or restore an existing `.phost.tar.gz` backup. + +## Screenshots | Upload | Gallery | | :----: | :-----: | @@ -53,29 +58,60 @@ ## Features -- **Drag, click, or Ctrl+V paste** — server-side WebP, Referer hotlink protection -- **Multi-user** — login with slider, Turnstile, or Cap verification; optional registration; users see only their images -- **Multi-backend storage** — local disk + S3-compatible (R2 / COS / OSS / AWS) + Telegram channel/group; hybrid `proxy` / `public` URLs -- **Gallery** — browse, search, filter by storage/source/tags, grid/list views, batch delete and batch tagging; stats overview and source breakdown; image detail modal with link formats -- **Tags** — per-user colored tags; tag on upload (single or batch); manage in Settings (create, recolor, merge, delete); API supports `tagIds` and batch tagging -- **Backup & migration** — full-site export/restore (`.phost.tar.gz`), cross-backend sync; restore from backup on uninitialized `/setup` -- **API & Twikoo** — global / per-user tokens; `POST /api/index.php` compatible -- **Zero-config Docker** — first-run web wizard, no secrets upfront +### Images -## Tech Stack +- Upload by drag and drop, file picker, or `Ctrl+V` paste, with configurable formats, size limits, batch limits, and rate limits. +- Server-side Sharp-based WebP compression, with optional original preservation and optional browser-side WebP compression. +- Search, pagination, storage/source/tag filters, grid or list layouts, detail views, multiple link formats, bulk tagging, and bulk deletion. +- Media counts and source statistics, Referer hotlink protection, and configurable referrer allowlists. -| Layer | Technologies | -| ----- | ------------ | -| Frontend | [Nuxt 4](https://nuxt.com) · [Nuxt UI 4](https://ui.nuxt.com) · [Vue 3](https://vuejs.org) · [Tailwind CSS 4](https://tailwindcss.com) · TypeScript | -| Backend | [Nitro](https://nitro.build) (`node-server`) · REST API | -| Data | SQLite · local `data/pichost.db` | -| Images | [sharp](https://sharp.pixelplumbing.com) (server-side WebP) | -| Storage | Local disk · S3-compatible ([AWS SDK](https://aws.amazon.com/sdk-for-javascript/) · R2 / COS / OSS, etc.) · Telegram channel/group | -| i18n | [@nuxtjs/i18n](https://i18n.nuxtjs.org) (zh-CN / English) | -| Quality & docs | [Vitest](https://vitest.dev) · [VitePress](https://vitepress.dev) docs site | -| Deploy | Docker · Node.js 22 | +### Video and HLS -## Quick Start +- Dedicated video upload and library pages for MP4, M4V, WebM, MOV, MKV, AVI, FLV, WMV, MPG, and MPEG. +- Automatic thumbnail generation and optional asynchronous HLS transcoding. +- `copy`, `veryfast`, `medium`, `slow`, and `compress` presets, with configurable concurrency, CPU thread count, and target bitrate. +- Transcode progress and failure reporting, with automatic cleanup of the source, thumbnail, playlist, and HLS segments. +- Original, thumbnail, and HLS links, plus MP4 remux download for HLS videos. + +### File Hosting + +- A dedicated file library with uploads, search, pagination, tags, bulk deletion, direct links, and download links. +- Configurable file-bed access policy, with separate domains supported for images, videos, and files. + +### Users and Access Control + +- Administrator and standard-user accounts; standard users only see and manage their own media. +- Slider, Cloudflare Turnstile, and Cap verification, with optional public registration. +- Profile and password management, administrator password reset, and account-system migration. +- Per-user tags and automatic deletion policies. +- Login and upload rate limits, global and personal API tokens, and activity logs. + +### Storage + +- Local disk, S3-compatible object storage, and Telegram channels or groups. +- S3-compatible support includes R2, COS, OSS, AWS S3, and similar services, with `proxy` or `public` access modes. +- Multiple backends, configurable default and enabled states, and per-backend capacity quotas. +- Migration of images, videos, files, and indexes between configured backends, with an optional target backend switch after migration. + +### Backup and Synchronization + +- Complete `.phost.tar.gz` site backups containing the database, images, videos, files, thumbnails, HLS content, and tags. +- Restore previews for file count, media size, new files, conflicts, and skip/overwrite conflict handling. +- Streaming uploads for large backups without loading the complete archive into memory. +- Restore directly from the first-run setup page; cloud storage secrets are excluded and must be re-entered after restore. +- Push or pull synchronization between two PicHost sites, for all media or only images, videos, or files. +- Resume support, conflict policies, and job progress; matching usernames must already exist on both sites. + +### API and Compatibility + +- APIs for images, videos, files, tags, search, bulk operations, backups, and system information. +- Global and personal tokens, accepted through request headers or upload forms. +- Twikoo / EasyImage-compatible uploads through `POST /api/index.php`. +- Built-in API documentation and debugger with generated `curl` examples. + +## Deployment + +### Docker ```bash docker run -d \ @@ -83,22 +119,97 @@ docker run -d \ -p 6892:6892 \ -v ./data:/data \ --restart unless-stopped \ - muxui/pichost:latest + yeomaiyelove/pichost:latest ``` -Open `http://:6892` and complete the setup wizard. +Open `http://:6892` and complete the setup wizard. Data is stored in the host `./data` directory by default. -**Full guide** (env vars, upgrades, dual-domain setup, API, Twikoo, reverse proxy, local dev, etc.): **[Documentation](https://o96u.github.io/PicHost/en/)**. +Docker Hub: -| Branch | Notes | -| ------ | ----- | -| [**main**](https://github.com/O96u/PicHost/tree/main) | Default: multi-backend, dual-domain, unified `images/` storage | -| [**cloudflare**](https://github.com/O96u/PicHost/tree/cloudflare) | Cloudflare R2 only; live demo [pic.roven.cc](https://pic.roven.cc) | +- `yeomaiyelove/pichost:latest` +- `yeomaiyelove/pichost:` + +### Windows + +The Windows x64 installer is self-contained: + +- Node.js and FFmpeg are bundled; no runtime download is required on the target computer. +- The first launch opens the web setup wizard. +- Data is stored in the `data` directory under the installation directory. +- Uninstall asks whether to delete the data directory. If preserved, the database, media, and backups remain on disk. + +### FnOS + +FnOS uses a dedicated x86 FPK package that runs the bundled Docker image: + +1. Import the matching `yeomaiyelove/pichost:` image into FnOS Docker. +2. Confirm that the image appears locally. +3. Install the FPK and choose account creation or backup restore in the wizard. + +The FPK uses the local image and does not pull PicHost from the internet. + +## Development and Packaging + +### Local Development + +```bash +npm ci +npm run dev +``` + +The first visit opens `/setup`. Common verification commands: + +```bash +npm test +npm run typecheck +npm run lint +npm run build +``` + +### Release Artifacts + +```bash +npm run pack:docker +npm run pack:fpk +npm run pack:windows +``` + +On Windows, all artifacts can be built at once: + +```bash +npm run pack:all +``` + +Output directories: + +- Docker image archive: `dist-docker/` +- FnOS package: `dist-fpk/` +- Windows installer: `dist-windows/release/` + +See [packaging/README.md](packaging/README.md) for requirements and override options. + +## Data Directory + +- Docker uses `/data` by default and supports the `DATA_DIR` override. +- Windows installs use the `data` directory under the installation path. +- Local development uses `data` in the project root. + +The database is stored as `pichost.db`. Create regular full-site backups and keep the `.phost.tar.gz` files on separate storage. + +## Tech Stack + +| Layer | Technologies | +| ----- | ------------ | +| Frontend | Nuxt 4 · Nuxt UI 4 · Vue 3 · Tailwind CSS 4 · TypeScript | +| Backend | Nitro `node-server` · REST API · H3 | +| Database | SQLite | +| Images | Sharp (WebP compression) | +| Video | FFmpeg · HLS · hls.js | +| Storage | Local disk · S3-compatible object storage · Telegram | +| Internationalization | @nuxtjs/i18n (Simplified Chinese / English) | +| Quality and documentation | Vitest · ESLint · vue-tsc · VitePress | +| Deployment | Docker · Node.js 22 · Electron (Windows) · FnOS FPK | ## License [GPL-3.0](LICENSE) - -## Friend links - -[LINUX DO](https://linux.do/) diff --git a/README.md b/README.md index 995403b..7a46c09 100644 --- a/README.md +++ b/README.md @@ -4,32 +4,37 @@

PicHost

-

个人轻量图床 · 图片放好，管理也要顺手

+

自托管图片、视频与文件管理平台

-

自托管图床 / 多用户 / Docker / API / Twikoo · 本地磁盘或对象存储

+

多用户 · WebP 压缩 · HLS 视频 · 文件床 · 标签 · 多存储后端 · 整站备份与迁移

- version - CI + version Nuxt 4 - Docker + Docker + Windows x64 + 飞牛 x86 GPL-3.0

- 文档 · 预览 · - 特性 · - 技术栈 · - 快速开始 · + 功能 · + 部署 · + 开发与打包 · + 文档源码 · English

--- -## 界面预览 +## 项目简介 -**main** 分支暂无公网演示；**cloudflare** 分支在线体验：[pic.roven.cc](https://pic.roven.cc) +PicHost 是一个面向 NAS、家庭服务器和小型自托管场景的媒体管理平台，可统一管理图片、视频和普通文件。除上传与直链外，还提供多用户、标签、搜索、多存储后端、HLS 视频处理、整站备份恢复、跨后端迁移以及两站点同步。 + +首次启动通过 Web 向导创建管理员，也可以直接从 `.phost.tar.gz` 完整备份恢复。 + +## 界面预览 | 上传 | 图库 | | :--: | :--: | @@ -51,31 +56,63 @@ | :------: | | ![操作日志](docs/screenshots/logs.png) | -## 特性 +## 核心功能 -- **拖拽 / 点击 / Ctrl+V 粘贴**上传；服务端 WebP 压缩、Referer 防盗链 -- **多用户**：账号密码登录（滑块 / Turnstile / Cap 人机验证）、可选开放注册；普通用户仅见自己的图片 -- **多后端存储**：本地磁盘 + S3 兼容（R2 / COS / OSS / AWS）+ Telegram 频道/群组；混合直链 `proxy` / `public` -- **图库**：浏览、搜索、按存储/来源/标签筛选、网格/列表切换、批量删除与批量打标；统计概览与来源分布；点击图片查看详情与多格式链接 -- **标签**：每用户独立标签、彩色标记；上传后单张/批量打标；设置页管理（新建、改色、合并、删除）；API 支持 `tagIds` 与批量打标 -- **备份与迁移**：整站导出/恢复（`.phost.tar.gz`）、跨后端同步；setup 未初始化时可从备份恢复 -- **API 与 Twikoo**：全局 / 个人 Token；`POST /api/index.php` 兼容 -- **Docker 零配置**：首次访问 Web 引导创建管理员 +### 图片管理 -## 技术栈 +- 支持拖拽、文件选择和 `Ctrl+V` 粘贴上传，可配置格式、大小、批量数量和频率限制。 +- 服务端使用 Sharp 压缩为 WebP，也可保留原图；支持可选的浏览器端 WebP 压缩。 +- 图库支持搜索、分页、存储后端/上传来源/标签筛选，以及网格和列表视图。 +- 支持查看详情、复制多种链接格式、批量打标和批量删除，并提供媒体数量与来源统计。 +- 支持 Referer 防盗链和来源域名白名单。 -| 层级 | 技术 | -| ---- | ---- | -| 前端 | [Nuxt 4](https://nuxt.com) · [Nuxt UI 4](https://ui.nuxt.com) · [Vue 3](https://vuejs.org) · [Tailwind CSS 4](https://tailwindcss.com) · TypeScript | -| 后端 | [Nitro](https://nitro.build)（`node-server`）· REST API | -| 数据 | SQLite · 本地 `data/pichost.db` | -| 图片处理 | [sharp](https://sharp.pixelplumbing.com)（服务端 WebP 压缩） | -| 存储 | 本地磁盘 · S3 兼容（[AWS SDK](https://aws.amazon.com/sdk-for-javascript/) · R2 / COS / OSS 等）· Telegram 频道/群组 | -| 国际化 | [@nuxtjs/i18n](https://i18n.nuxtjs.org)（简体中文 / English） | -| 质量与文档 | [Vitest](https://vitest.dev) · [VitePress](https://vitepress.dev) 文档站 | -| 部署 | Docker · Node.js 22 | +### 视频库与 HLS -## 快速开始 +- 独立的视频上传、搜索和管理页面，支持 MP4、M4V、WebM、MOV、MKV、AVI、FLV、WMV、MPG、MPEG 等格式。 +- 上传后自动生成视频缩略图，并可根据设置异步转码为 HLS。 +- 支持 `copy`、`veryfast`、`medium`、`slow`、`compress` 等转码档位，可限制并发数、CPU 核心数和目标码率。 +- 管理转码进度与失败原因，支持删除时同步清理原视频、缩略图、播放列表和 HLS 分片。 +- 支持复制原视频、缩略图和 HLS 地址，并可将 HLS 视频重新封装下载为 MP4。 + +### 文件床 + +- 独立管理普通文件，提供上传、搜索、分页、标签、批量删除和直链/下载链接。 +- 文件床访问策略可在后台配置，文件、图片和视频可分别使用独立域名。 + +### 多用户与权限 + +- 管理员与普通用户账号体系，普通用户只能查看和管理自己的媒体。 +- 支持滑块、Cloudflare Turnstile 和 Cap 人机验证，可选择开放注册。 +- 支持修改资料、修改密码、管理员清空密码和迁移到账号密码登录。 +- 每个用户拥有独立标签和自动删除策略，可设置媒体保存天数。 +- 提供登录与上传频率限制、全局/个人 API Token 和操作日志。 + +### 存储与迁移 + +- 支持本地磁盘、S3 兼容对象存储和 Telegram 频道/群组。 +- S3 兼容 R2、COS、OSS、AWS S3 等服务，支持 `proxy` 和 `public` 两种访问方式。 +- 可配置多个存储后端、默认后端、启用状态和容量配额。 +- 支持在已配置后端之间迁移图片、视频、文件和索引，迁移后可将目标后端设为默认。 + +### 备份与站点同步 + +- 创建和恢复完整 `.phost.tar.gz` 站点备份，包含数据库、图片、视频、文件、缩略图、HLS 内容和标签。 +- 备份恢复前可预检文件数量、媒体大小、新增与冲突情况，并选择跳过或覆盖冲突。 +- 支持大体积备份流式上传，无需将整个压缩包读入内存。 +- 未初始化时可在首次设置页直接恢复备份；云存储密钥不会写入备份，恢复后需重新填写。 +- 支持两站点双向同步，可推送或拉取全部媒体，也可只同步图片、视频或文件。 +- 站点同步支持断点继续、冲突策略和任务进度；目标站点需要预先存在同名用户。 + +### API 与兼容性 + +- 提供图片、视频、文件、标签、搜索、批量操作、备份和系统接口。 +- 支持全局 Token 和个人 Token，可通过请求头或表单上传。 +- 兼容 Twikoo / EasyImage 的 `POST /api/index.php` 上传接口。 +- 前端内置 API 文档和调试界面，支持直接生成并复制 `curl` 示例。 + +## 部署方式 + +### Docker ```bash docker run -d \ @@ -83,22 +120,97 @@ docker run -d \ -p 6892:6892 \ -v ./data:/data \ --restart unless-stopped \ - muxui/pichost:latest + yeomaiyelove/pichost:latest ``` -浏览器打开 `http://<主机IP>:6892`，按引导完成设置即可。 +浏览器打开 `http://<主机IP>:6892`，按向导创建管理员即可。数据默认保存在宿主机的 `./data` 目录。 -**详细说明**（环境变量、双域名、API、Twikoo、反向代理、本地开发等）见 **[用户文档](https://o96u.github.io/PicHost/)**。 +Docker Hub： -| 分支 | 说明 | +- `yeomaiyelove/pichost:latest` +- `yeomaiyelove/pichost:<版本号>` + +### Windows + +项目提供 Windows x64 一体安装包： + +- 内置 Node.js 和 FFmpeg，不依赖目标电脑预装运行环境。 +- 首次启动后按 Web 向导完成设置。 +- 数据保存在安装目录下的 `data` 子目录。 +- 卸载时会询问是否删除数据；选择保留后，数据库、图片、视频和备份不会被删除。 + +### 飞牛 NAS + +飞牛使用独立的 x86 FPK 安装包，FPK 以内置 Docker 镜像方式运行： + +1. 在飞牛 Docker 中导入与 FPK 版本对应的镜像包。 +2. 确认镜像列表中存在 `yeomaiyelove/pichost:<版本号>`。 +3. 安装 FPK，并按向导选择创建管理员或从备份恢复。 + +FPK 使用本地镜像，不会自动联网拉取 PicHost 镜像。 + +## 开发与打包 + +### 本地开发 + +```bash +npm ci +npm run dev +``` + +默认开发地址由 Nuxt 输出，首次访问会进入 `/setup`。常用检查命令： + +```bash +npm test +npm run typecheck +npm run lint +npm run build +``` + +### 构建安装产物 + +```bash +npm run pack:docker +npm run pack:fpk +npm run pack:windows +``` + +Windows 环境可以一次构建全部产物： + +```bash +npm run pack:all +``` + +输出位置： + +- Docker 离线镜像：`dist-docker/` +- 飞牛安装包：`dist-fpk/` +- Windows 安装程序：`dist-windows/release/` + +详细环境要求和可覆盖参数见 [打包说明](packaging/README.md)。 + +## 数据目录 + +- Docker 默认使用 `/data`，通过 `DATA_DIR` 可覆盖。 +- Windows 安装版使用安装目录下的 `data`。 +- 本地开发默认使用项目根目录下的 `data`。 + +数据库文件为 `pichost.db`。建议定期在后台创建整站备份，并将 `.phost.tar.gz` 文件保存到其他磁盘。 + +## 技术栈 + +| 层级 | 技术 | | ---- | ---- | -| [**main**](https://github.com/O96u/PicHost/tree/main) | 默认主线：多后端、双域名、统一 `images/` 存储 | -| [**cloudflare**](https://github.com/O96u/PicHost/tree/cloudflare) | 仅 Cloudflare R2；在线演示 [pic.roven.cc](https://pic.roven.cc) | +| 前端 | Nuxt 4 · Nuxt UI 4 · Vue 3 · Tailwind CSS 4 · TypeScript | +| 后端 | Nitro `node-server` · REST API · H3 | +| 数据库 | SQLite | +| 图片处理 | Sharp（WebP 压缩） | +| 视频处理 | FFmpeg · HLS · hls.js | +| 存储 | 本地磁盘 · S3 兼容对象存储 · Telegram | +| 国际化 | @nuxtjs/i18n（简体中文 / English） | +| 测试与文档 | Vitest · ESLint · vue-tsc · VitePress | +| 部署 | Docker · Node.js 22 · Electron（Windows）· 飞牛 FPK | ## License [GPL-3.0](LICENSE) - -## 友链 - -[LINUX DO](https://linux.do/)