Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.
TypeScript albumsexif-extractiongeocodinglive-photomotion-photophoto-galleryphoto-sharingwebgl-viewer
docs: update README.md
Timothy Yin01d039a5138a
diff --git a/README.md b/README.mdindex 3dffe792..c6b0b1a9 100644--- a/README.md+++ b/README.md@@ -9,86 +9,170 @@<img src="https://img.shields.io/badge/WebGL-2.0-FF6600.svg" alt="WebGL"></p>-丝滑的照片管理和查看应用,使用 WebGL 硬件加速技术提供流畅的图片浏览体验。+丝滑的照片展示和管理应用,支持多种图片格式和大尺寸图片渲染。[在线演示: TimoYin's Mems](https://lens.bh8.ga)## ✨ 特性### 🖼️ 强大的图片管理+- **在线管理照片** - 通过 Web 界面轻松管理和浏览照片+- **探索地图** - 在地图上浏览照片拍摄位置- **智能 EXIF 解析** - 自动提取拍摄时间、地理位置、相机参数等元数据-- **地理位置识别** - 自动识别照片拍摄地点,支持地图可视化-- **多格式支持** - 支持 JPEG、PNG、HEIC *(转换为 JPEG)*、RAW 等主流图片格式+- **地理位置识别** - 自动识别(Reverse Geocoding)照片拍摄地点+- **多格式支持** - 支持 JPEG、PNG、HEIC/HEIF 等主流图片格式- **智能缩略图** - 基于 ThumbHash 技术的高效缩略图生成-### 🚀 WebGL 硬件加速查看器-- **流畅缩放平移** - 基于 WebGL 的硬件加速渲染,支持丝滑的缩放和平移-- **渐进式加载** - 智能 LOD (Level of Detail) 系统,根据缩放级别加载最适合的图片质量-- **触控支持** - 完整的触摸手势支持,包括捏合缩放、双击缩放等-- **响应式设计** - 适配桌面端和移动端,提供一致的用户体验-### 🔧 现代技术栈+- **Nuxt 4** - 基于最新的 Nuxt 框架,提供 SSR/SSG 支持- **TypeScript** - 完整的类型安全保障-- **Drizzle ORM** - 类型安全的数据库 ORM- **TailwindCSS** - 现代化的 CSS 框架-- **Pinia** - Vue 3 状态管理+- **Drizzle ORM** - 类型安全的数据库 ORM### ☁️ 灵活的存储方案-- **多存储后端** - 支持 S3 兼容存储、*GitHub、本地文件系统 (尚未实现)* 等-- **CDN 加速** - 可配置 CDN 加速图片访问--## 🚀 快速开始-### 环境要求+- **多存储后端** - 支持 S3 兼容存储、GitHub(WIP)、本地文件系统(WIP) 等+- **CDN 加速** - 可配置 CDN 地址加速图片访问-- Node.js 18+-- pnpm 9.0+-- 支持 WebGL 的现代浏览器--### 安装依赖--```bash-# 使用 pnpm (推荐)-pnpm install+## 🐳 部署-# 或使用其他包管理器-npm install-yarn install-```+推荐使用预构建的 docker 镜像部署,[在 ghcr 上查看镜像](https://github.com/HoshinoSuzumi/chronoframe/pkgs/container/chronoframe)-### 配置环境变量+### Docker-复制环境变量模板并根据需要配置:+修改命令中的环境变量后运行:```bash-cp .env.example .env+docker run -d \+ --name chronoframe \+ -p 3000:3000 \+ -v $(pwd)/data:/app/data \+ -e NUXT_PUBLIC_APP_TITLE="" \+ -e NUXT_PUBLIC_APP_SLOGAN="" \+ -e NUXT_PUBLIC_APP_AVATAR_URL="" \+ -e NUXT_STORAGE_PROVIDER="s3" \+ -e NUXT_PROVIDER_S3_ENDPOINT="" \+ -e NUXT_PROVIDER_S3_BUCKET="chronoframe" \+ -e NUXT_PROVIDER_S3_REGION="auto" \+ -e NUXT_PROVIDER_S3_ACCESS_KEY_ID="" \+ -e NUXT_PROVIDER_S3_SECRET_ACCESS_KEY="" \+ -e NUXT_PROVIDER_S3_PREFIX="photos/" \+ -e NUXT_PROVIDER_S3_CDN_URL="" \+ -e NUXT_OAUTH_GITHUB_CLIENT_ID="" \+ -e NUXT_OAUTH_GITHUB_CLIENT_SECRET="" \+ -e NUXT_SESSION_PASSWORD="" \+ -e MAPBOX_TOKEN="" \+ ghcr.io/hoshinosuzumi/chronoframe:latest```-主要配置项:+### Docker Compose++创建 `.env` 文件```env-# 存储配置-NUXT_STORAGE_PROVIDER=s3+# 应用标题与口号+NUXT_PUBLIC_APP_TITLE=+NUXT_PUBLIC_APP_SLOGAN=+NUXT_PUBLIC_APP_AVATAR_URL=+# 存储配置(使用 S3)+NUXT_STORAGE_PROVIDER=s3NUXT_PROVIDER_S3_ENDPOINT=-NUXT_PROVIDER_S3_BUCKET=+NUXT_PROVIDER_S3_BUCKET=chronoframeNUXT_PROVIDER_S3_REGION=autoNUXT_PROVIDER_S3_ACCESS_KEY_ID=NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=NUXT_PROVIDER_S3_PREFIX=photos/NUXT_PROVIDER_S3_CDN_URL=+# 会话密码(必须设置,建议为一个随机长字符串)+NUXT_SESSION_PASSWORD=+# GitHub OAuthNUXT_OAUTH_GITHUB_CLIENT_ID=NUXT_OAUTH_GITHUB_CLIENT_SECRET=-NUXT_SESSION_PASSWORD=-# 地图服务配置 (可选)+# Mapbox TokenMAPBOX_TOKEN=```+创建 `docker-compose.yml`:++```yaml+services:+ chronoframe:+ image: ghcr.io/hoshinosuzumi/chronoframe:latest+ container_name: chronoframe+ restart: unless-stopped+ ports:+ - '3000:3000'+ volumes:+ - ./data:/app/data+ env_file:+ - .env+```++启动:++```bash+docker-compose up -d+```++### 环境变量列表++| 环境变量 | 说明 | 默认值 | 必需 |+| :--------------------------------- | :--------------------------------------- | :---------- | :---------------------------------------- |+| NUXT_PUBLIC_APP_TITLE | 应用标题 | ChronoFrame | 否 |+| NUXT_PUBLIC_APP_SLOGAN | 应用口号 | 无 | 否 |+| NUXT_PUBLIC_APP_AVATAR_URL | 应用头像 URL | 无 | 否 |+| NUXT_STORAGE_PROVIDER | 存储提供者,支持 `s3`、`github`、`local` | `s3` | 是 |+| NUXT_PROVIDER_S3_ENDPOINT | S3 兼容存储服务的 Endpoint | 无 | 当 `NUXT_STORAGE_PROVIDER` 为 `s3` 时必需 |+| NUXT_PROVIDER_S3_BUCKET | S3 存储桶名称 | chronoframe | 当 `NUXT_STORAGE_PROVIDER` 为 `s3` 时必需 |+| NUXT_PROVIDER_S3_REGION | S3 存储桶区域 | auto | 当 `NUXT_STORAGE_PROVIDER` 为 `s3` 时必需 |+| NUXT_PROVIDER_S3_ACCESS_KEY_ID | S3 访问密钥 ID | 无 | 当 `NUXT_STORAGE_PROVIDER` 为 `s3` 时必需 |+| NUXT_PROVIDER_S3_SECRET_ACCESS_KEY | S3 访问密钥 | 无 | 当 `NUXT_STORAGE_PROVIDER` 为 `s3` 时必需 |+| NUXT_PROVIDER_S3_PREFIX | S3 存储前缀 | photos/ | 否 |+| NUXT_PROVIDER_S3_CDN_URL | S3 存储的 CDN 地址 | 无 | 否 |+| NUXT_OAUTH_GITHUB_CLIENT_ID | GitHub OAuth 应用的 Client ID | 无 | 是 |+| NUXT_OAUTH_GITHUB_CLIENT_SECRET | GitHub OAuth 应用的 Client Secret | 无 | 是 |+| NUXT_SESSION_PASSWORD | 用于加密会话的密码,32 位随机字符串 | 无 | 是 |+| MAPBOX_TOKEN | Mapbox 访问令牌,用于地图服务 | 无 | 是 |++## 📸 截图+++++++## 🛠️ 开发++### 环境要求++- Node.js 18++- pnpm 9.0+++### 安装依赖++```bash+# 使用 pnpm (推荐)+pnpm install++# 或使用其他包管理器+npm install+yarn install+```++### 配置环境变量++复制环境变量模板并根据需要配置:++```bash+cp .env.example .env+```+### 数据库初始化```bash@@ -108,40 +192,28 @@ pnpm dev应用将在 `http://localhost:3000` 启动。-## 📖 使用指南--### 上传照片--1. 点击头像跳转到 GitHub 认证登录-1. 访问仪表板页面 `/dashboard`-2. 在 `Photos` 页面中选择图片并点击上传(支持批量上传和拖拽上传)-3. 系统将自动提取 EXIF 信息、生成缩略图并逆编码照片地理位置--## 🛠️ 开发-### 项目结构```chronoframe/-├── app/ # Nuxt 应用代码-│ ├── components/ # Vue 组件-│ ├── pages/ # 页面路由-│ ├── composables/ # 组合式函数-│ └── stores/ # Pinia 状态管理-├── packages/ # 内部包-│ └── webgl-image/ # WebGL 图片查看器包-├── server/ # 服务端代码-│ ├── api/ # API 路由-│ ├── database/ # 数据库 schema 和迁移-│ └── services/ # 业务逻辑服务-├── shared/ # 共享类型和工具-└── docs/ # 项目文档+├── app/ # Nuxt 应用+│ ├── components/ # 组件+│ ├── pages/ # 页面路由+│ ├── composables/ # 组合式函数+│ └── stores/ # Pinia 状态管理+├── packages/+│ └── webgl-image/ # WebGL 图片查看器+├── server/+│ ├── api/ # API 路由+│ ├── database/ # 数据库 schema 和迁移+│ └── services/ # 业务逻辑服务+└── shared/ # 共享类型和工具```### 构建命令```bash-# 开发模式 (包含依赖包监听)+# 开发模式 (包含依赖包构建)pnpm dev# 仅构建依赖包@@ -150,76 +222,22 @@ pnpm build:deps# 构建生产版本pnpm build-# 预览生产版本-pnpm preview-# 数据库操作pnpm db:generate # 生成迁移文件pnpm db:migrate # 执行迁移-```--### WebGL 图片查看器包--ChronoFrame 包含一个独立的 WebGL 图片查看器包 `@chronoframe/webgl-image`,特性包括:--- 基于 WebGL 的硬件加速渲染-- 支持大尺寸图片的高性能显示-- 丰富的交互手势支持-- 完整的 TypeScript 类型定义-- 可独立使用于其他 Vue 项目-#### 在其他项目中使用--```bash-npm install @chronoframe/webgl-image-```--```vue-<template>- <WebGLImageViewer- :src="imageUrl"- :min-scale="0.5"- :max-scale="10"- center-on-init- @zoom-change="handleZoomChange"- />-</template>--<script setup>-import { WebGLImageViewer } from '@chronoframe/webgl-image'-import '@chronoframe/webgl-image/style'-</script>-```--## 🐳 部署--### 使用 Docker--```bash-# 构建镜像-docker build -t chronoframe .--# 运行容器-docker run -p 3000:3000 chronoframe-```--### 使用 Docker Compose--```bash-# 启动服务-docker-compose up -d--# 查看日志-docker-compose logs -f+# 预览生产版本+pnpm preview```-### 也可以使用预构建 Docker 镜像+## 📖 使用指南-[在 ghcr 上查看](https://github.com/HoshinoSuzumi/chronoframe/pkgs/container/chronoframe)+### 上传照片-```bash-docker pull ghcr.io/hoshinosuzumi/chronoframe:latest-```+1. 点击头像跳转到 GitHub 认证登录+2. 访问仪表板页面 `/dashboard`+3. 在 `Photos` 页面中选择图片并点击上传(支持批量上传和拖拽上传)+4. 系统将自动提取 EXIF 信息、生成缩略图并逆编码照片地理位置## 🤝 贡献@@ -235,7 +253,6 @@ docker pull ghcr.io/hoshinosuzumi/chronoframe:latest- 使用 TypeScript 进行类型安全的开发- 遵循 ESLint 和 Prettier 代码规范-- 编写必要的单元测试- 更新相关文档## 📄 许可证@@ -245,7 +262,8 @@ docker pull ghcr.io/hoshinosuzumi/chronoframe:latest## 👤 作者**Timothy Yin**+- Email: [email protected]- GitHub: [@HoshinoSuzumi](https://github.com/HoshinoSuzumi)- Website: [bh8.ga](https://bh8.ga)-- My Gallery: [lens.bh8.ga](https://lens.bh8.ga)+- Gallery: [lens.bh8.ga](https://lens.bh8.ga)diff --git a/docs/images/screenshot1.png b/docs/images/screenshot1.pngnew file mode 100644index 00000000..807d554bBinary files /dev/null and b/docs/images/screenshot1.png differdiff --git a/docs/images/screenshot2.png b/docs/images/screenshot2.pngnew file mode 100644index 00000000..05e82219Binary files /dev/null and b/docs/images/screenshot2.png differdiff --git a/docs/images/screenshot3.png b/docs/images/screenshot3.pngnew file mode 100644index 00000000..c1291078Binary files /dev/null and b/docs/images/screenshot3.png differdiff --git a/docs/images/screenshot4.png b/docs/images/screenshot4.pngnew file mode 100644index 00000000..6b51e68bBinary files /dev/null and b/docs/images/screenshot4.png differ