diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a6e9211..fc9a32b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -34,6 +34,11 @@ jobs: cache: npm cache-dependency-path: ${{ matrix.package }}/package-lock.json - run: npm ci + # miniProgram imports shared components from web/app. TypeScript resolves + # their dependencies from web, not from miniProgram/node_modules. + - name: Install shared web component dependencies + if: matrix.package == 'miniProgram' + run: npm ci --prefix ../web - if: matrix.package == 'server' run: npm run prisma:generate - run: npm run lint --if-present diff --git a/deploy/.env.example b/deploy/.env.example index 5a4dc3e..1aadb80 100644 --- a/deploy/.env.example +++ b/deploy/.env.example @@ -2,6 +2,11 @@ POSTGRES_PASSWORD=replace-me REDIS_PASSWORD=replace-with-a-long-url-safe-random-secret BIND_PORT=18081 PUBLIC_API_URL=https://store.example.com +# r2 keeps the current direct-upload/read path; dual writes a verified local +# copy while retaining R2 as the remote copy. Switch only after migration. +UPLOAD_STORAGE=r2 +LOCAL_UPLOAD_DIR=/app/uploads +R2_BACKUP_ENABLED=false TRUST_PROXY_HOPS=1 TRUSTED_PROXY_CIDRS= PUBLIC_CATALOG_CACHE_ENABLED=true diff --git "a/docs/\346\234\254\345\234\260\344\274\230\345\205\210\344\270\216R2\345\217\214\345\206\231\345\244\207\344\273\275\345\256\236\346\226\275\346\226\271\346\241\210-2026-09-18.md" "b/docs/\346\234\254\345\234\260\344\274\230\345\205\210\344\270\216R2\345\217\214\345\206\231\345\244\207\344\273\275\345\256\236\346\226\275\346\226\271\346\241\210-2026-09-18.md" new file mode 100644 index 0000000..49d69e0 --- /dev/null +++ "b/docs/\346\234\254\345\234\260\344\274\230\345\205\210\344\270\216R2\345\217\214\345\206\231\345\244\207\344\273\275\345\256\236\346\226\275\346\226\271\346\241\210-2026-09-18.md" @@ -0,0 +1,202 @@ +# 本地优先与 R2 双写备份实施方案 + +更新时间:2026-09-18 +适用入口:`www.biterstore.top` 校园内网 H5、微信端及现有 `store.young581.com` 入口 + +## 1. 目标 + +将商品图片调整为“服务器本地存储为主、Cloudflare R2 为异地备份”: + +- 正常读取只访问本地 `api-uploads` 卷,校园网访问不依赖 R2 链路。 +- 每个已完成图片同时保留本地副本和 R2 副本。 +- R2 继续使用现有 `young581.com` 对应账号、Bucket 和对象,不迁移 Bucket。 +- 图片仍统一经过 `/api/v1/media/:id`,前端不获得本地文件路径或 R2 私有地址。 +- R2 暂时不可用时,本地上传可以完成,后台任务稍后补传 R2。 +- 本地文件丢失时可以从 R2 回源并修复本地副本。 + +## 2. 当前实现与限制 + +当前 `UPLOAD_STORAGE` 是二选一模式: + +- `r2`:浏览器通过预签名 URL 直传 R2,媒体接口从 R2 读取。 +- `local`:服务端接收上传内容并写入本地卷,媒体接口从本地读取。 + +生产现在使用 R2。直接改成 `local` 会让数据库中已有的 R2 对象在本地找不到,因此必须先完成对象迁移和双存储代码,再切换读取路径。 + +当前图片元数据保存在 `ListingImage`,核心关联是 `objectKey`、`size`、`mime`、`uploadedAt` 和 `listingId`。对象键同时作为本地路径和 R2 Key 使用,方案继续沿用这一约定。 + +## 3. 推荐架构 + +新增存储模式: + +```text +UPLOAD_STORAGE=dual +LOCAL_UPLOAD_DIR=/app/uploads +R2_BACKUP_ENABLED=true +``` + +上传流程: + +```text +客户端申请上传 + ↓ +本地临时文件或现有 R2 pending 对象 + ↓ +服务端读取并校验字节、格式、大小和图片尺寸 + ↓ +写入本地最终对象 media//. + ↓ +数据库提交完成状态 + ↓ +备份任务写入 R2 并记录校验结果 +``` + +读取流程: + +```text +/api/v1/media/:id + ↓ +优先读取本地 media//. + ↓ 本地缺失 +从 R2 读取同一个 objectKey,校验后修复本地副本 +``` + +R2 只作为备份和故障回源,不向客户端暴露 R2 URL。 + +## 4. 分阶段实施 + +### 阶段 A:增加状态和配置 + +为 `ListingImage` 增加备份字段,或建立独立的 `MediaBackup` 表。推荐独立表,避免改变现有图片状态机: + +```text +listingImageId 唯一关联图片 +objectKey R2/本地对象键 +status PENDING / BACKED_UP / FAILED +attempts 重试次数 +lastError 脱敏错误摘要 +lastAttemptAt 最近尝试时间 +verifiedBytes 已验证字节数 +verifiedSha256 已验证摘要 +backedUpAt R2 成功时间 +``` + +增加配置校验: + +- `UPLOAD_STORAGE=dual` 时必须配置本地目录。 +- 启用 R2 备份时必须配置 R2 Endpoint、Bucket 和凭据。 +- 禁止把 R2 Secret、备份口令或本地生产路径提交到 Git。 + +### 阶段 B:先实现双写,不改变读取入口 + +第一版尽量复用现有 R2 直传流程,降低前端改动: + +1. 客户端继续获得 R2 `pending/` 预签名地址。 +2. `complete` 从 R2 读取并校验完整字节。 +3. 将同一份已校验字节写入本地最终路径。 +4. 将同一份已校验字节写入 R2 最终路径。 +5. 数据库只在本地写入成功、R2 最终对象成功或备份任务已可靠入队后提交完成状态。 + +这一阶段可以验证本地磁盘容量、权限、性能和对象一致性,仍然由 R2 提供现有回退能力。 + +### 阶段 C:本地读取与 R2 异步备份 + +确认双写稳定后: + +- `media.controller.ts` 默认从本地读取。 +- R2 备份改为队列任务,使用指数退避重试,例如 1 分钟、5 分钟、30 分钟、2 小时。 +- 图片完成接口只等待本地最终文件落盘,不因短暂 R2 故障阻塞校园用户。 +- 备份任务使用 SHA-256、字节数和 MIME 校验,避免只检查对象存在。 +- 任务达到最大重试次数后进入告警状态,不自动删除本地副本。 + +### 阶段 D:现有对象迁移 + +切换前执行一次只读盘点: + +- 数据库中 `uploadedAt` 非空的图片数量。 +- R2 `media/` 对象数量、总字节数和缺失对象列表。 +- 本地卷已有对象数量和冲突列表。 + +迁移程序按 `ListingImage.objectKey` 从 R2 下载到临时文件,完成以下检查后原子移动到本地最终路径: + +- 文件大小等于数据库 `size`。 +- MIME 和图片结构校验通过。 +- SHA-256 与迁移记录一致。 +- 目标文件已存在且校验一致时跳过,不覆盖不一致文件。 + +迁移完成后再次对比数据库、R2 和本地清单。没有完成清单校验前,不切换生产读取模式。 + +### 阶段 E:故障回源和修复 + +当本地文件不存在、损坏或读取失败时: + +1. 记录一次受限告警,避免重复刷日志。 +2. 从 R2 读取并校验对象。 +3. 写入本地临时文件并原子改名。 +4. 返回图片内容。 + +R2 也不可用时返回标准 404/503,不泄露对象键、Bucket 或内部路径。 + +## 5. 删除、取消和生命周期 + +- 取消 pending 上传时同时清理本地 pending 文件和 R2 `pending/` 对象。 +- 删除已完成图片时先记录删除任务,再分别删除本地和 R2 对象。 +- 任一存储删除失败时保留任务记录并重试,不能因为本地删除成功就丢失 R2 删除状态。 +- R2 `pending/` 生命周期继续保留 1 天,作为备份任务异常时的兜底清理。 +- 不对 `media/` 设置短生命周期,避免误删已发布图片。 + +## 6. 备份与恢复 + +本地图片卷和 PostgreSQL 必须属于同一备份批次: + +- PostgreSQL 备份保存 `ListingImage` 元数据和对象键。 +- 本地 `api-uploads` 卷按对象键归档或做快照。 +- R2 作为异地图片副本,不替代数据库备份。 +- 恢复顺序:数据库 → 本地图片卷 → R2 差异补齐 → 媒体清单校验。 + +至少完成两类演练: + +1. 本地卷损坏:从 R2 恢复指定图片并验证页面访问。 +2. R2 暂时不可用:本地上传、读取和审核流程仍可用,备份任务恢复后补齐对象。 + +## 7. 监控指标 + +增加以下指标和告警: + +- 本地对象缺失数量。 +- R2 备份待处理数量。 +- R2 备份失败数量和最长等待时间。 +- 本地卷使用率和 inode 使用率。 +- 回源次数、回源失败次数。 +- 本地与 R2 校验不一致数量。 + +建议磁盘使用率达到 70% 提醒、80% 告警、90% 阻止新上传并提示运维处理。 + +## 8. 回滚方案 + +如果本地读取或双写出现问题: + +1. 停止备份任务写入,不删除本地和 R2 对象。 +2. 将媒体读取切回 R2。 +3. 保留本地卷和备份状态,继续排查失败对象。 +4. 不回滚数据库中已经完成的图片元数据,避免对象键重新变化。 + +只有在 R2 清单和数据库清单完整一致时,才允许清理迁移临时文件。 + +## 9. 验收标准 + +切换前必须全部通过: + +- 历史图片迁移数量、字节数和 SHA-256 校验一致。 +- 新上传图片本地读取成功,R2 备份最终变为 `BACKED_UP`。 +- R2 暂时不可用时,本地上传和本地读取不受影响,任务进入重试队列。 +- 删除、取消上传和重复完成请求保持幂等。 +- 本地文件删除后,下一次读取可以从 R2 回源并修复。 +- H5 和微信端图片 URL 仍使用当前域名 API,不出现 R2 或服务器本地路径。 +- `www.biterstore.top` 与 `store.young581.com` 的媒体访问、登录 Cookie 和权限边界不互相污染。 +- 生产备份可以恢复数据库和至少一组真实对象到隔离目录。 +- 迁移期间不改变现有 R2 Bucket、对象键和 R2 账号。 + +## 10. 暂不执行的操作 + +本方案只定义实施路径,当前不直接切换生产 `UPLOAD_STORAGE`,不删除 R2 对象,也不执行历史对象迁移。正式实施前需要先确认本地磁盘容量、备份窗口、R2 凭据权限和可接受的上传中断时间。 diff --git a/server/package.json b/server/package.json index ba38d4e..0174ecf 100644 --- a/server/package.json +++ b/server/package.json @@ -14,6 +14,8 @@ "prisma:deploy": "prisma migrate deploy", "seed": "tsx prisma/seed.ts", "r2:migrate-completed": "node dist/src/maintenance/migrate-completed-uploads.js", + "storage:migrate-r2-to-local": "node dist/src/maintenance/migrate-r2-to-local.js", + "storage:retry-r2-backups": "node dist/src/maintenance/retry-r2-backups.js", "r2:configure-lifecycle": "node dist/src/maintenance/configure-r2-lifecycle.js", "uploads:cleanup-pending": "node dist/src/maintenance/cleanup-pending-uploads.js", "accounts:cleanup-recovery": "node dist/src/maintenance/cleanup-account-recovery-links.js", diff --git a/server/prisma/migrations/202609180003_dual_image_storage/migration.sql b/server/prisma/migrations/202609180003_dual_image_storage/migration.sql new file mode 100644 index 0000000..53abab9 --- /dev/null +++ b/server/prisma/migrations/202609180003_dual_image_storage/migration.sql @@ -0,0 +1,7 @@ +ALTER TABLE "ListingImage" + ADD COLUMN "localStoredAt" TIMESTAMP(3), + ADD COLUMN "remoteStoredAt" TIMESTAMP(3), + ADD COLUMN "backupAttempts" INTEGER NOT NULL DEFAULT 0, + ADD COLUMN "backupError" TEXT; + +CREATE INDEX "ListingImage_remoteStoredAt_idx" ON "ListingImage"("remoteStoredAt"); diff --git a/server/prisma/schema.prisma b/server/prisma/schema.prisma index 3892e20..e12f487 100644 --- a/server/prisma/schema.prisma +++ b/server/prisma/schema.prisma @@ -200,10 +200,15 @@ model ListingImage { moderationReason String? moderatedAt DateTime? uploadedAt DateTime? + localStoredAt DateTime? + remoteStoredAt DateTime? + backupAttempts Int @default(0) + backupError String? createdAt DateTime @default(now()) listing Listing? @relation(fields: [listingId], references: [id], onDelete: Cascade) @@index([ownerId, uploadedAt]) + @@index([remoteStoredAt]) @@index([listingId, moderationStatus, sortOrder]) } diff --git a/server/src/health.controller.ts b/server/src/health.controller.ts index 9c70bf3..da66c2b 100644 --- a/server/src/health.controller.ts +++ b/server/src/health.controller.ts @@ -70,12 +70,14 @@ export class HealthController { } private async checkStorage(timeout: number): Promise { - if (process.env.UPLOAD_STORAGE !== 'r2') { + const storage = process.env.UPLOAD_STORAGE || 'local' + if (storage === 'local' || storage === 'dual') { await this.withTimeout(access(resolve(process.env.LOCAL_UPLOAD_DIR || 'uploads'), constants.R_OK | constants.W_OK), timeout) - return 'ok' } - if (!process.env.R2_ENDPOINT || !process.env.R2_BUCKET || !process.env.R2_ACCESS_KEY_ID || !process.env.R2_SECRET_ACCESS_KEY) throw new Error('R2 configuration incomplete') - await this.s3.send(new HeadBucketCommand({ Bucket: process.env.R2_BUCKET }), { abortSignal: AbortSignal.timeout(timeout) }) + if (storage === 'r2' || storage === 'dual') { + if (!process.env.R2_ENDPOINT || !process.env.R2_BUCKET || !process.env.R2_ACCESS_KEY_ID || !process.env.R2_SECRET_ACCESS_KEY) throw new Error('R2 configuration incomplete') + await this.s3.send(new HeadBucketCommand({ Bucket: process.env.R2_BUCKET }), { abortSignal: AbortSignal.timeout(timeout) }) + } return 'ok' } diff --git a/server/src/maintenance/cleanup-pending-uploads.ts b/server/src/maintenance/cleanup-pending-uploads.ts index eeaed37..98fd34e 100644 --- a/server/src/maintenance/cleanup-pending-uploads.ts +++ b/server/src/maintenance/cleanup-pending-uploads.ts @@ -102,7 +102,7 @@ export type PendingCleanupOptions = { } $transaction(callback: (tx: { listingImage: { deleteMany(args: unknown): Promise<{ count: number }> } }) => Promise): Promise } - storage?: 'local' | 'r2' + storage?: 'local' | 'r2' | 'dual' localRoot?: string s3?: S3Client bucket?: string @@ -130,10 +130,11 @@ export async function cleanupPendingUploads(options: PendingCleanupOptions) { const storage = options.storage || (process.env.UPLOAD_STORAGE === 'r2' ? 'r2' : 'local') const removeTrackedObject = async (objectKey: string) => { - if (storage === 'r2') { + if (storage === 'r2' || storage === 'dual') { if (!options.s3 || !options.bucket) throw new Error('R2 storage is not configured') await options.s3.send(new DeleteObjectCommand({ Bucket: options.bucket, Key: objectKey })) - } else { + } + if (storage === 'local' || storage === 'dual') { const target = safeLocalPath(options.localRoot || resolve(process.env.LOCAL_UPLOAD_DIR || 'uploads'), objectKey) await unlink(target).catch((cause: NodeJS.ErrnoException) => { if (cause.code !== 'ENOENT') throw cause }) } @@ -153,14 +154,15 @@ export async function cleanupPendingUploads(options: PendingCleanupOptions) { removedObjects += deleted } - if (storage === 'r2') { + if (storage === 'r2' || storage === 'dual') { if (!options.s3 || !options.bucket) throw new Error('R2 storage is not configured') const listed = await listPendingObjects(options.s3, options.bucket) // Missing LastModified is treated as stale because an untracked pending // object must not live forever. const keysToDelete = listed.filter((item) => !item.lastModified || item.lastModified <= cutoff).map((item) => item.key) removedObjects += await deleteR2Objects(options.s3, options.bucket, keysToDelete) - } else { + } + if (storage === 'local' || storage === 'dual') { removedObjects += await cleanupLocalPending(options.localRoot || resolve(process.env.LOCAL_UPLOAD_DIR || 'uploads'), cutoff) } @@ -176,8 +178,8 @@ export async function cleanupPendingUploads(options: PendingCleanupOptions) { async function main() { const prisma = new PrismaClient() - const storage = process.env.UPLOAD_STORAGE === 'r2' ? 'r2' : 'local' - const s3 = storage === 'r2' ? new S3Client({ + const storage = process.env.UPLOAD_STORAGE === 'r2' ? 'r2' : process.env.UPLOAD_STORAGE === 'dual' ? 'dual' : 'local' + const s3 = storage === 'r2' || storage === 'dual' ? new S3Client({ region: 'auto', endpoint: process.env.R2_ENDPOINT, credentials: { accessKeyId: process.env.R2_ACCESS_KEY_ID || '', secretAccessKey: process.env.R2_SECRET_ACCESS_KEY || '' } diff --git a/server/src/maintenance/migrate-r2-to-local.ts b/server/src/maintenance/migrate-r2-to-local.ts new file mode 100644 index 0000000..d0ec9d7 --- /dev/null +++ b/server/src/maintenance/migrate-r2-to-local.ts @@ -0,0 +1,82 @@ +import { GetObjectCommand, HeadObjectCommand, S3Client } from '@aws-sdk/client-s3' +import { PrismaClient } from '@prisma/client' +import { createHash } from 'node:crypto' +import { link, mkdir, readFile, unlink, writeFile } from 'node:fs/promises' +import { dirname, resolve, sep } from 'node:path' +import { inspectImage } from '../common/image-validation.js' + +const MAX_IMAGE_BYTES = 5 * 1024 * 1024 + +function localPath(root: string, objectKey: string) { + const base = resolve(root) + const target = resolve(base, objectKey) + if (!target.startsWith(`${base}${sep}`)) throw new Error(`invalid object key: ${objectKey}`) + return target +} + +async function readR2(s3: S3Client, bucket: string, key: string) { + const response = await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key })) + if (!response.Body) throw new Error(`empty R2 object: ${key}`) + const chunks: Buffer[] = [] + let size = 0 + for await (const chunk of response.Body as AsyncIterable) { + size += chunk.length + if (size > MAX_IMAGE_BYTES) throw new Error(`R2 object exceeds image limit: ${key}`) + chunks.push(Buffer.from(chunk)) + } + return Buffer.concat(chunks) +} + +async function main() { + const prisma = new PrismaClient() + const s3 = new S3Client({ + region: 'auto', + endpoint: process.env.R2_ENDPOINT, + credentials: { accessKeyId: process.env.R2_ACCESS_KEY_ID || '', secretAccessKey: process.env.R2_SECRET_ACCESS_KEY || '' } + }) + const bucket = process.env.R2_BUCKET + const root = resolve(process.env.LOCAL_UPLOAD_DIR || 'uploads') + if (!bucket || !process.env.R2_ENDPOINT || !process.env.R2_ACCESS_KEY_ID || !process.env.R2_SECRET_ACCESS_KEY) throw new Error('R2 configuration is incomplete') + let migrated = 0 + let skipped = 0 + try { + const rows = await prisma.listingImage.findMany({ where: { uploadedAt: { not: null }, objectKey: { startsWith: 'media/' } }, select: { id: true, objectKey: true, size: true, mime: true } }) + for (const row of rows) { + const target = localPath(root, row.objectKey) + await s3.send(new HeadObjectCommand({ Bucket: bucket, Key: row.objectKey })) + const bytes = await readR2(s3, bucket, row.objectKey) + if (bytes.length !== row.size) throw new Error(`size mismatch for ${row.objectKey}: ${bytes.length} != ${row.size}`) + inspectImage(bytes, row.mime) + const digest = createHash('sha256').update(bytes).digest('hex') + const existing = await readFile(target).catch((cause: NodeJS.ErrnoException) => { + if (cause.code === 'ENOENT') return null + throw cause + }) + if (existing) { + if (createHash('sha256').update(existing).digest('hex') !== digest) throw new Error(`local content conflict: ${row.id}`) + await prisma.listingImage.update({ where: { id: row.id }, data: { localStoredAt: new Date(), remoteStoredAt: new Date(), backupError: null } }) + skipped += 1 + console.log(JSON.stringify({ id: row.id, bytes: bytes.length, sha256: digest, status: 'verified-existing' })) + continue + } + const temporary = `${target}.migrate-${process.pid}-${digest.slice(0, 12)}` + await mkdir(dirname(target), { recursive: true }) + await writeFile(temporary, bytes, { flag: 'wx' }) + try { + // Publish only complete bytes and never replace an existing file. + await link(temporary, target) + } finally { await unlink(temporary) } + const persisted = await readFile(target) + if (createHash('sha256').update(persisted).digest('hex') !== digest) throw new Error(`local verification failed: ${row.id}`) + await prisma.listingImage.update({ where: { id: row.id }, data: { localStoredAt: new Date(), remoteStoredAt: new Date(), backupError: null } }) + migrated += 1 + console.log(JSON.stringify({ id: row.id, objectKey: row.objectKey, bytes: bytes.length, sha256: digest })) + } + console.log(JSON.stringify({ migrated, skipped, total: rows.length, localRoot: root })) + } finally { + await prisma.$disconnect() + s3.destroy() + } +} + +void main().catch((error) => { console.error(error); process.exitCode = 1 }) diff --git a/server/src/maintenance/retry-r2-backups.ts b/server/src/maintenance/retry-r2-backups.ts new file mode 100644 index 0000000..6ca6bce --- /dev/null +++ b/server/src/maintenance/retry-r2-backups.ts @@ -0,0 +1,37 @@ +import { PutObjectCommand, S3Client } from '@aws-sdk/client-s3' +import { PrismaClient } from '@prisma/client' +import { readFile, stat } from 'node:fs/promises' +import { resolve, sep } from 'node:path' + +function localPath(root: string, key: string) { + const base = resolve(root); const target = resolve(base, key) + if (!target.startsWith(`${base}${sep}`)) throw new Error(`invalid object key: ${key}`) + return target +} + +async function main() { + const prisma = new PrismaClient() + const bucket = process.env.R2_BUCKET + if (!bucket || !process.env.R2_ENDPOINT || !process.env.R2_ACCESS_KEY_ID || !process.env.R2_SECRET_ACCESS_KEY) throw new Error('R2 configuration is incomplete') + const s3 = new S3Client({ region: 'auto', endpoint: process.env.R2_ENDPOINT, credentials: { accessKeyId: process.env.R2_ACCESS_KEY_ID, secretAccessKey: process.env.R2_SECRET_ACCESS_KEY } }) + const root = process.env.LOCAL_UPLOAD_DIR || 'uploads' + let backedUp = 0, failed = 0 + try { + const rows = await prisma.listingImage.findMany({ where: { uploadedAt: { not: null }, localStoredAt: { not: null }, remoteStoredAt: null, objectKey: { startsWith: 'media/' } }, select: { id: true, objectKey: true, size: true, mime: true, backupAttempts: true } }) + for (const row of rows) { + try { + const path = localPath(root, row.objectKey); const details = await stat(path) + if (details.size !== row.size) throw new Error(`size mismatch: ${details.size} != ${row.size}`) + const bytes = await readFile(path) + await s3.send(new PutObjectCommand({ Bucket: bucket, Key: row.objectKey, Body: bytes, ContentType: row.mime, ContentLength: bytes.length })) + await prisma.listingImage.update({ where: { id: row.id }, data: { remoteStoredAt: new Date(), backupAttempts: { increment: 1 }, backupError: null } }) + backedUp++ + } catch (cause) { + failed++ + await prisma.listingImage.update({ where: { id: row.id }, data: { backupAttempts: { increment: 1 }, backupError: cause instanceof Error ? cause.message.slice(0, 500) : 'R2 backup failed' } }).catch(() => undefined) + } + } + console.log(JSON.stringify({ scanned: rows.length, backedUp, failed })) + } finally { await prisma.$disconnect(); s3.destroy() } +} +void main().catch((error) => { console.error(error); process.exitCode = 1 }) diff --git a/server/src/modules/uploads/media.controller.ts b/server/src/modules/uploads/media.controller.ts index c2a9378..9f11fb2 100644 --- a/server/src/modules/uploads/media.controller.ts +++ b/server/src/modules/uploads/media.controller.ts @@ -1,7 +1,7 @@ import { Controller, Get, Header, NotFoundException, Param, StreamableFile, UseGuards } from '@nestjs/common' import { GetObjectCommand, S3Client } from '@aws-sdk/client-s3' -import { readFile } from 'node:fs/promises' -import { resolve, sep } from 'node:path' +import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises' +import { dirname, resolve, sep } from 'node:path' import { AdminGuard, AuthGuard, CampusVerifiedGuard, CurrentUser, type AuthUser } from '../../common/auth.js' import { PrismaService } from '../../infra/prisma.service.js' import { PublicCatalogRateLimitGuard } from '../listings/public-catalog-rate-limit.guard.js' @@ -16,6 +16,10 @@ export class MediaController { constructor(private readonly prisma: PrismaService) {} + private storageMode() { return process.env.UPLOAD_STORAGE || 'local' } + private useR2() { return this.storageMode() === 'r2' || this.storageMode() === 'dual' } + private useLocal() { return this.storageMode() === 'local' || this.storageMode() === 'dual' } + @Get('owner/:id') @UseGuards(AuthGuard) @Header('Cache-Control', 'private, no-store') @@ -65,15 +69,35 @@ export class MediaController { private async stream(image: { objectKey: string; mime: string; size: number }) { try { - const bytes = process.env.UPLOAD_STORAGE === 'r2' - ? await this.readR2(image.objectKey) - : await readFile(this.localPath(image.objectKey)) + let bytes: Buffer + if (this.useLocal()) { + try { bytes = await readFile(this.localPath(image.objectKey)) } + catch (cause) { + if (!this.useR2()) throw cause + bytes = await this.readR2(image.objectKey) + await this.repairLocal(image.objectKey, bytes) + } + } else { + bytes = await this.readR2(image.objectKey) + } return new StreamableFile(bytes, { type: image.mime, length: image.size }) } catch { throw new NotFoundException('图片不存在') } } + private async repairLocal(objectKey: string, bytes: Buffer) { + const target = this.localPath(objectKey) + const temporary = `${target}.repair-${process.pid}-${Date.now()}` + try { + await mkdir(dirname(target), { recursive: true }) + await writeFile(temporary, bytes, { flag: 'wx' }) + await rename(temporary, target) + } catch { + await unlink(temporary).catch(() => undefined) + } + } + private async readR2(objectKey: string) { const response = await this.s3.send(new GetObjectCommand({ Bucket: process.env.R2_BUCKET, Key: objectKey })) if (!response.Body) throw new Error('empty R2 object') diff --git a/server/src/modules/uploads/uploads.controller.ts b/server/src/modules/uploads/uploads.controller.ts index 195df59..704b7bd 100644 --- a/server/src/modules/uploads/uploads.controller.ts +++ b/server/src/modules/uploads/uploads.controller.ts @@ -18,7 +18,9 @@ export class UploadsController { private activeImageValidations = 0 private readonly s3 = new S3Client({ region: 'auto', endpoint: process.env.R2_ENDPOINT, credentials: process.env.R2_ACCESS_KEY_ID ? { accessKeyId: process.env.R2_ACCESS_KEY_ID, secretAccessKey: process.env.R2_SECRET_ACCESS_KEY || '' } : undefined }) constructor(private readonly prisma: PrismaService, @Optional() private readonly redis?: RedisService) {} - private useR2() { return process.env.UPLOAD_STORAGE === 'r2' } + private storageMode() { return process.env.UPLOAD_STORAGE || 'local' } + private useR2() { return this.storageMode() === 'r2' || this.storageMode() === 'dual' } + private useLocal() { return this.storageMode() === 'local' || this.storageMode() === 'dual' } private normalizeMime(value: unknown): SupportedImageMime | undefined { const mime = typeof value === 'string' ? value.split(';', 1)[0]?.trim().toLowerCase() : '' return allowed.has(mime as SupportedImageMime) ? mime as SupportedImageMime : undefined @@ -53,19 +55,19 @@ export class UploadsController { } } const role = ['COVER', 'ISBN', 'GALLERY'].includes(body.role || '') ? body.role as 'COVER' | 'ISBN' | 'GALLERY' : 'GALLERY' - if (this.useR2() && (!process.env.R2_ENDPOINT || !process.env.R2_BUCKET)) throw new BadRequestException('R2 对象存储尚未配置') + if (this.storageMode() === 'r2' && (!process.env.R2_ENDPOINT || !process.env.R2_BUCKET)) throw new BadRequestException('R2 对象存储尚未配置') const extension = { 'image/jpeg': 'jpg', 'image/png': 'png', 'image/webp': 'webp' }[mime] const objectKey = `pending/${user.id}/${randomUUID()}.${extension}` const row = await this.prisma.listingImage.create({ data: { ownerId: user.id, objectKey, mime, size: body.size, role, sortOrder: role === 'COVER' ? 0 : role === 'ISBN' ? 1 : 2 } }) - const uploadUrl = this.useR2() + const uploadUrl = this.storageMode() === 'r2' ? await getSignedUrl(this.s3, new PutObjectCommand({ Bucket: process.env.R2_BUCKET, Key: objectKey, ContentType: mime, ContentLength: body.size }), { expiresIn: 600 }) : `${(process.env.PUBLIC_API_URL || `http://localhost:${process.env.PORT || 3100}`).replace(/\/$/, '')}/api/v1/uploads/${row.id}/content` - return { id: row.id, objectKey, uploadUrl, expiresIn: 600, authRequired: !this.useR2() } + return { id: row.id, objectKey, uploadUrl, expiresIn: 600, authRequired: this.storageMode() !== 'r2' } } @Put(':id/content') async putLocal(@CurrentUser() user: AuthUser, @Param('id') id: string, @Body() body: Buffer) { assertNotMuted(user) await this.enforceRate(user.id, 'content', Number(process.env.UPLOAD_CONTENT_PER_MINUTE || 60)) - if (this.useR2()) throw new BadRequestException('当前使用 R2,请通过预签名地址上传') + if (this.storageMode() === 'r2') throw new BadRequestException('当前使用 R2,请通过预签名地址上传') const row = await this.prisma.listingImage.findFirst({ where: { id, ownerId: user.id, uploadedAt: null } }) if (!row) throw new BadRequestException('上传记录不存在或已完成') if (!Buffer.isBuffer(body) || body.length !== row.size || body.length > MAX_IMAGE_BYTES) throw new BadRequestException('上传文件与申请大小不一致') @@ -93,7 +95,7 @@ export class UploadsController { let committed = false try { let bytes: Buffer - if (this.useR2()) { + if (this.storageMode() === 'r2') { const head = await this.s3.send(new HeadObjectCommand({ Bucket: process.env.R2_BUCKET, Key: row.objectKey })) if (head.ContentLength !== row.size || this.normalizeMime(head.ContentType) !== this.normalizeMime(row.mime)) throw new ImageValidationError('上传文件与申请信息不一致') bytes = await this.readR2(row.objectKey) @@ -104,16 +106,33 @@ export class UploadsController { } if (bytes.length !== row.size || bytes.length > MAX_IMAGE_BYTES) throw new ImageValidationError('上传文件与申请大小不一致') const metadata = await this.validateImage(bytes, row.mime) - if (this.useR2()) { - // Persist the exact inspected bytes, not a mutable presigned PUT key. - await this.s3.send(new PutObjectCommand({ Bucket: process.env.R2_BUCKET, Key: finalObjectKey, Body: bytes, ContentType: metadata.mime, ContentLength: bytes.length })) - } else { + if (this.useLocal()) { await mkdir(dirname(this.localPath(finalObjectKey)), { recursive: true }) await writeFile(this.localPath(finalObjectKey), bytes, { flag: 'wx' }) } + let remoteStoredAt: Date | null = null + let backupAttempts = 0 + // Dual backups are durable work represented by remoteStoredAt=null. + // The maintenance worker must finish them outside the HTTP request. + if (this.storageMode() === 'r2') { + backupAttempts = 1 + await this.s3.send(new PutObjectCommand({ Bucket: process.env.R2_BUCKET, Key: finalObjectKey, Body: bytes, ContentType: metadata.mime, ContentLength: bytes.length })) + remoteStoredAt = new Date() + } const result = await this.prisma.listingImage.updateMany({ where: { id, ownerId: user.id, uploadedAt: null, objectKey: row.objectKey }, - data: { objectKey: finalObjectKey, uploadedAt: new Date(), width: metadata.width, height: metadata.height, mime: metadata.mime, size: bytes.length } + data: { + objectKey: finalObjectKey, + uploadedAt: new Date(), + localStoredAt: this.useLocal() ? new Date() : null, + remoteStoredAt, + backupAttempts, + backupError: null, + width: metadata.width, + height: metadata.height, + mime: metadata.mime, + size: bytes.length + } }) committed = result.count === 1 if (!committed) { @@ -123,7 +142,11 @@ export class UploadsController { throw new ConflictException('上传已取消,请重新上传') } // Pending cleanup is best-effort; failure cannot undo a committed upload. - await this.removeObject(row.objectKey).catch(() => undefined) + if (this.storageMode() === 'dual') { + await unlink(this.localPath(row.objectKey)).catch(() => undefined) + } else { + await this.removeObject(row.objectKey).catch(() => undefined) + } const completed = await findOwned() if (!completed) throw new ConflictException('上传已取消,请重新上传') return completed @@ -222,11 +245,16 @@ export class UploadsController { } private async removeObject(objectKey: string) { + let firstError: unknown if (this.useR2()) { - await this.s3.send(new DeleteObjectCommand({ Bucket: process.env.R2_BUCKET, Key: objectKey })) - return + try { await this.s3.send(new DeleteObjectCommand({ Bucket: process.env.R2_BUCKET, Key: objectKey })) } + catch (cause) { firstError = firstError || cause } + } + if (this.useLocal()) { + try { await unlink(this.localPath(objectKey)).catch((cause: NodeJS.ErrnoException) => { if (cause.code !== 'ENOENT') throw cause }) } + catch (cause) { firstError = firstError || cause } } - await unlink(this.localPath(objectKey)).catch((cause: NodeJS.ErrnoException) => { if (cause.code !== 'ENOENT') throw cause }) + if (firstError) throw firstError } private positiveLimit(raw: string | undefined, fallback: number) { diff --git a/server/test/uploads-complete.test.ts b/server/test/uploads-complete.test.ts index 1854065..fafa237 100644 --- a/server/test/uploads-complete.test.ts +++ b/server/test/uploads-complete.test.ts @@ -32,13 +32,13 @@ describe('upload completion', () => { await expect(new UploadsController({} as never, redis as never).presign({ id: 'owner-id' } as never, { mime: 'image/png', size: 100 })).rejects.toMatchObject({ status: 429 }) }) - it('moves a verified upload out of pending before marking it complete', async () => { + it.each(['local', 'dual'])('completes a %s upload without contacting R2', async (storage) => { const root = await mkdtemp(join(tmpdir(), 'biterstore-upload-')) const bytes = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=', 'base64') const row = { id: 'image-id', ownerId: 'owner-id', objectKey: 'pending/owner-id/source.png', mime: 'image/png', size: bytes.length } await mkdir(join(root, 'pending/owner-id'), { recursive: true }) await writeFile(join(root, row.objectKey), bytes) - process.env.UPLOAD_STORAGE = 'local' + process.env.UPLOAD_STORAGE = storage process.env.LOCAL_UPLOAD_DIR = root let stored = { ...row, uploadedAt: null as Date | null } const prisma = { @@ -48,7 +48,13 @@ describe('upload completion', () => { } } try { - const result = await new UploadsController(prisma as never).complete({ id: 'owner-id' } as never, row.id) + const controller = new UploadsController(prisma as never) + const send = vi.spyOn((controller as any).s3, 'send').mockRejectedValue(new Error('R2 offline')) + const result = await controller.complete({ id: 'owner-id' } as never, row.id) + if (storage === 'dual') { + expect(send).not.toHaveBeenCalled() + expect(result).toMatchObject({ remoteStoredAt: null, backupAttempts: 0, backupError: null, localStoredAt: expect.any(Date) }) + } else expect(send).not.toHaveBeenCalled() expect(result.objectKey).toMatch(/^media\/owner-id\/image-id-[\w-]+\.png$/) expect(prisma.listingImage.updateMany).toHaveBeenCalledWith(expect.objectContaining({ data: expect.objectContaining({ width: 1, height: 1, mime: 'image/png' }) })) expect(await readFile(join(root, result.objectKey))).toEqual(bytes)