antispam-guardian — 反作弊与智能风控接入

分层：业务层 ｜ 部署单元：3 个 ｜ 数据库：MySQL（yidun-online-bj） ｜ base image：private-registry.nis.netease.com/library/base-image:jdk17

一、模块定位与架构

本模块是易盾「反作弊 / 智能风控」侧的服务实现：以 Dubbo 接口对外提供风控检测能力，向内复用 guardian.service 的判定逻辑，并把外部反作弊网关（anticheat-api、ac-api、yd-ir）的结论落库、经 Kafka 分发，供风控事件消费与运营查询。它本身偏「接入与转发 + 结果沉淀」，不承载页面/回调类对外 HTTP 入口。

架构分层（协议/逻辑/数据三层映射到子模块）：

• 协议层：facade/dubbo-check-api+facade/dubbo-check-provider（检测 Dubbo 契约与实现）、facade/dubbo-api+facade/dubbo-provider（查询类 Dubbo 契约与实现）、facade/http-api（HTTP 骨架，未构建）、console/api（控制台后端，未构建）。
• 逻辑层：scheduler（定时任务，当前仅示例任务）、storage（Kafka 消费入库/上报）、service/business。
• 数据层：service/base（MyBatis DAO）、domain、common。

关键数据流：

接入方 Dubbo 调用检测接口 → facade/dubbo-check-provider → guardian.service 风控判定 → 调外部 antispam.guardian.checkUrl / antispam.riskControl.checkUrl → 生成风控事件 → storage 消费 Kafka（new 集群）落 MySQL（yidun-online-bj）并转发 risk 集群 Kafka → 供下游风控与运营侧消费。

二、可部署服务清单

部署单元目录	artifactId	镜像名	端口	服务类型	独立 Dockerfile	是否进 kubernetes.yml
facade/dubbo-check-provider	antispam-guardian-facade-dubbo-check-provider	antispam-guardian-facade-dubbo-check-provider	随机（dubbo.protocol.port=-1）	Dubbo Provider（检测）	有	无（模块无 kubernetes.yml）
facade/dubbo-provider	antispam-guardian-facade-dubbo-provider	antispam-guardian-facade-dubbo-provider	随机（dubbo.protocol.port=-1）	Dubbo Provider（查询）	有	无（模块无 kubernetes.yml）
storage	antispam-guardian-storage	antispam-guardian-storage	无（Kafka 消费）	Kafka Consumer	有	无（模块无 kubernetes.yml）
console/api	antispam-guardian-console-api	—	8080	控制台 HTTP 后端	无（不构建）	否
console/web	—（仅 README 空壳，无工程）	—	无	前端骨架	无（不构建）	否
facade/http-api	antispam-guardian-facade-http	—	8080	HTTP 接口骨架	无（不构建）	否
scheduler	antispam-guardian-scheduler	—	无	定时任务	无（不构建）	否

三、同模块启动顺序

1. facade/dubbo-provider — 先起查询类 Dubbo Provider，供控制台/下游解析。
2. facade/dubbo-check-provider — 起检测类 Dubbo Provider（独立 registry id guardianCheckRegistry），对外提供风控检测。
3. storage — 消费 Kafka 落地风控结果，依赖 Dubbo Provider 与 MySQL/Kafka 就绪。

console/api、facade/http-api、scheduler 无可构建镜像、application-online.properties 仍为 localhost 模板，不纳入常规启动序列。

四、逐服务启动逻辑

4.1 facade/dubbo-check-provider

• 启动类：com.netease.is.antispam.guardian.facade.dubbo.check.DubboCheckApplication（facade/dubbo-check-provider/src/main/java/com/netease/is/antispam/guardian/facade/dubbo/check/DubboCheckApplication.java）。
• exclude：无。
• @Enable*/@Import：@EnableAspectJAutoProxy、@EnableBusinessClient。
• 配置类：configuration/CheckDubboConfiguration —— @ComponentScan({"com.netease.is.antispam.guardian.service"}) + @Bean RedisComponent（无 @MapperScan）。
• Dubbo：dubbo.scan.basePackages=com.netease.is.antispam.guardian.facade.dubbo.check.provider；dubbo.registry.id=guardianCheckRegistry（自定义 registry id）；dubbo.protocol.threads=300。
• main() 自定义：无。
• 启动钩子：client/ContextRefreshedEventListener implements ApplicationListener<ContextRefreshedEvent>，在根上下文（parent==null）时手动 businessClient.start()（因 business.client.autoStart=false）。

4.2 facade/dubbo-provider

• 启动类：com.netease.is.antispam.guardian.facade.dubbo.DubboApplication（facade/dubbo-provider/src/main/java/com/netease/is/antispam/guardian/facade/dubbo/DubboApplication.java）。
• exclude：无。
• @Enable*/@Import：@EnableAspectJAutoProxy（未加 @EnableBusinessClient）。
• 配置类：configuration/FacadeDubboConfiguration —— @ComponentScan({"com.netease.is.antispam.guardian.service"}) + @Bean RedisComponent。
• Dubbo：dubbo.scan.basePackages=com.netease.is.antispam.guardian.facade.dubbo.provider；dubbo.provider.filter=qos-access；dubbo.protocol.register=false（不注册注册中心）；dubbo.application.dump-directory=./logs；dubbo.application.qos-enable=false。
• main() 自定义：无。
• 启动钩子：未发现（仅 RedisComponent Bean）。

4.3 storage

• 启动类：com.netease.is.antispam.guardian.storage.StorageApplication（storage/src/main/java/com/netease/is/antispam/guardian/storage/StorageApplication.java）。
• exclude：无。
• @Enable*/@Import：@EnableBusinessClient。
• 配置类：configuration/StorageConfiguration —— @ComponentScan({"com.netease.is.antispam.guardian.service"}) + @Bean RedisComponent。
• Kafka：消费 netease.kafka.consumer.cluster.new（groupId=antispam-guardian-storage）；生产 netease.kafka.producer.cluster.risk（yidun-jdlt-ywkafka0*）。
• main() 自定义：无。
• 启动钩子：cache/RiskTransSwitchProductCache implements InitializingBean（定时刷新风控转接开关缓存，线程名 RiskTransSwitchProductCacheRefresh）；优雅下线 configuration/YidunQosApplication.doOffline() 调 kafkaListenerEndpointRegistry.stop() 后 Thread.sleep(3000)。

4.4 console/api（无 Dockerfile，不构建）

• 启动类：com.netease.is.antispam.console.api.ConsoleApplication；仅 @SpringBootApplication。
• 配置类：ConsoleConfiguration（@ComponentScan + @MapperScan）、SwaggerConfiguration（Swagger 文档）。
• 端口：server.port=8080，Undertow（io-threads=1、worker-threads=2）。
• application-online.properties 为 127.0.0.1:3306/fate localhost 模板。

4.5 facade/http-api（无 Dockerfile，不构建）

• 启动类：com.netease.is.antispam.facade.http.HttpApplication；仅 @SpringBootApplication。
• 配置类：FacadeHttpConfiguration（@ComponentScan + @MapperScan）、SwaggerConfiguration。
• application-online.properties 为 localhost 模板。

4.6 scheduler（无 Dockerfile，不构建）

• 启动类：com.netease.is.antispam.scheduler.SchedulerApplication；@SpringBootApplication + @EnableScheduling。
• 配置类：SchedulerConfiguration（@ComponentScan + @MapperScan）。
• 任务：tasks/ProjectDemoTask（@Scheduled(cron="* * * * * *")）示例任务，未发现真实业务任务。

五、启动前置依赖

依赖	配置键/地址	阻塞 or 弱依赖	配置文件
Apollo	app.id=antispam-guardian；namespaces application,guardian-common；apollo.meta=http://yd-apollo-meta.service.163.org	阻塞	storage/src/main/resources/application.properties
ZooKeeper（Dubbo 注册）	dubbo.registry.address=zookeeper://nisp-zk5.service.163.org:2181?...；group /yidun/antispam/online-new/yidun-antispam-dubbo	阻塞	application-online.properties
ZooKeeper（business 配置）	business.client.options.zookeeper.rootPath=/netease-antispam/online/config	阻塞	application-online.properties
MySQL	jdbc:mysql://yidun-ddbrw.dba.163.org:6000/yidun-online-bj（com.mysql.cj.jdbc.Driver + Hikari）	阻塞	application-online.properties
Kafka	收 netease.kafka.consumer.cluster.new.bootstrap.servers=yidun-jd-nrkafka0*；发 ...cluster.risk.bootstrap.servers=yidun-jdlt-ywkafka0*	阻塞	application-online.properties
外部 HTTP	antispam.guardian.apiUrl=http://anticheat-api.service.163.org；checkUrl=http://ac-api.service.163.org；antispam.riskControl.checkUrl=http://yd-ir.service.163.org	弱依赖	application-online.properties
Sentinel	spring.cloud.sentinel.transport.dashboard=yidun-sentinel.service.163.org:80；降级规则 ZK 路径 /sentinel_rule_config/${spring.application.name}/degradeRules	弱依赖	application-online.properties
Redis	未发现显式配置（代码中 @Bean RedisComponent）	弱依赖	—

六、启动参数与 Profile

• Profiles：各单元 application.properties 默认 spring.profiles.active=dev；已有 dev/test/online（facade/dubbo-check-provider 另有多地区变体 beijing-online/gz-online/sh-online/hz-ali/xjp-online/jiande-online/online-pre/test-pre/jiande-online-pre）；无 application-private.properties。
• Maven profile：根 buildAll.sh 设 GLOBAL_ENV=private，逐模块 build.sh -e private 触发 mvn clean install -P private。
• JAVA_OPTS：三个服务均 -Xmx512m -Xms512m -XX:+UseG1GC -Dspring.profiles.active=private。
• base image 与仓库：private-registry.nis.netease.com/library/base-image:jdk17；镜像仓库 private-registry.nis.netease.com/yidun；tag base-250409；jar 落 /app/，入口 bash docker-entrypoint.sh。

七、启动期踩坑

1. 无 application-private.properties 却强制 -Dspring.profiles.active=private：只会加载 application.properties（默认 dev 段），Dubbo 注册地址、数据源等关键配置缺失，容器内启动大概率失败。
2. 两个 registry id 不同：facade/dubbo-check-provider 用 guardianCheckRegistry，facade/dubbo-provider/storage 用 zookeeper；排查「注册不上」时先看 id 是否配对。
3. storage 优雅下线固定 sleep 3s（YidunQosApplication.doOffline 先 kafkaListenerEndpointRegistry.stop() 再 Thread.sleep(3000)），terminationGracePeriodSeconds 需留足。
4. facade/dubbo-provider 设 dubbo.protocol.register=false，不向注册中心注册，消费方需另配直连/其他发现方式。
5. 镜像私仓与 crawler 不同：本模块用 private-registry.nis.netease.com/yidun，crawler 用 private-registry.yidun.internal/yidun，构建脚本不可混用。
6. storage 设 spring.main.allow-bean-definition-overriding=true，Bean 覆盖被静默允许，冲突不易暴露。
7. console/api、facade/http-api、scheduler 无法构建：无 Dockerfile，且 application-online.properties 仍是 127.0.0.1:3306/fate localhost 模板。
8. scheduler 仅含示例任务 ProjectDemoTask（@Scheduled 每秒触发），未见真实业务定时逻辑。
9. 业务客户端手动启动：facade/dubbo-check-provider 因 business.client.autoStart=false，靠 ContextRefreshedEventListener 主动 businessClient.start()，异常仅记日志不阻断启动。

八、跨模块前置

• 依赖 antispam-business（@EnableBusinessClient 读产品/密钥，ZK rootPath=/netease-antispam/online/config）。
• 依赖外部反作弊网关（anticheat-api / ac-api / yd-ir / ir-inner），不可达会降级或超时。
• 中间件前置：ZooKeeper、MySQL、Kafka（new 与 risk 集群）就绪。
• Dubbo 侧：facade/dubbo-provider、facade/dubbo-check-provider 应先于消费方启动。

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