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: refresh documentation for ChronoFrame 1.0.0
Timothy Yin912d7f2ecce4
diff --git a/.env.example b/.env.exampleindex 0da80cee..a86285bc 100644--- a/.env.example+++ b/.env.example@@ -1,4 +1,8 @@-# Admin user email (required)+# Legacy bootstrap defaults: optional with the 1.0 setup wizard.+# Most site, storage and map settings are now managed in the dashboard.+# Copy only deployment options you need; a new Docker deployment needs no .env.++# Admin email (optional wizard default)CFRAME_ADMIN_EMAIL=# Admin user name (default to Chronoframe, optional)CFRAME_ADMIN_NAME=@@ -60,7 +64,8 @@ NUXT_PROVIDER_OPENLIST_ENDPOINT_META=/api/fs/getNUXT_PROVIDER_OPENLIST_PATH_FIELD=pathNUXT_PROVIDER_OPENLIST_CDN_URL=-# Session password for encrypting session data, 32 characters long+# Optional session secret override (at least 32 characters).+# Otherwise generated automatically and persisted in data/.session-password.NUXT_SESSION_PASSWORD=# Set to true only when ChronoFrame is reachable exclusively through a trusted reverse proxy.# The proxy must replace untrusted X-Forwarded-For headers with the client IP.diff --git a/README.md b/README.mdindex 098701a4..653417b6 100644--- a/README.md+++ b/README.md@@ -8,8 +8,8 @@<a href="https://github.com/HoshinoSuzumi/chronoframe/releases/latest"><img src="https://badgen.net/github/release/HoshinoSuzumi/chronoframe/stable?icon=docker&label=stable" alt="Latest Release"></a>- <a href="https://github.com/HoshinoSuzumi/chronoframe/releases?q=beta&expanded=false">- <img src="https://badgen.net/github/release/HoshinoSuzumi/chronoframe?icon=docker&label=nightly" alt="Latest Nightly Release">+ <a href="https://github.com/HoshinoSuzumi/chronoframe/releases">+ <img src="https://badgen.net/github/release/HoshinoSuzumi/chronoframe?icon=docker&label=prerelease" alt="Latest Prerelease"></a><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License"></p>@@ -27,103 +27,24 @@**Languages:** English | [中文](README_zh.md)-A smooth photo display and management application, supporting multiple image formats and large-size image rendering.+ChronoFrame is a self-hosted photo gallery. Upload your photos and it extracts EXIF, creates previews and identifies shooting locations. Visitors can browse by time, album or map, zoom into large images and play Live Photos.-[Live Demo: TimoYin's Mems](https://lens.bh8.ga)+[Live demo](https://lens.bh8.ga) · [Documentation](https://chronoframe.bh8.ga/) · [Changelog](https://chronoframe.bh8.ga/changelog)## ✨ Features-### 🖼️ Powerful Photo Management--- **Manage photos online** - Easily manage and browse photos via the web interface-- **Explore map** - Browse photo locations on a map-- **Smart EXIF parsing** - Automatically extracts metadata such as capture time, geolocation, and camera parameters-- **Reverse geocoding** - Automatically identifies photo shooting locations-- **Multi-format support** - Supports mainstream formats including JPEG, PNG, HEIC/HEIF-- **Smart thumbnails** - Efficient thumbnail generation using ThumbHash--### 🔧 Modern Tech Stack--- **Nuxt 4** - Built on the latest Nuxt framework with SSR/SSG support-- **TypeScript** - Full type safety-- **TailwindCSS** - Modern CSS framework-- **Drizzle ORM** - Type-safe database ORM--### ☁️ Flexible Storage Solutions--- **Multiple storage backends** - Supports S3-compatible storage, local filesystem-- **CDN acceleration** - Configurable CDN URL for faster photo delivery+- **Photo browsing**: masonry layout, filters and sorting, WebGL zoom and tiled rendering, histograms, original downloads and share previews.+- **Live and Motion Photos**: automatic image/video pairing, with hover or long-press playback.+- **Albums**: organize and reorder albums and photos, hide albums or protect them with passwords.+- **Dashboard**: batch uploads, metadata and rating editing, batch downloads and reindexing; task queues, live logs and recent activity.+- **Storage**: local files, S3-compatible services and OpenList, with storage schemes and CDN URLs managed in the dashboard.+- **Maps and locations**: MapLibre / Mapbox maps, reverse geocoding and a choice of place-name language.+- **Setup wizard**: create an administrator and configure your site and storage in the browser. Manage everyday settings in the dashboard.+- **Languages and login**: dashboard language switching, email/password login and optional GitHub OAuth, custom analytics scripts and upload privacy settings.## 🐳 Deployment-We recommend deploying with the prebuilt Docker image. [View the image on ghcr](https://github.com/HoshinoSuzumi/chronoframe/pkgs/container/chronoframe)--Create a `.env` file and configure environment variables.--Below is a **minimal configuration** example. For complete configuration options, see [Configuration Guide](https://chronoframe.bh8.ga/guide/configuration.html):--```bash-# Admin email (required)-CFRAME_ADMIN_EMAIL=-# Admin username (optional, default Chronoframe)-CFRAME_ADMIN_NAME=-# Admin password (optional, default CF1234@!)-CFRAME_ADMIN_PASSWORD=--# Site metadata (all optional)-NUXT_PUBLIC_APP_TITLE=-NUXT_PUBLIC_APP_SLOGAN=-NUXT_PUBLIC_APP_AUTHOR=-NUXT_PUBLIC_APP_AVATAR_URL=--# Map provider (maplibre/mapbox)-NUXT_PUBLIC_MAP_PROVIDER=maplibre-# MapTiler access token for MapLibre-NUXT_PUBLIC_MAP_MAPLIBRE_TOKEN=-# Mapbox access token for Mapbox-NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=--# Mapbox unrestricted token (optional, reverse geocoding)-NUXT_MAPBOX_ACCESS_TOKEN=--# Storage provider (local, s3 or openlist)-NUXT_STORAGE_PROVIDER=local-NUXT_PROVIDER_LOCAL_PATH=/app/data/storage--# Session password (32‑char random string, required)-NUXT_SESSION_PASSWORD=-# Secret key for stable signing og images-# Use: npx nuxt-og-image generate-secret-NUXT_OG_IMAGE_SECRET=-```--### Pull Image--Use the published image on GitHub Container Registry and Docker Hub. Choose the source that works best for your network:--#### [GitHub Container Registry (GHCR)](https://github.com/HoshinoSuzumi/chronoframe/pkgs/container/chronoframe)--```bash-docker pull ghcr.io/hoshinosuzumi/chronoframe:latest-```--#### [Docker Hub](https://hub.docker.com/r/hoshinosuzumi/chronoframe)--```bash-docker pull hoshinosuzumi/chronoframe:latest-```--### Docker--Run with customized environment variables:--```bash-docker run -d --name chronoframe -p 3000:3000 -v $(pwd)/data:/app/data --env-file .env ghcr.io/hoshinosuzumi/chronoframe:latest-```--### Docker Compose--Create docker-compose.yml:+Docker is the recommended option. Create `docker-compose.yml`:```yamlservices:@@ -135,32 +56,35 @@ services:- '3000:3000'volumes:- ./data:/app/data- env_file:- - .env```-Start:-```bashdocker compose up -d```-## 📖 User Guide+You can also use `hoshinosuzumi/chronoframe:latest` from Docker Hub. Replace the tag with `v1.0.0` to pin the version.-> If `CFRAME_ADMIN_EMAIL` and `CFRAME_ADMIN_PASSWORD` are not set, the default admin account is:->-> - Email: `[email protected]`-> - Password: `CF1234@!`+To run directly with Docker:++```bash+docker run -d --name chronoframe --restart unless-stopped \+ -p 3000:3000 -v "$(pwd)/data:/app/data" \+ ghcr.io/hoshinosuzumi/chronoframe:latest+```-### Logging into the Dashboard+Open `http://localhost:3000` and use the setup wizard to create your administrator and choose storage. For local storage, enter `/app/data/storage`. You can add a map token later and start uploading photos first.-1. Click avatar to sign in with GitHub OAuth or use email/password login+Keep the `./data` mount: it holds the database, settings, session secret and local photos when using the path above.-### Uploading Photos+Use HTTPS for a public deployment. See [Getting Started](https://chronoframe.bh8.ga/guide/getting-started) and the [update guide](https://chronoframe.bh8.ga/guide/updates) for proxies, backups and migration from older versions.-1. Go to the dashboard at /dashboard-2. On the Photos page, select and upload images (supports batch & drag-and-drop)-3. System will automatically parse EXIF data, generate thumbnails, and perform reverse geocoding+## 📖 Usage++Sign in and open `/dashboard` to upload and organize photos. After upload, the task queue processes EXIF, thumbnails, locations and Live Photos. Failed tasks show an error and can be retried.++For Apple Live Photos, the image and MOV must share a filename, such as `IMG_1234.heic` and `IMG_1234.mov`; either can be uploaded first. Image formats include JPEG, PNG, WebP, GIF, BMP, TIFF and HEIC / HEIF.++Album passwords control access through ChronoFrame. If S3, OpenList or a CDN exposes public image URLs, manage access in that service too. Read [Using ChronoFrame](https://chronoframe.bh8.ga/guide/usage) for details.## 📸 Screenshots@@ -171,161 +95,35 @@ docker compose up -d## 🛠️ Development-### Requirements--- Node.js 18+-- pnpm 9.0+--### Install dependencies--```bash-# With pnpm (recommended)-pnpm install--# Or with other package managers-npm install-yarn install-```--### Configure environment variables--```bash-cp .env.example .env-```--### Initialize database--```bash-# 2. Generate migration files (optional)-pnpm db:generate--# 3. Run database migrations-pnpm db:migrate-```--### Start development server+Use Node.js 22 and the project's pinned pnpm 10.34.1:```bash+corepack enable+pnpm install --frozen-lockfilepnpm dev```-App will start at http://localhost:3000.--### Project Structure--```-chronoframe/-├── app/ # Nuxt app-│ ├── components/ # Components-│ ├── pages/ # Page routes-│ ├── composables/ # Composables-│ └── stores/ # Pinia stores-├── packages/-│ └── webgl-image/ # WebGL image viewer-├── server/-│ ├── api/ # API routes-│ ├── database/ # DB schema & migrations-│ └── services/ # Business logic services-└── shared/ # Shared types & utils-```--### Build commands+Open `http://localhost:3000` and complete local setup in the wizard. Use `./data/storage` for local development storage.```bash-# Development (with dependencies build)-pnpm dev+pnpm lint # Oxlint+pnpm fmt:check # Oxfmt+pnpm build:deps # Build the WebGL package+pnpm build # Build the application+pnpm docs:build # Build documentation+```-# Build only dependencies-pnpm build:deps+After changing the database schema, run `pnpm db:generate` and review the SQL. Generating migrations is unnecessary just to start the app. See the [contributing guide](https://chronoframe.bh8.ga/development/contributing) for more.-# Production build-pnpm build+## 🤝 Contributing and community-# Database operations-pnpm db:generate # Generate migration files-pnpm db:migrate # Run migrations+Issues and pull requests are welcome. Explain the problem, resulting behavior and verification. Keep English and Chinese documentation in sync.-# Preview production build-pnpm preview-```--## 🤝 Contributing--Contributions are welcome! Please:--1. Fork the repo-2. Create a feature branch (git checkout -b feature/amazing-feature)-3. Commit changes (git commit -m 'Add some amazing feature')-4. Push to branch (git push origin feature/amazing-feature)-5. Open a Pull Request--### Coding Guidelines--- Use TypeScript for type safety-- Follow ESLint and Prettier conventions-- Update documentation accordingly--## 📄 License--This project is licensed under the MIT License.--## 👤 Author--**Timothy Yin**--- Email: [email protected]-- GitHub: @HoshinoSuzumi-- Website: bh8.ga-- Gallery: lens.bh8.ga--## ❓ FAQ--<details>- <summary>How is the admin user created?</summary>- <p>- On first startup, an admin user is created based on <code>CFRAME_ADMIN_EMAIL</code>, <code>CFRAME_ADMIN_NAME</code>, and <code>CFRAME_ADMIN_PASSWORD</code>. The email must match your GitHub account email used for login.- </p>-</details>-<details>- <summary>Which image formats are supported?</summary>- <p>- Supported formats: JPEG, PNG, HEIC/HEIF, MOV (for Live Photos).- </p>-</details>-<details>- <summary>Why can’t I use GitHub/Local storage?</summary>- <p>- Currently only S3-compatible storage is supported. GitHub and local storage support is planned.- </p>-</details>-<details>- <summary>Why is a map service required and how to configure it?</summary>- <p>- The map is used to browse photo locations and render mini-maps in photo details. Currently Mapbox is used. After registering, <a href="https://console.mapbox.com/account/access-tokens/">get an access token</a> and set it to the <code>MAPBOX_TOKEN</code> variable.- </p>-</details>-<details>- <summary>Why wasn’t my MOV file recognized as a Live Photo?</summary>- <p>- Ensure the image (.heic) and video (.mov) share the same filename (e.g., <code>IMG_1234.heic</code> and <code>IMG_1234.mov</code>). Upload order does not matter. If not recognized, you can trigger pairing manually from the dashboard.- </p>-</details>-<details>- <summary>How do I import existing photos from storage?</summary>- <p>- Direct import of existing photos is not yet supported. A directory scanning import feature is planned.- </p>-</details>+[GitHub Issues](https://github.com/HoshinoSuzumi/chronoframe/issues/new/choose) · [Discussions](https://github.com/HoshinoSuzumi/chronoframe/discussions) · [Discord](https://discord.gg/MM4ZK4Ed7s)## 🙏 Acknowledgements-This project was inspired by Afilmory, another excellent personal gallery project.--Thanks to the following open-source projects and libraries:--- [Nuxt](https://nuxt.com/)-- [TailwindCSS](https://tailwindcss.com/)-- [Drizzle ORM](https://orm.drizzle.team/)+Thanks to the maintainers of [Nuxt](https://nuxt.com/), [Vue](https://vuejs.org/), [Tailwind CSS](https://tailwindcss.com/), [Drizzle ORM](https://orm.drizzle.team/) and other open-source dependencies, and everyone contributing testing, translations and code.## ⭐️ Star Historydiff --git a/README_zh.md b/README_zh.mdindex a0d6a8d0..b5aa263f 100644--- a/README_zh.md+++ b/README_zh.md@@ -8,8 +8,8 @@<a href="https://github.com/HoshinoSuzumi/chronoframe/releases/latest"><img src="https://badgen.net/github/release/HoshinoSuzumi/chronoframe/stable?icon=docker&label=稳定" alt="Latest Release"></a>- <a href="https://github.com/HoshinoSuzumi/chronoframe/releases?q=beta&expanded=false">- <img src="https://badgen.net/github/release/HoshinoSuzumi/chronoframe?icon=docker&label=测试" alt="Latest Nightly Release">+ <a href="https://github.com/HoshinoSuzumi/chronoframe/releases">+ <img src="https://badgen.net/github/release/HoshinoSuzumi/chronoframe?icon=docker&label=测试" alt="Latest Prerelease"></a><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License"></p>@@ -27,103 +27,24 @@**Languages:** [English](README.md) | 中文-丝滑的照片展示和管理应用,支持多种图片格式和大尺寸图片渲染。+ChronoFrame 是一个可以自行部署的照片画廊。上传照片后,应用会提取 EXIF、生成预览并整理拍摄地点;访客可以按时间、相册或地图浏览,也能查看大图和播放实况照片。-[在线演示: TimoYin's Mems](https://lens.bh8.ga)+[在线演示](https://lens.bh8.ga) · [使用文档](https://chronoframe.bh8.ga/zh/) · [更新日志](https://chronoframe.bh8.ga/zh/changelog)-## ✨ 特性+## ✨ 功能-### 🖼️ 强大的图片管理--- **在线管理照片** - 通过 Web 界面轻松管理和浏览照片-- **探索地图** - 在地图上浏览照片拍摄位置-- **智能 EXIF 解析** - 自动提取拍摄时间、地理位置、相机参数等元数据-- **地理位置识别** - 自动识别(Reverse Geocoding)照片拍摄地点-- **多格式支持** - 支持 JPEG、PNG、HEIC/HEIF 等主流图片格式-- **智能缩略图** - 基于 ThumbHash 技术的高效缩略图生成--### 🔧 现代技术栈--- **Nuxt 4** - 基于最新的 Nuxt 框架,提供 SSR/SSG 支持-- **TypeScript** - 完整的类型安全保障-- **TailwindCSS** - 现代化的 CSS 框架-- **Drizzle ORM** - 类型安全的数据库 ORM--### ☁️ 灵活的存储方案--- **多存储后端** - 支持 S3 兼容存储、本地文件系统-- **CDN 加速** - 可配置 CDN 地址加速图片访问+- **照片浏览**:瀑布流、筛选与排序、WebGL 大图缩放和分块渲染、照片直方图、原图下载与分享预览。+- **动态照片**:支持 Apple Live Photo 和 Motion Photo,照片与视频自动配对,支持悬停或长按播放。+- **相册**:组织照片、调整相册及照片顺序,支持隐藏相册和密码相册。+- **后台管理**:批量上传、编辑元数据、评分、批量下载和重新索引;查看处理队列、实时日志与最近活动。+- **存储**:支持本地文件系统、S3 兼容对象存储和 OpenList,可在后台管理存储方案和 CDN 地址。+- **地图与地点**:MapLibre / Mapbox 地图,反向地理编码和可选的地名语言。+- **设置向导**:首次启动在网页中创建管理员、设置站点与存储;日常设置在后台修改,无需维护一长串环境变量。+- **多语言与登录**:后台语言切换,邮箱密码登录,可选 GitHub OAuth;支持自定义统计脚本和上传隐私设置。## 🐳 部署-推荐使用预构建的 docker 镜像部署,[在 ghcr 上查看镜像](https://github.com/HoshinoSuzumi/chronoframe/pkgs/container/chronoframe)--创建 `.env` 文件并配置。--下面是**最小化配置**示例,完整的配置项参考 [配置指南](https://chronoframe.bh8.ga/zh/guide/configuration.html):--```bash-# 管理员邮箱(必须)-CFRAME_ADMIN_EMAIL=-# 管理员用户名(可选,默认 ChronoFrame)-CFRAME_ADMIN_NAME=-# 管理员密码(可选,默认 CF1234@!)-CFRAME_ADMIN_PASSWORD=--# 站点信息(均可选)-NUXT_PUBLIC_APP_TITLE=-NUXT_PUBLIC_APP_SLOGAN=-NUXT_PUBLIC_APP_AUTHOR=-NUXT_PUBLIC_APP_AVATAR_URL=--# 地图提供器 (maplibre/mapbox)-NUXT_PUBLIC_MAP_PROVIDER=maplibre-# 使用 MapLibre 需要 MapTiler 访问令牌-NUXT_PUBLIC_MAP_MAPLIBRE_TOKEN=-# 使用 Mapbox 需要 Mapbox 访问令牌-NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=--# Mapbox 无域名限制令牌(反向地理编码,可选)-NUXT_MAPBOX_ACCESS_TOKEN=--# 存储提供者(local、s3 或 openlist)-NUXT_STORAGE_PROVIDER=local-NUXT_PROVIDER_LOCAL_PATH=/app/data/storage--# 会话密码(必须,32 位随机字符串)-NUXT_SESSION_PASSWORD=-# 用于稳定签名 OG 图片的密钥-# 使用命令生成:npx nuxt-og-image generate-secret-NUXT_OG_IMAGE_SECRET=-```--### 拉取镜像--我们推荐使用预构建的 Docker 镜像进行部署,镜像托管在 GHCR 和 Docker Hub,您可以根据网络情况选择合适的源。--#### [GitHub Container Registry (GHCR)](https://github.com/HoshinoSuzumi/chronoframe/pkgs/container/chronoframe)--```bash-docker pull ghcr.io/hoshinosuzumi/chronoframe:latest-```--#### [Docker Hub](https://hub.docker.com/r/hoshinosuzumi/chronoframe)--```bash-docker pull hoshinosuzumi/chronoframe:latest-```--### Docker--一行命令启动:--```bash-docker run -d --name chronoframe -p 3000:3000 -v $(pwd)/data:/app/data --env-file .env ghcr.io/hoshinosuzumi/chronoframe:latest-```--### Docker Compose--创建 `docker-compose.yml`:+推荐使用 Docker。创建 `docker-compose.yml`:```yamlservices:@@ -135,32 +56,35 @@ services:- '3000:3000'volumes:- ./data:/app/data- env_file:- - .env```-启动:-```bashdocker compose up -d```-## 📖 使用指南+也可以使用 Docker Hub 镜像 `hoshinosuzumi/chronoframe:latest`。需要固定版本时,将标签换成 `v1.0.0`。++直接使用 Docker 启动:++```bash+docker run -d --name chronoframe --restart unless-stopped \+ -p 3000:3000 -v "$(pwd)/data:/app/data" \+ ghcr.io/hoshinosuzumi/chronoframe:latest+```++打开 `http://localhost:3000`,按设置向导创建管理员并选择存储。使用本地存储时填写 `/app/data/storage`。地图令牌可以稍后补充,不影响先完成部署和上传照片。-> 如未配置 `CFRAME_ADMIN_EMAIL` 和 `CFRAME_ADMIN_PASSWORD`,默认账号如下:->-> - 邮箱: `[email protected]`-> - 密码: `CF1234@!`+请保留 `./data` 挂载,其中包含数据库、设置、会话密钥,以及采用上述路径时的本地照片。-### 登录到控制台+部署到公网时使用 HTTPS。反向代理、数据备份和旧版迁移见[快速开始](https://chronoframe.bh8.ga/zh/guide/getting-started)和[升级指南](https://chronoframe.bh8.ga/zh/guide/updates)。-1. 点击头像跳转到登录页面,可以使用账号密码或 GitHub 登录+## 📖 使用-### 上传照片+登录后进入 `/dashboard` 上传和整理照片。上传完成后,任务队列会继续处理 EXIF、缩略图、地点和实况照片,失败任务可以查看原因并重试。-1. 访问仪表板页面 `/dashboard`-2. 在 `Photos` 页面中选择图片并点击上传(支持批量上传和拖拽上传)-3. 系统将自动提取 EXIF 信息、生成缩略图并逆编码照片地理位置+Apple Live Photo 的图片和 MOV 文件需要相同文件名,例如 `IMG_1234.heic` 和 `IMG_1234.mov`,上传顺序不限。照片支持 JPEG、PNG、WebP、GIF、BMP、TIFF、HEIC / HEIF 等格式。++密码相册限制的是通过 ChronoFrame 访问的内容。如果 S3、OpenList 或 CDN 提供公开的图片直链,需要同时管理外部服务的权限。详见[日常使用](https://chronoframe.bh8.ga/zh/guide/usage)。## 📸 截图@@ -171,165 +95,35 @@ docker compose up -d## 🛠️ 开发-### 环境要求--- Node.js 18+-- pnpm 9.0+--### 安装依赖--```bash-# 使用 pnpm (推荐)-pnpm install--# 或使用其他包管理器-npm install-yarn install-```--### 配置环境变量--复制环境变量模板并根据需要配置:--```bash-cp .env.example .env-```--### 数据库初始化--```bash-# 2. 生成数据库迁移文件(可选)-pnpm db:generate--# 3. 执行数据库迁移-pnpm db:migrate-```--### 启动开发服务器+使用 Node.js 22 和项目指定的 pnpm 10.34.1:```bash+corepack enable+pnpm install --frozen-lockfilepnpm dev```-应用将在 `http://localhost:3000` 启动。--### 项目结构--```-chronoframe/-├── app/ # Nuxt 应用-│ ├── components/ # 组件-│ ├── pages/ # 页面路由-│ ├── composables/ # 组合式函数-│ └── stores/ # Pinia 状态管理-├── packages/-│ └── webgl-image/ # WebGL 图片查看器-├── server/-│ ├── api/ # API 路由-│ ├── database/ # 数据库 schema 和迁移-│ └── services/ # 业务逻辑服务-└── shared/ # 共享类型和工具-```--### 构建命令+打开 `http://localhost:3000`,通过向导完成本地初始化。本地存储可以使用 `./data/storage`。```bash-# 开发模式 (包含依赖包构建)-pnpm dev+pnpm lint # Oxlint+pnpm fmt:check # Oxfmt+pnpm build:deps # 构建 WebGL 包+pnpm build # 构建应用+pnpm docs:build # 构建文档+```-# 仅构建依赖包-pnpm build:deps+修改数据库 schema 后,使用 `pnpm db:generate` 生成迁移并检查 SQL。仅启动项目时无需生成迁移。更多说明见[贡献指南](https://chronoframe.bh8.ga/zh/development/contributing)。-# 构建生产版本-pnpm build+## 🤝 贡献与交流-# 数据库操作-pnpm db:generate # 生成迁移文件-pnpm db:migrate # 执行迁移+欢迎提交问题和 Pull Request。请说明问题、改动后的行为和验证结果;文档改动请同步维护中文和英文。-# 预览生产版本-pnpm preview-```--## 🤝 贡献--欢迎贡献代码!请确保:--1. Fork 本仓库-2. 创建功能分支 (`git checkout -b feature/amazing-feature`)-3. 提交更改 (`git commit -m 'Add some amazing feature'`)-4. 推送到分支 (`git push origin feature/amazing-feature`)-5. 开启 Pull Request--### 开发规范--- 使用 TypeScript 进行类型安全的开发-- 遵循 ESLint 和 Prettier 代码规范-- 更新相关文档--## 📄 许可证--本项目基于 [MIT 许可证](LICENSE) 开源。--## 👤 作者--**Timothy Yin**--- Email: [email protected]-- GitHub: [@HoshinoSuzumi](https://github.com/HoshinoSuzumi)-- Website: [bh8.ga](https://bh8.ga)-- Gallery: [lens.bh8.ga](https://lens.bh8.ga)--## ❓ FAQ--<details>- <summary>如何创建管理员用户?</summary>- <p>- 首次启动时,会根据环境变量 <code>CFRAME_ADMIN_EMAIL</code>、<code>CFRAME_ADMIN_NAME</code> 和 <code>CFRAME_ADMIN_PASSWORD</code> 环境变量创建一个管理员用户。<code>CFRAME_ADMIN_EMAIL</code> 必须是登录使用的 GitHub 账户的邮箱。- </p>-</details>-<details>- <summary>支持哪些图片格式?</summary>- <p>- 支持 JPEG、PNG、HEIC/HEIF、MOV(作为实况照片) 格式。- </p>-</details>-<details>- <summary>为什么无法使用 GitHub/Local 存储?</summary>- <p>- 目前支持 S3 兼容存储,未来计划支持 GitHub 和本地文件系统存储。- </p>-</details>-<details>- <summary>为什么需要/如何配置地图服务?</summary>- <p>- 地图服务用于在地图上浏览照片拍摄位置,以及照片详情中的小地图渲染。目前使用 Mapbox,注册后<a href="https://console.mapbox.com/account/access-tokens/">获取访问令牌</a>并配置到 <code>MAPBOX_TOKEN</code> 环境变量中。- </p>-</details>-<details>- <summary>为什么我上传的 MOV 文件没有被识别为实况照片?</summary>- <p>- 需要确保实况照片对的图片(.heic)和视频(.mov)的文件名一致(例如 <code>IMG_1234.heic</code> 与 <code>IMG_1234.mov</code> 会自动匹配)。- 一般情况来说,不管是上传 .heic 还是 .mov,都会检测一次配对,因此上传的顺序无关紧要。- 如果仍然没有被识别为实况照片,请在仪表盘中找到图片,在操作菜单中手动触发配对检测。- </p>-</details>-<details>- <summary>如何导入存储中已有的照片?</summary>- <p>- 目前不支持直接导入已有照片,未来计划支持通过指定目录扫描导入。- </p>-</details>+[GitHub Issues](https://github.com/HoshinoSuzumi/chronoframe/issues/new/choose) · [Discussions](https://github.com/HoshinoSuzumi/chronoframe/discussions) · [Discord](https://discord.gg/MM4ZK4Ed7s)## 🙏 致谢-本项目受启发于 Afilmory,同样优秀的个人相册项目。--感谢以下优秀的开源项目和库:--- [Nuxt](https://nuxt.com/)-- [TailwindCSS](https://tailwindcss.com/)-- [Drizzle ORM](https://orm.drizzle.team/)+感谢 [Nuxt](https://nuxt.com/)、[Vue](https://vuejs.org/)、[Tailwind CSS](https://tailwindcss.com/)、[Drizzle ORM](https://orm.drizzle.team/) 及其他开源项目的维护者,也感谢参与测试、翻译和开发的贡献者。## ⭐️ Star Historydiff --git a/docker-compose.yml b/docker-compose.ymlindex c5e3869b..a6667b9e 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -8,19 +8,4 @@ services:volumes:- ./data:/app/dataenv_file:- - .env-- # database:- # image: postgres:15-alpine- # container_name: chronoframe_db- # environment:- # POSTGRES_DB: chronoframe- # POSTGRES_USER: chronoframe- # POSTGRES_PASSWORD: your-password- # volumes:- # - postgres_data:/var/lib/postgresql/data- # ports:- # - "5432:5432"--# volumes:-# postgres_data:+ - .envdiff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.tsindex 36cfbb50..c7bd3d0b 100644--- a/docs/.vitepress/config.ts+++ b/docs/.vitepress/config.ts@@ -1,4 +1,5 @@import { defineConfig } from 'vitepress'+import zhConfig from '../zh/config'// https://vitepress.dev/reference/site-configexport default defineConfig({@@ -32,11 +33,13 @@ export default defineConfig({],lastUpdated: true,themeConfig: {+ logo: { src: '/logo.png', alt: 'ChronoFrame' },// https://vitepress.dev/reference/default-theme-confignav: [{ text: 'Guide', link: '/guide/getting-started' },{ text: 'Development', link: '/development/contributing' },- { text: 'Demo', link: 'https://lens.bh8.ga' },+ { text: 'Changelog', link: '/changelog' },+ { text: 'Demo Sites', link: '/demo-sites' },],sidebar: [@@ -44,31 +47,25 @@ export default defineConfig({text: 'Guide',items: [{ text: 'Getting Started', link: '/guide/getting-started' },- { text: 'Configuration', link: '/guide/configuration' },+ { text: 'Using ChronoFrame', link: '/guide/usage' },{ text: 'Update Guide', link: '/guide/updates' },- ],- },- {- text: 'Configuration',- items: [- {- text: 'Storage Providers',- link: '/configuration/storage-providers',- },- { text: 'Map Providers', link: '/configuration/map-providers' },- {- text: 'Location Providers',- link: '/configuration/location-providers',- },+ { text: 'Changelog', link: '/changelog' },+ { text: 'Demo Sites', link: '/demo-sites' },],},{text: 'Development',items: [- { text: 'Contributing Guide', link: '/development/contributing' },+ { text: 'Contributing', link: '/development/contributing' },{ text: 'API Documentation', link: '/development/api' },+ { text: 'Adding a Setting', link: '/development/how-to-add-setting' },],},+ {+ text: 'Legacy',+ collapsed: true,+ items: [{ text: 'Archived documentation', link: '/legacy/' }],+ },],socialLinks: [@@ -100,6 +97,7 @@ export default defineConfig({label: '简体中文',lang: 'zh',link: '/zh/',+ themeConfig: zhConfig.themeConfig,},},diff --git a/docs/.vitepress/theme/components/DemoSites.vue b/docs/.vitepress/theme/components/DemoSites.vuenew file mode 100644index 00000000..eb21ec37--- /dev/null+++ b/docs/.vitepress/theme/components/DemoSites.vue@@ -0,0 +1,184 @@+<script setup lang="ts">+import { computed } from 'vue'+import { useData } from 'vitepress'++const props = defineProps<{ group: 'developers' | 'community' }>()+const { lang } = useData()+const isChinese = computed(() => lang.value.startsWith('zh'))++const sites = {+ developers: [+ {+ name: "TimoYin's Mems",+ url: 'https://lens.bh8.ga',+ author: 'Timothy Yin',+ },+ {+ name: "Ahmet Ömer's Photography",+ url: 'https://photography.ahmeto.com/',+ author: 'Ahmet Ömer',+ },+ ],+ community: [+ {+ name: '懒洋洋喝咖啡',+ url: 'https://oreo.tanmantang.com',+ description: '用镜头记录每个精彩瞬间',+ },+ { name: 'My Photo Gallery', url: 'https://photo.fivk.cn' },+ {+ name: 'An ISFP Conductor of Current, Pixels, and Code.',+ url: 'https://gallery.xiaoten.com',+ },+ {+ name: '我的旅行相册',+ url: 'https://gallery.junlan.site',+ description: '记录光影,留存回忆',+ },+ {+ name: "Z.Zhou's Photography",+ url: 'https://photography.zzhou612.com/',+ description: 'Catch the Moment',+ },+ {+ name: 'Each Photo Turns a Moment Into Eternity.',+ url: 'https://eachphoto.com',+ },+ { name: 'WhyPhoto', url: 'https://photo.limina.top/' },+ { name: '用图片记录生活', url: 'https://gallery.d.cr' },+ { name: '何来尘埃飞舞', url: 'https://photo.jefftay.com/' },+ ],+}++const cards = computed(() =>+ sites[props.group].map((site) => ({+ ...site,+ host: new URL(site.url).hostname,+ author: 'author' in site ? site.author : '',+ description: 'description' in site ? site.description : '',+ })),+)+</script>++<template>+ <div class="demo-grid">+ <a+ v-for="site in cards"+ :key="site.url"+ class="demo-card"+ :href="site.url"+ target="_blank"+ rel="noopener noreferrer"+ >+ <span class="demo-content">+ <span class="demo-heading">+ <span class="demo-name">{{ site.name }}</span>+ <span+ v-if="site.description"+ class="demo-detail"+ >{{ site.description }}</span+ >+ </span>+ <span class="demo-host">+ <template v-if="site.author">{{ site.author }} · </template+ >{{ site.host }}+ </span>+ </span>+ <span class="demo-visit">+ {{ isChinese ? '访问站点' : 'Visit gallery' }}+ <span aria-hidden="true">↗</span>+ <span class="sr-only">{{+ isChinese ? '(在新窗口打开)' : ' (opens in a new window)'+ }}</span>+ </span>+ </a>+ </div>+</template>++<style scoped>+.demo-grid {+ display: grid;+ grid-template-columns: repeat(2, minmax(0, 1fr));+ gap: 16px;+ margin: 24px 0 32px;+}++.demo-card {+ display: flex;+ flex-direction: column;+ align-items: flex-start;+ gap: 10px;+ min-width: 0;+ padding: 12px 16px;+ border: 1px solid var(--vp-c-divider);+ border-radius: 12px;+ background: var(--vp-c-bg-soft);+ color: var(--vp-c-text-1);+ text-decoration: none;+ transition:+ border-color 0.2s,+ background-color 0.2s;+}++.demo-card:hover,+.demo-card:focus-visible {+ border-color: var(--vp-c-brand-1);+ background: var(--vp-c-bg-alt);+}++.demo-card:focus-visible {+ outline: 2px solid var(--vp-c-brand-1);+ outline-offset: 3px;+}++.demo-content,+.demo-heading {+ display: flex;+ flex-direction: column;+ gap: 4px;+}++.demo-host {+ color: var(--vp-c-text-3);+ font-size: 12px;+ overflow-wrap: anywhere;+}++.demo-detail {+ color: var(--vp-c-text-2);+ font-size: 14px;+ overflow-wrap: anywhere;+}++.demo-name {+ font-size: 18px;+ font-weight: 600;+ line-height: 1.5;+ overflow-wrap: anywhere;+}++.demo-visit {+ display: flex;+ align-items: center;+ gap: 8px;+ margin-top: auto;+ color: var(--vp-c-brand-1);+ font-size: 14px;+}++.sr-only {+ position: absolute;+ width: 1px;+ height: 1px;+ padding: 0;+ overflow: hidden;+ clip: rect(0, 0, 0, 0);+ white-space: nowrap;+}++@media (max-width: 640px) {+ .demo-grid {+ grid-template-columns: minmax(0, 1fr);+ }+}+</style>diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.tsindex e5318e8b..9d5d27b2 100644--- a/docs/.vitepress/theme/index.ts+++ b/docs/.vitepress/theme/index.ts@@ -2,11 +2,13 @@ import type { App } from 'vue'import DefaultTheme from 'vitepress/theme'import AdsenseToc from './components/AdsenseToc.vue'import Layout from './Layout.vue'+import DemoSites from './components/DemoSites.vue'export default {...DefaultTheme,enhanceApp({ app }: { app: App }) {app.component('AdsenseToc', AdsenseToc)+ app.component('DemoSites', DemoSites)},Layout,}diff --git a/docs/changelog.md b/docs/changelog.mdnew file mode 100644index 00000000..108c081b--- /dev/null+++ b/docs/changelog.md@@ -0,0 +1,472 @@+# Changelog++Changes grouped by stable version. 1.0.0 includes all changes since v0.14.1, without separate beta or release-candidate entries. Historical entries are checked against adjacent stable Git tags; early prerelease tags are omitted.++## v1.0.0++[Upgrade guide](/guide/updates) · [Changes since v0.14.1](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.14.1...main)++### Features++- Add a first-run wizard for the administrator, site, storage and map, with the option to add a map token later.+- Store settings in the database and manage storage schemes, site details, upload limits, duplicate handling and privacy in the dashboard.+- Add hidden and password-protected albums, album and photo ordering, and shares scoped to protected albums.+- Add upload-date sorting, persistent table columns, Shift range selection and recent activity in the dashboard.+- Add dashboard language switching, Russian translations and broader translation coverage.+- Configure GitHub OAuth in system settings, choose a place-name language and add custom analytics scripts.++### Improvements++- Refine globe interactions, reactions, photo editing and the upload queue layout.+- Add log filtering and virtual scrolling; improve live delivery, history loading and scrolling.+- Confirm storage scheme deletion and provide guidance when map setup is missing.+- Update OG image generation and dependencies; move linting and formatting to Oxlint / Oxfmt.++### Bug fixes++- Fix dashboard settings being reset on restart; use legacy environment values for initialization and preserve saved custom settings.+- Fix sign-in redirects after setup and migration of older storage settings.+- Fix viewer navigation escaping the current album, album cover fallbacks and empty-album placeholders.+- Fix stalled local-file loading progress, processing failures from invalid EXIF dates and file-path errors during metadata editing.+- Fix large-image zoom on iOS Safari and viewer position, scale and flicker after window resizing.+- Use HeadObject for S3 metadata; fix custom-script attribute parsing and translation calls in asynchronous flows.++### Security fixes++- Restrict anonymous access to photos in hidden albums, including photos also assigned to public albums.+- Harden protected-album grants, media access, share scope and proxy limits to prevent access through alternate routes.+- Use asynchronous scrypt for album passwords, validate minimum length and rate-limit unlock attempts.+- Harden media filename handling and photo access checks.++### Deployment and documentation++- Run database migrations at startup and generate a persistent session secret in the data directory.+- Rebuild the Docker runtime with TLS certificates, Perl and ExifTool dependencies; the runtime has no shell or package manager.+- Archive environment-based instructions under Legacy and use the wizard for new installations.++### Upgrade notes++- Keep old environment variables for the initial migration and verify settings and storage paths in the dashboard.+- Album passwords cannot block direct access through public S3, OpenList or CDN URLs; manage external storage access too.+- Photos in hidden albums are excluded from anonymous access, which can affect their display in public albums.+- Back up all data before upgrading and restore the pre-migration database when rolling back.++## v0.14.1++2025-10-28 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.14.1) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.14.0...v0.14.1)++### Bug fixes++- Default the S3 region to auto.++## v0.14.0++2025-10-27 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.14.0) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.13.1...v0.14.0)++### Improvements++- Reorganize the dashboard around a sidebar layout.++### Bug fixes++- Correct the photo preview action label.++## v0.13.1++2025-10-25 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.13.1) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.13.0...v0.13.1)++### Features++- Add shuffled photo ordering.+- Support a custom Nominatim service URL.++### Bug fixes++- Fix viewer behavior on direct photo links and Mapbox token lookup.++## v0.13.0++2025-10-24 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.13.0) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.12.2...v0.13.0)++### Features++- Add OpenList storage support.+- Add original-image downloads, batch downloads and site sharing.++### Bug fixes++- Fix photo editing when storage has no prefix.++## v0.12.2++2025-10-22 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.12.2) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.12.1...v0.12.2)++### Features++- Add configurable photo table columns and rating editing.+- Combine thumbnail and Live Photo previews in one modal.++## v0.12.1++2025-10-21 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.12.1) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.12.0...v0.12.1)++### Bug fixes++- Fall back to English for unmapped locale codes.++## v0.12.0++2025-10-20 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.12.0) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.11.0...v0.12.0)++### Features++- Add partial EXIF editing and expandable task rows with error details.++### Bug fixes++- Stop marking failed reverse geocoding tasks as successful.++### Behavior changes++- Remove the separate location management page.++## v0.11.0++2025-10-20 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.11.0) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.10.0...v0.11.0)++### Features++- Add tiled rendering for large images and thumbnail previews in the dashboard.++### Bug fixes++- Scale oversized images on mobile to avoid GPU texture-limit failures.++## v0.10.0++2025-10-19 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.10.0) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.9.1...v0.10.0)++### Improvements++- Redesign the upload page and localize upload management.++### Features++- Add a back-to-top button.++## v0.9.1++2025-10-18 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.9.1) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.9.0...v0.9.1)++### Bug fixes++- Fix camera information in the share panel and album button display.++## v0.9.0++2025-10-17 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.9.0) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.8.1...v0.9.0)++### Features++- Add album browsing and management, with album membership in photo details.++### Improvements++- Return to the originating page when closing the viewer.++## v0.8.1++2025-10-13 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.8.1) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.8.0...v0.8.1)++### Bug fixes++- Add the missing MapLibre / MapTiler token configuration.++## v0.8.0++2025-10-13 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.8.0) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.7.2...v0.8.0)++### Features++- Support MapLibre and Mapbox, including dark map styles.++### Improvements++- Show more location and EXIF information in photo descriptions and share previews.++### Bug fixes++- Fix CJK paths in local storage, share-preview thumbnails and Motion Photo boolean parsing.+- Extract GPS coordinates even without completed reverse geocoding.++## v0.7.2++2025-10-11 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.7.2) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.7.1...v0.7.2)++### Features++- Add XMP Motion Photo processing and S3 forcePathStyle support.++### Improvements++- Expand EXIF description fields and add photo deletion confirmation.++### Bug fixes++- Fix motion-photo video paths and file type checks; clean up converted HEIC JPEGs.++## v0.7.1++2025-10-09 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.7.1) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.7.0...v0.7.1)++### Bug fixes++- Fix S3 URL generation for Alibaba Cloud OSS.++## v0.7.0++2025-10-09 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.7.0) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.6.7...v0.7.0)++### Features++- Add local storage, Matomo analytics and photo reactions in the dashboard.++### Improvements++- Expand translations and improve system information reporting on Windows.++### Bug fixes++- Fix home-page city statistics, sign-in text and viewer loading translations.++## v0.6.7++2025-10-07 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.6.7) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.6.6...v0.6.7)++### Features++- Add photo reactions, a reaction picker and confetti effects.+- Add GitHub OAuth configuration and analytics for photo views and shares.++### Bug fixes++- Fix long-press behavior on noninteractive elements and database condition exports.++## v0.6.6++2025-10-05 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.6.6) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.6.5...v0.6.6)++### Features++- Add site color-theme preference and Google Analytics configuration.++### Bug fixes++- Correct the analytics variable and Traditional Chinese Live Photo labels.++## v0.6.5++2025-10-04 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.6.5) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.6.4...v0.6.5)++### Bug fixes++- Fix masonry header width, alignment and responsive layout.++## v0.6.4++2025-10-03 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.6.4) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.6.3...v0.6.4)++### Features++- Add photo sharing, social sharing links and OG preview downloads.++## v0.6.3++2025-10-02 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.6.3) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.6.2...v0.6.3)++### Features++- Add a dashboard log viewer, live log streaming and file logging.++## v0.6.2++2025-10-01 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.6.2) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.6.1...v0.6.2)++### Features++- Add task queue management and translations, plus a Mapbox geocoding token setting.++### Improvements++- Improve handling guidance for Live Photos missing their paired image.++## v0.6.1++2025-09-30 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.6.1) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.6.0...v0.6.1)++### Improvements++- Expand white-balance translations and undefined-value labels.++### Behavior changes++- Remove path-based EXIF tag extraction.++## v0.6.0++2025-09-27 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.6.0) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.5.8...v0.6.0)++### Improvements++- Unify service retries, clean up stale tasks at startup and improve queue concurrency.+- Improve upload status, queue cleanup, Live Photo preloading and playback retries.++### Features++- Complete the calendar heatmap and dashboard overview translations.++## v0.5.8++2025-09-27 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.5.8) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.5.7...v0.5.8)++### Features++- Add the calendar heatmap component and dashboard overview translations.++### Bug fixes++- Fix a server error in the dashboard overview.++## v0.5.7++2025-09-26 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.5.7) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.5.6...v0.5.7)++### Features++- Add a calendar heatmap to the dashboard.++### Improvements++- Refine the dashboard overview and globe buttons.++### Bug fixes++- Use a dashboard title fallback when the site title is unset.++## v0.5.6++2025-09-26 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.5.6) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.5.5...v0.5.6)++### Improvements++- Redesign dashboard overview and system status reporting; reduce refresh overhead.++### Bug fixes++- Add extension fallback for HEIC / HEIF detection and correct upload-limit messages.++## v0.5.5++2025-09-25 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.5.5) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.5.4...v0.5.5)++### Features++- Add site owner settings.++### Bug fixes++- Rework the masonry layout to fix photo ordering.++### Behavior changes++- Rename the explore map to Globe.++## v0.5.4++2025-09-25 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.5.4) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.5.3...v0.5.4)++### Features++- Add a cookie option for non-HTTPS connections. This legacy option is deprecated in 1.0.0.++## v0.5.3++2025-09-25 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.5.3) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.5.2...v0.5.3)++### Improvements++- Scroll to the photo in its list when opening it.++### Bug fixes++- Fix route scrolling and jumps to the top when opening photo details.++## v0.5.2++2025-09-24 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.5.2) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.5.1...v0.5.2)++### Bug fixes++- Fix map zoom for photo-ID links and dashboard photo action visibility.++## v0.5.1++2025-09-24 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.5.1) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.5.0...v0.5.1)++### Behavior changes++- Use Mapbox first for reverse geocoding, with Nominatim as a fallback.++## v0.5.0++2025-09-24 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.5.0) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.4.3...v0.5.0)++### Improvements++- Rework the photo processing queue and worker pool, add queue APIs and improve progress reporting.++### Bug fixes++- Fix empty-gallery messages and dashboard titles.++## v0.4.3++2025-09-24 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.4.3) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.4.2...v0.4.3)++### Bug fixes++- Fix the site avatar setting not taking effect.++### Improvements++- Reduce Docker image size and update dependencies.++## v0.4.2++2025-09-22 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.4.2) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.4.1...v0.4.2)++### Features++- Add OG images for link previews.++## v0.4.1++2025-09-21 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.4.1) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.4.0...v0.4.1)++### Improvements++- Run database migration and seeding through tasks.++## v0.4.0++2025-09-21 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.4.0)++### Features++- Provide photo uploads, a masonry gallery, WebGL viewer and dashboard.+- Support EXIF, HEIC conversion, Live Photo pairing and playback, map exploration, tags and filters.+- Support password login, Docker deployment and multiple interface languages.++### Bug fixes++- Fix repeated map loading, histogram loading, EXIF keywords and color-space parsing.diff --git a/docs/configuration/location-providers.md b/docs/configuration/location-providers.mdindex dd230591..b8299c22 100644--- a/docs/configuration/location-providers.md+++ b/docs/configuration/location-providers.md@@ -1,32 +1,5 @@-# Location Providers+# Archived configuration-Location providers convert photo GPS coordinates (latitude and longitude) into human-readable city or country names during photo processing. This process is called Reverse Geocoding.+This page has moved to the archive. Use the [setup wizard](/guide/getting-started) for new installations and the dashboard for existing sites.-By default, no configuration is required. ChronoFrame uses OpenStreetMap Nominatim as the default location provider.--However, you may need to configure a custom location provider in the following cases:--- Your server is located in mainland China-- The connection between your server and Nominatim is blocked--ChronoFrame supports two location providers. You can choose the appropriate one based on your needs.--## Nominatim--Nominatim is a free reverse geocoding service provided by OpenStreetMap. By default, ChronoFrame uses Nominatim as the location provider.--If your server cannot connect to the official Nominatim service, you can set up your own reverse proxy and use it through the following configuration:--```bash-NUXT_NOMINATIM_BASE_URL=http://your-nominatim-proxy-url/-```--## Mapbox Search API--Mapbox Search API provides powerful reverse geocoding capabilities. To use Mapbox as your location provider, you need a [Mapbox access token](https://console.mapbox.com/account/access-tokens/).--```bash-NUXT_MAPBOX_ACCESS_TOKEN=your-mapbox-access-token-```--When you configure the `NUXT_MAPBOX_ACCESS_TOKEN` environment variable, ChronoFrame will automatically use Mapbox Search API as the location provider.+[Read the archived page](/legacy/configuration/location-providers)diff --git a/docs/configuration/map-providers.md b/docs/configuration/map-providers.mdindex 770b9af4..5d9d2bbb 100644--- a/docs/configuration/map-providers.md+++ b/docs/configuration/map-providers.md@@ -1,43 +1,5 @@-# Map Providers+# Archived configuration-ChronoFrame supports two types of map providers. You can choose the one that best fits your needs.+This page has moved to the archive. Use the [setup wizard](/guide/getting-started) for new installations and the dashboard for existing sites.-| Provider | Supported | Extra Configuration | Features |-| --------------------- | :-------: | --------------------- | -------------------------------------------- |-| [MapLibre](#maplibre) | ✅ | MapTiler Access Token | Free and open-source, supports custom styles |-| [Mapbox](#mapbox) | ✅ | Mapbox Access Token | Free tier, better renderer performance |--## MapLibre--To use MapLibre as the map provider, you need a [MapTiler Access Token](https://cloud.maptiler.com/account/keys/).--```bash-NUXT_PUBLIC_MAP_PROVIDER=maplibre-NUXT_PUBLIC_MAP_MAPLIBRE_TOKEN=your_maplibre_access_token-```--### Custom Styles--```bash-# ChronoFrame comes with built-in light and dark styles that switch automatically.-# If you configure a custom style, it will override the default styles.-# Example: https://demotiles.maplibre.org/globe.json-NUXT_PUBLIC_MAP_MAPLIBRE_STYLE=-```--## Mapbox--To use Mapbox as the map provider, you will need a [Mapbox Access Token](https://console.mapbox.com/account/access-tokens/).--```bash-NUXT_PUBLIC_MAP_PROVIDER=mapbox-NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=your_mapbox_access_token-```--### Custom Styles--```bash-# If you configure a custom style, it will override the default styles.-# Example: mapbox://styles/mapbox/streets-v11-NUXT_PUBLIC_MAP_MAPBOX_STYLE=-```+[Read the archived page](/legacy/configuration/map-providers)diff --git a/docs/configuration/storage-providers.md b/docs/configuration/storage-providers.mdindex d73fef1a..820e05d0 100644--- a/docs/configuration/storage-providers.md+++ b/docs/configuration/storage-providers.md@@ -1,199 +1,5 @@-# Storage Provider Configuration+# Archived configuration-ChronoFrame supports multiple storage backends to save your photos and thumbnails. This document will detail how to configure different storage providers.+This page has moved to the archive. Use the [setup wizard](/guide/getting-started) for new installations and the dashboard for existing sites.-> Password-protected albums require media URLs that cannot be fetched without ChronoFrame authorization. S3 buckets, OpenList download endpoints, and CDNs configured with public access do **not** meet this requirement: changing an album password does not revoke previously issued direct URLs or cached copies. Use local storage for protected albums until private remote-object delivery is supported. If media was already published, restrict access at the storage/CDN, purge its cache, and rotate or move the objects; changing only the album setting is insufficient.--| Provider | Support | Use Case | Cost |-| ------------------------------------------- | :-----: | --------------------------------------- | ------------------ |-| [**S3 Compatible**](#s3-compatible-storage) | ✅ | Production environment, cloud storage | Varies by provider |-| [**Local Filesystem**](#local-filesystem) | ✅ | Testing environment, offline deployment | Free |-| [**OpenList**](#openlist-storage) | ✅ | Personal cloud storage, NAS | Free |--## S3 Compatible Storage--S3 compatible storage is the most recommended production environment option, supporting all major cloud service providers.--### Basic Configuration--```bash-# 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-NUXT_PROVIDER_S3_FORCE_PATH_STYLE=false-```--### Cloud Provider Configuration Examples--#### AWS S3--```bash-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--```bash-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--```bash-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--```bash-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--```bash-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-# MinIO requires path-style access-NUXT_PROVIDER_S3_FORCE_PATH_STYLE=true-```--### Bucket Configuration--#### CORS Settings--Recommended CORS configuration:--```json-[- {- "AllowedOrigins": ["https://your-domain.com"],- "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],- "AllowedHeaders": ["*"],- "ExposeHeaders": ["ETag"],- "MaxAgeSeconds": 3000- }-]-```--## Local Filesystem--Local storage saves files in the server filesystem.--```bash-# Set storage provider to local-NUXT_STORAGE_PROVIDER=local--# Local storage configuration-NUXT_PROVIDER_LOCAL_PATH=/app/data/storage-NUXT_PROVIDER_LOCAL_BASE_URL=/storage-```--## OpenList Storage--OpenList is a file listing program that supports multiple cloud storage services.--| Environment Variable | Type | Required | Default | Description |-| ------------------------------------------ | ------ | -------- | ---------------- | -------------------------------------------------- |-| `NUXT_PROVIDER_OPENLIST_BASE_URL` | string | Yes | - | Base URL of the OpenList service |-| `NUXT_PROVIDER_OPENLIST_ROOT_PATH` | string | Yes | - | Root storage path |-| `NUXT_PROVIDER_OPENLIST_TOKEN` | string | Required | - | Authentication token (required for authentication) |-| `NUXT_PROVIDER_OPENLIST_ENDPOINT_UPLOAD` | string | Optional | `/api/fs/put` | Upload endpoint |-| `NUXT_PROVIDER_OPENLIST_ENDPOINT_DOWNLOAD` | string | Optional | - | Download endpoint |-| `NUXT_PROVIDER_OPENLIST_ENDPOINT_LIST` | string | Optional | - | List endpoint |-| `NUXT_PROVIDER_OPENLIST_ENDPOINT_DELETE` | string | Optional | `/api/fs/remove` | Delete endpoint |-| `NUXT_PROVIDER_OPENLIST_ENDPOINT_META` | string | Optional | `/api/fs/get` | Metadata endpoint |-| `NUXT_PROVIDER_OPENLIST_PATH_FIELD` | string | Optional | `path` | Path field name |-| `NUXT_PROVIDER_OPENLIST_CDN_URL` | string | Optional | - | CDN URL |--**Authentication:**--OpenList provider requires token authentication for secure access:--```bash-NUXT_PROVIDER_OPENLIST_TOKEN=your-static-token-```--### Basic Configuration--```bash-# Set storage provider to OpenList-NUXT_STORAGE_PROVIDER=openlist--# OpenList basic configuration-NUXT_PROVIDER_OPENLIST_BASE_URL=https://your-openlist-server.com-NUXT_PROVIDER_OPENLIST_ROOT_PATH=/chronoframe/photos-# Token is required for authentication-NUXT_PROVIDER_OPENLIST_TOKEN=your-api-token--# Optional configuration-NUXT_PROVIDER_OPENLIST_ENDPOINT_UPLOAD=/api/fs/put-NUXT_PROVIDER_OPENLIST_ENDPOINT_DOWNLOAD=-NUXT_PROVIDER_OPENLIST_ENDPOINT_LIST=-NUXT_PROVIDER_OPENLIST_ENDPOINT_DELETE=/api/fs/remove-NUXT_PROVIDER_OPENLIST_ENDPOINT_META=/api/fs/get-NUXT_PROVIDER_OPENLIST_PATH_FIELD=path-NUXT_PROVIDER_OPENLIST_CDN_URL=-```--### Configuration Examples--#### OpenList--```bash-NUXT_STORAGE_PROVIDER=openlist-NUXT_PROVIDER_OPENLIST_BASE_URL=https://your-openlist-server.com-NUXT_PROVIDER_OPENLIST_ROOT_PATH=/local/chronoframe-NUXT_PROVIDER_OPENLIST_TOKEN=your-static-token-```--## 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.-:::+[Read the archived page](/legacy/configuration/storage-providers)diff --git a/docs/demo-sites.md b/docs/demo-sites.mdnew file mode 100644index 00000000..53de20ad--- /dev/null+++ b/docs/demo-sites.md@@ -0,0 +1,11 @@+# Demo Sites++Explore galleries shared by ChronoFrame developers and community members. Select a card to visit a gallery.++## Developers++<DemoSites group="developers" />++## Community Users++<DemoSites group="community" />diff --git a/docs/development/api.md b/docs/development/api.mdindex 14d3b15e..ad14867a 100644--- a/docs/development/api.md+++ b/docs/development/api.md@@ -1,3 +1,33 @@-# API Documentation+# API Overview-🚧 WIP+The API uses the same session authentication as the web app. Authenticated requests carry the cookie obtained at sign-in; dashboard settings and management operations also check administrator privileges.++Common routes are listed below. For full parameters, responses and access rules, consult the routes and Zod validation in `server/api/`. These routes are not a versioned external API contract.++| Method | Path | Purpose |+| ------ | ------------------------------------------- | ---------------------------------------------------------------------- |+| POST | `/api/login` | Sign in with email/password and set a session cookie |+| GET | `/api/auth/github` | GitHub OAuth login and callback |+| GET | `/api/photos` | Photo list for signed-in users |+| GET | `/api/photos/visible` | Public photo list excluding hidden and password-protected album photos |+| GET | `/api/albums` | Read accessible albums |+| POST | `/api/albums/:albumId/unlock` | Unlock an album with its password |+| GET | `/api/system/settings/fields?namespace=app` | Read setting form fields (administrator) |+| PUT | `/api/system/settings/batch` | Save settings in a batch (administrator) |+| GET | `/api/queue/recent` | Recent dashboard tasks |+| GET | `/api/system/logs` | Dashboard logs |++## Update settings in a batch++With an administrator session, send a PUT request to `/api/system/settings/batch`:++```json+{+ "updates": [+ { "namespace": "app", "key": "title", "value": "My Gallery" },+ { "namespace": "app", "key": "slogan", "value": "Photos from my travels" }+ ]+}+```++For new settings or form changes, read [Adding a setting](/development/how-to-add-setting). Photo access follows album visibility and password rules; do not use the authenticated dashboard photo list as a public API.diff --git a/docs/development/contributing.md b/docs/development/contributing.mdindex 4514137b..5415e739 100644--- a/docs/development/contributing.md+++ b/docs/development/contributing.md@@ -1,352 +1,46 @@-# Contributing Guide+# Contributing-This document will guide you through setting up the ChronoFrame development environment, including environment requirements, dependency installation, configuration settings, and development tools.+Use Node.js 22, matching the Docker build, and the project's pinned pnpm 10.34.1. This repository contains workspace packages; install dependencies with pnpm.-## Environment Requirements--### Required Software--- **Node.js**: 20.0+-- **pnpm**: 9.0+ (preferred package manager)-- **Git**: Latest version-- **Docker**: Optional, for containerized development--## Clone and Install--### 1. Clone Repository+## Run locally```bash-# Using HTTPSgit clone https://github.com/HoshinoSuzumi/chronoframe.git--# Or using SSH-git clone [email protected]:HoshinoSuzumi/chronoframe.git--# Enter project directorycd chronoframe--# Set upstream remote repository-git remote add upstream https://github.com/HoshinoSuzumi/chronoframe.git-```--### 2. Install Dependencies--```bash-# Install pnpm (if not already installed)-npm install -g pnpm--# Install project dependencies-pnpm install-```--### 3. Configure Environment Variables--```bash-# Copy environment variable template-cp .env.example .env--# Edit environment variables-nano .env # Or use your preferred editor-```--#### Minimal Development Configuration--```bash-# === Admin Account ===-CFRAME_ADMIN_NAME=Developer-CFRAME_ADMIN_PASSWORD=dev123456--# === Authentication Settings ===-NUXT_OAUTH_GITHUB_CLIENT_ID=your-dev-github-client-id-NUXT_OAUTH_GITHUB_CLIENT_SECRET=your-dev-github-client-secret-NUXT_SESSION_PASSWORD=your-32-character-development-key--# === Storage Settings (can use MinIO for development) ===-NUXT_STORAGE_PROVIDER=s3-NUXT_PROVIDER_S3_ENDPOINT=http://localhost:9000-NUXT_PROVIDER_S3_BUCKET=chronoframe-dev-NUXT_PROVIDER_S3_REGION=us-east-1-NUXT_PROVIDER_S3_ACCESS_KEY_ID=minioadmin-NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=minioadmin--# === Map Services (optional) ===-NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=pk.your-development-token-NUXT_MAPBOX_ACCESS_TOKEN=sk.your-development-token--# === Enable Debug Info ===-VITE_SHOW_DEBUG_INFO=true-```--## Project Architecture--### Directory Structure--```-chronoframe/-├── app/ # Nuxt 4 application directory-│ ├── components/ # Vue components-│ │ ├── ui/ # Common UI components-│ │ ├── photo/ # Photo-related components-│ │ ├── masonry/ # Masonry layout components-│ │ └── ...-│ ├── pages/ # Route pages-│ ├── composables/ # Vue composables-│ ├── stores/ # Pinia state management-│ ├── layouts/ # Layout templates-│ ├── plugins/ # Nuxt plugins-│ └── utils/ # Utility functions-├── packages/-│ └── webgl-image/ # WebGL image viewer package-│ ├── src/-│ │ ├── core/ # Core engine-│ │ ├── components/ # Vue components-│ │ └── types/ # Type definitions-│ └── package.json-├── server/ # Nitro server-side-│ ├── api/ # API routes-│ │ ├── photos/ # Photo management API-│ │ ├── auth/ # Authentication API-│ │ └── system/ # System API-│ ├── database/ # Database related-│ │ ├── schema.ts # Database schema-│ │ └── migrations/ # Migration files-│ ├── services/ # Business logic services-│ │ ├── storage/ # Storage services-│ │ ├── image/ # Image processing-│ │ ├── location/ # Geolocation-│ │ └── pipeline-queue/ # Processing queue-│ ├── tasks/ # Background tasks-│ └── utils/ # Server-side utilities-├── shared/ # Shared code between frontend and backend-│ ├── types/ # TypeScript type definitions-│ └── utils/ # Shared utilities-├── docs/ # Project documentation-├── scripts/ # Build and deployment scripts-└── Configuration files...-```--### Technology Stack--#### Frontend Technologies--- **Nuxt 4**: Vue.js full-stack framework-- **TypeScript**: Type-safe JavaScript-- **TailwindCSS**: Utility-first CSS framework--#### Backend Technologies--- **Nitro**: Server-side framework-- **SQLite**: Lightweight database-- **Drizzle ORM**: Type-safe ORM-- **Sharp**: High-performance image processing-- **ExifTool**: EXIF data extraction--## Development Workflow--### Start Development Server--```bash-# Start complete development server+corepack enable+pnpm install --frozen-lockfilepnpm dev--# Or start step by step-pnpm build:deps # Build WebGL package-pnpm dlx nuxi@latest dev # Start Nuxt development server only```-### Database Operations+Open `http://localhost:3000` and use the wizard to create an administrator and choose local storage. `./data/storage` works for development. Database migrations run at startup; you do not need to generate migrations or fill out a minimal environment configuration just to run the app.-```bash-# Generate migration files-pnpm db:generate--# Execute database migrations-pnpm db:migrate-```--### Build Project+## Commands```bash-# Build WebGL dependency package+pnpm lint+pnpm fmt:checkpnpm build:deps--# Build complete projectpnpm build--# Preview production buildpnpm preview+pnpm docs:dev+pnpm docs:build```-## Testing Environment--### Local MinIO Storage--Run local MinIO service using Docker:--```bash-# Start MinIO-docker run -d \- --name minio \- -p 9000:9000 \- -p 9001:9001 \- -e "MINIO_ROOT_USER=minioadmin" \- -e "MINIO_ROOT_PASSWORD=minioadmin" \- minio/minio server /data --console-address ":9001"-```--Access MinIO console: http://localhost:9001--### GitHub OAuth App--1. Visit GitHub Settings > Developer settings > OAuth Apps-2. Create new OAuth app-3. Set callback URL: `http://localhost:3000/api/auth/github`-4. Copy Client ID and Client Secret to `.env` file--### Mapbox Development Tokens--1. Register [Mapbox account](https://account.mapbox.com/)-2. Create development access tokens-3. Set URL restriction: `http://localhost:3000`-4. Add tokens to `.env` file--## Code Standards--### TypeScript Standards--```typescript-// ✅ Good practice-interface PhotoMetadata {- id: string- title?: string- width: number- height: number- createdAt: Date-}--// ❌ Avoid using any-const processPhoto = (photo: any) => { ... }--// ✅ Use specific types-const processPhoto = (photo: PhotoMetadata) => { ... }-```--### Vue Component Standards--```vue-<!-- ✅ Recommended component structure -->-<script setup lang="ts">-// Imports-import { ref, computed } from 'vue'-import type { Photo } from '~/types'--// Props and Emits-interface Props {- photos: Photo[]- loading?: boolean-}--interface Emits {- select: [photo: Photo]- delete: [photoId: string]-}--const props = withDefaults(defineProps<Props>(), {- loading: false,-})--const emit = defineEmits<Emits>()--// Reactive data-const selectedPhoto = ref<Photo | null>(null)--// Computed properties-const photoCount = computed(() => props.photos.length)--// Methods-const handlePhotoClick = (photo: Photo) => {- selectedPhoto.value = photo- emit('select', photo)-}-</script>--<template>- <div class="photo-grid">- <!-- Template content -->- </div>-</template>--<style scoped>-/* Component styles */-</style>-```--### Database Calls--When using database operations in `server`, use `useDB()` to get the Drizzle instance. This composable is globally auto-imported on the server side:--```typescript-const db = useDB()--const photos = await db.select().from(photosTable)-```--### Commit Message Standards--Use [Conventional Commits](https://www.conventionalcommits.org/) standard:--```-feat: add photo batch delete functionality-fix: fix WebGL viewer compatibility issue in Safari-docs: update deployment documentation-style: unify code formatting-refactor: refactor storage service interface-test: add unit tests for photo upload-chore: update dependency versions-```--## Contribution Guidelines--### Development Process--1. **Fork Project**: Fork the project on GitHub-2. **Create Branch**: `git checkout -b feature/new-feature`-3. **Develop Feature**: Write code and tests-4. **Commit Changes**: Use standard commit messages-5. **Push Branch**: `git push origin feature/new-feature`-6. **Create PR**: Create Pull Request on GitHub--### Pull Request Checklist--Before submitting PR, ensure:--- Code passes all tests-- Follows code standards-- Updates relevant documentation-- Adds appropriate test cases-- PR description is clear with change explanations--## Contribution Opportunities--### Beginner-friendly Tasks--Look for Issues labeled with:+`pnpm dev` runs the WebGL package development build alongside Nuxt. Once the dependency package is built, use `pnpm dev:only` to start Nuxt alone. Code checks use Oxlint; formatting uses Oxfmt.-- `good first issue`: Tasks suitable for beginners-- `help wanted`: Tasks needing community help-- `documentation`: Documentation-related improvements+After changing the database schema, run `pnpm db:generate` and review the generated SQL. `pnpm db:migrate` applies migrations manually. Keep local databases, photos and credentials out of Git.-## Useful Resources+## Where code lives-### Official Documentation+- `app/`: pages, components, composables and Pinia stores.+- `packages/webgl-image/`: the WebGL image viewer.+- `server/api/`: API routes; `server/services/`: storage, settings and photo processing.+- `server/database/`: Drizzle schema and migrations.+- `shared/`: shared types; `i18n/`: translations.+- `docs/`: English and Chinese documentation.-- [Nuxt 4 Documentation](https://nuxt.com/)-- [Vue 3 Documentation](https://vuejs.org/)-- [Drizzle ORM Documentation](https://orm.drizzle.team/)-- [TailwindCSS Documentation](https://tailwindcss.com/)+For new dashboard settings, read [Adding a setting](/development/how-to-add-setting). Enter test credentials for S3, OpenList, maps or GitHub login in the dashboard. Use `http://localhost:3000/api/auth/github` as the local OAuth callback.-### Community Resources+## Submit a change-- [GitHub Issues](https://github.com/HoshinoSuzumi/chronoframe/issues)-- [GitHub Discussions](https://github.com/HoshinoSuzumi/chronoframe/discussions)+Keep changes focused and use Conventional Commits. Explain the problem, resulting behavior and verification in your PR. Include screenshots for UI changes and update both language versions for documentation changes. Issues marked `good first issue` or `help wanted` are useful starting points.diff --git a/docs/development/how-to-add-setting.md b/docs/development/how-to-add-setting.mdindex 0c33518a..71e1387c 100644--- a/docs/development/how-to-add-setting.md+++ b/docs/development/how-to-add-setting.md@@ -1,13 +1,12 @@-# 如何添加一个新的设置项+# Adding a Setting-以在 `app` 命名空间中添加 `foo` 字段为例。+Settings live in the database and are described by `DEFAULT_SETTINGS` in `server/services/settings/contants.ts`. Dashboard forms combine these definitions with UI configuration and translations.-## 步骤 1:在 DEFAULT_SETTINGS 中添加字段定义+## Define the setting-编辑 `server/services/settings/contants.ts`,在 `DEFAULT_SETTINGS` 中对应的命名空间部分添加:+Add a definition under the appropriate namespace:```typescript-// NAMESPACE: app{namespace: 'app',key: 'foo',@@ -17,96 +16,28 @@},```-字段说明(必需):+Use `isPublic` only for values visitors may read. Use `isSecret` for credentials and `isReadonly` for values that normal setting updates must not change. An `enum` limits available string values.-- `namespace`: 设置所属的命名空间 (app, map, location, storage, system 等)-- `key`: 字段的唯一键-- `type`: 类型 (string, number, boolean 等)-- `defaultValue`: 默认值+## Describe the form field-字段说明(可选):--- `isPublic`: 是否公开-- `isReadonly`: 是否只读-- `isSecret`: 是否为机密字段(如密码)-- `enum`: 枚举值数组--> 💡 **注意**:不需要在 DEFAULT_SETTINGS 中添加 `label` 和 `description`。SettingField 组件会自动生成翻译键 `settings.${namespace}.${key}.label` 和 `settings.${namespace}.${key}.description`--## 步骤 2:添加 UI 配置--编辑 `server/services/settings/ui-config.ts`,在对应的 UI 配置对象中添加:+In `server/services/settings/ui-config.ts`, add the field to the namespace's UI configuration:```typescriptexport const APP_SETTINGS_UI: Record<string, FieldUIConfig> = {- // ... 其他配置foo: {- type: 'input', // 字段类型:input, password, url, textarea, select, radio, tabs, toggle, number- placeholder: 'Enter foo value',- help: 'settings.app.foo.help', // 翻译键,可选- required: true, // 是否必需,可选+ type: 'input',+ help: 'settings.app.foo.help',+ required: true,},}```-## 步骤 3:添加翻译--编辑 `i18n/locales/` 中的翻译文件(例如 `en.json`):--```json-{- "settings": {- "app": {- "foo": {- "label": "Foo",- "description": "The foo setting",- "help": "This is the help text for foo"- }- }- }-}-```--## 步骤 4:在页面中使用+Field types include input, password, URL, textarea, select, radio, tabs, toggle and number. Use `visibleIf: { fieldKey: 'bar', value: 'baz' }` when a field depends on another field's value.-编辑 `app/pages/dashboard/settings/general.vue`,直接在模板中使用:--```vue-<template>- <UDashboardPanel>- <!-- ... -->- <UForm class="space-y-4">- <SettingField- v-for="field in fields"- :key="field.key"- :field="field"- :model-value="state[field.key]"- @update:model-value="(val) => (state[field.key] = val)"- />- </UForm>- </UDashboardPanel>-</template>-```--✅ 完成!`foo` 字段会自动被 `useSettingsForm('app')` 获取并渲染。--## 条件字段示例--如果需要根据其他字段来显示/隐藏某个字段,在 UI 配置中添加 `visibleIf`:--```typescript-foo: {- type: 'input',- placeholder: 'Only show when bar = "baz"',- visibleIf: { fieldKey: 'bar', value: 'baz' },-}-```+## Add translations and use the field-## 其他命名空间+Add `settings.app.foo.label`, `settings.app.foo.description` and any help text to the locale files under `i18n/locales/`.-- `map`:地图相关设置-- `location`:位置相关设置-- `storage`:存储相关设置-- `system`:系统设置+Existing forms use `useSettingsForm('app')` and render their descriptors through `SettingField`. For another namespace, use its corresponding UI configuration and form namespace. Server code reads and writes values through `settingsManager`.-流程相同,只需修改对应的 UI 配置对象(`MAP_SETTINGS_UI`、`LOCATION_SETTINGS_UI` 等)。+Check that the field renders, saves and survives a restart. If it is private or secret, also check that it is absent from public settings responses. Database-backed settings do not normally require a new environment variable.diff --git a/docs/guide/configuration.md b/docs/guide/configuration.mdindex b1b84575..a1a27d89 100644--- a/docs/guide/configuration.md+++ b/docs/guide/configuration.md@@ -1,79 +1,5 @@-# Configuration Reference+# Archived configuration-Whether using Docker or Docker Compose (.env) deployment, configuration is done through environment variables.+This page has moved to the archive. Use the [setup wizard](/guide/getting-started) for new installations and the dashboard for existing sites.-## Environment Variables List--| Environment Variable | Description | Default | Required |-| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- | ---------------------------------------------------- |-| CFRAME_ADMIN_EMAIL | Initial admin user email | `[email protected]` | Yes |-| CFRAME_ADMIN_NAME | Initial admin username | `Chronoframe` | No |-| CFRAME_ADMIN_PASSWORD | Initial admin user password | `CF1234@!` | No |-| NUXT_PUBLIC_APP_TITLE | Application title | `ChronoFrame` | No |-| NUXT_PUBLIC_APP_SLOGAN | Application slogan | None | No |-| NUXT_PUBLIC_APP_AUTHOR | Application author | None | No |-| NUXT_PUBLIC_APP_AVATAR_URL | Application avatar URL | None | No |-| NUXT_PUBLIC_COLOR_MODE_PREFERENCE | Color mode preference, options: `light`, `dark`, `system` | `system` | No |-| NUXT_PUBLIC_MAP_PROVIDER | Map provider, options: `mapbox`, `maplibre` | `maplibre` | No |-| NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN | Mapbox access token (URL restricted), for map services | None | Required when `NUXT_PUBLIC_MAP_PROVIDER` is `mapbox` |-| NUXT_NOMINATIM_BASE_URL | Nominatim base URL for reverse geocoding service | `https://nominatim.openstreetmap.org` | No |-| NUXT_MAPBOX_ACCESS_TOKEN | Mapbox access token (no URL restriction), for location services | None | No |-| NUXT_STORAGE_PROVIDER | Storage provider, supports `local`, `s3`, `openlist` | `local` | Yes |-| NUXT_PROVIDER_LOCAL_PATH | Local storage path | `/app/data/storage` | No |-| NUXT_PROVIDER_LOCAL_BASE_URL | Local storage access URL | `/storage` | No |-| NUXT_PROVIDER_S3_ENDPOINT | S3 compatible storage service endpoint | None | Required when `NUXT_STORAGE_PROVIDER` is `s3` |-| NUXT_PROVIDER_S3_BUCKET | S3 bucket name | `chronoframe` | Required when `NUXT_STORAGE_PROVIDER` is `s3` |-| NUXT_PROVIDER_S3_REGION | S3 bucket region | `auto` | Required when `NUXT_STORAGE_PROVIDER` is `s3` |-| NUXT_PROVIDER_S3_ACCESS_KEY_ID | S3 access key ID | None | Required when `NUXT_STORAGE_PROVIDER` is `s3` |-| NUXT_PROVIDER_S3_SECRET_ACCESS_KEY | S3 secret access key | None | Required when `NUXT_STORAGE_PROVIDER` is `s3` |-| NUXT_PROVIDER_S3_PREFIX | S3 storage prefix | `photos/` | No |-| NUXT_PROVIDER_S3_CDN_URL | S3 storage CDN URL | None | No |-| NUXT_PROVIDER_OPENLIST_BASE_URL | OpenList server URL | None | Required when `NUXT_STORAGE_PROVIDER` is `openlist` |-| NUXT_PROVIDER_OPENLIST_ROOT_PATH | OpenList root path | None | Required when `NUXT_STORAGE_PROVIDER` is `openlist` |-| NUXT_PROVIDER_OPENLIST_TOKEN | OpenList API token | None | Recommended (for OpenList authentication) |-| NUXT_PROVIDER_OPENLIST_ENDPOINT_UPLOAD | OpenList upload endpoint | `/api/fs/put` | No |-| NUXT_PROVIDER_OPENLIST_ENDPOINT_DOWNLOAD | OpenList download endpoint | None | No |-| NUXT_PROVIDER_OPENLIST_ENDPOINT_LIST | OpenList list endpoint | None | No |-| NUXT_PROVIDER_OPENLIST_ENDPOINT_DELETE | OpenList delete endpoint | `/api/fs/remove` | No |-| NUXT_PROVIDER_OPENLIST_ENDPOINT_META | OpenList metadata endpoint | `/api/fs/get` | No |-| NUXT_PROVIDER_OPENLIST_PATH_FIELD | OpenList path field name | `path` | No |-| NUXT_PROVIDER_OPENLIST_CDN_URL | OpenList CDN URL | None | No |-| NUXT_PUBLIC_OAUTH_GITHUB_ENABLED | Enable GitHub OAuth login | `false` | No |-| NUXT_OAUTH_GITHUB_CLIENT_ID | GitHub OAuth app Client ID | None | No (optional, for GitHub login) |-| NUXT_OAUTH_GITHUB_CLIENT_SECRET | GitHub OAuth app Client Secret | None | No (optional, for GitHub login) |-| NUXT_SESSION_PASSWORD | Password for encrypting sessions, 32-character random string | None | Yes |-| NUXT_TRUST_PROXY | Trust `X-Forwarded-For` for album unlock rate limits; enable only behind a trusted proxy that replaces client-supplied headers | `false` | No |-| NUXT_PUBLIC_GTAG_ID | Google Analytics Tracking ID | None | No |-| NUXT_PUBLIC_ANALYTICS_MATOMO_ENABLED | Enable Matomo analytics tracking | `false` | No |-| NUXT_PUBLIC_ANALYTICS_MATOMO_URL | Matomo instance URL (e.g., https://matomo.example.com) | None | No (required when Matomo is enabled) |-| NUXT_PUBLIC_ANALYTICS_MATOMO_SITE_ID | Matomo site ID | None | No (required when Matomo is enabled) |-| NUXT_UPLOAD_MIME_WHITELIST_ENABLED | Enable MIME type whitelist validation for uploads | `true` | No |-| NUXT_UPLOAD_MIME_WHITELIST | Allowed MIME types for uploads (comma-separated) | See below | No |-| ALLOW_INSECURE_COOKIE | Allow insecure cookies (only for development environment) | `false` | No |--## Upload File Type Whitelist--The default value of `NUXT_UPLOAD_MIME_WHITELIST` includes the following MIME types:--- `image/jpeg` - JPEG images-- `image/png` - PNG images-- `image/webp` - WebP images-- `image/gif` - GIF images-- `image/bmp` - BMP images-- `image/tiff` - TIFF images-- `image/heic` - HEIC images (Apple)-- `image/heif` - HEIF images-- `video/quicktime` - QuickTime videos (MOV)-- `video/mp4` - MP4 videos--To customize the whitelist, use a comma-separated string of MIME types, for example:--```-NUXT_UPLOAD_MIME_WHITELIST=image/jpeg,image/png,video/mp4-```--To disable whitelist validation (allow any file type), set:--```-NUXT_UPLOAD_MIME_WHITELIST_ENABLED=false-```+[Read the archived page](/legacy/guide/configuration)diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.mdindex 87a6fef2..d0901b53 100644--- a/docs/guide/getting-started.md+++ b/docs/guide/getting-started.md@@ -1,118 +1,8 @@# Getting Started-This guide walks you through deploying and using ChronoFrame quickly.+ChronoFrame stores photo metadata and settings in SQLite. You only need Docker and a directory for persistent data; there is no separate database service to set up.-:::warning 🚧 Under Construction-The documentation is still being written; some sections may be incomplete.-:::--## Prerequisites--- A working [Docker](https://docs.docker.com/get-docker/) environment.-- A storage backend. You can start with the built‑in local filesystem storage or configure an S3‑compatible bucket. See the [Storage Providers](/configuration/storage-providers) section for details.- :::tip S3 configuration checklist- If using S3, collect: `ACCESS_KEY_ID`, `SECRET_ACCESS_KEY`, `ENDPOINT`, `BUCKET_NAME`, `REGION`, and optionally a public CDN base URL (`CDN_URL`) if different from the endpoint.- :::-- (Optional) A [GitHub OAuth App](https://github.com/settings/applications/new) for enabling GitHub login (`CLIENT_ID`, `CLIENT_SECRET`).- :::tip Callback URL- Set the OAuth app Authorization callback URL to: `http(s)://<your-domain>/api/auth/github`- :::- :::info- If GitHub OAuth is not configured you can still log in with the default admin account (auto‑provisioned on first start).- :::--## Quick Deployment--### Pull Image--Use the published image on GitHub Container Registry and Docker Hub. Choose the source that works best for your network:--#### [GitHub Container Registry (GHCR)](https://github.com/HoshinoSuzumi/chronoframe/pkgs/container/chronoframe)--```bash-docker pull ghcr.io/hoshinosuzumi/chronoframe:latest-```--#### [Docker Hub](https://hub.docker.com/r/hoshinosuzumi/chronoframe)--```bash-docker pull hoshinosuzumi/chronoframe:latest-```--### Create `.env`--Below is the minimal configuration for running with local storage. For the complete list, see the [Configuration Guide](/guide/configuration).--```bash-# Admin email (required)-CFRAME_ADMIN_EMAIL=-# Admin username (optional, default Chronoframe)-CFRAME_ADMIN_NAME=-# Admin password (optional, default CF1234@!)-CFRAME_ADMIN_PASSWORD=--# Site metadata (all optional)-NUXT_PUBLIC_APP_TITLE=-NUXT_PUBLIC_APP_SLOGAN=-NUXT_PUBLIC_APP_AUTHOR=-NUXT_PUBLIC_APP_AVATAR_URL=--# Map provider (maplibre/mapbox)-NUXT_PUBLIC_MAP_PROVIDER=maplibre-# MapTiler access token for MapLibre-NUXT_PUBLIC_MAP_MAPLIBRE_TOKEN=-# Mapbox access token for Mapbox-NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=--# Storage provider (local or s3 or openlist)-NUXT_STORAGE_PROVIDER=local-NUXT_PROVIDER_LOCAL_PATH=/app/data/storage--# Session password (32‑char random string, required)-NUXT_SESSION_PASSWORD=-```--If you want to use S3 instead of local storage, replace the storage section with:--```bash-NUXT_STORAGE_PROVIDER=s3-NUXT_PROVIDER_S3_ENDPOINT=-NUXT_PROVIDER_S3_BUCKET=chronoframe-NUXT_PROVIDER_S3_REGION=auto-NUXT_PROVIDER_S3_ACCESS_KEY_ID=-NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=-NUXT_PROVIDER_S3_PREFIX=photos/-NUXT_PROVIDER_S3_CDN_URL=-```--If you want to use openlist instead of local storage, replace the storage section with:--```bash-NUXT_STORAGE_PROVIDER=openlist-NUXT_PROVIDER_OPENLIST_BASE_URL=https://openlist.example.com-NUXT_PROVIDER_OPENLIST_ROOT_PATH=/115pan/chronoframe-NUXT_PROVIDER_OPENLIST_TOKEN=your-static-token-```--Optional GitHub OAuth variables:--```bash-NUXT_OAUTH_GITHUB_CLIENT_ID=-NUXT_OAUTH_GITHUB_CLIENT_SECRET=-```--### Single Container (Docker Run)--```bash-docker run -d \- --name chronoframe \- -p 3000:3000 \- -v "$(pwd)/data:/app/data" \- --env-file .env \- ghcr.io/hoshinosuzumi/chronoframe:latest-```--### Docker Compose+## Start the containerCreate `docker-compose.yml`:@@ -126,115 +16,66 @@ services:- '3000:3000'volumes:- ./data:/app/data- env_file:- - .env```-Start / manage lifecycle:+For Docker Hub, replace the image with `hoshinosuzumi/chronoframe:latest`.```bash-# Startdocker compose up -d--# Follow logsdocker compose logs -f chronoframe+```-# Stop-docker compose down+Or use Docker directly:-# Update to latest image-docker compose pull-docker compose up -d+```bash+docker run -d --name chronoframe --restart unless-stopped \+ -p 3000:3000 -v "$(pwd)/data:/app/data" \+ ghcr.io/hoshinosuzumi/chronoframe:latest```-## Reverse Proxy+Open `http://localhost:3000`. A fresh installation opens the setup wizard; you do not need to create an `.env` file first.-For production you typically place ChronoFrame behind a reverse proxy (Nginx, Caddy, Traefik) to terminate HTTPS and serve via your domain.+## Complete the setup wizard-For the Nginx or Traefik examples below, set `NUXT_TRUST_PROXY=true` in `.env` and make port 3000 accessible only to the proxy. Do not enable this setting behind a proxy that forwards client-supplied `X-Forwarded-For` values unchanged.+1. **Administrator**: choose your email, username and password. Use these credentials to sign in later. Avoid the default password from older tutorials.+2. **Site**: enter the gallery title, description, author and avatar.+3. **Storage**: choose local storage, S3 or OpenList. For local storage, use `/app/data/storage` so photos are saved in the mounted data directory.+4. **Map**: choose MapLibre or Mapbox and enter the service token and style. You can leave the token empty and add it in the dashboard later. Map views need a working map service.+5. Review your choices and finish setup to enter the dashboard.-### Nginx Example+For S3, prepare an endpoint, bucket, region, access key ID and secret access key, plus an optional CDN URL. For OpenList, prepare the service URL, root path and access token. Enter these in the wizard or dashboard, rather than environment variables.-```nginx-server {- listen 80;- server_name your-domain.com;- return 301 https://$server_name$request_uri;-}+## Keep your data-server {- listen 443 ssl http2;- server_name your-domain.com;-- ssl_certificate /path/to/your/certificate.crt;- ssl_certificate_key /path/to/your/private.key;-- 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 $remote_addr;- proxy_set_header X-Forwarded-Proto $scheme;- proxy_cache_bypass $http_upgrade;- proxy_connect_timeout 60s;- proxy_send_timeout 60s;- proxy_read_timeout 60s;- }-- location /_nuxt/ {- proxy_pass http://localhost:3000;- expires 1y;- add_header Cache-Control "public, immutable";- proxy_set_header Host $host;- }-}-```+Keep the `./data:/app/data` mount. The default database is `/app/data/app.sqlite3`; a session secret is generated automatically and saved to `/app/data/.session-password`. With the local path above, originals and derived files also live under this directory.-### Traefik (Labels)+Keep the data directory when replacing a container. Files stored in S3 or OpenList need their own backup; a database backup alone cannot restore missing originals.-```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-```+## Use a domain and HTTPS-## Common Issues+You can place Caddy, Nginx or Traefik in front of the container. Match the proxy upload limit to your dashboard setting and allow streaming responses for live logs.-:::details How do I generate a random `NUXT_SESSION_PASSWORD`?+Enable `NUXT_TRUST_PROXY=true` only if port 3000 is reachable exclusively through a trusted proxy that replaces client-supplied `X-Forwarded-For` headers. This deployment option still uses an environment variable, for example in Compose:-```bash-# Linux / macOS-openssl rand -base64 32+```yaml+environment:+ NUXT_TRUST_PROXY: 'true'+```++An Nginx application proxy block can look like this:-# Windows (PowerShell)-[Convert]::ToBase64String((1..32|%{[byte](Get-Random -Max 256)}))+```nginx+location / {+ proxy_pass http://127.0.0.1:3000;+ proxy_set_header Host $host;+ proxy_set_header X-Forwarded-For $remote_addr;+ proxy_set_header X-Forwarded-Proto $scheme;+ proxy_buffering off;+ proxy_read_timeout 300s;+ client_max_body_size 256M;+}```-:::+## Next steps++Read [Using ChronoFrame](/guide/usage) for uploads, albums and dashboard settings. For an existing installation, start with the [update guide](/guide/updates).diff --git a/docs/guide/updates.md b/docs/guide/updates.mdindex 9e491cdf..c5d4458a 100644--- a/docs/guide/updates.md+++ b/docs/guide/updates.md@@ -1,117 +1,44 @@# Update Guide-This document will guide you through safely updating and upgrading ChronoFrame to the latest version.+Read the [changelog](/changelog) before choosing a target version and review its migration notes. The dashboard overview shows your running version.-## Version Check+## Back up-### 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+Stop the container before copying the complete data directory and Compose file. If your older deployment uses `.env`, save it too. Back up local storage separately if it is outside `data`, and back up S3 or OpenList files in their storage service.```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/+docker compose stop chronoframe+mkdir -p backups+cp -a data "backups/data-$(date +%Y%m%d-%H%M%S)"+cp docker-compose.yml backups/docker-compose.yml```-#### 2. Check Compatibility--Review [Release Notes](https://github.com/HoshinoSuzumi/chronoframe/releases) to understand:--- Breaking changes-- New environment variables-- Feature deprecation notices+## Replace the image-### Docker Compose Update (Recommended)--#### Standard Update Process+Change the image tag in Compose to the version you want, for example `v1.0.0`, then run:```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+docker compose pull chronoframe+docker compose up -d chronoframe+docker compose logs -f chronoframe```-#### Specific Version Update+Database migrations run automatically at startup. Manual migration commands are normally unnecessary. The current runtime image has no shell or package manager, so older instructions using `docker exec ... sh` or `npx drizzle-kit migrate` inside the container do not apply.-If you need to update to a specific version:+For a `docker run` deployment, stop and remove the old container, then recreate it with the new tag and the same data mount. Preserve your ports, networks and any deployment environment variables you still need.-```yaml-# docker-compose.yml-services:- chronoframe:- image: ghcr.io/hoshinosuzumi/chronoframe:v1.2.3 # Specify version- # ... other configurations-```+## From v0.14.1 to 1.0.0-```bash-docker-compose up -d-```--### Single Container Update--```bash-# Stop existing container-docker stop chronoframe-docker rm chronoframe+- Use `v1.0.0` to pin this release or `latest` to follow stable releases.+- Keep your old environment variables during the first upgrade so the application can migrate recognized settings and storage schemes. Verify site details, maps, login and storage in the dashboard before cleaning up `.env`.+- 1.0.0 fixes settings being overwritten on restart; dashboard settings remain in effect.+- If setup appears after upgrading, use the existing administrator email and confirm the original storage path. Check the data mount and startup logs before proceeding; do not create an empty replacement data directory.+- Preserve the session secret, database and storage paths. Deployment options such as proxy trust still belong in the runtime environment.-# Pull latest image-docker pull ghcr.io/hoshinosuzumi/chronoframe:latest+## Check the result-# 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+Sign in, open several existing photos, upload a photo and check albums, maps and the task queue. 1.0.0 adds access restrictions for photos in hidden albums; check your public gallery after upgrading.-### Automatic Migration+## Roll back-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-```+Migrations may change the database schema. To roll back, stop the new container, restore the complete backup from before the upgrade and start the original image tag. Downgrading only the image while retaining a migrated database is not a reliable rollback.diff --git a/docs/guide/usage.md b/docs/guide/usage.mdnew file mode 100644index 00000000..d82f40cf--- /dev/null+++ b/docs/guide/usage.md@@ -0,0 +1,53 @@+# Using ChronoFrame++## Upload and organize photos++Sign in and open `/dashboard`. Select files or drag them onto the Photos page to upload a batch. After upload, background tasks extract EXIF, create thumbnails and identify locations. The task queue shows progress, errors and retry results.++- Sort and filter the photo table and choose which columns to show. ChronoFrame remembers column visibility and supports sorting by upload date.+- Select photos to delete, download, reindex or add them to albums in batches. You can also use Shift + click range selection.+- Edit photo metadata such as title, description and rating.+- For Apple Live Photos, use matching image and MOV filenames, such as `IMG_1234.heic` and `IMG_1234.mov`. Either file can be uploaded first; pairing can be retried in the dashboard.+- Motion Photos with embedded video are also supported. The WebGL viewer provides zoom, pan and tiled rendering for large images.++## Albums and visibility++Albums group photos by subject. ChronoFrame supports ordering for both albums and the photos within them.++Hidden albums restrict public visibility. ChronoFrame also restricts anonymous access to their photos, even when a photo belongs to a public album as well. Check the public gallery after changing visibility.++ChronoFrame supports album passwords with a minimum of six characters. Visitors must unlock the album to browse it in ChronoFrame, and photo shares retain the album access scope.++::: warning External storage access+Album passwords control access through ChronoFrame. If S3, OpenList or a CDN exposes a direct image URL, someone with that URL may still read the file without opening the album. To protect the files themselves, check the storage and CDN access policies too. Hiding an album cannot revoke an external link that was already public.+:::++## Manage settings in the dashboard++Site details, maps, location services, storage and upload limits can be edited in the dashboard. Settings are stored in the database; there is no need to edit `.env` or rebuild the container.++| Setting | Purpose |+| --------- | -------------------------------------------------------------------- |+| Site | Title, description, author, avatar and color theme |+| Storage | Add or edit local, S3 and OpenList schemes; choose the active scheme |+| Map | MapLibre / Mapbox, access token and map style |+| Location | Place-name language, Mapbox geocoding token and custom Nominatim URL |+| System | Upload size limit, duplicate handling and GitHub login |+| Privacy | Automatically remove location data from new uploads |+| Analytics | Custom tracking scripts inserted into the page head or body |++Map settings control display; location settings convert GPS coordinates into place names. After changing the place-name language, reindex existing locations to update names already saved in the database.++Before switching storage schemes, make sure existing photos remain accessible. Selecting a scheme does not automatically move originals to the new storage. Local paths must be inside a mounted directory to survive container replacement.++The upload privacy option applies to future uploads; it does not automatically clean previously uploaded files. For existing photos, use the individual or batch location-removal action and confirm completion in the task queue. Check descriptions and tags for information you do not want to publish as well.++## GitHub login++Sign in with the email and password created during setup, then enable GitHub OAuth in system settings and enter the Client ID and Client Secret. Set the OAuth application's callback URL to `https://your-domain/api/auth/github`.++The email returned by GitHub must match an existing administrator. Enabling OAuth does not grant administrator access to every GitHub user; unauthorized accounts are rejected.++## Troubleshoot uploads++Use the task queue for processing errors and the log page for live and historical logs. For rejected uploads, check both the application and proxy size limits. For storage failures, check directory permissions or remote credentials. Include your version, storage type and relevant logs when reporting a problem, removing tokens and secrets first.diff --git a/docs/index.md b/docs/index.mdindex 86a606b0..df942f87 100644--- a/docs/index.md+++ b/docs/index.md@@ -5,7 +5,7 @@ layout: homehero:name: 'ChronoFrame'text: 'Self-hosted Personal Gallery'- tagline: 'Manage photos online with multi-storage backends, LivePhoto, and globe view'+ tagline: 'Upload, organize and share your photos, with setup in your browser'image:src: /logo.pngalt: ChronoFrame@@ -18,8 +18,8 @@ hero:text: View on GitHublink: https://github.com/HoshinoSuzumi/chronoframe- theme: alt- text: View Demo- link: https://lens.bh8.ga+ text: Demo Sites+ link: /demo-sitesfeatures:- title: Powerful Photo Management@@ -27,16 +27,16 @@ features:details: Easily manage and browse photos through web interface, view photo locations on map.- title: Simple Deploymenticon: 🚀- details: Deploy with one command using Docker, no database required (based on SQLite3).+ details: Start with Docker, then create your administrator and choose storage in the setup wizard. SQLite runs with the application.- title: Flexible Storage Solutionsicon: 💾- details: Support multiple storage backends including S3-compatible storage and local filesystem.+ details: Use local files, S3-compatible storage or OpenList, with storage schemes managed in the dashboard.- title: Smart Geolocationicon: 🌍- details: Automatically extract photo GPS information, use Mapbox for geocoding, display photo locations on map.- - title: Responsive Design+ details: Extract GPS and identify places through reverse geocoding, then browse them with MapLibre or Mapbox.+ - title: Albums and Privacyicon: 📱- details: Perfect for desktop and mobile, support touch operations and gesture controls, native app-like experience.+ details: Organize and reorder albums, hide them from public browsing or require a password.- title: Live/Motion Photo Supporticon: 🎬details: Full support for Apple LivePhoto format and Google-standard Motion Photo, automatically detect and process MOV video files, preserve dynamic photo effects.@@ -44,23 +44,11 @@ features:## 🌍 Demo Sites-Here are some well-running ChronoFrame instances built by developers and community members:--- [**TimoYin's Mems**](https://lens.bh8.ga)-- [**懒洋洋喝咖啡**](https://oreo.tanmantang.com) — 用镜头记录每个精彩瞬间-- [**My Photo Gallery**](https://photo.fivk.cn)-- [**An ISFP Conductor of Current, Pixels, and Code.**](https://gallery.xiaoten.com)-- [**我的旅行相册**](https://gallery.junlan.site) — 记录光影,留存回忆-- [**Z.Zhou's Photography**](https://photography.zzhou612.com/) — Catch the Moment-- [**Each Photo Turns a Moment Into Eternity.**](https://eachphoto.com)-- [**WhyPhoto**](https://photo.limina.top/)-- [**用图片记录生活**](https://gallery.d.cr)-- [**Ahmet Ömer's Photography**](https://photography.ahmeto.com/)-- [**何来尘埃飞舞**](https://photo.jefftay.com/)+Browse galleries shared by developers and community members on the [Demo Sites page](/demo-sites).## 💬 Community Support-- **GitHub Issues**: [Report Issues](https://github.com/HoshinoSuzumi/chronoframe/issues)+- **GitHub Issues**: [Report Issues](https://github.com/HoshinoSuzumi/chronoframe/issues/new/choose)- **GitHub Discussions**: [Discussions](https://github.com/HoshinoSuzumi/chronoframe/discussions)- **Discord**: [Join Us](https://discord.gg/MM4ZK4Ed7s)diff --git a/docs/legacy/configuration/location-providers.md b/docs/legacy/configuration/location-providers.mdnew file mode 100644index 00000000..71583e6b--- /dev/null+++ b/docs/legacy/configuration/location-providers.md@@ -0,0 +1,40 @@+---+search: false+---++::: warning Archived documentation+These instructions describe older deployments and environment-based settings. For current installations, use [Getting Started](/guide/getting-started) and manage settings in the dashboard.+:::++# Location Providers++Location providers convert photo GPS coordinates (latitude and longitude) into human-readable city or country names during photo processing. This process is called Reverse Geocoding.++By default, no configuration is required. ChronoFrame uses OpenStreetMap Nominatim as the default location provider.++However, you may need to configure a custom location provider in the following cases:++- Your server is located in mainland China+- The connection between your server and Nominatim is blocked++ChronoFrame supports two location providers. You can choose the appropriate one based on your needs.++## Nominatim++Nominatim is a free reverse geocoding service provided by OpenStreetMap. By default, ChronoFrame uses Nominatim as the location provider.++If your server cannot connect to the official Nominatim service, you can set up your own reverse proxy and use it through the following configuration:++```bash+NUXT_NOMINATIM_BASE_URL=http://your-nominatim-proxy-url/+```++## Mapbox Search API++Mapbox Search API provides powerful reverse geocoding capabilities. To use Mapbox as your location provider, you need a [Mapbox access token](https://console.mapbox.com/account/access-tokens/).++```bash+NUXT_MAPBOX_ACCESS_TOKEN=your-mapbox-access-token+```++When you configure the `NUXT_MAPBOX_ACCESS_TOKEN` environment variable, ChronoFrame will automatically use Mapbox Search API as the location provider.diff --git a/docs/legacy/configuration/map-providers.md b/docs/legacy/configuration/map-providers.mdnew file mode 100644index 00000000..0e806b12--- /dev/null+++ b/docs/legacy/configuration/map-providers.md@@ -0,0 +1,51 @@+---+search: false+---++::: warning Archived documentation+These instructions describe older deployments and environment-based settings. For current installations, use [Getting Started](/guide/getting-started) and manage settings in the dashboard.+:::++# Map Providers++ChronoFrame supports two types of map providers. You can choose the one that best fits your needs.++| Provider | Supported | Extra Configuration | Features |+| --------------------- | :-------: | --------------------- | -------------------------------------------- |+| [MapLibre](#maplibre) | ✅ | MapTiler Access Token | Free and open-source, supports custom styles |+| [Mapbox](#mapbox) | ✅ | Mapbox Access Token | Free tier, better renderer performance |++## MapLibre++To use MapLibre as the map provider, you need a [MapTiler Access Token](https://cloud.maptiler.com/account/keys/).++```bash+NUXT_PUBLIC_MAP_PROVIDER=maplibre+NUXT_PUBLIC_MAP_MAPLIBRE_TOKEN=your_maplibre_access_token+```++### Custom Styles++```bash+# ChronoFrame comes with built-in light and dark styles that switch automatically.+# If you configure a custom style, it will override the default styles.+# Example: https://demotiles.maplibre.org/globe.json+NUXT_PUBLIC_MAP_MAPLIBRE_STYLE=+```++## Mapbox++To use Mapbox as the map provider, you will need a [Mapbox Access Token](https://console.mapbox.com/account/access-tokens/).++```bash+NUXT_PUBLIC_MAP_PROVIDER=mapbox+NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=your_mapbox_access_token+```++### Custom Styles++```bash+# If you configure a custom style, it will override the default styles.+# Example: mapbox://styles/mapbox/streets-v11+NUXT_PUBLIC_MAP_MAPBOX_STYLE=+```diff --git a/docs/legacy/configuration/storage-providers.md b/docs/legacy/configuration/storage-providers.mdnew file mode 100644index 00000000..fcb231e0--- /dev/null+++ b/docs/legacy/configuration/storage-providers.md@@ -0,0 +1,207 @@+---+search: false+---++::: warning Archived documentation+These instructions describe older deployments and environment-based settings. For current installations, use [Getting Started](/guide/getting-started) and manage settings in the dashboard.+:::++# Storage Provider Configuration++ChronoFrame supports multiple storage backends to save your photos and thumbnails. This document will detail how to configure different storage providers.++> Password-protected albums require media URLs that cannot be fetched without ChronoFrame authorization. S3 buckets, OpenList download endpoints, and CDNs configured with public access do **not** meet this requirement: changing an album password does not revoke previously issued direct URLs or cached copies. Use local storage for protected albums until private remote-object delivery is supported. If media was already published, restrict access at the storage/CDN, purge its cache, and rotate or move the objects; changing only the album setting is insufficient.++| Provider | Support | Use Case | Cost |+| ------------------------------------------- | :-----: | --------------------------------------- | ------------------ |+| [**S3 Compatible**](#s3-compatible-storage) | ✅ | Production environment, cloud storage | Varies by provider |+| [**Local Filesystem**](#local-filesystem) | ✅ | Testing environment, offline deployment | Free |+| [**OpenList**](#openlist-storage) | ✅ | Personal cloud storage, NAS | Free |++## S3 Compatible Storage++S3 compatible storage is the most recommended production environment option, supporting all major cloud service providers.++### Basic Configuration++```bash+# 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+NUXT_PROVIDER_S3_FORCE_PATH_STYLE=false+```++### Cloud Provider Configuration Examples++#### AWS S3++```bash+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++```bash+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++```bash+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++```bash+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++```bash+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+# MinIO requires path-style access+NUXT_PROVIDER_S3_FORCE_PATH_STYLE=true+```++### Bucket Configuration++#### CORS Settings++Recommended CORS configuration:++```json+[+ {+ "AllowedOrigins": ["https://your-domain.com"],+ "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],+ "AllowedHeaders": ["*"],+ "ExposeHeaders": ["ETag"],+ "MaxAgeSeconds": 3000+ }+]+```++## Local Filesystem++Local storage saves files in the server filesystem.++```bash+# Set storage provider to local+NUXT_STORAGE_PROVIDER=local++# Local storage configuration+NUXT_PROVIDER_LOCAL_PATH=/app/data/storage+NUXT_PROVIDER_LOCAL_BASE_URL=/storage+```++## OpenList Storage++OpenList is a file listing program that supports multiple cloud storage services.++| Environment Variable | Type | Required | Default | Description |+| ------------------------------------------ | ------ | -------- | ---------------- | -------------------------------------------------- |+| `NUXT_PROVIDER_OPENLIST_BASE_URL` | string | Yes | - | Base URL of the OpenList service |+| `NUXT_PROVIDER_OPENLIST_ROOT_PATH` | string | Yes | - | Root storage path |+| `NUXT_PROVIDER_OPENLIST_TOKEN` | string | Required | - | Authentication token (required for authentication) |+| `NUXT_PROVIDER_OPENLIST_ENDPOINT_UPLOAD` | string | Optional | `/api/fs/put` | Upload endpoint |+| `NUXT_PROVIDER_OPENLIST_ENDPOINT_DOWNLOAD` | string | Optional | - | Download endpoint |+| `NUXT_PROVIDER_OPENLIST_ENDPOINT_LIST` | string | Optional | - | List endpoint |+| `NUXT_PROVIDER_OPENLIST_ENDPOINT_DELETE` | string | Optional | `/api/fs/remove` | Delete endpoint |+| `NUXT_PROVIDER_OPENLIST_ENDPOINT_META` | string | Optional | `/api/fs/get` | Metadata endpoint |+| `NUXT_PROVIDER_OPENLIST_PATH_FIELD` | string | Optional | `path` | Path field name |+| `NUXT_PROVIDER_OPENLIST_CDN_URL` | string | Optional | - | CDN URL |++**Authentication:**++OpenList provider requires token authentication for secure access:++```bash+NUXT_PROVIDER_OPENLIST_TOKEN=your-static-token+```++### Basic Configuration++```bash+# Set storage provider to OpenList+NUXT_STORAGE_PROVIDER=openlist++# OpenList basic configuration+NUXT_PROVIDER_OPENLIST_BASE_URL=https://your-openlist-server.com+NUXT_PROVIDER_OPENLIST_ROOT_PATH=/chronoframe/photos+# Token is required for authentication+NUXT_PROVIDER_OPENLIST_TOKEN=your-api-token++# Optional configuration+NUXT_PROVIDER_OPENLIST_ENDPOINT_UPLOAD=/api/fs/put+NUXT_PROVIDER_OPENLIST_ENDPOINT_DOWNLOAD=+NUXT_PROVIDER_OPENLIST_ENDPOINT_LIST=+NUXT_PROVIDER_OPENLIST_ENDPOINT_DELETE=/api/fs/remove+NUXT_PROVIDER_OPENLIST_ENDPOINT_META=/api/fs/get+NUXT_PROVIDER_OPENLIST_PATH_FIELD=path+NUXT_PROVIDER_OPENLIST_CDN_URL=+```++### Configuration Examples++#### OpenList++```bash+NUXT_STORAGE_PROVIDER=openlist+NUXT_PROVIDER_OPENLIST_BASE_URL=https://your-openlist-server.com+NUXT_PROVIDER_OPENLIST_ROOT_PATH=/local/chronoframe+NUXT_PROVIDER_OPENLIST_TOKEN=your-static-token+```++## 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.+:::diff --git a/docs/legacy/development/contributing.md b/docs/legacy/development/contributing.mdnew file mode 100644index 00000000..4d47fd19--- /dev/null+++ b/docs/legacy/development/contributing.md@@ -0,0 +1,360 @@+---+search: false+---++::: warning Archived documentation+These instructions describe older deployments and environment-based settings. For current installations, use [Getting Started](/guide/getting-started) and manage settings in the dashboard.+:::++# 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++```bash+# === Admin Account ===+CFRAME_ADMIN_NAME=Developer+CFRAME_ADMIN_PASSWORD=dev123456++# === Authentication Settings ===+NUXT_OAUTH_GITHUB_CLIENT_ID=your-dev-github-client-id+NUXT_OAUTH_GITHUB_CLIENT_SECRET=your-dev-github-client-secret+NUXT_SESSION_PASSWORD=your-32-character-development-key++# === Storage Settings (can use MinIO for development) ===+NUXT_STORAGE_PROVIDER=s3+NUXT_PROVIDER_S3_ENDPOINT=http://localhost:9000+NUXT_PROVIDER_S3_BUCKET=chronoframe-dev+NUXT_PROVIDER_S3_REGION=us-east-1+NUXT_PROVIDER_S3_ACCESS_KEY_ID=minioadmin+NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=minioadmin++# === Map Services (optional) ===+NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=pk.your-development-token+NUXT_MAPBOX_ACCESS_TOKEN=sk.your-development-token++# === Enable Debug Info ===+VITE_SHOW_DEBUG_INFO=true+```++## Project Architecture++### Directory Structure++```+chronoframe/+├── app/ # Nuxt 4 application directory+│ ├── components/ # Vue components+│ │ ├── ui/ # Common UI components+│ │ ├── photo/ # Photo-related components+│ │ ├── masonry/ # Masonry layout components+│ │ └── ...+│ ├── pages/ # Route pages+│ ├── composables/ # Vue composables+│ ├── stores/ # Pinia state management+│ ├── layouts/ # Layout templates+│ ├── plugins/ # Nuxt plugins+│ └── utils/ # Utility functions+├── packages/+│ └── webgl-image/ # WebGL image viewer package+│ ├── src/+│ │ ├── core/ # Core engine+│ │ ├── components/ # Vue components+│ │ └── types/ # Type definitions+│ └── package.json+├── server/ # Nitro server-side+│ ├── api/ # API routes+│ │ ├── photos/ # Photo management API+│ │ ├── auth/ # Authentication API+│ │ └── system/ # System API+│ ├── database/ # Database related+│ │ ├── schema.ts # Database schema+│ │ └── migrations/ # Migration files+│ ├── services/ # Business logic services+│ │ ├── storage/ # Storage services+│ │ ├── image/ # Image processing+│ │ ├── location/ # Geolocation+│ │ └── pipeline-queue/ # Processing queue+│ ├── tasks/ # Background tasks+│ └── utils/ # Server-side utilities+├── shared/ # Shared code between frontend and backend+│ ├── types/ # TypeScript type definitions+│ └── utils/ # Shared utilities+├── docs/ # Project documentation+├── scripts/ # Build and deployment scripts+└── Configuration files...+```++### Technology Stack++#### Frontend Technologies++- **Nuxt 4**: Vue.js full-stack framework+- **TypeScript**: Type-safe JavaScript+- **TailwindCSS**: Utility-first CSS framework++#### Backend Technologies++- **Nitro**: Server-side framework+- **SQLite**: Lightweight database+- **Drizzle ORM**: Type-safe ORM+- **Sharp**: High-performance image processing+- **ExifTool**: EXIF data extraction++## Development Workflow++### Start Development Server++```bash+# Start complete development server+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/new/choose)+- [GitHub Discussions](https://github.com/HoshinoSuzumi/chronoframe/discussions)diff --git a/docs/legacy/guide/configuration.md b/docs/legacy/guide/configuration.mdnew file mode 100644index 00000000..6d2f4567--- /dev/null+++ b/docs/legacy/guide/configuration.md@@ -0,0 +1,87 @@+---+search: false+---++::: warning Archived documentation+These instructions describe older deployments and environment-based settings. For current installations, use [Getting Started](/guide/getting-started) and manage settings in the dashboard.+:::++# Configuration Reference++Whether using Docker or Docker Compose (.env) deployment, configuration is done through environment variables.++## Environment Variables List++| Environment Variable | Description | Default | Required |+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- | ---------------------------------------------------- |+| CFRAME_ADMIN_EMAIL | Initial admin user email | `[email protected]` | Yes |+| CFRAME_ADMIN_NAME | Initial admin username | `Chronoframe` | No |+| CFRAME_ADMIN_PASSWORD | Initial admin user password | `CF1234@!` | No |+| NUXT_PUBLIC_APP_TITLE | Application title | `ChronoFrame` | No |+| NUXT_PUBLIC_APP_SLOGAN | Application slogan | None | No |+| NUXT_PUBLIC_APP_AUTHOR | Application author | None | No |+| NUXT_PUBLIC_APP_AVATAR_URL | Application avatar URL | None | No |+| NUXT_PUBLIC_COLOR_MODE_PREFERENCE | Color mode preference, options: `light`, `dark`, `system` | `system` | No |+| NUXT_PUBLIC_MAP_PROVIDER | Map provider, options: `mapbox`, `maplibre` | `maplibre` | No |+| NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN | Mapbox access token (URL restricted), for map services | None | Required when `NUXT_PUBLIC_MAP_PROVIDER` is `mapbox` |+| NUXT_NOMINATIM_BASE_URL | Nominatim base URL for reverse geocoding service | `https://nominatim.openstreetmap.org` | No |+| NUXT_MAPBOX_ACCESS_TOKEN | Mapbox access token (no URL restriction), for location services | None | No |+| NUXT_STORAGE_PROVIDER | Storage provider, supports `local`, `s3`, `openlist` | `local` | Yes |+| NUXT_PROVIDER_LOCAL_PATH | Local storage path | `/app/data/storage` | No |+| NUXT_PROVIDER_LOCAL_BASE_URL | Local storage access URL | `/storage` | No |+| NUXT_PROVIDER_S3_ENDPOINT | S3 compatible storage service endpoint | None | Required when `NUXT_STORAGE_PROVIDER` is `s3` |+| NUXT_PROVIDER_S3_BUCKET | S3 bucket name | `chronoframe` | Required when `NUXT_STORAGE_PROVIDER` is `s3` |+| NUXT_PROVIDER_S3_REGION | S3 bucket region | `auto` | Required when `NUXT_STORAGE_PROVIDER` is `s3` |+| NUXT_PROVIDER_S3_ACCESS_KEY_ID | S3 access key ID | None | Required when `NUXT_STORAGE_PROVIDER` is `s3` |+| NUXT_PROVIDER_S3_SECRET_ACCESS_KEY | S3 secret access key | None | Required when `NUXT_STORAGE_PROVIDER` is `s3` |+| NUXT_PROVIDER_S3_PREFIX | S3 storage prefix | `photos/` | No |+| NUXT_PROVIDER_S3_CDN_URL | S3 storage CDN URL | None | No |+| NUXT_PROVIDER_OPENLIST_BASE_URL | OpenList server URL | None | Required when `NUXT_STORAGE_PROVIDER` is `openlist` |+| NUXT_PROVIDER_OPENLIST_ROOT_PATH | OpenList root path | None | Required when `NUXT_STORAGE_PROVIDER` is `openlist` |+| NUXT_PROVIDER_OPENLIST_TOKEN | OpenList API token | None | Recommended (for OpenList authentication) |+| NUXT_PROVIDER_OPENLIST_ENDPOINT_UPLOAD | OpenList upload endpoint | `/api/fs/put` | No |+| NUXT_PROVIDER_OPENLIST_ENDPOINT_DOWNLOAD | OpenList download endpoint | None | No |+| NUXT_PROVIDER_OPENLIST_ENDPOINT_LIST | OpenList list endpoint | None | No |+| NUXT_PROVIDER_OPENLIST_ENDPOINT_DELETE | OpenList delete endpoint | `/api/fs/remove` | No |+| NUXT_PROVIDER_OPENLIST_ENDPOINT_META | OpenList metadata endpoint | `/api/fs/get` | No |+| NUXT_PROVIDER_OPENLIST_PATH_FIELD | OpenList path field name | `path` | No |+| NUXT_PROVIDER_OPENLIST_CDN_URL | OpenList CDN URL | None | No |+| NUXT_PUBLIC_OAUTH_GITHUB_ENABLED | Enable GitHub OAuth login | `false` | No |+| NUXT_OAUTH_GITHUB_CLIENT_ID | GitHub OAuth app Client ID | None | No (optional, for GitHub login) |+| NUXT_OAUTH_GITHUB_CLIENT_SECRET | GitHub OAuth app Client Secret | None | No (optional, for GitHub login) |+| NUXT_SESSION_PASSWORD | Password for encrypting sessions, 32-character random string | None | Yes |+| NUXT_TRUST_PROXY | Trust `X-Forwarded-For` for album unlock rate limits; enable only behind a trusted proxy that replaces client-supplied headers | `false` | No |+| NUXT_PUBLIC_GTAG_ID | Google Analytics Tracking ID | None | No |+| NUXT_PUBLIC_ANALYTICS_MATOMO_ENABLED | Enable Matomo analytics tracking | `false` | No |+| NUXT_PUBLIC_ANALYTICS_MATOMO_URL | Matomo instance URL (e.g., https://matomo.example.com) | None | No (required when Matomo is enabled) |+| NUXT_PUBLIC_ANALYTICS_MATOMO_SITE_ID | Matomo site ID | None | No (required when Matomo is enabled) |+| NUXT_UPLOAD_MIME_WHITELIST_ENABLED | Enable MIME type whitelist validation for uploads | `true` | No |+| NUXT_UPLOAD_MIME_WHITELIST | Allowed MIME types for uploads (comma-separated) | See below | No |+| ALLOW_INSECURE_COOKIE | Allow insecure cookies (only for development environment) | `false` | No |++## Upload File Type Whitelist++The default value of `NUXT_UPLOAD_MIME_WHITELIST` includes the following MIME types:++- `image/jpeg` - JPEG images+- `image/png` - PNG images+- `image/webp` - WebP images+- `image/gif` - GIF images+- `image/bmp` - BMP images+- `image/tiff` - TIFF images+- `image/heic` - HEIC images (Apple)+- `image/heif` - HEIF images+- `video/quicktime` - QuickTime videos (MOV)+- `video/mp4` - MP4 videos++To customize the whitelist, use a comma-separated string of MIME types, for example:++```+NUXT_UPLOAD_MIME_WHITELIST=image/jpeg,image/png,video/mp4+```++To disable whitelist validation (allow any file type), set:++```+NUXT_UPLOAD_MIME_WHITELIST_ENABLED=false+```diff --git a/docs/legacy/guide/getting-started.md b/docs/legacy/guide/getting-started.mdnew file mode 100644index 00000000..f25f6d7c--- /dev/null+++ b/docs/legacy/guide/getting-started.md@@ -0,0 +1,248 @@+---+search: false+---++::: warning Archived documentation+These instructions describe older deployments and environment-based settings. For current installations, use [Getting Started](/guide/getting-started) and manage settings in the dashboard.+:::++# Getting Started++This guide walks you through deploying and using ChronoFrame quickly.++:::warning 🚧 Under Construction+The documentation is still being written; some sections may be incomplete.+:::++## Prerequisites++- A working [Docker](https://docs.docker.com/get-docker/) environment.+- A storage backend. You can start with the built‑in local filesystem storage or configure an S3‑compatible bucket. See the [Storage Providers](/legacy/configuration/storage-providers) section for details.+ :::tip S3 configuration checklist+ If using S3, collect: `ACCESS_KEY_ID`, `SECRET_ACCESS_KEY`, `ENDPOINT`, `BUCKET_NAME`, `REGION`, and optionally a public CDN base URL (`CDN_URL`) if different from the endpoint.+ :::+- (Optional) A [GitHub OAuth App](https://github.com/settings/applications/new) for enabling GitHub login (`CLIENT_ID`, `CLIENT_SECRET`).+ :::tip Callback URL+ Set the OAuth app Authorization callback URL to: `http(s)://<your-domain>/api/auth/github`+ :::+ :::info+ If GitHub OAuth is not configured you can still log in with the default admin account (auto‑provisioned on first start).+ :::++## Quick Deployment++### Pull Image++Use the published image on GitHub Container Registry and Docker Hub. Choose the source that works best for your network:++#### [GitHub Container Registry (GHCR)](https://github.com/HoshinoSuzumi/chronoframe/pkgs/container/chronoframe)++```bash+docker pull ghcr.io/hoshinosuzumi/chronoframe:latest+```++#### [Docker Hub](https://hub.docker.com/r/hoshinosuzumi/chronoframe)++```bash+docker pull hoshinosuzumi/chronoframe:latest+```++### Create `.env`++Below is the minimal configuration for running with local storage. For the complete list, see the [Configuration Guide](/legacy/guide/configuration).++```bash+# Admin email (required)+CFRAME_ADMIN_EMAIL=+# Admin username (optional, default Chronoframe)+CFRAME_ADMIN_NAME=+# Admin password (optional, default CF1234@!)+CFRAME_ADMIN_PASSWORD=++# Site metadata (all optional)+NUXT_PUBLIC_APP_TITLE=+NUXT_PUBLIC_APP_SLOGAN=+NUXT_PUBLIC_APP_AUTHOR=+NUXT_PUBLIC_APP_AVATAR_URL=++# Map provider (maplibre/mapbox)+NUXT_PUBLIC_MAP_PROVIDER=maplibre+# MapTiler access token for MapLibre+NUXT_PUBLIC_MAP_MAPLIBRE_TOKEN=+# Mapbox access token for Mapbox+NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=++# Storage provider (local or s3 or openlist)+NUXT_STORAGE_PROVIDER=local+NUXT_PROVIDER_LOCAL_PATH=/app/data/storage++# Session password (32‑char random string, required)+NUXT_SESSION_PASSWORD=+```++If you want to use S3 instead of local storage, replace the storage section with:++```bash+NUXT_STORAGE_PROVIDER=s3+NUXT_PROVIDER_S3_ENDPOINT=+NUXT_PROVIDER_S3_BUCKET=chronoframe+NUXT_PROVIDER_S3_REGION=auto+NUXT_PROVIDER_S3_ACCESS_KEY_ID=+NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=+NUXT_PROVIDER_S3_PREFIX=photos/+NUXT_PROVIDER_S3_CDN_URL=+```++If you want to use openlist instead of local storage, replace the storage section with:++```bash+NUXT_STORAGE_PROVIDER=openlist+NUXT_PROVIDER_OPENLIST_BASE_URL=https://openlist.example.com+NUXT_PROVIDER_OPENLIST_ROOT_PATH=/115pan/chronoframe+NUXT_PROVIDER_OPENLIST_TOKEN=your-static-token+```++Optional GitHub OAuth variables:++```bash+NUXT_OAUTH_GITHUB_CLIENT_ID=+NUXT_OAUTH_GITHUB_CLIENT_SECRET=+```++### Single Container (Docker Run)++```bash+docker run -d \+ --name chronoframe \+ -p 3000:3000 \+ -v "$(pwd)/data:/app/data" \+ --env-file .env \+ ghcr.io/hoshinosuzumi/chronoframe:latest+```++### Docker Compose++Create `docker-compose.yml`:++```yaml+services:+ chronoframe:+ image: ghcr.io/hoshinosuzumi/chronoframe:latest+ container_name: chronoframe+ restart: unless-stopped+ ports:+ - '3000:3000'+ volumes:+ - ./data:/app/data+ env_file:+ - .env+```++Start / manage lifecycle:++```bash+# Start+docker compose up -d++# Follow logs+docker compose logs -f chronoframe++# Stop+docker compose down++# Update to latest image+docker compose pull+docker compose up -d+```++## Reverse Proxy++For production you typically place ChronoFrame behind a reverse proxy (Nginx, Caddy, Traefik) to terminate HTTPS and serve via your domain.++For the Nginx or Traefik examples below, set `NUXT_TRUST_PROXY=true` in `.env` and make port 3000 accessible only to the proxy. Do not enable this setting behind a proxy that forwards client-supplied `X-Forwarded-For` values unchanged.++### Nginx Example++```nginx+server {+ listen 80;+ server_name your-domain.com;+ return 301 https://$server_name$request_uri;+}++server {+ listen 443 ssl http2;+ server_name your-domain.com;++ ssl_certificate /path/to/your/certificate.crt;+ ssl_certificate_key /path/to/your/private.key;++ 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 $remote_addr;+ proxy_set_header X-Forwarded-Proto $scheme;+ proxy_cache_bypass $http_upgrade;+ proxy_connect_timeout 60s;+ proxy_send_timeout 60s;+ proxy_read_timeout 60s;+ }++ location /_nuxt/ {+ proxy_pass http://localhost:3000;+ expires 1y;+ add_header Cache-Control "public, immutable";+ proxy_set_header Host $host;+ }+}+```++### Traefik (Labels)++```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 do I generate a random `NUXT_SESSION_PASSWORD`?++```bash+# Linux / macOS+openssl rand -base64 32++# Windows (PowerShell)+[Convert]::ToBase64String((1..32|%{[byte](Get-Random -Max 256)}))+```++:::diff --git a/docs/legacy/guide/updates.md b/docs/legacy/guide/updates.mdnew file mode 100644index 00000000..25143d37--- /dev/null+++ b/docs/legacy/guide/updates.md@@ -0,0 +1,125 @@+---+search: false+---++::: warning Archived documentation+These instructions describe older deployments and environment-based settings. For current installations, use [Getting Started](/guide/getting-started) and manage settings in the dashboard.+:::++# 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+```diff --git a/docs/legacy/index.md b/docs/legacy/index.mdnew file mode 100644index 00000000..1be55500--- /dev/null+++ b/docs/legacy/index.md@@ -0,0 +1,15 @@+---+search: false+---++# Legacy++These pages preserve instructions from before the setup wizard. They can help with older installations and migration checks; their default accounts, environment variables and container commands may no longer apply.++- [Environment variables](/legacy/guide/configuration)+- [Storage](/legacy/configuration/storage-providers)+- [Maps](/legacy/configuration/map-providers)+- [Location services](/legacy/configuration/location-providers)+- [Old installation guide](/legacy/guide/getting-started)+- [Old update guide](/legacy/guide/updates)+- [Old development guide](/legacy/development/contributing)diff --git a/docs/zh/changelog.md b/docs/zh/changelog.mdnew file mode 100644index 00000000..7d8f5be4--- /dev/null+++ b/docs/zh/changelog.md@@ -0,0 +1,472 @@+# 更新日志++按正式版本汇总面向使用者的变更。1.0.0 收录 v0.14.1 之后的全部更新,不再逐个列出测试版。历史条目根据相邻正式版的 Git 标签核对;早期测试标签不单独列入。++## v1.0.0++[升级指南](/zh/guide/updates) · [自 v0.14.1 起的代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.14.1...main)++### 新功能++- 新增首次设置向导,在网页中创建管理员、设置站点、选择存储和地图;地图令牌可稍后补充。+- 设置改为数据库保存,后台可管理多个存储方案、站点信息、上传大小、重复文件处理和隐私选项。+- 新增隐藏相册和密码相册,支持相册排序、相册内照片排序及受保护相册中的照片分享。+- 后台照片支持按上传日期排序、记住显示列、Shift 连续选择;概览新增最近活动。+- 后台支持切换语言,新增俄语并补齐各语言的界面文案。+- GitHub OAuth 可在系统设置中开启并配置,支持自定义地名语言和统计脚本。++### 改进++- 改善地球仪交互、表情反馈、照片编辑和上传队列布局。+- 日志页新增筛选与虚拟滚动,改善实时日志、历史加载和滚动行为。+- 删除存储方案前增加确认,未设置地图服务时提供引导。+- 更新 OG 图片生成及依赖,代码检查和格式化迁移至 Oxlint / Oxfmt。++### Bug 修复++- 修复重启覆盖后台设置的问题;旧环境变量用于初始化,已保存的自定义设置优先。+- 修复首次设置后的登录跳转和旧存储配置迁移。+- 修复相册查看器导航越出当前相册、封面回退和空相册占位图。+- 修复本地文件加载进度停滞、无法解析的 EXIF 日期导致处理失败,以及编辑元数据时的文件路径错误。+- 修复 iOS Safari 大图缩放及窗口尺寸变化后查看器的位置、缩放和闪烁。+- S3 文件元数据改用 HeadObject 获取,修复自定义脚本属性解析和异步流程中的翻译调用。++### 安全修复++- 限制匿名访问隐藏相册中的照片,包含同时属于公开相册的照片。+- 加固密码相册访问凭据、媒体读取、分享范围和代理请求限制,防止受保护内容经其他入口泄露。+- 相册密码使用异步 scrypt 处理,校验最短长度,并限制解锁尝试频率。+- 加固媒体文件名处理和照片访问检查。++### 部署与文档++- 启动时自动迁移数据库,会话密钥自动生成并持久化到 data 目录。+- 重做 Docker 运行镜像,补齐 TLS 证书、Perl 和 ExifTool 运行依赖。运行镜像不再提供 shell 和包管理器。+- 旧环境变量配置文档归档到 Legacy;新部署以设置向导为入口。++### 升级注意++- 首次升级保留旧环境变量,迁移后在后台核对设置和存储路径。+- 相册密码不能阻止通过公开的 S3、OpenList 或 CDN 地址访问原图,需要同时管理外部存储权限。+- 隐藏相册中的照片会从匿名访问中排除,可能影响它们在公开相册中的展示。+- 更新前备份完整数据;回退时同时恢复迁移前的数据库。++## v0.14.1++2025-10-28 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.14.1) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.14.0...v0.14.1)++### Bug 修复++- S3 的默认 Region 改为 auto。++## v0.14.0++2025-10-27 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.14.0) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.13.1...v0.14.0)++### 改进++- 后台改为侧边栏布局,整理导航和页面结构。++### Bug 修复++- 修正照片预览操作的文字。++## v0.13.1++2025-10-25 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.13.1) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.13.0...v0.13.1)++### 新功能++- 照片排序新增随机排列。+- 支持自定义 Nominatim 服务地址。++### Bug 修复++- 修复直接访问照片链接时的查看器行为,以及 Mapbox 令牌读取问题。++## v0.13.0++2025-10-24 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.13.0) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.12.2...v0.13.0)++### 新功能++- 新增 OpenList 存储支持。+- 支持下载原图、批量下载选中照片,以及分享站点。++### Bug 修复++- 修复未设置存储前缀时编辑照片失败的问题。++## v0.12.2++2025-10-22 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.12.2) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.12.1...v0.12.2)++### 新功能++- 后台照片表格支持自选显示列;照片元数据支持修改评分。+- 缩略图预览与实况照片预览合并为同一弹窗。++## v0.12.1++2025-10-21 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.12.1) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.12.0...v0.12.1)++### Bug 修复++- 未映射的语言代码回退到英文。++## v0.12.0++2025-10-20 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.12.0) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.11.0...v0.12.0)++### 新功能++- 支持编辑部分照片 EXIF;任务队列可展开查看错误详情。++### Bug 修复++- 反向地理编码失败时不再错误地标记为成功。++### 行为变更++- 移除独立的位置管理页。++## v0.11.0++2025-10-20 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.11.0) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.10.0...v0.11.0)++### 新功能++- 大图查看器支持分块渲染;后台新增缩略图预览。++### Bug 修复++- 移动端对超出 GPU 纹理大小限制的图片进行缩小,避免渲染失败。++## v0.10.0++2025-10-19 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.10.0) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.9.1...v0.10.0)++### 改进++- 重做照片上传页面,补齐上传管理翻译。++### 新功能++- 新增返回顶部按钮。++## v0.9.1++2025-10-18 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.9.1) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.9.0...v0.9.1)++### Bug 修复++- 修复分享面板中的相机信息和相册按钮显示。++## v0.9.0++2025-10-17 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.9.0) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.8.1...v0.9.0)++### 新功能++- 新增相册浏览和后台管理,照片信息面板显示所属相册。++### 改进++- 查看器关闭后返回进入时的页面。++## v0.8.1++2025-10-13 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.8.1) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.8.0...v0.8.1)++### Bug 修复++- 补齐 MapLibre / MapTiler 的令牌配置。++## v0.8.0++2025-10-13 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.8.0) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.7.2...v0.8.0)++### 新功能++- 地图同时支持 MapLibre 和 Mapbox,并新增深色样式。++### 改进++- 照片描述和分享预览中展示更多地点与 EXIF 信息。++### Bug 修复++- 修复本地存储中文路径、分享预览缩略图和 Motion Photo 布尔值解析。+- 即使反向地理编码未完成,也提取照片的 GPS 坐标。++## v0.7.2++2025-10-11 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.7.2) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.7.1...v0.7.2)++### 新功能++- 新增基于 XMP 的 Motion Photo 处理;S3 支持 forcePathStyle。++### 改进++- 补充 EXIF 描述字段,删除照片时增加确认弹窗。++### Bug 修复++- 修复动态照片的视频路径与文件类型检查,并清理 HEIC 转换出的 JPEG。++## v0.7.1++2025-10-09 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.7.1) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.7.0...v0.7.1)++### Bug 修复++- 修复阿里云 OSS 的 S3 地址生成。++## v0.7.0++2025-10-09 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.7.0) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.6.7...v0.7.0)++### 新功能++- 新增本地存储和 Matomo 统计支持;后台显示照片表情反馈。++### 改进++- 补充多语言文本,改善 Windows 系统信息获取。++### Bug 修复++- 修复首页城市统计、登录页文字和查看器加载信息的本地化。++## v0.6.7++2025-10-07 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.6.7) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.6.6...v0.6.7)++### 新功能++- 新增照片表情反馈、选择器和彩纸效果。+- 新增 GitHub OAuth 配置和照片查看、分享事件统计。++### Bug 修复++- 修复非交互元素的长按行为和数据库条件导出。++## v0.6.6++2025-10-05 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.6.6) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.6.5...v0.6.6)++### 新功能++- 新增站点明暗主题偏好和 Google Analytics 配置。++### Bug 修复++- 修正统计配置变量和繁体中文实况照片文案。++## v0.6.5++2025-10-04 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.6.5) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.6.4...v0.6.5)++### Bug 修复++- 修复瀑布流页头宽度、对齐和响应式显示。++## v0.6.4++2025-10-03 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.6.4) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.6.3...v0.6.4)++### 新功能++- 新增照片分享面板、社交平台分享、OG 图片预览与下载。++## v0.6.3++2025-10-02 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.6.3) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.6.2...v0.6.3)++### 新功能++- 新增后台日志页、实时日志流和文件日志。++## v0.6.2++2025-10-01 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.6.2) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.6.1...v0.6.2)++### 新功能++- 新增任务队列管理页和翻译,支持配置反向地理编码的 Mapbox 令牌。++### 改进++- 改善实况照片缺少配对图片时的处理提示。++## v0.6.1++2025-09-30 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.6.1) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.6.0...v0.6.1)++### 改进++- 补充白平衡翻译和未定义值的显示。++### 行为变更++- 移除基于文件路径提取 EXIF 标签的逻辑。++## v0.6.0++2025-09-27 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.6.0) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.5.8...v0.6.0)++### 改进++- 统一服务重试机制,启动时清理失效任务,优化处理队列并发。+- 改善上传状态、队列清理、实况照片预加载及播放重试。++### 新功能++- 完善日历热力图及后台概览的多语言支持。++## v0.5.8++2025-09-27 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.5.8) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.5.7...v0.5.8)++### 新功能++- 新增日历热力图组件并补齐后台概览翻译。++### Bug 修复++- 修复后台概览的服务器错误。++## v0.5.7++2025-09-26 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.5.7) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.5.6...v0.5.7)++### 新功能++- 后台新增日历热力图。++### 改进++- 调整后台概览和地球仪按钮。++### Bug 修复++- 站点标题未配置时使用后台标题作为回退。++## v0.5.6++2025-09-26 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.5.6) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.5.5...v0.5.6)++### 改进++- 重做后台概览和系统状态信息,减少状态刷新开销。++### Bug 修复++- HEIC / HEIF 识别增加扩展名回退,修正文件大小限制提示。++## v0.5.5++2025-09-25 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.5.5) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.5.4...v0.5.5)++### 新功能++- 新增站点所有者配置。++### Bug 修复++- 重做瀑布流布局,修复照片排列顺序。++### 行为变更++- 探索地图更名为地球仪。++## v0.5.4++2025-09-25 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.5.4) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.5.3...v0.5.4)++### 新功能++- 新增非 HTTPS 连接下的 Cookie 选项。该旧选项在 1.0.0 中已弃用。++## v0.5.3++2025-09-25 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.5.3) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.5.2...v0.5.3)++### 改进++- 打开照片时定位到它在列表中的位置。++### Bug 修复++- 修复路由滚动行为及打开详情时跳回页顶的问题。++## v0.5.2++2025-09-24 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.5.2) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.5.1...v0.5.2)++### Bug 修复++- 调整带照片 ID 的地图链接缩放级别,修复后台照片操作按钮显示。++## v0.5.1++2025-09-24 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.5.1) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.5.0...v0.5.1)++### 行为变更++- 反向地理编码优先使用 Mapbox,以 Nominatim 为备选。++## v0.5.0++2025-09-24 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.5.0) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.4.3...v0.5.0)++### 改进++- 重做照片处理队列和工作池,新增队列 API,改善上传处理进度。++### Bug 修复++- 修复空画廊提示和后台标题。++## v0.4.3++2025-09-24 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.4.3) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.4.2...v0.4.3)++### Bug 修复++- 修复站点头像设置未生效的问题。++### 改进++- 缩减 Docker 镜像体积并更新相关依赖。++## v0.4.2++2025-09-22 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.4.2) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.4.1...v0.4.2)++### 新功能++- 新增 OG 图片,用于链接分享预览。++## v0.4.1++2025-09-21 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.4.1) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.4.0...v0.4.1)++### 改进++- 将数据库迁移和初始化改为任务执行。++## v0.4.0++2025-09-21 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.4.0)++### 新功能++- 提供照片上传、瀑布流画廊、WebGL 查看器和后台管理。+- 支持 EXIF、HEIC 转换、实况照片配对与播放、地图探索、标签与筛选。+- 支持账号密码登录、Docker 部署和多语言界面。++### Bug 修复++- 修复地图重复加载、直方图加载、EXIF 关键词和色彩空间解析等问题。diff --git a/docs/zh/config.ts b/docs/zh/config.tsindex 6efc81aa..a2be08f8 100644--- a/docs/zh/config.ts+++ b/docs/zh/config.ts@@ -9,7 +9,8 @@ export default defineConfig({nav: [{ text: '指南', link: '/zh/guide/getting-started' },{ text: '开发文档', link: '/zh/development/contributing' },- { text: '演示', link: 'https://lens.bh8.ga' },+ { text: '更新日志', link: '/zh/changelog' },+ { text: '演示站点', link: '/zh/demo-sites' },],sidebar: [@@ -17,16 +18,10 @@ export default defineConfig({text: '指南',items: [{ text: '快速开始', link: '/zh/guide/getting-started' },- { text: '配置说明', link: '/zh/guide/configuration' },+ { text: '日常使用', link: '/zh/guide/usage' },{ text: '升级指南', link: '/zh/guide/updates' },- ],- },- {- text: '配置',- items: [- { text: '存储提供器', link: '/zh/configuration/storage-providers' },- { text: '地图提供器', link: '/zh/configuration/map-providers' },- { text: '位置提供器', link: '/zh/configuration/location-providers' },+ { text: '更新日志', link: '/zh/changelog' },+ { text: '演示站点', link: '/zh/demo-sites' },],},{@@ -34,8 +29,14 @@ export default defineConfig({items: [{ text: '贡献指南', link: '/zh/development/contributing' },{ text: 'API 文档', link: '/zh/development/api' },+ { text: '添加设置项', link: '/zh/development/how-to-add-setting' },],},+ {+ text: 'Legacy',+ collapsed: true,+ items: [{ text: '历史文档', link: '/zh/legacy/' }],+ },],editLink: {diff --git a/docs/zh/configuration/location-providers.md b/docs/zh/configuration/location-providers.mdindex 45fd5058..4026bef0 100644--- a/docs/zh/configuration/location-providers.md+++ b/docs/zh/configuration/location-providers.md@@ -1,32 +1,5 @@-# 位置提供器+# 旧配置文档-位置提供器在处理照片的过程中,将照片的经纬度信息转换为人类可读的城市或国家名称,这一过程成为逆向地理编码(Reverse Geocoding)。+此页已归档。新部署请使用[设置向导](/zh/guide/getting-started),已有实例的设置可在后台修改。-默认情况下,您不需要进行任何配置,ChronoFrame 会使用 OpenStreetMap Nominatim 作为默认的位置提供器。--然而,在下列情况下,您可能有必要配置自定义的位置提供器:--- 服务器位于中国大陆-- 服务器与 Nominatim 之间的连接受阻--ChronoFrame 支持两种位置提供器,您可以根据需求选择合适的提供器。--## Nominatim--Nominatim 是 OpenStreetMap 提供的免费逆向地理编码服务。默认情况下,ChronoFrame 会使用 Nominatim 作为位置提供器。--如果您的服务器无法连接到 Nominatim 官方的服务,您可以自行搭建反向代理,然后通过下面的配置使用自己的地址:--```bash-NUXT_NOMINATIM_BASE_URL=http://your-nominatim-proxy-url/-```--## Mapbox Search API--Mapbox Search API 提供强大的逆向地理编码功能,能够在中国大陆境内访问。要使用 Mapbox 作为位置提供器,您需要一个 [Mapbox 访问令牌](https://console.mapbox.com/account/access-tokens/)。--```bash-NUXT_MAPBOX_ACCESS_TOKEN=your-mapbox-access-token-```--当您配置了 `NUXT_MAPBOX_ACCESS_TOKEN` 环境变量后,ChronoFrame 会自动使用 Mapbox Search API 作为位置提供器。+[查看历史文档](/zh/legacy/configuration/location-providers)diff --git a/docs/zh/configuration/map-providers.md b/docs/zh/configuration/map-providers.mdindex cc6cd66d..9ae1f4a2 100644--- a/docs/zh/configuration/map-providers.md+++ b/docs/zh/configuration/map-providers.md@@ -1,43 +1,5 @@-# 地图提供器+# 旧配置文档-ChronoFrame 支持两种地图提供器,您可以根据需求选择合适的提供器。+此页已归档。新部署请使用[设置向导](/zh/guide/getting-started),已有实例的设置可在后台修改。-| 提供器 | 支持 | 额外配置 | 特性 |-| --------------------- | :--: | ----------------- | ------------------------ |-| [MapLibre](#maplibre) | ✅ | MapTiler 访问令牌 | 免费开源,支持自定义样式 |-| [Mapbox](#mapbox) | ✅ | MapBox 访问令牌 | 免费用量,更好的渲染器 |--## MapLibre--要使用 MapLibre 作为地图提供器,您需要一个 [MapTiler 访问令牌](https://cloud.maptiler.com/account/keys/)。--```bash-NUXT_PUBLIC_MAP_PROVIDER=maplibre-NUXT_PUBLIC_MAP_MAPLIBRE_TOKEN=your_maplibre_access_token-```--### 自定义样式--```bash-# ChronoFrame 已经内置了自动切换的浅色和深色两种样式-# 如果配置自定义样式,将会覆盖默认样式-# 示例: https://demotiles.maplibre.org/globe.json-NUXT_PUBLIC_MAP_MAPLIBRE_STYLE=-```--## MapBox--要使用 Mapbox 作为地图提供器,您需要一个 [Mapbox 访问令牌](https://console.mapbox.com/account/access-tokens/)。--```bash-NUXT_PUBLIC_MAP_PROVIDER=mapbox-NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=your_mapbox_access_token-```--### 自定义样式--```bash-# 如果配置自定义样式,将会覆盖默认样式-# 示例: mapbox://styles/mapbox/streets-v11-NUXT_PUBLIC_MAP_MAPBOX_STYLE=-```+[查看历史文档](/zh/legacy/configuration/map-providers)diff --git a/docs/zh/configuration/storage-providers.md b/docs/zh/configuration/storage-providers.mdindex e5172f12..606e225c 100644--- a/docs/zh/configuration/storage-providers.md+++ b/docs/zh/configuration/storage-providers.md@@ -1,200 +1,5 @@-# 存储提供器配置+# 旧配置文档-ChronoFrame 支持多种存储后端来保存您的照片和缩略图。本文档将详细介绍如何配置不同的存储提供器。+此页已归档。新部署请使用[设置向导](/zh/guide/getting-started),已有实例的设置可在后台修改。-> 密码保护相簿要求媒体 URL 不能绕过 ChronoFrame 授权直接获取。公开访问的 S3 存储桶、OpenList 下载地址或 CDN 不满足此要求:修改相簿密码不会撤销已发出的直链或缓存副本。在支持私有远端对象交付前,请对受保护相簿使用本地存储。若媒体已经公开,还需在存储/CDN 侧关闭公开访问、清理缓存并更换对象地址;只修改相簿设置并不足够。--| 提供器 | 支持 | 适用场景 | 成本 |-| --------------------------------- | :--: | ------------------ | ------------ |-| [**S3 兼容存储**](#s3-兼容存储) | ✅ | 生产环境,云存储 | 按使用量计费 |-| [**本地文件系统**](#本地文件系统) | ✅ | 测试环境,离线部署 | 免费 |-| [**OpenList**](#openlist-存储) | ✅ | 个人云存储,NAS | 免费 |--## S3 兼容存储--S3 兼容存储是最推荐的生产环境选项,支持所有主流云服务提供商。--### 基础配置--```bash-# 设置存储提供器为 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-NUXT_PROVIDER_S3_FORCE_PATH_STYLE=false-```--### 云服务商配置示例--#### AWS S3--```bash-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--```bash-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--```bash-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--```bash-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 自托管--```bash-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-# MinIO 需要启用路径样式访问-NUXT_PROVIDER_S3_FORCE_PATH_STYLE=true-```--### 存储桶配置--#### CORS 设置--推荐的 CORS 配置:--```json-[- {- "AllowedOrigins": ["https://your-domain.com"],- "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],- "AllowedHeaders": ["*"],- "ExposeHeaders": ["ETag"],- "MaxAgeSeconds": 3000- }-]-```--## 本地文件系统--本地存储将文件保存在服务器文件系统中。--```bash-# 设置存储提供器为本地-NUXT_STORAGE_PROVIDER=local--# 本地存储配置-NUXT_PROVIDER_LOCAL_PATH=/app/data/storage-NUXT_PROVIDER_LOCAL_BASE_URL=/storage-```--## OpenList 存储--OpenList 是一个开源的文件管理系统,提供对各种云存储服务的 API 访问。此提供程序允许您使用与 OpenList 兼容的服务作为照片存储后端。--| 环境变量 | 类型 | 必需 | 默认值 | 描述 |-| ------------------------------------------ | ------ | ---- | ---------------- | ----------------------- |-| `NUXT_PROVIDER_OPENLIST_BASE_URL` | string | 是 | - | OpenList 服务的基础 URL |-| `NUXT_PROVIDER_OPENLIST_ROOT_PATH` | string | 是 | - | 根存储路径 |-| `NUXT_PROVIDER_OPENLIST_TOKEN` | string | 必需 | - | 认证令牌(认证时必需) |-| `NUXT_PROVIDER_OPENLIST_ENDPOINT_UPLOAD` | string | 可选 | `/api/fs/put` | 上传端点 |-| `NUXT_PROVIDER_OPENLIST_ENDPOINT_DOWNLOAD` | string | 可选 | - | 下载端点 |-| `NUXT_PROVIDER_OPENLIST_ENDPOINT_LIST` | string | 可选 | - | 列表端点 |-| `NUXT_PROVIDER_OPENLIST_ENDPOINT_DELETE` | string | 可选 | `/api/fs/remove` | 删除端点 |-| `NUXT_PROVIDER_OPENLIST_ENDPOINT_META` | string | 可选 | `/api/fs/get` | 元数据端点 |-| `NUXT_PROVIDER_OPENLIST_PATH_FIELD` | string | 可选 | `path` | 路径字段名 |-| `NUXT_PROVIDER_OPENLIST_CDN_URL` | string | 可选 | - | CDN URL |--**认证:**--OpenList 提供程序需要令牌认证以确保安全访问:--```bash-NUXT_PROVIDER_OPENLIST_TOKEN=your-static-token-```--### 基础配置--```bash-# 设置存储提供器为 OpenList-NUXT_STORAGE_PROVIDER=openlist--# OpenList 基础配置-NUXT_PROVIDER_OPENLIST_BASE_URL=https://your-openlist-server.com-NUXT_PROVIDER_OPENLIST_ROOT_PATH=/chronoframe/photos--# 认证配置 - Token 认证-NUXT_PROVIDER_OPENLIST_TOKEN=your-api-token--# 可选配置-NUXT_PROVIDER_OPENLIST_ENDPOINT_UPLOAD=/api/fs/put-NUXT_PROVIDER_OPENLIST_ENDPOINT_DOWNLOAD=-NUXT_PROVIDER_OPENLIST_ENDPOINT_LIST=-NUXT_PROVIDER_OPENLIST_ENDPOINT_DELETE=/api/fs/remove-NUXT_PROVIDER_OPENLIST_ENDPOINT_META=/api/fs/get-NUXT_PROVIDER_OPENLIST_PATH_FIELD=path-NUXT_PROVIDER_OPENLIST_CDN_URL=-```--### 配置示例--#### OpenList(理论上Alist也可行)--```bash-NUXT_STORAGE_PROVIDER=openlist-NUXT_PROVIDER_OPENLIST_BASE_URL=https://openlist.example.com-NUXT_PROVIDER_OPENLIST_ROOT_PATH=/115pan/chronoframe-NUXT_PROVIDER_OPENLIST_TOKEN=your-static-token-```--## 常见问题--:::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-设置) 进行配置。-:::+[查看历史文档](/zh/legacy/configuration/storage-providers)diff --git a/docs/zh/demo-sites.md b/docs/zh/demo-sites.mdnew file mode 100644index 00000000..65844545--- /dev/null+++ b/docs/zh/demo-sites.md@@ -0,0 +1,11 @@+# 演示站点++看看开发者和社区用户如何用 ChronoFrame 展示自己的照片。点击卡片即可访问对应画廊。++## 开发者++<DemoSites group="developers" />++## 社区用户++<DemoSites group="community" />diff --git a/docs/zh/development/api.md b/docs/zh/development/api.mdindex 08ff383d..fd0f2d33 100644--- a/docs/zh/development/api.md+++ b/docs/zh/development/api.md@@ -1,3 +1,33 @@-# API 文档+# API 概览-🚧 WIP+API 与网页使用同一套会话认证。需要登录的请求携带登录后获得的 Cookie;后台设置和管理操作还会检查管理员权限。++下面列出常用入口,完整参数、响应和访问规则以 `server/api/` 的路由及其 Zod 校验为准。这不是一份固定版本的外部 API 合约。++| 方法 | 路径 | 用途 |+| ---- | ------------------------------------------- | ---------------------------------------- |+| POST | `/api/login` | 邮箱密码登录,设置会话 Cookie |+| GET | `/api/auth/github` | GitHub OAuth 登录回调 |+| GET | `/api/photos` | 登录用户读取照片列表 |+| GET | `/api/photos/visible` | 公开可见照片,排除隐藏和密码相册中的照片 |+| GET | `/api/albums` | 读取可访问的相册 |+| POST | `/api/albums/:albumId/unlock` | 使用密码解锁相册 |+| GET | `/api/system/settings/fields?namespace=app` | 读取设置表单字段(管理员) |+| PUT | `/api/system/settings/batch` | 批量保存设置(管理员) |+| GET | `/api/queue/recent` | 后台最近任务 |+| GET | `/api/system/logs` | 后台日志 |++## 批量修改设置++管理员会话下向 `/api/system/settings/batch` 发送 PUT 请求:++```json+{+ "updates": [+ { "namespace": "app", "key": "title", "value": "My Gallery" },+ { "namespace": "app", "key": "slogan", "value": "Photos from my travels" }+ ]+}+```++新增设置或修改设置表单,请阅读[设置开发指南](/zh/development/how-to-add-setting)。照片读取需要遵守相册可见性和密码访问规则,不要将后台照片列表当作公开接口使用。diff --git a/docs/zh/development/contributing.md b/docs/zh/development/contributing.mdindex 4b5e7661..d6657859 100644--- a/docs/zh/development/contributing.md+++ b/docs/zh/development/contributing.md@@ -1,352 +1,46 @@# 开始贡献-本文档将指导您搭建 ChronoFrame 的开发环境,包括环境要求、依赖安装、配置设置和开发工具。+使用 Node.js 22(与 Docker 构建环境一致)和项目指定的 pnpm 10.34.1。仓库包含 workspace 包,请使用 pnpm 安装依赖。-## 环境要求--### 必需软件--- **Node.js**: 20.0+-- **pnpm**: 9.0+ (首选包管理器)-- **Git**: 最新版本-- **Docker**: 可选,用于容器化开发--## 克隆与安装--### 1. 克隆代码库+## 本地运行```bash-# 使用 HTTPSgit clone https://github.com/HoshinoSuzumi/chronoframe.git--# 或使用 SSH-git clone [email protected]:HoshinoSuzumi/chronoframe.git--# 进入项目目录cd chronoframe--# 设置上游远程仓库-git remote add upstream https://github.com/HoshinoSuzumi/chronoframe.git-```--### 2. 安装依赖--```bash-# 安装 pnpm(如果尚未安装)-npm install -g pnpm--# 安装项目依赖-pnpm install-```--### 3. 配置环境变量--```bash-# 复制环境变量模板-cp .env.example .env--# 编辑环境变量-nano .env # 或使用您喜欢的编辑器-```--#### 最小开发配置--```bash-# === 管理员账户 ===-CFRAME_ADMIN_NAME=Developer-CFRAME_ADMIN_PASSWORD=dev123456--# === 认证设置 ===-NUXT_OAUTH_GITHUB_CLIENT_ID=your-dev-github-client-id-NUXT_OAUTH_GITHUB_CLIENT_SECRET=your-dev-github-client-secret-NUXT_SESSION_PASSWORD=your-32-character-development-key--# === 存储设置(开发环境可使用 MinIO) ===-NUXT_STORAGE_PROVIDER=s3-NUXT_PROVIDER_S3_ENDPOINT=http://localhost:9000-NUXT_PROVIDER_S3_BUCKET=chronoframe-dev-NUXT_PROVIDER_S3_REGION=us-east-1-NUXT_PROVIDER_S3_ACCESS_KEY_ID=minioadmin-NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=minioadmin--# === 地图服务(可选) ===-NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=pk.your-development-token-NUXT_MAPBOX_ACCESS_TOKEN=sk.your-development-token--# === 开启调试信息 ===-VITE_SHOW_DEBUG_INFO=true-```--## 项目架构--### 目录结构--```-chronoframe/-├── app/ # Nuxt 4 应用目录-│ ├── components/ # Vue 组件-│ │ ├── ui/ # 通用 UI 组件-│ │ ├── photo/ # 照片相关组件-│ │ ├── masonry/ # 瀑布流布局组件-│ │ └── ...-│ ├── pages/ # 路由页面-│ ├── composables/ # Vue 组合式函数-│ ├── stores/ # Pinia 状态管理-│ ├── layouts/ # 布局模板-│ ├── plugins/ # Nuxt 插件-│ └── utils/ # 工具函数-├── packages/-│ └── webgl-image/ # WebGL 图片查看器包-│ ├── src/-│ │ ├── core/ # 核心引擎-│ │ ├── components/ # Vue 组件-│ │ └── types/ # 类型定义-│ └── package.json-├── server/ # Nitro 服务端-│ ├── api/ # API 路由-│ │ ├── photos/ # 照片管理 API-│ │ ├── auth/ # 认证 API-│ │ └── system/ # 系统 API-│ ├── database/ # 数据库相关-│ │ ├── schema.ts # 数据库模式-│ │ └── migrations/ # 迁移文件-│ ├── services/ # 业务逻辑服务-│ │ ├── storage/ # 存储服务-│ │ ├── image/ # 图片处理-│ │ ├── location/ # 地理位置-│ │ └── pipeline-queue/ # 处理队列-│ ├── tasks/ # 后台任务-│ └── utils/ # 服务端工具-├── shared/ # 前后端共享代码-│ ├── types/ # TypeScript 类型定义-│ └── utils/ # 共享工具函数-├── docs/ # 项目文档-├── scripts/ # 构建和部署脚本-└── 配置文件...-```--### 技术栈--#### 前端技术--- **Nuxt 4**: Vue.js 全栈框架-- **TypeScript**: 类型安全的 JavaScript-- **TailwindCSS**: 实用优先的 CSS 框架--#### 后端技术--- **Nitro**: 服务端框架-- **SQLite**: 轻量级数据库-- **Drizzle ORM**: 类型安全的 ORM-- **Sharp**: 高性能图片处理-- **ExifTool**: EXIF 数据提取--## 开发流程--### 启动开发服务器--```bash-# 启动完整开发服务器+corepack enable+pnpm install --frozen-lockfilepnpm dev--# 或分步启动-pnpm build:deps # 构建 WebGL 包-pnpm dlx nuxi@latest dev # 只启动 Nuxt 开发服务器```-### 数据库操作+打开 `http://localhost:3000`,按设置向导创建管理员并选择本地存储。开发时可以使用 `./data/storage`。数据库在启动时自动迁移,无需为启动项目生成新的迁移文件,也无需填写最小环境变量配置。-```bash-# 生成迁移文件-pnpm db:generate--# 执行数据库迁移-pnpm db:migrate-```--### 构建项目+## 常用命令```bash-# 构建 WebGL 依赖包+pnpm lint+pnpm fmt:checkpnpm build:deps--# 构建完整项目pnpm build--# 预览生产构建pnpm preview+pnpm docs:dev+pnpm docs:build```-## 测试环境--### 本地 MinIO 存储--使用 Docker 运行本地 MinIO 服务:--```bash-# 启动 MinIO-docker run -d \- --name minio \- -p 9000:9000 \- -p 9001:9001 \- -e "MINIO_ROOT_USER=minioadmin" \- -e "MINIO_ROOT_PASSWORD=minioadmin" \- minio/minio server /data --console-address ":9001"-```--访问 MinIO 控制台:http://localhost:9001--### GitHub OAuth 应用--1. 访问 GitHub Settings > Developer settings > OAuth Apps-2. 创建新的 OAuth 应用-3. 设置回调 URL:`http://localhost:3000/api/auth/github`-4. 复制 Client ID 和 Client Secret 到 `.env` 文件--### Mapbox 开发令牌--1. 注册 [Mapbox 账户](https://account.mapbox.com/)-2. 创建开发用的访问令牌-3. 设置 URL 限制:`http://localhost:3000`-4. 将令牌添加到 `.env` 文件--## 代码规范--### TypeScript 规范--```typescript-// ✅ 好的做法-interface PhotoMetadata {- id: string- title?: string- width: number- height: number- createdAt: Date-}--// ❌ 避免使用 any-const processPhoto = (photo: any) => { ... }--// ✅ 使用具体类型-const processPhoto = (photo: PhotoMetadata) => { ... }-```--### Vue 组件规范--```vue-<!-- ✅ 推荐的组件结构 -->-<script setup lang="ts">-// 导入-import { ref, computed } from 'vue'-import type { Photo } from '~/types'--// Props 和 Emits-interface Props {- photos: Photo[]- loading?: boolean-}--interface Emits {- select: [photo: Photo]- delete: [photoId: string]-}--const props = withDefaults(defineProps<Props>(), {- loading: false,-})--const emit = defineEmits<Emits>()--// 响应式数据-const selectedPhoto = ref<Photo | null>(null)--// 计算属性-const photoCount = computed(() => props.photos.length)--// 方法-const handlePhotoClick = (photo: Photo) => {- selectedPhoto.value = photo- emit('select', photo)-}-</script>--<template>- <div class="photo-grid">- <!-- 模板内容 -->- </div>-</template>--<style scoped>-/* 组件样式 */-</style>-```--### 数据库调用--在 `server` 中使用数据库操作时,使用 `useDB()` 获取数据库的 Drizzle 实例。该 composable 在服务端是全局自动导入的:--```typescript-const db = useDB()--const photos = await db.select().from(photosTable)-```--### 提交信息规范--使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范:--```-feat: 添加照片批量删除功能-fix: 修复 WebGL 查看器在 Safari 中的兼容性问题-docs: 更新部署文档-style: 统一代码格式-refactor: 重构存储服务接口-test: 添加照片上传的单元测试-chore: 更新依赖包版本-```--## 贡献指南--### 开发流程--1. **Fork 项目**: 在 GitHub 上 fork 项目-2. **创建分支**: `git checkout -b feature/new-feature`-3. **开发功能**: 编写代码和测试-4. **提交更改**: 使用规范的提交信息-5. **推送分支**: `git push origin feature/new-feature`-6. **创建 PR**: 在 GitHub 上创建 Pull Request--### Pull Request 检查清单--提交 PR 前请确保:--- 代码通过所有测试-- 遵循代码规范-- 更新相关文档-- 添加适当的测试用例-- PR 描述清晰,包含变更说明--## 贡献机会--### 适合新手的任务--寻找标有以下标签的 Issues:+`pnpm dev` 同时启动 WebGL 包的开发构建和 Nuxt。已有依赖构建时,可使用 `pnpm dev:only` 单独启动 Nuxt。代码检查使用 Oxlint,格式化使用 Oxfmt。-- `good first issue`: 适合新手的任务-- `help wanted`: 需要社区帮助的任务-- `documentation`: 文档相关的改进+修改数据库 schema 后使用 `pnpm db:generate` 生成迁移,并检查生成的 SQL;`pnpm db:migrate` 可手动应用迁移。提交前不要把本地数据库、照片或访问密钥放进 Git。-## 有用资源+## 代码位置-### 官方文档+- `app/`:页面、组件、composables 和 Pinia stores。+- `packages/webgl-image/`:WebGL 图片查看器。+- `server/api/`:API;`server/services/`:存储、设置和照片处理服务。+- `server/database/`:Drizzle schema 和迁移。+- `shared/`:前后端共享类型;`i18n/`:翻译。+- `docs/`:英文和中文文档。-- [Nuxt 4 文档](https://nuxt.com/)-- [Vue 3 文档](https://vuejs.org/)-- [Drizzle ORM 文档](https://orm.drizzle.team/)-- [TailwindCSS 文档](https://tailwindcss.com/)+新增后台设置请阅读[设置开发指南](/zh/development/how-to-add-setting)。调试 S3、OpenList、地图或 GitHub 登录时,在后台填入测试服务的参数,OAuth 回调地址使用 `http://localhost:3000/api/auth/github`。-### 社区资源+## 提交更改-- [GitHub Issues](https://github.com/HoshinoSuzumi/chronoframe/issues)-- [GitHub Discussions](https://github.com/HoshinoSuzumi/chronoframe/discussions)+保持改动集中,使用 Conventional Commits 描述更改。PR 中说明解决的问题、最终行为和验证结果;涉及界面时附上截图,涉及文档时同步更新英文和中文。可从 GitHub 的 `good first issue` 和 `help wanted` 问题开始。diff --git a/docs/zh/development/how-to-add-setting.md b/docs/zh/development/how-to-add-setting.mdnew file mode 100644index 00000000..0c33518a--- /dev/null+++ b/docs/zh/development/how-to-add-setting.md@@ -0,0 +1,112 @@+# 如何添加一个新的设置项++以在 `app` 命名空间中添加 `foo` 字段为例。++## 步骤 1:在 DEFAULT_SETTINGS 中添加字段定义++编辑 `server/services/settings/contants.ts`,在 `DEFAULT_SETTINGS` 中对应的命名空间部分添加:++```typescript+// NAMESPACE: app+{+ namespace: 'app',+ key: 'foo',+ type: 'string',+ defaultValue: 'bar',+ isPublic: true,+},+```++字段说明(必需):++- `namespace`: 设置所属的命名空间 (app, map, location, storage, system 等)+- `key`: 字段的唯一键+- `type`: 类型 (string, number, boolean 等)+- `defaultValue`: 默认值++字段说明(可选):++- `isPublic`: 是否公开+- `isReadonly`: 是否只读+- `isSecret`: 是否为机密字段(如密码)+- `enum`: 枚举值数组++> 💡 **注意**:不需要在 DEFAULT_SETTINGS 中添加 `label` 和 `description`。SettingField 组件会自动生成翻译键 `settings.${namespace}.${key}.label` 和 `settings.${namespace}.${key}.description`++## 步骤 2:添加 UI 配置++编辑 `server/services/settings/ui-config.ts`,在对应的 UI 配置对象中添加:++```typescript+export const APP_SETTINGS_UI: Record<string, FieldUIConfig> = {+ // ... 其他配置+ foo: {+ type: 'input', // 字段类型:input, password, url, textarea, select, radio, tabs, toggle, number+ placeholder: 'Enter foo value',+ help: 'settings.app.foo.help', // 翻译键,可选+ required: true, // 是否必需,可选+ },+}+```++## 步骤 3:添加翻译++编辑 `i18n/locales/` 中的翻译文件(例如 `en.json`):++```json+{+ "settings": {+ "app": {+ "foo": {+ "label": "Foo",+ "description": "The foo setting",+ "help": "This is the help text for foo"+ }+ }+ }+}+```++## 步骤 4:在页面中使用++编辑 `app/pages/dashboard/settings/general.vue`,直接在模板中使用:++```vue+<template>+ <UDashboardPanel>+ <!-- ... -->+ <UForm class="space-y-4">+ <SettingField+ v-for="field in fields"+ :key="field.key"+ :field="field"+ :model-value="state[field.key]"+ @update:model-value="(val) => (state[field.key] = val)"+ />+ </UForm>+ </UDashboardPanel>+</template>+```++✅ 完成!`foo` 字段会自动被 `useSettingsForm('app')` 获取并渲染。++## 条件字段示例++如果需要根据其他字段来显示/隐藏某个字段,在 UI 配置中添加 `visibleIf`:++```typescript+foo: {+ type: 'input',+ placeholder: 'Only show when bar = "baz"',+ visibleIf: { fieldKey: 'bar', value: 'baz' },+}+```++## 其他命名空间++- `map`:地图相关设置+- `location`:位置相关设置+- `storage`:存储相关设置+- `system`:系统设置++流程相同,只需修改对应的 UI 配置对象(`MAP_SETTINGS_UI`、`LOCATION_SETTINGS_UI` 等)。diff --git a/docs/zh/guide/configuration.md b/docs/zh/guide/configuration.mdindex 6bc2ab07..38d0fdc9 100644--- a/docs/zh/guide/configuration.md+++ b/docs/zh/guide/configuration.md@@ -1,79 +1,5 @@-# 配置项说明+# 旧配置文档-无论是使用 Docker 还是 Docker Compose (.env) 方式部署,均通过环境变量进行配置。+此页已归档。新部署请使用[设置向导](/zh/guide/getting-started),已有实例的设置可在后台修改。-## 环境变量列表--| 环境变量 | 说明 | 默认值 | 必需 |-| ---------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------- | --------------------------------------------------------------------- |-| CFRAME_ADMIN_EMAIL | 初始管理员用户的邮箱 | `[email protected]` | 是 |-| CFRAME_ADMIN_NAME | 初始管理员用户的用户名 | `Chronoframe` | 否 |-| CFRAME_ADMIN_PASSWORD | 初始管理员用户的密码 | `CF1234@!` | 否 |-| NUXT_PUBLIC_APP_TITLE | 应用标题 | `ChronoFrame` | 否 |-| NUXT_PUBLIC_APP_SLOGAN | 应用口号 | 无 | 否 |-| NUXT_PUBLIC_APP_AUTHOR | 应用作者 | 无 | 否 |-| NUXT_PUBLIC_APP_AVATAR_URL | 应用头像 URL | 无 | 否 |-| NUXT_PUBLIC_COLOR_MODE_PREFERENCE | 颜色模式偏好,可选 `light`、`dark`、`system` | system | 否 |-| NUXT_PUBLIC_MAP_PROVIDER | 地图提供者,可选 `mapbox`、`maplibre` | `maplibre` | 否 |-| NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN | Mapbox 访问令牌(可限制 URL),用于地图服务 | 无 | 当 `NUXT_PUBLIC_MAP_PROVIDER` 为 `mapbox` 时必需 |-| NUXT_NOMINATIM_BASE_URL | Nominatim 反向地理编码服务的基础 URL | `https://nominatim.openstreetmap.org` | 否 |-| NUXT_MAPBOX_ACCESS_TOKEN | Mapbox 访问令牌(无 URL 限制),用于位置信息服务 | 无 | 否 |-| NUXT_STORAGE_PROVIDER | 存储提供者,支持 `local`、`s3`、`openlist` | `local` | 是 |-| NUXT_PROVIDER_LOCAL_PATH | 本地存储路径 | `/app/data/storage` | 否 |-| NUXT_PROVIDER_LOCAL_BASE_URL | 本地存储的访问 URL | `/storage` | 否 |-| NUXT_PROVIDER_S3_ENDPOINT | S3 兼容存储服务的 Endpoint | 无 | 当 `NUXT_STORAGE_PROVIDER` 为 `s3` 时必需 |-| NUXT_PROVIDER_S3_BUCKET | S3 存储桶名称 | `chronoframe` | 当 `NUXT_STORAGE_PROVIDER` 为 `s3` 时必需 |-| NUXT_PROVIDER_S3_REGION | S3 存储桶区域 | `auto` | 当 `NUXT_STORAGE_PROVIDER` 为 `s3` 时必需 |-| NUXT_PROVIDER_S3_ACCESS_KEY_ID | S3 访问密钥 ID | 无 | 当 `NUXT_STORAGE_PROVIDER` 为 `s3` 时必需 |-| NUXT_PROVIDER_S3_SECRET_ACCESS_KEY | S3 访问密钥 | 无 | 当 `NUXT_STORAGE_PROVIDER` 为 `s3` 时必需 |-| NUXT_PROVIDER_S3_PREFIX | S3 存储前缀 | `photos/` | 否 |-| NUXT_PROVIDER_S3_CDN_URL | S3 存储的 CDN 地址 | 无 | 否 |-| NUXT_PROVIDER_OPENLIST_BASE_URL | OpenList 服务器 URL | 无 | 当 `NUXT_STORAGE_PROVIDER` 为 `openlist` 时必需 |-| NUXT_PROVIDER_OPENLIST_ROOT_PATH | OpenList 根路径 | 无 | 当 `NUXT_STORAGE_PROVIDER` 为 `openlist` 时必需 |-| NUXT_PROVIDER_OPENLIST_TOKEN | OpenList API 令牌 | 无 | 当 `NUXT_STORAGE_PROVIDER` 为 `openlist` 时必需(用于 OpenList 认证) |-| NUXT_PROVIDER_OPENLIST_ENDPOINT_UPLOAD | OpenList 上传端点 | `/api/fs/put` | 否 |-| NUXT_PROVIDER_OPENLIST_ENDPOINT_DOWNLOAD | OpenList 下载端点 | 无 | 否 |-| NUXT_PROVIDER_OPENLIST_ENDPOINT_LIST | OpenList 列表端点 | 无 | 否 |-| NUXT_PROVIDER_OPENLIST_ENDPOINT_DELETE | OpenList 删除端点 | `/api/fs/remove` | 否 |-| NUXT_PROVIDER_OPENLIST_ENDPOINT_META | OpenList 元数据端点 | `/api/fs/get` | 否 |-| NUXT_PROVIDER_OPENLIST_PATH_FIELD | OpenList 路径字段名 | `path` | 否 |-| NUXT_PROVIDER_OPENLIST_CDN_URL | OpenList CDN 地址 | 无 | 否 |-| NUXT_PUBLIC_OAUTH_GITHUB_ENABLED | 是否启用 GitHub OAuth 登录 | `false` | 否 |-| NUXT_OAUTH_GITHUB_CLIENT_ID | GitHub OAuth 应用的 Client ID | 无 | 否(可选,用于 GitHub 登录) |-| NUXT_OAUTH_GITHUB_CLIENT_SECRET | GitHub OAuth 应用的 Client Secret | 无 | 否(可选,用于 GitHub 登录) |-| NUXT_SESSION_PASSWORD | 用于加密会话的密码,32 位随机字符串 | 无 | 是 |-| NUXT_TRUST_PROXY | 相簿解锁限流是否信任 `X-Forwarded-For`;仅在可信反代覆盖客户端同名请求头时启用 | `false` | 否 |-| NUXT_PUBLIC_GTAG_ID | Google Analytics 追踪 ID | 无 | 否 |-| NUXT_PUBLIC_ANALYTICS_MATOMO_ENABLED | 是否启用 Matomo 分析追踪 | `false` | 否 |-| NUXT_PUBLIC_ANALYTICS_MATOMO_URL | Matomo 实例 URL 地址(如: https://matomo.example.com) | 无 | 否(启用 Matomo 时必需) |-| NUXT_PUBLIC_ANALYTICS_MATOMO_SITE_ID | Matomo 站点 ID | 无 | 否(启用 Matomo 时必需) |-| NUXT_UPLOAD_MIME_WHITELIST_ENABLED | 是否启用上传文件 MIME 类型白名单验证 | `true` | 否 |-| NUXT_UPLOAD_MIME_WHITELIST | 上传文件允许的 MIME 类型列表(逗号分隔) | 见下方说明 | 否 |-| ALLOW_INSECURE_COOKIE | 是否允许非安全 Cookie(仅在开发环境使用) | `false` | 否 |--## 上传文件类型白名单--`NUXT_UPLOAD_MIME_WHITELIST` 的默认值包含以下 MIME 类型:--- `image/jpeg` - JPEG 图片-- `image/png` - PNG 图片-- `image/webp` - WebP 图片-- `image/gif` - GIF 图片-- `image/bmp` - BMP 图片-- `image/tiff` - TIFF 图片-- `image/heic` - HEIC 图片(Apple)-- `image/heif` - HEIF 图片-- `video/quicktime` - QuickTime 视频(MOV)-- `video/mp4` - MP4 视频--如需自定义白名单,请使用逗号分隔的 MIME 类型字符串,例如:--```-NUXT_UPLOAD_MIME_WHITELIST=image/jpeg,image/png,video/mp4-```--如需禁用白名单验证(允许任何文件类型),可设置:--```-NUXT_UPLOAD_MIME_WHITELIST_ENABLED=false-```+[查看历史文档](/zh/legacy/guide/configuration)diff --git a/docs/zh/guide/getting-started.md b/docs/zh/guide/getting-started.mdindex 0248961f..4eed0ea1 100644--- a/docs/zh/guide/getting-started.md+++ b/docs/zh/guide/getting-started.md@@ -1,119 +1,10 @@# 快速开始-本文档将指导您如何快速部署并开始使用 ChronoFrame。+ChronoFrame 使用 SQLite 保存照片信息和设置,无需单独部署数据库。准备好 Docker 和一个用于持久化数据的目录,就可以启动。-:::warning 🚧施工中-文档正在编写中,部分功能文档尚未完成。-:::+## 启动容器-## 前置准备--- 可用的 [Docker](https://docs.docker.com/get-docker/) 环境。-- 存储后端:可以直接使用内置本地文件系统,也可以配置任意兼容 S3 协议的对象存储。详见 [存储提供者](/zh/configuration/storage-providers)。- :::tip S3 参数清单- 若使用 S3,请准备:`ACCESS_KEY_ID`、`SECRET_ACCESS_KEY`、`ENDPOINT`、`BUCKET_NAME`、`REGION`,以及(可选)当外链域名与 ENDPOINT 不同时的 `CDN_URL`。- :::-- (可选)[GitHub OAuth 应用](https://github.com/settings/applications/new)(用于启用 GitHub 登录,需要 `CLIENT_ID` 与 `CLIENT_SECRET`)。- :::tip 回调地址- 在 GitHub OAuth 应用中将 Authorization callback URL 设为:`http(s)://<你的域名>/api/auth/github`- :::- :::info- 未配置 GitHub OAuth 也能使用默认管理员账号(首次启动自动创建)登录。- :::--## 快速部署--### 拉取镜像--我们推荐使用预构建的 Docker 镜像进行部署,镜像托管在 GHCR 和 Docker Hub,您可以根据网络情况选择合适的源。--#### [GitHub Container Registry (GHCR)](https://github.com/HoshinoSuzumi/chronoframe/pkgs/container/chronoframe)--```bash-docker pull ghcr.io/hoshinosuzumi/chronoframe:latest-```--#### [Docker Hub](https://hub.docker.com/r/hoshinosuzumi/chronoframe)--```bash-docker pull hoshinosuzumi/chronoframe:latest-```--### 创建配置文件--创建 `.env` 文件。下面是使用本地存储的最小示例,完整配置请参阅 [配置说明](/zh/guide/configuration)。--```bash-# 管理员邮箱(必须)-CFRAME_ADMIN_EMAIL=-# 管理员用户名(可选,默认 ChronoFrame)-CFRAME_ADMIN_NAME=-# 管理员密码(可选,默认 CF1234@!)-CFRAME_ADMIN_PASSWORD=--# 站点信息(均可选)-NUXT_PUBLIC_APP_TITLE=-NUXT_PUBLIC_APP_SLOGAN=-NUXT_PUBLIC_APP_AUTHOR=-NUXT_PUBLIC_APP_AVATAR_URL=--# 地图提供器 (maplibre/mapbox)-NUXT_PUBLIC_MAP_PROVIDER=maplibre-# 使用 MapLibre 需要 MapTiler 访问令牌-NUXT_PUBLIC_MAP_MAPLIBRE_TOKEN=-# 使用 Mapbox 需要 Mapbox 访问令牌-NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=--# 存储提供者(local 或 s3 或 openlist)-NUXT_STORAGE_PROVIDER=local-NUXT_PROVIDER_LOCAL_PATH=/app/data/storage--# 会话密码(必须,32 位随机字符串)-NUXT_SESSION_PASSWORD=-```--若选择使用 S3,请将存储部分替换为:--```bash-NUXT_STORAGE_PROVIDER=s3-NUXT_PROVIDER_S3_ENDPOINT=-NUXT_PROVIDER_S3_BUCKET=chronoframe-NUXT_PROVIDER_S3_REGION=auto-NUXT_PROVIDER_S3_ACCESS_KEY_ID=-NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=-NUXT_PROVIDER_S3_PREFIX=photos/-NUXT_PROVIDER_S3_CDN_URL=-```--若选择使用 openlist,请将存储部分替换为:--```bash-NUXT_STORAGE_PROVIDER=openlist-NUXT_PROVIDER_OPENLIST_BASE_URL=https://openlist.example.com-NUXT_PROVIDER_OPENLIST_ROOT_PATH=/115pan/chronoframe-NUXT_PROVIDER_OPENLIST_TOKEN=your-static-token-```--可选 GitHub OAuth 变量:--```bash-NUXT_OAUTH_GITHUB_CLIENT_ID=-NUXT_OAUTH_GITHUB_CLIENT_SECRET=-```--### Docker 单容器部署--#### 快速启动--```bash-docker run -d --name chronoframe -p 3000:3000 -v $(pwd)/data:/app/data --env-file .env ghcr.io/hoshinosuzumi/chronoframe:latest-```--### Docker Compose 部署--推荐使用 Docker Compose 进行生产环境部署,便于管理和配置。--#### 1. 创建 `docker-compose.yml` 文件+创建 `docker-compose.yml`:```yamlservices:@@ -125,129 +16,66 @@ services:- '3000:3000'volumes:- ./data:/app/data- env_file:- - .env```-#### 2. 启动 ChronoFrame 服务+也可以将镜像名换成 `hoshinosuzumi/chronoframe:latest`,从 Docker Hub 拉取。```bash-# 启动服务docker compose up -d--# 查看日志docker compose logs -f chronoframe+```-# 停止服务-docker compose down+习惯直接使用 Docker 的话:-# 更新到最新版本-docker compose pull-docker compose up -d+```bash+docker run -d --name chronoframe --restart unless-stopped \+ -p 3000:3000 -v "$(pwd)/data:/app/data" \+ ghcr.io/hoshinosuzumi/chronoframe:latest```-## 反向代理+打开 `http://localhost:3000`,首次访问会进入设置向导。新部署不需要先填写 `.env`。-在生产环境中部署时,您通常需要一个反向代理服务器(如 Nginx 或 Caddy)来处理 HTTPS 和域名解析。以下是一些示例配置。+## 完成设置向导-使用下方 Nginx 或 Traefik 示例时,请在 `.env` 中设置 `NUXT_TRUST_PROXY=true`,并确保 3000 端口只能由反向代理访问。若代理会原样转发客户端提供的 `X-Forwarded-For`,请勿启用此选项。+1. **管理员**:填写邮箱、用户名和密码,之后使用这组凭据登录。不要沿用旧教程中的默认密码。+2. **站点信息**:填写画廊名称、介绍、作者和头像。+3. **存储**:选择本地存储、S3 或 OpenList。本地存储的路径填写 `/app/data/storage`,这样照片会随数据卷保存。+4. **地图**:选择 MapLibre 或 Mapbox,并填写相应服务的令牌和样式。也可以暂不填写令牌,稍后在后台补充。没有可用的地图服务时,相关地图不会正常展示。+5. 确认并完成向导,进入后台。-### Nginx+S3 需要准备 Endpoint、Bucket、Region、Access Key ID 和 Secret Access Key,可另设 CDN 地址。OpenList 需要服务地址、根目录和访问令牌。连接信息直接填写到向导或后台,无需换成环境变量。-```nginx-server {- listen 80;- server_name your-domain.com;+## 保存数据- # HTTPS 重定向- return 301 https://$server_name$request_uri;-}+`./data:/app/data` 是部署中必须保留的挂载。默认数据库为 `/app/data/app.sqlite3`,会话密钥自动生成并保存在 `/app/data/.session-password`。使用上述本地路径时,原图和衍生文件也在这个目录下。-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 $remote_addr;- 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 /_nuxt/ {- proxy_pass http://localhost:3000;- expires 1y;- add_header Cache-Control "public, immutable";- proxy_set_header Host $host;- }-}-```+不要删除数据目录来更新应用。S3 和 OpenList 的文件存放在外部服务中,需要另外备份;只备份数据库无法恢复丢失的原图。-### Traefik+## 使用域名和 HTTPS-如果您使用 Traefik 作为反向代理,可以在 `docker-compose.yml` 中添加标签:+可以在容器前使用 Caddy、Nginx 或 Traefik。反向代理的上传大小上限应与后台设置匹配,并保留流式响应,供实时日志使用。++只有在 3000 端口只能被可信代理访问、且代理会覆盖用户传入的 `X-Forwarded-For` 时,才启用 `NUXT_TRUST_PROXY=true`。这项部署设置仍使用环境变量,例如在 Compose 中加入:```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+environment:+ NUXT_TRUST_PROXY: 'true'```-## 常见问题--:::details 如何生成随机的 `NUXT_SESSION_PASSWORD`?--```bash-# Linux / macOS-openssl rand -base64 32+Nginx 的应用代理段可参考:-# Windows (pwsh)-[Convert]::ToBase64String((1..32|%{[byte](Get-Random -Max 256)}))+```nginx+location / {+ proxy_pass http://127.0.0.1:3000;+ proxy_set_header Host $host;+ proxy_set_header X-Forwarded-For $remote_addr;+ proxy_set_header X-Forwarded-Proto $scheme;+ proxy_buffering off;+ proxy_read_timeout 300s;+ client_max_body_size 256M;+}```-:::+## 接下来++进入[日常使用](/zh/guide/usage)了解上传、相册和后台设置。已有旧版实例请先阅读[升级指南](/zh/guide/updates)。diff --git a/docs/zh/guide/updates.md b/docs/zh/guide/updates.mdindex 6f8f3cfd..53bee8f5 100644--- a/docs/zh/guide/updates.md+++ b/docs/zh/guide/updates.md@@ -1,117 +1,44 @@# 升级指南-本文档将指导您如何安全地更新和升级 ChronoFrame 到最新版本。+升级前先查看[更新日志](/zh/changelog),确定目标版本及其迁移说明。可以在后台概览的运行信息中查看当前版本。-## 版本检查+## 备份-### 查看当前版本--#### 通过 Web 界面--1. 登录 ChronoFrame 管理后台-2. 进入「仪表板」页面-3. 查看「运行信息」面板中的版本号--## 更新流程--### 准备工作--#### 1. 数据备份+停止容器后备份整个数据目录和 Compose 文件。如果旧部署仍使用 `.env`,也要保存它;本地存储不在 `data` 中时,需要额外备份对应目录。S3 和 OpenList 的文件应在外部服务中单独备份。```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/+docker compose stop chronoframe+mkdir -p backups+cp -a data "backups/data-$(date +%Y%m%d-%H%M%S)"+cp docker-compose.yml backups/docker-compose.yml```-#### 2. 检查兼容性--查看 [发布说明](https://github.com/HoshinoSuzumi/chronoframe/releases) 了解:--- 破坏性变更-- 新增环境变量-- 功能弃用通知+## 更新镜像-### Docker Compose 更新(推荐)--#### 标准更新流程+在 Compose 文件中将镜像标签改为目标版本,例如 `v1.0.0`,然后执行:```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+docker compose pull chronoframe+docker compose up -d chronoframe+docker compose logs -f chronoframe```-#### 指定版本更新+容器启动时会自动执行数据库迁移,正常情况下无需手动运行迁移命令。当前运行镜像不包含 shell 和包管理器,旧文档中的 `docker exec ... sh` 或容器内 `npx drizzle-kit migrate` 不适用。-如果需要更新到特定版本:+直接使用 `docker run` 的部署,先停止并移除旧容器,再用新标签和相同的数据挂载重建。保留原有的端口、网络和仍有用途的部署环境变量。-```yaml-# docker-compose.yml-services:- chronoframe:- image: ghcr.io/hoshinosuzumi/chronoframe:v1.2.3 # 指定版本- # ... 其他配置-```+## 从 v0.14.1 升级到 1.0.0-```bash-docker-compose up -d-```--### 单容器更新--```bash-# 停止现有容器-docker stop chronoframe-docker rm chronoframe+- 使用 `v1.0.0` 标签固定版本,或使用 `latest` 跟随正式版。+- 首次升级时先保留旧环境变量,让应用迁移可识别的设置和存储方案。启动后在后台核对站点、地图、登录和存储是否正确,再整理旧 `.env`。+- 1.0.0 修复了重启覆盖后台设置的问题,后续以后台保存的设置为准。+- 如果升级后进入向导,使用已有管理员邮箱,确认原存储路径,不要新建空数据目录。先核对挂载和启动日志,再继续操作。+- 会话密钥、数据库、存储路径等部署数据必须保留。代理信任等部署选项仍由运行环境提供,不属于可删除的旧站点设置。-# 拉取最新镜像-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-```--## 数据库迁移+确认能登录后台,打开几张已有照片,尝试上传一张照片,并检查相册、地图和任务队列。1.0.0 新增了隐藏相册照片的访问限制,升级后也应检查公开画廊。-### 自动迁移+## 回退-ChronoFrame 在启动时会自动执行数据库迁移:--```bash-# 查看迁移日志-docker logs chronoframe | grep -i migration-```--### 手动迁移(高级)--在特殊情况下,您可能需要手动执行迁移:--```bash-# 进入容器-docker exec -it chronoframe sh--# 执行迁移-npx drizzle-kit migrate-```+数据库迁移可能改变结构。需要回退时,停止新容器,恢复升级前的完整数据备份,再使用原版本标签启动。不要只降级镜像并继续使用已经迁移的数据库。diff --git a/docs/zh/guide/usage.md b/docs/zh/guide/usage.mdnew file mode 100644index 00000000..9470a864--- /dev/null+++ b/docs/zh/guide/usage.md@@ -0,0 +1,53 @@+# 日常使用++## 上传和整理照片++登录后访问 `/dashboard`,在照片页选择文件或拖入文件,支持批量上传。上传完成后,后台继续提取 EXIF、生成缩略图并识别拍摄地点;可以在任务队列中查看进度、失败原因和重试结果。++- 照片表格支持排序、筛选和自选显示列,并记住列的显示状态,也支持按上传日期排序。+- 选中照片后可以批量删除、下载、重新索引或加入相册。支持 Shift + 单击连续选择。+- 编辑照片可以修改标题、描述、评分等元数据。+- Apple Live Photo 的照片和 MOV 文件使用同一文件名,例如 `IMG_1234.heic` 和 `IMG_1234.mov`。上传顺序不限,配对失败时可在后台重新处理。+- 也支持带有嵌入视频的 Motion Photo。大图由 WebGL 查看器显示,支持平移、缩放和分块渲染。++## 相册和可见性++相册可将同一主题的照片集中展示,支持相册排序和相册内照片排序。++隐藏相册用于限制公开展示,同时限制匿名访客访问其中的照片,即使该照片还属于公开相册;请在调整可见性后检查公开画廊的结果。++也可以为相册设置密码,密码至少 6 个字符。访客需要解锁才能在 ChronoFrame 中查看相册内容,分享其中照片时也会保留相册访问范围。++::: warning 外部存储的访问边界+相册密码限制的是 ChronoFrame 内的访问。S3、OpenList 或 CDN 如果提供可直接访问的图片地址,知道地址的人仍可能绕过相册页面读取文件。需要保护文件本身时,应同时检查存储服务和 CDN 的访问策略。隐藏相册也不能收回已经公开的外部链接。+:::++## 在后台修改设置++站点信息、地图、位置服务、存储和上传限制均可在后台修改。设置保存在数据库中;无需编辑 `.env` 或重建容器。++| 设置 | 用途 |+| ---- | --------------------------------------------------------- |+| 站点 | 名称、介绍、作者、头像和明暗主题 |+| 存储 | 新增和编辑本地、S3、OpenList 存储方案,选择当前使用的方案 |+| 地图 | MapLibre / Mapbox、访问令牌和地图样式 |+| 位置 | 地名语言、Mapbox 反向地理编码令牌、自定义 Nominatim 地址 |+| 系统 | 单文件上传大小、重复文件处理、GitHub 登录 |+| 隐私 | 上传时自动移除位置信息 |+| 分析 | 注入到页面 head 或 body 的自定义统计脚本 |++地图负责显示,位置服务负责将 GPS 坐标转换成地名,两者分别设置。更改地名语言后,已有照片需要重新索引位置才能更新保存的地名。++更换存储方案前,请确认已有照片仍能访问。选择新方案不等于将原图自动搬到新存储中。本地存储路径必须位于已挂载的目录内,容器才能在重建后继续访问文件。++隐私设置影响之后的上传,不会自动清理过去上传的文件。已有照片可以在照片管理中单独或批量执行移除位置信息,并在任务队列中确认完成。公开前也应检查照片描述和标签是否含有不希望分享的信息。++## GitHub 登录++先使用向导创建的邮箱和密码登录,再在系统设置中开启 GitHub OAuth,填写 Client ID 和 Client Secret。OAuth 应用的回调地址填写 `https://你的域名/api/auth/github`。++GitHub 返回的邮箱需要匹配已有管理员的邮箱。启用 OAuth 不会让任意 GitHub 用户成为管理员;未获授权的账号会被拒绝登录。++## 排查上传问题++任务队列显示处理进度和失败原因,日志页可以查看实时日志和历史记录。遇到上传被拒绝时,先核对应用和反向代理的文件大小限制;遇到存储失败时,检查目录写入权限或远端凭据。反馈问题时附上版本号、使用的存储类型和相关日志,并去掉令牌、密钥等私人信息。diff --git a/docs/zh/index.md b/docs/zh/index.mdindex 8965b098..ff0a33e1 100644--- a/docs/zh/index.md+++ b/docs/zh/index.md@@ -5,7 +5,7 @@ layout: homehero:name: 'ChronoFrame'text: '自部署个人画廊'- tagline: '在线管理照片,多存储后端、LivePhoto、地球仪视图'+ tagline: '上传、整理和分享照片,在网页中完成站点设置'image:src: /logo.pngalt: ChronoFrame@@ -18,8 +18,8 @@ hero:text: 查看 GitHublink: https://github.com/HoshinoSuzumi/chronoframe- theme: alt- text: 查看演示- link: https://lens.bh8.ga+ text: 演示站点+ link: /zh/demo-sitesfeatures:- title: 强大的照片管理@@ -27,16 +27,16 @@ features:details: 通过网页界面轻松管理和浏览照片,并在地图上查看照片拍摄地点。- title: 简单部署icon: 🚀- details: 使用 Docker 一条命令即可部署,无需数据库(基于 SQLite3)。+ details: 使用 Docker 启动后,通过设置向导创建管理员和选择存储。SQLite 数据库随应用运行,无需单独部署。- title: 灵活的存储方案icon: 💾- details: 支持多种存储后端,包括兼容 S3 的存储和本地文件系统。+ details: 支持本地文件系统、S3 兼容存储和 OpenList,在后台管理存储方案。- title: 智能地理位置icon: 🌍- details: 自动提取照片 GPS 信息,使用 Mapbox 进行地理编码,在地图上展示照片拍摄位置。- - title: 响应式设计+ details: 提取照片 GPS,通过反向地理编码识别地点,使用 MapLibre 或 Mapbox 浏览地图。+ - title: 相册与隐私icon: 📱- details: 完美适配桌面端和移动端,支持触摸操作和手势控制,提供原生应用般的体验。+ details: 整理相册和照片顺序,设置隐藏相册或密码相册,控制画廊中的访问。- title: Live/Motion Photo 支持icon: 🎬details: 完整支持 Apple LivePhoto 格式和 Google 标准的 Motion Photo,自动检测和处理 MOV 视频文件,保留动态照片效果。@@ -44,23 +44,11 @@ features:## 🌍 演示站点-下面是一些由开发者、社区成员搭建的,运行良好的 ChronoFrame 实例:--- [**TimoYin's Mems**](https://lens.bh8.ga)-- [**懒洋洋喝咖啡**](https://oreo.tanmantang.com) — 用镜头记录每个精彩瞬间-- [**My Photo Gallery**](https://photo.fivk.cn)-- [**An ISFP Conductor of Current, Pixels, and Code.**](https://gallery.xiaoten.com)-- [**我的旅行相册**](https://gallery.junlan.site) — 记录光影,留存回忆-- [**Z.Zhou's Photography**](https://photography.zzhou612.com/) — Catch the Moment-- [**Each Photo Turns a Moment Into Eternity.**](https://eachphoto.com)-- [**WhyPhoto**](https://photo.limina.top/)-- [**用图片记录生活**](https://gallery.d.cr)-- [**Ahmet Ömer's Photography**](https://photography.ahmeto.com/)-- [**何来尘埃飞舞**](https://photo.jefftay.com/)+在[演示站点页面](/zh/demo-sites)浏览开发者和社区用户分享的画廊。## 💬 社区支持-- **GitHub Issues**: [报告问题](https://github.com/HoshinoSuzumi/chronoframe/issues)+- **GitHub Issues**: [报告问题](https://github.com/HoshinoSuzumi/chronoframe/issues/new/choose)- **GitHub Discussions**: [讨论分享](https://github.com/HoshinoSuzumi/chronoframe/discussions)- **Discord**: [加入我们](https://discord.gg/MM4ZK4Ed7s)diff --git a/docs/zh/legacy/configuration/location-providers.md b/docs/zh/legacy/configuration/location-providers.mdnew file mode 100644index 00000000..83a270e7--- /dev/null+++ b/docs/zh/legacy/configuration/location-providers.md@@ -0,0 +1,40 @@+---+search: false+---++::: warning 历史文档+本文保留旧版的部署和环境变量说明,仅供维护旧实例时查阅。当前版本请从[快速开始](/zh/guide/getting-started)进入,日常设置在后台完成。+:::++# 位置提供器++位置提供器在处理照片的过程中,将照片的经纬度信息转换为人类可读的城市或国家名称,这一过程成为逆向地理编码(Reverse Geocoding)。++默认情况下,您不需要进行任何配置,ChronoFrame 会使用 OpenStreetMap Nominatim 作为默认的位置提供器。++然而,在下列情况下,您可能有必要配置自定义的位置提供器:++- 服务器位于中国大陆+- 服务器与 Nominatim 之间的连接受阻++ChronoFrame 支持两种位置提供器,您可以根据需求选择合适的提供器。++## Nominatim++Nominatim 是 OpenStreetMap 提供的免费逆向地理编码服务。默认情况下,ChronoFrame 会使用 Nominatim 作为位置提供器。++如果您的服务器无法连接到 Nominatim 官方的服务,您可以自行搭建反向代理,然后通过下面的配置使用自己的地址:++```bash+NUXT_NOMINATIM_BASE_URL=http://your-nominatim-proxy-url/+```++## Mapbox Search API++Mapbox Search API 提供强大的逆向地理编码功能,能够在中国大陆境内访问。要使用 Mapbox 作为位置提供器,您需要一个 [Mapbox 访问令牌](https://console.mapbox.com/account/access-tokens/)。++```bash+NUXT_MAPBOX_ACCESS_TOKEN=your-mapbox-access-token+```++当您配置了 `NUXT_MAPBOX_ACCESS_TOKEN` 环境变量后,ChronoFrame 会自动使用 Mapbox Search API 作为位置提供器。diff --git a/docs/zh/legacy/configuration/map-providers.md b/docs/zh/legacy/configuration/map-providers.mdnew file mode 100644index 00000000..c746cbff--- /dev/null+++ b/docs/zh/legacy/configuration/map-providers.md@@ -0,0 +1,51 @@+---+search: false+---++::: warning 历史文档+本文保留旧版的部署和环境变量说明,仅供维护旧实例时查阅。当前版本请从[快速开始](/zh/guide/getting-started)进入,日常设置在后台完成。+:::++# 地图提供器++ChronoFrame 支持两种地图提供器,您可以根据需求选择合适的提供器。++| 提供器 | 支持 | 额外配置 | 特性 |+| --------------------- | :--: | ----------------- | ------------------------ |+| [MapLibre](#maplibre) | ✅ | MapTiler 访问令牌 | 免费开源,支持自定义样式 |+| [Mapbox](#mapbox) | ✅ | MapBox 访问令牌 | 免费用量,更好的渲染器 |++## MapLibre++要使用 MapLibre 作为地图提供器,您需要一个 [MapTiler 访问令牌](https://cloud.maptiler.com/account/keys/)。++```bash+NUXT_PUBLIC_MAP_PROVIDER=maplibre+NUXT_PUBLIC_MAP_MAPLIBRE_TOKEN=your_maplibre_access_token+```++### 自定义样式++```bash+# ChronoFrame 已经内置了自动切换的浅色和深色两种样式+# 如果配置自定义样式,将会覆盖默认样式+# 示例: https://demotiles.maplibre.org/globe.json+NUXT_PUBLIC_MAP_MAPLIBRE_STYLE=+```++## MapBox++要使用 Mapbox 作为地图提供器,您需要一个 [Mapbox 访问令牌](https://console.mapbox.com/account/access-tokens/)。++```bash+NUXT_PUBLIC_MAP_PROVIDER=mapbox+NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=your_mapbox_access_token+```++### 自定义样式++```bash+# 如果配置自定义样式,将会覆盖默认样式+# 示例: mapbox://styles/mapbox/streets-v11+NUXT_PUBLIC_MAP_MAPBOX_STYLE=+```diff --git a/docs/zh/legacy/configuration/storage-providers.md b/docs/zh/legacy/configuration/storage-providers.mdnew file mode 100644index 00000000..0e2b0e5a--- /dev/null+++ b/docs/zh/legacy/configuration/storage-providers.md@@ -0,0 +1,208 @@+---+search: false+---++::: warning 历史文档+本文保留旧版的部署和环境变量说明,仅供维护旧实例时查阅。当前版本请从[快速开始](/zh/guide/getting-started)进入,日常设置在后台完成。+:::++# 存储提供器配置++ChronoFrame 支持多种存储后端来保存您的照片和缩略图。本文档将详细介绍如何配置不同的存储提供器。++> 密码保护相簿要求媒体 URL 不能绕过 ChronoFrame 授权直接获取。公开访问的 S3 存储桶、OpenList 下载地址或 CDN 不满足此要求:修改相簿密码不会撤销已发出的直链或缓存副本。在支持私有远端对象交付前,请对受保护相簿使用本地存储。若媒体已经公开,还需在存储/CDN 侧关闭公开访问、清理缓存并更换对象地址;只修改相簿设置并不足够。++| 提供器 | 支持 | 适用场景 | 成本 |+| --------------------------------- | :--: | ------------------ | ------------ |+| [**S3 兼容存储**](#s3-兼容存储) | ✅ | 生产环境,云存储 | 按使用量计费 |+| [**本地文件系统**](#本地文件系统) | ✅ | 测试环境,离线部署 | 免费 |+| [**OpenList**](#openlist-存储) | ✅ | 个人云存储,NAS | 免费 |++## S3 兼容存储++S3 兼容存储是最推荐的生产环境选项,支持所有主流云服务提供商。++### 基础配置++```bash+# 设置存储提供器为 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+NUXT_PROVIDER_S3_FORCE_PATH_STYLE=false+```++### 云服务商配置示例++#### AWS S3++```bash+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++```bash+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++```bash+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++```bash+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 自托管++```bash+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+# MinIO 需要启用路径样式访问+NUXT_PROVIDER_S3_FORCE_PATH_STYLE=true+```++### 存储桶配置++#### CORS 设置++推荐的 CORS 配置:++```json+[+ {+ "AllowedOrigins": ["https://your-domain.com"],+ "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],+ "AllowedHeaders": ["*"],+ "ExposeHeaders": ["ETag"],+ "MaxAgeSeconds": 3000+ }+]+```++## 本地文件系统++本地存储将文件保存在服务器文件系统中。++```bash+# 设置存储提供器为本地+NUXT_STORAGE_PROVIDER=local++# 本地存储配置+NUXT_PROVIDER_LOCAL_PATH=/app/data/storage+NUXT_PROVIDER_LOCAL_BASE_URL=/storage+```++## OpenList 存储++OpenList 是一个开源的文件管理系统,提供对各种云存储服务的 API 访问。此提供程序允许您使用与 OpenList 兼容的服务作为照片存储后端。++| 环境变量 | 类型 | 必需 | 默认值 | 描述 |+| ------------------------------------------ | ------ | ---- | ---------------- | ----------------------- |+| `NUXT_PROVIDER_OPENLIST_BASE_URL` | string | 是 | - | OpenList 服务的基础 URL |+| `NUXT_PROVIDER_OPENLIST_ROOT_PATH` | string | 是 | - | 根存储路径 |+| `NUXT_PROVIDER_OPENLIST_TOKEN` | string | 必需 | - | 认证令牌(认证时必需) |+| `NUXT_PROVIDER_OPENLIST_ENDPOINT_UPLOAD` | string | 可选 | `/api/fs/put` | 上传端点 |+| `NUXT_PROVIDER_OPENLIST_ENDPOINT_DOWNLOAD` | string | 可选 | - | 下载端点 |+| `NUXT_PROVIDER_OPENLIST_ENDPOINT_LIST` | string | 可选 | - | 列表端点 |+| `NUXT_PROVIDER_OPENLIST_ENDPOINT_DELETE` | string | 可选 | `/api/fs/remove` | 删除端点 |+| `NUXT_PROVIDER_OPENLIST_ENDPOINT_META` | string | 可选 | `/api/fs/get` | 元数据端点 |+| `NUXT_PROVIDER_OPENLIST_PATH_FIELD` | string | 可选 | `path` | 路径字段名 |+| `NUXT_PROVIDER_OPENLIST_CDN_URL` | string | 可选 | - | CDN URL |++**认证:**++OpenList 提供程序需要令牌认证以确保安全访问:++```bash+NUXT_PROVIDER_OPENLIST_TOKEN=your-static-token+```++### 基础配置++```bash+# 设置存储提供器为 OpenList+NUXT_STORAGE_PROVIDER=openlist++# OpenList 基础配置+NUXT_PROVIDER_OPENLIST_BASE_URL=https://your-openlist-server.com+NUXT_PROVIDER_OPENLIST_ROOT_PATH=/chronoframe/photos++# 认证配置 - Token 认证+NUXT_PROVIDER_OPENLIST_TOKEN=your-api-token++# 可选配置+NUXT_PROVIDER_OPENLIST_ENDPOINT_UPLOAD=/api/fs/put+NUXT_PROVIDER_OPENLIST_ENDPOINT_DOWNLOAD=+NUXT_PROVIDER_OPENLIST_ENDPOINT_LIST=+NUXT_PROVIDER_OPENLIST_ENDPOINT_DELETE=/api/fs/remove+NUXT_PROVIDER_OPENLIST_ENDPOINT_META=/api/fs/get+NUXT_PROVIDER_OPENLIST_PATH_FIELD=path+NUXT_PROVIDER_OPENLIST_CDN_URL=+```++### 配置示例++#### OpenList(理论上Alist也可行)++```bash+NUXT_STORAGE_PROVIDER=openlist+NUXT_PROVIDER_OPENLIST_BASE_URL=https://openlist.example.com+NUXT_PROVIDER_OPENLIST_ROOT_PATH=/115pan/chronoframe+NUXT_PROVIDER_OPENLIST_TOKEN=your-static-token+```++## 常见问题++:::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/legacy/development/contributing.md b/docs/zh/legacy/development/contributing.mdnew file mode 100644index 00000000..8521e3ce--- /dev/null+++ b/docs/zh/legacy/development/contributing.md@@ -0,0 +1,360 @@+---+search: false+---++::: warning 历史文档+本文保留旧版的部署和环境变量说明,仅供维护旧实例时查阅。当前版本请从[快速开始](/zh/guide/getting-started)进入,日常设置在后台完成。+:::++# 开始贡献++本文档将指导您搭建 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 # 或使用您喜欢的编辑器+```++#### 最小开发配置++```bash+# === 管理员账户 ===+CFRAME_ADMIN_NAME=Developer+CFRAME_ADMIN_PASSWORD=dev123456++# === 认证设置 ===+NUXT_OAUTH_GITHUB_CLIENT_ID=your-dev-github-client-id+NUXT_OAUTH_GITHUB_CLIENT_SECRET=your-dev-github-client-secret+NUXT_SESSION_PASSWORD=your-32-character-development-key++# === 存储设置(开发环境可使用 MinIO) ===+NUXT_STORAGE_PROVIDER=s3+NUXT_PROVIDER_S3_ENDPOINT=http://localhost:9000+NUXT_PROVIDER_S3_BUCKET=chronoframe-dev+NUXT_PROVIDER_S3_REGION=us-east-1+NUXT_PROVIDER_S3_ACCESS_KEY_ID=minioadmin+NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=minioadmin++# === 地图服务(可选) ===+NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=pk.your-development-token+NUXT_MAPBOX_ACCESS_TOKEN=sk.your-development-token++# === 开启调试信息 ===+VITE_SHOW_DEBUG_INFO=true+```++## 项目架构++### 目录结构++```+chronoframe/+├── app/ # Nuxt 4 应用目录+│ ├── components/ # Vue 组件+│ │ ├── ui/ # 通用 UI 组件+│ │ ├── photo/ # 照片相关组件+│ │ ├── masonry/ # 瀑布流布局组件+│ │ └── ...+│ ├── pages/ # 路由页面+│ ├── composables/ # Vue 组合式函数+│ ├── stores/ # Pinia 状态管理+│ ├── layouts/ # 布局模板+│ ├── plugins/ # Nuxt 插件+│ └── utils/ # 工具函数+├── packages/+│ └── webgl-image/ # WebGL 图片查看器包+│ ├── src/+│ │ ├── core/ # 核心引擎+│ │ ├── components/ # Vue 组件+│ │ └── types/ # 类型定义+│ └── package.json+├── server/ # Nitro 服务端+│ ├── api/ # API 路由+│ │ ├── photos/ # 照片管理 API+│ │ ├── auth/ # 认证 API+│ │ └── system/ # 系统 API+│ ├── database/ # 数据库相关+│ │ ├── schema.ts # 数据库模式+│ │ └── migrations/ # 迁移文件+│ ├── services/ # 业务逻辑服务+│ │ ├── storage/ # 存储服务+│ │ ├── image/ # 图片处理+│ │ ├── location/ # 地理位置+│ │ └── pipeline-queue/ # 处理队列+│ ├── tasks/ # 后台任务+│ └── utils/ # 服务端工具+├── shared/ # 前后端共享代码+│ ├── types/ # TypeScript 类型定义+│ └── utils/ # 共享工具函数+├── docs/ # 项目文档+├── scripts/ # 构建和部署脚本+└── 配置文件...+```++### 技术栈++#### 前端技术++- **Nuxt 4**: Vue.js 全栈框架+- **TypeScript**: 类型安全的 JavaScript+- **TailwindCSS**: 实用优先的 CSS 框架++#### 后端技术++- **Nitro**: 服务端框架+- **SQLite**: 轻量级数据库+- **Drizzle ORM**: 类型安全的 ORM+- **Sharp**: 高性能图片处理+- **ExifTool**: EXIF 数据提取++## 开发流程++### 启动开发服务器++```bash+# 启动完整开发服务器+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/new/choose)+- [GitHub Discussions](https://github.com/HoshinoSuzumi/chronoframe/discussions)diff --git a/docs/zh/legacy/guide/configuration.md b/docs/zh/legacy/guide/configuration.mdnew file mode 100644index 00000000..32f17426--- /dev/null+++ b/docs/zh/legacy/guide/configuration.md@@ -0,0 +1,87 @@+---+search: false+---++::: warning 历史文档+本文保留旧版的部署和环境变量说明,仅供维护旧实例时查阅。当前版本请从[快速开始](/zh/guide/getting-started)进入,日常设置在后台完成。+:::++# 配置项说明++无论是使用 Docker 还是 Docker Compose (.env) 方式部署,均通过环境变量进行配置。++## 环境变量列表++| 环境变量 | 说明 | 默认值 | 必需 |+| ---------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------- | --------------------------------------------------------------------- |+| CFRAME_ADMIN_EMAIL | 初始管理员用户的邮箱 | `[email protected]` | 是 |+| CFRAME_ADMIN_NAME | 初始管理员用户的用户名 | `Chronoframe` | 否 |+| CFRAME_ADMIN_PASSWORD | 初始管理员用户的密码 | `CF1234@!` | 否 |+| NUXT_PUBLIC_APP_TITLE | 应用标题 | `ChronoFrame` | 否 |+| NUXT_PUBLIC_APP_SLOGAN | 应用口号 | 无 | 否 |+| NUXT_PUBLIC_APP_AUTHOR | 应用作者 | 无 | 否 |+| NUXT_PUBLIC_APP_AVATAR_URL | 应用头像 URL | 无 | 否 |+| NUXT_PUBLIC_COLOR_MODE_PREFERENCE | 颜色模式偏好,可选 `light`、`dark`、`system` | system | 否 |+| NUXT_PUBLIC_MAP_PROVIDER | 地图提供者,可选 `mapbox`、`maplibre` | `maplibre` | 否 |+| NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN | Mapbox 访问令牌(可限制 URL),用于地图服务 | 无 | 当 `NUXT_PUBLIC_MAP_PROVIDER` 为 `mapbox` 时必需 |+| NUXT_NOMINATIM_BASE_URL | Nominatim 反向地理编码服务的基础 URL | `https://nominatim.openstreetmap.org` | 否 |+| NUXT_MAPBOX_ACCESS_TOKEN | Mapbox 访问令牌(无 URL 限制),用于位置信息服务 | 无 | 否 |+| NUXT_STORAGE_PROVIDER | 存储提供者,支持 `local`、`s3`、`openlist` | `local` | 是 |+| NUXT_PROVIDER_LOCAL_PATH | 本地存储路径 | `/app/data/storage` | 否 |+| NUXT_PROVIDER_LOCAL_BASE_URL | 本地存储的访问 URL | `/storage` | 否 |+| NUXT_PROVIDER_S3_ENDPOINT | S3 兼容存储服务的 Endpoint | 无 | 当 `NUXT_STORAGE_PROVIDER` 为 `s3` 时必需 |+| NUXT_PROVIDER_S3_BUCKET | S3 存储桶名称 | `chronoframe` | 当 `NUXT_STORAGE_PROVIDER` 为 `s3` 时必需 |+| NUXT_PROVIDER_S3_REGION | S3 存储桶区域 | `auto` | 当 `NUXT_STORAGE_PROVIDER` 为 `s3` 时必需 |+| NUXT_PROVIDER_S3_ACCESS_KEY_ID | S3 访问密钥 ID | 无 | 当 `NUXT_STORAGE_PROVIDER` 为 `s3` 时必需 |+| NUXT_PROVIDER_S3_SECRET_ACCESS_KEY | S3 访问密钥 | 无 | 当 `NUXT_STORAGE_PROVIDER` 为 `s3` 时必需 |+| NUXT_PROVIDER_S3_PREFIX | S3 存储前缀 | `photos/` | 否 |+| NUXT_PROVIDER_S3_CDN_URL | S3 存储的 CDN 地址 | 无 | 否 |+| NUXT_PROVIDER_OPENLIST_BASE_URL | OpenList 服务器 URL | 无 | 当 `NUXT_STORAGE_PROVIDER` 为 `openlist` 时必需 |+| NUXT_PROVIDER_OPENLIST_ROOT_PATH | OpenList 根路径 | 无 | 当 `NUXT_STORAGE_PROVIDER` 为 `openlist` 时必需 |+| NUXT_PROVIDER_OPENLIST_TOKEN | OpenList API 令牌 | 无 | 当 `NUXT_STORAGE_PROVIDER` 为 `openlist` 时必需(用于 OpenList 认证) |+| NUXT_PROVIDER_OPENLIST_ENDPOINT_UPLOAD | OpenList 上传端点 | `/api/fs/put` | 否 |+| NUXT_PROVIDER_OPENLIST_ENDPOINT_DOWNLOAD | OpenList 下载端点 | 无 | 否 |+| NUXT_PROVIDER_OPENLIST_ENDPOINT_LIST | OpenList 列表端点 | 无 | 否 |+| NUXT_PROVIDER_OPENLIST_ENDPOINT_DELETE | OpenList 删除端点 | `/api/fs/remove` | 否 |+| NUXT_PROVIDER_OPENLIST_ENDPOINT_META | OpenList 元数据端点 | `/api/fs/get` | 否 |+| NUXT_PROVIDER_OPENLIST_PATH_FIELD | OpenList 路径字段名 | `path` | 否 |+| NUXT_PROVIDER_OPENLIST_CDN_URL | OpenList CDN 地址 | 无 | 否 |+| NUXT_PUBLIC_OAUTH_GITHUB_ENABLED | 是否启用 GitHub OAuth 登录 | `false` | 否 |+| NUXT_OAUTH_GITHUB_CLIENT_ID | GitHub OAuth 应用的 Client ID | 无 | 否(可选,用于 GitHub 登录) |+| NUXT_OAUTH_GITHUB_CLIENT_SECRET | GitHub OAuth 应用的 Client Secret | 无 | 否(可选,用于 GitHub 登录) |+| NUXT_SESSION_PASSWORD | 用于加密会话的密码,32 位随机字符串 | 无 | 是 |+| NUXT_TRUST_PROXY | 相簿解锁限流是否信任 `X-Forwarded-For`;仅在可信反代覆盖客户端同名请求头时启用 | `false` | 否 |+| NUXT_PUBLIC_GTAG_ID | Google Analytics 追踪 ID | 无 | 否 |+| NUXT_PUBLIC_ANALYTICS_MATOMO_ENABLED | 是否启用 Matomo 分析追踪 | `false` | 否 |+| NUXT_PUBLIC_ANALYTICS_MATOMO_URL | Matomo 实例 URL 地址(如: https://matomo.example.com) | 无 | 否(启用 Matomo 时必需) |+| NUXT_PUBLIC_ANALYTICS_MATOMO_SITE_ID | Matomo 站点 ID | 无 | 否(启用 Matomo 时必需) |+| NUXT_UPLOAD_MIME_WHITELIST_ENABLED | 是否启用上传文件 MIME 类型白名单验证 | `true` | 否 |+| NUXT_UPLOAD_MIME_WHITELIST | 上传文件允许的 MIME 类型列表(逗号分隔) | 见下方说明 | 否 |+| ALLOW_INSECURE_COOKIE | 是否允许非安全 Cookie(仅在开发环境使用) | `false` | 否 |++## 上传文件类型白名单++`NUXT_UPLOAD_MIME_WHITELIST` 的默认值包含以下 MIME 类型:++- `image/jpeg` - JPEG 图片+- `image/png` - PNG 图片+- `image/webp` - WebP 图片+- `image/gif` - GIF 图片+- `image/bmp` - BMP 图片+- `image/tiff` - TIFF 图片+- `image/heic` - HEIC 图片(Apple)+- `image/heif` - HEIF 图片+- `video/quicktime` - QuickTime 视频(MOV)+- `video/mp4` - MP4 视频++如需自定义白名单,请使用逗号分隔的 MIME 类型字符串,例如:++```+NUXT_UPLOAD_MIME_WHITELIST=image/jpeg,image/png,video/mp4+```++如需禁用白名单验证(允许任何文件类型),可设置:++```+NUXT_UPLOAD_MIME_WHITELIST_ENABLED=false+```diff --git a/docs/zh/legacy/guide/getting-started.md b/docs/zh/legacy/guide/getting-started.mdnew file mode 100644index 00000000..379ed60a--- /dev/null+++ b/docs/zh/legacy/guide/getting-started.md@@ -0,0 +1,261 @@+---+search: false+---++::: warning 历史文档+本文保留旧版的部署和环境变量说明,仅供维护旧实例时查阅。当前版本请从[快速开始](/zh/guide/getting-started)进入,日常设置在后台完成。+:::++# 快速开始++本文档将指导您如何快速部署并开始使用 ChronoFrame。++:::warning 🚧施工中+文档正在编写中,部分功能文档尚未完成。+:::++## 前置准备++- 可用的 [Docker](https://docs.docker.com/get-docker/) 环境。+- 存储后端:可以直接使用内置本地文件系统,也可以配置任意兼容 S3 协议的对象存储。详见 [存储提供者](/zh/legacy/configuration/storage-providers)。+ :::tip S3 参数清单+ 若使用 S3,请准备:`ACCESS_KEY_ID`、`SECRET_ACCESS_KEY`、`ENDPOINT`、`BUCKET_NAME`、`REGION`,以及(可选)当外链域名与 ENDPOINT 不同时的 `CDN_URL`。+ :::+- (可选)[GitHub OAuth 应用](https://github.com/settings/applications/new)(用于启用 GitHub 登录,需要 `CLIENT_ID` 与 `CLIENT_SECRET`)。+ :::tip 回调地址+ 在 GitHub OAuth 应用中将 Authorization callback URL 设为:`http(s)://<你的域名>/api/auth/github`+ :::+ :::info+ 未配置 GitHub OAuth 也能使用默认管理员账号(首次启动自动创建)登录。+ :::++## 快速部署++### 拉取镜像++我们推荐使用预构建的 Docker 镜像进行部署,镜像托管在 GHCR 和 Docker Hub,您可以根据网络情况选择合适的源。++#### [GitHub Container Registry (GHCR)](https://github.com/HoshinoSuzumi/chronoframe/pkgs/container/chronoframe)++```bash+docker pull ghcr.io/hoshinosuzumi/chronoframe:latest+```++#### [Docker Hub](https://hub.docker.com/r/hoshinosuzumi/chronoframe)++```bash+docker pull hoshinosuzumi/chronoframe:latest+```++### 创建配置文件++创建 `.env` 文件。下面是使用本地存储的最小示例,完整配置请参阅 [配置说明](/zh/legacy/guide/configuration)。++```bash+# 管理员邮箱(必须)+CFRAME_ADMIN_EMAIL=+# 管理员用户名(可选,默认 ChronoFrame)+CFRAME_ADMIN_NAME=+# 管理员密码(可选,默认 CF1234@!)+CFRAME_ADMIN_PASSWORD=++# 站点信息(均可选)+NUXT_PUBLIC_APP_TITLE=+NUXT_PUBLIC_APP_SLOGAN=+NUXT_PUBLIC_APP_AUTHOR=+NUXT_PUBLIC_APP_AVATAR_URL=++# 地图提供器 (maplibre/mapbox)+NUXT_PUBLIC_MAP_PROVIDER=maplibre+# 使用 MapLibre 需要 MapTiler 访问令牌+NUXT_PUBLIC_MAP_MAPLIBRE_TOKEN=+# 使用 Mapbox 需要 Mapbox 访问令牌+NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=++# 存储提供者(local 或 s3 或 openlist)+NUXT_STORAGE_PROVIDER=local+NUXT_PROVIDER_LOCAL_PATH=/app/data/storage++# 会话密码(必须,32 位随机字符串)+NUXT_SESSION_PASSWORD=+```++若选择使用 S3,请将存储部分替换为:++```bash+NUXT_STORAGE_PROVIDER=s3+NUXT_PROVIDER_S3_ENDPOINT=+NUXT_PROVIDER_S3_BUCKET=chronoframe+NUXT_PROVIDER_S3_REGION=auto+NUXT_PROVIDER_S3_ACCESS_KEY_ID=+NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=+NUXT_PROVIDER_S3_PREFIX=photos/+NUXT_PROVIDER_S3_CDN_URL=+```++若选择使用 openlist,请将存储部分替换为:++```bash+NUXT_STORAGE_PROVIDER=openlist+NUXT_PROVIDER_OPENLIST_BASE_URL=https://openlist.example.com+NUXT_PROVIDER_OPENLIST_ROOT_PATH=/115pan/chronoframe+NUXT_PROVIDER_OPENLIST_TOKEN=your-static-token+```++可选 GitHub OAuth 变量:++```bash+NUXT_OAUTH_GITHUB_CLIENT_ID=+NUXT_OAUTH_GITHUB_CLIENT_SECRET=+```++### Docker 单容器部署++#### 快速启动++```bash+docker run -d --name chronoframe -p 3000:3000 -v $(pwd)/data:/app/data --env-file .env ghcr.io/hoshinosuzumi/chronoframe:latest+```++### Docker Compose 部署++推荐使用 Docker Compose 进行生产环境部署,便于管理和配置。++#### 1. 创建 `docker-compose.yml` 文件++```yaml+services:+ chronoframe:+ image: ghcr.io/hoshinosuzumi/chronoframe:latest+ container_name: chronoframe+ restart: unless-stopped+ ports:+ - '3000:3000'+ volumes:+ - ./data:/app/data+ env_file:+ - .env+```++#### 2. 启动 ChronoFrame 服务++```bash+# 启动服务+docker compose up -d++# 查看日志+docker compose logs -f chronoframe++# 停止服务+docker compose down++# 更新到最新版本+docker compose pull+docker compose up -d+```++## 反向代理++在生产环境中部署时,您通常需要一个反向代理服务器(如 Nginx 或 Caddy)来处理 HTTPS 和域名解析。以下是一些示例配置。++使用下方 Nginx 或 Traefik 示例时,请在 `.env` 中设置 `NUXT_TRUST_PROXY=true`,并确保 3000 端口只能由反向代理访问。若代理会原样转发客户端提供的 `X-Forwarded-For`,请勿启用此选项。++### 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 $remote_addr;+ 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 /_nuxt/ {+ 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)}))+```++:::diff --git a/docs/zh/legacy/guide/updates.md b/docs/zh/legacy/guide/updates.mdnew file mode 100644index 00000000..e5c7f4b3--- /dev/null+++ b/docs/zh/legacy/guide/updates.md@@ -0,0 +1,125 @@+---+search: false+---++::: warning 历史文档+本文保留旧版的部署和环境变量说明,仅供维护旧实例时查阅。当前版本请从[快速开始](/zh/guide/getting-started)进入,日常设置在后台完成。+:::++# 升级指南++本文档将指导您如何安全地更新和升级 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+```diff --git a/docs/zh/legacy/index.md b/docs/zh/legacy/index.mdnew file mode 100644index 00000000..2d1be9c9--- /dev/null+++ b/docs/zh/legacy/index.md@@ -0,0 +1,15 @@+---+search: false+---++# Legacy++这里保留设置向导推出前的文档,便于维护旧实例和核对迁移前的配置。示例中的默认账号、环境变量、容器命令可能已不适用于当前版本。++- [环境变量](/zh/legacy/guide/configuration)+- [存储提供器](/zh/legacy/configuration/storage-providers)+- [地图提供器](/zh/legacy/configuration/map-providers)+- [位置服务](/zh/legacy/configuration/location-providers)+- [旧安装指南](/zh/legacy/guide/getting-started)+- [旧升级指南](/zh/legacy/guide/updates)+- [旧开发指南](/zh/legacy/development/contributing)