Cosine Gallery

项目简介

一个基于 Next.js 14 的现代化 ACG 艺术作品展示平台，为 Telegram 频道 @CosineGallery 提供在线图库服务。项目实现了高性能的图片瀑布流展示、全文搜索、艺术家管理等核心功能，支持数千张图片的流畅浏览体验。

• 用户活跃度：月活用户 4.44k+，月访问量 4.89k+，月浏览量 13.6k+，平均访问时长 1分39秒，跳出率 61%（数据来源：Umami Analytics）

项目周期：2024.10 - 2025.08（10 个月） 项目角色：全栈开发工程师

技术栈

前端技术

• 框架：Next.js 14 (App Router)、React 18、TypeScript
• 样式方案：Tailwind CSS v4、CSS Modules、PostCSS
• 状态管理：Jotai (原子化状态)、SWR (服务端状态)、TanStack Query
• UI 组件：Radix UI、自定义组件库
• 动画：Motion (原 Framer Motion)、自定义动画系统
• 图片处理：React Photo View、Masonic Grid、虚拟化滚动

后端技术

• 数据库：PostgreSQL + Prisma ORM
• 搜索引擎：Meilisearch (全文搜索)
• API 设计：RESTful API、Next.js API Routes
• 数据序列化：Superjson (支持 BigInt、Date 等复杂类型)

工程化

• 部署：PM2 进程管理、Docker 容器化
• 性能优化：ISR (增量静态再生成)、图片懒加载、虚拟化列表

核心功能与技术实现

1. 高性能瀑布流图片展示系统

功能描述：

• 自实现瀑布流布局算法，替代第三方库，实现精确的列高计算和图片定位
• 支持动态列数调整（2-8 列），响应式适配不同屏幕尺寸
• 提供分页模式和无限滚动模式切换

技术亮点：

• 自研瀑布流算法：使用 Masonic 库作为基础，重写核心布局逻辑
• 虚拟化渲染：对大列表进行视口内元素渲染优化，减少 DOM 节点数量
• 图片多源回退机制：实现 ImageAutoFallback 组件，支持 S3 图源 → Pixiv 代理的自动降级

2. Meilisearch 全文搜索集成

功能描述：

• 集成 Meilisearch 搜索引擎，支持图片标题、作者、标签的全文检索
• 提供多维度搜索过滤器（平台、作者、标签、R18、AI 生成）
• 实现搜索建议和实时搜索结果预览

技术实现：

• 索引管理：开发管理 API 实现索引的初始化、批量索引、健康检查
• 批量索引：采用分批处理策略（每批 100 张），避免内存溢出
• 实时同步：图片上传/更新时自动同步至搜索索引

3. 数据库架构设计与迁移

技术实现：

• PostgreSQL：重构数据库架构，优化查询性能
• Prisma ORM：类型安全的数据库操作，自动生成 TypeScript 类型定义
• 数据模型设计：Images 表、ImageTags 多对多关系表、Stash 临时存储表
• 连接池优化：配置 Prisma 连接池参数，避免开发环境连接泄漏

4. 艺术家管理系统

• 艺术家列表页面，支持按最后更新时间排序
• 艺术家详情页，展示该作者的所有作品
• 使用 Prisma 的 groupBy 和聚合查询统计每个艺术家的作品数量

5. 标签系统与标签云

• 标签云页面，可视化展示所有标签及其使用频率
• 使用加权算法计算标签字体大小，热门标签显示更大
• 支持多标签组合筛选和过滤

6. RSS 订阅功能

• 使用 feed 库生成符合标准的 RSS 2.0 和 Atom 订阅源
• 配置 Next.js rewrites 实现多路径访问

项目难点与解决方案

难点 1：大规模图片数据的高性能渲染

问题：3000+ 张图片同时渲染导致页面卡顿

解决方案：

1. 实现虚拟化滚动，仅渲染视口内及附近的图片
2. 使用 Masonic 的 useInfiniteLoader 实现增量加载
3. 使用 React.memo 和 useMemo 优化组件性能

效果：页面渲染时间从 3s 降至 0.5s，滚动帧率稳定在 60fps

难点 2：搜索索引的性能优化

问题：3000+ 张图片的全量索引需要 10+ 分钟

解决方案：

1. 采用分批处理策略，每批处理 100 张图片
2. 使用流式处理，避免一次性加载所有数据到内存
3. 实现索引健康检查和增量更新机制

效果：索引时间降至 2 分钟，内存占用减少 70%

项目成果

• 性能指标：首屏加载时间 < 1s，TTI (可交互时间) < 2s
• 数据规模：管理 3000+ 张图片，50+ 位艺术家，200+ 个标签
• 用户体验：支持分页/无限滚动双模式，搜索响应时间 < 100ms
• 可维护性：TypeScript 类型覆盖率 100%，代码规范严格