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: update readme and documents
Timothy Yinb4510008e45c
diff --git a/README.md b/README.mdindex 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.mdindex 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.mdindex 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 configurationNUXT_PROVIDER_S3_ENDPOINT=NUXT_PROVIDER_S3_BUCKET=chronoframeNUXT_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+```envNUXT_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`:```yamlservices:@@ -148,54 +124,49 @@ services:- .env```-#### 3. Start ChronoFrame Service+Start / manage lifecycle:```bash-# Start service+# Startdocker compose up -d-# View logs+# Follow logsdocker compose logs -f chronoframe-# Stop service+# Stopdocker compose down-# Update to latest version+# Update to latest imagedocker compose pulldocker 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```nginxserver {listen 80;server_name your-domain.com;-- # HTTPS redirectreturn 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 settingsproxy_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)```yamlservices:@@ -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 / macOSopenssl 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:```envNUXT_ALLOW_INSECURE_COOKIE=true```diff --git a/docs/zh/guide/getting-started.md b/docs/zh/guide/getting-started.mdindex 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,请将存储部分替换为:++```bashNUXT_STORAGE_PROVIDER=s3-# S3 存储服务配置NUXT_PROVIDER_S3_ENDPOINT=NUXT_PROVIDER_S3_BUCKET=chronoframeNUXT_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+```bashNUXT_OAUTH_GITHUB_CLIENT_ID=NUXT_OAUTH_GITHUB_CLIENT_SECRET=```