飞图 FlyPic 开发文档

这个项目是什么

FlyPic 飞图是一个轻量的图像素材检索、浏览与管理应用：支持数十万张图片流畅浏览，并能对图片做 OCR 文字搜索（关键词同时匹配文件名与图片内文字，中英双语）。本仓库是 ZangXincz/FlyPic 的 Docker 独立部署版分支——上游已归档停更、飞牛应用商店下架，本分支用多阶段 Dockerfile 把它跑成普通容器，不依赖飞牛 fnOS 应用框架，任何 Linux + Docker 环境都能部署。

对二次开发者来说，这是一个结构清晰的全栈样板：React 前端 + Express 后端 + SQLite 索引，加一个可插拔的 OCR 模块。

技术栈与架构

前端：React 18 + Vite 5 + TailwindCSS + Zustand + react-window（虚拟滚动瀑布流）+ react-photo-view（预览）。
后端：Node.js + Express + Sharp（缩略图）+ better-sqlite3（本地索引）+ Socket.IO（实时通知）+ tesseract（系统命令行 OCR）。
架构：后端三层 Config → Model → Service → Route；前端模块化 Store → Hooks → API。
OCR：调用系统 tesseract 命令，语言包 chi_sim + eng，在扫描图片时把识别文字写进 ocr_text 列；OCR 失败不影响扫描主流程。
索引：SQLite 存在素材目录的 .flypic/metadata.db，缩略图是 .flypic/thumbnails/ 下的 WebP。

仓库结构

路径	作用
`Dockerfile`	多阶段构建：前端 Vite 编译 → 后端依赖 → 运行时镜像（含 tesseract 与中英语言包）
`docker-compose.yml`	一键部署：端口 15002、素材库挂载、配置持久化
`backend/`	Node 后端
`backend/server.js`	服务入口
`backend/src/`	config / models / services / routes / middleware 分层实现
`backend/utils/ocr.js`	OCR 模块（系统 tesseract，chi_sim + eng）
`backend/utils/scanner.js`	素材扫描器，已集成 OCR 提取
`backend/database/db.js`	SQLite schema（`ocr_text` 列 + 索引）
`backend/test-thumbnail-cleanup.js`	缩略图清理测试脚本
`frontend/`	React 前端（`src/` 下 stores / hooks / api / components，`vite.config.js`、Tailwind/PostCSS 配置）
`scripts/build.js`	构建辅助脚本
`website/`	介绍页
`飞牛打包部署指南.md`	上游的 fpk 打包文档（Docker 部署不需要）
`config/`	运行时配置（JWT 密钥、素材库列表），已 gitignore，不入库

根 package.json 是 npm workspaces 单仓（frontend + backend 两个 workspace）。

本地开发环境

git clone http://127.0.0.1:3200/jinghui/flypic.git
cd flypic
npm install
npm run dev:frontend    # Vite 开发服务器，5173
npm run dev:backend     # Express 后端，15002

其他真实脚本：npm run dev（等价于只起后端）、npm run build:fpk（飞牛 fpk 打包）、npm run build:fpk:docker（容器内打包）、npm run test:docker（Docker 内测试）。裸机开发时后端需要系统装有 tesseract 才能出 OCR 文本。

配置项说明

docker-compose.yml 中的服务配置：

配置键	默认值	含义
端口映射	`15002:15002`	面板访问端口，`http://<主机IP>:15002`
`PORT`	`15002`	后端监听端口
`FRONTEND_DIST`	`/app/backend/public`	后端托管的前端产物目录
`NODE_ENV`	`production`	运行模式
素材库挂载	与宿主机同路径（如 `/vol2/1000/HD2/壁纸:/vol2/1000/HD2/壁纸`）	容器内路径与宿主机一致，中文路径直接可用；允许 `:ro`
配置卷	`/vol1/1000/HD1/docker/flypic/config:/root/.flypic`	持久化 `config.json`（素材库路径、管理员密码、JWT 密钥）

数据落点：素材库目录下 .flypic/（隐藏目录，存缩略图与 metadata.db）；应用级配置在项目 config/（已 gitignore）。

构建与发布

首次部署前先编辑 docker-compose.yml，把 volumes 换成自己的素材库目录，然后：

docker compose up -d --build

日常更新代码：

git pull && docker compose up -d --build

Dockerfile 三阶段：第一阶段用 Vite 编译前端，第二阶段装后端依赖，第三阶段是运行时镜像并安装 tesseract-ocr + chi-sim + eng 语言包。镜像内路径设计成与宿主机一致，因此中文目录无需做路径转换。

二次开发要点

新增素材库必须重新扫描，否则 OCR 文字不会进索引、搜不到；扫描时会同步生成缩略图与 ocr_text。
非侵入原则：只在素材目录创建 .flypic，不修改任何原始文件；删除该目录即可完全清除索引、重新扫描重建。
只读挂载可用：早期版本要求素材目录可写，现已改为仅验证可读，:ro 挂载的目录也能添加成功。
中文路径：compose 挂载示例支持任意中文目录（曾有 Path does not exist 的问题，已在 v1.1.0 修复）。
OCR 是可降级能力：容器内 tesseract 失败只影响文字列，扫描主流程照常；后端用的是系统命令行 tesseract 而非 npm 包，改镜像时注意别删掉语言包。
历史修复可当排雷清单：LibraryService.js 曾漏 require logger 导致添加素材库报 Internal server error；瀑布流交互约定为单击选中、Ctrl/Shift 多选、双击放大预览，改前端时保持这个约定。
scripts/ 与 飞牛打包部署指南.md 是上游 fpk 打包遗留，Docker 部署用不到，但 npm run build:fpk* 脚本仍真实存在。