易盾服务启动手册

外观

antispam-business — 反垃圾业务配置中心（配置写入/事件分发 + 只读缓存开放接口） ​

分层：平台基础配置层 ｜ 部署单元：2 个（另有 3 个有启动类但不构建）｜ 数据库：MySQL/TiDB antispam ｜ base image：private-registry.yidun.internal/yidun/base-image:jdk17（tag migu-231016）

一、模块定位与架构 ​

它是易盾内容安全平台的“配置底座”：把产品、业务(Target)、业务配置、检测器、标签、密钥、预上线配置、客户场景、策略集等十几类配置统一管起来，替代早期纯 Zookeeper 存储+推送的重方案，再通过 Dubbo 门面、HTTP 开放接口与客户端 SDK 分发给下游约 20 个检测模块（文本/图片/音视频/直播/解决方案/计费）。

架构分层

  • 门面层（协议层）：facade/dubbo-provider（Dubbo 写侧：配置 CRUD/上下线）、facade/http-api（HTTP 读侧：api/business/* 全量/增量拉取 + BusinessCacheManager）
  • 逻辑层：service/business（*ServiceImpl、component/event/OperateEventDispatcher、component/cache/BusinessCache*、AsyncComponent、QpsExcludeComponent）
  • 数据层：service/base（*Manager + *Dao，MyBatis）+ domain（Model/BO/Request/Response）+ common（OperateTargetType/OperateType/ResultStatus 等枚举常量）
  • 分发层：client/（core/http/zookeeper/spring-starter，下游 SDK：全量/增量同步、本地缓存、事件订阅）
  • 事件落地与运维：storage（Kafka 消费配置变更事件）、console/api（控制台）、scheduler（定时任务）—— 三者本仓库不构建部署

关键数据流（写入）

  1. 运营/CMS/netease-antispam → Dubbo TargetFacade/TargetConfigFacade/ProductFacade → service/business 落库 MySQL
  2. 落库后 applicationEventPublisher.publishEvent(OperateEvent)
  3. OperateEventDispatcher 扇出到 *ZookeeperListener（回写 ZK 节点，兼容存量客户端）与 *OpRecordListener（写操作流水 business_op_record）
  4. http-api 的 BusinessCacheManager 周期扫描 business_op_record 增量刷新内存缓存
  5. 下游客户端凭 lastOperateTime 经 api/business/fetch 拉增量 / 经 init 接口拉全量

关键数据流（读取）

  1. 下游客户端/HTTP 调用 → facade/http-api 的 api/business/*
  2. BusinessCacheManager 命中内存 businessCacheMap（按 OperateTargetType 索引）
  3. 未命中或时间戳落后时回查 business_op_record 并前插历史队列（businessOpRecordQueryBoResponsesDeque，有 historicalDataSize 上限与 lastOperateTimeProtection 保护）
  4. 返回 BusinessDataResponse（含 serverSideRefreshInterval / serverSideLastRefreshTime 供客户端校准）

配置对象生命周期 状态不用“上/下线”二态表达，而由 OperateType（CREATE/UPDATE/DELETE/ONLINE/OFFLINE）表达动作语义：ONLINE = 生效（刷入 ZK / 使配置生效），OFFLINE = 失效（从 ZK 移除）；预上线配置（PRE_*）与正式配置共用实体类型，靠 OperateTargetType 区分。

二、可部署服务清单 ​

部署单元目录artifactId镜像名端口服务类型独立 Dockerfile是否进 kubernetes.yml
facade/dubbo-providerantispam-business-facade-dubbo-providerprivate-registry.yidun.internal/yidun/antispam-business-dubbo-provider:migu-231016Dubbo port=-1（随机，无 Web）Dubbo Provider有是（replicas=2）
facade/http-apiantispam-business-facade-http-apiprivate-registry.yidun.internal/yidun/antispam-business-http-api:migu-23101618880(base) / 8080(private)HTTP（Undertow）有否
console/apiantispam-business-console-api无（不构建）—控制台后端无否
schedulerantispam-business-scheduler无（不构建）—ElasticJob 定时任务无否
storageantispam-business-storage无（不构建）—Kafka Consumer无否

kubernetes.yml 中唯一 Deployment 为 antispam-business-facade-dubbo-provider（namespace yidun），且未声明 resources 限额，仅注入 JAVA_OPTS、ENABLE_SKYWALKING 与 SkyWalking OAP 地址。

三、同模块启动顺序 ​

  1. 先启 facade/dubbo-provider —— 它是 Dubbo 注册主体（dubbo.application.id=antispam-business_dubbo-provider，注册到 ZK group /yidun/antispam/online-new/yidun-antispam-dubbo），也是配置写入与 OperateEvent 产生者；下游与 http-api 的增量数据都源于它写的 business_op_record。
  2. 后启 facade/http-api —— 读侧，BusinessCacheManager 直读同一个 DB 全量构建缓存，进程上不依赖 dubbo-provider，但逻辑上以 dubbo-provider 作为配置写/推源，且拉起最重。

四、逐服务启动逻辑 ​

facade/dubbo-provider ​

  • 启动类：com.netease.is.antispam.business.facade.dubbo.DubboApplication（facade/dubbo-provider/src/main/java/com/netease/is/antispam/business/facade/dubbo/DubboApplication.java）
  • @SpringBootApplication：无 exclude
  • @Enable* 注解：@EnableAspectJAutoProxy(exposeProxy = true)、@EnableTransactionManagement、@EnableApolloConfig、@EnableBusinessClient、@EnableConfigurationProperties({BusinessDynamicConfig, BusinessCacheProperties})
  • @EnableBusinessClient → @Import(BusinessClientConfiguration)：按 business.client.options.zookeeper.address 条件装配 BusinessZookeeperClient（@Bean(destroyMethod="destroy")，构造后 init() + start()），并把容器内所有 Listener<?> 注册进 BusinessEventBus；仅当存在 business.client.options.remote.address 时才建 BusinessHttpClient
  • DubboFacadeConfiguration（同包配置类）：@ComponentScan({"...business.service", "...business.manager", "...business.proxy", "...business.component"}) + @MapperScan("com.netease.is.antispam.business.dao")；另 @Bean(destroyMethod="close") CuratorFramework curatorFramework() 带 @ConditionalOnProperty("zookeeper.server.url")（private 下该键被注释 → Bean 不创建）
  • main()：仅 SpringApplication.run(...)，无自定义逻辑
  • 启动钩子：未发现（无 @PostConstruct / ApplicationListener / ApplicationRunner / SmartLifecycle）

facade/http-api ​

  • 启动类：com.netease.is.antispam.business.facade.http.HttpApplication（facade/http-api/src/main/java/.../HttpApplication.java）
  • @SpringBootApplication：无 exclude；仅 @EnableConfigurationProperties({BusinessCacheProperties})；无 @EnableApolloConfig、无 @EnableBusinessClient（源码里 import 了 EnableBusinessClient 但注解未使用）
  • HttpFacadeConfiguration（同包配置类）：@ComponentScan({"...business.service", "...business.component.converter", "...business.manager"}) + @MapperScan("...business.dao")；注册 @Bean AsyncComponent（异步线程池）、@Bean Validator（HibernateValidator，hibernate.validator.fail_fast=true）、@Bean QpsExcludeComponent
  • main()：run 之后执行 ServiceStatus.setStatus(ServiceStatus.STARTED)（供健康检查读）
  • 启动钩子：BusinessCacheManager.@PostConstruct init() 是启动期最重一步——按 OperateTargetType.ordinal() 排序后逐个 businessCache.init(true) 全量加载并放入 businessCacheMap，随后建 ScheduledThreadPoolExecutor(2, "business-cache-loader")（守护线程）周期执行 refresh() 与 validate()；@PreDestroy destroy() 关线程池并销毁各缓存。DB 不可达会直接导致启动失败
  • 其它：HealthCheckApi 整类被注释，故该服务对外健康语义弱

console/api、scheduler、storage（有启动类，不构建） ​

  • com.netease.is.antispam.business.console.api.ConsoleApplication：控制台后端骨架，含 ConsoleConfiguration/SwaggerConfiguration，通过 Dubbo 调业务服务；无 Dockerfile。
  • com.netease.is.antispam.business.scheduler.SchedulerApplication：ElasticJob 定时任务（配 SchedulerConfiguration），无 Dockerfile。
  • com.netease.is.antispam.business.storage.StorageApplication：Kafka 消费者，把配置变更事件落地（StorageConfiguration + 内置 YidunQosApplication），无 Dockerfile。
  • 三者 @SpringBootApplication 均无 exclude；启动钩子未逐一核对（因不构建部署，未纳入启动顺序）。

五、启动前置依赖 ​

依赖配置键 / 地址阻塞 or 弱依赖配置文件
MySQL/TiDBspring.datasource.url=jdbc:mysql://tidb-cluster0-tidb.tidb.svc:4000/antispam阻塞（两个单元都强依赖）application-private.properties
ZK — Dubbo 注册中心dubbo.registries.antispam.address=zookeeper://zk-0.zookeeper.yidun-infra:2181?backup=...，group /yidun/antispam/online-new/yidun-antispam-dubbo阻塞（dubbo-provider）application-private.properties
ZK — business.clientbusiness.client.options.zookeeper.address=zk-0/1/2.zookeeper.yidun-infra:2181，rootPath /netease-antispam/online/config阻塞（dubbo-provider 建 ZK 客户端）application-private.properties
Apolloapollo.meta=http://yd-apollo-config.nistest.netease.com，app.id=antispam-business_dubbo，apollo.bootstrap.namespaces=application,application.yml弱（仅 dubbo-provider，拉不到走本地 cache）application.properties（dubbo-provider）
Kafka Producerspring.kafka.bootstrap-servers=kafka-yidun-0/1/2...-headless.yidun-infra:9092弱application-private.properties
Redis（Sentinel）spring.redis.sentinel.master=master01，spring.redis.sentinel.nodes=redis0-redis-ha.yidun-infra.svc:26379弱application-private.properties
curator（可选 ZK）zookeeper.server.urlprivate 未启用（键被注释）application-private.properties（注释行）

六、启动参数与 Profile ​

  • -Dspring.profiles.active：base 默认 dev；仓库含 dev/test/private/online/jiande-online/jiande-pre 等；容器统一 private（Dockerfile ENV 与 k8s env 均写 private）
  • maven profile：本仓库根 pom.xml 未自定义 profile，-P private 由父/平台 POM 提供；facade/http-api/build.sh 额外叠加 arch_x86（BUILD_ENV=private,arch_x86）
  • JAVA_OPTS：Dockerfile -Xmx512m -Xms512m -XX:+UseG1GC -Dspring.profiles.active=private；k8s 覆写为 -Xmx1024m -Xms1024m -XX:+UseG1GC ...（未配 resources，堆上限即容器实际内存需求）
  • base image 与镜像仓库：private-registry.yidun.internal/yidun/base-image:jdk17；产出镜像 private-registry.yidun.internal/yidun/antispam-business-{dubbo-provider,http-api}:migu-231016
  • build.sh 关键参数：MODEL_NAME=facade/dubbo-provider|facade/http-api、BUILD_ENV=private、DOCKER_REPOSITORY=private-registry.yidun.internal/yidun、DOCKER_IMAGE_TAG=migu-231016、sudo docker build（非 buildx，仅 amd64），可用 -e/-r/-t/-c/-p 覆盖；buildAll.sh 固定 GLOBAL_ENV=private，遍历 find . -name build.sh 逐个执行（-c false -p false）

七、启动期踩坑 ​

  1. curator Bean 静默缺失：DubboFacadeConfiguration.curatorFramework() 带 @ConditionalOnProperty("zookeeper.server.url")，而 application-private.properties 中该键被注释 → private 环境不创建 CuratorFramework，依赖它的回写链路缺失时不会报错，只会在使用时报 NPE。
  2. business.client.options.server=true 误配：http-api/application.properties 写了 business.client.options.server=true；若同时补上 business.client.options.zookeeper.address，BusinessClientConfiguration 会额外创建一个 ZK 客户端（该 Bean 条件为 @ConditionalOnMissingBean(BusinessClient.class)）。
  3. BusinessCacheManager 同步全量加载：@PostConstruct 内按 ordinal() 串行 init(true) 全部缓存，数据量大时启动耗时长；DB 慢/不可达直接启动失败（无降级）。
  4. Apollo namespace 未建则拉空：dubbo-provider app.id=antispam-business_dubbo、namespaces application,application.yml，apollo.cache-dir=./apollo/cache；namespace 不存在时配置为空却不报错。
  5. 三个单元永不被构建：buildAll.sh 只遍历 build.sh，而 console/api、scheduler、storage 均无 build.sh/Dockerfile —— 有启动类 ≠ 会被打包。
  6. http-api 走 Undertow 且线程数极端：base server.undertow.worker-threads=2、io-threads=1，private 才覆写 worker-threads=600；漏配 private 会表现为严重并发瓶颈。
  7. dubbo-provider dubbo.protocol.port=-1：随机端口，消费者必须走 ZK 注册发现，直连不可用。
  8. 相对路径缓存目录：apollo.cache-dir=./apollo/cache、http-api business.cache.storage.path=./rocksdb_data（private 设 business.cache.load-from-storage=false），容器工作目录必须可写。
  9. 启动即全量从 DB 加载：private 把 business.cache.load-from-storage=false，意味着每次重启都跳过本地存储快照、直接从 MySQL 全量加载，大库场景重启耗时与 DB 压力成正比。
  10. netease.kafka.producer.enable=true 是默认值：application.properties 打开生产者，Kafka 不可用时启动不失败但配置变更事件会发送失败并写错误日志，排查“配置改了没生效”时要一并看这里。
  11. Hikari 连接池只有 10：两个单元都是 spring.datasource.hikari.maximum-pool-size=10，而 http-api 启动期要做全量加载、dubbo-provider 要并发写，池偏小易成瓶颈（无报错，只变慢）。
  12. 多环境共用同一 ZK group：dubbo-provider 注册 group 固定为 /yidun/antispam/online-new/yidun-antispam-dubbo，private 与 online 若共用同一 ZK 集群会互相可见，需确认 ZK 实例隔离。
  13. dubbo.consumer.timeout=30000（30s）：dubbo-provider 消费端超时较长，下游不可用时会长时间挂住调用线程。

八、跨模块前置 ​

  • 本模块是配置源，启动前不依赖任何其它业务模块 —— 无硬依赖。
  • 仅需就绪的基础设施：MySQL/TiDB（阻塞）、Zookeeper（阻塞，dubbo-provider）、Apollo（弱）、Kafka（弱）、Redis（弱）。
  • 上游写入方（antispam-cms、netease-antispam）是运行期调用方，不是本模块的启动前置。
  • 反向约束：下游约 20 个模块（antispam-business-*、netease-antispam、antispam-cms、antispam-bill 等）把本模块视为跨模块前置，其 ZK 配置源 /netease-antispam/online/config 就由本模块写入。
  • 与 antispam-business-* 系列模块的关系是“被复用配置”而非依赖：本模块启动不等待它们。

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

内部技术文档 · 请勿外传

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