feat: 完善媒体管理与备份迁移流程

- 视频上传生成缩略图并提供占位封面和失败原因展示
- 支持 HLS 按需重新封装 MP4，并限制临时文件生命周期与访问权限
- 完善视频、文件 API 文档、搜索、批量删除和单次转码质量参数
- 修复备份恢复与跨后端迁移遗漏缩略图、HLS 清单和分片的问题
- 将备份任务、归档和下载权限按用户隔离
- 增加仅清理当前用户数据的高危存储清空流程和二次文字确认
- 修复 S3 中文文件名元数据及 CLI 数据库连接问题
- 补充备份恢复、用户隔离、媒体资源和转码相关测试

app/components/ClearStorageModal.vue

@@ -0,0 +1,159 @@
+<script setup lang="ts">
+const props = defineProps<{
+  open: boolean
+}>()
+
+const emit = defineEmits<{
+  'update:open': [value: boolean]
+  'cleared': []
+}>()
+
+const { t } = useI18n()
+const toast = useToast()
+const step = ref<'warning' | 'confirm'>('warning')
+const confirmation = ref('')
+const clearing = ref(false)
+
+const canConfirm = computed(() =>
+  !clearing.value && confirmation.value.trim() === t('storage.clearStoragePhrase')
+)
+
+watch(() => props.open, (open) => {
+  if (open) {
+    step.value = 'warning'
+    confirmation.value = ''
+    clearing.value = false
+  }
+})
+
+function close() {
+  if (clearing.value) return
+  emit('update:open', false)
+}
+
+function goToConfirm() {
+  step.value = 'confirm'
+}
+
+function clearBrowserCache() {
+  const keys = [
+    'pichost.upload-preferences',
+    'pichost.upload-preferences.video',
+    'pichost.upload-preferences.file',
+    'pichost.recent-tag-ids',
+    'pichost.library-view.image',
+    'pichost.library-view.video',
+    'pichost.library-view.file'
+  ]
+  for (const key of keys) localStorage.removeItem(key)
+}
+
+async function confirmClear() {
+  if (!canConfirm.value) return
+  clearing.value = true
+  try {
+    const result = await $fetch<{
+      deletedMedia: number
+      deletedObjects: number
+      clearedCacheDirs: number
+      failed: Array<{ key: string }>
+    }>('/api/user/storage/purge', {
+      method: 'POST',
+      credentials: 'include',
+      body: { confirmation: confirmation.value.trim() }
+    })
+
+    clearBrowserCache()
+    emit('cleared')
+
+    if (result.failed.length) {
+      toast.add({
+        title: t('storage.clearStoragePartial', {
+          failed: result.failed.length,
+          total: result.deletedMedia + result.failed.length
+        }),
+        color: 'warning'
+      })
+    } else {
+      toast.add({
+        title: t('storage.clearStorageSuccess', {
+          files: result.deletedObjects,
+          cache: result.clearedCacheDirs
+        }),
+        color: 'success'
+      })
+    }
+    emit('update:open', false)
+  } catch (error: unknown) {
+    const message = error && typeof error === 'object' && 'data' in error
+      ? (error as { data?: { error?: { message?: string } } }).data?.error?.message
+      : undefined
+    toast.add({
+      title: message || t('storage.clearStorageFailed'),
+      color: 'error'
+    })
+  } finally {
+    clearing.value = false
+  }
+}
+</script>
+
+<template>
+  <UModal
+    :open="open"
+    :title="step === 'warning' ? t('storage.clearStorageTitle') : t('storage.clearStorageFinalTitle')"
+    @update:open="emit('update:open', $event)"
+  >
+    <template #body>
+      <template v-if="step === 'warning'">
+        <UAlert
+          color="error"
+          variant="subtle"
+          icon="i-lucide-octagon-alert"
+          :description="t('storage.clearStorageWarning')"
+        />
+        <p class="mt-3 text-sm text-muted">
+          {{ t('storage.clearStorageScope') }}
+        </p>
+      </template>
+
+      <template v-else>
+        <p class="text-sm leading-6 text-muted">
+          {{ t('storage.clearStorageInstruction') }}
+        </p>
+        <UInput
+          v-model="confirmation"
+          class="mt-3 w-full"
+          :placeholder="t('storage.clearStoragePlaceholder')"
+          autofocus
+        />
+      </template>
+    </template>
+
+    <template #footer>
+      <div class="flex w-full justify-end gap-2">
+        <UButton
+          :label="t('common.cancel')"
+          color="neutral"
+          variant="outline"
+          :disabled="clearing"
+          @click="close"
+        />
+        <UButton
+          v-if="step === 'warning'"
+          :label="t('common.continue')"
+          color="error"
+          @click="goToConfirm"
+        />
+        <UButton
+          v-else
+          :label="t('storage.clearStorageConfirm')"
+          color="error"
+          :loading="clearing"
+          :disabled="!canConfirm"
+          @click="confirmClear"
+        />
+      </div>
+    </template>
+  </UModal>
+</template>

app/components/HlsDownloadModal.vue

@@ -0,0 +1,100 @@
+<script setup lang="ts">
+import type { FileItem } from '~/types/file'
+
+const props = defineProps<{
+  open: boolean
+  item: FileItem | null
+}>()
+
+const emit = defineEmits<{
+  'update:open': [value: boolean]
+}>()
+
+const { t } = useI18n()
+const toast = useToast()
+const downloading = ref(false)
+
+watch(() => props.open, (open) => {
+  if (!open) downloading.value = false
+})
+
+async function confirmDownload() {
+  const item = props.item
+  if (!item?.hlsKey || downloading.value) return
+
+  downloading.value = true
+  try {
+    const response = await fetch('/api/files/hls-mp4', {
+      method: 'POST',
+      credentials: 'include',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ key: item.key })
+    })
+
+    if (!response.ok) {
+      const payload = await response.json().catch(() => null) as {
+        error?: { message?: string }
+      } | null
+      throw new Error(payload?.error?.message || t('library.video.downloadMp4Failed'))
+    }
+
+    const blob = await response.blob()
+    const objectUrl = URL.createObjectURL(blob)
+    const dot = item.originalName.lastIndexOf('.')
+    const filename = `${dot > 0 ? item.originalName.slice(0, dot) : item.originalName}.mp4`
+    const link = document.createElement('a')
+    link.href = objectUrl
+    link.download = filename
+    document.body.appendChild(link)
+    link.click()
+    link.remove()
+    setTimeout(() => URL.revokeObjectURL(objectUrl), 0)
+    emit('update:open', false)
+  } catch (error) {
+    toast.add({
+      title: error instanceof Error ? error.message : t('library.video.downloadMp4Failed'),
+      color: 'error'
+    })
+  } finally {
+    downloading.value = false
+  }
+}
+</script>
+
+<template>
+  <UModal
+    :open="open && !!item"
+    :title="t('library.video.downloadMp4Title')"
+    @update:open="emit('update:open', $event)"
+  >
+    <template #body>
+      <p class="text-sm leading-6 text-muted">
+        {{ t('library.video.downloadMp4Confirm') }}
+      </p>
+      <p
+        v-if="downloading"
+        class="mt-3 text-sm text-primary"
+      >
+        {{ t('library.video.downloadMp4Working') }}
+      </p>
+    </template>
+
+    <template #footer>
+      <div class="flex w-full justify-end gap-2">
+        <UButton
+          :label="t('common.cancel')"
+          color="neutral"
+          variant="outline"
+          :disabled="downloading"
+          @click="emit('update:open', false)"
+        />
+        <UButton
+          :label="t('common.continue')"
+          color="primary"
+          :loading="downloading"
+          @click="confirmDownload"
+        />
+      </div>
+    </template>
+  </UModal>
+</template>

app/components/MediaSessionCard.vue

@@ -17,6 +17,7 @@ const emit = defineEmits<{
 
 const { formatFileSize } = useFileSize()
 const { t, locale } = useI18n()
+const transcodeFailureLabel = useTranscodeFailureLabel()
 const { copyFormat } = useUploadPreferences(props.kind)
 
 const copyFormatItems = computed(() => [
@@ -102,22 +103,11 @@ const presetLabel = computed(() => {
 <template>
   <div class="flex flex-col overflow-hidden rounded-xl border border-default bg-elevated shadow-sm">
     <div class="relative aspect-video shrink-0 overflow-hidden bg-muted">
-      <img
-        v-if="kind === 'video' && item.thumbUrl"
+      <VideoThumbnail
+        v-if="kind === 'video'"
         :src="thumbLink"
         :alt="item.originalName"
-        loading="lazy"
-        class="size-full object-cover"
-      >
-      <div
-        v-else-if="kind === 'video'"
-        class="flex size-full items-center justify-center"
-      >
-        <UIcon
-          name="i-lucide-film"
-          class="size-10 text-dimmed"
-        />
-      </div>
+      />
       <div
         v-else
         class="flex size-full items-center justify-center"
@@ -174,9 +164,10 @@ const presetLabel = computed(() => {
           color="error"
           variant="subtle"
           size="xs"
-          class="shrink-0"
+          class="max-w-48 shrink-0 truncate"
+          :title="transcodeFailureLabel(item.transcodeError)"
         >
-          {{ t('library.transcodeFailed') }}
+          {{ transcodeFailureLabel(item.transcodeError) }}
         </UBadge>
         <UBadge
           v-else-if="item.hlsUrl"

app/components/VideoCard.vue

@@ -16,11 +16,13 @@ const props = defineProps<{
 const emit = defineEmits<{
   'play': []
   'delete': []
+  'download': []
   'update:selected': [value: boolean]
 }>()
 
 const { formatFileSize } = useFileSize()
 const { t, locale } = useI18n()
+const transcodeFailureLabel = useTranscodeFailureLabel()
 
 /** 转码完成后按 HLS 播放列表展示 */
 const displayName = computed(() => {
@@ -37,34 +39,15 @@ const uploadedLabel = computed(() => {
     return props.item.uploadedAt
   }
 })
-
-const thumbFailed = ref(false)
-
-watch(() => props.item.thumbUrl, () => {
-  thumbFailed.value = false
-})
 </script>
 
 <template>
   <div class="flex flex-col overflow-hidden rounded-xl border border-default bg-elevated">
     <div class="relative aspect-video shrink-0 overflow-hidden bg-muted">
-      <img
-        v-if="item.thumbUrl && !thumbFailed"
+      <VideoThumbnail
         :src="thumbLink"
         :alt="displayName"
-        loading="lazy"
-        class="size-full object-cover object-center"
-        @error="thumbFailed = true"
-      >
-      <div
-        v-else
-        class="flex size-full items-center justify-center"
-      >
-        <UIcon
-          name="i-lucide-film"
-          class="size-10 text-dimmed"
-        />
-      </div>
+      />
 
       <button
         type="button"
@@ -108,8 +91,10 @@ watch(() => props.item.thumbUrl, () => {
           color="error"
           variant="solid"
           size="xs"
+          class="max-w-48 truncate"
+          :title="transcodeFailureLabel(item.transcodeError)"
         >
-          {{ t('library.transcodeFailed') }}
+          {{ transcodeFailureLabel(item.transcodeError) }}
         </UBadge>
       </div>
     </div>
@@ -162,6 +147,15 @@ watch(() => props.item.thumbUrl, () => {
         rel="noopener"
         :aria-label="t('files.download')"
       />
+      <UButton
+        v-else-if="item.hlsUrl"
+        icon="i-lucide-download"
+        variant="ghost"
+        color="neutral"
+        size="sm"
+        :aria-label="t('library.video.downloadMp4')"
+        @click="emit('download')"
+      />
       <UButton
         icon="i-lucide-trash-2"
         variant="ghost"

app/components/VideoLibraryPanel.vue

@@ -7,6 +7,7 @@ const { isAuthenticated, handleAuthError } = useAuth()
 const toast = useToast()
 const { t, locale } = useI18n()
 const { items: tagItems, fetchTags, batchUpdateTags } = useTags()
+const transcodeFailureLabel = useTranscodeFailureLabel()
 
 const items = ref<FileItem[]>([])
 const total = ref(0)
@@ -27,6 +28,8 @@ const deleteTargetKeys = ref<string[]>([])
 const deleting = ref(false)
 const previewOpen = ref(false)
 const previewItem = ref<FileItem | null>(null)
+const downloadOpen = ref(false)
+const downloadItem = ref<FileItem | null>(null)
 
 const currentBackend = ref('all')
 const currentSource = ref('all')
@@ -66,7 +69,7 @@ function videoLink(item: FileItem): string {
 }
 
 function thumbLink(item: FileItem): string {
-  return withToken(item.thumbUrl)
+  return withToken(item.thumbUrl) || '/video-placeholder.svg'
 }
 
 function downloadUrl(item: FileItem): string {
@@ -264,6 +267,13 @@ function openPreview(item: FileItem) {
   previewOpen.value = true
 }
 
+function requestDownload(item: FileItem | null) {
+  if (!item?.hlsUrl) return
+  previewOpen.value = false
+  downloadItem.value = item
+  downloadOpen.value = true
+}
+
 onMounted(() => {
   void loadBackendOptions()
 })
@@ -514,6 +524,7 @@ defineExpose({ refresh })
           :selected="selectedKeys.has(item.key)"
           @update:selected="toggleSelected(item.key, $event)"
           @play="openPreview(item)"
+          @download="requestDownload(item)"
           @delete="requestDelete(item)"
         />
       </div>
@@ -577,17 +588,9 @@ defineExpose({ refresh })
                       :aria-label="t('library.play')"
                       @click="openPreview(item)"
                     >
-                      <img
-                        v-if="item.thumbUrl"
+                      <VideoThumbnail
                         :src="thumbLink(item)"
                         :alt="displayName(item)"
-                        loading="lazy"
-                        class="size-full object-cover"
-                      >
-                      <UIcon
-                        v-else
-                        name="i-lucide-film"
-                        class="size-5 text-dimmed"
                       />
                     </button>
                     <p
@@ -611,8 +614,9 @@ defineExpose({ refresh })
                       variant="subtle"
                       size="xs"
                       class="shrink-0"
+                      :title="transcodeFailureLabel(item.transcodeError)"
                     >
-                      {{ t('library.transcodeFailed') }}
+                      {{ transcodeFailureLabel(item.transcodeError) }}
                     </UBadge>
                   </div>
                 </td>
@@ -695,6 +699,15 @@ defineExpose({ refresh })
                       rel="noopener"
                       :aria-label="t('files.download')"
                     />
+                    <UButton
+                      v-else-if="item.hlsUrl"
+                      size="xs"
+                      variant="ghost"
+                      color="neutral"
+                      icon="i-lucide-download"
+                      :aria-label="t('library.video.downloadMp4')"
+                      @click="requestDownload(item)"
+                    />
                     <UButton
                       size="xs"
                       variant="ghost"
@@ -746,7 +759,13 @@ defineExpose({ refresh })
       :thumb-link="previewItem ? thumbLink(previewItem) : ''"
       :download-link="previewItem ? downloadUrl(previewItem) : ''"
       :deleting="deleting"
+      @download="requestDownload(previewItem)"
       @delete="previewItem && requestDelete(previewItem)"
     />
+
+    <HlsDownloadModal
+      v-model:open="downloadOpen"
+      :item="downloadItem"
+    />
   </div>
 </template>

app/components/VideoPreviewModal.vue

@@ -20,11 +20,13 @@ const props = withDefaults(defineProps<{
 const emit = defineEmits<{
   'update:open': [value: boolean]
   'delete': []
+  'download': []
 }>()
 
 const toast = useToast()
 const { formatFileSize } = useFileSize()
 const { t, locale } = useI18n()
+const transcodeFailureLabel = useTranscodeFailureLabel()
 const { copyFormat } = useUploadPreferences('video')
 
 const videoEl = ref<HTMLVideoElement | null>(null)
@@ -80,7 +82,7 @@ const transcodeLabel = computed(() => {
     case 'done':
       return t('library.video.transcodeDone')
     case 'failed':
-      return t('library.transcodeFailed')
+      return transcodeFailureLabel(item.transcodeError)
     default:
       return t('library.video.transcodeNone')
   }
@@ -498,6 +500,15 @@ function downloadOriginal() {
           size="sm"
           @click="downloadOriginal"
         />
+        <UButton
+          v-else-if="item.hlsUrl"
+          :label="t('library.video.downloadMp4')"
+          icon="i-lucide-download"
+          color="neutral"
+          variant="outline"
+          size="sm"
+          @click="emit('download')"
+        />
         <UButton
           :label="t('image.previewCopyLink')"
           icon="i-lucide-link"

app/components/VideoThumbnail.vue

@@ -0,0 +1,30 @@
+<script setup lang="ts">
+const props = defineProps<{
+  src?: string
+  alt: string
+}>()
+
+const failed = ref(false)
+
+watch(() => props.src, () => {
+  failed.value = false
+})
+</script>
+
+<template>
+  <img
+    v-if="src && !failed"
+    :src="src"
+    :alt="alt"
+    loading="lazy"
+    class="size-full object-cover object-center"
+    @error="failed = true"
+  >
+  <img
+    v-else
+    src="/video-placeholder.svg"
+    :alt="alt"
+    loading="lazy"
+    class="size-full object-cover object-center"
+  >
+</template>

app/components/api/ApiDebugger.vue

@@ -65,8 +65,14 @@ function resetForm() {
     if (!isDebugParam(param)) continue
     if (param.type === 'file') {
       files[param.name] = null
+    } else if (param.name === 'kind') {
+      values[param.name] = props.endpoint.category === 'video' ? 'video' : 'file'
     } else if (param.name === 'keys') {
-      values[param.name] = '["images/2026/08/example.webp"]'
+      values[param.name] = props.endpoint.category === 'video'
+        ? '["videos/2026/10/example.mp4"]'
+        : props.endpoint.category === 'file'
+          ? '["files/2026/10/example.pdf"]'
+          : '["images/2026/08/example.webp"]'
     } else if (param.name === 'token' && props.token) {
       values[param.name] = props.token
     } else {
@@ -84,6 +90,12 @@ function fileLabel(name: string) {
   return fileValues.value[name]?.name ?? t('api.debug.noFileSelected')
 }
 
+function fileAccept() {
+  if (props.endpoint.category === 'video') return 'video/*'
+  if (props.endpoint.category === 'file') return undefined
+  return 'image/*'
+}
+
 function triggerFilePick(name: string) {
   fileInputRefs.value[name]?.click()
 }
@@ -101,8 +113,8 @@ function isParamFilled(param: ApiDocParam) {
   if (!value) return false
   if (param.location === 'body' && param.name === 'keys') {
     try {
-      const parsed = JSON.parse(value) as { keys?: unknown }
-      return Array.isArray(parsed.keys) && parsed.keys.length > 0
+      const parsed = JSON.parse(value) as unknown
+      return Array.isArray(parsed) && parsed.length > 0
     } catch {
       return false
     }
@@ -159,7 +171,14 @@ async function sendRequest() {
     } else if (debugBodyParams.value.some(p => p.location === 'body')) {
       headers['Content-Type'] = 'application/json'
       try {
-        body = JSON.stringify(JSON.parse(paramValues.value.keys || '{}'))
+        const payload: Record<string, unknown> = {}
+        for (const param of debugBodyParams.value) {
+          if (param.location !== 'body') continue
+          const value = paramValues.value[param.name]?.trim()
+          if (!value) continue
+          payload[param.name] = param.name === 'keys' ? JSON.parse(value) : value
+        }
+        body = JSON.stringify(payload)
       } catch {
         toast.add({ title: t('api.debug.invalidJson'), color: 'error' })
         sending.value = false
@@ -297,7 +316,7 @@ const responseScrollable = computed(() => responseBody.value.split('\n').length
                 <input
                   :ref="(el) => { fileInputRefs[param.name] = el as HTMLInputElement }"
                   type="file"
-                  accept="image/*"
+                  :accept="fileAccept()"
                   class="hidden"
                   @change="onFileChange(param.name, $event)"
                 >

app/components/api/ApiSidebar.vue

@@ -20,9 +20,18 @@ const docsUrl = computed(() =>
 
 const categories: { key: ApiDocCategory, labelKey: string }[] = [
   { key: 'image', labelKey: 'api.categories.image' },
+  { key: 'video', labelKey: 'api.categories.video' },
+  { key: 'file', labelKey: 'api.categories.file' },
   { key: 'extension', labelKey: 'api.categories.extension' },
   { key: 'system', labelKey: 'api.categories.system' }
 ]
+const openCategories = ref<Set<ApiDocCategory>>(
+  new Set(
+    categories
+      .filter(category => category.key !== 'video' && category.key !== 'file')
+      .map(category => category.key)
+  )
+)
 
 const filteredEndpoints = computed(() => {
   const q = search.value.trim().toLowerCase()
@@ -38,6 +47,17 @@ function endpointsForCategory(category: ApiDocCategory) {
   return filteredEndpoints.value.filter(endpoint => endpoint.category === category)
 }
 
+function isCategoryOpen(category: ApiDocCategory) {
+  return openCategories.value.has(category)
+}
+
+function toggleCategory(category: ApiDocCategory) {
+  const next = new Set(openCategories.value)
+  if (next.has(category)) next.delete(category)
+  else next.add(category)
+  openCategories.value = next
+}
+
 function onSelect(id: string) {
   emit('select', id)
 }
@@ -59,6 +79,15 @@ onMounted(() => {
   window.addEventListener('keydown', onGlobalKeydown)
   onUnmounted(() => window.removeEventListener('keydown', onGlobalKeydown))
 })
+
+watch(search, (value) => {
+  if (!value.trim()) return
+  const next = new Set(openCategories.value)
+  for (const category of categories) {
+    if (endpointsForCategory(category.key).length) next.add(category.key)
+  }
+  openCategories.value = next
+})
 </script>
 
 <template>
@@ -89,13 +118,24 @@ onMounted(() => {
         :key="category.key"
         class="mb-4"
       >
-        <p
+        <button
           v-if="endpointsForCategory(category.key).length"
-          class="mb-1.5 px-2 text-xs font-medium text-muted"
+          type="button"
+          class="mb-1.5 flex w-full items-center justify-between rounded-md px-2 py-1 text-xs font-medium text-muted transition-colors hover:bg-muted/40 hover:text-highlighted"
+          :aria-expanded="isCategoryOpen(category.key)"
+          @click="toggleCategory(category.key)"
+        >
+          <span>{{ t(category.labelKey) }}</span>
+          <UIcon
+            name="i-lucide-chevron-down"
+            class="size-3.5 transition-transform"
+            :class="isCategoryOpen(category.key) ? '' : '-rotate-90'"
+          />
+        </button>
+        <ul
+          v-show="isCategoryOpen(category.key)"
+          class="space-y-0.5"
         >
-          {{ t(category.labelKey) }}
-        </p>
-        <ul class="space-y-0.5">
           <li
             v-for="endpoint in endpointsForCategory(category.key)"
             :key="endpoint.id"

app/components/storage/BackupJobTable.vue

@@ -53,6 +53,12 @@ function progressPercent(job: BackupJobItem): number {
   return Math.min(100, Math.round((job.progress / job.total) * 100))
 }
 
+function progressUnit(job: BackupJobItem): string {
+  return job.type === 'full_restore'
+    ? t('storage.backup.progressUnitObjects')
+    : t('storage.backup.progressUnitMedia')
+}
+
 function jobMessage(job: BackupJobItem): string {
   if (job.status === 'failed') {
     return job.error || job.message || t('storage.backup.jobFailedUnknown')
@@ -174,7 +180,7 @@ function formatTime(value: string) {
                 class="text-xs text-dimmed"
               >—</span>
             </td>
-            <td class="min-w-32 px-4 py-3.5 sm:px-5">
+            <td class="min-w-40 px-4 py-3.5 sm:px-5">
               <div class="flex items-center gap-2">
                 <div class="h-1 min-w-0 flex-1 overflow-hidden rounded-full bg-muted">
                   <div
@@ -183,10 +189,15 @@ function formatTime(value: string) {
                     :style="{ width: `${progressPercent(job)}%` }"
                   />
                 </div>
-                <span class="shrink-0 text-xs tabular-nums text-muted">
-                  <template v-if="job.total">{{ job.progress }}/{{ job.total }}</template>
-                  <template v-else-if="job.status === 'done'">100%</template>
-                  <template v-else>—</template>
+                <span class="flex shrink-0 flex-col text-right">
+                  <span class="text-xs tabular-nums text-muted">
+                    <template v-if="job.total">{{ job.progress }}/{{ job.total }}</template>
+                    <template v-else-if="job.status === 'done'">100%</template>
+                    <template v-else>—</template>
+                  </span>
+                  <span class="text-[10px] text-dimmed">
+                    {{ progressUnit(job) }}
+                  </span>
                 </span>
               </div>
             </td>