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.

refactor(ftue): improve storage provider migration and initialization logic (#270)

Timothy Yinc4ac48d61714
diff --git a/server/plugins/2.settings-manager.ts b/server/plugins/2.settings-manager.ts
index b3030a2c..cf2234e5 100644
--- a/server/plugins/2.settings-manager.ts
+++ b/server/plugins/2.settings-manager.ts
@@ -86,41 +86,52 @@ async function migrateRuntimeConfigToSettings() {
config.provider?.[storageProvider as keyof typeof config.provider]
if (providerConfig) {
- try {
- // Check if a provider of the same type already exists
- const existingProviders = await settingsManager.storage.getProviders()
- const sameTypeProviderExists = existingProviders.some(
- (provider) => provider.provider === storageProvider,
+ const normalizedConfig = normalizeProviderConfig(
+ storageProvider,
+ providerConfig,
+ )
+
+ if (!isRuntimeProviderConfigUsable(normalizedConfig)) {
+ _logger.info(
+ `Skipping storage migration for ${storageProvider}: runtime config is incomplete`,
)
-
- if (sameTypeProviderExists) {
- _logger.info(
- `Storage provider of type ${storageProvider} already exists, skipping creation`,
- )
- } else {
- // Create a storage provider from the current configuration
- const providerName = `Migrated ${storageProvider} Provider`
-
- const providerId = await settingsManager.storage.addProvider({
- name: providerName,
- provider: storageProvider as 's3' | 'local' | 'openlist',
- config: normalizeProviderConfig(storageProvider, providerConfig),
- })
-
- // Set this as the active provider
- await settingsManager.set(
- 'storage',
- 'provider',
- providerId,
- undefined,
- true,
- )
- _logger.info(
- `Storage provider migrated and set as active. Provider ID: ${providerId}`,
+ } else {
+ try {
+ // Check if a provider of the same type already exists
+ const existingProviders = await settingsManager.storage.getProviders()
+ const sameTypeProviderExists = existingProviders.some(
+ (provider) => provider.provider === storageProvider,
)
+
+ if (sameTypeProviderExists) {
+ _logger.info(
+ `Storage provider of type ${storageProvider} already exists, skipping creation`,
+ )
+ } else {
+ // Create a storage provider from the current configuration
+ const providerName = `Migrated ${storageProvider} Provider`
+
+ const providerId = await settingsManager.storage.addProvider({
+ name: providerName,
+ provider: storageProvider as 's3' | 'local' | 'openlist',
+ config: normalizedConfig,
+ })
+
+ // Set this as the active provider
+ await settingsManager.set(
+ 'storage',
+ 'provider',
+ providerId,
+ undefined,
+ true,
+ )
+ _logger.info(
+ `Storage provider migrated and set as active. Provider ID: ${providerId}`,
+ )
+ }
+ } catch (error) {
+ _logger.error('Failed to migrate storage provider:', error)
}
- } catch (error) {
- _logger.error('Failed to migrate storage provider:', error)
}
}
}
@@ -194,3 +205,25 @@ function normalizeProviderConfig(provider: string, config: any): any {
return config
}
}
+
+function isRuntimeProviderConfigUsable(config: any): boolean {
+ if (!config || !config.provider) {
+ return false
+ }
+
+ switch (config.provider) {
+ case 's3':
+ return Boolean(
+ config.endpoint &&
+ config.bucket &&
+ config.accessKeyId &&
+ config.secretAccessKey,
+ )
+ case 'local':
+ return Boolean(config.basePath)
+ case 'openlist':
+ return Boolean(config.baseUrl && config.rootPath && config.token)
+ default:
+ return false
+ }
+}
diff --git a/server/plugins/3.storage.ts b/server/plugins/3.storage.ts
index 677359c0..739142e8 100644
--- a/server/plugins/3.storage.ts
+++ b/server/plugins/3.storage.ts
@@ -5,27 +5,69 @@ import { setGlobalStorageManager } from '../services/storage/events'
import { logger } from '../utils/logger'
import { settingsManager } from '../services/settings/settingsManager'
-/**
- * Get the global storage manager instance
- * Used in non-request context (e.g., background tasks, event handlers)
- */
-export function getStorageManager() {
- const storageManager = getGlobalStorageManager()
- if (!storageManager) {
- throw new Error('Storage manager not initialized')
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+const isLocalStorageProvider = (
+ provider: StorageConfig,
+): provider is LocalStorageConfig => {
+ return provider?.provider === 'local'
+}
+
+async function ensureLocalStorageReady(provider: StorageConfig): Promise<void> {
+ if (!isLocalStorageProvider(provider)) {
+ return
+ }
+
+ const localBase = provider.basePath
+ try {
+ if (!path.isAbsolute(localBase)) {
+ logger.storage.warn(`LOCAL basePath is not absolute: ${localBase}`)
+ }
+ await import('node:fs').then(async (m) => {
+ const fs = m.promises as typeof import('node:fs').promises
+ await fs.mkdir(localBase, { recursive: true })
+ })
+ logger.storage.success(`Local storage ready at: ${localBase}`)
+ } catch (err) {
+ logger.storage.error('Failed to prepare local storage directory', err)
}
- return storageManager
}
-export default nitroPlugin(async (nitroApp) => {
- // const config = useRuntimeConfig()
+function attachStorageManagerEvents(storageManager: StorageManager): void {
+ storageManager.on('provider-changed', async (event) => {
+ logger.storage.info(
+ `Storage provider changed from ${event.oldProvider} to ${event.provider}`,
+ )
+
+ if (event.provider === 'local') {
+ try {
+ const newProvider = await settingsManager.storage.getActiveProvider()
+ if (newProvider) {
+ await ensureLocalStorageReady(newProvider.config)
+ }
+ } catch (error) {
+ logger.storage.error('Failed to initialize local storage:', error)
+ }
+ }
+ })
+
+ storageManager.on('provider-error', (event) => {
+ logger.storage.error(
+ `Storage provider error for ${event.provider}: ${event.error?.message}`,
+ )
+ })
+}
+
+export async function initializeStorageManagerFromActiveProvider(
+ reason = 'startup',
+): Promise<boolean> {
+ if (getGlobalStorageManager()) {
+ return true
+ }
// Wait for settings migration to complete if still initializing
- // This ensures we get the active provider after config migration
let activeProvider = await settingsManager.storage.getActiveProvider()
-
if (!activeProvider) {
- // Retry while settings manager is still initializing
let attempts = 0
const maxAttempts = 100 // 5 seconds max with 50ms intervals
@@ -34,84 +76,67 @@ export default nitroPlugin(async (nitroApp) => {
attempts < maxAttempts &&
settingsManager.isInitializing_()
) {
- await new Promise((resolve) => setTimeout(resolve, 50))
+ await wait(50)
activeProvider = await settingsManager.storage.getActiveProvider()
attempts++
}
}
if (!activeProvider) {
- logger.storage.error('No active storage provider configured.')
- return
+ logger.storage.info(
+ `Storage manager init skipped (${reason}): no active storage provider configured yet.`,
+ )
+ return false
}
- const storageConfiguration = activeProvider.config
-
- const storageManager = new StorageManager(
- storageConfiguration,
- logger.storage,
- )
-
- // 设置全局实例
- setGlobalStorageManager(storageManager)
-
- // Set storage manager in context for each request
- nitroApp.hooks.hook('request', (event) => {
- event.context.storage = storageManager
- })
-
- // Initialize local storage directory if needed
- const isLocalStorageProvider = (
- provider: StorageConfig,
- ): provider is LocalStorageConfig => {
- return provider?.provider === 'local'
+ try {
+ const storageManager = new StorageManager(activeProvider.config, logger.storage)
+ setGlobalStorageManager(storageManager)
+ attachStorageManagerEvents(storageManager)
+ await ensureLocalStorageReady(activeProvider.config)
+ logger.storage.success(
+ `Storage manager initialized (${reason}) with provider: ${activeProvider.config.provider}`,
+ )
+ return true
+ } catch (error) {
+ logger.storage.error(
+ `Failed to initialize storage manager (${reason}) with provider ${activeProvider.config.provider}`,
+ error,
+ )
+ return false
}
+}
- if (isLocalStorageProvider(storageConfiguration)) {
- const localBase = storageConfiguration.basePath
- try {
- if (!path.isAbsolute(localBase)) {
- logger.storage.warn(`LOCAL basePath is not absolute: ${localBase}`)
- }
- await import('node:fs').then(async (m) => {
- const fs = m.promises as typeof import('node:fs').promises
- await fs.mkdir(localBase, { recursive: true })
- })
- logger.storage.success(`Local storage ready at: ${localBase}`)
- } catch (err) {
- logger.storage.error('Failed to prepare local storage directory', err)
- }
+/**
+ * Get the global storage manager instance
+ * Used in non-request context (e.g., background tasks, event handlers)
+ */
+export function getStorageManager() {
+ const storageManager = getGlobalStorageManager()
+ if (!storageManager) {
+ throw new Error('Storage manager not initialized')
}
+ return storageManager
+}
- // Setup event listeners for storage manager
- storageManager.on('provider-changed', async (event) => {
- logger.storage.info(
- `Storage provider changed from ${event.oldProvider} to ${event.provider}`,
- )
-
- // Re-initialize local storage if switching to local provider
- if (event.provider === 'local') {
- try {
- const newProvider = await settingsManager.storage.getActiveProvider()
- if (newProvider && isLocalStorageProvider(newProvider.config)) {
- const localBase = newProvider.config.basePath
- await import('node:fs').then(async (m) => {
- const fs = m.promises as typeof import('node:fs').promises
- await fs.mkdir(localBase, { recursive: true })
- })
- logger.storage.success(`Local storage ready at: ${localBase}`)
- }
- } catch (error) {
- logger.storage.error('Failed to initialize local storage:', error)
- }
+export default nitroPlugin(async (nitroApp) => {
+ // Try eager initialization on startup, but do not fail the app if provider
+ // is missing or invalid before onboarding completes.
+ await initializeStorageManagerFromActiveProvider('startup')
+
+ // Always resolve storage manager from global state per-request so late
+ // onboarding configuration can initialize storage without container restart.
+ nitroApp.hooks.hook('request', async (event) => {
+ let storageManager = getGlobalStorageManager()
+ if (!storageManager) {
+ await initializeStorageManagerFromActiveProvider('request')
+ storageManager = getGlobalStorageManager()
}
- })
- storageManager.on('provider-error', (event) => {
- logger.storage.error(
- `Storage provider error for ${event.provider}: ${event.error?.message}`,
- )
+ if (storageManager) {
+ event.context.storage = storageManager
+ }
})
- logger.storage.success('Storage plugin initialized successfully')
+ logger.storage.info('Storage plugin initialized with lazy bootstrap support')
})
diff --git a/server/services/settings/settingsManager.ts b/server/services/settings/settingsManager.ts
index 6645693d..b25abad0 100644
--- a/server/services/settings/settingsManager.ts
+++ b/server/services/settings/settingsManager.ts
@@ -294,24 +294,45 @@ export class SettingsManager {
): Promise<void> {
try {
// Dynamically import to avoid circular dependency issues
- const { getGlobalStorageManager } =
+ const { getGlobalStorageManager, setGlobalStorageManager } =
await import('~~/server/services/storage/events')
+ const { StorageManager } = await import('~~/server/services/storage')
const loggerModule = await import('~~/server/utils/logger')
- const storageManager = getGlobalStorageManager()
- if (!storageManager) {
- this._logger.warn(
- 'Storage manager not initialized, cannot switch provider',
- )
- return
- }
-
const newProvider = await this.storage.getProviderById(providerId)
if (!newProvider) {
this._logger.error(`Provider with ID ${providerId} not found`)
return
}
+ let storageManager = getGlobalStorageManager()
+ if (!storageManager) {
+ this._logger.info(
+ `Storage manager not initialized, bootstrapping with provider: ${newProvider.name} (ID: ${providerId})`,
+ )
+ try {
+ storageManager = new StorageManager(
+ newProvider.config,
+ loggerModule.logger.dynamic('storage'),
+ )
+ setGlobalStorageManager(storageManager)
+
+ if (newProvider.config.provider === 'local') {
+ const fs = await import('node:fs/promises')
+ await fs.mkdir(newProvider.config.basePath, { recursive: true })
+ }
+
+ this._logger.info('Storage manager bootstrap completed')
+ return
+ } catch (bootstrapError) {
+ this._logger.error(
+ 'Failed to bootstrap storage manager with new provider:',
+ bootstrapError,
+ )
+ return
+ }
+ }
+
this._logger.info(
`Triggering storage provider switch to: ${newProvider.name} (ID: ${providerId})`,
)
diff --git a/server/services/storage/index.ts b/server/services/storage/index.ts
index 426c7279..3ad4d41b 100644
--- a/server/services/storage/index.ts
+++ b/server/services/storage/index.ts
@@ -1,4 +1,4 @@
-export { StorageProvider, StorageObject } from './interfaces'
+export type { StorageProvider, StorageObject } from './interfaces'
export {
s3StorageConfigSchema,
@@ -7,7 +7,7 @@ export {
storageConfigSchema,
} from '~~/shared/types/storage'
-export {
+export type {
S3StorageConfig,
LocalStorageConfig,
OpenListStorageConfig,