From 76328fa058ace3c853f44042cb8f2e782b36be4b Mon Sep 17 00:00:00 2001
From: tianmo <tianmokeji6001@icloud.com>
Date: Sat, 17 Oct 2026 16:19:18 +0800
Subject: [PATCH] feat: add thumbnail timeout and low-memory warning

---
 app/components/UploadPreferencesPanel.vue     | 21 ++++++
 .../SettingsVideoProcessingFields.vue         | 21 ++++++
 app/composables/useTranscodeSettings.ts       | 13 ++++
 i18n/locales/en.json                          |  2 +
 i18n/locales/zh-CN.json                       |  2 +
 server/api/videos/transcode-settings.get.ts   |  7 +-
 server/utils/system-resources.test.ts         | 24 +++++++
 server/utils/system-resources.ts              | 42 ++++++++++++
 server/utils/transcode.test.ts                | 15 ++++-
 server/utils/transcode.ts                     | 66 ++++++++++++++-----
 10 files changed, 196 insertions(+), 17 deletions(-)
 create mode 100644 server/utils/system-resources.test.ts
 create mode 100644 server/utils/system-resources.ts

diff --git a/app/components/UploadPreferencesPanel.vue b/app/components/UploadPreferencesPanel.vue
index 5f6f5ae..03ce0ff 100644
--- a/app/components/UploadPreferencesPanel.vue
+++ b/app/components/UploadPreferencesPanel.vue
@@ -31,6 +31,11 @@ const gridClass = computed(() => {
 })
 
 const { t } = useI18n()
+const {
+  lowMemory,
+  memoryBytes,
+  load: loadTranscodeSettings
+} = useTranscodeSettings()
 
 const {
   userSettings,
@@ -52,6 +57,12 @@ const clientQualityLevel = computed(() => {
   return t('preferences.qualityLow')
 })
 
+const memoryGb = computed(() => (
+  memoryBytes.value > 0
+    ? (memoryBytes.value / (1024 * 1024 * 1024)).toFixed(1)
+    : '—'
+))
+
 function setCopyFormat(value: 'url' | 'markdown' | 'html' | 'bbcode') {
   copyFormat.value = value
 }
@@ -64,6 +75,7 @@ function onClientQualityInput(event: Event) {
 onMounted(() => {
   loadPreferences()
   void loadUserSettings()
+  void loadTranscodeSettings()
 })
 </script>
 
@@ -170,6 +182,15 @@ onMounted(() => {
             {{ t('preferences.videoProcessing') }}
           </h3>
 
+          <UAlert
+            v-if="lowMemory"
+            color="warning"
+            variant="subtle"
+            icon="i-lucide-triangle-alert"
+            :title="t('preferences.lowMemoryTranscodeTitle')"
+            :description="t('preferences.lowMemoryTranscodeHint', { memory: memoryGb })"
+          />
+
           <label class="flex cursor-pointer items-start gap-2.5">
             <UCheckbox
               v-model="transcodeToHls"
diff --git a/app/components/settings/SettingsVideoProcessingFields.vue b/app/components/settings/SettingsVideoProcessingFields.vue
index 0d47ab6..f7f60a5 100644
--- a/app/components/settings/SettingsVideoProcessingFields.vue
+++ b/app/components/settings/SettingsVideoProcessingFields.vue
@@ -1,13 +1,34 @@
 <script setup lang="ts">
 const { transcodeToHls, loadPreferences } = useUploadPreferences('video')
 const { t } = useI18n()
+const {
+  lowMemory,
+  memoryBytes,
+  load: loadTranscodeSettings
+} = useTranscodeSettings()
+
+const memoryGb = computed(() => (
+  memoryBytes.value > 0
+    ? (memoryBytes.value / (1024 * 1024 * 1024)).toFixed(1)
+    : '—'
+))
 
 onMounted(() => {
   loadPreferences()
+  void loadTranscodeSettings()
 })
 </script>
 
 <template>
+  <UAlert
+    v-if="lowMemory"
+    color="warning"
+    variant="subtle"
+    icon="i-lucide-triangle-alert"
+    :title="t('preferences.lowMemoryTranscodeTitle')"
+    :description="t('preferences.lowMemoryTranscodeHint', { memory: memoryGb })"
+    class="my-4"
+  />
   <SettingsToggleRow
     v-model="transcodeToHls"
     :title="t('preferences.transcodeToHls')"
diff --git a/app/composables/useTranscodeSettings.ts b/app/composables/useTranscodeSettings.ts
index 23fae69..b9fe5ad 100644
--- a/app/composables/useTranscodeSettings.ts
+++ b/app/composables/useTranscodeSettings.ts
@@ -8,6 +8,9 @@ interface TranscodeSettingsResponse {
   minBitratePercent: number
   maxBitratePercent: number
   presets: string[]
+  memoryBytes: number
+  lowMemoryThresholdBytes: number
+  lowMemory: boolean
 }
 
 /** 服务端转码参数：并发任务数与单任务 CPU 核心数（仅管理员可改） */
@@ -27,6 +30,9 @@ export function useTranscodeSettings() {
   const maxBitratePercent = ref(100)
   const loaded = ref(false)
   const hydrated = ref(false)
+  const memoryBytes = ref(0)
+  const lowMemoryThresholdBytes = ref(2 * 1024 * 1024 * 1024)
+  const lowMemory = ref(false)
 
   let saveTimer: ReturnType<typeof setTimeout> | null = null
 
@@ -41,6 +47,10 @@ export function useTranscodeSettings() {
     if (data.presets?.length) presets.value = data.presets
     maxConcurrency.value = data.maxConcurrency
     maxThreads.value = data.maxThreads
+    memoryBytes.value = data.memoryBytes ?? 0
+    lowMemoryThresholdBytes.value = data.lowMemoryThresholdBytes
+      ?? 2 * 1024 * 1024 * 1024
+    lowMemory.value = data.lowMemory === true
     loaded.value = true
     nextTick(() => {
       hydrated.value = true
@@ -108,6 +118,9 @@ export function useTranscodeSettings() {
     presets,
     maxConcurrency,
     maxThreads,
+    memoryBytes,
+    lowMemoryThresholdBytes,
+    lowMemory,
     loaded,
     load
   }
diff --git a/i18n/locales/en.json b/i18n/locales/en.json
index f1e4edf..7fbbcf9 100644
--- a/i18n/locales/en.json
+++ b/i18n/locales/en.json
@@ -308,6 +308,8 @@
     "qualityLow": "Lossy",
     "convenience": "Convenience",
     "videoProcessing": "Video processing",
+    "lowMemoryTranscodeTitle": "Low-memory server warning",
+    "lowMemoryTranscodeHint": "This machine has about {memory} GB of memory, below 2 GB. HLS transcoding is not recommended for now because it may exhaust memory or make the service unstable.",
     "transcodeToHls": "Transcode to m3u8",
     "transcodeToHlsHint": "Segment into HLS, uses extra CPU.",
     "concurrentHint": "at a time",
diff --git a/i18n/locales/zh-CN.json b/i18n/locales/zh-CN.json
index c7f8a7f..fa7574e 100644
--- a/i18n/locales/zh-CN.json
+++ b/i18n/locales/zh-CN.json
@@ -308,6 +308,8 @@
     "qualityLow": "有损压缩",
     "convenience": "便捷功能",
     "videoProcessing": "视频处理",
+    "lowMemoryTranscodeTitle": "低内存服务器提示",
+    "lowMemoryTranscodeHint": "检测到当前机器内存约 {memory} GB，低于 2 GB。暂不建议开启 HLS 转码，以免转码过程导致内存不足或服务不稳定。",
     "transcodeToHls": "转码成 m3u8",
     "transcodeToHlsHint": "自动切片为 HLS，会占用 CPU。",
     "concurrentHint": "同时转码数",
diff --git a/server/api/videos/transcode-settings.get.ts b/server/api/videos/transcode-settings.get.ts
index 215a171..7807801 100644
--- a/server/api/videos/transcode-settings.get.ts
+++ b/server/api/videos/transcode-settings.get.ts
@@ -1,4 +1,5 @@
 import { requireUserAuth } from '../../utils/access'
+import { detectSystemMemory } from '../../utils/system-resources'
 import {
   getTranscodeSettings,
   MAX_TRANSCODE_CONCURRENCY,
@@ -11,12 +12,16 @@ import {
 export default defineEventHandler(async (event) => {
   await requireUserAuth(event)
 
+  const memory = detectSystemMemory()
   return {
     ...getTranscodeSettings(),
     maxConcurrency: MAX_TRANSCODE_CONCURRENCY,
     maxThreads: MAX_TRANSCODE_THREADS,
     minBitratePercent: MIN_TRANSCODE_BITRATE_PERCENT,
     maxBitratePercent: MAX_TRANSCODE_BITRATE_PERCENT,
-    presets: TRANSCODE_PRESETS
+    presets: TRANSCODE_PRESETS,
+    memoryBytes: memory.totalBytes,
+    lowMemoryThresholdBytes: memory.thresholdBytes,
+    lowMemory: memory.lowMemory
   }
 })
diff --git a/server/utils/system-resources.test.ts b/server/utils/system-resources.test.ts
new file mode 100644
index 0000000..c602d0f
--- /dev/null
+++ b/server/utils/system-resources.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import {
+  detectSystemMemory,
+  isLowMemory,
+  LOW_MEMORY_THRESHOLD_BYTES
+} from './system-resources'
+
+describe('system resource detection', () => {
+  it('treats machines below 2 GB as low memory', () => {
+    expect(isLowMemory(1024 * 1024 * 1024)).toBe(true)
+    expect(isLowMemory(LOW_MEMORY_THRESHOLD_BYTES - 1)).toBe(true)
+  })
+
+  it('does not flag machines at or above 2 GB', () => {
+    expect(isLowMemory(LOW_MEMORY_THRESHOLD_BYTES)).toBe(false)
+    expect(isLowMemory(4 * 1024 * 1024 * 1024)).toBe(false)
+  })
+
+  it('returns usable current memory information', () => {
+    const memory = detectSystemMemory()
+    expect(memory.totalBytes).toBeGreaterThan(0)
+    expect(memory.thresholdBytes).toBe(LOW_MEMORY_THRESHOLD_BYTES)
+  })
+})
diff --git a/server/utils/system-resources.ts b/server/utils/system-resources.ts
new file mode 100644
index 0000000..8ec932f
--- /dev/null
+++ b/server/utils/system-resources.ts
@@ -0,0 +1,42 @@
+import { readFileSync } from 'node:fs'
+import { totalmem } from 'node:os'
+
+export const LOW_MEMORY_THRESHOLD_BYTES = 2 * 1024 * 1024 * 1024
+
+export function isLowMemory(bytes: number): boolean {
+  return bytes > 0 && bytes < LOW_MEMORY_THRESHOLD_BYTES
+}
+
+function readCgroupMemoryLimit(): number | null {
+  for (const path of [
+    '/sys/fs/cgroup/memory.max',
+    '/sys/fs/cgroup/memory/memory.limit_in_bytes'
+  ]) {
+    try {
+      const raw = readFileSync(path, 'utf8').trim()
+      if (!raw || raw === 'max') continue
+      const value = Number(raw)
+      if (Number.isFinite(value) && value > 0) return value
+    } catch {
+      // The current platform may not use cgroup memory limits.
+    }
+  }
+  return null
+}
+
+export function detectSystemMemory(): {
+  totalBytes: number
+  lowMemory: boolean
+  thresholdBytes: number
+} {
+  const hostMemory = totalmem()
+  const cgroupLimit = readCgroupMemoryLimit()
+  const totalBytes = cgroupLimit
+    ? Math.min(hostMemory, cgroupLimit)
+    : hostMemory
+  return {
+    totalBytes,
+    lowMemory: isLowMemory(totalBytes),
+    thresholdBytes: LOW_MEMORY_THRESHOLD_BYTES
+  }
+}
diff --git a/server/utils/transcode.test.ts b/server/utils/transcode.test.ts
index 82dad93..1f3da07 100644
--- a/server/utils/transcode.test.ts
+++ b/server/utils/transcode.test.ts
@@ -4,6 +4,7 @@ import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import {
   cleanupExpiredHlsDownloads,
+  buildThumbnailFfmpegArgs,
   DEFAULT_TRANSCODE_CONCURRENCY,
   DEFAULT_TRANSCODE_PRESET,
   DEFAULT_TRANSCODE_THREADS,
@@ -15,7 +16,8 @@ import {
   parseTranscodePreset,
   setTranscodeSettings,
   summarizeTranscodeFailure,
-  thumbKeyFor
+  thumbKeyFor,
+  THUMBNAIL_FFMPEG_TIMEOUT_MS
 } from './transcode'
 import { isVideoSidecarKey, mediaTypeForKey } from './image-key'
 
@@ -28,6 +30,17 @@ describe('hlsPlaylistKey', () => {
   })
 })
 
+describe('thumbnail ffmpeg args', () => {
+  it('limits thumbnail extraction to one worker and one filter thread', () => {
+    const args = buildThumbnailFfmpegArgs('/tmp/input.mp4', '/tmp/thumb.png', 1)
+    expect(args.slice(args.indexOf('-threads'), args.indexOf('-threads') + 2))
+      .toEqual(['-threads', '1'])
+    expect(args.slice(args.indexOf('-filter_threads'), args.indexOf('-filter_threads') + 2))
+      .toEqual(['-filter_threads', '1'])
+    expect(THUMBNAIL_FFMPEG_TIMEOUT_MS).toBe(10_000)
+  })
+})
+
 describe('isVideoSidecarKey', () => {
   it('detects playlists, segments and thumbnails', () => {
     expect(isVideoSidecarKey('videos/2026/10/abc/index.m3u8')).toBe(true)
diff --git a/server/utils/transcode.ts b/server/utils/transcode.ts
index ae7800b..9560fc8 100644
--- a/server/utils/transcode.ts
+++ b/server/utils/transcode.ts
@@ -209,32 +209,67 @@ export function hlsSegmentNames(playlistText: string): string[] {
   return [...names]
 }
 
+export function buildThumbnailFfmpegArgs(
+  inputPath: string,
+  outputPath: string,
+  seek: number
+): string[] {
+  return [
+    '-hide_banner',
+    '-loglevel', 'error',
+    '-threads', '1',
+    '-filter_threads', '1',
+    '-y',
+    '-ss', String(seek),
+    '-i', inputPath,
+    '-frames:v', '1',
+    '-vf', 'scale=640:-2',
+    '-c:v', 'png',
+    outputPath
+  ]
+}
+
+export const THUMBNAIL_FFMPEG_TIMEOUT_MS = 10_000
+
+class ThumbnailFfmpegTimeoutError extends Error {
+  constructor() {
+    super(`缩略图生成超时（${THUMBNAIL_FFMPEG_TIMEOUT_MS / 1000} 秒）`)
+    this.name = 'ThumbnailFfmpegTimeoutError'
+  }
+}
+
 function runThumbFfmpeg(inputPath: string, outputPath: string, seek: number): Promise<void> {
   return new Promise((resolve, reject) => {
-    const child = spawn('ffmpeg', [
-      '-hide_banner',
-      '-loglevel', 'error',
-      '-y',
-      '-ss', String(seek),
-      '-i', inputPath,
-      '-frames:v', '1',
-      '-vf', 'scale=640:-2',
-      '-c:v', 'png',
-      outputPath
-    ], { windowsHide: true })
+    const child = spawn(
+      'ffmpeg',
+      buildThumbnailFfmpegArgs(inputPath, outputPath, seek),
+      { windowsHide: true }
+    )
 
     let stderr = ''
+    let finished = false
+    const finish = (error?: Error) => {
+      if (finished) return
+      finished = true
+      clearTimeout(timer)
+      if (error) reject(error)
+      else resolve()
+    }
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL')
+      finish(new ThumbnailFfmpegTimeoutError())
+    }, THUMBNAIL_FFMPEG_TIMEOUT_MS)
     child.stderr.on('data', (chunk) => {
       stderr += String(chunk)
     })
-    child.on('error', reject)
+    child.on('error', error => finish(error))
     child.on('close', (code) => {
       if (code === 0) {
-        resolve()
+        finish()
         return
       }
       const detail = stderr.trim().split('\n').filter(Boolean).pop()
-      reject(new Error(detail || `ffmpeg 退出码 ${code}`))
+      finish(new Error(detail || `ffmpeg 退出码 ${code}`))
     })
   })
 }
@@ -259,7 +294,8 @@ export async function generateVideoThumbnail(videoKey: string): Promise<string |
 
     try {
       await runThumbFfmpeg(inputPath, framePath, 1)
-    } catch {
+    } catch (error) {
+      if (error instanceof ThumbnailFfmpegTimeoutError) throw error
       await runThumbFfmpeg(inputPath, framePath, 0)
     }