LitePic V2 文档 - 西风图床

LitePic V2 使用文档

面向部署者、第三方调用方和 WordPress 接入方的完整说明。

支持格式 .JPG / .JPEG / .PNG / .GIF / .WEBP / .ICO / .SVG / .BMP / .TIFF / .TIF 单文件上限 50MB 缩略图 640x360 压缩模式 IMAGEMAGICK 远程存储 SYNC

项目简介

LitePic V2 是一个轻量级 PHP 图床系统，提供本地上传、第三方 API 上传、自动缩略图、自动压缩、自动转 WebP、图库管理、统计分析以及 R2/S3 远程同步能力。

系统设计目标是“上传不中断”：即使压缩或转换失败，原始上传流程仍可继续完成，并在处理结果中返回具体原因。

图片功能介绍

上传能力

支持单图/多图、拖拽、粘贴、第三方 API 上传，服务端统一校验格式和大小。

缩略图机制

上传后自动生成缩略图，图库列表优先展示缩略图，复制和查看使用原图地址。

自动压缩

支持 ImageMagick / GD / TinyPNG / 混合模式。不可压缩格式自动跳过，不阻塞上传。

自动转 WebP

支持 JPG/JPEG/PNG/GIF 转换为 WebP，可按设置仅保留 WebP 成果文件。

图库管理

支持批量选择、批量删除、批量压缩、批量转 WebP、复制多种链接格式。

统计分析

提供访问量、图片数、空间占用、文件类型分布、时间维度统计。

历史文件扫描

可扫描旧 upload 目录并重建图库索引、缩略图与统计数据，便于迁移升级。

R2/S3 同步

支持 OFF/SYNC/BACKUP 模式，可同步原图和缩略图到对象存储。

上传后处理链路

接收文件并完成格式/大小校验。
保存原图并记录原始文件名映射。
生成缩略图（支持格式才生成）。
按配置执行自动压缩（失败只记录，不终止）。
按配置执行自动 WebP 转换（失败只记录，不终止）。
如 WebP 成功且配置要求，仅保留最终文件并清理原图。
按远程模式同步到 R2/S3，并返回处理报告。

第三方上传 API

接口	`POST /api/upload.php`
鉴权	`X-API-Key: <token>` 或 `Authorization: Bearer <token>`
文件字段	`image` / `image[]` / `file` / `files[]`
返回	`results[]`，逐文件给出 `status` / `url` / `thumbnail_url` / `processing`

cURL 示例

curl -X POST "https://your-domain.com/api/upload.php" \
  -H "Authorization: Bearer ltp_xxxxxxxxx" \
  -F "image[]=@/path/a.jpg" \
  -F "image[]=@/path/b.png"

成功返回示例（节选）

{
  "status": "success",
  "results": [
    {
      "status": "success",
      "filename": "20260227_xxx.webp",
      "original_name": "demo.jpg",
      "url": "https://your-domain.com/uploads/2026/02/20260227_xxx.webp",
      "thumbnail_url": "https://your-domain.com/uploads/2026/02/.thumbs/20260227_xxx.webp",
      "processing": {
        "auto_compress": {"enabled": true, "compressed": true, "method": "imagemagick"},
        "auto_webp": {"enabled": true, "created": true},
        "original_deleted": true,
        "final_filename": "20260227_xxx.webp"
      }
    }
  ]
}

后台图片操作接口（已登录/已鉴权）

操作	请求	说明
压缩	`GET /action.php?action=compress&file=xxx.jpg`	仅支持 JPG/JPEG/PNG，返回压缩比例和体积变化。
转 WebP	`GET /action.php?action=webp&file=xxx.png`	支持 JPG/JPEG/PNG/GIF，成功后返回新文件 URL。
删除	`GET /action.php?action=delete&file=xxx.webp`	删除原图并清理缩略图，必要时联动远程存储删除。

Token 与安全策略

可在系统设置中创建多个 API Token，用于第三方系统调用上传 API。
Token 支持随时撤销，撤销后立即失效。
压缩 API Key（TinyPNG）支持多 Key 轮询，系统记录每个 Key 的调用次数与状态。
建议在生产环境启用 HTTPS，并限制 Token 泄露面（仅在服务端保存）。

WordPress 插件对接建议

在插件设置中填写图床地址（例如 https://your-domain.com）。
填写 API Token，并点击“连接测试”。
开启“WordPress 上传同步到图床”。
在文章编辑器中使用“插入图床图片”按钮，选择已上传图片或直接上传。

推荐在插件中优先使用 /api/upload.php 作为上传入口，返回结构稳定且带处理报告。

运维与排障

如出现“未压缩/未转 WebP”，可在开启调试后查看 logs/YYYY-MM-DD.log 的 upload post-process 记录。
旧数据迁移后，可使用扫描功能重建图库数据与缩略图。
当对象存储配置不完整时，系统会回退为本地可用模式，上传不会被中断。