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(map): add MapLibre and Mapbox providers configuration details, reduce minimal configuration

Timothy Yin843028272ad0
diff --git a/.env.example b/.env.example
index cd6b781c..d08b1780 100644
--- a/.env.example
+++ b/.env.example
@@ -13,8 +13,14 @@ NUXT_PUBLIC_APP_AVATAR_URL=/avatar.webp
# Color mode preference: light, dark, or system
NUXT_PUBLIC_COLOR_MODE_PREFERENCE=light
+# Map Provider (mapbox/maplibre)
+NUXT_PUBLIC_MAP_PROVIDER=maplibre
+# Map style URL
+NUXT_PUBLIC_MAP_MAPLIBRE_STYLE=
+NUXT_PUBLIC_MAP_MAPBOX_STYLE=
# 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=
diff --git a/app/components/map/Provider.vue b/app/components/map/Provider.vue
index 7a9cf384..7715c2c2 100644
--- a/app/components/map/Provider.vue
+++ b/app/components/map/Provider.vue
@@ -6,11 +6,10 @@ import type { MapboxMap, MapInstance, MaplibreMap } from '~~/shared/types/map'
import ChronoFrameLightStyle from '~/assets/mapStyles/chronoframe_light.json'
import ChronoFrameDarkStyle from '~/assets/mapStyles/chronoframe_dark.json'
-const props = withDefaults(
+withDefaults(
defineProps<{
class?: string
mapId?: string
- style?: StyleSpecification | string
center?: [number, number]
zoom?: number
interactive?: boolean
@@ -20,7 +19,6 @@ const props = withDefaults(
{
class: undefined,
mapId: undefined,
- style: undefined,
center: undefined,
zoom: 2,
interactive: true,
@@ -40,10 +38,10 @@ const colorMode = useColorMode()
const provider = computed(() => mapConfig.provider)
const mapStyle = computed(() => {
if (provider.value === 'mapbox') {
- return props.style || `mapbox://styles/mapbox/standard`
+ return mapConfig.mapbox.style || `mapbox://styles/mapbox/standard`
} else {
return (
- props.style ||
+ mapConfig.maplibre.style ||
((colorMode.value === 'dark'
? ChronoFrameDarkStyle
: ChronoFrameLightStyle) as StyleSpecification)
diff --git a/app/pages/map-test.vue b/app/pages/map-test.vue
deleted file mode 100644
index 9aeebd26..00000000
--- a/app/pages/map-test.vue
+++ /dev/null
@@ -1,33 +0,0 @@
-<script lang="ts" setup>
-import type { MapInstance } from '~~/shared/types/map'
-
-const mapInstance = ref<MapInstance | null>(null)
-
-watch(mapInstance, (newMap) => {
- if (newMap) {
- mapInstance.value?.flyTo({
- center: [-122.4, 37.8],
- zoom: 12,
- essential: true,
- duration: 3000,
- })
- console.log('Map instance is ready:', newMap)
- } else {
- console.log('Map instance is null')
- }
-})
-
-const onMapLoaded = (map: any) => {
- mapInstance.value = map
-}
-</script>
-
-<template>
- <div class="w-full h-screen">
- <MapProvider @load="onMapLoaded">
- <slot />
- </MapProvider>
- </div>
-</template>
-
-<style scoped></style>
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 9ca01b8b..4f6e9a2a 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -29,6 +29,7 @@ export default defineConfig({
text: 'Storage Providers',
link: '/configuration/storage-providers',
},
+ { text: 'Map Providers', link: '/configuration/map-providers' },
],
},
{
diff --git a/docs/configuration/map-providers.md b/docs/configuration/map-providers.md
new file mode 100644
index 00000000..5a429b2b
--- /dev/null
+++ b/docs/configuration/map-providers.md
@@ -0,0 +1,42 @@
+# 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) | ✅ | None | 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, simply configure it as follows—no additional setup is required:
+
+```bash
+NUXT_PUBLIC_MAP_PROVIDER=maplibre
+```
+
+### 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/guide/configuration.md b/docs/guide/configuration.md
index aa1c4e39..938768e0 100644
--- a/docs/guide/configuration.md
+++ b/docs/guide/configuration.md
@@ -4,41 +4,42 @@ Whether using Docker or Docker Compose (.env) deployment, configuration is done
## 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_MAPBOX_ACCESS_TOKEN | Mapbox access token (URL restricted), for map services | None | Yes |
-| NUXT_MAPBOX_ACCESS_TOKEN | Mapbox access token (no URL restriction), for location services | None | No |
-| NUXT_STORAGE_PROVIDER | Storage provider, supports `local`, `s3` | `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_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_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 |
-| NUXT_UPLOAD_DUPLICATE_CHECK_ENABLED | Enable duplicate file detection during upload | `true` | No |
-| NUXT_UPLOAD_DUPLICATE_CHECK_MODE | Duplicate handling mode, options: `warn`, `block`, `skip` | `skip` | No |
-| ALLOW_INSECURE_COOKIE | Allow insecure cookies (only for development environment) | `false` | No |
+| 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_MAPBOX_ACCESS_TOKEN | Mapbox access token (no URL restriction), for location services | None | No |
+| NUXT_STORAGE_PROVIDER | Storage provider, supports `local`, `s3` | `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_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_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 |
+| NUXT_UPLOAD_DUPLICATE_CHECK_ENABLED | Enable duplicate file detection during upload | `true` | No |
+| NUXT_UPLOAD_DUPLICATE_CHECK_MODE | Duplicate handling mode, options: `warn`, `block`, `skip` | `skip` | No |
+| ALLOW_INSECURE_COOKIE | Allow insecure cookies (only for development environment) | `false` | No |
## Upload File Type Whitelist
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index ec57fa67..06687cc9 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -9,11 +9,6 @@ The documentation is still being written; some sections may be incomplete.
## Prerequisites
- A working [Docker](https://docs.docker.com/get-docker/) environment.
-- Two [Mapbox access tokens](https://console.mapbox.com/account/access-tokens/).
- :::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](/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.
@@ -62,11 +57,6 @@ NUXT_PUBLIC_APP_SLOGAN=
NUXT_PUBLIC_APP_AUTHOR=
NUXT_PUBLIC_APP_AVATAR_URL=
-# Mapbox public token (required for map UI)
-NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=
-# Mapbox unrestricted token (optional, reverse geocoding)
-NUXT_MAPBOX_ACCESS_TOKEN=
-
# Storage provider (local or s3)
NUXT_STORAGE_PROVIDER=local
NUXT_PROVIDER_LOCAL_PATH=/app/data/storage
diff --git a/docs/zh/config.ts b/docs/zh/config.ts
index 4cfd4851..106dabeb 100644
--- a/docs/zh/config.ts
+++ b/docs/zh/config.ts
@@ -25,6 +25,7 @@ export default defineConfig({
text: '配置',
items: [
{ text: '存储提供器', link: '/zh/configuration/storage-providers' },
+ { text: '地图提供器', link: '/zh/configuration/map-providers' },
],
},
{
diff --git a/docs/zh/configuration/map-providers.md b/docs/zh/configuration/map-providers.md
new file mode 100644
index 00000000..e32d1796
--- /dev/null
+++ b/docs/zh/configuration/map-providers.md
@@ -0,0 +1,42 @@
+# 地图提供器
+
+ChronoFrame 支持两种地图提供器,您可以根据需求选择合适的提供器。
+
+| 提供器 | 支持 | 额外配置 | 特性 |
+| --------------------- | :--: | --------------- | ------------------------ |
+| [MapLibre](#maplibre) | ✅ | 无 | 免费开源,支持自定义样式 |
+| [Mapbox](#mapbox) | ✅ | MapBox 访问令牌 | 免费用量,更好的渲染器 |
+
+## MapLibre
+
+将地图提供器配置为 MapLibre 即可,无需其他配置:
+
+```bash
+NUXT_PUBLIC_MAP_PROVIDER=maplibre
+```
+
+### 自定义样式
+
+```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/guide/configuration.md b/docs/zh/guide/configuration.md
index 149993d6..acc3b853 100644
--- a/docs/zh/guide/configuration.md
+++ b/docs/zh/guide/configuration.md
@@ -4,41 +4,42 @@
## 环境变量列表
-| 环境变量 | 说明 | 默认值 | 必需 |
-| ------------------------------------ | ---------------------------------------------------- | ----------------------- | ----------------------------------------- |
-| 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_MAPBOX_ACCESS_TOKEN | Mapbox 访问令牌(可限制 URL),用于地图服务 | 无 | 是 |
-| NUXT_MAPBOX_ACCESS_TOKEN | Mapbox 访问令牌(无 URL 限制),用于位置信息服务 | 无 | 否 |
-| NUXT_STORAGE_PROVIDER | 存储提供者,支持 `local`、`s3` | `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_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 地址(如: 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 类型列表(逗号分隔) | 见下方说明 | 否 |
-| NUXT_UPLOAD_DUPLICATE_CHECK_ENABLED | 是否启用重复文件检测 | `true` | 否 |
-| NUXT_UPLOAD_DUPLICATE_CHECK_MODE | 重复文件处理模式,可选 `warn`、`block`、`skip` | `skip` | 否 |
-| ALLOW_INSECURE_COOKIE | 是否允许非安全 Cookie(仅在开发环境使用) | `false` | 否 |
+| 环境变量 | 说明 | 默认值 | 必需 |
+| ------------------------------------ | ---------------------------------------------------- | ----------------------- | ------------------------------------------------ |
+| 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_MAPBOX_ACCESS_TOKEN | Mapbox 访问令牌(无 URL 限制),用于位置信息服务 | 无 | 否 |
+| NUXT_STORAGE_PROVIDER | 存储提供者,支持 `local`、`s3` | `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_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 地址(如: 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 类型列表(逗号分隔) | 见下方说明 | 否 |
+| NUXT_UPLOAD_DUPLICATE_CHECK_ENABLED | 是否启用重复文件检测 | `true` | 否 |
+| NUXT_UPLOAD_DUPLICATE_CHECK_MODE | 重复文件处理模式,可选 `warn`、`block`、`skip` | `skip` | 否 |
+| ALLOW_INSECURE_COOKIE | 是否允许非安全 Cookie(仅在开发环境使用) | `false` | 否 |
## 上传文件类型白名单
diff --git a/docs/zh/guide/getting-started.md b/docs/zh/guide/getting-started.md
index e43e4485..be7a1228 100644
--- a/docs/zh/guide/getting-started.md
+++ b/docs/zh/guide/getting-started.md
@@ -9,11 +9,6 @@
## 前置准备
- 可用的 [Docker](https://docs.docker.com/get-docker/) 环境。
-- 两个 [Mapbox 访问令牌](https://console.mapbox.com/account/access-tokens/)。
- :::details 为什么需要两个 Token?
- - 第一个(前端)Token 用于 Mapbox GL JS 渲染地图,需要 `styles:read` 权限。建议将其域名限制为你的 ChronoFrame 实例,防止滥用。
- - 第二个(服务端)Token 用于反向地理编码(Mapbox Search API),此 Token **不能** 有 URL 限制。如果不需要反向解析,可以不配置(可选)。
- :::
- 存储后端:可以直接使用内置本地文件系统,也可以配置任意兼容 S3 协议的对象存储。详见 [存储提供者](/zh/configuration/storage-providers)。
:::tip S3 参数清单
若使用 S3,请准备:`ACCESS_KEY_ID`、`SECRET_ACCESS_KEY`、`ENDPOINT`、`BUCKET_NAME`、`REGION`,以及(可选)当外链域名与 ENDPOINT 不同时的 `CDN_URL`。
@@ -60,11 +55,6 @@ NUXT_PUBLIC_APP_SLOGAN=
NUXT_PUBLIC_APP_AUTHOR=
NUXT_PUBLIC_APP_AVATAR_URL=
-# Mapbox 公共访问令牌(地图 UI,必须)
-NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=
-# Mapbox 无域名限制令牌(反向地理编码,可选)
-NUXT_MAPBOX_ACCESS_TOKEN=
-
# 存储提供者(local 或 s3)
NUXT_STORAGE_PROVIDER=local
NUXT_PROVIDER_LOCAL_PATH=/app/data/storage