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 and README_zh.md

Timothy Yin111ee69997ce
diff --git a/README.md b/README.md
index 46b07729..c0c997a9 100644
--- a/README.md
+++ b/README.md
@@ -9,40 +9,42 @@
<img src="https://img.shields.io/badge/WebGL-2.0-FF6600.svg" alt="WebGL">
</p>
-丝滑的照片展示和管理应用,支持多种图片格式和大尺寸图片渲染。
+**Languages:** English | [中文](README_zh.md)
-[在线演示: TimoYin's Mems](https://lens.bh8.ga)
+A smooth photo display and management application, supporting multiple image formats and large-size image rendering.
-## ✨ 特性
+[Live Demo: TimoYin's Mems](https://lens.bh8.ga)
-### 🖼️ 强大的图片管理
+## ✨ Features
-- **在线管理照片** - 通过 Web 界面轻松管理和浏览照片
-- **探索地图** - 在地图上浏览照片拍摄位置
-- **智能 EXIF 解析** - 自动提取拍摄时间、地理位置、相机参数等元数据
-- **地理位置识别** - 自动识别(Reverse Geocoding)照片拍摄地点
-- **多格式支持** - 支持 JPEG、PNG、HEIC/HEIF 等主流图片格式
-- **智能缩略图** - 基于 ThumbHash 技术的高效缩略图生成
+### 🖼️ Powerful Photo Management
-### 🔧 现代技术栈
+- **Manage photos online** - Easily manage and browse photos via the web interface
+- **Explore map** - Browse photo locations on a map
+- **Smart EXIF parsing** - Automatically extracts metadata such as capture time, geolocation, and camera parameters
+- **Reverse geocoding** - Automatically identifies photo shooting locations
+- **Multi-format support** - Supports mainstream formats including JPEG, PNG, HEIC/HEIF
+- **Smart thumbnails** - Efficient thumbnail generation using ThumbHash
-- **Nuxt 4** - 基于最新的 Nuxt 框架,提供 SSR/SSG 支持
-- **TypeScript** - 完整的类型安全保障
-- **TailwindCSS** - 现代化的 CSS 框架
-- **Drizzle ORM** - 类型安全的数据库 ORM
+### 🔧 Modern Tech Stack
-### ☁️ 灵活的存储方案
+- **Nuxt 4** - Built on the latest Nuxt framework with SSR/SSG support
+- **TypeScript** - Full type safety
+- **TailwindCSS** - Modern CSS framework
+- **Drizzle ORM** - Type-safe database ORM
-- **多存储后端** - 支持 S3 兼容存储、GitHub(WIP)、本地文件系统(WIP) 等
-- **CDN 加速** - 可配置 CDN 地址加速图片访问
+### ☁️ Flexible Storage Solutions
-## 🐳 部署
+- **Multiple storage backends** - Supports S3-compatible storage, GitHub (WIP), and local filesystem (WIP)
+- **CDN acceleration** - Configurable CDN URL for faster photo delivery
-推荐使用预构建的 docker 镜像部署,[在 ghcr 上查看镜像](https://github.com/HoshinoSuzumi/chronoframe/pkgs/container/chronoframe)
+## 🐳 Deployment
+
+We recommend deploying with the prebuilt Docker image. [View the image on ghcr](https://github.com/HoshinoSuzumi/chronoframe/pkgs/container/chronoframe)
### Docker
-修改命令中的环境变量后运行:
+Run with customized environment variables:
```bash
docker run -d \
@@ -72,7 +74,7 @@ docker run -d \
### Docker Compose
-创建 `.env` 文件
+Create a .env file:
```env
# Admin user email (required)
@@ -108,7 +110,7 @@ NUXT_OAUTH_GITHUB_CLIENT_SECRET=
MAPBOX_TOKEN=
```
-创建 `docker-compose.yml`:
+Create docker-compose.yml:
```yaml
services:
@@ -124,158 +126,212 @@ services:
- .env
```
-启动:
+Start:
```bash
docker-compose up -d
```
-### 环境变量列表
-
-| 环境变量 | 说明 | 默认值 | 必需 |
-| :--------------------------------- | :--------------------------------------- | :---------- | :---------------------------------------- |
-| CFRAME_ADMIN_EMAIL | 初始管理员用户的邮箱 | 无 | 是,填写登录使用的 GitHub 账户的邮箱 |
-| CFRAME_ADMIN_NAME | 初始管理员用户的用户名 | Chronoframe | 否 |
-| CFRAME_ADMIN_PASSWORD | 初始管理员用户的密码 | CF1234@! | 否 |
-| 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 访问令牌,用于地图服务 | 无 | 是 |
-
-## 📸 截图
+### Environment Variables
+
+| Variable | Description | Default | Required |
+| :--------------------------------- | :--------------------------------------------- | :---------- | :---------------------------------------- |
+| CFRAME_ADMIN_EMAIL | Email of the initial admin user | None | Yes, must be the GitHub account email used for login |
+| CFRAME_ADMIN_NAME | Username of the initial admin | Chronoframe | No |
+| CFRAME_ADMIN_PASSWORD | Password of the initial admin | CF1234@! | No |
+| NUXT_PUBLIC_APP_TITLE | Application title | ChronoFrame | No |
+| NUXT_PUBLIC_APP_SLOGAN | Application slogan | None | No |
+| NUXT_PUBLIC_APP_AVATAR_URL | Application avatar URL | None | No |
+| NUXT_STORAGE_PROVIDER | Storage provider (s3, github, local) | s3 | Yes |
+| NUXT_PROVIDER_S3_ENDPOINT | S3 endpoint | None | Required if provider is s3 |
+| NUXT_PROVIDER_S3_BUCKET | S3 bucket name | chronoframe | Required if provider is s3 |
+| NUXT_PROVIDER_S3_REGION | S3 bucket region | auto | Required if provider is s3 |
+| NUXT_PROVIDER_S3_ACCESS_KEY_ID | S3 access key ID | None | Required if provider is s3 |
+| NUXT_PROVIDER_S3_SECRET_ACCESS_KEY | S3 secret access key | None | Required if provider is s3 |
+| NUXT_PROVIDER_S3_PREFIX | S3 object prefix | photos/ | No |
+| NUXT_PROVIDER_S3_CDN_URL | S3 CDN URL | None | No |
+| NUXT_OAUTH_GITHUB_CLIENT_ID | GitHub OAuth app Client ID | None | Yes |
+| NUXT_OAUTH_GITHUB_CLIENT_SECRET | GitHub OAuth app Client Secret | None | Yes |
+| NUXT_SESSION_PASSWORD | Session encryption password (32 chars) | None | Yes |
+| MAPBOX_TOKEN | Mapbox access token for map service | None | Yes |
+
+## 📸 Screenshots
![Gallery](./docs/images/screenshot1.png)
![Photo Detail](./docs/images/screenshot2.png)
![Map Explore](./docs/images/screenshot3.png)
![Dashboard](./docs/images/screenshot4.png)
-## 🛠️ 开发
+## 🛠️ Development
-### 环境要求
+### Requirements
- Node.js 18+
- pnpm 9.0+
-### 安装依赖
+### Install dependencies
```bash
-# 使用 pnpm (推荐)
+# With pnpm (recommended)
pnpm install
-# 或使用其他包管理器
+# Or with other package managers
npm install
yarn install
```
-### 配置环境变量
-
-复制环境变量模板并根据需要配置:
+### Configure environment variables
```bash
cp .env.example .env
```
-### 数据库初始化
+### Initialize database
```bash
-# 2. 生成数据库迁移文件(可选)
+# 2. Generate migration files (optional)
pnpm db:generate
-# 3. 执行数据库迁移
+# 3. Run database migrations
pnpm db:migrate
```
-### 启动开发服务器
+### Start development server
```bash
pnpm dev
```
-应用将在 `http://localhost:3000` 启动。
+App will start at http://localhost:3000.
-### 项目结构
+### Project Structure
```
chronoframe/
-├── app/ # Nuxt 应用
-│ ├── components/ # 组件
-│ ├── pages/ # 页面路由
-│ ├── composables/ # 组合式函数
-│ └── stores/ # Pinia 状态管理
+├── app/ # Nuxt app
+│ ├── components/ # Components
+│ ├── pages/ # Page routes
+│ ├── composables/ # Composables
+│ └── stores/ # Pinia stores
├── packages/
-│ └── webgl-image/ # WebGL 图片查看器
+│ └── webgl-image/ # WebGL image viewer
├── server/
-│ ├── api/ # API 路由
-│ ├── database/ # 数据库 schema 和迁移
-│ └── services/ # 业务逻辑服务
-└── shared/ # 共享类型和工具
+│ ├── api/ # API routes
+│ ├── database/ # DB schema & migrations
+│ └── services/ # Business logic services
+└── shared/ # Shared types & utils
```
-### 构建命令
+### Build commands
```bash
-# 开发模式 (包含依赖包构建)
+# Development (with dependencies build)
pnpm dev
-# 仅构建依赖包
+# Build only dependencies
pnpm build:deps
-# 构建生产版本
+# Production build
pnpm build
-# 数据库操作
-pnpm db:generate # 生成迁移文件
-pnpm db:migrate # 执行迁移
+# Database operations
+pnpm db:generate # Generate migration files
+pnpm db:migrate # Run migrations
-# 预览生产版本
+# Preview production build
pnpm preview
```
-## 📖 使用指南
+## 📖 User Guide
-### 上传照片
+### Uploading Photos
-1. 点击头像跳转到 GitHub 认证登录
-2. 访问仪表板页面 `/dashboard`
-3. 在 `Photos` 页面中选择图片并点击上传(支持批量上传和拖拽上传)
-4. 系统将自动提取 EXIF 信息、生成缩略图并逆编码照片地理位置
+1. Click avatar to sign in with GitHub OAuth
+2. Go to the dashboard at /dashboard
+3. On the Photos page, select and upload images (supports batch & drag-and-drop)
+4. System will automatically parse EXIF data, generate thumbnails, and perform reverse geocoding
-## 🤝 贡献
+## 🤝 Contributing
-欢迎贡献代码!请确保:
+Contributions are welcome! Please:
-1. Fork 本仓库
-2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
-3. 提交更改 (`git commit -m 'Add some amazing feature'`)
-4. 推送到分支 (`git push origin feature/amazing-feature`)
-5. 开启 Pull Request
+1. Fork the repo
+2. Create a feature branch (git checkout -b feature/amazing-feature)
+3. Commit changes (git commit -m 'Add some amazing feature')
+4. Push to branch (git push origin feature/amazing-feature)
+5. Open a Pull Request
-### 开发规范
+### Coding Guidelines
-- 使用 TypeScript 进行类型安全的开发
-- 遵循 ESLint 和 Prettier 代码规范
-- 更新相关文档
+- Use TypeScript for type safety
+- Follow ESLint and Prettier conventions
+- Update documentation accordingly
-## 📄 许可证
+## 📄 License
-本项目基于 [MIT 许可证](LICENSE) 开源。
+This project is licensed under the MIT License.
-## 👤 作者
+## 👤 Author
**Timothy Yin**
-- GitHub: [@HoshinoSuzumi](https://github.com/HoshinoSuzumi)
-- Website: [bh8.ga](https://bh8.ga)
-- Gallery: [lens.bh8.ga](https://lens.bh8.ga)
+- GitHub: @HoshinoSuzumi
+- Website: bh8.ga
+- Gallery: lens.bh8.ga
+
+## ❓ FAQ
+
+<details>
+ <summary>How is the admin user created?</summary>
+ <p>
+ On first startup, an admin user is created based on <code>CFRAME_ADMIN_EMAIL</code>, <code>CFRAME_ADMIN_NAME</code>, and <code>CFRAME_ADMIN_PASSWORD</code>. The email must match your GitHub account email used for login.
+ </p>
+</details>
+<details>
+ <summary>Which image formats are supported?</summary>
+ <p>
+ Supported formats: JPEG, PNG, HEIC/HEIF, MOV (for Live Photos).
+ </p>
+</details>
+<details>
+ <summary>Why can’t I use GitHub/Local storage?</summary>
+ <p>
+ Currently only S3-compatible storage is supported. GitHub and local storage support is planned.
+ </p>
+</details>
+<details>
+ <summary>Why is a map service required and how to configure it?</summary>
+ <p>
+ The map is used to browse photo locations and render mini-maps in photo details. Currently Mapbox is used. After registering, <a href="https://console.mapbox.com/account/access-tokens/">get an access token</a> and set it to the <code>MAPBOX_TOKEN</code> variable.
+ </p>
+</details>
+<details>
+ <summary>Why wasn’t my MOV file recognized as a Live Photo?</summary>
+ <p>
+ Ensure the image (.heic) and video (.mov) share the same filename (e.g., <code>IMG_1234.heic</code> and <code>IMG_1234.mov</code>). Upload order does not matter. If not recognized, you can trigger pairing manually from the dashboard.
+ </p>
+</details>
+<details>
+ <summary>How do I import existing photos from storage?</summary>
+ <p>
+ Direct import of existing photos is not yet supported. A directory scanning import feature is planned.
+ </p>
+</details>
+<details>
+ <summary>How is this different from Afilmory?</summary>
+ <p>
+ Afilmory generates a manifest from photos during local/CI processing and serves them statically. ChronoFrame is a dynamic photo management app, offering online upload, management, and browsing—better for frequently updated galleries.
+ </p>
+</details>
+
+
+## 🙏 Acknowledgements
+
+This project was inspired by [Afilmory](https://github.com/Afilmory/afilmory), another excellent personal gallery project.
+
+Thanks to the following open-source projects and libraries:
+
+- [Nuxt](https://nuxt.com/)
+- [TailwindCSS](https://tailwindcss.com/)
+- [Drizzle ORM](https://orm.drizzle.team/)
diff --git a/README_zh.md b/README_zh.md
new file mode 100644
index 00000000..b6d752e0
--- /dev/null
+++ b/README_zh.md
@@ -0,0 +1,341 @@
+# ChronoFrame
+
+<p align="center">
+ <img src="public/favicon.svg" alt="Chronoframe Logo" width="192">
+ <br/>
+ <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License">
+ <img src="https://img.shields.io/badge/Nuxt-4.0+-00DC82.svg" alt="Nuxt">
+ <img src="https://img.shields.io/badge/TypeScript-5.0+-3178C6.svg" alt="TypeScript">
+ <img src="https://img.shields.io/badge/WebGL-2.0-FF6600.svg" alt="WebGL">
+</p>
+
+**Languages:** [English](README.md) | 中文
+
+丝滑的照片展示和管理应用,支持多种图片格式和大尺寸图片渲染。
+
+[在线演示: TimoYin's Mems](https://lens.bh8.ga)
+
+## ✨ 特性
+
+### 🖼️ 强大的图片管理
+
+- **在线管理照片** - 通过 Web 界面轻松管理和浏览照片
+- **探索地图** - 在地图上浏览照片拍摄位置
+- **智能 EXIF 解析** - 自动提取拍摄时间、地理位置、相机参数等元数据
+- **地理位置识别** - 自动识别(Reverse Geocoding)照片拍摄地点
+- **多格式支持** - 支持 JPEG、PNG、HEIC/HEIF 等主流图片格式
+- **智能缩略图** - 基于 ThumbHash 技术的高效缩略图生成
+
+### 🔧 现代技术栈
+
+- **Nuxt 4** - 基于最新的 Nuxt 框架,提供 SSR/SSG 支持
+- **TypeScript** - 完整的类型安全保障
+- **TailwindCSS** - 现代化的 CSS 框架
+- **Drizzle ORM** - 类型安全的数据库 ORM
+
+### ☁️ 灵活的存储方案
+
+- **多存储后端** - 支持 S3 兼容存储、GitHub(WIP)、本地文件系统(WIP) 等
+- **CDN 加速** - 可配置 CDN 地址加速图片访问
+
+## 🐳 部署
+
+推荐使用预构建的 docker 镜像部署,[在 ghcr 上查看镜像](https://github.com/HoshinoSuzumi/chronoframe/pkgs/container/chronoframe)
+
+### Docker
+
+修改命令中的环境变量后运行:
+
+```bash
+docker run -d \
+ --name chronoframe \
+ -p 3000:3000 \
+ -v $(pwd)/data:/app/data \
+ -e CFRAME_ADMIN_EMAIL="" \
+ -e CFRAME_ADMIN_NAME="" \
+ -e CFRAME_ADMIN_PASSWORD="" \
+ -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
+# Admin user email (required)
+CFRAME_ADMIN_EMAIL=
+# Admin user name (default to Chronoframe, optional)
+CFRAME_ADMIN_NAME=
+# Admin user password (default to CF1234@!, optional)
+CFRAME_ADMIN_PASSWORD=
+
+# 应用标题与口号
+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=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=
+
+# 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
+```
+
+### 环境变量列表
+
+| 环境变量 | 说明 | 默认值 | 必需 |
+| :--------------------------------- | :--------------------------------------- | :---------- | :---------------------------------------- |
+| CFRAME_ADMIN_EMAIL | 初始管理员用户的邮箱 | 无 | 是,填写登录使用的 GitHub 账户的邮箱 |
+| CFRAME_ADMIN_NAME | 初始管理员用户的用户名 | Chronoframe | 否 |
+| CFRAME_ADMIN_PASSWORD | 初始管理员用户的密码 | CF1234@! | 否 |
+| 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
+# 2. 生成数据库迁移文件(可选)
+pnpm db:generate
+
+# 3. 执行数据库迁移
+pnpm db:migrate
+```
+
+### 启动开发服务器
+
+```bash
+pnpm dev
+```
+
+应用将在 `http://localhost:3000` 启动。
+
+### 项目结构
+
+```
+chronoframe/
+├── app/ # Nuxt 应用
+│ ├── components/ # 组件
+│ ├── pages/ # 页面路由
+│ ├── composables/ # 组合式函数
+│ └── stores/ # Pinia 状态管理
+├── packages/
+│ └── webgl-image/ # WebGL 图片查看器
+├── server/
+│ ├── api/ # API 路由
+│ ├── database/ # 数据库 schema 和迁移
+│ └── services/ # 业务逻辑服务
+└── shared/ # 共享类型和工具
+```
+
+### 构建命令
+
+```bash
+# 开发模式 (包含依赖包构建)
+pnpm dev
+
+# 仅构建依赖包
+pnpm build:deps
+
+# 构建生产版本
+pnpm build
+
+# 数据库操作
+pnpm db:generate # 生成迁移文件
+pnpm db:migrate # 执行迁移
+
+# 预览生产版本
+pnpm preview
+```
+
+## 📖 使用指南
+
+### 上传照片
+
+1. 点击头像跳转到 GitHub 认证登录
+2. 访问仪表板页面 `/dashboard`
+3. 在 `Photos` 页面中选择图片并点击上传(支持批量上传和拖拽上传)
+4. 系统将自动提取 EXIF 信息、生成缩略图并逆编码照片地理位置
+
+## 🤝 贡献
+
+欢迎贡献代码!请确保:
+
+1. Fork 本仓库
+2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
+3. 提交更改 (`git commit -m 'Add some amazing feature'`)
+4. 推送到分支 (`git push origin feature/amazing-feature`)
+5. 开启 Pull Request
+
+### 开发规范
+
+- 使用 TypeScript 进行类型安全的开发
+- 遵循 ESLint 和 Prettier 代码规范
+- 更新相关文档
+
+## 📄 许可证
+
+本项目基于 [MIT 许可证](LICENSE) 开源。
+
+## 👤 作者
+
+**Timothy Yin**
+
+- GitHub: [@HoshinoSuzumi](https://github.com/HoshinoSuzumi)
+- Website: [bh8.ga](https://bh8.ga)
+- Gallery: [lens.bh8.ga](https://lens.bh8.ga)
+
+## ❓ FAQ
+
+<details>
+ <summary>如何创建管理员用户?</summary>
+ <p>
+ 首次启动时,会根据环境变量 <code>CFRAME_ADMIN_EMAIL</code>、<code>CFRAME_ADMIN_NAME</code> 和 <code>CFRAME_ADMIN_PASSWORD</code> 环境变量创建一个管理员用户。<code>CFRAME_ADMIN_EMAIL</code> 必须是登录使用的 GitHub 账户的邮箱。
+ </p>
+</details>
+<details>
+ <summary>支持哪些图片格式?</summary>
+ <p>
+ 支持 JPEG、PNG、HEIC/HEIF、MOV(作为实况照片) 格式。
+ </p>
+</details>
+<details>
+ <summary>为什么无法使用 GitHub/Local 存储?</summary>
+ <p>
+ 目前支持 S3 兼容存储,未来计划支持 GitHub 和本地文件系统存储。
+ </p>
+</details>
+<details>
+ <summary>为什么需要/如何配置地图服务?</summary>
+ <p>
+ 地图服务用于在地图上浏览照片拍摄位置,以及照片详情中的小地图渲染。目前使用 Mapbox,注册后<a href="https://console.mapbox.com/account/access-tokens/">获取访问令牌</a>并配置到 <code>MAPBOX_TOKEN</code> 环境变量中。
+ </p>
+</details>
+<details>
+ <summary>为什么我上传的 MOV 文件没有被识别为实况照片?</summary>
+ <p>
+ 需要确保实况照片对的图片(.heic)和视频(.mov)的文件名一致(例如 <code>IMG_1234.heic</code> 与 <code>IMG_1234.mov</code> 会自动匹配)。
+ 一般情况来说,不管是上传 .heic 还是 .mov,都会检测一次配对,因此上传的顺序无关紧要。
+ 如果仍然没有被识别为实况照片,请在仪表盘中找到图片,在操作菜单中手动触发配对检测。
+ </p>
+</details>
+<details>
+ <summary>如何导入存储中已有的照片?</summary>
+ <p>
+ 目前不支持直接导入已有照片,未来计划支持通过指定目录扫描导入。
+ </p>
+</details>
+<details>
+ <summary>本项目与 Afilmory 有何区别?</summary>
+ <p>
+ Afilmory 是一个非常优秀的项目,其部署方式是在本地或 CI 中处理存储中的照片并生成清单文件,然后前端通过读取清单文件来展示照片,属于静态部署。
+ ChronoFrame 则是一个动态的照片管理应用,提供在线上传、管理和浏览照片的功能,适合需要频繁更新照片的场景。
+ </p>
+</details>
+
+## 🙏 致谢
+
+本项目受启发于 [Afilmory](https://github.com/Afilmory/afilmory),同样优秀的个人相册项目。
+
+感谢以下优秀的开源项目和库:
+
+- [Nuxt](https://nuxt.com/)
+- [TailwindCSS](https://tailwindcss.com/)
+- [Drizzle ORM](https://orm.drizzle.team/)