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(settings): seed app branding from env once, then prefer dashboard

Ahmet Ömeree2c1c24f32b
diff --git a/.env.example b/.env.example
index b9f8bac4..34b6f7c6 100644
--- a/.env.example
+++ b/.env.example
@@ -5,9 +5,10 @@ CFRAME_ADMIN_NAME=
# Admin user password (default to CF1234@!, optional)
CFRAME_ADMIN_PASSWORD=
-# Site configuration
-NUXT_PUBLIC_APP_TITLE=ChronoFrame
-NUXT_PUBLIC_APP_SLOGAN=Mems rest within the lens.
+# Site configuration (optional first-boot seeds; dashboard wins after customization)
+# Leave empty unless you want a non-default title/slogan on a fresh database.
+NUXT_PUBLIC_APP_TITLE=
+NUXT_PUBLIC_APP_SLOGAN=
NUXT_PUBLIC_APP_AUTHOR=
NUXT_PUBLIC_APP_AVATAR_URL=
# Color mode preference: light, dark, or system
diff --git a/README.md b/README.md
index 098701a4..5a569a2e 100644
--- a/README.md
+++ b/README.md
@@ -70,7 +70,7 @@ CFRAME_ADMIN_NAME=
# Admin password (optional, default CF1234@!)
CFRAME_ADMIN_PASSWORD=
-# Site metadata (all optional)
+# Site metadata (optional first-boot seeds only; change later in Dashboard → Settings → General)
NUXT_PUBLIC_APP_TITLE=
NUXT_PUBLIC_APP_SLOGAN=
NUXT_PUBLIC_APP_AUTHOR=
diff --git a/README_zh.md b/README_zh.md
index a0d6a8d0..3a7aa9e6 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -70,7 +70,7 @@ CFRAME_ADMIN_NAME=
# 管理员密码(可选,默认 CF1234@!)
CFRAME_ADMIN_PASSWORD=
-# 站点信息(均可选)
+# 站点信息(可选,仅首次启动写入;之后请在仪表盘 → 设置 → 常规中修改)
NUXT_PUBLIC_APP_TITLE=
NUXT_PUBLIC_APP_SLOGAN=
NUXT_PUBLIC_APP_AUTHOR=
diff --git a/app/components/OgImage/Photo.takumi.vue b/app/components/OgImage/Photo.takumi.vue
index fc1f80cb..b4a09e4c 100644
--- a/app/components/OgImage/Photo.takumi.vue
+++ b/app/components/OgImage/Photo.takumi.vue
@@ -7,16 +7,27 @@ initIconBundle(addIcon)
interface PhotoProps {
photo?: Photo
+ appTitle?: string
}
-const { photo } = defineProps<PhotoProps>()
+const { photo, appTitle: appTitleProp } = defineProps<PhotoProps>()
const { $i18n } = useNuxtApp()
-const config = useRuntimeConfig()
+
+const resolvedAppTitle = computed(() => {
+ if (typeof appTitleProp === 'string' && appTitleProp.length > 0) {
+ return appTitleProp
+ }
+ const fromSettings = getSetting('app:title')
+ if (typeof fromSettings === 'string' && fromSettings.length > 0) {
+ return fromSettings
+ }
+ return 'ChronoFrame'
+})
const headline = computed(() => (photo ? $i18n.t('title.fallback.photo') : 'ChronoFrame'))
-const title = computed(() => (photo?.title || config.public.app.title).slice(0, 60))
-const description = computed(() => (photo ? photo.description || '' : config.public.app.title).slice(0, 200))
+const title = computed(() => (photo?.title || resolvedAppTitle.value).slice(0, 60))
+const description = computed(() => (photo ? photo.description || '' : resolvedAppTitle.value).slice(0, 200))
const thumbnailUrl = computed(() =>
photo?.thumbnailKey && photo.thumbnailUrl
? `/thumb/${encodeURIComponent(photo.thumbnailUrl)}`
@@ -47,7 +58,7 @@ const thumbnailUrl = computed(() =>
v-if="headline"
class="m-0 mb-2 uppercase text-4xl font-semibold text-rose-500"
>
- {{ headline }} · {{ config.public.app.title }}
+ {{ headline }} · {{ resolvedAppTitle }}
</p>
<h1
v-if="title"
diff --git a/app/pages/[...slug].vue b/app/pages/[...slug].vue
index 5777fbb0..88c5c15a 100644
--- a/app/pages/[...slug].vue
+++ b/app/pages/[...slug].vue
@@ -21,6 +21,7 @@ const currentPhoto = computed(() =>
defineOgImage('Photo', {
photo: currentPhoto.value || undefined,
+ appTitle: (getSetting('app:title') as string) || 'ChronoFrame',
})
// 处理标签查询参数
diff --git a/app/pages/albums/index.vue b/app/pages/albums/index.vue
index 2f4ec8ef..3d1f96c8 100644
--- a/app/pages/albums/index.vue
+++ b/app/pages/albums/index.vue
@@ -4,7 +4,7 @@ import type { Album } from '~~/server/utils/db'
interface AlbumWithPhotos extends Album {
photoIds?: string[]
}
-const config = useRuntimeConfig()
+const appSlogan = useSettingRef('app:slogan')
const { photos } = usePhotos()
const { loggedIn } = useUserSession()
const { data: albums } = useAsyncData<AlbumWithPhotos[]>(
@@ -202,7 +202,7 @@ const hoveredAlbum = ref<number | null>(null)
<p
class="mt-2 text-lg text-neutral-600 dark:text-neutral-400 font-medium font-[Pacifico]"
>
- {{ config.public.app.slogan }}
+ {{ appSlogan }}
</p>
</div>
diff --git a/app/pages/dashboard/index.vue b/app/pages/dashboard/index.vue
index a70d8a7d..e07d4b7f 100644
--- a/app/pages/dashboard/index.vue
+++ b/app/pages/dashboard/index.vue
@@ -11,7 +11,8 @@ useHead({
})
const dayjs = useDayjs()
-const config = useRuntimeConfig()
+const appTitle = useSettingRef('app:title')
+const appSlogan = useSettingRef('app:slogan')
const { photos } = usePhotos()
const { data: dashboardStats, refresh: refreshStats } =
@@ -128,8 +129,8 @@ const yearOptions = computed(() => {
const onShareSite = () => {
const discussionParams = new URLSearchParams({
category: 'showcases',
- title: `Show: ${config.public.app.title}`,
- body: `## Description / Motto\n\n${config.public.app.slogan}\n\n## URL\n\n[${window.location.origin}](${window.location.origin})`,
+ title: `Show: ${appTitle.value || 'ChronoFrame'}`,
+ body: `## Description / Motto\n\n${appSlogan.value || ''}\n\n## URL\n\n[${window.location.origin}](${window.location.origin})`,
})
window.open(
`https://github.com/HoshinoSuzumi/chronoframe/discussions/new?${discussionParams}`,
diff --git a/app/pages/signin.vue b/app/pages/signin.vue
index 0e1a3a72..36580929 100644
--- a/app/pages/signin.vue
+++ b/app/pages/signin.vue
@@ -11,6 +11,7 @@ const route = useRoute()
const router = useRouter()
const isLoading = ref(false)
+const appTitle = useSettingRef('app:title')
const githubOauthEnabled = computed(() => {
const settingsValue = settingsStore.getSetting('system:auth.github.enabled')
@@ -51,7 +52,7 @@ const onAuthSubmit = async (event: any) => {
>
<AuthForm
:title="$t('auth.form.signin.title')"
- :subtitle="$t('auth.form.signin.subtitle', [config.public.app.title])"
+ :subtitle="$t('auth.form.signin.subtitle', [appTitle || 'ChronoFrame'])"
:loading="isLoading"
:providers="[
githubOauthEnabled && {
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
index 8178372a..039a7c56 100644
--- a/docs/guide/configuration.md
+++ b/docs/guide/configuration.md
@@ -9,10 +9,10 @@ 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 |
-| 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_APP_TITLE | Initial application title (seeded once into settings; dashboard wins after) | `ChronoFrame` | No |
+| NUXT_PUBLIC_APP_SLOGAN | Initial application slogan (seeded once into settings; dashboard wins after) | None | No |
+| NUXT_PUBLIC_APP_AUTHOR | Initial application author (seeded once into settings; dashboard wins after) | None | No |
+| NUXT_PUBLIC_APP_AVATAR_URL | Initial application avatar URL (seeded once into settings; dashboard wins after) | 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` |
@@ -50,6 +50,30 @@ 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 |
+## App settings vs environment variables
+
+`NUXT_PUBLIC_APP_TITLE`, `NUXT_PUBLIC_APP_SLOGAN`, `NUXT_PUBLIC_APP_AUTHOR`, and `NUXT_PUBLIC_APP_AVATAR_URL` are **first-boot seeds** only.
+
+On startup, ChronoFrame copies an env value into the settings database **only when**:
+
+1. The env var is explicitly set to a non-empty value, and
+2. That setting still equals its schema default (never customized)
+
+After you change Instance Name (or related fields) in **Dashboard → Settings → General**, or during the setup wizard, the database value is the source of truth. Later restarts do **not** re-apply env, even if the env var still holds an older title.
+
+Recommendations:
+
+- Prefer setting the instance name in the dashboard after install.
+- Leave these env vars empty unless you want a non-default title on a fresh database.
+- In Docker Compose / Coolify, avoid personal fallbacks such as `${CFRAME_APP_TITLE:-My Studio Name}`. Empty should stay empty:
+
+```yaml
+environment:
+ NUXT_PUBLIC_APP_TITLE: '${CFRAME_APP_TITLE:-}'
+```
+
+Clearing an env var does not reset a title already stored in the database; change it in the dashboard instead.
+
## Upload File Type Whitelist
The default value of `NUXT_UPLOAD_MIME_WHITELIST` includes the following MIME types:
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index c5341a4d..4838d621 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -51,7 +51,7 @@ CFRAME_ADMIN_NAME=
# Admin password (optional, default CF1234@!)
CFRAME_ADMIN_PASSWORD=
-# Site metadata (all optional)
+# Site metadata (optional first-boot seeds only; change later in Dashboard → Settings → General)
NUXT_PUBLIC_APP_TITLE=
NUXT_PUBLIC_APP_SLOGAN=
NUXT_PUBLIC_APP_AUTHOR=
diff --git a/docs/zh/guide/configuration.md b/docs/zh/guide/configuration.md
index aecb059e..7af4f3e5 100644
--- a/docs/zh/guide/configuration.md
+++ b/docs/zh/guide/configuration.md
@@ -9,10 +9,10 @@
| 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_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` 时必需 |
@@ -50,6 +50,30 @@
| NUXT_UPLOAD_MIME_WHITELIST | 上传文件允许的 MIME 类型列表(逗号分隔) | 见下方说明 | 否 |
| ALLOW_INSECURE_COOKIE | 是否允许非安全 Cookie(仅在开发环境使用) | `false` | 否 |
+## 应用设置与环境变量
+
+`NUXT_PUBLIC_APP_TITLE`、`NUXT_PUBLIC_APP_SLOGAN`、`NUXT_PUBLIC_APP_AUTHOR`、`NUXT_PUBLIC_APP_AVATAR_URL` 仅作为**首次启动的种子值**。
+
+启动时,ChronoFrame 仅在以下条件同时满足时,才会把环境变量写入设置数据库:
+
+1. 该环境变量被显式设置为非空值,并且
+2. 对应设置仍等于 schema 默认值(尚未被自定义)
+
+在 **仪表盘 → 设置 → 常规** 或安装向导中修改实例名称(及相关字段)后,数据库中的值即为唯一数据源。之后即使环境变量仍保留旧标题,重启也不会再次覆盖。
+
+建议:
+
+- 安装完成后优先在仪表盘中设置实例名称。
+- 除非希望全新数据库使用非默认标题,否则请将这些环境变量留空。
+- 在 Docker Compose / Coolify 中,避免使用个人化的回退值,例如 `${CFRAME_APP_TITLE:-我的工作室}`。空值应保持为空:
+
+```yaml
+environment:
+ NUXT_PUBLIC_APP_TITLE: '${CFRAME_APP_TITLE:-}'
+```
+
+清空环境变量不会重置数据库中已保存的标题;请改在仪表盘中修改。
+
## 上传文件类型白名单
`NUXT_UPLOAD_MIME_WHITELIST` 的默认值包含以下 MIME 类型:
diff --git a/docs/zh/guide/getting-started.md b/docs/zh/guide/getting-started.md
index d6dcd58f..93b73dd0 100644
--- a/docs/zh/guide/getting-started.md
+++ b/docs/zh/guide/getting-started.md
@@ -51,7 +51,7 @@ CFRAME_ADMIN_NAME=
# 管理员密码(可选,默认 CF1234@!)
CFRAME_ADMIN_PASSWORD=
-# 站点信息(均可选)
+# 站点信息(可选,仅首次启动写入;之后请在仪表盘 → 设置 → 常规中修改)
NUXT_PUBLIC_APP_TITLE=
NUXT_PUBLIC_APP_SLOGAN=
NUXT_PUBLIC_APP_AUTHOR=
diff --git a/server/plugins/2.settings-manager.ts b/server/plugins/2.settings-manager.ts
index 0621b61e..cd3bdf2d 100644
--- a/server/plugins/2.settings-manager.ts
+++ b/server/plugins/2.settings-manager.ts
@@ -30,66 +30,75 @@ export default defineNitroPlugin(async (_nitroApp) => {
})
/**
- * Migrate existing configurations from runtimeConfig to the settings system.
+ * Read an environment variable only when the operator explicitly set a
+ * non-empty value. This ignores nuxt.config built-in defaults that always
+ * appear in useRuntimeConfig() (e.g. public.app.title = "ChronoFrame").
+ */
+function getExplicitEnv(name: string): string | undefined {
+ const value = process.env[name]
+ if (typeof value !== 'string') return undefined
+ const trimmed = value.trim()
+ return trimmed.length > 0 ? trimmed : undefined
+}
+
+/**
+ * Seed settings from explicit environment variables.
*
- * Runtime config (env vars / nuxt.config defaults) is only used to seed
- * settings that the user has never customized. Once a value has been changed
- * in the dashboard or the setup wizard, it must survive restarts, so settings
- * that already differ from their default are left untouched.
+ * Env vars are a one-shot bootstrap for fresh installs. Values already
+ * customized in the dashboard or setup wizard (value !== default_value) are
+ * left untouched, so UI changes survive restarts even if env still has an
+ * older title.
*/
async function migrateRuntimeConfigToSettings() {
const config = useRuntimeConfig() as any
const _logger = logger.dynamic('settings-migration')
try {
- // Migrate app settings
- if (config.public.app) {
- _logger.info('Migrating app settings')
- const appSettings = {
- title: config.public.app.title,
- slogan: config.public.app.slogan,
- author: config.public.app.author,
- avatarUrl: config.public.app.avatarUrl,
- }
-
- for (const [key, value] of Object.entries(appSettings)) {
- if (value) {
- await migrateSetting('app', key, value, _logger)
- }
+ _logger.info('Migrating app settings from explicit env')
+ const appEnvSeeds: Array<[string, string | undefined]> = [
+ ['title', getExplicitEnv('NUXT_PUBLIC_APP_TITLE')],
+ ['slogan', getExplicitEnv('NUXT_PUBLIC_APP_SLOGAN')],
+ ['author', getExplicitEnv('NUXT_PUBLIC_APP_AUTHOR')],
+ ['avatarUrl', getExplicitEnv('NUXT_PUBLIC_APP_AVATAR_URL')],
+ ]
+
+ for (const [key, value] of appEnvSeeds) {
+ if (value !== undefined) {
+ await migrateSetting('app', key, value, _logger)
}
}
- // Migrate map settings
- if (config.public.map) {
- _logger.info('Migrating map settings')
- const mapSettings = {
- provider: config.public.map.provider,
- 'mapbox.token': config.mapbox?.accessToken || '',
- 'mapbox.style': config.public.map.mapbox?.style || '',
- 'maplibre.token': config.public.map.maplibre?.token || '',
- 'maplibre.style': config.public.map.maplibre?.style || '',
- }
-
- for (const [key, value] of Object.entries(mapSettings)) {
- if (value) {
- await migrateSetting('map', key, value, _logger)
- }
+ _logger.info('Migrating map settings from explicit env')
+ const mapEnvSeeds: Array<[string, string | undefined]> = [
+ ['provider', getExplicitEnv('NUXT_PUBLIC_MAP_PROVIDER')],
+ ['mapbox.token', getExplicitEnv('NUXT_MAPBOX_ACCESS_TOKEN')],
+ ['mapbox.style', getExplicitEnv('NUXT_PUBLIC_MAP_MAPBOX_STYLE')],
+ ['maplibre.token', getExplicitEnv('NUXT_PUBLIC_MAP_MAPLIBRE_TOKEN')],
+ ['maplibre.style', getExplicitEnv('NUXT_PUBLIC_MAP_MAPLIBRE_STYLE')],
+ ]
+
+ for (const [key, value] of mapEnvSeeds) {
+ if (value !== undefined) {
+ await migrateSetting('map', key, value, _logger)
}
}
- // Migrate auth settings (GitHub OAuth)
- const githubOauthConfig = config.oauth?.github || {}
- if (config.public?.oauth?.github?.enabled === true) {
+ // Migrate auth settings (GitHub OAuth) from explicit env only
+ const githubOauthEnabled = getExplicitEnv('NUXT_PUBLIC_OAUTH_GITHUB_ENABLED')
+ if (githubOauthEnabled === 'true') {
await migrateSetting('system', 'auth.github.enabled', true, _logger)
}
- const githubOauthSettings = {
- 'auth.github.clientId': githubOauthConfig.clientId || '',
- 'auth.github.clientSecret': githubOauthConfig.clientSecret || '',
- }
+ const githubOauthSettings: Array<[string, string | undefined]> = [
+ ['auth.github.clientId', getExplicitEnv('NUXT_OAUTH_GITHUB_CLIENT_ID')],
+ [
+ 'auth.github.clientSecret',
+ getExplicitEnv('NUXT_OAUTH_GITHUB_CLIENT_SECRET'),
+ ],
+ ]
- for (const [key, value] of Object.entries(githubOauthSettings)) {
- if (typeof value === 'string' && value.length > 0) {
+ for (const [key, value] of githubOauthSettings) {
+ if (value !== undefined) {
await migrateSetting('system', key, value, _logger)
}
}
@@ -160,10 +169,10 @@ async function migrateRuntimeConfigToSettings() {
}
/**
- * Write a runtime-config value into a setting, but only if the setting still
- * holds its default value. This keeps the migration one-shot per setting and
- * prevents nuxt.config defaults (e.g. app.title = "ChronoFrame") from
- * overwriting user changes on every server start.
+ * Write an explicit env value into a setting, but only if the setting still
+ * holds its default value. This keeps seeding one-shot per setting and
+ * prevents env / compose defaults from overwriting dashboard changes on
+ * every server start.
*/
async function migrateSetting(
namespace: SettingNamespace,