adminroot
73847d8107
Add Live Photo playback for paired MOV/MP4/M4V videos and embedded Google and Samsung JPEG clips, with hover/tap controls, viewer replay, and original-video range and cache responses. Show top-level albums and direct subfolders with breadcrumb navigation and nested album search. Add browser regression fixtures and update album navigation checks. Bump Rust and frontend versions and their lockfiles to 0.2.7. Validated: frontend and Rust builds, 121 Rust tests (2 network tests not run), 198 layout cases, and Chromium live-photo and album navigation checks.
96 lines
4.9 KiB
Markdown
96 lines
4.9 KiB
Markdown
# Pixhelf
|
||
|
||
一隅光影，满架时光。
|
||
|
||
轻量、自托管的图片画廊，支持 JPEG、PNG、WebP，相册与 Justified 布局、中文自然语言搜索、以图搜图、随机探索，以及原图下载、EXIF 和直方图。
|
||
|
||
## Docker 部署（推荐）
|
||
|
||
镜像支持 Linux amd64 / arm64，内置文字搜图模型。将以下内容保存为 [`compose.yml`](compose.yml)：
|
||
|
||
```yaml
|
||
services:
|
||
pixhelf:
|
||
image: eureka6688/pixhelf:latest
|
||
restart: unless-stopped
|
||
ports:
|
||
- "3002:3002"
|
||
volumes:
|
||
- "./pic:/data/pic:ro"
|
||
- pixhelf-data:/data/.pixhelf-data
|
||
|
||
volumes:
|
||
pixhelf-data:
|
||
```
|
||
|
||
```bash
|
||
mkdir -p pic
|
||
docker compose up -d
|
||
```
|
||
|
||
把图片放入 `pic`，或将 `./pic` 换成已有图片目录。打开 `http://服务器地址:3002`，创建管理员账号并设置至少 15 个字符的密码即可使用，无需额外配置登录环境变量。首次初始化仅能完成一次，部署后请先创建管理员。
|
||
|
||
程序自动索引图片并检测目录变化；索引期间可按文件名搜索，完成后支持自然语言搜索。公网部署建议使用 HTTPS 反向代理，代理目标为 `服务器地址:3002`，同一 Docker 网络内可用 `pixhelf:3002`；图库页面和 API 应遵循应用的缓存指令。
|
||
|
||
## 使用与设置
|
||
|
||
- **浏览图片**：点击查看大图，桌面右键或手机长按打开菜单，可查看图片信息、查找相似图片或下载原图。
|
||
- **浏览相册**：首页显示顶层文件夹，进入后显示直属子相册；可通过路径导航返回上层。搜索会查找所有层级，支持直接进入子相册；同名文件夹通过完整路径区分。
|
||
- **实况照片**：支持 JPEG、PNG、WebP 与同名 MOV／MP4／M4V 配对，以及 Google／Samsung 二合一 JPG。桌面悬停播放；手机首次轻点播放，之后再点打开大图，播完也有效；播放过另一张实况后，回到之前的图片需先点一次播放。大图自动播放一遍，之后单击重播。全页面最多同时播放一个，等待时显示细进度条。浏览器可缓存原视频，不转码、不生成服务端视频缓存文件，也不依赖 FFmpeg。HEVC 需浏览器和设备支持；HEIC／HEIF 照片暂不支持，可导出为 JPEG 并保留同名视频。
|
||
- **以图搜图**：侧栏“相似图片”支持上传不超过 20 MB 的 JPG、PNG、WebP；查询图片仅用于搜索，不写入图库。
|
||
- **账号安全**：设置中可修改用户名和密码，保存后所有设备需重新登录。
|
||
- **访客模式**：默认关闭。开启“免登录浏览”后，来访者无需密码即可浏览、搜图和下载；账号设置与外部存储仅限管理员。
|
||
- **外部存储**：在设置中连接 OpenList，填写服务地址、账号密码或令牌及起始目录，即可浏览、预览和下载远程文件。
|
||
|
||
## 更新与数据
|
||
|
||
```bash
|
||
docker compose pull
|
||
docker compose up -d
|
||
docker compose logs --tail=50 -f pixhelf
|
||
```
|
||
|
||
`pixhelf-data` 卷挂载到 `/data/.pixhelf-data`，保存缩略图、索引、账号与设置。卷内 `thumbnails/auth/` 保存管理员和访客配置，`thumbnails/settings/` 保存外部存储配置。保留并备份此卷，更新或重建容器后设置仍在；`docker compose down -v` 会删除数据卷。
|
||
|
||
<details>
|
||
<summary>从旧的 pixhelf-cache 升级</summary>
|
||
|
||
先运行 `docker volume ls` 确认原卷名。将新 Compose 底部的卷声明改为以下形式，即可通过新名称和挂载路径复用原有账号与数据：
|
||
|
||
```yaml
|
||
volumes:
|
||
pixhelf-data:
|
||
external: true
|
||
name: 原项目名_pixhelf-cache
|
||
```
|
||
|
||
将 `原项目名_pixhelf-cache` 替换为实际旧卷名，然后执行 `docker compose up -d`。如需同时更换实际卷名，先停服并将旧卷完整复制到新卷，再使用默认 Compose。
|
||
|
||
独立运行时，先停止程序，将工作目录中的 `.pixhelf-cache` 改名为 `.pixhelf-data`；也可继续用 `--cache-dir` 或 `PIXHELF_CACHE_DIR` 指向原来的 `thumbnails` 目录。
|
||
|
||
</details>
|
||
|
||
## 可选配置
|
||
|
||
按需在 Compose 服务中添加 `environment`，其余参数可通过 `docker compose exec pixhelf /pixhelf --help` 查看。
|
||
|
||
| 环境变量 | 默认值 | 用途 |
|
||
| --- | --- | --- |
|
||
| `PIXHELF_TEXT_SEARCH_MODEL` | 镜像内置模型 | 设为 `false` 关闭自然语言搜索 |
|
||
| `PIXHELF_WORKERS` | 自动选择 2–4 | 后台处理并发数，范围 1–16 |
|
||
| `PIXHELF_SCAN_INTERVAL` | `10` | 图片目录扫描间隔，单位秒 |
|
||
|
||
## 源码运行
|
||
|
||
需要 Rust stable、Node.js 22+ 和 npm。
|
||
|
||
```bash
|
||
npm --prefix frontend ci
|
||
cargo build --release
|
||
./target/release/pixhelf --gallery-dir /path/to/photos
|
||
```
|
||
|
||
前端随 Cargo 构建并嵌入程序，默认数据目录为 `./.pixhelf-data/thumbnails`，可用 `--cache-dir` 指定其他位置。独立程序会自动下载文字搜图模型，可加 `--text-search-model false` 关闭。
|
||
|
||
验证：`cargo test`；浏览器回归使用 `npm --prefix frontend run auth-check`（需先执行 `cargo build`，并安装 OpenSSL 和 Chromium）。
|