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 and README_zh.md
Timothy Yin111ee69997ce
diff --git a/README.md b/README.mdindex 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:```bashdocker 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:```yamlservices:@@ -124,158 +126,212 @@ services:- .env```-启动:+Start:```bashdocker-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-## 🛠️ 开发+## 🛠️ Development-### 环境要求+### Requirements- Node.js 18+- pnpm 9.0+-### 安装依赖+### Install dependencies```bash-# 使用 pnpm (推荐)+# With pnpm (recommended)pnpm install-# 或使用其他包管理器+# Or with other package managersnpm installyarn install```-### 配置环境变量--复制环境变量模板并根据需要配置:+### Configure environment variables```bashcp .env.example .env```-### 数据库初始化+### Initialize database```bash-# 2. 生成数据库迁移文件(可选)+# 2. Generate migration files (optional)pnpm db:generate-# 3. 执行数据库迁移+# 3. Run database migrationspnpm db:migrate```-### 启动开发服务器+### Start development server```bashpnpm 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 dependenciespnpm build:deps-# 构建生产版本+# Production buildpnpm build-# 数据库操作-pnpm db:generate # 生成迁移文件-pnpm db:migrate # 执行迁移+# Database operations+pnpm db:generate # Generate migration files+pnpm db:migrate # Run migrations-# 预览生产版本+# Preview production buildpnpm 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**- Email: [email protected]-- 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.mdnew file mode 100644index 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 访问令牌,用于地图服务 | 无 | 是 |++## 📸 截图+++++++## 🛠️ 开发++### 环境要求++- 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**++- Email: [email protected]+- 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/)