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
fix(settings): seed app branding from env once, then prefer dashboard
Ahmet Ömeree2c1c24f32b
diff --git a/.env.example b/.env.exampleindex 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 systemdiff --git a/README.md b/README.mdindex 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.mdindex 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.vueindex 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><h1v-if="title"diff --git a/app/pages/[...slug].vue b/app/pages/[...slug].vueindex 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.vueindex 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)<pclass="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.vueindex 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.vueindex 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.mdindex 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 WhitelistThe 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.mdindex 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.mdindex 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.mdindex 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.tsindex 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 anyconst _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,