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: 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.mdsimilarity index 100%rename from docs/develop/queue-api.mdrename to docs/.develop/queue-api.mddiff --git a/docs/develop/queue-task-api.md b/docs/.develop/queue-task-api.mdsimilarity index 100%rename from docs/develop/queue-task-api.mdrename to docs/.develop/queue-task-api.mddiff --git a/docs/develop/retry-mechanism.md b/docs/.develop/retry-mechanism.mdsimilarity index 100%rename from docs/develop/retry-mechanism.mdrename to docs/.develop/retry-mechanism.mddiff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.tsindex 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-confignav: [{ 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.mdnew file mode 100644index 00000000..14d3b15e--- /dev/null+++ b/docs/guide/api.md@@ -0,0 +1,3 @@+# API Documentation++🚧 WIPdiff --git a/docs/guide/configuration.md b/docs/guide/configuration.mdnew file mode 100644index 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 filediff --git a/docs/guide/contributing.md b/docs/guide/contributing.mdnew file mode 100644index 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 filediff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.mdindex 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```bashdocker 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 sloganNUXT_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```yamlservices:@@ -116,10 +126,130 @@ services:- .env```-Start the ChronoFrame instance:+#### 3. Start ChronoFrame Service```bash+# Start servicedocker 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 filediff --git a/docs/guide/storage-providers.md b/docs/guide/storage-providers.mdnew file mode 100644index 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 filediff --git a/docs/guide/updates.md b/docs/guide/updates.mdnew file mode 100644index 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 filediff --git a/docs/index.md b/docs/index.mdindex c90fcb57..3b2c18bc 100644--- a/docs/index.md+++ b/docs/index.md@@ -3,9 +3,9 @@layout: homehero:- 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: brandtext: Getting Started@@ -20,11 +20,36 @@ hero:features:- title: Powerful Photo Managementicon: 🖼️- 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 Deploymenticon: 🚀- 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 Solutionsicon: 💾- 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.tsindex 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-confignav: [{ 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.mdnew file mode 100644index 00000000..08ff383d--- /dev/null+++ b/docs/zh/guide/api.md@@ -0,0 +1,3 @@+# API 文档++🚧 WIPdiff --git a/docs/zh/guide/configuration.md b/docs/zh/guide/configuration.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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 实例:+#### 快速启动```bashdocker 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` 文件```yamlservices:@@ -116,8 +126,130 @@ services:- .env```-启动 ChronoFrame 实例+#### 3. 启动 ChronoFrame 服务```bash+# 启动服务+docker compose up -d++# 查看日志+docker compose logs -f chronoframe++# 停止服务+docker compose down++# 更新到最新版本+docker compose pulldocker 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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 filediff --git a/docs/zh/index.md b/docs/zh/index.mdindex 9c43987a..6e848236 100644--- a/docs/zh/index.md+++ b/docs/zh/index.md@@ -4,8 +4,8 @@ layout: homehero:name: "ChronoFrame"- text: "自部署、在线管理的个人画廊"- tagline: 镜头中藏匿记忆+ text: "自部署个人画廊"+ tagline: "在线管理照片,多存储后端、LivePhoto、地球仪视图"actions:- theme: brandtext: 快速开始@@ -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) 开源,欢迎自由使用和贡献。