fix(file): orphan cleanup idempotency; remove orphan cleanup cron

Innei · Innei · commit 2b4e946a49b4 · 2026-03-22T21:18:42.000+08:00
- Stop scheduling cleanupOrphanImages in CronTaskScheduler; drop cron type
  and CronBusinessService wrapper for orphan images.
- When deleting local orphan files, treat ENOENT as already removed so DB
  records are cleared and missing-file API errors are avoided.
- Add unit test for ENOENT path in cleanupOrphanFiles.

Made-with: Cursor
diff --git a/apps/core/src/modules/cron-task/cron-business.service.ts b/apps/core/src/modules/cron-task/cron-business.service.ts
@@ -9,7 +9,6 @@ import { STATIC_FILE_TRASH_DIR, TEMP_DIR } from '~/constants/path.constant'
 import { AggregateService } from '~/modules/aggregate/aggregate.service'
 import { AnalyzeModel } from '~/modules/analyze/analyze.model'
 import { ConfigsService } from '~/modules/configs/configs.service'
-import { FileReferenceService } from '~/modules/file/file-reference.service'
 import { SearchService } from '~/modules/search/search.service'
 import { HttpService } from '~/processors/helper/helper.http.service'
 import type { StoreJWTPayload } from '~/processors/helper/helper.jwt.service'
@@ -33,7 +32,6 @@ export class CronBusinessService {
     @InjectModel(AnalyzeModel)
     private readonly analyzeModel: MongooseModel<AnalyzeModel>,
     private readonly redisService: RedisService,
-    private readonly fileReferenceService: FileReferenceService,
 
     @Inject(forwardRef(() => AggregateService))
     private readonly aggregateService: AggregateService,
@@ -225,19 +223,6 @@ export class CronBusinessService {
     return { deletedCount: deleteCount }
   }
 
-  /**
-   * 清理孤儿图片
-   */
-  async cleanupOrphanImages() {
-    this.logger.log('--> 开始清理孤儿图片')
-    const { deletedCount, totalOrphan } =
-      await this.fileReferenceService.cleanupOrphanFiles(60)
-    this.logger.log(
-      `--> 清理孤儿图片完成：删除了 ${deletedCount}/${totalOrphan} 个文件`,
-    )
-    return { deletedCount, totalOrphan }
-  }
-
   /**
    * 重建搜索索引
    */
diff --git a/apps/core/src/modules/cron-task/cron-task.scheduler.ts b/apps/core/src/modules/cron-task/cron-task.scheduler.ts
@@ -93,17 +93,6 @@ export class CronTaskScheduler {
     )
   }
 
-  @CronOnce(CronExpression.EVERY_HOUR, { name: 'cleanupOrphanImages' })
-  async scheduleCleanupOrphanImages() {
-    this.logger.log('Scheduling cleanupOrphanImages task')
-    const result = await this.cronTaskService.createCronTask(
-      CronTaskType.CleanupOrphanImages,
-    )
-    this.logger.log(
-      `cleanupOrphanImages task ${result.created ? 'created' : 'already exists'}: ${result.taskId}`,
-    )
-  }
-
   @CronOnce(CronExpression.EVERY_DAY_AT_4AM, { name: 'rebuildSearchIndex' })
   async scheduleRebuildSearchIndex() {
     this.logger.log('Scheduling rebuildSearchIndex task')
diff --git a/apps/core/src/modules/cron-task/cron-task.types.ts b/apps/core/src/modules/cron-task/cron-task.types.ts
@@ -6,7 +6,6 @@ export const CronTaskType = {
   PushToBaiduSearch: 'cron:push-to-baidu-search',
   PushToBingSearch: 'cron:push-to-bing-search',
   DeleteExpiredJWT: 'cron:delete-expired-jwt',
-  CleanupOrphanImages: 'cron:cleanup-orphan-images',
   RebuildSearchIndex: 'cron:rebuild-search-index',
 } as const
 
@@ -66,12 +65,6 @@ export const CronTaskMetas: Record<
     cronExpression: 'EVERY_DAY_AT_1AM',
     methodName: 'deleteExpiredJWT',
   },
-  [CronTaskType.CleanupOrphanImages]: {
-    name: 'cleanupOrphanImages',
-    description: '清理孤儿图片',
-    cronExpression: 'EVERY_HOUR',
-    methodName: 'cleanupOrphanImages',
-  },
   [CronTaskType.RebuildSearchIndex]: {
     name: 'rebuildSearchIndex',
     description: '重建搜索索引',
diff --git a/apps/core/src/modules/file/file-reference.service.ts b/apps/core/src/modules/file/file-reference.service.ts
@@ -26,6 +26,30 @@ interface ContentLike {
 export class FileReferenceService {
   private readonly logger = new Logger(FileReferenceService.name)
 
+  private isEnoent(err: unknown): boolean {
+    return (
+      typeof err === 'object' &&
+      err !== null &&
+      'code' in err &&
+      (err as NodeJS.ErrnoException).code === 'ENOENT'
+    )
+  }
+
+  /**
+   * 删除本地孤儿图片文件。若磁盘上已不存在（ENOENT），视为已清理成功，避免 DB 残留导致接口仍引用缺失文件。
+   */
+  private async unlinkLocalOrphanImage(fileName: string): Promise<void> {
+    const localPath = path.join(STATIC_FILE_DIR, 'image', fileName)
+    try {
+      await unlink(localPath)
+    } catch (err) {
+      if (this.isEnoent(err)) {
+        return
+      }
+      throw err
+    }
+  }
+
   constructor(
     @InjectModel(FileReferenceModel)
     private readonly fileReferenceModel: MongooseModel<FileReferenceModel>,
@@ -131,8 +155,7 @@ export class FileReferenceService {
           }
           await s3Uploader.deleteObject(file.s3ObjectKey)
         } else if (file.fileUrl.includes('/objects/image/')) {
-          const localPath = path.join(STATIC_FILE_DIR, 'image', file.fileName)
-          await unlink(localPath)
+          await this.unlinkLocalOrphanImage(file.fileName)
         } else {
           continue
         }
@@ -175,8 +198,7 @@ export class FileReferenceService {
         return true
       }
       if (file.fileUrl.includes('/objects/image/')) {
-        const localPath = path.join(STATIC_FILE_DIR, 'image', file.fileName)
-        await unlink(localPath)
+        await this.unlinkLocalOrphanImage(file.fileName)
         return true
       }
       return false
diff --git a/apps/core/test/src/modules/file/file-reference.service.spec.ts b/apps/core/test/src/modules/file/file-reference.service.spec.ts
@@ -1,3 +1,5 @@
+import { unlink } from 'node:fs/promises'
+
 import { Test } from '@nestjs/testing'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
@@ -10,6 +12,11 @@ import {
 import { FileReferenceService } from '~/modules/file/file-reference.service'
 import { getModelToken } from '~/transformers/model.transformer'
 
+vi.mock('node:fs/promises', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:fs/promises')>()
+  return { ...actual, unlink: vi.fn(actual.unlink) }
+})
+
 describe('FileReferenceService', () => {
   let fileReferenceService: FileReferenceService
   let mockReferences: any[]
@@ -140,6 +147,40 @@ describe('FileReferenceService', () => {
     mockReferences = []
   })
 
+  describe('cleanupOrphanFiles', () => {
+    beforeEach(() => {
+      vi.mocked(unlink).mockReset()
+      vi.mocked(unlink).mockResolvedValue(undefined)
+    })
+
+    it('should delete DB record when local file is already missing (ENOENT)', async () => {
+      const orphan = {
+        _id: 'ref_orphan',
+        fileUrl: 'http://example.com/objects/image/gone.png',
+        fileName: 'gone.png',
+        status: FileReferenceStatus.Pending,
+        created: new Date(Date.now() - 120 * 60 * 1000),
+      }
+      mockReferences.push(orphan)
+
+      const model = fileReferenceService['fileReferenceModel'] as {
+        find: ReturnType<typeof vi.fn>
+        deleteOne: ReturnType<typeof vi.fn>
+      }
+      vi.spyOn(model, 'find').mockResolvedValue([orphan] as never)
+      const deleteOneSpy = vi.spyOn(model, 'deleteOne')
+
+      vi.mocked(unlink).mockRejectedValueOnce(
+        Object.assign(new Error('ENOENT'), { code: 'ENOENT' }),
+      )
+
+      const result = await fileReferenceService.cleanupOrphanFiles(60)
+
+      expect(deleteOneSpy).toHaveBeenCalledWith({ _id: 'ref_orphan' })
+      expect(result.deletedCount).toBe(1)
+    })
+  })
+
   describe('createPendingReference', () => {
     it('should create a pending reference for a new file', async () => {
       const fileUrl = 'http://example.com/objects/image/test.jpg'
