Skip to content

Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.

docs: update README.md

Timothy Yin01d039a5138a
diff --git a/README.md b/README.md
index 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=s3
NUXT_PROVIDER_S3_ENDPOINT=
-NUXT_PROVIDER_S3_BUCKET=
+NUXT_PROVIDER_S3_BUCKET=chronoframe
NUXT_PROVIDER_S3_REGION=auto
NUXT_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 OAuth
NUXT_OAUTH_GITHUB_CLIENT_ID=
NUXT_OAUTH_GITHUB_CLIENT_SECRET=
-NUXT_SESSION_PASSWORD=
-# 地图服务配置 (可选)
+# Mapbox Token
MAPBOX_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 访问令牌,用于地图服务 | 无 | 是 |
+
+## 📸 截图
+
+![Gallery](./docs/images/screenshot1.png)
+![Photo Detail](./docs/images/screenshot2.png)
+![Map Explore](./docs/images/screenshot3.png)
+![Dashboard](./docs/images/screenshot4.png)
+
+## 🛠️ 开发
+
+### 环境要求
+
+- 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**
+
- 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.png
new file mode 100644
index 00000000..807d554b
Binary files /dev/null and b/docs/images/screenshot1.png differ
diff --git a/docs/images/screenshot2.png b/docs/images/screenshot2.png
new file mode 100644
index 00000000..05e82219
Binary files /dev/null and b/docs/images/screenshot2.png differ
diff --git a/docs/images/screenshot3.png b/docs/images/screenshot3.png
new file mode 100644
index 00000000..c1291078
Binary files /dev/null and b/docs/images/screenshot3.png differ
diff --git a/docs/images/screenshot4.png b/docs/images/screenshot4.png
new file mode 100644
index 00000000..6b51e68b
Binary files /dev/null and b/docs/images/screenshot4.png differ