Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 5 additions & 0 deletions deploy/.env.example
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
202 changes: 202 additions & 0 deletions docs/本地优先与R2双写备份实施方案-2026-09-18.md
Original file line number Diff line number Diff line change
@@ -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/<owner>/<image>.<ext>
↓
数据库提交完成状态
↓
备份任务写入 R2 并记录校验结果
```

读取流程:

```text
/api/v1/media/:id
↓
优先读取本地 media/<owner>/<image>.<ext>
↓ 本地缺失
从 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 凭据权限和可接受的上传中断时间。
2 changes: 2 additions & 0 deletions server/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
Original file line number Diff line number Diff line change
@@ -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");
5 changes: 5 additions & 0 deletions server/prisma/schema.prisma
Original file line number Diff line number Diff line change
Expand Up @@ -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])
}

Expand Down
10 changes: 6 additions & 4 deletions server/src/health.controller.ts
Original file line number Diff line number Diff line change
Expand Up @@ -70,12 +70,14 @@ export class HealthController {
}

private async checkStorage(timeout: number): Promise<CheckStatus> {
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'
}

Expand Down
16 changes: 9 additions & 7 deletions server/src/maintenance/cleanup-pending-uploads.ts
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ export type PendingCleanupOptions = {
}
$transaction<T>(callback: (tx: { listingImage: { deleteMany(args: unknown): Promise<{ count: number }> } }) => Promise<T>): Promise<T>
}
storage?: 'local' | 'r2'
storage?: 'local' | 'r2' | 'dual'
localRoot?: string
s3?: S3Client
bucket?: string
Expand Down Expand Up @@ -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 })
}
Expand All @@ -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)
}

Expand All @@ -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 || '' }
Expand Down
Loading
Loading