使用说明

核心功能

FrankenPHP 部署（推荐）

LitePic 默认推荐 FrankenPHP 经典模式（内置 Caddy + PHP）。仓库根目录已带 Caddyfile：敏感路径拒绝、php_ini 上传上限、try_files 兜底都已写好。 仍可用 Nginx + PHP-FPM（见仓库 nginx-litepic.conf），但新站优先按本节走。

不要开 worker mode。LitePic 的配置缓存与 Session 按「每请求独立 boot」设计；worker 常驻会导致设置变更不生效、登录态异常。

1. 安装 FrankenPHP（二进制或 Docker dunglas/frankenphp）。
2. 解压 / clone LitePic 到站点目录，复制 .env.example → .env，改好 SITE_URL。
3. 创建可写目录，并把属主改成跑 PHP 的用户（见下方「目录权限」）。
4. 用仓库自带 Caddyfile 启动；生产用 SERVER_NAME 开自动 HTTPS。
5. 浏览器打开站点，默认密码 12345678 登录后立刻改密；大批量处理再加一行 worker.php cron。

cd /path/to/LitePic
cp -n .env.example .env
mkdir -p uploads data logs

# systemd 官方包通常以 frankenphp 用户运行：
sudo chown -R frankenphp:frankenphp uploads data logs
# 若用当前用户直接 frankenphp run，可改为：
# chown -R "$(id -u):$(id -g)" uploads data logs
chmod -R u+rwX,g+rwX uploads data logs

# 生产：换成你的域名
SERVER_NAME=img.example.com frankenphp run --config ./Caddyfile

# 本地试跑
frankenphp run --config ./Caddyfile
# → http://127.0.0.1:8080

[Unit]
Description=LitePic (FrankenPHP)
After=network.target

[Service]
Type=simple
User=frankenphp
Group=frankenphp
WorkingDirectory=/var/www/litepic
Environment=SERVER_NAME=img.example.com
ExecStart=/usr/bin/frankenphp run --config /var/www/litepic/Caddyfile
Restart=on-failure

[Install]
WantedBy=multi-user.target

docker run --rm -d \
  --name litepic \
  -p 80:80 -p 443:443 \
  -v "$PWD":/app \
  -e SERVER_NAME=img.example.com \
  -w /app \
  dunglas/frankenphp \
  frankenphp run --config /app/Caddyfile

{
	frankenphp {
		php_ini {
			upload_max_filesize 200M
			post_max_size 220M
			max_file_uploads 50
			memory_limit 256M
			max_input_time 600
		}
	}
	servers {
		timeouts {
			read_body 10m
		}
	}
}

{$SERVER_NAME::8080} {
	root * {$LITEPIC_ROOT:.}
	request_body {
		max_size 200MB
	}

	@denied {
		path /.env* /.git* /.user.ini /data/* /logs/* /app/* /bin/*
		path_regexp php_in_uploads (?i)^/uploads/.*\.php$
	}
	respond @denied 403

	php_server
}

# 查看进程用户
ps aux | grep frankenphp

# 对齐可写目录（按实际用户改名）
sudo chown -R frankenphp:frankenphp /path/to/LitePic/uploads \
  /path/to/LitePic/data /path/to/LitePic/logs
sudo chmod -R u+rwX,g+rwX /path/to/LitePic/uploads \
  /path/to/LitePic/data /path/to/LitePic/logs

* * * * * php /path/to/LitePic/worker.php >/dev/null 2>&1

可配置项

下面是 LitePic 后台 设置 里的关键开关清单。保存后写入 SQLite 设置表（不是覆盖 .env）； PHP-FPM 场景还会同步站点根目录 .user.ini。.env 主要用于首次导入默认值。 装好后进入 设置 → 基础 → 环境信息 可查看当前实际生效值。

检查实际生效值：进入 设置 → 基础 → 环境信息 可看 PHP 版本、GD / Imagick、AVIF/WebP/HEIC 能力、Web 服务器、上传上限等。

压缩方式选择

设置页的「压缩方式」只影响 JPG/JPEG/PNG 的压缩链路，与「转换引擎 / WebP·AVIF 转换」相互独立。

转换策略：格式转换由「转换引擎」控制（默认 Imagick 优先、回退 GD）。单张转换可同步返回；图库批量选 2 张及以上时常进异步队列。

修改 PHP 上传限制

应用层上限在后台保存到 SQLite（键 MAX_FILE_SIZE / MAX_FILE_SIZE_MB），默认示例多为 20MB。真正拦大文件的是运行环境：FrankenPHP 看 Caddyfile 的 php_ini + request_body； PHP-FPM 看 php.ini / .user.ini，Nginx 还要 client_max_body_size。 三者取最严；仓库默认 Caddyfile 已放开到约 200MB，可按需下调。

1. 进入 设置 → 基础，修改「最大上传大小（MB）」并保存。
2. 确认 PHP upload_max_filesize ≥ 该值，且 post_max_size 略大。
3. FrankenPHP：同步改 Caddyfile 后 reload；Nginx：再改 client_max_body_size。
4. 重载服务后到 设置 → 基础 → 环境信息 核对「上传上限」。

frankenphp {
	php_ini {
		upload_max_filesize 200M
		post_max_size 220M
		max_file_uploads 50
		memory_limit 256M
	}
}
request_body {
	max_size 200MB
}

frankenphp reload --config /path/to/LitePic/Caddyfile
# 或 systemctl reload frankenphp

upload_max_filesize = 200M
post_max_size = 220M
max_file_uploads = 50
memory_limit = 256M
max_execution_time = 600
max_input_time = 600

sudo systemctl restart php8.3-fpm
sudo systemctl reload nginx

server {
    client_max_body_size 200m;
}

php_value upload_max_filesize 200M
php_value post_max_size 220M
php_value memory_limit 256M
php_value max_execution_time 600

open_basedir=/path/to/LitePic/:/tmp/:/proc/cpuinfo:/proc/meminfo:/proc/uptime:/etc/os-release
upload_max_filesize=200M
post_max_size=220M
max_file_uploads=50
memory_limit=256M

验证：环境信息卡片的上传上限；或 php -i | grep -E "upload_max_filesize|post_max_size|memory_limit"。 未生效通常是服务未重载、Caddy/Nginx 请求体限制更严，或面板上层限制更低。

开启防盗链

LitePic 的防盗链由 PHP 在 /i/<文件> 路由上校验 Referer，不依赖写入 .htaccess，也不要求你先改 Nginx/Caddy 规则。 开启后，后台复制出的公网图片链接会统一走 /i/...（由 image.php → ImageServeService 提供）。

1. 进入 设置 → 图片处理，填写「防盗链允许域名」（英文逗号分隔）。
2. 开启「启用防盗链（开启后图片链接强制走 /i/<文件> 由 PHP 校验 Referer）」，保存。
3. 用新复制的链接测试：本站页面内嵌应正常；外站盗链应 403。
4. （可选加固）若仍担心有人猜到物理路径直链 /uploads/...，可在 Web 服务器额外禁止公网访问该目录，或只允许本机反代——这是可选加固，不是当前防盗链的主路径。

说明：Referer 防盗链适合拦普通外站引用，不能当鉴权。关闭防盗链后，链接样式回退到「图片链接格式」配置（例如存储目录前缀）。

允许无来源请求是什么意思？

图片防盗链主要依赖浏览器请求里的 Referer 判断来源。「无来源请求」就是请求里没有 Referer，常见于直接打开图片地址、复制 URL 到新标签页、隐私浏览器、浏览器插件隐藏来源，或聊天软件、App、代理/CDN 请求图片时没有传来源。

1. 开启后：没有 Referer 的请求会放行，用户可以直接打开图片链接；防盗链主要拦截带有外站 Referer 的盗链请求。
2. 关闭后：没有 Referer 的请求也会被拒绝，规则更严格，但直接打开图片链接、部分隐私浏览器或 App 访问图片可能失败。
3. 建议默认开启。这样不影响正常分享图片链接，同时还能拦截大多数外站直接引用。

水印设置

文字水印默认使用白色文字，并在文字背后生成半透明磨砂底层。字体会优先使用服务器上的 Ubuntu 字体；没有 Ubuntu 字体时会回退到系统可用字体或 GD 内置字体。

1. 进入 设置 → 图片处理，开启「启用水印」。
2. 选择文字或 PNG 图片水印；文字水印可开「磨砂底层」并调透明度 / 内边距 / 圆角。
3. 需要自定义字体时，上传 TTF / OTF（中文请用含中文字形的字体）。
4. PNG 水印请用透明背景；配置后优先使用图片水印。

建议：PNG 图片水印请使用透明背景，并把最大宽度控制在原图宽度的 20% 到 30% 之间，避免遮挡图片主体。

开启 WebP 转换

WebP 转换由「转换引擎」完成：默认 auto（Imagick 优先，不可用则回退 GD imagewebp()）。 「压缩方式」里的 ImageMagick / GD / TinyPNG 只影响压缩，不等于转换能力。

1. 进入 设置 → 图片处理，将「转换优先格式」设为 WebP。
2. 开启上传后自动转换（或图库批量转换），保存。
3. 在 设置 → 基础 → 环境信息 确认 WebP 能力为已启用（GD 或 Imagick 任一即可）。
4. 上传 JPG/PNG/GIF/HEIC 等源图测试。

sudo apt update
sudo apt install -y php-gd php-imagick webp imagemagick
# FrankenPHP 用户：装对应 php-zts / 扩展后 reload frankenphp
sudo systemctl restart php8.3-fpm   # 仅 PHP-FPM 场景

php -m | grep -Ei "gd|imagick"
php -r 'var_dump(function_exists("imagewebp"));'
# Imagick：后台环境信息也会探测 WEBP 格式

面板环境：启用 fileinfo、gd，有条件再装 imagick。 仅 GD 且 imagewebp() 为 false 时，需换带 WebP 的 PHP 构建，或改用 Imagick。

开启 AVIF 转换

AVIF 对环境要求更高。可用路径：GD imageavif()（常需 PHP 8.1+ 且编译支持），或 Imagick 支持 AVIF。 后台「AVIF 支持」徽章会同时认 GD 与 Imagick。

1. 确认 PHP / 扩展能力（见下方命令）。
2. 进入 设置 → 图片处理，偏好格式选 AVIF，开启自动或批量转换。
3. 在环境信息确认「AVIF 支持」已启用。
4. 上传测试图，查看处理报告 / 队列结果。

sudo apt update
sudo apt install -y php-gd php-imagick imagemagick libavif-bin
sudo systemctl restart php8.3-fpm   # PHP-FPM；FrankenPHP 则 reload 服务

php -v
php -r 'var_dump(function_exists("imageavif"));'
# 或看设置页环境信息「AVIF 支持」徽章

排障：GD 无 imageavif 时，可装 Imagick+AVIF，或先用 WebP。批量多张 AVIF 常走异步队列。

上传后处理链路

上传请求只负责校验、落盘原图、写入元数据并入队，尽快返回。耗时工作由队列异步完成（响应后轻量 drain、心跳调度，或 cron 跑 worker.php）。

1. 接收文件并完成格式 / 大小校验。
2. 保存原图，写入 images 表与原始文件名映射。
3. 将后处理任务写入 import_queue（缩略图、压缩、转换、水印、远程同步等按配置入队）。
4. Worker 消费队列：缩略图 → 压缩 / 格式转换 →（可选）删原图 → 水印 → 最终缩略图 → R2/S3 同步。
5. 任一步失败只记报告 / 失败队列，不回滚已成功入库的原图。

注意：目前没有自动 EXIF 清理。大批量上传请配置 cron： cd /path/to/LitePic && php worker.php >> logs/worker.log 2>&1。

认证与安全

• 可在 设置 → 账号 创建多个第三方 API Token，供外部上传接口使用；只在创建时显示一次，可随时撤销。
• TinyPNG API Key 支持多 Key 轮询，并记录调用状态。
• 后台写操作受 CSRF Token 保护。
• 建议生产启用 HTTPS，Token 只放在服务端。

接口与外部接入

上传、导出、后台图片操作与 WordPress 插件说明见 litepic.io/api。

Token 在实例后台创建：登录 → 设置 → 账号 → 新建 API Token。只显示一次。

运维与排障

• 如出现「未压缩 / 未转 WebP / 未转 AVIF」，可在开启调试后查看 logs/YYYY-MM-DD.log 的 upload post-process 记录。
• 上传报「保存失败」且日志有 Permission denied：把 uploads / data / logs 属主改成 FrankenPHP 进程用户（多为 frankenphp），详见 FrankenPHP 部署。
• 旧数据迁移后，可使用设置中的扫描功能重建图库数据、缩略图与统计数据。
• 当对象存储配置不完整时，系统会回退为本地可用模式，上传不会被中断。
• 若 AVIF 转换失败，请确认 PHP 版本 ≥ 8.1，且 GD 已编译 AVIF 支持（php -r 'var_dump(function_exists("imageavif"));'）或已装 Imagick + AVIF。