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

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

server/api/admin/backup/estimate.get.ts

@@ -1,12 +1,23 @@
 import { requireAdminAuth } from '../../../utils/access'
 import { getBackupExportEstimate } from '../../../utils/backup/stats'
 import { getBackupsDir, isSafeBackupFilename } from '../../../utils/backup/paths'
+import { listAllBackupJobsForUser } from '../../../utils/backup/jobs'
+import { basename, join } from 'node:path'
 import { promises as fs } from 'node:fs'
-import { join } from 'node:path'
 
 export default defineEventHandler(async (event) => {
-  await requireAdminAuth(event)
+  const user = await requireAdminAuth(event)
   const estimate = await getBackupExportEstimate()
+  const allowedArchives = new Set(
+    listAllBackupJobsForUser(user.id).flatMap((job) => {
+      const names: string[] = []
+      if (job.outputPath) names.push(basename(job.outputPath))
+      if (typeof job.payload.archivePath === 'string') {
+        names.push(basename(job.payload.archivePath))
+      }
+      return names
+    })
+  )
 
   const packages = await (async () => {
     try {
@@ -15,6 +26,7 @@ export default defineEventHandler(async (event) => {
       const items = await Promise.all(
         entries
           .filter(entry => entry.isFile() && isSafeBackupFilename(entry.name))
+          .filter(entry => allowedArchives.has(entry.name))
           .map(async (entry) => {
             const full = join(getBackupsDir(), entry.name)
             const fileStat = await fs.stat(full)

server/api/admin/backup/export.post.ts

@@ -5,14 +5,14 @@ import { getBackupExportEstimate } from '../../../utils/backup/stats'
 import { startFullExportJob } from '../../../utils/backup/runner'
 
 export default defineEventHandler(async (event) => {
-  await requireAdminAuth(event)
+  const user = await requireAdminAuth(event)
   const config = useRuntimeConfig(event)
   const appVersion = String(config.appVersion ?? '0.0.0')
 
   const estimate = await getBackupExportEstimate()
 
   try {
-    const job = startFullExportJob(appVersion)
+    const job = startFullExportJob(appVersion, user.id)
     return {
       job: serializeBackupJob(job),
       estimate

server/api/admin/backup/jobs/[id].get.ts

@@ -4,13 +4,13 @@ import { serializeBackupJob } from '../../../../utils/backup/api'
 import { getBackupJob } from '../../../../utils/backup/jobs'
 
 export default defineEventHandler(async (event) => {
-  await requireAdminAuth(event)
+  const user = await requireAdminAuth(event)
   const id = getRouterParam(event, 'id')
   if (!id) {
     createApiError(event, 'INVALID_REQUEST', '缺少任务 ID', 400)
   }
 
-  const job = getBackupJob(id)
+  const job = getBackupJob(id, user.id)
   if (!job) {
     createApiError(event, 'INVALID_REQUEST', '任务不存在', 404)
   }

server/api/admin/backup/jobs/[id]/cancel.post.ts

@@ -5,16 +5,19 @@ import { getBackupJob } from '../../../../../utils/backup/jobs'
 import { cancelBackupJob } from '../../../../../utils/backup/runner'
 
 export default defineEventHandler(async (event) => {
-  await requireAdminAuth(event)
+  const user = await requireAdminAuth(event)
   const id = getRouterParam(event, 'id')
   if (!id) {
     createApiError(event, 'INVALID_REQUEST', '缺少任务 ID', 400)
   }
 
+  if (!getBackupJob(id, user.id)) {
+    createApiError(event, 'INVALID_REQUEST', '任务不存在', 404)
+  }
   if (!cancelBackupJob(id)) {
     createApiError(event, 'INVALID_REQUEST', '只能取消进行中的任务', 400)
   }
 
-  const job = getBackupJob(id)
+  const job = getBackupJob(id, user.id)
   return { job: job ? serializeBackupJob(job) : null }
 })

server/api/admin/backup/jobs/[id]/download.get.ts

@@ -6,13 +6,13 @@ import { getBackupJob } from '../../../../../utils/backup/jobs'
 import { BACKUP_ARCHIVE_EXT } from '../../../../../utils/backup/paths'
 
 export default defineEventHandler(async (event) => {
-  await requireAdminAuth(event)
+  const user = await requireAdminAuth(event)
   const id = getRouterParam(event, 'id')
   if (!id) {
     createApiError(event, 'INVALID_REQUEST', '缺少任务 ID', 400)
   }
 
-  const job = getBackupJob(id)
+  const job = getBackupJob(id, user.id)
   if (!job || job.type !== 'full_export' || job.status !== 'done' || !job.outputPath) {
     createApiError(event, 'INVALID_REQUEST', '可下载的备份不存在', 404)
   }

server/api/admin/backup/jobs/[id]/retry.post.ts

@@ -5,13 +5,13 @@ import { serializeBackupJob } from '../../../../../utils/backup/api'
 import { getBackupJob } from '../../../../../utils/backup/jobs'
 
 export default defineEventHandler(async (event) => {
-  await requireAdminAuth(event)
+  const user = await requireAdminAuth(event)
   const id = getRouterParam(event, 'id')
   if (!id) {
     createApiError(event, 'INVALID_REQUEST', '缺少任务 ID', 400)
   }
 
-  const job = getBackupJob(id)
+  const job = getBackupJob(id, user.id)
   if (!job || job.type !== 'backend_sync') {
     createApiError(event, 'INVALID_REQUEST', '任务不存在', 404)
   }
@@ -23,6 +23,6 @@ export default defineEventHandler(async (event) => {
     createApiError(event, 'INVALID_REQUEST', message, 400)
   }
 
-  const updated = getBackupJob(id)
+  const updated = getBackupJob(id, user.id)
   return { job: updated ? serializeBackupJob(updated) : null }
 })

server/api/admin/backup/jobs/index.get.ts

@@ -9,21 +9,21 @@ import {
 import { isBackupRunnerBusy } from '../../../../utils/backup/runner'
 
 export default defineEventHandler(async (event) => {
-  await requireAdminAuth(event)
+  const user = await requireAdminAuth(event)
   if (getRunningBackupJob() && !isBackupRunnerBusy()) {
     recoverInterruptedBackupJobs()
   }
   const query = getQuery(event)
   const pageSize = Math.min(50, Math.max(1, Number(query.pageSize) || 10))
   const pageNum = Math.max(1, Number(query.pageNum) || Number(query.page) || 1)
-  const { jobs, total } = listBackupJobsPage(pageNum, pageSize)
+  const { jobs, total } = listBackupJobsPage(pageNum, pageSize, user.id)
   const totalPages = Math.max(1, Math.ceil(total / pageSize))
   const page = total > 0 ? Math.min(pageNum, totalPages) : 1
   const slice = page === pageNum
     ? jobs
-    : listBackupJobsPage(page, pageSize).jobs
+    : listBackupJobsPage(page, pageSize, user.id).jobs
 
-  const activeJob = getActiveBackupJob()
+  const activeJob = getActiveBackupJob(user.id)
 
   return {
     jobs: slice.map(serializeBackupJob),

server/api/admin/backup/restore.post.ts

@@ -4,13 +4,14 @@ import { createApiError } from '../../../utils/api-error'
 import { serializeBackupJob } from '../../../utils/backup/api'
 import { previewFullRestore } from '../../../utils/backup/full-restore'
 import { startFullRestoreJob } from '../../../utils/backup/runner'
+import { listAllBackupJobsForUser } from '../../../utils/backup/jobs'
 import {
   BACKUP_ARCHIVE_EXT,
   getBackupsDir,
   getBackupStagingDir,
   isSafeBackupFilename
 } from '../../../utils/backup/paths'
-import { join } from 'node:path'
+import { basename, join } from 'node:path'
 import { promises as fs } from 'node:fs'
 
 interface RestoreBody {
@@ -19,7 +20,7 @@ interface RestoreBody {
   dryRun?: boolean
 }
 
-async function resolveRestoreInput(event: H3Event): Promise<{
+async function resolveRestoreInput(event: H3Event, userId: number): Promise<{
   archivePath: string
   body: RestoreBody
   cleanup?: () => Promise<void>
@@ -71,6 +72,19 @@ async function resolveRestoreInput(event: H3Event): Promise<{
   if (!body?.archiveName || !isSafeBackupFilename(body.archiveName)) {
     createApiError(event, 'INVALID_REQUEST', '请选择有效的备份文件', 400)
   }
+  const allowedArchives = new Set(
+    listAllBackupJobsForUser(userId).flatMap((job) => {
+      const names: string[] = []
+      if (job.outputPath) names.push(basename(job.outputPath))
+      if (typeof job.payload.archivePath === 'string') {
+        names.push(basename(job.payload.archivePath))
+      }
+      return names
+    })
+  )
+  if (!allowedArchives.has(body.archiveName)) {
+    createApiError(event, 'INVALID_REQUEST', '备份文件不存在', 404)
+  }
   const archivePath = join(getBackupsDir(), body.archiveName)
   try {
     await fs.access(archivePath)
@@ -81,9 +95,9 @@ async function resolveRestoreInput(event: H3Event): Promise<{
 }
 
 export default defineEventHandler(async (event) => {
-  await requireAdminAuth(event)
+  const user = await requireAdminAuth(event)
 
-  const { archivePath, body, cleanup } = await resolveRestoreInput(event)
+  const { archivePath, body, cleanup } = await resolveRestoreInput(event, user.id)
 
   const conflictMode = body.conflictMode === 'skip' ? 'skip' : 'overwrite'
 
@@ -97,7 +111,7 @@ export default defineEventHandler(async (event) => {
   }
 
   try {
-    const job = startFullRestoreJob(archivePath, conflictMode)
+    const job = startFullRestoreJob(archivePath, conflictMode, user.id)
     return { job: serializeBackupJob(job) }
   } catch (error) {
     if (error instanceof Error && error.message === 'BACKUP_JOB_RUNNING') {

server/api/admin/storage/sync.post.ts

@@ -13,7 +13,7 @@ interface SyncBody {
 }
 
 export default defineEventHandler(async (event) => {
-  await requireAdminAuth(event)
+  const user = await requireAdminAuth(event)
   const body = await readBody<SyncBody>(event)
 
   const fromBackendId = body?.fromBackendId?.trim() ?? ''
@@ -36,7 +36,7 @@ export default defineEventHandler(async (event) => {
       return { preview }
     }
 
-    const job = startBackendSyncJob(options)
+    const job = startBackendSyncJob(options, user.id)
     return { job: serializeBackupJob(job) }
   } catch (error) {
     if (error instanceof Error) {

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)
+})

server/api/user/storage/purge.post.ts

@@ -0,0 +1,31 @@
+import { requireUserAuth } from '../../../utils/access'
+import { createApiError } from '../../../utils/api-error'
+import { logInfo } from '../../../utils/logger'
+import { clearUserStorage } from '../../../utils/user-storage'
+
+export default defineEventHandler(async (event) => {
+  const user = await requireUserAuth(event)
+  const body = await readBody<{ confirmation?: string }>(event).catch(() => null)
+  if (!['我已确认', 'I confirm'].includes(body?.confirmation?.trim() ?? '')) {
+    createApiError(event, 'INVALID_REQUEST', '请输入“我已确认”以继续', 400)
+  }
+
+  try {
+    const result = await clearUserStorage(user.id)
+    logInfo('user storage cleared', {
+      userId: user.id,
+      deletedMedia: result.deletedMedia,
+      deletedObjects: result.deletedObjects,
+      failed: result.failed.length
+    })
+    return result
+  } catch (error) {
+    if (error instanceof Error && error.message === 'USER_STORAGE_CLEAR_IN_PROGRESS') {
+      createApiError(event, 'CONFLICT', '清空存储任务正在执行，请勿重复操作', 409)
+    }
+    if (error instanceof Error && error.message === 'USER_STORAGE_CLEAR_ACTIVE_JOB') {
+      createApiError(event, 'CONFLICT', '当前有备份或迁移任务正在运行，请完成后再清空存储', 409)
+    }
+    throw error
+  }
+})

server/api/videos/search.get.ts

@@ -0,0 +1,11 @@
+import { handleFileList } from '../files/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)
+  }
+  return handleFileList(event, 'video')
+})

server/api/videos/upload.post.ts

@@ -10,7 +10,12 @@ import { MAX_FILES_PER_UPLOAD } from '../../utils/constants'
 import { createApiError } from '../../utils/api-error'
 import { checkUploadRateLimit } from '../../utils/rate-limit'
 import { processSingleVideoUpload } from '../../utils/file-bed'
-import { enqueueTranscode } from '../../utils/transcode'
+import {
+  enqueueTranscode,
+  MAX_TRANSCODE_BITRATE_PERCENT,
+  MIN_TRANSCODE_BITRATE_PERCENT,
+  parseTranscodePreset
+} from '../../utils/transcode'
 import { getFileBedAccessMode } from '../../utils/env'
 
 export default defineEventHandler(async (event) => {
@@ -37,6 +42,36 @@ export default defineEventHandler(async (event) => {
       )
     : false
 
+  const presetField = formData.find(part => part.name === 'transcodePreset')
+  const presetRaw = presetField?.data?.length
+    ? new TextDecoder().decode(presetField.data).trim()
+    : ''
+  const transcodePreset = presetRaw ? parseTranscodePreset(presetRaw) : undefined
+  if (presetRaw && !transcodePreset) {
+    createApiError(event, 'INVALID_REQUEST', '无效的转码质量档位', 400)
+  }
+
+  const bitrateField = formData.find(part => part.name === 'transcodeBitratePercent')
+  const bitrateRaw = bitrateField?.data?.length
+    ? new TextDecoder().decode(bitrateField.data).trim()
+    : ''
+  const transcodeBitratePercent = bitrateRaw ? Number(bitrateRaw) : undefined
+  if (
+    bitrateRaw
+    && (
+      !Number.isInteger(transcodeBitratePercent)
+      || transcodeBitratePercent! < MIN_TRANSCODE_BITRATE_PERCENT
+      || transcodeBitratePercent! > MAX_TRANSCODE_BITRATE_PERCENT
+    )
+  ) {
+    createApiError(
+      event,
+      'INVALID_REQUEST',
+      `转码目标码率需为 ${MIN_TRANSCODE_BITRATE_PERCENT}–${MAX_TRANSCODE_BITRATE_PERCENT} 的整数`,
+      400
+    )
+  }
+
   const fileParts = formData.filter(
     part => (part.name === 'file' || part.name === 'files' || part.name === 'video')
       && part.data?.length
@@ -82,7 +117,10 @@ export default defineEventHandler(async (event) => {
 
   if (wantTranscode) {
     for (const item of items) {
-      enqueueTranscode(item.key)
+      enqueueTranscode(item.key, {
+        ...(transcodePreset ? { preset: transcodePreset } : {}),
+        ...(transcodeBitratePercent !== undefined ? { bitratePercent: transcodeBitratePercent } : {})
+      })
     }
   }