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: add location providers section and links in configuration

HoshinoSuzumiaa5ed305df79
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 8326019d..569a84b6 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -48,6 +48,10 @@ export default defineConfig({
link: '/configuration/storage-providers',
},
{ text: 'Map Providers', link: '/configuration/map-providers' },
+ {
+ text: 'Location Providers',
+ link: '/configuration/location-providers',
+ },
],
},
{
diff --git a/docs/configuration/location-providers.md b/docs/configuration/location-providers.md
new file mode 100644
index 00000000..c37e3664
--- /dev/null
+++ b/docs/configuration/location-providers.md
@@ -0,0 +1,32 @@
+# 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_BASEURL=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/guide/configuration.md b/docs/guide/configuration.md
index c0660271..e382c329 100644
--- a/docs/guide/configuration.md
+++ b/docs/guide/configuration.md
@@ -4,52 +4,53 @@ 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_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`, `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_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_NOMINATIM_BASEURL | 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_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/zh/config.ts b/docs/zh/config.ts
index 106dabeb..6efc81aa 100644
--- a/docs/zh/config.ts
+++ b/docs/zh/config.ts
@@ -26,6 +26,7 @@ export default defineConfig({
items: [
{ text: '存储提供器', link: '/zh/configuration/storage-providers' },
{ text: '地图提供器', link: '/zh/configuration/map-providers' },
+ { text: '位置提供器', link: '/zh/configuration/location-providers' },
],
},
{
diff --git a/docs/zh/configuration/location-providers.md b/docs/zh/configuration/location-providers.md
new file mode 100644
index 00000000..d75e81e5
--- /dev/null
+++ b/docs/zh/configuration/location-providers.md
@@ -0,0 +1,32 @@
+# 位置提供器
+
+位置提供器在处理照片的过程中,将照片的经纬度信息转换为人类可读的城市或国家名称,这一过程成为逆向地理编码(Reverse Geocoding)。
+
+默认情况下,您不需要进行任何配置,ChronoFrame 会使用 OpenStreetMap Nominatim 作为默认的位置提供器。
+
+然而,在下列情况下,您可能有必要配置自定义的位置提供器:
+
+- 服务器位于中国大陆
+- 服务器与 Nominatim 之间的连接受阻
+
+ChronoFrame 支持两种位置提供器,您可以根据需求选择合适的提供器。
+
+## Nominatim
+
+Nominatim 是 OpenStreetMap 提供的免费逆向地理编码服务。默认情况下,ChronoFrame 会使用 Nominatim 作为位置提供器。
+
+如果您的服务器无法连接到 Nominatim 官方的服务,您可以自行搭建反向代理,然后通过下面的配置使用自己的地址:
+
+```bash
+NUXT_NOMINATIM_BASEURL=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/guide/configuration.md b/docs/zh/guide/configuration.md
index ca5b12a8..f0b6491f 100644
--- a/docs/zh/guide/configuration.md
+++ b/docs/zh/guide/configuration.md
@@ -4,52 +4,53 @@
## 环境变量列表
-| 环境变量 | 说明 | 默认值 | 必需 |
-| ------------------------------------ | ---------------------------------------------------- | ----------------------- | ------------------------------------------------ |
-| 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`、`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_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_NOMINATIM_BASEURL | 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_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` | 否 |
## 上传文件类型白名单