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
Merge main into docs/v1.0.0
Timothy Yin79066eb3ed9c
diff --cc README.mdindex 653417b6,9a3e2531..0046ec29--- a/README.md+++ b/README.md@@@ -95,11 -173,41 +96,11 @@@ Album passwords control access through## 🛠️ Development- Use Node.js 22 and the project's pinned pnpm 10.34.1:-### Requirements--- Node.js 18+-- pnpm 9.0+--### Install dependencies--```bash-# 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. Generate migration files (optional)-pnpm db:generate--# 3. Run database migrations-pnpm db:migrate-```--### Start development server++Use Node.js 22 and the project's pinned pnpm 10.34.6:```bash+corepack enable+pnpm install --frozen-lockfilepnpm dev```diff --cc README_zh.mdindex b5aa263f,92c67c62..ce4306f2--- a/README_zh.md+++ b/README_zh.md@@@ -95,11 -173,43 +96,11 @@@ Apple Live Photo 的图片和 MOV 文�## 🛠️ 开发- 使用 Node.js 22 和项目指定的 pnpm 10.34.1:-### 环境要求--- 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-```--### 启动开发服务器++使用 Node.js 22 和项目指定的 pnpm 10.34.6:```bash+corepack enable+pnpm install --frozen-lockfilepnpm dev```diff --cc docs/development/contributing.mdindex 5415e739,4514137b..0ae89101--- a/docs/development/contributing.md+++ b/docs/development/contributing.md@@@ -1,46 -1,352 +1,46 @@@-# Contributing Guide+# Contributing- Use Node.js 22, matching the Docker build, and the project's pinned pnpm 10.34.1. This repository contains workspace packages; install dependencies with pnpm.-This document will guide you through setting up the ChronoFrame development environment, including environment requirements, dependency installation, configuration settings, and development tools.++Use Node.js 22, matching the Docker build, and the project's pinned pnpm 10.34.6. This repository contains workspace packages; install dependencies with pnpm.-## Environment Requirements--### Required Software--- **Node.js**: 20.0+-- **pnpm**: 9.0+ (preferred package manager)-- **Git**: Latest version-- **Docker**: Optional, for containerized development--## Clone and Install--### 1. Clone Repository+## Run locally```bash-# Using HTTPSgit clone https://github.com/HoshinoSuzumi/chronoframe.git--# Or using SSH-git clone [email protected]:HoshinoSuzumi/chronoframe.git--# Enter project directorycd chronoframe--# Set upstream remote repository-git remote add upstream https://github.com/HoshinoSuzumi/chronoframe.git-```--### 2. Install Dependencies--```bash-# Install pnpm (if not already installed)-npm install -g pnpm--# Install project dependencies-pnpm install-```--### 3. Configure Environment Variables--```bash-# Copy environment variable template-cp .env.example .env--# Edit environment variables-nano .env # Or use your preferred editor-```--#### Minimal Development Configuration--```bash-# === Admin Account ===-CFRAME_ADMIN_NAME=Developer-CFRAME_ADMIN_PASSWORD=dev123456--# === Authentication Settings ===-NUXT_OAUTH_GITHUB_CLIENT_ID=your-dev-github-client-id-NUXT_OAUTH_GITHUB_CLIENT_SECRET=your-dev-github-client-secret-NUXT_SESSION_PASSWORD=your-32-character-development-key--# === Storage Settings (can use MinIO for development) ===-NUXT_STORAGE_PROVIDER=s3-NUXT_PROVIDER_S3_ENDPOINT=http://localhost:9000-NUXT_PROVIDER_S3_BUCKET=chronoframe-dev-NUXT_PROVIDER_S3_REGION=us-east-1-NUXT_PROVIDER_S3_ACCESS_KEY_ID=minioadmin-NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=minioadmin--# === Map Services (optional) ===-NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=pk.your-development-token-NUXT_MAPBOX_ACCESS_TOKEN=sk.your-development-token--# === Enable Debug Info ===-VITE_SHOW_DEBUG_INFO=true-```--## Project Architecture--### Directory Structure--```-chronoframe/-├── app/ # Nuxt 4 application directory-│ ├── components/ # Vue components-│ │ ├── ui/ # Common UI components-│ │ ├── photo/ # Photo-related components-│ │ ├── masonry/ # Masonry layout components-│ │ └── ...-│ ├── pages/ # Route pages-│ ├── composables/ # Vue composables-│ ├── stores/ # Pinia state management-│ ├── layouts/ # Layout templates-│ ├── plugins/ # Nuxt plugins-│ └── utils/ # Utility functions-├── packages/-│ └── webgl-image/ # WebGL image viewer package-│ ├── src/-│ │ ├── core/ # Core engine-│ │ ├── components/ # Vue components-│ │ └── types/ # Type definitions-│ └── package.json-├── server/ # Nitro server-side-│ ├── api/ # API routes-│ │ ├── photos/ # Photo management API-│ │ ├── auth/ # Authentication API-│ │ └── system/ # System API-│ ├── database/ # Database related-│ │ ├── schema.ts # Database schema-│ │ └── migrations/ # Migration files-│ ├── services/ # Business logic services-│ │ ├── storage/ # Storage services-│ │ ├── image/ # Image processing-│ │ ├── location/ # Geolocation-│ │ └── pipeline-queue/ # Processing queue-│ ├── tasks/ # Background tasks-│ └── utils/ # Server-side utilities-├── shared/ # Shared code between frontend and backend-│ ├── types/ # TypeScript type definitions-│ └── utils/ # Shared utilities-├── docs/ # Project documentation-├── scripts/ # Build and deployment scripts-└── Configuration files...-```--### Technology Stack--#### Frontend Technologies--- **Nuxt 4**: Vue.js full-stack framework-- **TypeScript**: Type-safe JavaScript-- **TailwindCSS**: Utility-first CSS framework--#### Backend Technologies--- **Nitro**: Server-side framework-- **SQLite**: Lightweight database-- **Drizzle ORM**: Type-safe ORM-- **Sharp**: High-performance image processing-- **ExifTool**: EXIF data extraction--## Development Workflow--### Start Development Server--```bash-# Start complete development server+corepack enable+pnpm install --frozen-lockfilepnpm dev--# Or start step by step-pnpm build:deps # Build WebGL package-pnpm dlx nuxi@latest dev # Start Nuxt development server only```-### Database Operations+Open `http://localhost:3000` and use the wizard to create an administrator and choose local storage. `./data/storage` works for development. Database migrations run at startup; you do not need to generate migrations or fill out a minimal environment configuration just to run the app.-```bash-# Generate migration files-pnpm db:generate--# Execute database migrations-pnpm db:migrate-```--### Build Project+## Commands```bash-# Build WebGL dependency package+pnpm lint+pnpm fmt:checkpnpm build:deps--# Build complete projectpnpm build--# Preview production buildpnpm preview+pnpm docs:dev+pnpm docs:build```-## Testing Environment--### Local MinIO Storage--Run local MinIO service using Docker:--```bash-# Start MinIO-docker run -d \- --name minio \- -p 9000:9000 \- -p 9001:9001 \- -e "MINIO_ROOT_USER=minioadmin" \- -e "MINIO_ROOT_PASSWORD=minioadmin" \- minio/minio server /data --console-address ":9001"-```--Access MinIO console: http://localhost:9001--### GitHub OAuth App--1. Visit GitHub Settings > Developer settings > OAuth Apps-2. Create new OAuth app-3. Set callback URL: `http://localhost:3000/api/auth/github`-4. Copy Client ID and Client Secret to `.env` file--### Mapbox Development Tokens--1. Register [Mapbox account](https://account.mapbox.com/)-2. Create development access tokens-3. Set URL restriction: `http://localhost:3000`-4. Add tokens to `.env` file--## Code Standards--### TypeScript Standards--```typescript-// ✅ Good practice-interface PhotoMetadata {- id: string- title?: string- width: number- height: number- createdAt: Date-}--// ❌ Avoid using any-const processPhoto = (photo: any) => { ... }--// ✅ Use specific types-const processPhoto = (photo: PhotoMetadata) => { ... }-```--### Vue Component Standards--```vue-<!-- ✅ Recommended component structure -->-<script setup lang="ts">-// Imports-import { ref, computed } from 'vue'-import type { Photo } from '~/types'--// Props and Emits-interface Props {- photos: Photo[]- loading?: boolean-}--interface Emits {- select: [photo: Photo]- delete: [photoId: string]-}--const props = withDefaults(defineProps<Props>(), {- loading: false,-})--const emit = defineEmits<Emits>()--// Reactive data-const selectedPhoto = ref<Photo | null>(null)--// Computed properties-const photoCount = computed(() => props.photos.length)--// Methods-const handlePhotoClick = (photo: Photo) => {- selectedPhoto.value = photo- emit('select', photo)-}-</script>--<template>- <div class="photo-grid">- <!-- Template content -->- </div>-</template>--<style scoped>-/* Component styles */-</style>-```--### Database Calls--When using database operations in `server`, use `useDB()` to get the Drizzle instance. This composable is globally auto-imported on the server side:--```typescript-const db = useDB()--const photos = await db.select().from(photosTable)-```--### Commit Message Standards--Use [Conventional Commits](https://www.conventionalcommits.org/) standard:--```-feat: add photo batch delete functionality-fix: fix WebGL viewer compatibility issue in Safari-docs: update deployment documentation-style: unify code formatting-refactor: refactor storage service interface-test: add unit tests for photo upload-chore: update dependency versions-```--## Contribution Guidelines--### Development Process--1. **Fork Project**: Fork the project on GitHub-2. **Create Branch**: `git checkout -b feature/new-feature`-3. **Develop Feature**: Write code and tests-4. **Commit Changes**: Use standard commit messages-5. **Push Branch**: `git push origin feature/new-feature`-6. **Create PR**: Create Pull Request on GitHub--### Pull Request Checklist--Before submitting PR, ensure:--- Code passes all tests-- Follows code standards-- Updates relevant documentation-- Adds appropriate test cases-- PR description is clear with change explanations--## Contribution Opportunities--### Beginner-friendly Tasks--Look for Issues labeled with:+`pnpm dev` runs the WebGL package development build alongside Nuxt. Once the dependency package is built, use `pnpm dev:only` to start Nuxt alone. Code checks use Oxlint; formatting uses Oxfmt.-- `good first issue`: Tasks suitable for beginners-- `help wanted`: Tasks needing community help-- `documentation`: Documentation-related improvements+After changing the database schema, run `pnpm db:generate` and review the generated SQL. `pnpm db:migrate` applies migrations manually. Keep local databases, photos and credentials out of Git.-## Useful Resources+## Where code lives-### Official Documentation+- `app/`: pages, components, composables and Pinia stores.+- `packages/webgl-image/`: the WebGL image viewer.+- `server/api/`: API routes; `server/services/`: storage, settings and photo processing.+- `server/database/`: Drizzle schema and migrations.+- `shared/`: shared types; `i18n/`: translations.+- `docs/`: English and Chinese documentation.-- [Nuxt 4 Documentation](https://nuxt.com/)-- [Vue 3 Documentation](https://vuejs.org/)-- [Drizzle ORM Documentation](https://orm.drizzle.team/)-- [TailwindCSS Documentation](https://tailwindcss.com/)+For new dashboard settings, read [Adding a setting](/development/how-to-add-setting). Enter test credentials for S3, OpenList, maps or GitHub login in the dashboard. Use `http://localhost:3000/api/auth/github` as the local OAuth callback.-### Community Resources+## Submit a change-- [GitHub Issues](https://github.com/HoshinoSuzumi/chronoframe/issues)-- [GitHub Discussions](https://github.com/HoshinoSuzumi/chronoframe/discussions)+Keep changes focused and use Conventional Commits. Explain the problem, resulting behavior and verification in your PR. Include screenshots for UI changes and update both language versions for documentation changes. Issues marked `good first issue` or `help wanted` are useful starting points.diff --cc docs/legacy/guide/configuration.mdindex 6d2f4567,00000000..cf212685mode 100644,000000..100644--- a/docs/legacy/guide/configuration.md+++ b/docs/legacy/guide/configuration.md@@@ -1,87 -1,0 +1,87 @@@+---+search: false+---++::: warning Archived documentation+These instructions describe older deployments and environment-based settings. For current installations, use [Getting Started](/guide/getting-started) and manage settings in the dashboard.+:::++# Configuration Reference++Whether using Docker or Docker Compose (.env) deployment, configuration is done through environment variables.++## Environment Variables List++| Environment Variable | Description | Default | Required |+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- | ---------------------------------------------------- |+| CFRAME_ADMIN_EMAIL | Initial admin user email | `[email protected]` | Yes |+| CFRAME_ADMIN_NAME | Initial admin username | `Chronoframe` | No |+| CFRAME_ADMIN_PASSWORD | Initial admin user password | `CF1234@!` | No |+| NUXT_PUBLIC_APP_TITLE | Application title | `ChronoFrame` | No |+| NUXT_PUBLIC_APP_SLOGAN | Application slogan | None | No |+| NUXT_PUBLIC_APP_AUTHOR | Application author | None | No |- | NUXT_PUBLIC_APP_AVATAR_URL | Application avatar URL | None | No |++| NUXT_PUBLIC_APP_AVATAR_URL | External application avatar URL (an avatar can also be uploaded from the dashboard, stored in the configured storage provider) | None | No |+| NUXT_PUBLIC_COLOR_MODE_PREFERENCE | Color mode preference, options: `light`, `dark`, `system` | `system` | No |+| NUXT_PUBLIC_MAP_PROVIDER | Map provider, options: `mapbox`, `maplibre` | `maplibre` | No |+| NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN | Mapbox access token (URL restricted), for map services | None | Required when `NUXT_PUBLIC_MAP_PROVIDER` is `mapbox` |+| NUXT_NOMINATIM_BASE_URL | Nominatim base URL for reverse geocoding service | `https://nominatim.openstreetmap.org` | No |+| NUXT_MAPBOX_ACCESS_TOKEN | Mapbox access token (no URL restriction), for location services | None | No |+| NUXT_STORAGE_PROVIDER | Storage provider, supports `local`, `s3`, `openlist` | `local` | Yes |+| NUXT_PROVIDER_LOCAL_PATH | Local storage path | `/app/data/storage` | No |+| NUXT_PROVIDER_LOCAL_BASE_URL | Local storage access URL | `/storage` | No |+| NUXT_PROVIDER_S3_ENDPOINT | S3 compatible storage service endpoint | None | Required when `NUXT_STORAGE_PROVIDER` is `s3` |+| NUXT_PROVIDER_S3_BUCKET | S3 bucket name | `chronoframe` | Required when `NUXT_STORAGE_PROVIDER` is `s3` |+| NUXT_PROVIDER_S3_REGION | S3 bucket region | `auto` | Required when `NUXT_STORAGE_PROVIDER` is `s3` |+| NUXT_PROVIDER_S3_ACCESS_KEY_ID | S3 access key ID | None | Required when `NUXT_STORAGE_PROVIDER` is `s3` |+| NUXT_PROVIDER_S3_SECRET_ACCESS_KEY | S3 secret access key | None | Required when `NUXT_STORAGE_PROVIDER` is `s3` |+| NUXT_PROVIDER_S3_PREFIX | S3 storage prefix | `photos/` | No |+| NUXT_PROVIDER_S3_CDN_URL | S3 storage CDN URL | None | No |+| NUXT_PROVIDER_OPENLIST_BASE_URL | OpenList server URL | None | Required when `NUXT_STORAGE_PROVIDER` is `openlist` |+| NUXT_PROVIDER_OPENLIST_ROOT_PATH | OpenList root path | None | Required when `NUXT_STORAGE_PROVIDER` is `openlist` |+| NUXT_PROVIDER_OPENLIST_TOKEN | OpenList API token | None | Recommended (for OpenList authentication) |+| NUXT_PROVIDER_OPENLIST_ENDPOINT_UPLOAD | OpenList upload endpoint | `/api/fs/put` | No |+| NUXT_PROVIDER_OPENLIST_ENDPOINT_DOWNLOAD | OpenList download endpoint | None | No |+| NUXT_PROVIDER_OPENLIST_ENDPOINT_LIST | OpenList list endpoint | None | No |+| NUXT_PROVIDER_OPENLIST_ENDPOINT_DELETE | OpenList delete endpoint | `/api/fs/remove` | No |+| NUXT_PROVIDER_OPENLIST_ENDPOINT_META | OpenList metadata endpoint | `/api/fs/get` | No |+| NUXT_PROVIDER_OPENLIST_PATH_FIELD | OpenList path field name | `path` | No |+| NUXT_PROVIDER_OPENLIST_CDN_URL | OpenList CDN URL | None | No |+| NUXT_PUBLIC_OAUTH_GITHUB_ENABLED | Enable GitHub OAuth login | `false` | No |+| NUXT_OAUTH_GITHUB_CLIENT_ID | GitHub OAuth app Client ID | None | No (optional, for GitHub login) |+| NUXT_OAUTH_GITHUB_CLIENT_SECRET | GitHub OAuth app Client Secret | None | No (optional, for GitHub login) |+| NUXT_SESSION_PASSWORD | Password for encrypting sessions, 32-character random string | None | Yes |+| NUXT_TRUST_PROXY | Trust `X-Forwarded-For` for album unlock rate limits; enable only behind a trusted proxy that replaces client-supplied headers | `false` | No |+| NUXT_PUBLIC_GTAG_ID | Google Analytics Tracking ID | None | No |+| NUXT_PUBLIC_ANALYTICS_MATOMO_ENABLED | Enable Matomo analytics tracking | `false` | No |+| NUXT_PUBLIC_ANALYTICS_MATOMO_URL | Matomo instance URL (e.g., https://matomo.example.com) | None | No (required when Matomo is enabled) |+| NUXT_PUBLIC_ANALYTICS_MATOMO_SITE_ID | Matomo site ID | None | No (required when Matomo is enabled) |+| NUXT_UPLOAD_MIME_WHITELIST_ENABLED | Enable MIME type whitelist validation for uploads | `true` | No |+| NUXT_UPLOAD_MIME_WHITELIST | Allowed MIME types for uploads (comma-separated) | See below | No |+| ALLOW_INSECURE_COOKIE | Allow insecure cookies (only for development environment) | `false` | No |++## Upload File Type Whitelist++The default value of `NUXT_UPLOAD_MIME_WHITELIST` includes the following MIME types:++- `image/jpeg` - JPEG images+- `image/png` - PNG images+- `image/webp` - WebP images+- `image/gif` - GIF images+- `image/bmp` - BMP images+- `image/tiff` - TIFF images+- `image/heic` - HEIC images (Apple)+- `image/heif` - HEIF images+- `video/quicktime` - QuickTime videos (MOV)+- `video/mp4` - MP4 videos++To customize the whitelist, use a comma-separated string of MIME types, for example:++```+NUXT_UPLOAD_MIME_WHITELIST=image/jpeg,image/png,video/mp4+```++To disable whitelist validation (allow any file type), set:++```+NUXT_UPLOAD_MIME_WHITELIST_ENABLED=false+```diff --cc docs/zh/development/contributing.mdindex d6657859,4b5e7661..cf4ec1cc--- a/docs/zh/development/contributing.md+++ b/docs/zh/development/contributing.md@@@ -1,46 -1,352 +1,46 @@@# 开始贡献- 使用 Node.js 22(与 Docker 构建环境一致)和项目指定的 pnpm 10.34.1。仓库包含 workspace 包,请使用 pnpm 安装依赖。-本文档将指导您搭建 ChronoFrame 的开发环境,包括环境要求、依赖安装、配置设置和开发工具。++使用 Node.js 22(与 Docker 构建环境一致)和项目指定的 pnpm 10.34.6。仓库包含 workspace 包,请使用 pnpm 安装依赖。-## 环境要求--### 必需软件--- **Node.js**: 20.0+-- **pnpm**: 9.0+ (首选包管理器)-- **Git**: 最新版本-- **Docker**: 可选,用于容器化开发--## 克隆与安装--### 1. 克隆代码库+## 本地运行```bash-# 使用 HTTPSgit clone https://github.com/HoshinoSuzumi/chronoframe.git--# 或使用 SSH-git clone [email protected]:HoshinoSuzumi/chronoframe.git--# 进入项目目录cd chronoframe--# 设置上游远程仓库-git remote add upstream https://github.com/HoshinoSuzumi/chronoframe.git-```--### 2. 安装依赖--```bash-# 安装 pnpm(如果尚未安装)-npm install -g pnpm--# 安装项目依赖-pnpm install-```--### 3. 配置环境变量--```bash-# 复制环境变量模板-cp .env.example .env--# 编辑环境变量-nano .env # 或使用您喜欢的编辑器-```--#### 最小开发配置--```bash-# === 管理员账户 ===-CFRAME_ADMIN_NAME=Developer-CFRAME_ADMIN_PASSWORD=dev123456--# === 认证设置 ===-NUXT_OAUTH_GITHUB_CLIENT_ID=your-dev-github-client-id-NUXT_OAUTH_GITHUB_CLIENT_SECRET=your-dev-github-client-secret-NUXT_SESSION_PASSWORD=your-32-character-development-key--# === 存储设置(开发环境可使用 MinIO) ===-NUXT_STORAGE_PROVIDER=s3-NUXT_PROVIDER_S3_ENDPOINT=http://localhost:9000-NUXT_PROVIDER_S3_BUCKET=chronoframe-dev-NUXT_PROVIDER_S3_REGION=us-east-1-NUXT_PROVIDER_S3_ACCESS_KEY_ID=minioadmin-NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=minioadmin--# === 地图服务(可选) ===-NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=pk.your-development-token-NUXT_MAPBOX_ACCESS_TOKEN=sk.your-development-token--# === 开启调试信息 ===-VITE_SHOW_DEBUG_INFO=true-```--## 项目架构--### 目录结构--```-chronoframe/-├── app/ # Nuxt 4 应用目录-│ ├── components/ # Vue 组件-│ │ ├── ui/ # 通用 UI 组件-│ │ ├── photo/ # 照片相关组件-│ │ ├── masonry/ # 瀑布流布局组件-│ │ └── ...-│ ├── pages/ # 路由页面-│ ├── composables/ # Vue 组合式函数-│ ├── stores/ # Pinia 状态管理-│ ├── layouts/ # 布局模板-│ ├── plugins/ # Nuxt 插件-│ └── utils/ # 工具函数-├── packages/-│ └── webgl-image/ # WebGL 图片查看器包-│ ├── src/-│ │ ├── core/ # 核心引擎-│ │ ├── components/ # Vue 组件-│ │ └── types/ # 类型定义-│ └── package.json-├── server/ # Nitro 服务端-│ ├── api/ # API 路由-│ │ ├── photos/ # 照片管理 API-│ │ ├── auth/ # 认证 API-│ │ └── system/ # 系统 API-│ ├── database/ # 数据库相关-│ │ ├── schema.ts # 数据库模式-│ │ └── migrations/ # 迁移文件-│ ├── services/ # 业务逻辑服务-│ │ ├── storage/ # 存储服务-│ │ ├── image/ # 图片处理-│ │ ├── location/ # 地理位置-│ │ └── pipeline-queue/ # 处理队列-│ ├── tasks/ # 后台任务-│ └── utils/ # 服务端工具-├── shared/ # 前后端共享代码-│ ├── types/ # TypeScript 类型定义-│ └── utils/ # 共享工具函数-├── docs/ # 项目文档-├── scripts/ # 构建和部署脚本-└── 配置文件...-```--### 技术栈--#### 前端技术--- **Nuxt 4**: Vue.js 全栈框架-- **TypeScript**: 类型安全的 JavaScript-- **TailwindCSS**: 实用优先的 CSS 框架--#### 后端技术--- **Nitro**: 服务端框架-- **SQLite**: 轻量级数据库-- **Drizzle ORM**: 类型安全的 ORM-- **Sharp**: 高性能图片处理-- **ExifTool**: EXIF 数据提取--## 开发流程--### 启动开发服务器--```bash-# 启动完整开发服务器+corepack enable+pnpm install --frozen-lockfilepnpm dev--# 或分步启动-pnpm build:deps # 构建 WebGL 包-pnpm dlx nuxi@latest dev # 只启动 Nuxt 开发服务器```-### 数据库操作+打开 `http://localhost:3000`,按设置向导创建管理员并选择本地存储。开发时可以使用 `./data/storage`。数据库在启动时自动迁移,无需为启动项目生成新的迁移文件,也无需填写最小环境变量配置。-```bash-# 生成迁移文件-pnpm db:generate--# 执行数据库迁移-pnpm db:migrate-```--### 构建项目+## 常用命令```bash-# 构建 WebGL 依赖包+pnpm lint+pnpm fmt:checkpnpm build:deps--# 构建完整项目pnpm build--# 预览生产构建pnpm preview+pnpm docs:dev+pnpm docs:build```-## 测试环境--### 本地 MinIO 存储--使用 Docker 运行本地 MinIO 服务:--```bash-# 启动 MinIO-docker run -d \- --name minio \- -p 9000:9000 \- -p 9001:9001 \- -e "MINIO_ROOT_USER=minioadmin" \- -e "MINIO_ROOT_PASSWORD=minioadmin" \- minio/minio server /data --console-address ":9001"-```--访问 MinIO 控制台:http://localhost:9001--### GitHub OAuth 应用--1. 访问 GitHub Settings > Developer settings > OAuth Apps-2. 创建新的 OAuth 应用-3. 设置回调 URL:`http://localhost:3000/api/auth/github`-4. 复制 Client ID 和 Client Secret 到 `.env` 文件--### Mapbox 开发令牌--1. 注册 [Mapbox 账户](https://account.mapbox.com/)-2. 创建开发用的访问令牌-3. 设置 URL 限制:`http://localhost:3000`-4. 将令牌添加到 `.env` 文件--## 代码规范--### TypeScript 规范--```typescript-// ✅ 好的做法-interface PhotoMetadata {- id: string- title?: string- width: number- height: number- createdAt: Date-}--// ❌ 避免使用 any-const processPhoto = (photo: any) => { ... }--// ✅ 使用具体类型-const processPhoto = (photo: PhotoMetadata) => { ... }-```--### Vue 组件规范--```vue-<!-- ✅ 推荐的组件结构 -->-<script setup lang="ts">-// 导入-import { ref, computed } from 'vue'-import type { Photo } from '~/types'--// Props 和 Emits-interface Props {- photos: Photo[]- loading?: boolean-}--interface Emits {- select: [photo: Photo]- delete: [photoId: string]-}--const props = withDefaults(defineProps<Props>(), {- loading: false,-})--const emit = defineEmits<Emits>()--// 响应式数据-const selectedPhoto = ref<Photo | null>(null)--// 计算属性-const photoCount = computed(() => props.photos.length)--// 方法-const handlePhotoClick = (photo: Photo) => {- selectedPhoto.value = photo- emit('select', photo)-}-</script>--<template>- <div class="photo-grid">- <!-- 模板内容 -->- </div>-</template>--<style scoped>-/* 组件样式 */-</style>-```--### 数据库调用--在 `server` 中使用数据库操作时,使用 `useDB()` 获取数据库的 Drizzle 实例。该 composable 在服务端是全局自动导入的:--```typescript-const db = useDB()--const photos = await db.select().from(photosTable)-```--### 提交信息规范--使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范:--```-feat: 添加照片批量删除功能-fix: 修复 WebGL 查看器在 Safari 中的兼容性问题-docs: 更新部署文档-style: 统一代码格式-refactor: 重构存储服务接口-test: 添加照片上传的单元测试-chore: 更新依赖包版本-```--## 贡献指南--### 开发流程--1. **Fork 项目**: 在 GitHub 上 fork 项目-2. **创建分支**: `git checkout -b feature/new-feature`-3. **开发功能**: 编写代码和测试-4. **提交更改**: 使用规范的提交信息-5. **推送分支**: `git push origin feature/new-feature`-6. **创建 PR**: 在 GitHub 上创建 Pull Request--### Pull Request 检查清单--提交 PR 前请确保:--- 代码通过所有测试-- 遵循代码规范-- 更新相关文档-- 添加适当的测试用例-- PR 描述清晰,包含变更说明--## 贡献机会--### 适合新手的任务--寻找标有以下标签的 Issues:+`pnpm dev` 同时启动 WebGL 包的开发构建和 Nuxt。已有依赖构建时,可使用 `pnpm dev:only` 单独启动 Nuxt。代码检查使用 Oxlint,格式化使用 Oxfmt。-- `good first issue`: 适合新手的任务-- `help wanted`: 需要社区帮助的任务-- `documentation`: 文档相关的改进+修改数据库 schema 后使用 `pnpm db:generate` 生成迁移,并检查生成的 SQL;`pnpm db:migrate` 可手动应用迁移。提交前不要把本地数据库、照片或访问密钥放进 Git。-## 有用资源+## 代码位置-### 官方文档+- `app/`:页面、组件、composables 和 Pinia stores。+- `packages/webgl-image/`:WebGL 图片查看器。+- `server/api/`:API;`server/services/`:存储、设置和照片处理服务。+- `server/database/`:Drizzle schema 和迁移。+- `shared/`:前后端共享类型;`i18n/`:翻译。+- `docs/`:英文和中文文档。-- [Nuxt 4 文档](https://nuxt.com/)-- [Vue 3 文档](https://vuejs.org/)-- [Drizzle ORM 文档](https://orm.drizzle.team/)-- [TailwindCSS 文档](https://tailwindcss.com/)+新增后台设置请阅读[设置开发指南](/zh/development/how-to-add-setting)。调试 S3、OpenList、地图或 GitHub 登录时,在后台填入测试服务的参数,OAuth 回调地址使用 `http://localhost:3000/api/auth/github`。-### 社区资源+## 提交更改-- [GitHub Issues](https://github.com/HoshinoSuzumi/chronoframe/issues)-- [GitHub Discussions](https://github.com/HoshinoSuzumi/chronoframe/discussions)+保持改动集中,使用 Conventional Commits 描述更改。PR 中说明解决的问题、最终行为和验证结果;涉及界面时附上截图,涉及文档时同步更新英文和中文。可从 GitHub 的 `good first issue` 和 `help wanted` 问题开始。diff --cc docs/zh/legacy/guide/configuration.mdindex 32f17426,00000000..481ee8a0mode 100644,000000..100644--- a/docs/zh/legacy/guide/configuration.md+++ b/docs/zh/legacy/guide/configuration.md@@@ -1,87 -1,0 +1,87 @@@+---+search: false+---++::: warning 历史文档+本文保留旧版的部署和环境变量说明,仅供维护旧实例时查阅。当前版本请从[快速开始](/zh/guide/getting-started)进入,日常设置在后台完成。+:::++# 配置项说明++无论是使用 Docker 还是 Docker Compose (.env) 方式部署,均通过环境变量进行配置。++## 环境变量列表++| 环境变量 | 说明 | 默认值 | 必需 |+| ---------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------- | --------------------------------------------------------------------- |+| CFRAME_ADMIN_EMAIL | 初始管理员用户的邮箱 | `[email protected]` | 是 |+| CFRAME_ADMIN_NAME | 初始管理员用户的用户名 | `Chronoframe` | 否 |+| CFRAME_ADMIN_PASSWORD | 初始管理员用户的密码 | `CF1234@!` | 否 |+| NUXT_PUBLIC_APP_TITLE | 应用标题 | `ChronoFrame` | 否 |+| NUXT_PUBLIC_APP_SLOGAN | 应用口号 | 无 | 否 |+| NUXT_PUBLIC_APP_AUTHOR | 应用作者 | 无 | 否 |- | NUXT_PUBLIC_APP_AVATAR_URL | 应用头像 URL | 无 | 否 |++| NUXT_PUBLIC_APP_AVATAR_URL | 外部应用头像 URL(也可在后台上传头像,存储在已配置的存储提供商中) | 无 | 否 |+| NUXT_PUBLIC_COLOR_MODE_PREFERENCE | 颜色模式偏好,可选 `light`、`dark`、`system` | system | 否 |+| NUXT_PUBLIC_MAP_PROVIDER | 地图提供者,可选 `mapbox`、`maplibre` | `maplibre` | 否 |+| NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN | Mapbox 访问令牌(可限制 URL),用于地图服务 | 无 | 当 `NUXT_PUBLIC_MAP_PROVIDER` 为 `mapbox` 时必需 |+| NUXT_NOMINATIM_BASE_URL | Nominatim 反向地理编码服务的基础 URL | `https://nominatim.openstreetmap.org` | 否 |+| NUXT_MAPBOX_ACCESS_TOKEN | Mapbox 访问令牌(无 URL 限制),用于位置信息服务 | 无 | 否 |+| NUXT_STORAGE_PROVIDER | 存储提供者,支持 `local`、`s3`、`openlist` | `local` | 是 |+| NUXT_PROVIDER_LOCAL_PATH | 本地存储路径 | `/app/data/storage` | 否 |+| NUXT_PROVIDER_LOCAL_BASE_URL | 本地存储的访问 URL | `/storage` | 否 |+| 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_PROVIDER_OPENLIST_BASE_URL | OpenList 服务器 URL | 无 | 当 `NUXT_STORAGE_PROVIDER` 为 `openlist` 时必需 |+| NUXT_PROVIDER_OPENLIST_ROOT_PATH | OpenList 根路径 | 无 | 当 `NUXT_STORAGE_PROVIDER` 为 `openlist` 时必需 |+| NUXT_PROVIDER_OPENLIST_TOKEN | OpenList API 令牌 | 无 | 当 `NUXT_STORAGE_PROVIDER` 为 `openlist` 时必需(用于 OpenList 认证) |+| NUXT_PROVIDER_OPENLIST_ENDPOINT_UPLOAD | OpenList 上传端点 | `/api/fs/put` | 否 |+| NUXT_PROVIDER_OPENLIST_ENDPOINT_DOWNLOAD | OpenList 下载端点 | 无 | 否 |+| NUXT_PROVIDER_OPENLIST_ENDPOINT_LIST | OpenList 列表端点 | 无 | 否 |+| NUXT_PROVIDER_OPENLIST_ENDPOINT_DELETE | OpenList 删除端点 | `/api/fs/remove` | 否 |+| NUXT_PROVIDER_OPENLIST_ENDPOINT_META | OpenList 元数据端点 | `/api/fs/get` | 否 |+| NUXT_PROVIDER_OPENLIST_PATH_FIELD | OpenList 路径字段名 | `path` | 否 |+| NUXT_PROVIDER_OPENLIST_CDN_URL | OpenList CDN 地址 | 无 | 否 |+| NUXT_PUBLIC_OAUTH_GITHUB_ENABLED | 是否启用 GitHub OAuth 登录 | `false` | 否 |+| NUXT_OAUTH_GITHUB_CLIENT_ID | GitHub OAuth 应用的 Client ID | 无 | 否(可选,用于 GitHub 登录) |+| NUXT_OAUTH_GITHUB_CLIENT_SECRET | GitHub OAuth 应用的 Client Secret | 无 | 否(可选,用于 GitHub 登录) |+| NUXT_SESSION_PASSWORD | 用于加密会话的密码,32 位随机字符串 | 无 | 是 |+| NUXT_TRUST_PROXY | 相簿解锁限流是否信任 `X-Forwarded-For`;仅在可信反代覆盖客户端同名请求头时启用 | `false` | 否 |+| NUXT_PUBLIC_GTAG_ID | Google Analytics 追踪 ID | 无 | 否 |+| NUXT_PUBLIC_ANALYTICS_MATOMO_ENABLED | 是否启用 Matomo 分析追踪 | `false` | 否 |+| NUXT_PUBLIC_ANALYTICS_MATOMO_URL | Matomo 实例 URL 地址(如: https://matomo.example.com) | 无 | 否(启用 Matomo 时必需) |+| NUXT_PUBLIC_ANALYTICS_MATOMO_SITE_ID | Matomo 站点 ID | 无 | 否(启用 Matomo 时必需) |+| NUXT_UPLOAD_MIME_WHITELIST_ENABLED | 是否启用上传文件 MIME 类型白名单验证 | `true` | 否 |+| NUXT_UPLOAD_MIME_WHITELIST | 上传文件允许的 MIME 类型列表(逗号分隔) | 见下方说明 | 否 |+| ALLOW_INSECURE_COOKIE | 是否允许非安全 Cookie(仅在开发环境使用) | `false` | 否 |++## 上传文件类型白名单++`NUXT_UPLOAD_MIME_WHITELIST` 的默认值包含以下 MIME 类型:++- `image/jpeg` - JPEG 图片+- `image/png` - PNG 图片+- `image/webp` - WebP 图片+- `image/gif` - GIF 图片+- `image/bmp` - BMP 图片+- `image/tiff` - TIFF 图片+- `image/heic` - HEIC 图片(Apple)+- `image/heif` - HEIF 图片+- `video/quicktime` - QuickTime 视频(MOV)+- `video/mp4` - MP4 视频++如需自定义白名单,请使用逗号分隔的 MIME 类型字符串,例如:++```+NUXT_UPLOAD_MIME_WHITELIST=image/jpeg,image/png,video/mp4+```++如需禁用白名单验证(允许任何文件类型),可设置:++```+NUXT_UPLOAD_MIME_WHITELIST_ENABLED=false+```