易盾服务启动手册

外观

antispam-file — 文档 / 压缩包内容反垃圾检测（文件解析 → 元素送检 → 结果回调） ​

分层：解决方案层（Facade + 异步 Worker） ｜ 部署单元：5 个（有 Dockerfile） ｜ 数据库：TiDB（库 antispam） ｜ base image：private-registry.nis.netease.com/library/base-image:jdk8

一、模块定位与架构 ​

业务定位：antispam-file 负责文档类内容的反垃圾检测，覆盖 Office / PDF / 纯文本 / 压缩包等文件的解析、元素拆分、送下游文本与图片引擎检测，以及检测结果的入库与回调。它本身不做识别算法，而是做「文件 → 可检测元素 → 引擎结果 → 客户回调」的编排与状态机。

架构分层：

层子模块目录职责
协议层facade/http-api、facade/dubbo-provider、checker对外 HTTP 查询/回调/反馈、内部 Dubbo 服务、Kafka 检测入口
逻辑层service/business、service/base、parser、common、domainES/Kafka/Redis 封装、MyBatis DAO 与 Manager、文件解析库、枚举常量、实体与 DTO
数据层MySQL/TiDB、Elasticsearch、Redis Sentinel、Kafka任务与结果持久化、检索、缓存/锁、异步消息

关键数据流：

  1. 客户端 → http-api：提交文件检测任务（含内容上传），任务落库并投递 Kafka。
  2. checker 消费 Antispam_FileSolution_Check_N：下载文件 → 解析 → 拆分文本/图片元素。
  3. checker 将元素送下游文本/图片检测能力（http://as.test.dun.163.com/v1/file/parse/submit 等）。
  4. storage 消费结果消息：写 DB/ES，并按需触发主动回调。
  5. http-api：对外提供查询、被动回调、反馈审核；scheduler 兜底重试回调与超时/积压处理。
  6. scheduler（ElasticJob）扫描解析/送检/回调各阶段，做补偿与重试。

二、可部署服务清单 ​

部署单元目录artifactId镜像名端口服务类型独立 Dockerfile是否进 kubernetes.yml
checkerantispam-file-solution-checkerantispam-file-solution-checker无（非 Web）Kafka Worker（解析 + 送检）有是（replicas=2）
facade/dubbo-providerantispam-file-solution-facade-dubbo-providerantispam-file-solution-facade-dubbo-providerDubbo 协议端口（未显式配置，走默认）Dubbo Provider有是（replicas=2）
facade/http-apiantispam-file-solution-facade-httpantispam-file-solution-facade-http-api18809（private 覆写为 8080）HTTP（查询 / 回调 / 反馈）有是（replicas=2）
storageantispam-file-solution-storageantispam-file-solution-storage无Kafka Consumer（结果入库 + 回调）有是（replicas=2）
schedulerantispam-file-solution-schedulerantispam-file-solution-scheduler无ElasticJob 定时任务有否
console/apiantispam-file-solution-console-api—8080控制台 HTTP无（不构建）否
  • 镜像推送仓库为 private-registry.nis.netease.com/yidun，而 kubernetes.yml 拉取的是 private-registry.yidun.internal/yidun/*:1.0.0.private，仓库主机不一致（见第七节）。
  • scheduler 有 Dockerfile 但无 build.sh，因此不会被根目录 buildAll.sh 的 find . -name build.sh 循环命中，也不会进入 kubernetes.yml。

三、同模块启动顺序 ​

  1. storage —— 先让结果落库/建索引的通路就绪，避免后续消费到的检测结果无处可写。
  2. checker —— 文件解析与送检 Worker 上线，但此时生产者不活跃，可安全冷启动。
  3. http-api —— 打开客户提交通路；此时 storage 已可消费，链路完整。
  4. dubbo-provider —— 注册内部 Dubbo 服务，供其它模块查询复用。
  5. scheduler —— 最后开闸：一旦启动即按 cron 向 Antispam_FileSolution_Check_N 投递/推动任务，过早启动会在下游未就绪时制造积压。

四、逐服务启动逻辑 ​

checker ​

  • 启动类：com.netease.is.antispam.file.solution.checker.CheckerApplication（checker/src/main/java/com/netease/is/antispam/file/solution/checker/CheckerApplication.java）。
  • @SpringBootApplication：无 exclude。
  • @Enable*：@EnableCdcDataSubscribe、@EnableOssClient、@EnableBusinessClient、@EnableRecoverComponent、@EnableConfigurationProperties({FileSolutionProperties.class})。
  • 组件扫描：与启动类同包的 checker.configuration.CheckerConfiguration（@ComponentScan：file.solution.service/manager/component/component.recover + @MapperScan("com.netease.is.antispam.file.solution.dao")）；checker.configuration.KafkaConfiguration（@EnableKafka）。
  • Kafka 关键参数（KafkaConfiguration）：enable.auto.commit=false、max.partition.fetch.bytes=20971520、max.poll.records=100，kafkaListenerContainerFactory 的 concurrency=1（固定单并发）。
  • main() 自定义逻辑：System.setProperty("javax.xml.parsers.DocumentBuilderFactory", "com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl")（JAXP 实现强制指定，不可删，否则文档解析可能出现工厂解析异常）。
  • 启动钩子：com.netease.is.antispam.file.solution.checker.configuration.YidunQosApplication（@QosRegister）。doOffline() 停止 KafkaListenerEndpointRegistry 与全部 ConcurrentMessageListenerContainer 后 Thread.sleep(3000L)，用于优雅下线。

facade/dubbo-provider ​

  • 启动类：com.netease.is.antispam.file.solution.facade.dubbo.DubboApplication。
  • @SpringBootApplication(exclude = {DataSourceAutoConfiguration.class})。
  • @Enable*：@EnableAspectJAutoProxy、@EnableCdcDataSubscribe、@EnableOssClient、@EnableConfigurationProperties({FileSolutionProperties.class})、@EnableRecoverComponent。无 @EnableApolloConfig（properties 里存在 app.id=antispam-file 与 apollo.bootstrap.*，但缺注解入口）。
  • 组件扫描：facade.dubbo.configuration.DubboFacadeConfiguration（@ComponentScan：service、manager、component.limiter/op/cdc/recover + @MapperScan(...dao)）。
  • 数据源：facade.dubbo.configuration.DynamicDataSourceConfiguration —— Druid masterDataSource(spring.datasource.master)、mirrorDataSource(spring.datasource.mirror)，并暴露 @Primary 的 DynamicDataSource（Master/Mirror 物理源映射）。
  • main() 无自定义逻辑；启动钩子：未发现。

facade/http-api ​

  • 启动类：com.netease.is.antispam.file.solution.facade.http.HttpApplication。
  • @SpringBootApplication（无 exclude）。
  • @Enable*：@EnableCdcDataSubscribe、@EnableOssClient、@EnableBusinessClient、@EnableConfigurationProperties({FileSolutionProperties.class})、@EnableRecoverComponent、@ServletComponentScan、@EnableI18nComponent、@EnableApolloConfig、@EnableAspectJAutoProxy。
  • 组件扫描：facade.http.configuration.HttpFacadeConfiguration implements WebMvcConfigurer（@ComponentScan 含 component.callback 与 com.netease.is.antispam.components.callback + @MapperScan(...dao)）。@Bean validator() 使用 HibernateValidator，hibernate.validator.fail_fast=false；addInterceptors 注册 GlobalControllerInterceptor 拦截 /**。
  • 配置：server.port=18809（application-private.properties 覆写为 8080），app.id=antispam-file-http，Apollo 命名空间 application,file-http，端口 dubbo.registry.group=/yidun/antispam/online-new/yidun-antispam-dubbo。
  • main() 无自定义；启动钩子：未发现。

storage ​

  • 启动类：com.netease.is.antispam.file.solution.storage.StorageApplication。
  • @SpringBootApplication + @EnableOssClient、@EnableBusinessClient、@EnableRecoverComponent、@EnableCdcDataSubscribe、@EnableApolloConfig、@EnableConfigurationProperties({FileSolutionProperties.class})。
  • 组件扫描：storage.configuration.StorageConfiguration（@ComponentScan 含 component.check.submitter、components.callback + @MapperScan(...dao)）；storage.configuration.KafkaConfiguration（@EnableKafka，kafkaListenerContainerFactory 的 concurrency=8）。
  • Kafka 双通道：Spring Kafka（spring.kafka，group-id=file-solution-storage、max.poll.records=100）+ 易盾组件消费 netease.kafka.consumer.cluster.new（max.poll.records=20、max.poll.interval.ms=600000）。
  • 业务参数：file.dealpool.consumer.maxwait.count=10；app.id=antispam-file-storage，Apollo 命名空间 application,file-storage,antispam-privatization-common。
  • 启动钩子：storage.YidunQosApplication（停 Kafka 容器 + sleep，与 checker 同实现）。

scheduler ​

  • 启动类：com.netease.is.antispam.file.solution.scheduler.SchedulerApplication。
  • @SpringBootApplication + @EnableElasticJob、@EnableScheduling、@EnableOssClient、@EnableConfigurationProperties({FileSolutionProperties.class})、@EnableBusinessClient、@EnableRecoverComponent、@EnableApolloConfig、@EnableCdcDataSubscribe、@EnableDubbo。
  • 组件扫描：scheduler.configuration.SchedulerTaskConfiguration（任务包 + integration + kafka + components.callback）。
  • ElasticJob 作业（application.properties）：fileParseTaskDealWorker(0/3s，分片 15)、fileItemSendCheckWorker(0/3s，分片 10)、fileParseTaskDealRecoverWorker(0/20s)、fileDataLockRecordReleaseWorker(*/5s)、fileDataCheckFinishWorker、compressFileCheckFinishWorker、fileActiveCallbackRetryWorker、fileAutoCallbackRetryWorker、fileCheckOverStockNoticeWorker、fileParseCallbackTaskDealWorker、fileCreateWorkerTaskDealWorker；fileCheckTimeoutWorker2.enable=false（已停用）。
  • 配置：app.id=antispam-file_scheduler，Apollo 命名空间 application,file_scheduler；ElasticJob ZK private 见各 profile。
  • 启动钩子：scheduler.YidunQosApplication。

五、启动前置依赖 ​

依赖配置键 / 地址阻塞 or 弱依赖配置文件
Apollo无显式 meta（各 profile 内置）；app.id / apollo.bootstrap.namespaces弱（未下发时用本地默认）application*.properties
TiDBspring.datasource.*；tidb-cluster0-tidb.tidb.svc:4000/antispam阻塞application-private.properties
Redis Sentinelspring.redis.sentinel.master=master01、...nodes=redis0-redis-ha.yidun-infra.svc:26379阻塞application-private.properties
ZooKeeper（Dubbo 注册）dubbo.registry.address=zookeeper://zk-0/1/2.zookeeper.yidun-infra:2181；dubbo.registry.group=/yidun/antispam/online-new/yidun-antispam-dubbo阻塞application-private.properties
ZooKeeper（business client）business.client.options.zookeeper.rootPath=/netease-antispam/online/config阻塞application-private.properties
Kafkaspring.kafka.bootstrap-servers=kafka-yidun-0/1/2...:9092、cdc.kafka.bootstrap-servers阻塞application-private.properties
ElasticJob ZKelastic.job.zk.server-lists（scheduler 专属）阻塞（仅 scheduler）scheduler/application-{test,online,...}.properties
OSSnos.netease.com、nos-jd.service.163.org弱application.properties
下游检测 HTTPhttp://as.test.dun.163.com/v1/file/parse/submit 等弱（失败可重试）application-private.properties

六、启动参数与 Profile ​

  • Spring profiles：默认 spring.profiles.active=dev；容器统一 -Dspring.profiles.active=private（Dockerfile ENV JAVA_OPTS）。
  • Maven profile（根 pom.xml）：default（activeByDefault）、test、online、private、jiande-online、private-bes（宝兰德 BES 内嵌容器）。作用为设置 deploy.env 驱动资源过滤 <filter>src/main/filter/${deploy.env}.properties</filter>。
  • JAVA_OPTS：checker = -Xmx1024m -Xms1024m -XX:+UseG1GC -Dspring.profiles.active=private；其余单元 -Xmx512m -Xms512m + 同款 GC/Profile。
  • base image 与仓库：FROM private-registry.nis.netease.com/library/base-image:jdk8；推送仓库 private-registry.nis.netease.com/yidun；tag 1.0.0.private。
  • checker 额外 RUN apk add --no-cache unrar（需解析 RAR 压缩包）。
  • 构建：buildAll.sh → mvn clean install -Pprivate → 遍历 build.sh（-c false -p false -e private）→ docker buildx build --platform linux/amd64,linux/arm64 --push → 调 podupdate.sh 更新 Pod。

七、启动期踩坑 ​

  1. storage/build.sh 的 MODEL_NAME=checker：storage 目录的构建脚本里 MODEL_NAME 误设为 checker（复制粘贴遗留），会编译错模块。
  2. Dockerfile COPY 与 finalName 不匹配：除 checker（<finalName>antispam-file-solution-checker</finalName>）外，其余单元 finalName 均为 ${project.artifactId}-${project.version}-application，而 Dockerfile 写死 COPY ./target/${APP_NAME}.jar（APP_NAME 为不带版本后缀的镜像名）→ docker build 阶段 COPY 找不到文件而失败。
  3. scheduler 不在 kubernetes.yml，且无 build.sh：定时补偿任务不会随清单部署，也不被 buildAll.sh 构建，需人工处理。
  4. CheckerApplication.main 的 DocumentBuilderFactory 设置不可删：删除后文档解析相关 XML 工厂可能抛异常。
  5. checker 无 Apollo 注解入口 / 无 @EnableApolloConfig：改配置只能重打镜像或改 profile 文件，无法走配置中心热更。
  6. dubbo-provider 无 @EnableApolloConfig：虽然 application.properties 里有 app.id 与 apollo.bootstrap.*，但缺注解入口，Apollo 生效性存疑。
  7. checker Kafka 消费者并发固定为 1：kafkaListenerContainerFactory.setConcurrency(1)，分区横向扩展能力受限，需靠多副本分摊。
  8. 仓库主机不一致：build.sh 推送 private-registry.nis.netease.com/yidun，kubernetes.yml 拉取 private-registry.yidun.internal/yidun*；镜像 tag 也要人工对齐 1.0.0.private。
  9. kubernetes.yml 探针缩进错误：readinessProbe 被错误地嵌套在 livenessProbe 的字段之下，readinessProbe 实际不会生效。

八、跨模块前置 ​

  • 下游文本 / 图片检测能力（文本、图片业务服务的 Dubbo/HTTP）必须先可用，否则 checker 送检全量失败并堆积。
  • 公共组件配置中心：Apollo application 命名空间 + antispam-privatization-common 的公共配置需先就绪。
  • 共享基础设施：Kafka（kafka-yidun-*）、ZooKeeper（zk-0/1/2.zookeeper.yidun-infra:2181）、Redis Sentinel（redis0-redis-ha.yidun-infra.svc:26379）、TiDB（tidb-cluster0-tidb.tidb.svc:4000）由平台侧统一提供，需先于本模块启动。
  • OSS 对象存储：文件原件与解析产物依赖 OSS，桶 yidun-antispam-solution 需已创建并授权。

相关：全局启动顺序 · 部署单元矩阵 · 踩坑速查

内部技术文档 · 请勿外传

网易易盾 · 反垃圾内容安全平台