Lsky Pro 自定义版开发文档

这个项目是什么

Lsky Pro 自定义版（仓库 jinghui/lsky-pro-custom）是开源图床 Lsky Pro 的深度定制版，线上实例为 https://img.88531.cn 。相比官方版，它新增了三大能力：OCR 智能搜索（上传图片自动识别文字，搜索时直接输入图片里的文字就能找到图）、图片在线编辑器（浏览器内裁剪/旋转/调色，无需下载专业软件）、独立 Token 管理页（查看 Token 来源、IP、使用时间，API 上传支持指定相册），并修复了图片交互与相册计数的一批 Bug。

重要认知：本仓库不是完整的 Lsky Pro 全量源码，而是相对官方版的改动文件子集——顶层只含 app/、database/、public/、resources/、routes/ 五个目录加 CHANGELOG.md、README.md。使用方式是在官方 Lsky Pro 部署的基础上，用这些目录覆盖对应文件。

技术栈与架构

后端：Laravel 9 + PHP 8.1（沿用 Lsky Pro 官方技术栈）。
前端：Tailwind CSS + Alpine.js；图片编辑器集成 Cropper.js（v1.6.1，仓库内 public/js/cropper/ 自带库文件）+ Canvas API。
OCR：Tesseract 5 引擎 + 中文语言包（简体/繁体），服务层封装为 app/Services/OcrService.php，上传图片时自动识别文字并入库，搜索同时匹配文件名与 OCR 文字。
存储：沿用官方的多存储支持（本地 / 阿里云 OSS / 腾讯云 COS / 七牛云 / 又拍云）。

仓库结构

路径	说明
`app/`	PHP 后端改动：`app/Services/OcrService.php`（OCR 服务）、`app/Services/ImageService.php`（集成 OCR）、`app/Http/Controllers/User/ImageController.php`（新增 `edit()` 图片编辑保存）、`app/Http/Controllers/User/AlbumController.php` 与 `app/Http/Controllers/Api/V1/AlbumController.php`（相册动态计数）、`app/Http/Controllers/User/TokenController.php`（Token 管理）、`app/Models/Image.php`（OCR 搜索支持）、`app/Models/Album.php`
`database/`	新增迁移 `2026_07_01_191052_add_ocr_text_to_images_table`：`images` 表新增 `ocr_text` 字段（TEXT，可空）
`public/`	Cropper.js 库文件（`js/cropper/cropper.min.js`、`cropper.min.css`）
`resources/`	视图改动：`resources/views/user/images.blade.php`（编辑器 UI + 交互修复）、`resources/views/user/tokens.blade.php`（Token 管理页）
`routes/`	`routes/web.php` 新增路由：`PUT /user/images/{id}/edit`（图片编辑保存）、`GET/POST /tokens`（Token 管理页）

部署与二次开发流程

基于官方 Lsky Pro（Docker 容器名示例为 lsky-pro）叠加本仓库改动：

# 1. 安装 Tesseract OCR 与中文语言包
docker exec lsky-pro apt-get update
docker exec lsky-pro apt-get install -y tesseract-ocr tesseract-ocr-chi-sim tesseract-ocr-chi-tra

# 2. 执行数据库迁移（images 表加 ocr_text 字段）
docker exec lsky-pro php artisan migrate

# 3. 清除缓存
docker exec lsky-pro php artisan cache:clear
docker exec lsky-pro php artisan view:clear
docker exec lsky-pro php artisan route:clear

为已有图片批量补 OCR 识别（可选）：

docker exec lsky-pro php artisan tinker
>>> $service = new App\Services\OcrService();
>>> $images = App\Models\Image::whereNull('ocr_text')->get();
>>> foreach ($images as $img) { $service->processImage($img); echo '.'; }

二次开发要点

模型层改动：Image 模型的 scopeFilter 移除了 whereNull('album_id') 默认过滤（修复未选相册时搜索为空的问题），fill 数组新增 ocr_text 字段；改上传链路时注意 OCR 字段的写入路径在 ImageService。
相册计数：Album 模型废弃静态 image_num 字段，前后端（用户端与 API v1）都改用 withCount('images') 动态计数——不要在新代码里再依赖 image_num。
图片交互修复范围：DragSelect 与 Viewer.js 在动态加载后失效的问题、切换相册后图片不显示的问题，改动集中在 resources/views/user/images.blade.php，前端改动时注意保持动态加载后重新初始化。
API 契约：上传接口支持 album_id 指定相册；Token 信息包含来源、IP、最后使用时间，管理页分页每页 10 条。
覆盖式部署：更新官方版后需要用本仓库的五个目录重新覆盖对应文件，再跑一遍迁移与清缓存。