Photo Gallery Site

一个现代化的照片画廊网站，采用 React + TypeScript 构建，支持从多种存储源（S3、GitHub）自动同步照片，具有高性能 WebGL 渲染、瀑布流布局、EXIF 信息展示、缩略图生成等功能。

🌟 特性

核心功能

• 🖼️ 高性能 WebGL 图像渲染器 - 基于自研 WebGL 组件，支持流畅的缩放、平移操作
• 📱 响应式瀑布流布局 - 采用 Masonic 实现，自适应不同屏幕尺寸
• 🎨 现代化 UI 设计 - 基于 Tailwind CSS 和 Radix UI 组件库
• ⚡ 增量同步 - 智能检测文件变化，仅处理新增或修改的照片

图像处理

• 🔄 HEIC/HEIF 格式支持 - 自动转换 Apple 设备的 HEIC 格式
• 🖼️ 智能缩略图生成 - 多尺寸缩略图，优化加载性能
• 📊 EXIF 信息展示 - 完整的拍摄参数，包括相机型号、焦距、光圈等
• 🌈 Blurhash 占位符 - 优雅的图片加载体验
• 📱 Live Photo 支持 - 检测并展示 iPhone Live Photo

高级功能

• 🎛️ 富士胶片模拟 - 读取和展示富士相机的胶片模拟设置
• 🔍 全屏查看器 - 支持手势操作的图片查看器
• 🏷️ 智能标签 - 基于 EXIF 数据自动生成标签
• ⚡ 并发处理 - 支持多进程/多线程并发处理
• 🗂️ 多存储支持 - S3、GitHub 等多种存储后端

🏗️ 技术架构

前端技术栈

• React 19 - 使用最新的 React 版本和 Compiler
• TypeScript - 完整的类型安全
• Vite - 现代化构建工具
• Tailwind CSS - 原子化 CSS 框架
• Radix UI - 无障碍组件库
• Jotai - 状态管理
• TanStack Query - 数据获取和缓存
• React Router 7 - 路由管理

构建系统

• Node.js - 服务端运行时
• Sharp - 高性能图像处理
• AWS SDK - S3 存储操作
• Worker Threads/Cluster - 并发处理
• EXIF-Reader - EXIF 数据提取

存储架构

采用适配器模式设计，支持多种存储后端：

• S3 兼容存储 - AWS S3、MinIO、阿里云 OSS 等
• GitHub 存储 - 使用 GitHub 仓库作为图片存储

📦 项目结构

photo-gallery-site/
├── apps/web/                    # 主应用
│   ├── src/
│   │   ├── components/          # React 组件
│   │   │   ├── ui/             # UI 组件库
│   │   │   └── common/         # 通用组件
│   │   ├── core/               # 核心构建系统
│   │   │   ├── builder/        # 主构建器
│   │   │   ├── storage/        # 存储适配器
│   │   │   ├── image/          # 图像处理
│   │   │   ├── photo/          # 照片处理
│   │   │   └── worker/         # 并发处理
│   │   ├── modules/            # 功能模块
│   │   ├── pages/              # 页面组件
│   │   └── data/               # 数据文件
│   ├── public/                 # 静态资源
│   └── scripts/                # 构建脚本
├── packages/webgl-viewer/       # WebGL 图像查看器
├── config/                     # 配置文件
└── docs/                       # 文档

🚀 快速开始

环境要求

• Node.js 18+
• 至少 4GB RAM（用于图像处理）

1. 克隆项目

git clone https://github.com/Iris-Photo-Gallery/Iris.git
cd photo-gallery-site

2. 安装依赖

pnpm install

3. 环境配置

创建 .env 文件：

# S3 存储配置
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your_access_key_id
S3_SECRET_ACCESS_KEY=your_secret_access_key
S3_ENDPOINT=https://s3.amazonaws.com
S3_BUCKET_NAME=your_bucket_name
S3_PREFIX=photos/
S3_CUSTOM_DOMAIN=your_custom_domain.com

4. 站点配置

复制并编辑配置文件：

cp config.example.json config.json

编辑 config.json：

{
  "name": "我的照片画廊",
  "title": "我的照片画廊",
  "description": "记录生活中的美好瞬间",
  "url": "https://gallery.example.com",
  "accentColor": "#007bff",
  "author": {
    "name": "Your Name",
    "url": "https://example.com"
  },
  "social": {
    "twitter": "@yourusername"
  }
}

5. 构建照片清单

# 首次构建
pnpm run build:manifest

# 增量更新
pnpm run build:manifest

# 强制全量更新
pnpm run build:manifest -- --force

6. 启动开发服务器

pnpm dev

⚙️ 配置选项

构建器配置

创建 builder.config.json 文件进行高级配置：

{
  "repo": {
    "enable": false,
    "url": "https://github.com/username/gallery-assets"
  },
  "storage": {
    "provider": "s3",
    "bucket": "my-photos",
    "region": "us-east-1",
    "prefix": "photos/",
    "customDomain": "cdn.example.com"
  },
  "options": {
    "defaultConcurrency": 8,
    "maxPhotos": 5000,
    "enableLivePhotoDetection": true,
    "showProgress": true,
    "showDetailedStats": true
  },
  "logging": {
    "verbose": true,
    "level": "info",
    "outputToFile": false
  },
  "performance": {
    "worker": {
      "workerCount": 8,
      "timeout": 30000,
      "useClusterMode": true,
      "workerConcurrency": 2
    }
  }
}

配置选项说明

存储配置 (storage)

• provider: 存储提供商 (s3 | github)
• bucket: S3 存储桶名称
• region: S3 区域
• endpoint: S3 端点（可选）
• prefix: 文件前缀
• customDomain: 自定义域名

构建选项 (options)

• defaultConcurrency: 默认并发数 (1-50)
• maxPhotos: 最大照片数量限制
• enableLivePhotoDetection: 启用 Live Photo 检测
• showProgress: 显示构建进度
• showDetailedStats: 显示详细统计信息

性能配置 (performance)

• worker.workerCount: Worker 进程数
• worker.timeout: Worker 超时时间（毫秒）
• worker.useClusterMode: 启用集群模式

日志配置 (logging)

• verbose: 详细日志
• level: 日志级别 (info | warn | error | debug)
• outputToFile: 输出到文件

远程资源库配置

如果你有独立的资源仓库存储缩略图和清单：

{
  "repo": {
    "enable": true,
    "url": "https://github.com/username/gallery-assets"
  }
}

这将自动从远程仓库拉取资源，避免每次构建。

📋 CLI 命令

构建命令

# 查看帮助
pnpm run build:manifest -- --help

# 增量更新（默认）
pnpm run build:manifest

# 强制全量更新
pnpm run build:manifest -- --force

# 仅重新生成缩略图
pnpm run build:manifest -- --force-thumbnails

# 仅重新生成清单
pnpm run build:manifest -- --force-manifest

开发命令

# 启动开发服务器
pnpm dev

# 构建生产版本
pnpm build

🚀 部署指南

Vercel 部署（推荐）

1. Fork 项目

   • 访问 GitHub 仓库
   • 点击右上角的 "Fork" 按钮，将项目 fork 到你的 GitHub 账户

2. 在 Vercel 部署

   • 访问 Vercel
   • 使用 GitHub 账户登录
   • 点击 "New Project"，选择你刚才 fork 的仓库
   • 在项目设置中添加以下环境变量（如果你使用 S3 存储）：

S3_REGION=us-east-1
S3_ACCESS_KEY_ID=你的 S3 访问密钥 ID
S3_SECRET_ACCESS_KEY=你的 S3 秘密访问密钥
S3_ENDPOINT=https://s3.amazonaws.com
S3_BUCKET_NAME=你的 S3 存储桶名称
S3_PREFIX=photos/
S3_CUSTOM_DOMAIN=你的自定义域名（可选）

3. 触发部署
   • 配置完环境变量后，Vercel 会自动开始部署
   • 等待部署完成，你的照片画廊就上线了！

注意事项

• 确保你的 S3 存储桶已经包含照片文件
• 如果使用远程资源库，需要先配置 builder.config.json

🔧 高级用法

自定义存储提供商

实现 StorageProvider 接口以支持新的存储后端：

import { StorageProvider } from './src/core/storage/interfaces'

class MyStorageProvider implements StorageProvider {
  async getFile(key: string): Promise<Buffer | null> {
    // 实现文件获取逻辑
  }

  async listImages(): Promise<StorageObject[]> {
    // 实现图片列表获取逻辑
  }

  // ... 其他方法
}

自定义图像处理

在 src/core/image/ 目录下添加自定义处理器：

export async function customImageProcessor(buffer: Buffer) {
  // 自定义图像处理逻辑
  return processedBuffer
}

📄 许可证

MIT License © 2025 Innei

🔗 相关链接

• 在线演示
• 个人网站
• GitHub
• 问题反馈

---

如果这个项目对你有帮助，请给个 ⭐️ Star 支持一下！