Pixhelf

基于 Axum 和 Preact 的自托管图片画廊。Preact 生产资源会嵌入 Rust 可执行文件，运行时只需要一个程序文件和外部图库目录。

运行

默认从当前工作目录的 ./pic 读取图片，并监听 0.0.0.0:3002：

./target/release/pixhelf

HTTP 服务会立即开放，并优先生成首批 60 张缩略图。每张图片只生成一套最长边 720px、质量 82 的高质量 WebP 缩略图；其余缩略图由后台任务持续处理。新增、修改或删除图片会在定期扫描后自动同步，图库为空时也可正常启动并等待后续图片。

首屏图库数据与压缩后的关键样式会随 HTML 一并下发，首张图片会提前加载。JS 使用内容版本化的长期缓存，API 使用 ETag 协商缓存，并按浏览器能力启用 Brotli 或 gzip 压缩。

缩略图缓存在 ./.pixhelf-cache/thumbnails 下的单一版本化目录，原图不会被修改。点击图片后，查看器会先显示这份缩略图，再加载原图，并提前预取相邻原图；超大原图会在浏览器内解码到 GPU 安全画布，不会生成第二套预览缓存。查看器支持键盘切换、滚轮缩放，以及移动端滑动、双击和双指缩放。缓存目录必须位于图库目录之外。

构建

需要当前稳定版 Rust、Node.js 20+ 和 npm：

cd frontend
npm ci
cd ..
cargo build --release

cargo build 会自动执行 React 生产构建，并将结果嵌入 target/release/pixhelf。

参数

--gallery-dir PATH     图库目录，默认 ./pic
--cache-dir PATH       缩略图缓存，默认 ./.pixhelf-cache/thumbnails
--listen HOST:PORT     监听地址，默认 0.0.0.0:3002
--initial-batch N      启动前生成数量，默认 60
--workers N            后台压缩并发数，默认按 CPU 自动选择 2-4
--scan-interval SEC    图库重新扫描间隔，默认 10 秒

支持 JPEG、PNG 和 WebP 文件。其他文件不会进入图库索引。