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

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

server/api/files/hls-mp4.post.ts

@@ -0,0 +1,81 @@
+import { createReadStream, promises as fs } from 'node:fs'
+import { randomUUID } from 'node:crypto'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { assertImageOwnership, requireUserAuth } from '../../utils/access'
+import { createApiError } from '../../utils/api-error'
+import { buildAttachmentDisposition } from '../../utils/file-bed'
+import { getImageIndexRow } from '../../utils/image-index'
+import { validateVideoKey } from '../../utils/image-key'
+import { logException, logInfo } from '../../utils/logger'
+import {
+  cleanupExpiredHlsDownloads,
+  markHlsDownloadForCleanup,
+  remuxHlsToMp4
+} from '../../utils/transcode'
+
+interface DownloadBody {
+  key?: string
+}
+
+export default defineEventHandler(async (event) => {
+  const user = await requireUserAuth(event)
+
+  const body = await readBody<DownloadBody>(event).catch(() => null)
+  const key = body?.key
+  if (!key || !validateVideoKey(key)) {
+    createApiError(event, 'INVALID_VIDEO_KEY', '无效的视频路径', 400)
+  }
+
+  const row = getImageIndexRow(key)
+  if (!row?.hls_key) {
+    createApiError(event, 'HLS_NOT_FOUND', 'HLS 视频不存在或尚未转码完成', 404)
+  }
+  await assertImageOwnership(event, row.user_id)
+
+  void cleanupExpiredHlsDownloads()
+  const workDir = join(tmpdir(), `pichost-hls-download-${user.id}-${randomUUID()}`)
+  try {
+    await fs.mkdir(workDir, { recursive: true })
+    await markHlsDownloadForCleanup(workDir)
+  } catch (error) {
+    await fs.rm(workDir, { recursive: true, force: true }).catch(() => {})
+    throw error
+  }
+
+  let outputPath: string
+  try {
+    outputPath = await remuxHlsToMp4(row.hls_key, workDir)
+  } catch (error) {
+    await fs.rm(workDir, { recursive: true, force: true }).catch(() => {})
+    logException('HLS download remux failed', error, { key })
+    createApiError(event, 'HLS_REMUX_FAILED', '视频合并失败，请稍后重试', 500)
+  }
+
+  let outputSize: number
+  try {
+    const stat = await fs.stat(outputPath)
+    if (!stat.isFile() || stat.size === 0) {
+      createApiError(event, 'HLS_REMUX_FAILED', '视频合并失败，请稍后重试', 500)
+    }
+    outputSize = stat.size
+    await markHlsDownloadForCleanup(workDir)
+  } catch (error) {
+    await fs.rm(workDir, { recursive: true, force: true }).catch(() => {})
+    throw error
+  }
+
+  const baseName = row.original_name.replace(/\.[^.]+$/, '') || 'video'
+  setResponseHeader(event, 'Content-Type', 'video/mp4')
+  setResponseHeader(event, 'Content-Length', outputSize)
+  setResponseHeader(event, 'Cache-Control', 'no-store')
+  setResponseHeader(
+    event,
+    'Content-Disposition',
+    buildAttachmentDisposition(`${baseName}.mp4`)
+  )
+
+  logInfo('HLS download remuxed', { key, size: outputSize })
+  await sendStream(event, createReadStream(outputPath))
+  await fs.rm(workDir, { recursive: true, force: true }).catch(() => {})
+})

server/api/files/index.get.ts

@@ -1,3 +1,4 @@
+import type { H3Event } from 'h3'
 import type { FileListResponse } from '~/types/file'
 import type { MediaType, TranscodeStatus } from '../../utils/storage/types'
 import { requireApiOrAdminAuth, getImageUserFilter } from '../../utils/access'
@@ -21,7 +22,10 @@ import {
 } from '../../utils/image-query'
 import { listImages, searchImages } from '../../utils/storage'
 
-export default defineEventHandler(async (event) => {
+export async function handleFileList(
+  event: H3Event,
+  forcedKind?: MediaType
+): Promise<FileListResponse> {
   await requireApiOrAdminAuth(event)
 
   const query = getQuery(event)
@@ -51,7 +55,7 @@ export default defineEventHandler(async (event) => {
   }
 
   // 文件床按类型分工：视频库看 media_type=video，文件库看 media_type=file
-  const kindRaw = typeof query.kind === 'string' ? query.kind.trim() : ''
+  const kindRaw = forcedKind ?? (typeof query.kind === 'string' ? query.kind.trim() : '')
   if (kindRaw && kindRaw !== 'file' && kindRaw !== 'video') {
     createApiError(event, 'INVALID_REQUEST', '无效的文件类型筛选', 400)
   }
@@ -111,6 +115,7 @@ export default defineEventHandler(async (event) => {
       ...(uploadSource === 'web' || uploadSource === 'api' ? { uploadSource } : {}),
       transcodeStatus: stored.transcodeStatus ?? 'none',
       transcodeProgress: stored.transcodeProgress ?? 0,
+      ...(stored.transcodeError ? { transcodeError: stored.transcodeError } : {}),
       ...(stored.transcodePreset ? { transcodePreset: stored.transcodePreset } : {}),
       ...(stored.sourceDeleted ? { sourceDeleted: true } : {}),
       ...(stored.thumbKey
@@ -138,4 +143,6 @@ export default defineEventHandler(async (event) => {
   }
 
   return response
-})
+}
+
+export default defineEventHandler(handleFileList)

server/api/files/search.get.ts

@@ -0,0 +1,16 @@
+import { handleFileList } from './index.get'
+import { createApiError } from '../../utils/api-error'
+
+export default defineEventHandler(async (event) => {
+  const query = getQuery(event)
+  const search = typeof query.q === 'string' ? query.q.trim() : ''
+  if (!search) {
+    createApiError(event, 'INVALID_REQUEST', '搜索关键词不能为空', 400)
+  }
+
+  const kind = typeof query.kind === 'string' ? query.kind.trim() : 'file'
+  if (kind !== 'file' && kind !== 'video') {
+    createApiError(event, 'INVALID_REQUEST', '无效的文件类型筛选', 400)
+  }
+  return handleFileList(event)
+})