release: v1.3.0 — 整站备份恢复、跨后端同步与任务中心

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

@@ -0,0 +1,40 @@
+import { requireAdminAuth } from '../../../utils/access'
+import { getBackupExportEstimate } from '../../../utils/backup/stats'
+import { getBackupsDir, isSafeBackupFilename } from '../../../utils/backup/paths'
+import { promises as fs } from 'node:fs'
+import { join } from 'node:path'
+
+export default defineEventHandler(async (event) => {
+  await requireAdminAuth(event)
+  const estimate = await getBackupExportEstimate()
+
+  const packages = await (async () => {
+    try {
+      await fs.mkdir(getBackupsDir(), { recursive: true })
+      const entries = await fs.readdir(getBackupsDir(), { withFileTypes: true })
+      const items = await Promise.all(
+        entries
+          .filter(entry => entry.isFile() && isSafeBackupFilename(entry.name))
+          .map(async (entry) => {
+            const full = join(getBackupsDir(), entry.name)
+            const fileStat = await fs.stat(full)
+            return {
+              name: entry.name,
+              bytes: fileStat.size,
+              modifiedAt: fileStat.mtime.toISOString()
+            }
+          })
+      )
+      items.sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt))
+      return items
+    } catch {
+      return []
+    }
+  })()
+
+  return {
+    estimate,
+    backupsDir: getBackupsDir(),
+    packages
+  }
+})

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

@@ -0,0 +1,26 @@
+import { requireAdminAuth } from '../../../utils/access'
+import { createApiError } from '../../../utils/api-error'
+import { serializeBackupJob } from '../../../utils/backup/api'
+import { getBackupExportEstimate } from '../../../utils/backup/stats'
+import { startFullExportJob } from '../../../utils/backup/runner'
+
+export default defineEventHandler(async (event) => {
+  await requireAdminAuth(event)
+  const config = useRuntimeConfig(event)
+  const appVersion = String(config.appVersion ?? '0.0.0')
+
+  const estimate = await getBackupExportEstimate()
+
+  try {
+    const job = startFullExportJob(appVersion)
+    return {
+      job: serializeBackupJob(job),
+      estimate
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message === 'BACKUP_JOB_RUNNING') {
+      createApiError(event, 'CONFLICT', '已有备份或迁移任务正在运行', 409)
+    }
+    throw error
+  }
+})

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

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

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

@@ -0,0 +1,20 @@
+import { requireAdminAuth } from '../../../../../utils/access'
+import { createApiError } from '../../../../../utils/api-error'
+import { serializeBackupJob } from '../../../../../utils/backup/api'
+import { getBackupJob } from '../../../../../utils/backup/jobs'
+import { cancelBackupJob } from '../../../../../utils/backup/runner'
+
+export default defineEventHandler(async (event) => {
+  await requireAdminAuth(event)
+  const id = getRouterParam(event, 'id')
+  if (!id) {
+    createApiError(event, 'INVALID_REQUEST', '缺少任务 ID', 400)
+  }
+
+  if (!cancelBackupJob(id)) {
+    createApiError(event, 'INVALID_REQUEST', '只能取消进行中的任务', 400)
+  }
+
+  const job = getBackupJob(id)
+  return { job: job ? serializeBackupJob(job) : null }
+})

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

@@ -0,0 +1,29 @@
+import { createReadStream } from 'node:fs'
+import { basename } from 'node:path'
+import { requireAdminAuth } from '../../../../../utils/access'
+import { createApiError } from '../../../../../utils/api-error'
+import { getBackupJob } from '../../../../../utils/backup/jobs'
+import { BACKUP_ARCHIVE_EXT } from '../../../../../utils/backup/paths'
+
+export default defineEventHandler(async (event) => {
+  await requireAdminAuth(event)
+  const id = getRouterParam(event, 'id')
+  if (!id) {
+    createApiError(event, 'INVALID_REQUEST', '缺少任务 ID', 400)
+  }
+
+  const job = getBackupJob(id)
+  if (!job || job.type !== 'full_export' || job.status !== 'done' || !job.outputPath) {
+    createApiError(event, 'INVALID_REQUEST', '可下载的备份不存在', 404)
+  }
+
+  const filename = basename(job.outputPath)
+  if (!filename.endsWith(BACKUP_ARCHIVE_EXT)) {
+    createApiError(event, 'INVALID_REQUEST', '备份文件无效', 404)
+  }
+
+  setResponseHeader(event, 'Content-Type', 'application/gzip')
+  setResponseHeader(event, 'Content-Disposition', `attachment; filename="${filename}"`)
+
+  return sendStream(event, createReadStream(job.outputPath))
+})

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

@@ -0,0 +1,28 @@
+import { requireAdminAuth } from '../../../../../utils/access'
+import { createApiError } from '../../../../../utils/api-error'
+import { retryFailedBackendSync } from '../../../../../utils/backup/backend-sync'
+import { serializeBackupJob } from '../../../../../utils/backup/api'
+import { getBackupJob } from '../../../../../utils/backup/jobs'
+
+export default defineEventHandler(async (event) => {
+  await requireAdminAuth(event)
+  const id = getRouterParam(event, 'id')
+  if (!id) {
+    createApiError(event, 'INVALID_REQUEST', '缺少任务 ID', 400)
+  }
+
+  const job = getBackupJob(id)
+  if (!job || job.type !== 'backend_sync') {
+    createApiError(event, 'INVALID_REQUEST', '任务不存在', 404)
+  }
+
+  try {
+    await retryFailedBackendSync(id)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : '重试失败'
+    createApiError(event, 'INVALID_REQUEST', message, 400)
+  }
+
+  const updated = getBackupJob(id)
+  return { job: updated ? serializeBackupJob(updated) : null }
+})

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

@@ -0,0 +1,36 @@
+import { requireAdminAuth } from '../../../../utils/access'
+import { serializeBackupJob } from '../../../../utils/backup/api'
+import {
+  getActiveBackupJob,
+  getRunningBackupJob,
+  listBackupJobsPage,
+  recoverInterruptedBackupJobs
+} from '../../../../utils/backup/jobs'
+import { isBackupRunnerBusy } from '../../../../utils/backup/runner'
+
+export default defineEventHandler(async (event) => {
+  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 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
+
+  const activeJob = getActiveBackupJob()
+
+  return {
+    jobs: slice.map(serializeBackupJob),
+    total,
+    page,
+    pageSize,
+    totalPages,
+    activeJob: activeJob ? serializeBackupJob(activeJob) : null
+  }
+})

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

@@ -0,0 +1,108 @@
+import type { H3Event } from 'h3'
+import { requireAdminAuth } from '../../../utils/access'
+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 {
+  BACKUP_ARCHIVE_EXT,
+  getBackupsDir,
+  getBackupStagingDir,
+  isSafeBackupFilename
+} from '../../../utils/backup/paths'
+import { join } from 'node:path'
+import { promises as fs } from 'node:fs'
+
+interface RestoreBody {
+  archiveName?: string
+  conflictMode?: 'skip' | 'overwrite'
+  dryRun?: boolean
+}
+
+async function resolveRestoreInput(event: H3Event): Promise<{
+  archivePath: string
+  body: RestoreBody
+  cleanup?: () => Promise<void>
+}> {
+  const contentType = getHeader(event, 'content-type') ?? ''
+
+  if (contentType.includes('multipart/form-data')) {
+    const form = await readMultipartFormData(event)
+    const filePart = form?.find(part => part.name === 'file' && part.data?.length)
+    if (!filePart?.data) {
+      createApiError(event, 'INVALID_REQUEST', '请上传备份文件', 400)
+    }
+
+    const conflictField = form?.find(part => part.name === 'conflictMode')?.data?.toString('utf8')
+    const dryRunField = form?.find(part => part.name === 'dryRun')?.data?.toString('utf8')
+    const dryRun = dryRunField === 'true'
+
+    if (dryRun) {
+      const tempDir = getBackupStagingDir(`upload-preview-${Date.now()}`)
+      await fs.mkdir(tempDir, { recursive: true })
+      const archivePath = join(tempDir, 'package.phost.tar.gz')
+      await fs.writeFile(archivePath, filePart.data)
+      return {
+        archivePath,
+        body: {
+          conflictMode: conflictField === 'skip' ? 'skip' : 'overwrite',
+          dryRun: true
+        },
+        cleanup: async () => {
+          await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {})
+        }
+      }
+    }
+
+    await fs.mkdir(getBackupsDir(), { recursive: true })
+    const safeName = `upload-${Date.now()}${BACKUP_ARCHIVE_EXT}`
+    const archivePath = join(getBackupsDir(), safeName)
+    await fs.writeFile(archivePath, filePart.data)
+    return {
+      archivePath,
+      body: {
+        conflictMode: conflictField === 'skip' ? 'skip' : 'overwrite',
+        dryRun: false
+      }
+    }
+  }
+
+  const body = await readBody<RestoreBody>(event)
+  if (!body?.archiveName || !isSafeBackupFilename(body.archiveName)) {
+    createApiError(event, 'INVALID_REQUEST', '请选择有效的备份文件', 400)
+  }
+  const archivePath = join(getBackupsDir(), body.archiveName)
+  try {
+    await fs.access(archivePath)
+  } catch {
+    createApiError(event, 'INVALID_REQUEST', '备份文件不存在', 400)
+  }
+  return { archivePath, body }
+}
+
+export default defineEventHandler(async (event) => {
+  await requireAdminAuth(event)
+
+  const { archivePath, body, cleanup } = await resolveRestoreInput(event)
+
+  const conflictMode = body.conflictMode === 'skip' ? 'skip' : 'overwrite'
+
+  if (body.dryRun) {
+    try {
+      const preview = await previewFullRestore(archivePath)
+      return { preview }
+    } finally {
+      await cleanup?.()
+    }
+  }
+
+  try {
+    const job = startFullRestoreJob(archivePath, conflictMode)
+    return { job: serializeBackupJob(job) }
+  } catch (error) {
+    if (error instanceof Error && error.message === 'BACKUP_JOB_RUNNING') {
+      createApiError(event, 'CONFLICT', '已有备份或迁移任务正在运行', 409)
+    }
+    throw error
+  }
+})

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

@@ -0,0 +1,50 @@
+import { requireAdminAuth } from '../../../utils/access'
+import { createApiError } from '../../../utils/api-error'
+import { serializeBackupJob } from '../../../utils/backup/api'
+import { previewBackendSync } from '../../../utils/backup/backend-sync'
+import { startBackendSyncJob } from '../../../utils/backup/runner'
+
+interface SyncBody {
+  fromBackendId?: string
+  toBackendId?: string
+  deleteSource?: boolean
+  setDefault?: boolean
+  dryRun?: boolean
+}
+
+export default defineEventHandler(async (event) => {
+  await requireAdminAuth(event)
+  const body = await readBody<SyncBody>(event)
+
+  const fromBackendId = body?.fromBackendId?.trim() ?? ''
+  const toBackendId = body?.toBackendId?.trim() ?? ''
+  if (!fromBackendId || !toBackendId) {
+    createApiError(event, 'INVALID_REQUEST', '请选择源与目标存储后端', 400)
+  }
+
+  const options = {
+    fromBackendId,
+    toBackendId,
+    deleteSource: Boolean(body?.deleteSource),
+    setDefault: Boolean(body?.setDefault),
+    dryRun: Boolean(body?.dryRun)
+  }
+
+  try {
+    if (options.dryRun) {
+      const preview = previewBackendSync(options)
+      return { preview }
+    }
+
+    const job = startBackendSyncJob(options)
+    return { job: serializeBackupJob(job) }
+  } catch (error) {
+    if (error instanceof Error) {
+      if (error.message === 'BACKUP_JOB_RUNNING') {
+        createApiError(event, 'CONFLICT', '已有备份或迁移任务正在运行', 409)
+      }
+      createApiError(event, 'INVALID_REQUEST', error.message, 400)
+    }
+    throw error
+  }
+})