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: add API documentation and configuration reference; update contributing, storage providers, and update guides in English and Chinese

HoshinoSuzumi480b9e7a45ee
diff --git a/docs/develop/queue-api.md b/docs/.develop/queue-api.md
similarity index 100%
rename from docs/develop/queue-api.md
rename to docs/.develop/queue-api.md
diff --git a/docs/develop/queue-task-api.md b/docs/.develop/queue-task-api.md
similarity index 100%
rename from docs/develop/queue-task-api.md
rename to docs/.develop/queue-task-api.md
diff --git a/docs/develop/retry-mechanism.md b/docs/.develop/retry-mechanism.md
similarity index 100%
rename from docs/develop/retry-mechanism.md
rename to docs/.develop/retry-mechanism.md
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 41464232..1c95aa7c 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -9,13 +9,31 @@ export default defineConfig({
// https://vitepress.dev/reference/default-theme-config
nav: [
{ text: 'Guide', link: '/guide/getting-started' },
+ { text: 'Development', link: '/guide/contributing' },
{ text: 'Demo', link: 'https://lens.bh8.ga' },
],
sidebar: [
{
text: 'Guide',
- items: [{ text: 'Getting Started', link: '/guide/getting-started' }],
+ items: [
+ { text: 'Getting Started', link: '/guide/getting-started' },
+ { text: 'Configuration', link: '/guide/configuration' },
+ { text: 'Update Guide', link: '/guide/updates' },
+ ],
+ },
+ {
+ text: 'Configuration',
+ items: [
+ { text: 'Storage Providers', link: '/guide/storage-providers' },
+ ],
+ },
+ {
+ text: 'Development',
+ items: [
+ { text: 'Contributing Guide', link: '/guide/contributing' },
+ { text: 'API Documentation', link: '/guide/api' },
+ ],
},
],
diff --git a/docs/guide/api.md b/docs/guide/api.md
new file mode 100644
index 00000000..14d3b15e
--- /dev/null
+++ b/docs/guide/api.md
@@ -0,0 +1,3 @@
+# API Documentation
+
+🚧 WIP
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
new file mode 100644
index 00000000..bb756f89
--- /dev/null
+++ b/docs/guide/configuration.md
@@ -0,0 +1,28 @@
+# 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 | None | Yes, fill in the GitHub account email used for login |
+| 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_MAPBOX_ACCESS_TOKEN | Mapbox access token (URL restricted), for map services | None | Yes |
+| NUXT_MAPBOX_ACCESS_TOKEN | Mapbox access token (no URL restriction), for location services | None | No |
+| NUXT_STORAGE_PROVIDER | Storage provider, supports `s3`, `github`, `local` | `s3` | Yes |
+| 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_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 | Password for encrypting sessions, 32-character random string | None | Yes |
\ No newline at end of file
diff --git a/docs/guide/contributing.md b/docs/guide/contributing.md
new file mode 100644
index 00000000..be3629ef
--- /dev/null
+++ b/docs/guide/contributing.md
@@ -0,0 +1,349 @@
+# Contributing Guide
+
+This document will guide you through setting up the ChronoFrame development environment, including environment requirements, dependency installation, configuration settings, and development tools.
+
+## 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
+
+```bash
+# Using HTTPS
+git clone https://github.com/HoshinoSuzumi/chronoframe.git
+
+# Or using SSH
+git clone [email protected]:HoshinoSuzumi/chronoframe.git
+
+# Enter project directory
+cd 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
+
+```env
+# === 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
+```
+
+## 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
+pnpm dev
+
+# Or start step by step
+pnpm build:deps # Build WebGL package
+pnpm dlx nuxi@latest dev # Start Nuxt development server only
+```
+
+### Database Operations
+
+```bash
+# Generate migration files
+pnpm db:generate
+
+# Execute database migrations
+pnpm db:migrate
+```
+
+### Build Project
+
+```bash
+# Build WebGL dependency package
+pnpm build:deps
+
+# Build complete project
+pnpm build
+
+# Preview production build
+pnpm preview
+```
+
+## 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:
+
+- `good first issue`: Tasks suitable for beginners
+- `help wanted`: Tasks needing community help
+- `documentation`: Documentation-related improvements
+
+## Useful Resources
+
+### Official 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/)
+
+### Community Resources
+
+- [GitHub Issues](https://github.com/HoshinoSuzumi/chronoframe/issues)
+- [GitHub Discussions](https://github.com/HoshinoSuzumi/chronoframe/discussions)
\ No newline at end of file
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index 7c30aba5..11f7da2c 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -1,35 +1,43 @@
# Getting Started
-:::warning 🚧WIP
-The documentation is under construction, and some feature docs are not yet complete.
+This documentation will guide you on how to quickly deploy and start using ChronoFrame.
+
+:::warning 🚧 Under Construction
+Documentation is being written, some feature documentation is not yet complete.
:::
-## 🛠️ Prerequisites
+## Prerequisites
-- A working [Docker](https://docs.docker.com/get-docker/) environment.
-- An S3-compatible storage bucket *(GitHub repository storage and local filesystem storage are still under development)*.
+- Available [Docker](https://docs.docker.com/get-docker/) environment.
+- An S3 protocol-compatible storage bucket *(GitHub repository storage and local filesystem storage are still in development)*.
:::tip
- When using S3 storage, you need at least the following information from your provider: `ACCESS_KEY_ID`, `SECRET_ACCESS_KEY`, `ENDPOINT`, `BUCKET_NAME`, `REGION`. If your bucket's public URL differs from the `ENDPOINT`, you'll also need to provide the public URL as `CDN_URL`.
+ When using S3 storage, you need to obtain at least the following information from your service provider: `ACCESS_KEY_ID`, `SECRET_ACCESS_KEY`, `ENDPOINT`, `BUCKET_NAME`, `REGION`. When the bucket's external URL is different from the `ENDPOINT`, you also need to provide the external URL `CDN_URL`.
:::
- Two [Mapbox access tokens](https://console.mapbox.com/account/access-tokens/).
:::details Why do I need two tokens?
- - The first token is for frontend map display and requires `styles:read` permission. It's recommended to restrict this token's URL to your ChronoFrame instance domain to prevent abuse.
- - The second token is for backend reverse geocoding and **cannot** have URL restrictions. This token is **optional**.
+ - The first token is used for frontend map display, requires `styles:read` permission. It's recommended to restrict this token's URL to your ChronoFrame instance domain to prevent abuse.
+ - The second token is used for backend reverse geocoding, this token **cannot** have URL restrictions. This token is **optional**.
:::
-- `CLIENT_ID` and `CLIENT_SECRET` from a [GitHub OAuth App](https://github.com/settings/applications/new) *(optional, for enabling GitHub login)*.
+- [GitHub OAuth App](https://github.com/settings/applications/new) `CLIENT_ID` and `CLIENT_SECRET` *(optional, for enabling GitHub login)*.
:::tip
- When creating the OAuth app, set the `Authorization callback URL` to `http(s)://<your-domain>/api/auth/github`.
+ When creating the OAuth app, the `Authorization callback URL` should be set to `http(s)://<your-domain>/api/auth/github`.
:::
-## 🐳 Quick Deployment
+## Quick Deployment
+
+### Pre-built Images
+
+We recommend using pre-built Docker images for deployment, hosted on GitHub Container Registry:
-We recommend using the pre-built Docker image for deployment. [View the image on ghcr](https://github.com/HoshinoSuzumi/chronoframe/pkgs/container/chronoframe).
+```
+ghcr.io/hoshinosuzumi/chronoframe:latest
+```
-Choose between Docker or Docker Compose based on your preference.
+[View all available versions](https://github.com/HoshinoSuzumi/chronoframe/pkgs/container/chronoframe)
-### Deploy with Docker
+### Docker Single Container Deployment
-Run the following command to start a ChronoFrame instance:
+#### Quick Start
```bash
docker run -d \
@@ -58,19 +66,21 @@ docker run -d \
ghcr.io/hoshinosuzumi/chronoframe:latest
```
-### Deploy with Docker Compose
+### Docker Compose Deployment
-Create a `.env` file:
+Recommended for production environment deployment using Docker Compose for easier management and configuration.
+
+#### 1. Create `.env` file
```env
# Admin user email (required)
CFRAME_ADMIN_EMAIL=
-# Admin user name (default to Chronoframe, optional)
+# Admin username (default to Chronoframe, optional)
CFRAME_ADMIN_NAME=
# Admin user password (default to CF1234@!, optional)
CFRAME_ADMIN_PASSWORD=
-# App title and slogan
+# Application title and slogan
NUXT_PUBLIC_APP_TITLE=
NUXT_PUBLIC_APP_SLOGAN=
NUXT_PUBLIC_APP_AUTHOR=
@@ -100,7 +110,7 @@ NUXT_OAUTH_GITHUB_CLIENT_ID=
NUXT_OAUTH_GITHUB_CLIENT_SECRET=
```
-Create a `docker-compose.yml` file:
+#### 2. Create `docker-compose.yml` file
```yaml
services:
@@ -116,10 +126,130 @@ services:
- .env
```
-Start the ChronoFrame instance:
+#### 3. Start ChronoFrame Service
```bash
+# Start service
docker compose up -d
+
+# View logs
+docker compose logs -f chronoframe
+
+# Stop service
+docker compose down
+
+# Update to latest version
+docker compose pull
+docker compose up -d
+```
+
+## Reverse Proxy
+
+When deploying in production environment, you usually need a reverse proxy server (like Nginx or Caddy) to handle HTTPS and domain resolution. Here are some example configurations.
+
+### Nginx
+
+```nginx
+server {
+ listen 80;
+ server_name your-domain.com;
+
+ # HTTPS redirect
+ return 301 https://$server_name$request_uri;
+}
+
+server {
+ listen 443 ssl http2;
+ server_name your-domain.com;
+
+ # SSL certificate configuration
+ ssl_certificate /path/to/your/certificate.crt;
+ ssl_certificate_key /path/to/your/private.key;
+
+ # SSL security configuration
+ ssl_protocols TLSv1.2 TLSv1.3;
+ ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
+ ssl_prefer_server_ciphers off;
+
+ # Upload size limit
+ client_max_body_size 100M;
+
+ location / {
+ proxy_pass http://localhost:3000;
+ proxy_http_version 1.1;
+ proxy_set_header Upgrade $http_upgrade;
+ proxy_set_header Connection 'upgrade';
+ proxy_set_header Host $host;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ proxy_cache_bypass $http_upgrade;
+
+ # WebSocket support
+ proxy_set_header Connection "upgrade";
+ proxy_set_header Upgrade $http_upgrade;
+
+ # Timeout settings
+ proxy_connect_timeout 60s;
+ proxy_send_timeout 60s;
+ proxy_read_timeout 60s;
+ }
+
+ # Static resource caching
+ location ~* \.(jpg|jpeg|png|gif|webp|svg|css|js|ico|woff|woff2|ttf|eot)$ {
+ proxy_pass http://localhost:3000;
+ expires 1y;
+ add_header Cache-Control "public, immutable";
+ proxy_set_header Host $host;
+ }
+}
+```
+
+### Traefik
+
+If you use Traefik as reverse proxy, you can add labels in `docker-compose.yml`:
+
+```yaml
+services:
+ chronoframe:
+ image: ghcr.io/hoshinosuzumi/chronoframe:latest
+ container_name: chronoframe
+ restart: unless-stopped
+ volumes:
+ - ./data:/app/data
+ env_file:
+ - .env
+ labels:
+ - "traefik.enable=true"
+ - "traefik.http.routers.chronoframe.rule=Host(`your-domain.com`)"
+ - "traefik.http.routers.chronoframe.entrypoints=websecure"
+ - "traefik.http.routers.chronoframe.tls.certresolver=letsencrypt"
+ - "traefik.http.services.chronoframe.loadbalancer.server.port=3000"
+ networks:
+ - traefik
+
+networks:
+ traefik:
+ external: true
```
+## Common Issues
+:::details How to generate random `NUXT_SESSION_PASSWORD`?
+```bash
+# Linux / macOS
+openssl rand -base64 32
+
+# Windows (pwsh)
+[Convert]::ToBase64String((1..32|%{[byte](Get-Random -Max 256)}))
+```
+:::
+
+:::details After successful backend authentication login, redirect to homepage and still in unauthenticated state?
+First, please make sure you're not accessing directly through IP address and port number. For security reasons, please access through the configured domain name.
+
+If for some reason you insist on accessing through IP port, please add to configuration:
+```env
+NUXT_ALLOW_INSECURE_COOKIE=true
+```
+:::
\ No newline at end of file
diff --git a/docs/guide/storage-providers.md b/docs/guide/storage-providers.md
new file mode 100644
index 00000000..af9c42ea
--- /dev/null
+++ b/docs/guide/storage-providers.md
@@ -0,0 +1,152 @@
+# Storage Provider Configuration
+
+ChronoFrame supports multiple storage backends to save your photos and thumbnails. This document will detail how to configure different storage providers.
+
+| Provider | Support | Use Case | Cost |
+| ------------------ | :-----: | ---------------------- | -------------- |
+| **S3 Compatible** | ✅ | Production environment | Varies by provider |
+| **GitHub** | 🚧 | Small scale, version control | Free (with limits) |
+| **Local Filesystem** | 🚧 | Testing environment, offline deployment | Free |
+
+## S3 Compatible Storage
+
+S3 compatible storage is the most recommended production environment option, supporting all major cloud service providers.
+
+### Basic Configuration
+
+```env
+# Set storage provider to S3
+NUXT_STORAGE_PROVIDER=s3
+
+# S3 basic configuration
+NUXT_PROVIDER_S3_ENDPOINT=https://your-s3-endpoint.com
+NUXT_PROVIDER_S3_BUCKET=chronoframe-photos
+NUXT_PROVIDER_S3_REGION=us-east-1
+NUXT_PROVIDER_S3_ACCESS_KEY_ID=your-access-key-id
+NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=your-secret-access-key
+
+# Optional configuration
+NUXT_PROVIDER_S3_PREFIX=photos/
+NUXT_PROVIDER_S3_CDN_URL=https://cdn.example.com
+```
+
+### Cloud Provider Configuration Examples
+
+#### AWS S3
+
+```env
+NUXT_STORAGE_PROVIDER=s3
+NUXT_PROVIDER_S3_ENDPOINT=https://s3.amazonaws.com
+NUXT_PROVIDER_S3_BUCKET=my-chronoframe-bucket
+NUXT_PROVIDER_S3_REGION=us-east-1
+NUXT_PROVIDER_S3_ACCESS_KEY_ID=AKIA...
+NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=...
+NUXT_PROVIDER_S3_CDN_URL=https://d1234567890.cloudfront.net
+```
+
+#### Cloudflare R2
+
+```env
+NUXT_STORAGE_PROVIDER=s3
+NUXT_PROVIDER_S3_ENDPOINT=https://[account-id].r2.cloudflarestorage.com
+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_CDN_URL=https://photos.example.com
+```
+
+#### Alibaba Cloud OSS
+
+```env
+NUXT_STORAGE_PROVIDER=s3
+NUXT_PROVIDER_S3_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
+NUXT_PROVIDER_S3_BUCKET=chronoframe-photos
+NUXT_PROVIDER_S3_REGION=oss-cn-hangzhou
+NUXT_PROVIDER_S3_ACCESS_KEY_ID=LTAI...
+NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=...
+NUXT_PROVIDER_S3_CDN_URL=https://cdn.example.com
+```
+
+#### Tencent Cloud COS
+
+```env
+NUXT_STORAGE_PROVIDER=s3
+NUXT_PROVIDER_S3_ENDPOINT=https://cos.ap-beijing.myqcloud.com
+NUXT_PROVIDER_S3_BUCKET=chronoframe-1234567890
+NUXT_PROVIDER_S3_REGION=ap-beijing
+NUXT_PROVIDER_S3_ACCESS_KEY_ID=AKID...
+NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=...
+```
+
+#### MinIO Self-hosted
+
+```env
+NUXT_STORAGE_PROVIDER=s3
+NUXT_PROVIDER_S3_ENDPOINT=https://minio.example.com
+NUXT_PROVIDER_S3_BUCKET=chronoframe
+NUXT_PROVIDER_S3_REGION=us-east-1
+NUXT_PROVIDER_S3_ACCESS_KEY_ID=minioadmin
+NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=minioadmin
+```
+
+### Bucket Configuration
+
+#### CORS Settings
+
+Recommended CORS configuration:
+
+```json
+[
+ {
+ "AllowedOrigins": ["https://your-domain.com"],
+ "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],
+ "AllowedHeaders": ["*"],
+ "ExposeHeaders": ["ETag"],
+ "MaxAgeSeconds": 3000
+ }
+]
+```
+
+## GitHub Storage (In Development)
+
+GitHub storage stores photos in Git repositories, suitable for small-scale use.
+
+```env
+# Set storage provider to GitHub (not yet implemented)
+NUXT_STORAGE_PROVIDER=github
+
+# GitHub storage configuration
+NUXT_PROVIDER_GITHUB_OWNER=your-username
+NUXT_PROVIDER_GITHUB_REPOSITORY=chronoframe-photos
+NUXT_PROVIDER_GITHUB_BRANCH=main
+NUXT_PROVIDER_GITHUB_PATH=photos
+NUXT_PROVIDER_GITHUB_TOKEN=ghp_...
+```
+
+## Local Filesystem (In Development)
+
+Local storage saves files in the server filesystem.
+
+```env
+# Set storage provider to local (not yet implemented)
+NUXT_STORAGE_PROVIDER=local
+
+# Local storage configuration
+NUXT_PROVIDER_LOCAL_PATH=/app/storage
+NUXT_PROVIDER_LOCAL_BASE_URL=https://your-domain.com/storage
+```
+
+## Common Issues
+
+:::details `The AWS Access Key Id you provided does not exist in our records`
+Access key error, check if `ACCESS_KEY_ID` and `SECRET_ACCESS_KEY` are correct.
+:::
+
+:::details `The specified bucket does not exist`
+Bucket does not exist, confirm the bucket name is correct and exists in the specified region.
+:::
+
+:::details Can upload but cannot access images, console shows `Access to fetch at '...' from origin '...' has been blocked by CORS policy`
+Bucket CORS configuration error, refer to [CORS Settings](#cors-settings) for configuration.
+:::
\ No newline at end of file
diff --git a/docs/guide/updates.md b/docs/guide/updates.md
new file mode 100644
index 00000000..028da229
--- /dev/null
+++ b/docs/guide/updates.md
@@ -0,0 +1,113 @@
+# Update Guide
+
+This document will guide you through safely updating and upgrading ChronoFrame to the latest version.
+
+## Version Check
+
+### View Current Version
+
+#### Through Web Interface
+1. Login to ChronoFrame admin dashboard
+2. Go to "Dashboard" page
+3. Check version number in "Runtime Information" panel
+
+## Update Process
+
+### Preparation
+
+#### 1. Data Backup
+```bash
+# Stop service
+docker-compose down
+
+# Create complete backup
+ts=$(date +%Y%m%d-%H%M%S) && mkdir -p backups/$ts && cp -r data/ .env docker-compose.yml backups/$ts/
+```
+
+#### 2. Check Compatibility
+Review [Release Notes](https://github.com/HoshinoSuzumi/chronoframe/releases) to understand:
+- Breaking changes
+- New environment variables
+- Feature deprecation notices
+
+### Docker Compose Update (Recommended)
+
+#### Standard Update Process
+
+```bash
+# 1. Enter project directory
+cd /path/to/chronoframe
+
+# 2. Backup current configuration
+cp docker-compose.yml docker-compose.yml.backup
+
+# 3. Stop current service
+docker-compose down
+
+# 4. Pull latest image
+docker-compose pull
+
+# 5. Start new version
+docker-compose up -d
+
+# 6. View startup logs
+docker-compose logs -f chronoframe
+```
+
+#### Specific Version Update
+
+If you need to update to a specific version:
+
+```yaml
+# docker-compose.yml
+services:
+ chronoframe:
+ image: ghcr.io/hoshinosuzumi/chronoframe:v1.2.3 # Specify version
+ # ... other configurations
+```
+
+```bash
+docker-compose up -d
+```
+
+### Single Container Update
+
+```bash
+# Stop existing container
+docker stop chronoframe
+docker rm chronoframe
+
+# Pull latest image
+docker pull ghcr.io/hoshinosuzumi/chronoframe:latest
+
+# Start new container with same configuration
+docker run -d \
+ --name chronoframe \
+ -p 3000:3000 \
+ -v $(pwd)/data:/app/data \
+ --env-file .env \
+ ghcr.io/hoshinosuzumi/chronoframe:latest
+```
+
+## Database Migration
+
+### Automatic Migration
+
+ChronoFrame automatically executes database migrations on startup:
+
+```bash
+# View migration logs
+docker logs chronoframe | grep -i migration
+```
+
+### Manual Migration (Advanced)
+
+In special cases, you may need to manually execute migrations:
+
+```bash
+# Enter container
+docker exec -it chronoframe sh
+
+# Execute migration
+npx drizzle-kit migrate
+```
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
index c90fcb57..3b2c18bc 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -3,9 +3,9 @@
layout: home
hero:
- name: 'ChronoFrame'
- text: 'Self-hosted, online-managed gallery'
- tagline: Mems rest within the lens.
+ name: "ChronoFrame"
+ text: "Self-hosted Personal Gallery"
+ tagline: "Manage photos online with multi-storage backends, LivePhoto, and globe view"
actions:
- theme: brand
text: Getting Started
@@ -20,11 +20,36 @@ hero:
features:
- title: Powerful Photo Management
icon: 🖼️
- details: Easily manage and browse photos via the web interface, browse photo locations on a map.
- - title: Easy to Deploy
+ details: Easily manage and browse photos through web interface, view photo locations on map.
+ - title: Simple Deployment
icon: 🚀
- details: Deploy with a single command using Docker, no database required(based on SQLite3).
+ details: Deploy with one command using Docker, no database required (based on SQLite3).
- title: Flexible Storage Solutions
icon: 💾
- details: Supports various storage backends, including S3-compatible storage, GitHub (WIP), and local filesystem (WIP).
+ details: Support multiple storage backends including S3-compatible storage, GitHub (in development), and local filesystem (in development).
+ - title: Smart Geolocation
+ icon: 🌍
+ details: Automatically extract photo GPS information, use Mapbox for geocoding, display photo locations on map.
+ - title: Responsive Design
+ icon: 📱
+ details: Perfect for desktop and mobile, support touch operations and gesture controls, native app-like experience.
+ - title: LivePhoto Support
+ icon: 🎬
+ details: Full support for Apple LivePhoto format, automatically detect and process MOV video files, preserve dynamic photo effects.
+
---
+
+## 🌍 Demo Sites
+
+Here are some well-running ChronoFrame instances built by developers and community members:
+
+- [**TimoYin's Mems**](https://lens.bh8.ga)
+
+## 💬 Community Support
+
+- **GitHub Issues**: [Report Issues](https://github.com/HoshinoSuzumi/chronoframe/issues)
+- **GitHub Discussions**: [Discussions](https://github.com/HoshinoSuzumi/chronoframe/discussions)
+
+## 📄 License
+
+ChronoFrame is open source under the [MIT License](https://github.com/HoshinoSuzumi/chronoframe/blob/main/LICENSE), welcome to use and contribute freely.
diff --git a/docs/zh/config.ts b/docs/zh/config.ts
index 13ca76bf..4ec9543b 100644
--- a/docs/zh/config.ts
+++ b/docs/zh/config.ts
@@ -8,13 +8,31 @@ export default defineConfig({
// https://vitepress.dev/reference/default-theme-config
nav: [
{ text: '指南', link: '/zh/guide/getting-started' },
+ { text: '开发文档', link: '/zh/guide/contributing' },
{ text: '演示', link: 'https://lens.bh8.ga' },
],
sidebar: [
{
text: '指南',
- items: [{ text: '快速开始', link: '/zh/guide/getting-started' }],
+ items: [
+ { text: '快速开始', link: '/zh/guide/getting-started' },
+ { text: '配置说明', link: '/zh/guide/configuration' },
+ { text: '升级指南', link: '/zh/guide/updates' },
+ ],
+ },
+ {
+ text: '配置',
+ items: [
+ { text: '存储提供器', link: '/zh/guide/storage-providers' },
+ ],
+ },
+ {
+ text: '开发',
+ items: [
+ { text: '贡献指南', link: '/zh/guide/contributing' },
+ { text: 'API 文档', link: '/zh/guide/api' },
+ ],
},
],
diff --git a/docs/zh/guide/api.md b/docs/zh/guide/api.md
new file mode 100644
index 00000000..08ff383d
--- /dev/null
+++ b/docs/zh/guide/api.md
@@ -0,0 +1,3 @@
+# API 文档
+
+🚧 WIP
diff --git a/docs/zh/guide/configuration.md b/docs/zh/guide/configuration.md
new file mode 100644
index 00000000..f132de4e
--- /dev/null
+++ b/docs/zh/guide/configuration.md
@@ -0,0 +1,28 @@
+# 配置项说明
+
+无论是使用 Docker 还是 Docker Compose (.env) 方式部署,均通过环境变量进行配置。
+
+## 环境变量列表
+
+| 环境变量 | 说明 | 默认值 | 必需 |
+| ---------------------------------- | ---------------------------------------------- | ----------- | ----------------------------------------- |
+| CFRAME_ADMIN_EMAIL | 初始管理员用户的邮箱 | 无 | 是,填写登录使用的 GitHub 账户的邮箱 |
+| 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_MAPBOX_ACCESS_TOKEN | Mapbox 访问令牌(可限制 URL),用于地图服务 | 无 | 是 |
+| NUXT_MAPBOX_ACCESS_TOKEN | Mapbox 访问令牌(无 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 位随机字符串 | 无 | 是 |
diff --git a/docs/zh/guide/contributing.md b/docs/zh/guide/contributing.md
new file mode 100644
index 00000000..5a68c57e
--- /dev/null
+++ b/docs/zh/guide/contributing.md
@@ -0,0 +1,349 @@
+# 开始贡献
+
+本文档将指导您搭建 ChronoFrame 的开发环境,包括环境要求、依赖安装、配置设置和开发工具。
+
+## 环境要求
+
+### 必需软件
+
+- **Node.js**: 20.0+
+- **pnpm**: 9.0+ (首选包管理器)
+- **Git**: 最新版本
+- **Docker**: 可选,用于容器化开发
+
+## 克隆与安装
+
+### 1. 克隆代码库
+
+```bash
+# 使用 HTTPS
+git 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 # 或使用您喜欢的编辑器
+```
+
+#### 最小开发配置
+
+```env
+# === 管理员账户 ===
+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
+```
+
+## 项目架构
+
+### 目录结构
+
+```
+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
+# 启动完整开发服务器
+pnpm dev
+
+# 或分步启动
+pnpm build:deps # 构建 WebGL 包
+pnpm dlx nuxi@latest dev # 只启动 Nuxt 开发服务器
+```
+
+### 数据库操作
+
+```bash
+# 生成迁移文件
+pnpm db:generate
+
+# 执行数据库迁移
+pnpm db:migrate
+```
+
+### 构建项目
+
+```bash
+# 构建 WebGL 依赖包
+pnpm build:deps
+
+# 构建完整项目
+pnpm build
+
+# 预览生产构建
+pnpm preview
+```
+
+## 测试环境
+
+### 本地 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:
+
+- `good first issue`: 适合新手的任务
+- `help wanted`: 需要社区帮助的任务
+- `documentation`: 文档相关的改进
+
+## 有用资源
+
+### 官方文档
+
+- [Nuxt 4 文档](https://nuxt.com/)
+- [Vue 3 文档](https://vuejs.org/)
+- [Drizzle ORM 文档](https://orm.drizzle.team/)
+- [TailwindCSS 文档](https://tailwindcss.com/)
+
+### 社区资源
+
+- [GitHub Issues](https://github.com/HoshinoSuzumi/chronoframe/issues)
+- [GitHub Discussions](https://github.com/HoshinoSuzumi/chronoframe/discussions)
diff --git a/docs/zh/guide/getting-started.md b/docs/zh/guide/getting-started.md
index d427dd02..09ed635d 100644
--- a/docs/zh/guide/getting-started.md
+++ b/docs/zh/guide/getting-started.md
@@ -1,10 +1,12 @@
# 快速开始
+本文档将指导您如何快速部署并开始使用 ChronoFrame。
+
:::warning 🚧施工中
文档正在编写中,部分功能文档尚未完成。
:::
-## 🛠️ 前置准备
+## 前置准备
- 可用的 [Docker](https://docs.docker.com/get-docker/) 环境。
- 一个支持 S3 协议的存储桶 *(GitHub 仓库存储和本地文件系统存储仍在开发中)*。
@@ -21,15 +23,21 @@
创建 OAuth 应用时,`Authorization callback URL` 应设置为 `http(s)://<你的域名>/api/auth/github`。
:::
-## 🐳 快速部署
+## 快速部署
+
+### 预建镜像
+
+我们推荐使用预构建的 Docker 镜像进行部署,镜像托管在 GitHub Container Registry:
-推荐使用预构建的 docker 镜像部署,[在 ghcr 上查看镜像](https://github.com/HoshinoSuzumi/chronoframe/pkgs/container/chronoframe)。
+```
+ghcr.io/hoshinosuzumi/chronoframe:latest
+```
-按喜好选择 Docker 或 Docker Compose 进行部署。
+[查看所有可用版本](https://github.com/HoshinoSuzumi/chronoframe/pkgs/container/chronoframe)
-### 使用 Docker 部署
+### Docker 单容器部署
-运行以下命令启动 ChronoFrame 实例:
+#### 快速启动
```bash
docker run -d \
@@ -58,14 +66,16 @@ docker run -d \
ghcr.io/hoshinosuzumi/chronoframe:latest
```
-### 使用 Docker Compose 部署
+### Docker Compose 部署
-创建 `.env` 文件
+推荐使用 Docker Compose 进行生产环境部署,便于管理和配置。
+
+#### 1. 创建 `.env` 文件
```env
# Admin user email (required)
CFRAME_ADMIN_EMAIL=
-# Admin user name (default to Chronoframe, optional)
+# Admin username (default to Chronoframe, optional)
CFRAME_ADMIN_NAME=
# Admin user password (default to CF1234@!, optional)
CFRAME_ADMIN_PASSWORD=
@@ -100,7 +110,7 @@ NUXT_OAUTH_GITHUB_CLIENT_ID=
NUXT_OAUTH_GITHUB_CLIENT_SECRET=
```
-创建 `docker-compose.yml` 文件
+#### 2. 创建 `docker-compose.yml` 文件
```yaml
services:
@@ -116,8 +126,130 @@ services:
- .env
```
-启动 ChronoFrame 实例
+#### 3. 启动 ChronoFrame 服务
```bash
+# 启动服务
+docker compose up -d
+
+# 查看日志
+docker compose logs -f chronoframe
+
+# 停止服务
+docker compose down
+
+# 更新到最新版本
+docker compose pull
docker compose up -d
-```
\ No newline at end of file
+```
+
+## 反向代理
+
+在生产环境中部署时,您通常需要一个反向代理服务器(如 Nginx 或 Caddy)来处理 HTTPS 和域名解析。以下是一些示例配置。
+
+### Nginx
+
+```nginx
+server {
+ listen 80;
+ server_name your-domain.com;
+
+ # HTTPS 重定向
+ return 301 https://$server_name$request_uri;
+}
+
+server {
+ listen 443 ssl http2;
+ server_name your-domain.com;
+
+ # SSL 证书配置
+ ssl_certificate /path/to/your/certificate.crt;
+ ssl_certificate_key /path/to/your/private.key;
+
+ # SSL 安全配置
+ ssl_protocols TLSv1.2 TLSv1.3;
+ ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
+ ssl_prefer_server_ciphers off;
+
+ # 上传大小限制
+ client_max_body_size 100M;
+
+ location / {
+ proxy_pass http://localhost:3000;
+ proxy_http_version 1.1;
+ proxy_set_header Upgrade $http_upgrade;
+ proxy_set_header Connection 'upgrade';
+ proxy_set_header Host $host;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ proxy_cache_bypass $http_upgrade;
+
+ # WebSocket 支持
+ proxy_set_header Connection "upgrade";
+ proxy_set_header Upgrade $http_upgrade;
+
+ # 超时设置
+ proxy_connect_timeout 60s;
+ proxy_send_timeout 60s;
+ proxy_read_timeout 60s;
+ }
+
+ # 静态资源缓存
+ location ~* \.(jpg|jpeg|png|gif|webp|svg|css|js|ico|woff|woff2|ttf|eot)$ {
+ proxy_pass http://localhost:3000;
+ expires 1y;
+ add_header Cache-Control "public, immutable";
+ proxy_set_header Host $host;
+ }
+}
+```
+
+### Traefik
+
+如果您使用 Traefik 作为反向代理,可以在 `docker-compose.yml` 中添加标签:
+
+```yaml
+services:
+ chronoframe:
+ image: ghcr.io/hoshinosuzumi/chronoframe:latest
+ container_name: chronoframe
+ restart: unless-stopped
+ volumes:
+ - ./data:/app/data
+ env_file:
+ - .env
+ labels:
+ - "traefik.enable=true"
+ - "traefik.http.routers.chronoframe.rule=Host(`your-domain.com`)"
+ - "traefik.http.routers.chronoframe.entrypoints=websecure"
+ - "traefik.http.routers.chronoframe.tls.certresolver=letsencrypt"
+ - "traefik.http.services.chronoframe.loadbalancer.server.port=3000"
+ networks:
+ - traefik
+
+networks:
+ traefik:
+ external: true
+```
+
+## 常见问题
+
+:::details 如何生成随机的 `NUXT_SESSION_PASSWORD`?
+```bash
+# Linux / macOS
+openssl rand -base64 32
+
+# Windows (pwsh)
+[Convert]::ToBase64String((1..32|%{[byte](Get-Random -Max 256)}))
+```
+:::
+
+:::details 登录后台认证成功后,跳转到首页且仍为未登录状态?
+首先请确保不是直接通过 IP 地址和端口号访问。出于安全考虑,请通过配置的域名访问。
+
+如果出于某些原因,您执意要通过 IP 端口访问,请在配置项中添加:
+```env
+NUXT_ALLOW_INSECURE_COOKIE=true
+```
+:::
diff --git a/docs/zh/guide/storage-providers.md b/docs/zh/guide/storage-providers.md
new file mode 100644
index 00000000..fd406cbf
--- /dev/null
+++ b/docs/zh/guide/storage-providers.md
@@ -0,0 +1,152 @@
+# 存储提供器配置
+
+ChronoFrame 支持多种存储后端来保存您的照片和缩略图。本文档将详细介绍如何配置不同的存储提供器。
+
+| 提供器 | 支持 | 适用场景 | 成本 |
+| ---------------- | :------: | ------------------ | -------------- |
+| **S3 兼容** | ✅ | 生产环境 | 视服务商而定 |
+| **GitHub** | 🚧 | 小规模,版本控制 | 免费(有限制) |
+| **本地文件系统** | 🚧 | 测试环境,离线部署 | 免费 |
+
+## S3 兼容存储
+
+S3 兼容存储是最推荐的生产环境选项,支持所有主流云服务提供商。
+
+### 基础配置
+
+```env
+# 设置存储提供器为 S3
+NUXT_STORAGE_PROVIDER=s3
+
+# S3 基础配置
+NUXT_PROVIDER_S3_ENDPOINT=https://your-s3-endpoint.com
+NUXT_PROVIDER_S3_BUCKET=chronoframe-photos
+NUXT_PROVIDER_S3_REGION=us-east-1
+NUXT_PROVIDER_S3_ACCESS_KEY_ID=your-access-key-id
+NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=your-secret-access-key
+
+# 可选配置
+NUXT_PROVIDER_S3_PREFIX=photos/
+NUXT_PROVIDER_S3_CDN_URL=https://cdn.example.com
+```
+
+### 云服务商配置示例
+
+#### AWS S3
+
+```env
+NUXT_STORAGE_PROVIDER=s3
+NUXT_PROVIDER_S3_ENDPOINT=https://s3.amazonaws.com
+NUXT_PROVIDER_S3_BUCKET=my-chronoframe-bucket
+NUXT_PROVIDER_S3_REGION=us-east-1
+NUXT_PROVIDER_S3_ACCESS_KEY_ID=AKIA...
+NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=...
+NUXT_PROVIDER_S3_CDN_URL=https://d1234567890.cloudfront.net
+```
+
+#### Cloudflare R2
+
+```env
+NUXT_STORAGE_PROVIDER=s3
+NUXT_PROVIDER_S3_ENDPOINT=https://[account-id].r2.cloudflarestorage.com
+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_CDN_URL=https://photos.example.com
+```
+
+#### 阿里云 OSS
+
+```env
+NUXT_STORAGE_PROVIDER=s3
+NUXT_PROVIDER_S3_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
+NUXT_PROVIDER_S3_BUCKET=chronoframe-photos
+NUXT_PROVIDER_S3_REGION=oss-cn-hangzhou
+NUXT_PROVIDER_S3_ACCESS_KEY_ID=LTAI...
+NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=...
+NUXT_PROVIDER_S3_CDN_URL=https://cdn.example.com
+```
+
+#### 腾讯云 COS
+
+```env
+NUXT_STORAGE_PROVIDER=s3
+NUXT_PROVIDER_S3_ENDPOINT=https://cos.ap-beijing.myqcloud.com
+NUXT_PROVIDER_S3_BUCKET=chronoframe-1234567890
+NUXT_PROVIDER_S3_REGION=ap-beijing
+NUXT_PROVIDER_S3_ACCESS_KEY_ID=AKID...
+NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=...
+```
+
+#### MinIO 自托管
+
+```env
+NUXT_STORAGE_PROVIDER=s3
+NUXT_PROVIDER_S3_ENDPOINT=https://minio.example.com
+NUXT_PROVIDER_S3_BUCKET=chronoframe
+NUXT_PROVIDER_S3_REGION=us-east-1
+NUXT_PROVIDER_S3_ACCESS_KEY_ID=minioadmin
+NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=minioadmin
+```
+
+### 存储桶配置
+
+#### CORS 设置
+
+推荐的 CORS 配置:
+
+```json
+[
+ {
+ "AllowedOrigins": ["https://your-domain.com"],
+ "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],
+ "AllowedHeaders": ["*"],
+ "ExposeHeaders": ["ETag"],
+ "MaxAgeSeconds": 3000
+ }
+]
+```
+
+## GitHub 存储(开发中)
+
+GitHub 存储将照片存储在 Git 仓库中,适合小规模使用。
+
+```env
+# 设置存储提供器为 GitHub(暂未实现)
+NUXT_STORAGE_PROVIDER=github
+
+# GitHub 存储配置
+NUXT_PROVIDER_GITHUB_OWNER=your-username
+NUXT_PROVIDER_GITHUB_REPOSITORY=chronoframe-photos
+NUXT_PROVIDER_GITHUB_BRANCH=main
+NUXT_PROVIDER_GITHUB_PATH=photos
+NUXT_PROVIDER_GITHUB_TOKEN=ghp_...
+```
+
+## 本地文件系统(开发中)
+
+本地存储将文件保存在服务器文件系统中。
+
+```env
+# 设置存储提供器为本地(暂未实现)
+NUXT_STORAGE_PROVIDER=local
+
+# 本地存储配置
+NUXT_PROVIDER_LOCAL_PATH=/app/storage
+NUXT_PROVIDER_LOCAL_BASE_URL=https://your-domain.com/storage
+```
+
+## 常见问题
+
+:::details `The AWS Access Key Id you provided does not exist in our records`
+访问密钥错误,检查 `ACCESS_KEY_ID` 和 `SECRET_ACCESS_KEY` 是否正确。
+:::
+
+:::details `The specified bucket does not exist`
+存储桶不存在,确认存储桶名称正确,且在指定区域存在
+:::
+
+:::details 可以上传但无法访问图片,控制台提示 `Access to fetch at '...' from origin '...' has been blocked by CORS policy`
+存储桶 CORS 配置错误,参考 [CORS 设置](#CORS-设置) 进行配置。
+:::
diff --git a/docs/zh/guide/updates.md b/docs/zh/guide/updates.md
new file mode 100644
index 00000000..f2190d10
--- /dev/null
+++ b/docs/zh/guide/updates.md
@@ -0,0 +1,113 @@
+# 升级指南
+
+本文档将指导您如何安全地更新和升级 ChronoFrame 到最新版本。
+
+## 版本检查
+
+### 查看当前版本
+
+#### 通过 Web 界面
+1. 登录 ChronoFrame 管理后台
+2. 进入「仪表板」页面
+3. 查看「运行信息」面板中的版本号
+
+## 更新流程
+
+### 准备工作
+
+#### 1. 数据备份
+```bash
+# 停止服务
+docker-compose down
+
+# 创建完整备份
+ts=$(date +%Y%m%d-%H%M%S) && mkdir -p backups/$ts && cp -r data/ .env docker-compose.yml backups/$ts/
+```
+
+#### 2. 检查兼容性
+查看 [发布说明](https://github.com/HoshinoSuzumi/chronoframe/releases) 了解:
+- 破坏性变更
+- 新增环境变量
+- 功能弃用通知
+
+### Docker Compose 更新(推荐)
+
+#### 标准更新流程
+
+```bash
+# 1. 进入项目目录
+cd /path/to/chronoframe
+
+# 2. 备份当前配置
+cp docker-compose.yml docker-compose.yml.backup
+
+# 3. 停止当前服务
+docker-compose down
+
+# 4. 拉取最新镜像
+docker-compose pull
+
+# 5. 启动新版本
+docker-compose up -d
+
+# 6. 查看启动日志
+docker-compose logs -f chronoframe
+```
+
+#### 指定版本更新
+
+如果需要更新到特定版本:
+
+```yaml
+# docker-compose.yml
+services:
+ chronoframe:
+ image: ghcr.io/hoshinosuzumi/chronoframe:v1.2.3 # 指定版本
+ # ... 其他配置
+```
+
+```bash
+docker-compose up -d
+```
+
+### 单容器更新
+
+```bash
+# 停止现有容器
+docker stop chronoframe
+docker rm chronoframe
+
+# 拉取最新镜像
+docker pull ghcr.io/hoshinosuzumi/chronoframe:latest
+
+# 使用相同配置启动新容器
+docker run -d \
+ --name chronoframe \
+ -p 3000:3000 \
+ -v $(pwd)/data:/app/data \
+ --env-file .env \
+ ghcr.io/hoshinosuzumi/chronoframe:latest
+```
+
+## 数据库迁移
+
+### 自动迁移
+
+ChronoFrame 在启动时会自动执行数据库迁移:
+
+```bash
+# 查看迁移日志
+docker logs chronoframe | grep -i migration
+```
+
+### 手动迁移(高级)
+
+在特殊情况下,您可能需要手动执行迁移:
+
+```bash
+# 进入容器
+docker exec -it chronoframe sh
+
+# 执行迁移
+npx drizzle-kit migrate
+```
\ No newline at end of file
diff --git a/docs/zh/index.md b/docs/zh/index.md
index 9c43987a..6e848236 100644
--- a/docs/zh/index.md
+++ b/docs/zh/index.md
@@ -4,8 +4,8 @@ layout: home
hero:
name: "ChronoFrame"
- text: "自部署、在线管理的个人画廊"
- tagline: 镜头中藏匿记忆
+ text: "自部署个人画廊"
+ tagline: "在线管理照片,多存储后端、LivePhoto、地球仪视图"
actions:
- theme: brand
text: 快速开始
@@ -27,5 +27,29 @@ features:
- title: 灵活的存储方案
icon: 💾
details: 支持多种存储后端,包括兼容 S3 的存储、GitHub(开发中)和本地文件系统(开发中)。
+ - title: 智能地理位置
+ icon: 🌍
+ details: 自动提取照片 GPS 信息,使用 Mapbox 进行地理编码,在地图上展示照片拍摄位置。
+ - title: 响应式设计
+ icon: 📱
+ details: 完美适配桌面端和移动端,支持触摸操作和手势控制,提供原生应用般的体验。
+ - title: LivePhoto 支持
+ icon: 🎬
+ details: 完整支持 Apple LivePhoto 格式,自动检测和处理 MOV 视频文件,保留动态照片效果。
+
---
+## 🌍 演示站点
+
+下面是一些由开发者、社区成员搭建的,运行良好的 ChronoFrame 实例:
+
+- [**TimoYin's Mems**](https://lens.bh8.ga)
+
+## 💬 社区支持
+
+- **GitHub Issues**: [报告问题](https://github.com/HoshinoSuzumi/chronoframe/issues)
+- **GitHub Discussions**: [讨论分享](https://github.com/HoshinoSuzumi/chronoframe/discussions)
+
+## 📄 开源协议
+
+ChronoFrame 基于 [MIT 协议](https://github.com/HoshinoSuzumi/chronoframe/blob/main/LICENSE) 开源,欢迎自由使用和贡献。