启动期踩坑速查

按「症状 → 原因 → 处置」组织。全部结论来自仓库源码与配置实测。

一、起不来的 Top 10

#	症状	原因	处置
1	启动即报配置缺失 / Dubbo 注册失败	`Dockerfile` 强制 `-Dspring.profiles.active=private`，但仓库无 `application-private.properties` → profile 回退到 `dev`	用环境变量覆盖 profile，或补齐 private 配置文件。受影响：`antispam-guardian`、`yidun-cms`、`yidun-mplatform-event`、`yidun-website`、`antispam-stream-solution`、`yidun-ai-agent`、`yidun-model-evaluation`
2	数据源初始化失败	启动类 `exclude = DataSourceAutoConfiguration.class`，但未提供自定义数据源配置	检查 `spring.datasource.master/mirror` 是否齐全。受影响：`antispam-business-*` 的 dubbo-provider、`antispam-cms` 的 console/api、`antispam-file` 的 dubbo-provider
3	启动慢 / 卡在 Bean 初始化	`@PostConstruct` 全量加载（配置缓存、词表、图库、名单）	属正常，但库不可达会直接抛异常。见 §三
4	Kafka 消费者起不来	`@EnableKafka` + `enable.auto.commit=false` + ZK/集群地址错误	校验 `spring.kafka.bootstrap-servers`；注意 `netease.kafka.consumer.` 与 `spring.kafka.` 两套并存
5	ElasticJob 任务注册失败	`elastic.job.zk.serverLists` 指向错误端口	`antispam-video-solution` 的 private 配置误指向 Kafka 9092
6	分布式 ID 冲突	多服务共用同一 `distribute.id.namespace`	`antispam-keyword` 的 check-provider 与其它服务共用 `namespace=antispam-keyword`
7	OSS 客户端初始化失败	`@PropertySource("classpath:xxx-oss.properties")` 指向的文件不存在	`antispam-business-livevideo` 的 `livevideo-oss.properties` 仓库内缺失
8	ShenYu 网关注册反复重试	`shenyu.register.enabled=true` 但 ShenYu admin 不可达	`antispam-rule` 的 http-api base 默认 `false`，环境需确认
9	服务起来了但业务全失败	弱依赖（算法侧）未就绪	见 §四
10	容器启动命令失败、日志里没有 Java 堆栈	`netease-image` 启动命令第一步是 nagent/CMDB 认领	检查 `/etc/nagent_sn`、`claimUrl`、`kinit`

二、构建 / 部署层面（改完不生效）

症状	原因	处置
改代码后镜像没变	该子模块没有 `build.sh`，`buildAll.sh`（`find . -name build.sh`）不会构建它	手动构建或补 `build.sh`。全模块 `console/api` 几乎都是这种情况
镜像构建 COPY 失败	Dockerfile 的 `COPY ./target/${APP_NAME}.jar` 与 pom 的 `<finalName>` 不一致	检查 `<finalName>`；`antispam-file` 的 4 个单元、`yidun-model-evaluation` 的 platform-api 有此问题
构建出来的镜像互相覆盖	两个单元的 `build.sh` 用了同一个 `DOCKER_IMAGE_NAME`	`antispam-keyword` 的 `dubbo-cache-provider` 与 `dubbo-provider` 冲突
构建出的是旧代码	`antispam-file/storage/build.sh` 的 `MODEL_NAME=checker`	脚本复制粘贴遗留，需人工核对
ARM 构建污染后续构建	`buildAll-arm.sh` 会改写文件再 `git checkout -- .` 还原，中途失败则残留	构建失败后先 `git status` 检查
拉不到镜像	`build.sh` 推 `private-registry.nis.netease.com/yidun`，`kubernetes.yml` 拉 `private-registry.yidun.internal/yidun`	两套 registry 并存，按环境确认
部署清单与镜像 tag 不一致	`kubernetes.yml` 固定 `:1.0.0.private`，`build.sh` 用其它 tag	以部署编排为准

三、启动钩子相关的隐性行为

钩子	影响
`BusinessCacheManager.@PostConstruct init()`（`antispam-business` http-api）	同步全量加载业务配置，DB 不可达即启动失败（非优雅降级）
`ImageConfigSyncService` / `ImageLibSyncService`（`antispam-image` check-provider）	`@PostConstruct` 分页全量扫表（`BATCH_SIZE=2000`）+ `@Scheduled` 增量；且 `@EnableScheduling` 挂在与启动类同包的 `CheckConfiguration` 上，若启动类加了覆盖默认包的 `@ComponentScan`，定时同步会静默失效
`ListFullSyncService` / `IpRegionFullSyncService`（`antispam-list` dubbo-provider）	启动期全量同步名单与 IP 地区，量大时启动耗时长
`PreStartHandler.preStart()`（`antispam-business-image` storage）	`SpringApplication.run()` 之后手动调用，bean 缺失直接崩在启动后
`RedisDelayTask implements ApplicationRunner`（`antispam-cms` scheduler）	Redis 不可用 → scheduler 启动失败（非降级）
`ContextRefreshedEventListener`（keyword / rule / liveaudio / textclassify）	容器刷新后预热；异常会阻断启动
`YidunQosApplication.doOffline()`	主动 pause/stop Kafka 容器再 sleep（3s / 60s）→ `terminationGracePeriodSeconds` 必须大于该值
`StorageSmartLifecycle.isRunning()`（business-video/livevideo）	实现恒返回 `false`（实现瑕疵），依赖该值的框架会误判就绪

四、弱依赖导致的「启动成功但业务不可用」

服务	弱依赖	表现
`antispam-image`	`netease-image`（`app.image.check-url`）	检测返回空/异常，进程正常
`antispam-textclassify`	`textalg` 算法引擎（`app.text-classify.remote.cluster.api-url`）	检测降级，抛 `ApiNotAvailableException`
`antispam-llm`	`yidun-ai-agent`（`aiAgentSk`）	`chat()` 直接返回 null，只打 error 日志，静默失败
`antispam-llm`	`antispam-rule`（`RuleCheckFacade.checkV2`）	审核动作无法最终裁决
`antispam-business-livevideo-solution`	`antispam-business-livevideo` / `-liveaudio` Dubbo	同步提交链路直接超时失败（不是异步积压）
`yidun-private-consume`	`antispam-cms` console-api	token 清理失败仅 warn
全平台	`antispam-business`（配置源）	鉴权/策略/密钥空，检测结果不可信

五、配置与代码的「对不上」清单

位置	问题
`antispam-textclassify`	`dubbo.protocal.register=false`（拼写错误 `protocal`，配置不生效）；`apollo.bootstrap.enabled=false`（与其它模块相反）
`antispam-stream-solution`	`dubbo-protocal.register=false` 同样拼写错误
`antispam-llm`	`scheduler` 的包名与物理路径错位（`com.netease.is.antispam.llm.scheduler` vs `.../antispam/text/library/scheduler/`）
`antispam-stream-solution`	`SchedulerConfiguration` 的 `@ComponentScan` 包名多了一层 `antispam`（`...antispam.antispam.stream.solution...`），实际不扫描任何 Bean；`@MapperScan` 被注释
`yidun-model-evaluation` / `yidun-ai-agent`	`mq` 模块的 `MqConfiguration` 扫描 `com.netease.is.antispam.yidun-model-evaluation`（外部包名），`ExampleConsumer` 的 topic 为 `topic-xxx` —— 骨架占位
`antispam-livevideo-solution`	`dubbo-check-provider` 扫描 `com.netease.is.antispam.liveaudio` 包
`antispam-cms`	`facade/http-api` 有端口 8918 与启动类，但无 Dockerfile
`yidun-message`	`facade/dubbo-provider` 的 `dubbo.scan.basePackages` 指向空包（无 Provider 实现）；`scheduler` 无任何任务
`yidun-export`	`scheduler` 无任务实现（任务内嵌在 http-api）
`antispam-image`	`http-api`/`scheduler`/`console/api` 三产物有启动类但无 Dockerfile

六、「空壳 / 未接线」服务（别浪费时间排查）

服务	状态
`antispam-bill` 的 `collect`/`scheduler`/`http-api`/`console`	有完整启动类与配置，无部署脚本
`antispam-business` 的 `console`/`scheduler`/`storage`	同上
`yidun-message` 的 `dubbo-provider`/`scheduler`	无 Provider 实现 / 无任务
`yidun-export` 的 `scheduler`	无任务
`yidun-private-consume` 的 `storage`	`EdaConsumer.consume()` 无任何调用方，pom 无 MQ 依赖 → 不消费任何消息
`yidun-private-consume` 的 `facade/http-api`	只有启动类，无 Controller
`yidun-model-evaluation`/`yidun-ai-agent` 的 `mq`	示例消费者，topic 为占位
`yidun-model-evaluation` 的 `facade/dubbo-provider`	无 `@DubboService` 实现
`antispam-keyword` 的 `dubbo-cache-provider`	构建脚本与 `dubbo-provider` 冲突，实际不会产出独立镜像
`netease-antispam` 的 `open-api`/`dubbo-check`/`calculation`/`on-device-check`/`privatization-consume`/`privatization-server-http`	有可运行入口，无 `build.sh` + `Dockerfile`
`antispam-textclassify` 的 `scheduler`	仅有 demo 任务 `@Scheduled(cron="* * * * * *")`（每秒）

七、安全与合规提醒

明文凭据：antispam-crawler-solution（OSS AK/SK）、antispam-guardian/yidun-account/yidun-cms（DB 口令）、antispam-business-image（Redis 口令、gpt.auth.token=sk-...）、yidun-private-custom（默认硬编码 AES key WWlEdW4yMDI2U2VjcmV0IQ==）均直接写在 application*.properties。
私有化凭据规范：中间件凭据应经 yidun-private-custom 获取，禁止在配置/代码硬编码密码。

相关页面：全局启动顺序 · 中间件与配置基线 · 模块矩阵