Skip to content

Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.

docs: update readme and documents

Timothy Yinb4510008e45c
diff --git a/README.md b/README.md
index 54cefb17..e9e831fe 100644
--- a/README.md
+++ b/README.md
@@ -35,7 +35,7 @@ A smooth photo display and management application, supporting multiple image for
### ☁️ Flexible Storage Solutions
-- **Multiple storage backends** - Supports S3-compatible storage, GitHub (WIP), and local filesystem (WIP)
+- **Multiple storage backends** - Supports S3-compatible storage, local filesystem
- **CDN acceleration** - Configurable CDN URL for faster photo delivery
## 🐳 Deployment
@@ -49,42 +49,44 @@ Below is a **minimal configuration** example. For complete configuration options
```env
# Admin email (required)
CFRAME_ADMIN_EMAIL=
-# Admin username (optional, default: Chronoframe)
+# Admin username (optional, default Chronoframe)
CFRAME_ADMIN_NAME=
-# Admin password (optional, default: CF1234@!)
+# Admin password (optional, default CF1234@!)
CFRAME_ADMIN_PASSWORD=
-# Site title (optional)
+# Site metadata (all optional)
NUXT_PUBLIC_APP_TITLE=
-# Site slogan (optional)
NUXT_PUBLIC_APP_SLOGAN=
-# Site author (optional)
NUXT_PUBLIC_APP_AUTHOR=
-# Site avatar URL (optional)
NUXT_PUBLIC_APP_AVATAR_URL=
-# Mapbox access token (required)
+# Mapbox public token (required for map UI)
NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=
-# Mapbox unrestricted access token (optional)
+# Mapbox unrestricted token (optional, reverse geocoding)
NUXT_MAPBOX_ACCESS_TOKEN=
-# Storage provider (local/s3, choose one)
+# Storage provider (local or s3)
NUXT_STORAGE_PROVIDER=local
+NUXT_PROVIDER_LOCAL_PATH=/app/data/storage
-# S3 storage configuration
-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_CDN_URL=
+# Session password (32‑char random string, required)
+NUXT_SESSION_PASSWORD=
+```
-# Local storage configuration
-# (If using local storage, ensure /app/data directory is mounted)
-NUXT_PROVIDER_LOCAL_PATH=/app/data/photos
+### Pull Image
-# Session password (required, 32 random characters)
-NUXT_SESSION_PASSWORD=
+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
@@ -119,36 +121,6 @@ Start:
docker-compose up -d
```
-### Environment Variables
-
-| Variable | Description | Default | Required |
-| :----------------------------------- | :------------------------------------- | :---------- | :------------------------------ |
-| CFRAME_ADMIN_EMAIL | Email of the initial admin user | None | Yes |
-| CFRAME_ADMIN_NAME | Username of the initial admin | Chronoframe | No |
-| CFRAME_ADMIN_PASSWORD | Password of the initial admin | CF1234@! | No |
-| NUXT_PUBLIC_APP_TITLE | Application title | ChronoFrame | No |
-| NUXT_PUBLIC_APP_SLOGAN | Application slogan | None | No |
-| NUXT_PUBLIC_APP_AUTHOR | Application author | None | No |
-| NUXT_PUBLIC_APP_AVATAR_URL | Application avatar URL | None | No |
-| NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN | Mapbox access token for map service | None | Yes |
-| NUXT_MAPBOX_ACCESS_TOKEN | Mapbox access token for location info | None | No |
-| NUXT_STORAGE_PROVIDER | Storage provider (s3, github, local) | s3 | Yes |
-| NUXT_PROVIDER_S3_ENDPOINT | S3 endpoint | None | Required if provider is s3 |
-| NUXT_PROVIDER_S3_BUCKET | S3 bucket name | chronoframe | Required if provider is s3 |
-| NUXT_PROVIDER_S3_REGION | S3 bucket region | auto | Required if provider is s3 |
-| NUXT_PROVIDER_S3_ACCESS_KEY_ID | S3 access key ID | None | Required if provider is s3 |
-| NUXT_PROVIDER_S3_SECRET_ACCESS_KEY | S3 secret access key | None | Required if provider is s3 |
-| NUXT_PROVIDER_S3_PREFIX | S3 object prefix | photos/ | No |
-| NUXT_PROVIDER_S3_CDN_URL | S3 CDN URL | None | No |
-| NUXT_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 | Session encryption password (32 chars) | None | Yes |
-| NUXT_PUBLIC_GTAG_ID | Google Analytics Measurement ID | None | No |
-| NUXT_PUBLIC_ANALYTICS_MATOMO_ENABLED | Enable Matomo analytics | false | No |
-| NUXT_PUBLIC_ANALYTICS_MATOMO_URL | Matomo instance URL | None | No (required if Matomo enabled) |
-| NUXT_PUBLIC_ANALYTICS_MATOMO_SITE_ID | Matomo site ID | None | No (required if Matomo enabled) |
-
## 📖 User Guide
> If `CFRAME_ADMIN_EMAIL` and `CFRAME_ADMIN_PASSWORD` are not set, the default admin account is:
diff --git a/README_zh.md b/README_zh.md
index cee974d2..bdf45caa 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -38,7 +38,7 @@
### ☁️ 灵活的存储方案
-- **多存储后端** - 支持 S3 兼容存储、GitHub(WIP)、本地文件系统(WIP) 等
+- **多存储后端** - 支持 S3 兼容存储、本地文件系统
- **CDN 加速** - 可配置 CDN 地址加速图片访问
## 🐳 部署
@@ -50,44 +50,44 @@
下面是**最小化配置**示例,完整的配置项参考 [.env.example](./.env.example):
```env
-# 管理员邮箱 (必须)
+# 管理员邮箱(必须)
CFRAME_ADMIN_EMAIL=
-# 管理员用户名 (可选, 默认 Chronoframe)
+# 管理员用户名(可选,默认 ChronoFrame)
CFRAME_ADMIN_NAME=
-# 管理员密码 (可选, 默认 CF1234@!)
+# 管理员密码(可选,默认 CF1234@!)
CFRAME_ADMIN_PASSWORD=
-# 站点标题 (可选)
+# 站点信息(均可选)
NUXT_PUBLIC_APP_TITLE=
-# 站点口号 (可选)
NUXT_PUBLIC_APP_SLOGAN=
-# 站点作者 (可选)
NUXT_PUBLIC_APP_AUTHOR=
-# 站点头像 URL (可选)
NUXT_PUBLIC_APP_AVATAR_URL=
-# Mapbox 访问令牌 (必须)
+# Mapbox 公共访问令牌(地图 UI,必须)
NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=
-# Mapbox 无 URL 限制访问令牌 (可选)
+# Mapbox 无域名限制令牌(反向地理编码,可选)
NUXT_MAPBOX_ACCESS_TOKEN=
-# 存储提供者 (local/s3, 选其一)
+# 存储提供者(local 或 s3)
NUXT_STORAGE_PROVIDER=local
+NUXT_PROVIDER_LOCAL_PATH=/app/data/storage
-# 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_CDN_URL=
+# 会话密码(必须,32 位随机字符串)
+NUXT_SESSION_PASSWORD=
+```
-# Local 存储配置
-# (如果使用 local 存储, 请确保挂载了 /app/data 目录)
-NUXT_PROVIDER_LOCAL_PATH=/app/data/photos
+### 拉取镜像
-# 会话密码 (必须, 32 位随机字符串)
-NUXT_SESSION_PASSWORD=
+我们推荐使用预构建的 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
@@ -122,36 +122,6 @@ services:
docker-compose up -d
```
-### 环境变量列表
-
-| 环境变量 | 说明 | 默认值 | 必需 |
-| :--------------------------------- | :--------------------------------------------- | :---------- | :---------------------------------------- |
-| CFRAME_ADMIN_EMAIL | 初始管理员用户的邮箱 | 无 | 是 |
-| CFRAME_ADMIN_NAME | 初始管理员用户的用户名 | Chronoframe | 否 |
-| CFRAME_ADMIN_PASSWORD | 初始管理员用户的密码 | CF1234@! | 否 |
-| NUXT_PUBLIC_APP_TITLE | 应用标题 | ChronoFrame | 否 |
-| NUXT_PUBLIC_APP_SLOGAN | 应用口号 | 无 | 否 |
-| NUXT_PUBLIC_APP_AUTHOR | 应用作者 | 无 | 否 |
-| NUXT_PUBLIC_APP_AVATAR_URL | 应用头像 URL | 无 | 否 |
-| NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN | Mapbox 访问令牌(可限制 URL),用于地图服务 | 无 | 是 |
-| NUXT_MAPBOX_ACCESS_TOKEN | Mapbox 访问令牌(无 URL 限制),用于位置信息服务 | 无 | 否 |
-| NUXT_STORAGE_PROVIDER | 存储提供者,支持 `s3`、`github`、`local` | `s3` | 是 |
-| NUXT_PROVIDER_S3_ENDPOINT | S3 兼容存储服务的 Endpoint | 无 | 当 `NUXT_STORAGE_PROVIDER` 为 `s3` 时必需 |
-| NUXT_PROVIDER_S3_BUCKET | S3 存储桶名称 | chronoframe | 当 `NUXT_STORAGE_PROVIDER` 为 `s3` 时必需 |
-| NUXT_PROVIDER_S3_REGION | S3 存储桶区域 | auto | 当 `NUXT_STORAGE_PROVIDER` 为 `s3` 时必需 |
-| NUXT_PROVIDER_S3_ACCESS_KEY_ID | S3 访问密钥 ID | 无 | 当 `NUXT_STORAGE_PROVIDER` 为 `s3` 时必需 |
-| NUXT_PROVIDER_S3_SECRET_ACCESS_KEY | S3 访问密钥 | 无 | 当 `NUXT_STORAGE_PROVIDER` 为 `s3` 时必需 |
-| NUXT_PROVIDER_S3_PREFIX | S3 存储前缀 | photos/ | 否 |
-| NUXT_PROVIDER_S3_CDN_URL | S3 存储的 CDN 地址 | 无 | 否 |
-| NUXT_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_PUBLIC_GTAG_ID | Google Analytics 追踪 ID | 无 | 否 |
-| NUXT_PUBLIC_ANALYTICS_MATOMO_ENABLED | 是否启用 Matomo 分析 | false | 否 |
-| NUXT_PUBLIC_ANALYTICS_MATOMO_URL | Matomo 实例 URL 地址 | 无 | 否(启用 Matomo 时必需) |
-| NUXT_PUBLIC_ANALYTICS_MATOMO_SITE_ID | Matomo 站点 ID | 无 | 否(启用 Matomo 时必需) |
-
## 📖 使用指南
> 如未配置 `CFRAME_ADMIN_EMAIL` 和 `CFRAME_ADMIN_PASSWORD`,默认账号如下:
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index 3cdd00cb..d716ceba 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -1,121 +1,84 @@
# Getting Started
-This documentation will guide you on how to quickly deploy and start using ChronoFrame.
+This guide walks you through deploying and using ChronoFrame quickly.
:::warning 🚧 Under Construction
-Documentation is being written, some feature documentation is not yet complete.
+The documentation is still being written; some sections may be incomplete.
:::
## Prerequisites
-- Available [Docker](https://docs.docker.com/get-docker/) environment.
-- An S3 protocol-compatible storage bucket *(GitHub repository storage and local filesystem storage are still in development)*.
- :::tip
- When using S3 storage, you need to obtain at least the following information from your service provider: `ACCESS_KEY_ID`, `SECRET_ACCESS_KEY`, `ENDPOINT`, `BUCKET_NAME`, `REGION`. When the bucket's external URL is different from the `ENDPOINT`, you also need to provide the external URL `CDN_URL`.
- :::
+- A working [Docker](https://docs.docker.com/get-docker/) environment.
- Two [Mapbox access tokens](https://console.mapbox.com/account/access-tokens/).
- :::details Why do I need two tokens?
- - The first token is used for frontend map display, requires `styles:read` permission. It's recommended to restrict this token's URL to your ChronoFrame instance domain to prevent abuse.
- - The second token is used for backend reverse geocoding, this token **cannot** have URL restrictions. This token is **optional**.
+ :::details Why two tokens?
+ - The first token (frontend) is used by Mapbox GL JS to render maps. It needs `styles:read` permission. You should restrict this token to your ChronoFrame domain to avoid abuse.
+ - The second token (server) is used for reverse geocoding (Mapbox Search API). It **must not** have URL restrictions. This token is **optional** if you don't need reverse geocoding.
+ :::
+- A storage backend. You can start with the built‑in local filesystem storage or configure an S3‑compatible bucket. See the [Storage Providers](/guide/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.
:::
-- [GitHub OAuth App](https://github.com/settings/applications/new) `CLIENT_ID` and `CLIENT_SECRET` *(optional, for enabling GitHub login)*.
- :::tip
- When creating the OAuth app, the `Authorization callback URL` should be set to `http(s)://<your-domain>/api/auth/github`.
+- (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
- GitHub OAuth credentials are **optional**. If not configured, you can still use the default admin account to log in.
+ If GitHub OAuth is not configured you can still log in with the default admin account (auto‑provisioned on first start).
:::
## Quick Deployment
-### Pre-built Images
+### Pull Image
-We recommend using pre-built Docker images for deployment, hosted on GitHub Container Registry:
+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
```
-ghcr.io/hoshinosuzumi/chronoframe:latest
-```
-[View all available versions](https://github.com/HoshinoSuzumi/chronoframe/pkgs/container/chronoframe)
+#### [Docker Hub](https://hub.docker.com/r/hoshinosuzumi/chronoframe)
+
+```bash
+docker pull hoshinosuzumi/chronoframe:latest
+```
-### Create Configuration File
+### Create `.env`
-Create a `.env` file in a directory beforehand. To see all configuration options, please refer to the [Configuration Guide](/guide/configuration).
+Below is the minimal configuration for running with local storage. For the complete list, see the [Configuration Guide](/guide/configuration).
```env
-# Admin user email (required)
+# Admin email (required)
CFRAME_ADMIN_EMAIL=
-# Admin username (default to Chronoframe, optional)
+# Admin username (optional, default Chronoframe)
CFRAME_ADMIN_NAME=
-# Admin user password (default to CF1234@!, optional)
+# 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=
-# Mapbox access token for map features, Mapbox GL JS (Client-side, public)
+# Mapbox public token (required for map UI)
NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=
-# Mapbox secret access token for server-side, Mapbox Search API (Reverse Geocoding)
+# Mapbox unrestricted token (optional, reverse geocoding)
NUXT_MAPBOX_ACCESS_TOKEN=
-# 存储提供者(s3/github/local)
-NUXT_STORAGE_PROVIDER=s3
-# 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=
+# Storage provider (local or s3)
+NUXT_STORAGE_PROVIDER=local
+NUXT_PROVIDER_LOCAL_PATH=/app/data/storage
-# 会话密码(32 位随机字符串,必须设置)
+# Session password (32‑char random string, required)
NUXT_SESSION_PASSWORD=
-
-# GitHub OAuth
-NUXT_OAUTH_GITHUB_CLIENT_ID=
-NUXT_OAUTH_GITHUB_CLIENT_SECRET=
```
-### Docker Single Container Deployment
-
-#### Quick Start
-
-```bash
-docker run -d --name chronoframe -p 3000:3000 -v $(pwd)/data:/app/data --env-file .env ghcr.io/hoshinosuzumi/chronoframe:latest
-```
-
-### Docker Compose Deployment
-
-Recommended for production environment deployment using Docker Compose for easier management and configuration.
-
-#### 1. Create `.env` file
+If you want to use S3 instead of local storage, replace the storage section with:
```env
-# Admin user email (required)
-CFRAME_ADMIN_EMAIL=
-# Admin username (default to Chronoframe, optional)
-CFRAME_ADMIN_NAME=
-# Admin user password (default to CF1234@!, optional)
-CFRAME_ADMIN_PASSWORD=
-
-# Application title and slogan
-NUXT_PUBLIC_APP_TITLE=
-NUXT_PUBLIC_APP_SLOGAN=
-NUXT_PUBLIC_APP_AUTHOR=
-NUXT_PUBLIC_APP_AVATAR_URL=
-
-# Mapbox access token for map features, Mapbox GL JS (Client-side, public)
-NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=
-# Mapbox secret access token for server-side, Mapbox Search API (Reverse Geocoding)
-NUXT_MAPBOX_ACCESS_TOKEN=
-
-# Storage provider (s3/github/local)
NUXT_STORAGE_PROVIDER=s3
-# S3 storage service configuration
NUXT_PROVIDER_S3_ENDPOINT=
NUXT_PROVIDER_S3_BUCKET=chronoframe
NUXT_PROVIDER_S3_REGION=auto
@@ -123,16 +86,29 @@ NUXT_PROVIDER_S3_ACCESS_KEY_ID=
NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=
NUXT_PROVIDER_S3_PREFIX=photos/
NUXT_PROVIDER_S3_CDN_URL=
+```
-# Session password (32-character random string, required)
-NUXT_SESSION_PASSWORD=
+Optional GitHub OAuth variables:
-# GitHub OAuth
+```env
NUXT_OAUTH_GITHUB_CLIENT_ID=
NUXT_OAUTH_GITHUB_CLIENT_SECRET=
```
-#### 2. Create `docker-compose.yml` file
+### 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:
@@ -148,54 +124,49 @@ services:
- .env
```
-#### 3. Start ChronoFrame Service
+Start / manage lifecycle:
```bash
-# Start service
+# Start
docker compose up -d
-# View logs
+# Follow logs
docker compose logs -f chronoframe
-# Stop service
+# Stop
docker compose down
-# Update to latest version
+# Update to latest image
docker compose pull
docker compose up -d
```
## Reverse Proxy
-When deploying in production environment, you usually need a reverse proxy server (like Nginx or Caddy) to handle HTTPS and domain resolution. Here are some example configurations.
+For production you typically place ChronoFrame behind a reverse proxy (Nginx, Caddy, Traefik) to terminate HTTPS and serve via your domain.
-### Nginx
+### Nginx Example
```nginx
server {
listen 80;
server_name your-domain.com;
-
- # HTTPS redirect
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name your-domain.com;
-
- # SSL certificate configuration
+
ssl_certificate /path/to/your/certificate.crt;
ssl_certificate_key /path/to/your/private.key;
-
- # SSL security configuration
+
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off;
-
- # Upload size limit
+
client_max_body_size 100M;
-
+
location / {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
@@ -206,18 +177,11 @@ server {
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_cache_bypass $http_upgrade;
-
- # WebSocket support
- proxy_set_header Connection "upgrade";
- proxy_set_header Upgrade $http_upgrade;
-
- # Timeout settings
proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
}
-
- # Static resource caching
+
location ~* \.(jpg|jpeg|png|gif|webp|svg|css|js|ico|woff|woff2|ttf|eot)$ {
proxy_pass http://localhost:3000;
expires 1y;
@@ -227,9 +191,7 @@ server {
}
```
-### Traefik
-
-If you use Traefik as reverse proxy, you can add labels in `docker-compose.yml`:
+### Traefik (Labels)
```yaml
services:
@@ -257,20 +219,20 @@ networks:
## Common Issues
-:::details How to generate random `NUXT_SESSION_PASSWORD`?
+:::details How do I generate a random `NUXT_SESSION_PASSWORD`?
```bash
# Linux / macOS
openssl rand -base64 32
-# Windows (pwsh)
+# Windows (PowerShell)
[Convert]::ToBase64String((1..32|%{[byte](Get-Random -Max 256)}))
```
:::
-:::details After successful backend authentication login, redirect to homepage and still in unauthenticated state?
-First, please make sure you're not accessing directly through IP address and port number. For security reasons, please access through the configured domain name.
+:::details Logged in successfully but redirected home still unauthenticated?
+Make sure you are not accessing the site via raw IP:port. For security, cookies are set for the domain.
-If for some reason you insist on accessing through IP port, please add to configuration:
+If you must use IP + port (not recommended), add:
```env
NUXT_ALLOW_INSECURE_COOKIE=true
```
diff --git a/docs/zh/guide/getting-started.md b/docs/zh/guide/getting-started.md
index 6e1c3e3b..c5f9494d 100644
--- a/docs/zh/guide/getting-started.md
+++ b/docs/zh/guide/getting-started.md
@@ -9,61 +9,74 @@
## 前置准备
- 可用的 [Docker](https://docs.docker.com/get-docker/) 环境。
-- 一个支持 S3 协议的存储桶 *(GitHub 仓库存储和本地文件系统存储仍在开发中)*。
- :::tip
- 使用 S3 存储时,你至少需要从服务商处获取以下信息:`ACCESS_KEY_ID`、`SECRET_ACCESS_KEY`、`ENDPOINT`、`BUCKET_NAME`、`REGION`,当存储桶的外链地址和 `ENDPOINT` 不同时,你还需要提供外链地址 `CDN_URL`。
- :::
- 两个 [Mapbox 访问令牌](https://console.mapbox.com/account/access-tokens/)。
:::details 为什么需要两个 Token?
- - 第一个 Token 用于前端显示地图,要求有 `styles:read` 权限。建议将此 Token 的 URL 限制为你的 ChronoFrame 实例域名以防止滥用。
- - 第二个 Token 用于后端进行地理位置反向解析,此 Token **不能**有 URL 限制。这个 Token 是**可选**的。
+ - 第一个(前端)Token 用于 Mapbox GL JS 渲染地图,需要 `styles:read` 权限。建议将其域名限制为你的 ChronoFrame 实例,防止滥用。
+ - 第二个(服务端)Token 用于反向地理编码(Mapbox Search API),此 Token **不能** 有 URL 限制。如果不需要反向解析,可以不配置(可选)。
+ :::
+- 存储后端:可以直接使用内置本地文件系统,也可以配置任意兼容 S3 协议的对象存储。详见 [存储提供者](/zh/guide/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)的 `CLIENT_ID` 和 `CLIENT_SECRET` *(可选,用于启用 GitHub 登录)*。
- :::tip
- 创建 OAuth 应用时,`Authorization callback URL` 应设置为 `http(s)://<你的域名>/api/auth/github`。
+- (可选)[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 凭据是**可选的**。如果不配置,您仍然可以使用默认管理员账号登录。
+ 未配置 GitHub OAuth 也能使用默认管理员账号(首次启动自动创建)登录。
:::
## 快速部署
-### 预建镜像
+### 拉取镜像
-我们推荐使用预构建的 Docker 镜像进行部署,镜像托管在 GitHub Container Registry:
+我们推荐使用预构建的 Docker 镜像进行部署,镜像托管在 GHCR 和 Docker Hub,您可以根据网络情况选择合适的源。
-```
-ghcr.io/hoshinosuzumi/chronoframe:latest
+#### [GitHub Container Registry (GHCR)](https://github.com/HoshinoSuzumi/chronoframe/pkgs/container/chronoframe)
+```bash
+docker pull ghcr.io/hoshinosuzumi/chronoframe:latest
```
-[查看所有可用版本](https://github.com/HoshinoSuzumi/chronoframe/pkgs/container/chronoframe)
+#### [Docker Hub](https://hub.docker.com/r/hoshinosuzumi/chronoframe)
+```bash
+docker pull hoshinosuzumi/chronoframe:latest
+```
### 创建配置文件
-事先在一个目录中创建 `.env` 文件。要查看所有的配置项,请查看 [配置说明](/zh/guide/configuration) 章节。
+创建 `.env` 文件。下面是使用本地存储的最小示例,完整配置请参阅 [配置说明](/zh/guide/configuration)。
-```env
-# Admin user email (required)
+```bash
+# 管理员邮箱(必须)
CFRAME_ADMIN_EMAIL=
-# Admin username (default to Chronoframe, optional)
+# 管理员用户名(可选,默认 ChronoFrame)
CFRAME_ADMIN_NAME=
-# Admin user password (default to CF1234@!, optional)
+# 管理员密码(可选,默认 CF1234@!)
CFRAME_ADMIN_PASSWORD=
-# 应用标题与口号
+# 站点信息(均可选)
NUXT_PUBLIC_APP_TITLE=
NUXT_PUBLIC_APP_SLOGAN=
NUXT_PUBLIC_APP_AUTHOR=
NUXT_PUBLIC_APP_AVATAR_URL=
-# Mapbox access token for map features, Mapbox GL JS (Client-side, public)
+# Mapbox 公共访问令牌(地图 UI,必须)
NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=
-# Mapbox secret access token for server-side, Mapbox Search API (Reverse Geocoding)
+# Mapbox 无域名限制令牌(反向地理编码,可选)
NUXT_MAPBOX_ACCESS_TOKEN=
-# 存储提供者(s3/github/local)
+# 存储提供者(local 或 s3)
+NUXT_STORAGE_PROVIDER=local
+NUXT_PROVIDER_LOCAL_PATH=/app/data/storage
+
+# 会话密码(必须,32 位随机字符串)
+NUXT_SESSION_PASSWORD=
+```
+
+若选择使用 S3,请将存储部分替换为:
+
+```bash
NUXT_STORAGE_PROVIDER=s3
-# S3 存储服务配置
NUXT_PROVIDER_S3_ENDPOINT=
NUXT_PROVIDER_S3_BUCKET=chronoframe
NUXT_PROVIDER_S3_REGION=auto
@@ -71,11 +84,11 @@ NUXT_PROVIDER_S3_ACCESS_KEY_ID=
NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=
NUXT_PROVIDER_S3_PREFIX=photos/
NUXT_PROVIDER_S3_CDN_URL=
+```
-# 会话密码(32 位随机字符串,必须设置)
-NUXT_SESSION_PASSWORD=
+可选 GitHub OAuth 变量:
-# GitHub OAuth
+```bash
NUXT_OAUTH_GITHUB_CLIENT_ID=
NUXT_OAUTH_GITHUB_CLIENT_SECRET=
```