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.

fix!: correct setup guides and require an explicit seed password

Timothy Yin3e9829d9ea08
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b459cefc..16874e12 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,7 +2,7 @@
Contributions to code, documentation and translations are welcome. The detailed guide is available in [English](https://chronoframe.bh8.ga/development/contributing) and [简体中文](https://chronoframe.bh8.ga/zh/development/contributing).
-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.
+Use Node.js 22, matching the Docker build, and the project's pinned pnpm 10.34.6. This repository contains workspace packages; install dependencies with pnpm.
## Run locally
diff --git a/docker-compose.yml b/docker-compose.yml
index a6667b9e..3fa9a57c 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -8,4 +8,5 @@ services:
volumes:
- ./data:/app/data
env_file:
- - .env
+ - path: .env
+ required: false
diff --git a/docs/changelog.md b/docs/changelog.md
index 108c081b..2eec65d6 100644
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -4,7 +4,7 @@ Changes grouped by stable version. 1.0.0 includes all changes since v0.14.1, wit
## v1.0.0
-[Upgrade guide](/guide/updates) · [Changes since v0.14.1](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.14.1...main)
+[Upgrade guide](/guide/updates) · [Changes since v0.14.1](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.14.1...v1.0.0)
### Features
diff --git a/docs/configuration/map-providers.md b/docs/configuration/map-providers.md
index fa13be5f..d78a48f5 100644
--- a/docs/configuration/map-providers.md
+++ b/docs/configuration/map-providers.md
@@ -4,10 +4,10 @@ Open **Site settings → Maps and locations**. Map display and place-name lookup
## Choose a map service
-| Option | Renderer | Default map data | Required credential |
-| -------- | -------------------------- | ---------------- | -------------------------- |
-| MapLibre | Open-source MapLibre GL JS | MapTiler | MapTiler API key |
-| Mapbox | Mapbox GL JS | Mapbox | Mapbox public access token |
+| Option | Renderer | Default map data | Required credential |
+| -------- | -------------------------- | ---------------- | --------------------------------------- |
+| MapLibre | Open-source MapLibre GL JS | MapTiler | MapTiler API key for the built-in style |
+| Mapbox | Mapbox GL JS | Mapbox | Mapbox public access token |
MapLibre is the renderer; MapTiler supplies map data. The built-in MapLibre style follows the site's light/dark theme. A custom style overrides it. Check each provider's current terms, allowances and pricing.
@@ -63,6 +63,6 @@ MapLibre can display maps while Mapbox or Nominatim identifies places. Troublesh
## Configure later and troubleshoot
-You can skip the token during setup and add it here later. Uploads and photo management still work; map views indicate that setup is missing.
+You can skip the token during setup and add it here later. Uploads and photo management still work. MapLibre views indicate that setup is missing only when neither a token nor a custom style is configured; the built-in MapTiler style requires a key.
For blank maps or 401 / 403 responses, check the provider, token, current URL restrictions and access to styles, tiles and fonts. Update origin restrictions when moving from localhost to a public domain.
diff --git a/docs/legacy/development/contributing.md b/docs/legacy/development/contributing.md
index 4d47fd19..9b14f0cb 100644
--- a/docs/legacy/development/contributing.md
+++ b/docs/legacy/development/contributing.md
@@ -23,12 +23,14 @@ This document will guide you through setting up the ChronoFrame development envi
### 1. Clone Repository
+Fork the repository on GitHub, then replace `YOUR_USERNAME` below with your username.
+
```bash
# Using HTTPS
-git clone https://github.com/HoshinoSuzumi/chronoframe.git
+git clone https://github.com/YOUR_USERNAME/chronoframe.git
# Or using SSH
-git clone [email protected]:HoshinoSuzumi/chronoframe.git
+git clone [email protected]:YOUR_USERNAME/chronoframe.git
# Enter project directory
cd chronoframe
diff --git a/docs/legacy/guide/configuration.md b/docs/legacy/guide/configuration.md
index cf212685..ba1dad1f 100644
--- a/docs/legacy/guide/configuration.md
+++ b/docs/legacy/guide/configuration.md
@@ -16,13 +16,14 @@ Whether using Docker or Docker Compose (.env) deployment, configuration is done
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- | ---------------------------------------------------- |
| 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 |
+| CFRAME_ADMIN_PASSWORD | Initial admin password; set a unique password | None | Required when creating the first administrator |
| 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 | External application avatar URL (an avatar can also be uploaded from the dashboard, stored in the configured storage provider) | 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_MAP_MAPLIBRE_TOKEN | MapTiler API token for the built-in MapLibre style | None | Required for `maplibre` without a custom style |
| 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 |
@@ -38,7 +39,7 @@ Whether using Docker or Docker Compose (.env) deployment, configuration is done
| 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_TOKEN | OpenList API token | None | Required 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 |
@@ -59,6 +60,8 @@ Whether using Docker or Docker Compose (.env) deployment, configuration is done
| 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 |
+Set a unique `CFRAME_ADMIN_PASSWORD` before creating the first administrator. If an existing account uses the former built-in password, rotate it immediately in the dashboard; changing the environment variable alone does not update existing accounts.
+
## Upload File Type Whitelist
The default value of `NUXT_UPLOAD_MIME_WHITELIST` includes the following MIME types:
diff --git a/docs/legacy/guide/getting-started.md b/docs/legacy/guide/getting-started.md
index f25f6d7c..fa6ec6b2 100644
--- a/docs/legacy/guide/getting-started.md
+++ b/docs/legacy/guide/getting-started.md
@@ -56,7 +56,7 @@ Below is the minimal configuration for running with local storage. For the compl
CFRAME_ADMIN_EMAIL=
# Admin username (optional, default Chronoframe)
CFRAME_ADMIN_NAME=
-# Admin password (optional, default CF1234@!)
+# Admin password (required: set a unique password before creating the first administrator)
CFRAME_ADMIN_PASSWORD=
# Site metadata (all optional)
@@ -80,6 +80,8 @@ NUXT_PROVIDER_LOCAL_PATH=/app/data/storage
NUXT_SESSION_PASSWORD=
```
+If an existing account uses the former built-in password, rotate it immediately in the dashboard; changing `CFRAME_ADMIN_PASSWORD` alone does not update existing accounts.
+
If you want to use S3 instead of local storage, replace the storage section with:
```bash
diff --git a/docs/zh/changelog.md b/docs/zh/changelog.md
index 7d8f5be4..722c314e 100644
--- a/docs/zh/changelog.md
+++ b/docs/zh/changelog.md
@@ -4,7 +4,7 @@
## v1.0.0
-[升级指南](/zh/guide/updates) · [自 v0.14.1 起的代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.14.1...main)
+[升级指南](/zh/guide/updates) · [自 v0.14.1 起的代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.14.1...v1.0.0)
### 新功能
diff --git a/docs/zh/configuration/map-providers.md b/docs/zh/configuration/map-providers.md
index cd8636fe..6b2c1b08 100644
--- a/docs/zh/configuration/map-providers.md
+++ b/docs/zh/configuration/map-providers.md
@@ -4,10 +4,10 @@
## 选择地图服务
-| 选项 | 地图由谁渲染 | 默认地图数据 | 需要准备 |
-| -------- | ------------------- | ------------ | ------------------- |
-| MapLibre | 开源 MapLibre GL JS | MapTiler | MapTiler API Key |
-| Mapbox | Mapbox GL JS | Mapbox | Mapbox 公共访问令牌 |
+| 选项 | 地图由谁渲染 | 默认地图数据 | 需要准备 |
+| -------- | ------------------- | ------------ | ----------------------------------- |
+| MapLibre | 开源 MapLibre GL JS | MapTiler | 使用内置样式时需要 MapTiler API Key |
+| Mapbox | Mapbox GL JS | Mapbox | Mapbox 公共访问令牌 |
MapLibre 是渲染器,MapTiler 是提供地图数据的服务,两者不是同一个产品。默认 MapLibre 样式随站点明暗主题切换;自定义样式会覆盖内置样式。服务的免费额度、商用要求和计费以各自官网为准。
@@ -63,6 +63,6 @@ mapbox://styles/YOUR_USERNAME/YOUR_STYLE_ID
## 暂不配置及排查
-设置向导允许先跳过令牌,之后在本页补齐。没有令牌时仍可上传和管理照片,相关地图会提示尚未设置。
+设置向导允许先跳过令牌,之后在本页补齐。仍可上传和管理照片。MapLibre 仅在令牌和自定义样式均未配置时提示尚未设置;使用内置 MapTiler 样式需要 API Key。
地图空白或请求出现 401 / 403 时,核对选择的提供器、令牌、当前域名限制,以及样式、瓦片和字体的访问权限。站点从 localhost 换成正式域名后,要同步修改服务商的来源限制。
diff --git a/docs/zh/legacy/configuration/location-providers.md b/docs/zh/legacy/configuration/location-providers.md
index 83a270e7..12dc1edd 100644
--- a/docs/zh/legacy/configuration/location-providers.md
+++ b/docs/zh/legacy/configuration/location-providers.md
@@ -8,7 +8,7 @@ search: false
# 位置提供器
-位置提供器在处理照片的过程中,将照片的经纬度信息转换为人类可读的城市或国家名称,这一过程成为逆向地理编码(Reverse Geocoding)。
+位置提供器在处理照片的过程中,将照片的经纬度信息转换为人类可读的城市或国家名称,这一过程称为逆向地理编码(Reverse Geocoding)。
默认情况下,您不需要进行任何配置,ChronoFrame 会使用 OpenStreetMap Nominatim 作为默认的位置提供器。
diff --git a/docs/zh/legacy/configuration/map-providers.md b/docs/zh/legacy/configuration/map-providers.md
index c746cbff..86decf78 100644
--- a/docs/zh/legacy/configuration/map-providers.md
+++ b/docs/zh/legacy/configuration/map-providers.md
@@ -17,11 +17,11 @@ ChronoFrame 支持两种地图提供器,您可以根据需求选择合适的
## MapLibre
-要使用 MapLibre 作为地图提供器,您需要一个 [MapTiler 访问令牌](https://cloud.maptiler.com/account/keys/)。
+使用 MapLibre 的内置 MapTiler 样式时,您需要一个 [MapTiler 访问令牌](https://cloud.maptiler.com/account/keys/)。
```bash
NUXT_PUBLIC_MAP_PROVIDER=maplibre
-NUXT_PUBLIC_MAP_MAPLIBRE_TOKEN=your_maplibre_access_token
+NUXT_PUBLIC_MAP_MAPLIBRE_TOKEN=your_maptiler_api_key
```
### 自定义样式
diff --git a/docs/zh/legacy/configuration/storage-providers.md b/docs/zh/legacy/configuration/storage-providers.md
index 0e2b0e5a..a0650a99 100644
--- a/docs/zh/legacy/configuration/storage-providers.md
+++ b/docs/zh/legacy/configuration/storage-providers.md
@@ -204,5 +204,5 @@ NUXT_PROVIDER_OPENLIST_TOKEN=your-static-token
:::
:::details 可以上传但无法访问图片,控制台提示 `Access to fetch at '...' from origin '...' has been blocked by CORS policy`
-存储桶 CORS 配置错误,参考 [CORS 设置](#CORS-设置) 进行配置。
+存储桶 CORS 配置错误,参考 [CORS 设置](#cors-设置) 进行配置。
:::
diff --git a/docs/zh/legacy/development/contributing.md b/docs/zh/legacy/development/contributing.md
index 8521e3ce..ccf9e520 100644
--- a/docs/zh/legacy/development/contributing.md
+++ b/docs/zh/legacy/development/contributing.md
@@ -23,12 +23,14 @@ search: false
### 1. 克隆代码库
+先在 GitHub 上 Fork 仓库,将下方的 `YOUR_USERNAME` 替换为您的用户名。
+
```bash
# 使用 HTTPS
-git clone https://github.com/HoshinoSuzumi/chronoframe.git
+git clone https://github.com/YOUR_USERNAME/chronoframe.git
# 或使用 SSH
-git clone [email protected]:HoshinoSuzumi/chronoframe.git
+git clone [email protected]:YOUR_USERNAME/chronoframe.git
# 进入项目目录
cd chronoframe
diff --git a/docs/zh/legacy/guide/configuration.md b/docs/zh/legacy/guide/configuration.md
index 481ee8a0..3fed6347 100644
--- a/docs/zh/legacy/guide/configuration.md
+++ b/docs/zh/legacy/guide/configuration.md
@@ -16,13 +16,14 @@ search: false
| ---------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------- | --------------------------------------------------------------------- |
| CFRAME_ADMIN_EMAIL | 初始管理员用户的邮箱 | `[email protected]` | 是 |
| CFRAME_ADMIN_NAME | 初始管理员用户的用户名 | `Chronoframe` | 否 |
-| CFRAME_ADMIN_PASSWORD | 初始管理员用户的密码 | `CF1234@!` | 否 |
+| CFRAME_ADMIN_PASSWORD | 初始管理员用户的密码,必须设置独有密码 | 无 | 创建首个管理员时必需 |
| 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_MAP_MAPLIBRE_TOKEN | MapLibre 内置 MapTiler 样式使用的 MapTiler API 令牌 | 无 | 使用 `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 限制),用于位置信息服务 | 无 | 否 |
@@ -59,6 +60,8 @@ search: false
| NUXT_UPLOAD_MIME_WHITELIST | 上传文件允许的 MIME 类型列表(逗号分隔) | 见下方说明 | 否 |
| ALLOW_INSECURE_COOKIE | 是否允许非安全 Cookie(仅在开发环境使用) | `false` | 否 |
+创建首个管理员前,必须设置独有的 `CFRAME_ADMIN_PASSWORD`。如果已有账号使用旧版内置密码,请立即在后台修改密码;仅修改环境变量不会更新已有账号。
+
## 上传文件类型白名单
`NUXT_UPLOAD_MIME_WHITELIST` 的默认值包含以下 MIME 类型:
diff --git a/docs/zh/legacy/guide/getting-started.md b/docs/zh/legacy/guide/getting-started.md
index 379ed60a..e8708bfe 100644
--- a/docs/zh/legacy/guide/getting-started.md
+++ b/docs/zh/legacy/guide/getting-started.md
@@ -56,7 +56,7 @@ docker pull hoshinosuzumi/chronoframe:latest
CFRAME_ADMIN_EMAIL=
# 管理员用户名(可选,默认 ChronoFrame)
CFRAME_ADMIN_NAME=
-# 管理员密码(可选,默认 CF1234@!)
+# 管理员密码(创建首个管理员前必须设置独有密码)
CFRAME_ADMIN_PASSWORD=
# 站点信息(均可选)
@@ -80,6 +80,8 @@ NUXT_PROVIDER_LOCAL_PATH=/app/data/storage
NUXT_SESSION_PASSWORD=
```
+如果已有账号使用旧版内置密码,请立即在后台修改密码;仅修改 `CFRAME_ADMIN_PASSWORD` 不会更新已有账号。
+
若选择使用 S3,请将存储部分替换为:
```bash
diff --git a/server/tasks/db/seed.ts b/server/tasks/db/seed.ts
index 3f6693a0..d2d0ad79 100644
--- a/server/tasks/db/seed.ts
+++ b/server/tasks/db/seed.ts
@@ -13,13 +13,17 @@ export default defineTask({
if (users.length > 0) {
log.info('User already exists, skipping seeding.')
} else {
+ const password = process.env.CFRAME_ADMIN_PASSWORD
+ if (!password?.trim() || password === 'CF1234@!') {
+ throw new Error(
+ 'Set CFRAME_ADMIN_PASSWORD to a unique password before creating the first administrator.',
+ )
+ }
log.info('No users found, creating default admin user...')
await db.insert(tables.users).values({
username: process.env.CFRAME_ADMIN_NAME || 'chronoframe',
email: process.env.CFRAME_ADMIN_EMAIL || '[email protected]',
- password: await hashPassword(
- process.env.CFRAME_ADMIN_PASSWORD || 'CF1234@!',
- ),
+ password: await hashPassword(password),
createdAt: new Date(),
isAdmin: 1,
})