fix(可观测): 让"续跑/兜底拉取没开"在日志里可辨识,并纠正与 yml 相反的默认值

V129 客户端中断自动续跑从上线至今一次都没执行过:aiimage.task-resume.enabled
继承 aiimage.client-task-pull.enabled,两台生产两个键都没设 → false →
resumeInterruptedTasks() 第一行 return。7 天 12 个「客户端异常中断」任务、
48 轮巡检 resume(s=0 r=0 k=0 u=0)、pull-pending 1 小时 4443 次空返回,
在日志上与"恰好没有中断任务"完全同形。

不改开关(属产品语义:兜底拉取会把用户只解析没点启动的 PENDING 真跑,
而外观专利占 LLM 花费 95% 且扣用户自付次数),已写进决策文档 §十三 交人工决定。
本版只做三件事:
- ResumeStats.ran:真查过库才算跑过;巡检段位改 resume(ran= s= r= k= u=)
- TaskResumeService / TaskClientPullService 各加 @PostConstruct 生效配置启动行
- @Value 的 enabled 默认由 :true 改为继承 client-task-pull.enabled:false(与 yml 同语义)

测试:TaskResumeServiceTest +4、TaskClientPullServiceTest +1,全量 3271 通过 / 0 失败。
This commit is contained in:
2026-09-28 16:52:33 +08:00
parent 35f0debb69
commit 575b7f9f8c
6 changed files with 247 additions and 4 deletions
@@ -133,7 +133,7 @@ public class DeleteBrandStaleTaskService {
// 周期每 2 分钟一轮,各模块 summary 合并为单行,避免定期刷屏
// 注意:每段占位符数量必须与实参一致——此前每段 5 个占位符只传 4 个参数,
// 导致 withdraw 之后的取值整体错位、末尾 elapsedMs/thread 打成字面量
log.info("[stale-check] summary product-risk(s={} f={} x={} p={}) price-track(s={} f={} x={} p={}) price-track-loop(s={} f={} p={} r={} x={}) shop-match(s={} f={} x={} p={}) patrol-delete(s={} f={} x={} p={}) query-asin(s={} f={} x={} p={}) withdraw(s={} f={} x={} p={}) no-upload(c={} f={} x={}) resume(s={} r={} k={} u={}) elapsedMs={} thread={}",
log.info("[stale-check] summary product-risk(s={} f={} x={} p={}) price-track(s={} f={} x={} p={}) price-track-loop(s={} f={} p={} r={} x={}) shop-match(s={} f={} x={} p={}) patrol-delete(s={} f={} x={} p={}) query-asin(s={} f={} x={} p={}) withdraw(s={} f={} x={} p={}) no-upload(c={} f={} x={}) resume(ran={} s={} r={} k={} u={}) elapsedMs={} thread={}",
stats.scannedTaskCount, stats.finalizedTaskCount, stats.failedTaskCount, stats.skippedTaskCount,
priceTrackStats.scannedTaskCount, priceTrackStats.finalizedTaskCount, priceTrackStats.failedTaskCount, priceTrackStats.skippedTaskCount,
priceTrackLoopStats.scannedLoopRunCount, priceTrackLoopStats.failedLoopRunCount, priceTrackLoopStats.stoppedLoopRunCount, priceTrackLoopStats.finalizedLoopRunCount, priceTrackLoopStats.skippedLoopRunCount,
@@ -142,8 +142,10 @@ public class DeleteBrandStaleTaskService {
queryAsinStats.scannedTaskCount, queryAsinStats.finalizedTaskCount, queryAsinStats.failedTaskCount, queryAsinStats.skippedTaskCount,
withdrawStats.scannedTaskCount, withdrawStats.finalizedTaskCount, withdrawStats.failedTaskCount, withdrawStats.skippedTaskCount,
noUploadStats.scannedTaskCount, noUploadStats.failedTaskCount, noUploadStats.skippedTaskCount,
resumeStats.scannedTaskCount, resumeStats.resumedTaskCount, resumeStats.skippedTaskCount,
resumeStats.unsupportedTaskCount,
// ran 放在最前面:续跑默认是关的,没有它时"没跑"与"跑了没候选"都是 s=0 r=0 k=0 u=0,
// V129 上线以来一直全零就是这么被当成"恰好没有中断任务"的
resumeStats.ran, resumeStats.scannedTaskCount, resumeStats.resumedTaskCount,
resumeStats.skippedTaskCount, resumeStats.unsupportedTaskCount,
System.currentTimeMillis() - startedAt,
Thread.currentThread().getName());
}
@@ -7,6 +7,7 @@ import com.nanri.aiimage.modules.task.mapper.FileTaskMapper;
import com.nanri.aiimage.modules.task.model.entity.FileTaskEntity;
import com.nanri.aiimage.modules.task.model.vo.TaskClientPullVo;
import com.nanri.aiimage.modules.task.spi.ClientTaskPullSpi;
import jakarta.annotation.PostConstruct;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;
@@ -80,6 +81,19 @@ public class TaskClientPullService {
log.info("[client-task-pull] 模块兜底实现注册完成 count={} modules={}", index.size(), index.keySet());
}
/**
* 启动时打印生效配置。
*
* <p>关闭时 {@link #pullPendingTasks(Long)} 直接返回空列表,HTTP 侧仍是 200 且响应体与
* "开启但没有候选"完全同形(线上实测 1 小时 4443 次 pull-pending 全空返回),
* 没有这一行就没法从日志判断兜底拉取到底有没有在用。
*/
@PostConstruct
public void logEffectiveConfig() {
log.info("[client-task-pull] 生效配置 enabled={} moduleTypes={} minPendingMinutes={} limit={} handlers={}",
enabled, moduleTypes, minPendingMinutes, Math.max(1, Math.min(limit, MAX_LIMIT)), pullHandlers.keySet());
}
/** 拉取并认领该用户"长期未被领取"的任务,按创建时间升序返回,最多 limit 条。 */
public List<TaskClientPullVo> pullPendingTasks(Long userId) {
if (!enabled) {
@@ -5,6 +5,7 @@ import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.nanri.aiimage.modules.task.mapper.FileTaskMapper;
import com.nanri.aiimage.modules.task.model.entity.FileTaskEntity;
import com.nanri.aiimage.modules.task.spi.ClientTaskPullSpi;
import jakarta.annotation.PostConstruct;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;
@@ -45,7 +46,15 @@ public class TaskResumeService {
/** moduleType → 模块兜底载荷实现;只有注册了 SPI 的模块才能被自动续跑。 */
private final Map<String, ClientTaskPullSpi> resumeHandlers;
@Value("${aiimage.task-resume.enabled:true}")
/**
* 续跑总开关。默认值必须与 {@code application.yml} 的
* {@code ${AIIMAGE_TASK_RESUME_ENABLED:${AIIMAGE_CLIENT_TASK_PULL_ENABLED:false}}} 保持同一语义:
* 继承兜底拉取的开关、两者都没配时为 <b>false</b>。
*
* <p>这里曾经是 {@code :true},而 yml 永远会给出值,所以注解里的默认在生效路径上是死代码 ——
* 但它误导了读代码的人(以为默认开着),线上因此把「48 轮全零」当成了「恰好没有中断任务」。
*/
@Value("${aiimage.task-resume.enabled:${aiimage.client-task-pull.enabled:false}}")
private boolean enabled;
/** 续跑代数上限:达到后不再重排队,任务保持 FAILED 等人工介入。 */
@@ -75,6 +84,18 @@ public class TaskResumeService {
log.info("[task-resume] 可自动续跑模块注册完成 count={} modules={}", index.size(), index.keySet());
}
/**
* 启动时打印本轮真正生效的配置,而不是让运维去反推 yml 的嵌套占位符。
*
* <p>{@code enabled=false} 会让巡检里的 resume 统计恒为 0,与"恰好没有中断任务"同形;
* 没有这一行,"续跑从未执行过"这件事在日志里是不可见的。
*/
@PostConstruct
public void logEffectiveConfig() {
log.info("[task-resume] 生效配置 enabled={} maxAttempt={} windowMinutes={} limit={} modules={}",
enabled, maxAttempt, windowMinutes, limit, resumeHandlers.keySet());
}
/** 扫描一轮:把最近因客户端中断而失败、且未续跑过的任务重新排队。 */
public ResumeStats resumeInterruptedTasks() {
ResumeStats stats = new ResumeStats();
@@ -87,6 +108,7 @@ public class TaskResumeService {
}
LocalDateTime cutoff = LocalDateTime.now().minusMinutes(Math.max(1L, windowMinutes));
int safeLimit = Math.max(1, limit);
stats.ran = true;
List<FileTaskEntity> candidates = fileTaskMapper.selectList(new LambdaQueryWrapper<FileTaskEntity>()
.eq(FileTaskEntity::getStatus, STATUS_FAILED)
.likeRight(FileTaskEntity::getErrorMessage, CLIENT_INTERRUPT_PREFIX)
@@ -181,6 +203,11 @@ public class TaskResumeService {
/** 单轮统计(合并进 stale-check 的 summary 日志,避免定期刷屏)。 */
public static final class ResumeStats {
/**
* 本轮是否真的执行过扫描。开关关闭或模块未注册时为 false,此时其余计数虽同为 0,
* 含义却是"没跑"而不是"跑了没活" —— 必须让日志能把这两件事区分开。
*/
public boolean ran;
public int scannedTaskCount;
public int resumedTaskCount;
public int skippedTaskCount;
@@ -1,5 +1,8 @@
package com.nanri.aiimage.modules.task.service;
import ch.qos.logback.classic.Logger;
import ch.qos.logback.classic.spi.ILoggingEvent;
import ch.qos.logback.core.read.ListAppender;
import com.baomidou.mybatisplus.core.MybatisConfiguration;
import com.baomidou.mybatisplus.core.conditions.Wrapper;
import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
@@ -13,6 +16,7 @@ import org.apache.ibatis.builder.MapperBuilderAssistant;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.mockito.ArgumentCaptor;
import org.slf4j.LoggerFactory;
import org.springframework.test.util.ReflectionTestUtils;
import java.time.LocalDateTime;
@@ -156,6 +160,37 @@ class TaskClientPullServiceTest {
new StubHandler("SIMILAR_ASIN", payload("similar-asin-run"))));
}
/**
* 启动必须把兜底拉取的生效配置打出来。
*
* <p>它与续跑是一对({@code task-resume.enabled} 默认继承本开关),线上两个键都没配 → 都是关;
* 而关闭时 {@code pullPendingTasks} 直接返回空,接口 200 且响应与"开了但没候选"一模一样
* (实测 1 小时 4443 次 pull-pending 全空返回)。没有这一行日志就永远查不出来。
*/
@Test
void 启动时打印生效配置() {
Logger logger = (Logger) LoggerFactory.getLogger(TaskClientPullService.class);
ListAppender<ILoggingEvent> appender = new ListAppender<>();
appender.start();
logger.addAppender(appender);
try {
TaskClientPullService service = service(new StubHandler("SIMILAR_ASIN", payload("similar-asin-run")));
ReflectionTestUtils.setField(service, "enabled", false);
service.logEffectiveConfig();
String line = appender.list.stream()
.map(ILoggingEvent::getFormattedMessage)
.filter(m -> m.contains("[client-task-pull] 生效配置"))
.findFirst()
.orElse("");
assertTrue(line.contains("enabled=false"), "启动必须说得清兜底拉取开没开:<" + line + ">");
assertTrue(line.contains("moduleTypes=SIMILAR_ASIN,COLLECT_DATA"), line);
} finally {
logger.detachAppender(appender);
}
}
private TaskClientPullService service(ClientTaskPullSpi... handlers) {
TaskClientPullService service = new TaskClientPullService(
fileTaskMapper, new InstanceMetadata("server-test"), List.of(handlers));
@@ -1,10 +1,14 @@
package com.nanri.aiimage.modules.task.service;
import ch.qos.logback.classic.Logger;
import ch.qos.logback.classic.spi.ILoggingEvent;
import ch.qos.logback.core.read.ListAppender;
import com.nanri.aiimage.modules.task.mapper.FileTaskMapper;
import com.nanri.aiimage.modules.task.model.entity.FileTaskEntity;
import com.nanri.aiimage.modules.task.spi.ClientTaskPullSpi;
import org.junit.jupiter.api.Test;
import org.mockito.ArgumentCaptor;
import org.slf4j.LoggerFactory;
import org.springframework.test.util.ReflectionTestUtils;
import java.time.LocalDateTime;
@@ -12,6 +16,7 @@ import java.util.List;
import java.util.Map;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.Mockito.doThrow;
@@ -165,4 +170,80 @@ class TaskResumeServiceTest {
assertEquals(1, stats.skippedTaskCount);
verify(mapper, never()).insert(any(FileTaskEntity.class));
}
/**
* 开关关着时,统计必须说"本轮没跑",不能长得像"跑了但没活"。
*
* <p>线上 2026-09-28 实测:{@code resume(s=0 r=0 k=0 u=0)} 在两台连续 48 轮全零,
* 而 {@code aiimage.task-resume.enabled} 的真实默认是
* {@code ${AIIMAGE_TASK_RESUME_ENABLED:${AIIMAGE_CLIENT_TASK_PULL_ENABLED:false}}}(生产两个键都没设)
* —— 也就是说 V129 整套续跑从来没执行过,但从巡检日志上和"恰好没有中断任务"完全无法区分。
*/
@Test
void 开关关闭时统计标记本轮未执行() {
FileTaskMapper mapper = mock(FileTaskMapper.class);
TaskResumeService service = service(mapper, List.of(spi("SIMILAR_ASIN")), false, 3);
TaskResumeService.ResumeStats stats = service.resumeInterruptedTasks();
assertFalse(stats.ran, "关闭时必须留得下「没跑」这个信息,否则日志里与「跑了没候选」同形");
assertEquals(0, stats.scannedTaskCount);
}
/** 真的查过库才算"本轮执行过",包括零候选的轮次。 */
@Test
void 查过库之后标记本轮已执行即使没有候选() {
FileTaskMapper mapper = mock(FileTaskMapper.class);
when(mapper.selectList(any())).thenReturn(List.of());
when(mapper.selectCount(any())).thenReturn(0L);
TaskResumeService service = service(mapper, List.of(spi("SIMILAR_ASIN")), true, 3);
TaskResumeService.ResumeStats stats = service.resumeInterruptedTasks();
assertTrue(stats.ran);
assertEquals(0, stats.scannedTaskCount);
}
/** 没有注册兜底实现等于跑不了:同样要标记未执行,不能报成"跑了没活"。 */
@Test
void 无模块注册时也算本轮未执行() {
FileTaskMapper mapper = mock(FileTaskMapper.class);
TaskResumeService service = service(mapper, List.of(), true, 3);
TaskResumeService.ResumeStats stats = service.resumeInterruptedTasks();
assertFalse(stats.ran);
}
/**
* 开机必须把续跑的生效配置打出来。
*
* <p>续跑是"功能写完了、测试全绿、线上默认关"的典型:光看代码里的
* {@code @Value(":true")} 会以为默认开着,实际 yml 把默认压成了 false。
* 所以启动那一行要直接说清 enabled 是什么、上限多少,别再让人去反推。
*/
@Test
void 启动时打印生效配置() {
Logger logger = (Logger) LoggerFactory.getLogger(TaskResumeService.class);
ListAppender<ILoggingEvent> appender = new ListAppender<>();
appender.start();
logger.addAppender(appender);
try {
FileTaskMapper mapper = mock(FileTaskMapper.class);
TaskResumeService service = service(mapper, List.of(spi("SIMILAR_ASIN")), false, 3);
service.logEffectiveConfig();
String line = appender.list.stream()
.map(ILoggingEvent::getFormattedMessage)
.filter(m -> m.contains("[task-resume] 生效配置"))
.findFirst()
.orElse("");
assertTrue(line.contains("enabled=false"), "启动必须说得清续跑到底开没开:<" + line + ">");
assertTrue(line.contains("maxAttempt=3"), line);
assertTrue(line.contains("windowMinutes=30"), line);
assertTrue(line.contains("modules=[SIMILAR_ASIN]"), line);
} finally {
logger.detachAppender(appender);
}
}
}