IPTV on 方糖猫Blog

C 端 IPTV 产品的 Java 高并发架构设计：高可用、高性能、零信任与缓存一致性

Mon, 19 Oct 2026 10:00:00 +0800

C 端 IPTV 产品的 Java 高并发架构设计：高可用、高性能、零信任与缓存一致性

过去几年我一直在做一个面向海外的 C 端 IPTV 产品（STB 机顶盒 + 移动端，多品牌多租户，跑在 AWS 上）。这篇文章是我对这套系统架构的复盘：高并发、高可用、高性能、高安全、缓存一致性这几件事我们分别是怎么做的、踩过什么坑。过程中我们落地了不少 Netflix 的开源组件和公开实践（Hystrix、EVCache、Zuul 的网关思想、混沌工程等），但每一个决策都是经过我们自己生产环境验证或修正的，不是照搬。文中方案细节来自真实的系统设计文档（Video Cloud 目标模型、vod-auth、CloudRouter、DRM、网盘整改等），脱敏后分享。

一、先搞清楚对手：C 端 IPTV 的流量模型

设计之前先看清流量的形状。这是我做这套系统第一天就逼自己回答的问题：

特征	说明	架构含义
潮汐效应极强	晚 8 点 - 11 点是高峰，大促、球赛、爆款剧上线时流量成倍脉冲	弹性伸缩 + 削峰，按高峰容量做预案
读极多、写极少	EPG 节目单、Meta 元数据、Layout 下发占了 9 成以上流量	缓存优先，读路径尽量不打 DB
播放鉴权是超级热点	每次起播、切台都要鉴权取播放链接，QPS 随在线用户数线性涨	热点接口单独优化（缓存 + 短 TTL + 滑动续期）
设备在线心跳	app 轮询 session，百万级设备定时上报	心跳服务独立部署，写路径异步化
多品牌多租户	同一套系统服务多个品牌（巴西、俄语区等）	分库隔离爆炸半径，account_id 前缀区分品牌

这个流量形状——读多写少、晚间高峰、播放路径是生命线——决定了后面所有的架构取舍。

二、总体架构：一张图看清全貌

graph TB
    subgraph 终端
        STB["STB 机顶盒"]
        APP["移动 App"]
        WEB["Web / Portal"]
    end

    subgraph 接入层
        ELB["AWS ELB"]
        APISIX["APISIX 网关<br/>限流 Sentinel / WAF / 鉴权前置"]
    end

    subgraph 微服务层
        AUTH["vod-auth<br/>登录注册 / 账号 / 子账号"]
        SESS["common-session<br/>会话管理"]
        META["vod-meta-api<br/>元数据 / Layout / EPG"]
        PROF["profile<br/>观看历史 / 收藏 / 偏好"]
        CLOUD["vod-cloud<br/>个人网盘"]
        ROUTER["CloudRouter<br/>播放链接路由"]
        DRM["drmlicense<br/>DRM 鉴权与 license 下发"]
    end

    subgraph 数据层
        MYSQL["MySQL RDS<br/>按品牌分库"]
        REDIS["Redis Cluster<br/>Session / 验证码 / Meta 缓存"]
        METAREDIS["Meta 专用 Redis Cluster"]
        ES["Elasticsearch<br/>检索字段"]
        KAFKA["Kafka MSK<br/>Meta 同步 / 网盘同步"]
    end

    subgraph 内容侧
        STREAM["Streaming 流媒体"]
        CDN["CDN / Squid 边缘缓存"]
        CP["cloudProxy<br/>第三方网盘适配"]
    end

    STB --> ELB
    APP --> ELB
    WEB --> ELB
    ELB --> APISIX
    APISIX --> AUTH
    APISIX --> SESS
    APISIX --> META
    APISIX --> PROF
    APISIX --> CLOUD
    APISIX --> ROUTER
    ROUTER --> DRM
    ROUTER --> STREAM
    STREAM --> CDN
    STREAM --> CP
    META --> METAREDIS
    META --> ES
    AUTH --> MYSQL
    AUTH --> REDIS
    SESS --> REDIS
    CLOUD --> KAFKA
    META --> KAFKA

几个关键决策，后面逐章展开：

接入层：链路是 app -> ELB -> APISIX -> vod 微服务，限流用 Sentinel，网关做鉴权前置和 WAF。网关选型时我认真研究过 Netflix Zuul 2 从同步阻塞改异步非阻塞的历程——结论是网关本身绝不能成为瓶颈。我们体量没那么大，APISIX（底层同样是 Nginx + Lua 的高性能异步模型）已经够用。
服务拆分：按业务域拆（Auth / Profile / Meta / Cloud / Session），不是按技术层拆。领域拆分的完整过程在视频系统 DDD 实战里写过。
数据层：MySQL 按品牌分库（{brand}_account_db 等）；Redis 承载 Session、验证码、热点数据；Meta 用独立的 Redis Cluster 全量缓存，与业务缓存物理隔离；检索字段入 ES。
异步化：Kafka（MSK）只干两件事——Meta 同步管道和网盘同步，不滥用。这是我给自己立的规矩：每加一个 MQ topic 都要回答「同步调用为什么不行」。

三、高并发：把流量挡在离用户最近的地方

高并发的核心心法就一句：每一层都尽量把请求消化掉，别让它穿透到下一层。越靠近 DB 越贵。

3.1 网关层：第一道削峰闸

我们在网关层做了三件事：

限流：APISIX 自带 limit-req / limit-count 插件做粗粒度限流，Sentinel 做服务级细粒度熔断限流（现网组合就是「ELK + Skywalking + Sentinel（APISIX）」）。
鉴权前置：明显非法的请求（无 token、签名错误、UA 黑名单）在网关直接 401/403，不放行到业务服务。被攻击时这一层挡掉的流量经常比业务层处理的还多。
静态配置下发走 CDN：/ui/cfg/v1、/layout/v1 这类终端配置接口，内容变化频率低，直接走 CDN 缓存，源站只承担回源请求。

3.2 热点接口：播放鉴权链接的缓存设计

CloudRouter（播放源路由服务）是我手里最热的路径：每次起播都要按 logicStreamId 换真实的下载/播放链接。我做的设计非常直接：

graph LR
    A["App 起播请求<br/>logicStreamId"] --> B{"查 Redis"}
    B -- "命中" --> C["刷新 TTL 滑动续期<br/>直接返回链接"]
    B -- "未命中" --> D["查 MySQL 两表<br/>logic_stream + file_source"]
    D --> E["构建下载链接 DownloadBO<br/>link / fileSize / expired"]
    E --> F["写回 Redis"]
    F --> G["返回"]

三个细节值得说：

命中即续期（滑动 TTL）：热播内容的链接永不过期，冷内容自然淘汰——不需要人工预热。这个设计替我省掉了整个「热点内容运营」的麻烦。
缓存对象自带过期时间：链接本身有 expired 字段，客户端在链接到期前会重新请求，和缓存 TTL 是两层独立的过期机制，互不相信。
失败快速抛出：查不到直接抛业务异常，不做 fallback 到第三方存储的慢路径——播放链路每一毫秒都值钱。

3.3 多级缓存：L1 + L2

纯 Redis 方案在超热点 key 上依然会打满单个分片（新片上线当晚的 metaId 我真实遇到过）。为了解决这个问题我研究了 Netflix 的 EVCache——它的多副本加客户端本地缓存思路给了我启发，但我们体量用不上 EVCache 全套，于是我基于 Caffeine（L1 进程内缓存）+ Redis（L2）自己实现了一个两级缓存框架并开源，见我开发的 keCache：面向 Spring Boot 3 的 L1 + L2 两级缓存框架，要点：

L1 短 TTL（秒级），扛住瞬时洪峰；
L1 失效消息走 Redis Pub/Sub 广播，保证多实例间 L1 不一致的窗口可控；
序列化用 Kryo，比 JDK 序列化小 3-5 倍。

3.4 写路径异步化：MQ 削峰

写少但集中的场景（新片上线批量导入 Meta、网盘大规模刷新）我全部走 Kafka：

graph LR
    A["vod-sync-dispatcher<br/>每 30 秒轮询上游片源"] --> B["Kafka MSK"]
    B --> C["vod-imdb-meta-sync<br/>元数据入 Redis + ES"]
    D["vod-cloud-sync-dispatcher"] --> B
    B --> E["vod-cloud-sync-worker<br/>刷新网盘"]
    F["http2Msk<br/>大数据 HTTP 回调转 MQ"] --> B
    B --> G["偏好计算<br/>you may like"]

生产者-消费者模型 + MQ 缓冲，让上游脉冲（片源方一次推几万条 meta）被摊平成消费者能吃得动的匀速流。当时的 MQ 选型过程见消息队列总结：RabbitMQ、Kafka、RocketMQ 与 Redis MQ。

另一个异步化的例子是我设计的转码调度：Quartz + DB 状态机驱动，每个片源转出 1-3 个分辨率、每个分辨率一个任务，用「动态归一化权重调度算法」分配执行器（priority = 客户权重 / 活跃任务数，兼顾多客户公平与并发槽位控制），30 分钟轮询任务进度。慢不要紧，稳和公平才要紧——这是典型的「离线任务用状态机换可靠性」。

四、高可用：假设一切依赖都会挂

我做高可用的两条心法，是从 Netflix 的工程实践里学来并在我们系统里反复验证过的：Design for failure（为失败而设计）和 Blast radius（控制爆炸半径）。落地到我们系统：

4.1 熔断、降级与兜底重试

熔断：我们早期直接用 Netflix 开源的 Hystrix 做熔断隔离，Hystrix 停更后迁移到 Resilience4j（网关层用 Sentinel）。工具换了，规则不变：下游超时率/错误率超阈值就熔断，快速失败，绝不线程排队等死。Hystrix 的线程池隔离思想对我们影响很大——核心链路（登录、起播）和非核心链路（埋点上报）的资源池必须分开。
降级而非失败：Meta 自动匹配失败时我定的策略是降级创建默认元数据，不影响文件源状态——内容能播永远比信息完美重要。
兜底重试：CloudAsset 的异常处理是我给全系统定的统一模式——3 次以内本轮调度重试，超过 3 次任务进失败状态，由独立的失败任务调度器兜底。关键设计点：主流程不被重试拖死，失败任务有独立通道排队消化，互不阻塞。

graph TB
    A["任务执行"] --> B{"成功?"}
    B -- "是" --> C["完成"]
    B -- "否, failCount+1"] --> D{"failCount ＞ 3?"}
    D -- "否" --> A
    D -- "是" --> E["status = fail"]
    E --> F["独立失败任务调度器<br/>定时扫描兜底重试"]
    F --> A

后来我把这类「一定要跑到」的可靠执行逻辑抽成了通用组件开源，见我开发的 KE Reliable Executor。

4.2 多租户隔离：分库就是隔舱

多品牌共享一套代码，但我在数据层做了物理隔离：

MySQL 按品牌分库（{brand}_account_db、{brand}_profile_db），公共数据在 vod_meta_db；
account_id 前缀区分品牌（MFC:11、TVELA:12、WAKA:13），应用层强制路由；
实体普遍带 env / vnoId 字段，logicStreamId 内嵌环境标识。

某品牌数据被打爆、误删、需要回滚时，影响面天然被限制在单库内。这就是水密隔舱——后来某品牌做数据订正时我真切体会到这个设计的价值。

4.3 依赖解耦：订阅模式

DRM 链路里我有个坚持：drmlicense 不直接依赖 Headend 和 drmencryptor 的在线接口，而是以订阅模式收 DrmContentInfoBO 和 ContentKeyBO，自己组装 logicalStream 与 PSSH 的关系。上游挂了，license 下发用已订阅到的数据照常工作。原因是算术：同步调用是可用性的乘法，异步订阅是加法——一个可用性 99.9% 的服务同步串依赖十个同样 99.9% 的服务，链路可用性就只剩 99% 了。

4.4 混沌工程：轻量版就够

Netflix 的 Chaos Monkey 是随机杀生产实例，逼所有服务习惯「邻居随时消失」。我评估后没敢直接上生产，但保留了这个思想的两个轻量实践：预发环境定期随机关停单个实例观察告警与自愈；每个季度做一次依赖演练（手动切断 Redis 从库、Kafka 单 broker），验证降级路径真的能用。我的原则：降级方案不演练就等于没有——每次演练几乎都能发现某条降级路径已经悄悄失效。

五、高性能：把钱花在读路径上

高性能章节不长，因为大部分事前面已经做了。补几个我做过的针对性的点：

优化点	做法
Meta 全量入内存	元数据全量进专用 Redis Cluster，终端 `/root/v1`、`/tree/v1` 等接口零 DB 访问
检索走 ES	只有关键检索字段入 Elasticsearch，不全量双写
播放内容边缘缓存	Streaming 前置 Squid + CDN，热点片源命中边缘节点，源站只承担回源（对应 Netflix Open Connect 的角色，我们用商用 CDN 实现）
大表治理	观看历史表现网 2-3 亿行，是我一直盯着的最大风险点：每天定时任务删 90 天前历史 + 按账号双表拆分（设备账号/普通账号）
JVM 与连接池	G1/ZGC、HikariCP 连接池按「连接数 = (核数 × 2) + 磁盘数」起步压测调优，慢 SQL 进 Skywalking 告警

原则：性能优化的 80% 是让请求根本到不了慢的地方，剩下 20% 才是调参数。

六、缓存一致性与缓存高可用

这是全文我最想细说的一章。缓存是性能的来源，也是我事故最多的地方。

6.1 一致性策略：先写 DB，后删缓存

vod-auth 的账号数据我用的是标准的 Cache Aside + 写后删除：先写 DB，成功后再删缓存，下次读时回源重建。为什么选「删除」而不是「更新」？我想清楚过：「先写 DB 再删缓存」只有在「读线程恰好踩着写间隙回源了旧值」的极端窗口才会短暂不一致，而「更新缓存」在并发双写下会乱序覆盖出脏数据。删除的失败模式是 miss（回源一次，便宜），更新的失败模式是脏数据（播错内容，贵）。

对一致性要求更高的场景（套餐权益、付费状态），我在删除之上再加一层：

延迟双删：写 DB → 删缓存 → 延迟 N 秒 → 再删一次，兜住间隙回源；
或用 MQ 发缓存失效消息，由消费者负责删除 + 失败重试，把「删缓存失败」这个尾巴也闭环掉。

6.2 缓存三大经典问题的组合拳

问题	我遇到的场景	解法
穿透	恶意刷不存在的 metaId / accountId	布隆过滤器拦截 + 空值短 TTL 缓存（30 秒）
击穿	爆款剧上线，热点 key 过期瞬间	逻辑过期 + 互斥重建：value 里带逻辑过期时间，过期后只放一个线程回源，其余返回旧值
雪崩	大量 key 同 TTL 同时到期	TTL 加随机抖动（基础值 ± 20%）+ Redis Cluster 多主分摊

逻辑过期方案有个工程细节：回源重建要用分布式锁（Meta 绑定我用的就是分布式锁，获取失败快速失败、重新调度），且锁的 TTL 必须大于回源耗时，finally 里释放——我在 CloudAsset 方案里专门写了「任何异常都会释放分布式锁、清除 ThreadLocal」，这是血泪经验，锁泄漏一次就够排查一晚上。

6.3 缓存自身的高可用

Redis Cluster 多主 + 从：Meta 缓存我用独立集群，和 Session/验证码的集群物理隔离——Meta 集群被打挂不影响用户登录。
多级缓存兜底：Redis 整体不可用时，L1（Caffeine）还能扛住读过期窗口，服务降级而不是全灭。
从 EVCache 学到的运营观：我研究 Netflix EVCache 时最大的收获不是 memcached 本身，而是他们把缓存当成 tier-0 服务运营——独立容量规划、独立监控、独立 SLO。我照这个思路给缓存集群配了和业务服务同级别的告警与容量评审。缓存在高并发系统里不是优化项，是一级基础设施——这点很多团队要到出事才懂，我庆幸自己学得早。

七、零信任安全与必要防御

7.1 零信任：永不信任，始终验证

我们的安全体系是在几次整改后逐步按零信任思路重建的——内网不再等于可信，每一次调用都要验证身份，不论它来自哪里。落地到我的系统，是这几件事：

用户侧：accessToken（JWT，sub = accountId）+ 播放票据 tk12（内含 expireTime / accountId / streamId，由平台密钥签发）。App 起播时两个都要验，token 验「你是谁」，tk12 验「你能不能播这条流、能播到什么时候」。
设备侧：账号卡与设备绑定（ac_device_binding），device_limit 限制并发设备数，挤掉盗号共享的盈利空间。
服务间：内部接口（/internal-api/...）不走公网网关，服务间调用带服务身份凭证。我评估过 mTLS + SPIFFE 这套工作负载身份方案（Netflix 零信任改造用的就是这条路），对我们体量偏重，最终落地为「内部接口不暴露 + 调用方白名单」，等规模上来再升级。
最小权限：cloudProxy 是我专门做的收敛层——把对第三方网盘（Mega 等）的所有访问收敛成一个适配层，只暴露 checkPassword 和 getDownloadLink 两个接口，业务服务根本不接触第三方凭证。

7.2 一次真实的安全整改：网盘密码泄露

这是我亲手推动的整改，值得完整复盘。背景：网盘打包工具生成的加密网盘包里含账号 + 加密后的登录密码，加解密密钥一旦泄露，所有网盘账号密码全部泄露。

整改分两步走：

第一步，密码不落地。 新网盘包不再写密码，改为写入与网盘账号一一对应的 shareKey（UUID）。导入时只校验 shareKey 一致性，通过后把网盘与用户关联。按网盘包 version 字段区分新老包走新旧两条校验逻辑，平滑迁移——存量兼容是安全改造里最容易被低估的工作量，这一步我花的精力比新逻辑本身还多。

第二步，密钥体系升级。 对称加密改 RSA 非对称加密：

graph TB
    A["CP / Reseller<br/>只拿到 RSA 公钥"] --> B["公钥加密网盘包<br/>公钥泄露也无法解包"]
    C["VNO 上传私钥<br/>加密保存于平台 pkg_rsa_key 表"] --> D["导入时按 VNO 查私钥"]
    B --> E["网盘包带签名<br/>含 pkgId + keyId"]
    E --> D
    D --> F["先验签再解密<br/>解密成功才关联用户"]

配套我设计的密钥轮换机制：平台同时最多两个 Key 生效；更新时旧密钥先进入最长 30 天缓冲期，再生成新密钥对；存在生效中的旧密钥则不允许再次更新——防止轮换频率失控导致历史包无法解密。

另外扫码登录链路我也推动做过同类加固：扫码站点从 S3 静态托管（明文登录）迁移到托管服务并接入加固方案，鉴权统一收口到 vod-auth。

7.3 接口消息体加密：HTTPS 之上的第二道锁

有人会问：全站都上 HTTPS 了，为什么还要在应用层再加密一次消息体？我的理由有三个，都来自实际教训：

HTTPS 防不住终端侧的抓包。Charles/Fiddler 挂个代理证书，App 和网关之间的明文报文一览无余——协议字段、业务参数、token 用法全暴露。C 端 App 发出去的那一刻起，客户端环境就不可信。
HTTPS 到网关就终止了。TLS 在 ELB/APISIX 卸载后，内网转发的是明文；零信任的原则是内网也不可信，敏感报文在网关之后依然应该处于加密状态。
IPTV 场景的特殊性：播放鉴权、充值、账号接口一旦被逆向出报文格式，黑产就可以脱离 App 直接伪造请求刷接口。

我设计的方案是 TLS 为底线 + 应用层 AES 加密消息体，核心链路如下：

graph LR
    A["App 启动<br/>ECDH 密钥协商<br/>网关公钥经 SSL Pinning 校验"] --> B["得到会话密钥 sessionKey<br/>按 session 绑定"]
    B --> C["业务请求<br/>AES-256-GCM 加密 body"]
    C --> D["明文头带 token + 时间戳<br/>+ nonce + HMAC 签名"]
    D --> E["网关统一解密过滤器<br/>验签名 / 验时间窗 / 验 nonce"]
    E --> F["业务服务收到明文<br/>响应同样加密回传"]

工程上的几个取舍，都是试出来的：

密钥协商用 ECDH，不用硬编码密钥。早期图省事在 App 里内置过 AES 密钥，App 被反编译后全线失守，改成登录/启动时 ECDH 动态协商、密钥绑定 session、服务端定期强制轮换。SSL Pinning（证书固定）挡住大部分中间人代理，让 ECDH 协商本身不被劫持。
AES-256-GCM 而不是 CBC：GCM 自带完整性校验（AEAD），加密和防篡改一次完成；密钥 nonce 绝不复用。
头部明文、body 加密：token、时间戳、nonce、签名放明文头里，网关不解密就能先做限流和鉴权前置；body 整体加密，解密收敛在网关的统一过滤器里，业务服务无感知——加解密逻辑散落进每个 Controller 是维护灾难。
不是所有接口都加密。EPG、Meta 这类公开内容接口只走 HTTPS + 签名；登录、充值、播放鉴权、账号操作这些敏感接口才上消息体加密。全量加密的 CPU 成本和排查问题的痛苦不成比例——加密后的日志排障要靠专门的脱密工具，这也是成本。
绝不自研算法。所有原语都用成熟实现（AES-GCM、ECDH、HMAC-SHA256），自己拼协议可以，自己造算法不行。

7.4 必要防御：防攻击清单

攻击面	我们的防御手段
接口刷量 / CC 攻击	网关限流 + Sentinel 熔断；登录、验证码接口按 IP + 账号双维度计数
短信/邮件轰炸机	验证码存 Redis 带 TTL，验证成功后立即删除防重放；单账号/单 IP 频次限制
重放攻击	请求带时间戳 + nonce，token 短过期
抓包 / 中间人	HTTPS + SSL Pinning + 敏感接口消息体加密（见 7.3）
越权访问	tk12 绑定 `accountId + streamId`，换账号播放直接鉴权失败
篡改网盘包	RSA 签名验签，验签不过不解密
撞库 / 盗号	登录失败计数锁定（`account_black_list`）、设备绑定、子账号体系隔离
敏感信息外泄	交接文档脱敏（我们的交接文档里曾出现明文环境密码，是我抓出来的典型反面教材）；日志脱敏；DB 密码字段只存哈希

7.5 DRM：内容安全的最后一道门

DRM 链路的安全设计我同样按零信任思路做：ContentKey 由独立密钥服务（drmencryptor）管理，先查缓存没有再向外部 DRM 厂商申请并落库缓存；播放优先走离线 license（有缓存用缓存），PSSH 异常才降级在线 license。license 本身带过期时间，App 本地不持久化密钥。系统支持 Goose DRM 与 Multi-DRM（Widevine）切换，切换动作就是删旧流加新流——密钥体系与业务流解耦，这个设计让后来的 DRM 厂商迁移几乎没动业务代码。

八、可观测性：没有度量就没有高可用

我们的现网组合：ELK 日志 + Skywalking 链路追踪 + Prometheus/Grafana 指标 + Nacos 配置中心，每个子系统独立 ES index。

我压测过的容量数据（v7.16 集群）：只写日志约 11 万条/秒，只写 Skywalking 约 2 万条/秒，混合写时日志 6 万 + 链路 1 万/秒。

血泪教训：周一高峰 Skywalking 曾出现 4 小时写入延迟，日志量增长也让 Logstash 排队。事后我立了两条规矩：

日志与链路采样分离：高峰期链路数据降采样，保住日志；两者绝不能互相拖死。
本地日志保留 30 天，crontab 定时清理——磁盘写满导致的 ELK 雪崩比业务故障还常见。

我还坚持一点：告警要打在用户可感知的指标上（起播成功率、鉴权失败率、链接过期率），而不是只打 CPU 内存——机器好好的但用户看不了，是最尴尬的监控盲区。服务间的依赖关系复杂到一定程度后，「告警来了不知道谁影响了谁」会成为新问题，Netflix 为此专门做过一套服务拓扑系统，我研究过它的实现并整理了笔记：Netflix 服务拓扑系统笔记。

九、总结：一张 checklist

维度	我采用的核心手段	用到的 Netflix 开源组件 / 实践
高并发	网关限流、缓存优先、MQ 削峰、多级缓存	Zuul 2 异步化思想、EVCache 启发 keCache
高可用	熔断降级、失败兜底调度器、多租户分库隔离、订阅模式解耦	Hystrix（后迁 Resilience4j/Sentinel）、Chaos Monkey 轻量版
高性能	Meta 全量入内存、ES 检索、CDN/Squid 边缘缓存、大表治理	Open Connect 的边缘缓存角色
缓存一致性	先写 DB 后删缓存 + 延迟双删、逻辑过期防击穿、随机 TTL 防雪崩	EVCache 的缓存运营观
零信任	双票据鉴权、设备绑定、内部接口白名单、最小权限适配层	零信任改造思路（mTLS/SPIFFE 评估后暂缓）
攻击防御	网关 WAF/限流、验证码防重放、RSA 验签、黑名单、敏感接口消息体加密	—
可观测	ELK + Skywalking + Prometheus，日志链路采样分离	服务拓扑系统的思路

最后一句实话：这套架构没有一样是发明出来的，全部是踩坑踩出来的。网盘密码泄露、Skywalking 四小时延迟、2-3 亿行的历史大表——每个设计决策背后都有一次事故或一次险些事故。Netflix 的开源组件和博客帮我少踩了很多坑，但终究要自己踩过才知道坑有多深。架构师的职责不是画出完美的图，而是让每个坑只踩一次。

视频系统 DDD 实战：巴西 IPTV 项目的领域拆分

Fri, 23 Aug 2024 17:00:00 +0800

视频系统 DDD 实战：巴西 IPTV 项目的领域拆分

2021 年到 2025 年，我负责面向巴西市场的 IPTV 视频点播系统。这是一个用户量过百万、业务持续演进的系统。在几次大的产品迭代中，我们引入了领域驱动设计（DDD）来控制系统复杂度。这篇文章会完整复盘当时的领域拆分过程。

一、项目背景

系统核心功能：

视频上传：支持 tus / FTP / 网盘 / m3u8 等多种来源
视频转码：h264 / h265 多码率输出
DRM 加密：永新 / 自研加密方案
元数据管理：同步 IMDb / TMDB / PP 等外部数据源
播放列表：专题、分类、推荐
播放鉴权：用户权限、设备管理、防盗链

服务用户：200 万+，峰值日活 40 万。

二、为什么需要 DDD？

2.1 早期的问题

系统最初是一个单体应用，模块按技术分层组织：

controller/
service/
dao/
entity/

这种结构在业务简单时没问题，但随着功能增加，开始出现：

一个需求改动涉及多个「层」，改哪里不确定
业务逻辑散落在 Service 中，相似功能重复实现
转码、鉴权、元数据互相耦合，改一个模块影响多个模块
新成员上手慢，需要全局理解才敢改代码

2.2 DDD 带来的改变

DDD 不是银弹，但它帮我们做了两件事：

按业务边界组织代码，而不是按技术分层
显式定义领域概念，让业务逻辑有明确的归属

三、领域划分

3.1 核心域识别

我们先识别出系统的核心业务域：

flowchart TD
    content["内容域 (Content)<br/>媒资管理、视频文件、转码任务、DRM 加密"]
    metadata["元数据域 (Metadata)<br/>影片信息、演员、分类、标签、外部数据源同步"]
    playback["播放域 (Playback)<br/>播放鉴权、播放地址生成、防盗链、码率适配"]
    user["用户域 (User)<br/>用户账户、订阅、设备、播放历史"]
    recommendation["推荐域 (Recommendation)<br/>播放列表、专题、个性化推荐"]
    billing["计费域 (Billing)<br/>套餐、订单、支付、用量统计"]
    content --- metadata --- playback --- user --- recommendation --- billing

3.2 域间关系

flowchart LR
    playback["播放域"] -- 依赖 --> content["内容域"]
    playback -- 依赖 --> user["用户域"]
    recommendation["推荐域"] -- 依赖 --> metadata["元数据域"]
    recommendation -- "依赖（获取热门数据）" --> playback
    billing["计费域"] -- 依赖 --> user
    metadata -- 依赖 --> external["外部数据源"]

依赖方向尽量保持单向，避免循环依赖。

四、内容域详细设计

内容域是最复杂的域之一，我们以它为例展开。

4.1 聚合根设计

flowchart TD
    root["MediaAsset（媒资聚合根）"]
    file["MediaFile（视频文件）"]
    raw["原始文件"]
    transcoded["转码后文件（多码率）"]
    drmfile["DRM 加密文件"]
    job["TranscodingJob（转码任务）"]
    license["DrmLicense（DRM 许可证信息）"]
    root --> file
    file --> raw
    file --> transcoded
    file --> drmfile
    root --> job
    root --> license

MediaAsset 是聚合根，外部系统只能通过它访问内部实体。

4.2 关键领域事件

内容域会产生大量领域事件，其他域可以订阅：

事件	含义	订阅方
`MediaAssetUploaded`	媒资上传完成	转码服务
`TranscodingCompleted`	转码完成	内容域自身、播放域
`DrmEncryptionCompleted`	DRM 加密完成	播放域
`MetadataSynced`	元数据同步完成	推荐域
`MediaAssetPublished`	媒资发布上线	推荐域、搜索服务

4.3 状态流转

媒资从上传到发布的状态机：

flowchart TD
    UPLOADED --> PENDING_TRANSCODE --> TRANSCODING --> PENDING_DRM --> DRM_ENCRYPTED --> PENDING_METADATA --> METADATA_READY --> FINAL["PUBLISHED / REJECTED"]

每个状态变更都通过领域事件触发下一步操作。

五、分层架构

每个领域内部采用 DDD 经典四层架构：

flowchart TD
    ui["用户接口层<br/>REST Controller / DTO"]
    app["应用层<br/>Application Service / 用例编排"]
    domain["领域层<br/>Entity / Value Object / Domain Service / Repository Interface / Domain Event"]
    infra["基础设施层<br/>Repository Impl / MQ Client / External API Client / DB / Cache"]
    ui --- app --- domain --- infra

5.1 领域层示例

public class MediaAsset {
    private MediaAssetId id;
    private String title;
    private MediaStatus status;
    private List<MediaFile> files;
    private List<TranscodingJob> transcodingJobs;

    public void upload(MediaFile file) {
        this.files.add(file);
        this.status = MediaStatus.UPLOADED;
        registerEvent(new MediaAssetUploadedEvent(this.id));
    }

    public void completeTranscoding(TranscodingJob job) {
        this.transcodingJobs.add(job);
        this.status = MediaStatus.TRANSCODING_COMPLETED;
        registerEvent(new TranscodingCompletedEvent(this.id, job.getOutputFiles()));
    }
}

5.2 防腐层设计

与外部系统（IMDb / TMDB / PP）对接时，使用防腐层（Anti-Corruption Layer）：

public interface MetadataSourceClient {
    ExternalMetadata fetch(String externalId);
}

// IMDb 适配器
public class ImdbClientAdapter implements MetadataSourceClient {
    private final ImdbApiClient imdbClient;

    @Override
    public ExternalMetadata fetch(String externalId) {
        ImdbResponse response = imdbClient.fetch(externalId);
        return MetadataConverter.fromImdb(response);
    }
}

这样外部 API 的数据结构变化不会直接影响到我们内部的元数据模型。

六、微服务拆分过程

6.1 第一次拆分：按技术边界

早期我们按技术栈拆：

upload-service
transcoding-service
metadata-service
playback-service

结果导致一个业务操作要跨多个服务，分布式事务复杂。

6.2 第二次拆分：按领域边界

调整后按 DDD 领域拆分：

content-service（内容域）
metadata-service（元数据域）
playback-service（播放域）
user-service（用户域）
recommendation-service（推荐域）
billing-service（计费域）

每个服务有清晰的业务边界和聚合根。

6.3 服务间通信

场景	通信方式	说明
领域事件传播	RocketMQ	异步、最终一致
同步查询	HTTP / gRPC	强一致查询
配置/字典数据	Redis 缓存	高频读取

七、领域事件实现

7.1 事件定义

public class TranscodingCompletedEvent extends DomainEvent {
    private final MediaAssetId mediaAssetId;
    private final List<FileUrl> outputFiles;
    private final Instant completedAt;
}

7.2 事件发布

领域层只负责注册事件，应用层统一发布：

@Transactional
public void handleTranscodingCallback(TranscodingJobId jobId, List<FileUrl> outputs) {
    MediaAsset asset = mediaAssetRepository.findByJobId(jobId);
    asset.completeTranscoding(new TranscodingJob(jobId, outputs));

    mediaAssetRepository.save(asset);
    eventPublisher.publish(asset.getDomainEvents());
    asset.clearDomainEvents();
}

7.3 事件消费

@Component
public class PlaybackEventListener {

    @RocketMQMessageListener(topic = "content-events", selectorExpression = "TranscodingCompleted")
    public class Listener implements RocketMQListener<TranscodingCompletedEvent> {
        @Override
        public void onMessage(TranscodingCompletedEvent event) {
            playbackService.preparePlayUrls(event.getMediaAssetId(), event.getOutputFiles());
        }
    }
}

八、几次关键演进

8.1 从单体到领域化单体

第一步不是拆微服务，而是先在单体内部按领域组织代码包：

com.ftmao.iptv.content
com.ftmao.iptv.metadata
com.ftmao.iptv.playback

这样可以在不引入分布式复杂度的前提下，先验证领域划分是否合理。

8.2 从同步调用到事件驱动

转码完成后，原本播放域通过接口轮询内容域查询状态。后来改为内容域发布 TranscodingCompleted 事件，播放域订阅。

收益：

内容域和播放域解耦
新增订阅方不需要改内容域
系统扩展性更好

8.3 引入 CQRS 处理播放查询

播放接口对性能要求很高，我们单独做了读模型：

写模型：MediaAsset 聚合根
读模型：Redis 中的播放信息缓存

当内容发布或更新时，通过事件同步更新读模型。

九、踩过的坑

9.1 领域划分过细

早期我们划分了 10 多个领域，导致服务数量爆炸，运维成本剧增。

教训：领域数量要匹配团队规模。小团队 4-6 个领域足够。

9.2 领域事件丢失

消息队列配置不当，出现过领域事件丢失，导致播放域看不到新发布的内容。

教训：关键领域事件必须持久化，支持重放和补偿。

9.3 贫血领域模型

很多「DDD」项目最后变成了 Transaction Script 套壳，实体只有 getter/setter。

教训：要把业务规则和状态变更放在领域对象里，而不是 Service 里。

9.4 过度设计聚合根

一开始想把所有内容相关的东西都放到 MediaAsset 聚合根里，结果聚合根过大，事务边界混乱。

教训：聚合根要小而聚焦，跨聚合用领域事件协作。

十、效果与反思

10.1 量化效果

指标	优化前	优化后
新需求平均改动文件数	40 个	20 个
线上因耦合导致的 Bug	10 次/月	2 次/月
新成员独立上手时间	3 周	1 周

10.2 核心反思

DDD 不是先拆分微服务，而是先拆清楚业务边界。微服务是结果，不是起点。
领域事件是域间协作的核心，但事件丢失和顺序问题必须重视。
不要追求完美的领域模型，先有一个可用的模型，再迭代优化。
DDD 需要团队共识，不是架构师一个人画几张图就行的。

十一、总结

巴西 IPTV 项目让我对 DDD 有了真实的体感。它不是教科书上的概念，而是解决复杂业务系统演化问题的工程方法。

对于视频系统这类业务复杂、流程长、多团队协作的系统，DDD 能带来的最大价值是：

让每个业务概念都有清晰的归属
让系统变更的影响范围可控
让新成员能更快理解业务

如果你也在做 DDD 实践，欢迎在评论区交流领域划分和事件驱动的经验。

从Redis核心原理到 IPTV 视频项目落地

Tue, 28 Sep 2021 10:00:00 +0800

从Redis核心原理到 IPTV 视频项目落地

先系统梳理 Redis 的核心原理与面试高频知识点，再结合 IPTV（交互式网络电视）视频业务场景，给出可直接运行的 Demo。最后讨论 Redis 为什么不适合长期存储、常见踩坑点，以及 List / Pub/Sub / Stream 三种消息队列实现。

一、Redis 是什么？一句话定位

Redis（Remote Dictionary Server）是一个开源的、基于内存的高性能键值对数据库，支持多种数据结构、持久化、高可用与分布式扩展。

graph LR
    A[Redis] --> B[内存存储]
    A --> C[数据结构服务器]
    A --> D[单线程命令执行]
    A --> E[IO 多路复用]
    A --> F[持久化 + 高可用]
    B --> G[读写毫秒级]
    C --> H[String/Hash/List/Set/ZSET/Stream/Bitmap/Geo/HyperLogLog]
    F --> I[RDB/AOF/主从/哨兵/Cluster]

与 Memcached 等纯缓存不同，Redis 的核心价值在于丰富的数据结构与原子操作，可以直接在内存中完成排序、计数、限流、去重、队列等复杂逻辑。

二、Redis 为什么快？

面试常问「Redis 为什么快」，通常从四个层面回答：

原因	说明
内存操作	数据存于内存，无需磁盘寻道，访问速度是 SSD 的千倍以上。
单线程命令执行	避免多线程上下文切换、锁竞争，CPU 缓存命中率更高。
IO 多路复用	基于 epoll/kqueue/select 用一个线程处理大量连接。
高效数据结构	String 底层 SDS、ZSET 底层跳表+字典、List 底层 quicklist 等。

graph TB
    subgraph Redis 6/7 线程模型
        M[主线程<br/>命令执行 + IO 多路复用]
        IO[IO 线程池<br/>仅网络读写]
        BG[后台进程<br/>RDB fork / AOF rewrite]
    end
    C1[Client 1] --> M
    C2[Client 2] --> M
    C3[Client 3] --> M
    M <--> IO
    M -.-> BG

注意：Redis 6/7 引入的多线程只用于网络 IO 读写，命令执行依旧是单线程。所以单条慢命令仍会阻塞整个实例。

三、Redis 数据类型与使用场景

3.1 五种基本数据类型

类型	底层结构	典型场景
String	SDS（简单动态字符串）	缓存、计数器、分布式锁、Session
Hash	ziplist / hashtable	对象缓存、用户信息、EPG 节目单
List	quicklist（ziplist + 双向链表）	消息队列、最新 N 条记录
Set	intset / hashtable	去重、共同关注、抽奖
ZSET	ziplist / skiplist + dict	排行榜、延时队列、范围查询

注：表中 ziplist 在 Redis 7 起已被 listpack 替代（动机见 §4.2），配置项改名 *-max-listpack-*，旧名仍兼容。

3.2 三种特殊数据类型

类型	说明	场景
Bitmap	位数组，按位操作	用户签到、在线状态、UV 统计
HyperLogLog	基数估计算法	海量 UV 去重计数，误差约 0.81%
Geo	地理位置坐标	附近的人、POI 搜索

3.3 String：最常用却被低估

String 不仅能存字符串，还能存整数、浮点数、二进制数据。常用命令：

SET key value EX 3600
GET key
INCR view_count
INCRBY view_count 10
SETNX lock:order:123 true EX 30  # 分布式锁核心命令

SDS 的优势（相对 C 字符串）：

O(1) 获取长度。
二进制安全，可存图片、序列化数据。
预分配空间，减少内存重分配次数。
杜绝缓冲区溢出。

3.4 Hash：对象缓存首选

Hash 适合存「一组字段」的对象，比 JSON String 更节省内存、更新更灵活。

HSET user:1001 name "张三" age 30 city "北京"
HGET user:1001 name
HGETALL user:1001
HINCRBY user:1001 age 1

3.5 ZSET：排行榜的王牌

ZSET 底层同时维护「跳表」和「字典」：

跳表（skiplist）：支持 O(log N) 的范围查询和排序。
字典（dict）：支持 O(1) 按 member 查 score。

ZADD hot:tv 1000 "庆余年"
ZADD hot:tv 800 "狂飙"
ZINCRBY hot:tv 50 "狂飙"
ZREVRANGE hot:tv 0 9 WITHSCORES
ZREVRANK hot:tv "狂飙"

3.6 List 与 Stream：队列双雄

List 适合简单队列，Stream 适合生产级消息队列，后面第十四部分会详细对比。

3.7 Bitmap 与 HyperLogLog：海量 UV 统计的利器

Bitmap 为什么能天然去重？

Bitmap 本质是一个超长 bit 数组，每个 bit 只能是 0 或 1。把 user_id 作为偏移量（offset），用户访问一次就把对应位置 1：

天然去重：同一用户重复访问，置的都是同一个 bit，无需额外判断。
极致省内存：1 亿用户只需 1 亿 bit ≈ 12MB；而 Set 存 1 亿个 ID 要占用数 GB。
支持位运算：BITOP AND/OR 可以直接算多日留存（今天访问 AND 昨天也访问）。

SETBIT uv:20210928 10086 1   # 用户 10086 访问
SETBIT uv:20210928 10086 1   # 重复访问，结果不变
BITCOUNT uv:20210928         # 直接得出 UV 数

局限：要求 user_id 是连续整数，ID 稀疏时浪费内存。

HyperLogLog 为什么 12KB 能数一亿？

HyperLogLog 基于概率估计算法：把每个元素 hash 成均匀分布的随机数，观察 hash 值二进制串中前导零的最大个数。

类比抛硬币：想连续抛出 N 次正面，平均要抛 2^N 次。反过来，如果见过最长连续 N 次正面，就估计大约抛了 2^N 次——前导零越多，说明见过的不同元素越多。
单次估计误差大，所以内部用 16384 个分桶（寄存器，每个 6 bit） 分别记录，再取调和平均数消除偶然性，最终误差稳定在 0.81% 左右。
内存恒定 约 12KB，与元素个数无关：统计 1 亿 UV 还是 10 亿 UV 都是 12KB。

PFADD uv:20210928 "user:10086"
PFADD uv:20210928 "user:10086"  # 重复添加不影响计数
PFCOUNT uv:20210928             # 估算 UV

局限：有误差、不可逆（不能取出具体是哪些用户）。

怎么选：

需求	推荐
精确计数、算多日留存（交并集）、ID 是连续整数	Bitmap
只要近似 UV、数据量极大、ID 是任意字符串	HyperLogLog

四、Redis 底层数据结构速览

graph TD
    A[Redis 数据类型] --> B[String]
    A --> C[Hash]
    A --> D[List]
    A --> E[Set]
    A --> F[ZSET]
    B --> G[SDS]
    C --> H[ziplist]
    C --> I[hashtable]
    D --> J[quicklist]
    E --> K[intset]
    E --> L[hashtable]
    F --> M[ziplist]
    F --> N[skiplist + dict]

底层结构	特点
SDS	带长度、预分配、二进制安全。
ziplist	紧凑列表，小数据量时省内存；大数据量时改为 hashtable/skiplist。
listpack	ziplist 的修正版（Redis 7+）：entry 只记自身长度，消灭连锁更新。
quicklist	List 的底层，由多个紧凑块（Redis 7 前是 ziplist，之后是 listpack）节点组成的双向链表。
hashtable	标准哈希表，渐进式 rehash 避免一次性阻塞。
intset	Set 在元素全为整数且数量少时的紧凑实现。
skiplist	多层索引链表，实现 ZSET 的有序范围查询。

下面把 5 种核心结构「画」出来。

4.1 SDS（Simple Dynamic String）

Redis 没有直接用 C 字符串，而是包了 SDS：

flowchart LR
    L["len<br/>已用长度（4B）<br/>= 5"] --- A["alloc<br/>总容量<br/>= 8"] --- F["flags<br/>编码位<br/>= 0"] --- B["buf[]<br/>实际字符/二进制数据<br/>H e l l o \0 ..."]
    N1["O(1) 取长度"] -.-> L
    N2["末尾保留 \0<br/>兼容 C 字符串函数"] -.-> B

len：已用长度，取长度 O(1)。
alloc：分配的总空间；free = alloc - len 可减少内存重分配。
二进制安全：内容中间可以有 \0，长度由 len 决定。
预分配：修改时若 free 足够就不 realloc；不足时按 2 倍或 1MB 上限预分配。

4.2 ziplist（压缩列表）

ziplist 是一块连续内存，把所有 entry 紧凑排列：

flowchart LR
    A["zlbytes<br/>总字节数<br/>4B"] --- B["zltail<br/>尾偏移量<br/>4B"] --- C["zllen<br/>节点数<br/>2B"] --- D["entry1<br/>变长字节"] --- E["entry2<br/>变长字节"] --- F["..."] --- G["zlend<br/>0xFF<br/>1B"]

每个 entry 的内部结构：

flowchart LR
    A["prevlen<br/>前节点长度<br/>1B 或 5B"] --- B["encoding<br/>编码/长度类型<br/>1B 或更多"] --- C["content<br/>实际数据<br/>变长"]

连续内存、无额外指针，所以省内存。
插入/删除需要整体 memmove，因此只用于小数据量。
Hash/List/ZSET 元素少且单元素短时先用 ziplist，超过阈值升级为 hashtable/skiplist。

listpack（Redis 7 的替代者）：ziplist 的致命伤就藏在 prevlen 里——每个 entry 要记录前一个 entry 的长度：前 entry 小于 254 字节时 prevlen 占 1B，达到 254 字节时占 5B。于是一个 entry 从 253 涨到 254 字节，会让后面每个 entry 的 prevlen 从 1B 膨胀到 5B，膨胀又可能触发下一个 entry 继续膨胀——连锁更新，最坏 O(N²)。

listpack 的修法：每个 entry 只记录自己的总长度，且存在 entry 末尾，entry 之间互不引用——改任何一个 entry 都不会波及邻居，连锁更新从根上消失。Redis 7 起 Hash/List/ZSET 的小对象编码全部换成 listpack，配置项同步改名（hash-max-listpack-entries 等，旧的 *-ziplist-* 名仍兼容）。面试回答「ziplist 和 listpack 的区别」，核心就是这一句：ziplist 记前驱长度所以连锁更新，listpack 记自身长度所以免疫。

4.3 quicklist（快速列表）

Redis 3.2 后，List 的底层是 quicklist = 双向链表 + ziplist：

flowchart LR
    H["head"] --> A["ziplist A<br/>[a|b|c]<br/>count=3<br/>sz=..."] <--> B["ziplist B<br/>[d|e|f|g]<br/>count=4<br/>sz=..."] <--> C["..."]
    N["每个节点是一个 ziplist<br/>节点之间用 prev/next 指针连接"] -.-> A

quicklistNode 结构：

flowchart LR
    A["prev<br/>指针"] --- B["next<br/>指针"] --- C["zl<br/>ziplist"] --- D["sz<br/>字节数"] --- E["count<br/>元素个数"] --- F["encoding<br/>是否压缩"]

结合了双向链表「插入删除快」和 ziplist「省内存」的优点。
每个节点只存少量元素，避免单个 ziplist 太大导致 memmove 开销。
Redis 7 起节点从 ziplist 换成 listpack（动机见 §4.2），但 quicklist 的「链表 + 紧凑块」思想不变。

4.4 intset（整数集合）

Set 在元素全为整数且数量少时使用 intset，否则升级为 hashtable：

flowchart LR
    A["encoding<br/>编码类型<br/>2B/4B/8B"] --- B["length<br/>元素个数<br/>4B"] --- C["contents[]<br/>有序整数数组<br/>[1] [3] [5] [7] [9] ..."]

有序数组，支持二分查找 O(log N)。
所有元素用同一 encoding；加入更大范围整数时可能整体升级（如 int16 → int32），升级是 O(N)。
无重复元素（Set 语义）。

4.5 skiplist（跳表）

ZSET 同时维护 skiplist + dict：

skiplist：按 score 排序，支持范围查询 / 排名 O(log N)。
dict：按 member 查 score，O(1)。

普通有序链表只能顺序扫描，跳表加了多层「快速通道」：

flowchart LR
    subgraph L3["level 3"]
        A3["1"] --> B3["9"] --> C3["15"]
    end
    subgraph L2["level 2"]
        A2["1"] --> B2["5"] --> C2["9"] --> D2["13"] --> E2["15"]
    end
    subgraph L1["level 1"]
        A1["1"] --> B1["3"] --> C1["5"] --> D1["7"] --> E1["9"] --> F1["11"] --> G1["13"] --> H1["15"]
    end
    A3 --- A2 --- A1
    B3 --- C2 --- E1
    C3 --- E2 --- H1
    HEAD["头节点"] -.-> A1
    H1 -.-> TAIL["尾节点"]

跳表节点结构：

flowchart LR
    A["member<br/>成员字符串<br/>（sds）"] --- B["score<br/>分数<br/>（double）"] --- C["forward[] 数组<br/>[L1指针， L2指针， L3指针， ...]<br/>最高层数 = 随机 1~32"]

概率平衡：不用像红黑树那样做复杂旋转。
查找 score=11 时，先在高层大步跳跃，再逐层下降，平均 O(log N)。
配合 dict 实现 ZSCORE 的 O(1) 查询。

五、Redis 持久化：RDB 与 AOF

Redis 提供两种持久化方式，各有优劣。

5.1 RDB（Redis Database）

在指定时间间隔内将内存数据集快照写入磁盘。

save 900 1      # 900 秒内至少 1 次修改则触发
save 300 10     # 300 秒内至少 10 次修改则触发
save 60 10000   # 60 秒内至少 10000 次修改则触发

优点：

文件紧凑，适合备份和灾难恢复。
恢复速度快。

缺点：

两次快照之间数据可能丢失。
bgsave 通过 fork() 子进程生成，大数据集时可能阻塞主线程。

5.2 AOF（Append Only File）

将每次写操作命令追加到日志文件。

appendonly yes
appendfsync everysec  # 每秒刷盘一次（推荐）
# appendfsync always  # 每次写都刷盘，最安全但最慢
# appendfsync no      # 由操作系统决定，最快但不安全

优点：

数据安全性更高，默认最多丢失 1 秒数据。

缺点：

文件体积大。
恢复速度慢。
AOF 重写（rewrite）时会占用额外资源。

5.3 混合持久化（Redis 4.0+）

AOF 重写时先写入 RDB 全量数据，再追加增量 AOF，兼顾恢复速度和数据安全。

aof-use-rdb-preamble yes

graph LR
    A[持久化选择] --> B[RDB]
    A --> C[AOF]
    A --> D[混合持久化]
    B --> E[适合备份/快速恢复]
    C --> F[适合低丢失容忍]
    D --> G[生产推荐]

八股重点：Redis 的持久化是「灾难恢复手段」，不是「主存储方案」。

六、过期删除与内存淘汰

6.1 过期删除策略

Redis 对过期 Key 采用两种策略结合：

策略	说明	优点	缺点
惰性删除	访问 Key 时检查是否过期，过期则删除。	CPU 开销小	过期 Key 可能长期占用内存
定期删除	每隔一段时间随机抽查部分 Key 删除。	平衡内存与 CPU	仍可能有漏网之鱼

6.2 内存淘汰策略

当内存达到 maxmemory 时，根据 maxmemory-policy 决定如何淘汰：

策略	说明
`noeviction`	不淘汰，写操作直接报错。
`allkeys-lru`	所有 Key 中淘汰最近最少使用。
`volatile-lru`	只在设置了 TTL 的 Key 中淘汰最近最少使用。
`allkeys-random`	所有 Key 中随机淘汰。
`volatile-random`	只在设置了 TTL 的 Key 中随机淘汰。
`volatile-ttl`	淘汰即将过期的 Key。
`allkeys-lfu`	所有 Key 中淘汰使用频率最低的。
`volatile-lfu`	只在设置了 TTL 的 Key 中淘汰使用频率最低的。

生产建议：

必须设置 maxmemory。
缓存场景推荐 allkeys-lru 或 allkeys-lfu。
有冷热区分时可用 volatile-lru，但必须给 Key 设置 TTL。

七、Redis 高可用架构

7.1 主从复制（Replication）

一主多从，读流量分摊到从节点。

graph LR
    M[Master<br/>写 + 读] -->|全量/增量同步| S1[Slave 1<br/>读]
    M --> S2[Slave 2<br/>读]
    M --> S3[Slave 3<br/>读]

复制过程：

Slave 发送 PSYNC runId offset。
如果 runId 一致且 offset 在复制积压缓冲区中，则增量同步。
否则全量同步：Master 执行 bgsave 生成 RDB，发送给 Slave。

复制延迟问题：

主从异步复制必然存在延迟。
读从库时可能读到旧数据，需要业务容忍或强制走主库。

7.2 哨兵（Sentinel）

实现自动故障转移，解决主节点宕机问题。

graph TB
    subgraph Sentinel 集群
        Se1[Sentinel 1]
        Se2[Sentinel 2]
        Se3[Sentinel 3]
    end
    M[Master] --> S1[Slave 1]
    M --> S2[Slave 2]
    Se1 -->|监控| M
    Se2 -->|监控| M
    Se3 -->|监控| M
    Se1 -.-> Se2
    Se2 -.-> Se3

核心机制：

主观下线（SDOWN）：单个 Sentinel 认为 Master 不可用。
客观下线（ODOWN）：多数 Sentinel 达成一致。
Leader 选举：Sentinel 之间通过 Raft 算法选举出执行故障转移的 Leader。
故障转移：选一个 Slave 提升为 Master，通知其他 Slave 和客户端。

7.3 Cluster 集群

Redis Cluster 采用无中心架构，数据按槽位分布。

graph TB
    subgraph Redis Cluster
        N1[Node 1<br/>0-5460]
        N2[Node 2<br/>5461-10922]
        N3[Node 3<br/>10923-16383]
    end
    N1 <--> N2
    N2 <--> N3
    N1 <--> N3

关键概念：

集群共有 16384 个槽（slot）。
每个 Key 通过 CRC16(key) % 16384 计算所属槽。
每个 Master 负责一部分槽，可配置 Slave 做高可用。
客户端访问错误节点时，会收到 MOVED 或 ASK 重定向。

MOVED vs ASK：

MOVED：槽已经永久迁移到目标节点。
ASK：槽正在迁移中，先访问目标节点一次。

八、事务与 Lua 脚本

8.1 事务（MULTI/EXEC/DISCARD/WATCH）

MULTI
SET a 1
INCR b
EXEC

特点：

命令按顺序入队，EXEC 时一次性执行。
执行期间不会被其他客户端打断。
但没有回滚机制：如果某条命令语法错误，整个事务不执行；如果运行时错误（如 INCR 字符串），后续命令仍会执行。

8.2 Lua 脚本

EVAL "return redis.call('incr', KEYS[1])" 1 counter

特点：

整个脚本作为一个整体在单线程中原子执行。
适用于需要多个命令且要保证原子性的场景，如秒杀、分布式锁、限流。
集群模式下所有 Key 必须落在同一 slot，否则需要加 hash tag，如 {user}:1001:profile。

九、缓存经典问题

9.1 缓存穿透

问题：查询不存在的数据，缓存不命中，请求直接打到数据库。

解法：

缓存空值（设置短 TTL）。
使用布隆过滤器预先判断 Key 是否存在。

9.2 缓存击穿

问题：热点 Key 突然过期，大量请求同时打到数据库。

解法：

热点 Key 设置永不过期，异步更新。
加互斥锁（SETNX），只允许一个线程重建缓存。

9.3 缓存雪崩

问题：大量 Key 同时过期，或 Redis 宕机，数据库压力陡增。

解法：

给 TTL 加随机值，避免同时失效。
多级缓存（本地 + Redis）。
熔断降级。

9.4 缓存与数据库一致性

常见策略：

策略	说明	问题
Cache Aside	读：先读缓存，未命中读 DB 并写回缓存；写：先更新 DB，再删缓存。	短暂不一致
Read/Write Through	由缓存层统一维护 DB 和缓存。	实现复杂
Write Behind	先写缓存，异步写 DB。	可能丢数据

最常用的是 Cache Aside，配合「先更新数据库，再删除缓存」+ 延时双删 + 消息队列补偿，能在大多数场景下保证最终一致。

十、Redis 在 IPTV 系统中的角色

IPTV 系统的特点是：高并发读、强实时性、热点集中、写流量脉冲式。用户在换台、看 EPG、播放点播、抢购付费节目时，系统需要在毫秒级返回结果。

flowchart TB
    subgraph 用户层
        A[机顶盒 / 手机 / Web]
    end

    subgraph 接入层
        B[CDN / 边缘节点]
        C[API Gateway]
    end

    subgraph 应用层
        D[鉴权服务]
        E[EPG 服务]
        F[播放调度服务]
        G[订单 / 秒杀服务]
    end

    subgraph 数据层
        H[(MySQL / 长视频元信息)]
        I[(对象存储 OSS)]
        J[(Redis 缓存 + 实时计算)]
    end

    A --> B --> C
    C --> D & E & F & G
    D --> J
    E --> J
    F --> J
    G --> J
    E --> H
    F --> I
    G --> H
    J -.-> H

场景	Redis 数据结构	作用
用户会话 / Token	String + EXPIRE	毫秒级鉴权
EPG 节目单缓存	Hash / JSON String	减少数据库查询
热播榜单 / 推荐位	Sorted Set (ZSET)	实时排序
播放限速 / 防刷	Lua + INCR + EXPIRE	滑动窗口限流
秒杀 / 付费解锁	SETNX + DECR + Lua	库存扣减
消息通知 / 任务队列	List / Stream	异步解耦

十一、IPTV 项目 Demo

11.1 用户会话缓存

import redis
import uuid
import time

r = redis.Redis(host='localhost', port=6379, db=0, decode_responses=True)

def login(user_id: str, device_id: str, ttl: int = 3600) -> str:
    token = str(uuid.uuid4())
    key = f"session:{token}"
    r.hset(key, mapping={
        "user_id": user_id,
        "device_id": device_id,
        "login_at": str(time.time())
    })
    r.expire(key, ttl)
    return token

def auth(token: str) -> dict | None:
    return r.hgetall(f"session:{token}")

11.2 EPG 节目单缓存

import json
from datetime import datetime

def cache_epg(channel_id: str, programs: list[dict]):
    key = f"epg:{channel_id}:{datetime.today().strftime('%Y%m%d')}"
    pipe = r.pipeline()
    for p in programs:
        pipe.hset(key, p['start_time'], json.dumps(p))
    pipe.expire(key, 86400 * 2)
    pipe.execute()

def get_program(channel_id: str, start_time: str) -> dict | None:
    data = r.hget(f"epg:{channel_id}:{datetime.today().strftime('%Y%m%d')}", start_time)
    return json.loads(data) if data else None

11.3 热播排行榜

def record_view(program_id: str, score: float = 1.0):
    r.zincrby("hot:tv:daily", score, program_id)

def top_n(n: int = 10) -> list[tuple[str, float]]:
    return r.zrevrange("hot:tv:daily", 0, n - 1, withscores=True)

11.4 滑动窗口限流

LIMIT_SCRIPT = """
local key = KEYS[1]
local window = tonumber(ARGV[1])
local limit = tonumber(ARGV[2])
local now = tonumber(ARGV[3])
local min = now - window

redis.call('zremrangebyscore', key, '-inf', min)
local count = redis.call('zcard', key)
if count < limit then
    redis.call('zadd', key, now, now)
    redis.call('expire', key, math.ceil(window / 1000))
    return 1
else
    return 0
end
"""

limiter = r.register_script(LIMIT_SCRIPT)

def allow(user_id: str, max_qps: int = 10, window_ms: int = 1000) -> bool:
    key = f"rate_limit:{user_id}"
    now = int(time.time() * 1000)
    return bool(limiter(keys=[key], args=[window_ms, max_qps, now]))

11.5 秒杀 / 限时解锁

SECKILL_SCRIPT = """
local key = KEYS[1]
local user_id = ARGV[1]
local stock = tonumber(redis.call('get', key) or '0')
if stock <= 0 then
    return -1
end
if redis.call('sismember', key .. ':users', user_id) == 1 then
    return 0
end
redis.call('decr', key)
redis.call('sadd', key .. ':users', user_id)
return 1
"""

seckill = r.register_script(SECKILL_SCRIPT)

def try_buy(activity_id: str, user_id: str, total_stock: int) -> int:
    key = f"seckill:{activity_id}:stock"
    r.setnx(key, total_stock)
    return int(seckill(keys=[key], args=[user_id]))

十二、为什么 Redis 不适合做长期存储？

12.1 持久化不是主存储

RDB 会丢数据，AOF 文件大且恢复慢。Redis 的持久化定位是「灾难恢复」，不是「可靠主存」。

12.2 内存成本过高

内存价格是 SSD 的 10-50 倍。IPTV 的媒资、播放记录、订单流水动辄几十 TB，全放 Redis 不现实。

12.3 单线程执行风险

大数据集下，一个 KEYS *、HGETALL 或慢查询可能阻塞整个实例。

12.4 缺乏复杂查询能力

Redis 不支持 SQL、JOIN、二级索引。长期业务数据需要分析统计时，应使用 MySQL / PostgreSQL / ClickHouse。

结论：

Redis 适合「热数据 + 临时状态 + 实时计算」，价值在于速度；长期存储应交给磁盘数据库 + 对象存储。

十三、Redis 容易踩坑的地方

坑	说明	解法
大 Key	String > 10MB，集合元素百万级	拆分、分片、UNLINK 异步删除
热 Key	单个 Key 被高频访问	本地缓存、Key 分片、Cluster
缓存穿透/击穿/雪崩	缓存失效导致 DB 被打挂	布隆过滤器、互斥锁、随机 TTL
未设置 maxmemory	内存打满后写操作报错	设置 maxmemory 和淘汰策略
误用 KEYS	`KEYS *` 扫描全库阻塞主线程	生产禁用，改用 SCAN
Lua 跨 slot	Cluster 下脚本 Key 不在同一 slot	使用 hash tag `{user}:1001:xxx`
事务没有回滚	EXEC 后某命令失败不会撤销前面命令	业务层保证幂等，或用 Lua
主从延迟	读从库可能读到旧数据	对一致性要求高的读走主库

十四、Redis 做消息队列的方法

14.1 List：轻量队列

flowchart LR
    P[Producer] -->|LPUSH queue:transcode task| R[(Redis List)]
    C[Consumer] -->|BRPOP queue:transcode 5| R
    C --> S[执行转码]

r.lpush("queue:transcode", json.dumps({"video_id": "v123"}))
_, task = r.brpop("queue:transcode", timeout=5)

优点：简单、阻塞读。缺点：无 ACK、无多消费者组、无消息回溯。

14.2 Pub/Sub：实时广播

r.publish("live:start", json.dumps({"channel_id": "cctv1"}))

优点：实时、多订阅者。缺点：不持久化，消费者断线期间消息丢失。

14.3 Stream：生产级队列

r.xadd("mq:events", {"event": "video:play", "user_id": "u10086"})

r.xgroup_create("mq:events", "group_log", id="0", mkstream=True)

messages = r.xreadgroup(
    groupname="group_log",
    consumername="worker_1",
    streams={"mq:events": ">"},
    count=10,
    block=5000
)
for stream, entries in messages:
    for msg_id, fields in entries:
        process(fields)
        r.xack("mq:events", "group_log", msg_id)

优点：支持消费者组、ACK、消息回溯。

方式	推荐场景
List	简单任务队列
Pub/Sub	实时广播
Stream	生产级消息队列

十五、总结

《Redis in Action》的核心思想可以概括为一句话：把 Redis 当成内存里的数据结构工具箱，而不是数据库。

Redis 适合：

缓存加速（会话、配置、热点数据）。
实时计算（排行榜、计数器、限流、秒杀）。
异步解耦（List / Pub/Sub / Stream）。

Redis 不适合：

长期持久化存储。
复杂查询与大数据分析。
超大数据集主存储。

避免踩坑的关键是：控制 Key 大小、设置合理 TTL、配置淘汰策略、慎用阻塞命令、理解持久化边界。Redis 用好了是神兵利器，用错了就是生产事故的导火索。

Elasticsearch 从原理到 IPTV 媒资搜索实战：基于 ftmao-meta 项目的完整复盘

Sat, 28 Aug 2021 14:00:00 +0800

Elasticsearch 从原理到 IPTV 媒资搜索实战：基于 ftmao-meta 项目的完整复盘

以我们线上运行的 IPTV 媒资元数据服务 ftmao-meta 为样本，讲清楚一个真实的 ES（实际为 AWS 托管 OpenSearch）应用是怎么设计索引、同步数据、支撑搜索和下游订阅的。所有配置、代码、索引设计均来自项目本身，踩过的坑也一并奉上。

一、项目背景：这是一个什么系统

ftmao-meta 是一个面向多地区运营的 IPTV/OTT 视频内容平台的媒资元数据微服务，Spring Boot 3.3 + Java 21，单模块 Gradle 工程，包结构 gtt.ftmao.meta，分 api / app / bean / core 四层。它管理的数据包括：

影视元数据：电影、剧集、季、集、短视频的多语言标题、简介、海报、演职员、分级、票房；
演职人员：多语言姓名、热度值（pgcHot / ugcHot / imdbHot）、代表作；
物料：剧照海报（artwork）、预告片（trailer）；
C 端搜索：全文检索 + 输入自动补全。

这些数据量巨大（千万级文档）、多语言（英语/西语/葡语，服务拉美市场）、多租户（多家运营商公司共用），而且需要被下游多个服务增量订阅。MySQL 是事实源（Source of Truth），ES 承担所有读路径的检索。

技术选型上的关键事实：

后端是 AWS 托管 OpenSearch，客户端用官方 opensearch-java 2.8.1（org.opensearch.client.opensearch.OpenSearchClient），没有用 spring-data-elasticsearch，也没有 RestHighLevelClient；
全文检索与自动补全能力封装在公司内部库 searchengine-api/core/sync 里，业务代码只调用 SearchApi / SearchSync 门面；
数据同步不走 MQ（Kafka 依赖在启动类里被显式排除），而是"MySQL 任务表 + 定时轮询 + 分布式锁"。

graph TB
    subgraph 上游["上游数据来源"]
        BOSS["运营后台 / 内容录入"]
        PP["PP 开放平台<br/>（REST 拉取外部媒资）"]
    end

    subgraph META["ftmao-meta 服务"]
        API["REST API 层"]
        SVC["业务 Service<br/>MetaService / ArtworkService ..."]
        JOB["定时 Job<br/>PpMetaSyncJob 每 15s"]
        LOCK["分布式锁<br/>AsyncJobExecutorManager"]
    end

    subgraph STORE["存储层"]
        MYSQL[("MySQL<br/>事实源 + 同步任务表")]
        subgraph OS["AWS OpenSearch"]
            DETAIL["meta_detail_index<br/>媒资详情（重索引）"]
            PERSON["meta_person_index<br/>人物详情"]
            ART["meta_artwork_index<br/>剧照物料"]
            TRAILER["meta_trailer_index<br/>预告片"]
            SEARCH["search_engine_index<br/>C端搜索（轻索引）"]
        end
    end

    subgraph DOWN["下游消费方"]
        PORTAL["门户/推荐服务"]
        SUB["增量订阅方<br/>（时间水位拉取变更）"]
    end

    BOSS --> SVC
    PP --> JOB
    SVC -->|"事务内：先写库，再直写 ES"| MYSQL
    SVC --> DETAIL
    SVC --> SEARCH
    JOB --> LOCK --> MYSQL
    JOB -->|"批量灌入"| SEARCH
    API -->|"全文搜索/补全"| SEARCH
    API -->|"mget 回查详情"| DETAIL
    API --> PERSON & ART & TRAILER
    DETAIL -->|"lastModifiedIndicator 水位"| SUB
    SEARCH --> PORTAL

二、先补原理：理解后面设计决策的三个支点

在进入项目细节前，用三句话回顾《Elasticsearch in Action》里最重要的原理，后面每个设计决策都会用到它们。

2.1 倒排索引与分词

ES 搜索快的根本原因是倒排索引：term → 文档列表。而文本进入倒排索引前要经过分析链：

graph LR
    A["原始文本<br/>O Auto da Compadecida"] --> B["Character Filter<br/>变音符号映射 á→a"]
    B --> C["Tokenizer<br/>standard 分词"]
    C --> D["Token Filter<br/>lowercase + stopword + stemmer"]
    D --> E["词项 Term<br/>auto / compadecida"]

一个字段建索引时用哪个 analyzer、搜索时用哪个 analyzer，直接决定了"搜不搜得到"。这就是为什么 mapping 必须在灌数据之前设计好——改 analyzer 意味着重建索引。

2.2 近实时（NRT）与 refresh

文档写入后先进内存缓冲区，默认 1 秒后 refresh 生成 segment 才可被搜索。批量灌数据时调大 refresh_interval、或显式控制 refresh 时机，是写入性能优化的第一手段——后面会看到项目里批量写入怎么用它。

2.3 Query 与 Filter 的区别

Query：算相关性得分 _score，用于全文匹配排序；
Filter：只判断 yes/no，不算分、结果可被缓存，用于精确过滤。

项目里几乎所有查询都是"filter 套 query"的 bool 结构：关键词进 must，租户、类型、软删除标记进 filter。

三、索引设计：一个搜索索引 + 四个详情索引

3.1 索引清单

项目中没有任何 @Document 注解或 mapping JSON 文件，索引 DDL 采用类似 Liquibase 的 changelog 形式管理（changelog/elasticsearch/*.yaml，HTTP method + path + body，由外部部署工具执行），别名字段统一管理：

代码中的别名	实体索引	分片	存什么
`meta_detail_index`	`ftmao-meta-detail-1`	6 主 2 副	媒资详情全集
`meta_person_index`	`ftmao-meta-person-detail`	6 主 2 副	演职人员详情
`meta_artwork_index`	`ftmao-meta-media-artwork`	6 主 2 副	剧照物料
`meta_trailer_index`	`ftmao-meta-media-trailer`	6 主 2 副	预告片
`search_engine_index`	`ftmao-meta-search-engine`	1 分片	C 端搜索/补全

别名与文档类的映射集中在一个枚举里（OpenSearchIndexEnum），业务代码只认别名——这是"换索引不改代码"的基本功，比如 ftmao-meta-detail-1 后面出现 -2，只需要 reindex 后切别名。

3.2 详情索引：重存储、轻检索

meta_detail_index 的 mapping 有个鲜明特征：几乎所有字段都是 keyword，标题、剧情简介都是 keyword + nested，不参与分词检索，大量 nested 对象（displayTitles / plots / posters / casts）配 dynamic: false。

为什么？因为详情索引的职责是**“按 ID/结构化条件精确取数”**，不是全文搜索。keyword 不做分词，聚合、terms 过滤、精确匹配都快；dynamic: false 防止上游数据乱塞字段把 mapping 撑爆（mapping explosion 是生产事故常客）。

3.3 搜索索引：整个项目最精彩的部分

search_engine_index 只有 1 个分片（轻量、追求查询 RT），但它的 analysis 配置是整个项目技术含量最高的地方。以主搜索字段 mainTitle 为例：

# 摘自 changelog（简化）
mainTitle:
  type: text
  store: true
  term_vector: with_positions_offsets   # 为 fast-vector-highlighter 高亮做准备
  analyzer: en_es_pt                     # 英/西/葡三语混合分词器
  fields:
    cut_word:    { analyzer: en_es_pt }              # 正常分词匹配
    all_letters: { analyzer: N_gram(4-15) }          # 长 ngram：前缀/模糊匹配
    word_letters:{ analyzer: N_gram(2-10) }          # 短 ngram：更激进的模糊匹配
    origin:      { type: keyword, normalizer: lowercase }  # 精确匹配/排序

配套自定义组件：

多语分析器 en_es_pt：standard tokenizer + 英语/西语/葡语三套 stopword + stemmer；
变音符号 char_filter：把 áéíóúàèç 等西葡变音符号映射为 ASCII——拉美用户搜 compadecida 也能命中 Compadecida，对多语言市场这是体验生死线；
ngram tokenizer 一批（1–10、4–15 等不同窗口），max_ngram_diff=14；
completion suggester：suggest 字段配 suggester_trigram 分析器，带 3 个 category context（markCate / tenantCate / comboCate）——自动补全可以按内容类型和租户隔离，A 运营商的用户不会看到 B 运营商专有的片名提示。

设计启示：一个"能搜"的字段，实际需要四层子字段分工——正常分词管召回、长 ngram 管前缀联想、短 ngram 管纠错、keyword 管精确和排序。这也正是《Elasticsearch in Action》里"多字段映射"思想的生产级演绎。

3.4 双索引架构：为什么搜索和详情要分开

graph LR
    subgraph 写入["写入侧"]
        D["MetaDetail 完整文档<br/>（几十 KB，含 nested 海报/演员/多语言）"] --> DETAIL["详情索引<br/>6分片 重存储"]
        D -->|"裁剪：docId + mainTitle +<br/>suggest + 过滤字段 + 租户"| SEARCH["搜索索引<br/>1分片 轻量"]
    end
    subgraph 查询["查询侧"]
        U["用户搜索 'auto'"] -->|"① matchSearch 命中<br/>返回 docId 列表"| SEARCH
        SEARCH -->|"② 按 docId mget"| DETAIL
        DETAIL -->|"组装完整详情返回"| U
    end

搜索索引里不存详情，只有：docId、mainTitle（及 ngram 子字段）、suggest、40+ 个 keyword 过滤字段（ext-field-to-index-map 里配置，如媒资类型、地区、年份、分级）、租户字段。好处有三个：

搜索索引小，1 个分片 + 内存友好，C 端 QPS 扛得住；
详情变更不用动搜索索引——海报换了只 update 详情索引；搜索索引只在标题/过滤字段变化时更新；
两类索引可以独立扩缩容、独立重建。

代价也很明显：多一次 mget 回查、数据一致性要维护两份。这个项目用下一节的同步机制来兜底。

四、数据同步：MySQL → ES 的三条路径

ES 是"读模型"，MySQL 才是事实源。项目没用 Canal/MQ，而是自己实现了一套事务内直写 + 任务表轮询的混合方案：

flowchart TD
    A["业务写请求<br/>MetaService.save()"] --> B{"@Transactional"}
    B --> C["① 写 MySQL 业务表"]
    B --> D["② 写 MySQL 同步任务表<br/>MixedMetaSyncTask"]
    B --> E["③ 同事务内直写详情索引<br/>bulkOperationByBatch(refresh=True)"]
    B --> F["④ saveMetaToSearchEngine<br/>同步搜索索引"]
    E --> G{"ES 写失败?"}
    G -->|"是，事务回滚或留下任务"| H["任务表残留记录"]
    D --> I["PpMetaSyncJob<br/>@Scheduled 每 15s"]
    H --> I
    I --> J["分布式锁<br/>executeWithLock"]
    J --> K["MetaTaskProcessService<br/>分批 Lists.partition(batchSize)"]
    K -->|"searchSync.save(batch)"| L["搜索索引"]
    M["失败重试 Job<br/>每小时"] --> J

三条路径各有分工：

同事务直写（主路径）：保证"后台保存完，前台立刻能搜到"。写入时统一刷新 updateTime 和 lastModifiedIndicator（格式：时间戳_docId 的版本游标，下一节详述）；
任务表 + 定时轮询（兜底路径）：15 秒一轮，分布式锁防多实例并发，分批灌入；
失败重试 Job（保险）：每小时扫描失败任务重放。

为什么不纯用 MQ？ 这个系统的写入量级不大（媒资是低频高价值数据，不是日志），事务内直写的一致性收益远大于引入 MQ 的复杂度。这是"按场景选方案"而不是"按潮流选方案"的好例子。

4.1 批量写入的性能细节

工具类 OpenSearchUtil.bulkUpsertDocuments 里有两个值得抄的实践：

// 按配置的 bulkSize（默认 200）分批，避免单个 bulk 过大压垮集群
// 每批显式 refresh(WaitFor)：写完后“等 refresh 完成再返回”，
// 保证同步接口的调用方“写完立即可见”，同时比 refresh=true（每文档刷新）省资源

对照第 2.2 节的 NRT 原理：refresh=WaitFor 是吞吐和可见性之间的甜点——批量场景不要无脑 refresh=true。

五、查询实战：从业务代码反推 ES 用法

5.1 一切查询的起点：软删除过滤

项目里文档不物理删除，而是软删除——所有读路径都要叠一层 isDeleted=0：

// OpenSearchUtil.getUndeletedQuery：所有查询都要过这层包装
Query undeletedQuery = openSearchUtil.getUndeletedQuery(boolQueryBuilder.build()._toQuery());
// 底层就是 bool.filter(terms(isDeleted, [0]))，可能再叠加 status=1（已发布）

业务侧的典型用法（ArtworkService，按媒资 ID 查剧照）：

Query metaIdQuery = Query.of(q -> q.terms(t -> t.field("metaId")
    .terms(tv -> tv.value(Stream.of(request.getMetaId())
        .map(FieldValue::of).toList()))));
boolQueryBuilder.filter(metaIdQuery);
Query undeletedQuery = openSearchUtil.getUndeletedQuery(boolQueryBuilder.build()._toQuery());
SortOptions sortOption = SortOptions.of(s -> s.field(
    f -> f.field("pos").order(SortOrder.Asc)));
List<MediaArtwork> artworks = openSearchUtil.searchDoc(
    OpenSearchIndexEnum.MEDIA_ARTWORK.getIndexName(),
    undeletedQuery, MediaArtwork.class,
    request.getPageId(), request.getPageSize(),
    Collections.singletonList(sortOption), totalCount);

这正是第 2.3 节"filter 不算分、可缓存"原理的落地：结构化条件全部进 filter。

5.2 软删除的实现：updateByQuery + Painless 脚本

删除不是 delete，而是 updateByQuery 打标记：

String script = " ctx._source.isDeleted = 1;"
      + "ctx._source.updateTime = params.currentTime;"
      + "ctx._source.lastModifiedIndicator = params.indicatorPrefix + '_' + ctx._id";
UpdateByQueryRequest request = new UpdateByQueryRequest.Builder()
    .index(indexName).query(query)
    .script(s -> s.inline(i -> i.source(finalScript)
        .params("currentTime", JsonData.of(currentTime))
        .params("indicatorPrefix", JsonData.of(String.valueOf(modifyTime)))))
    .build();

注意脚本里同时更新了 lastModifiedIndicator——软删除也是一次"变更"，必须让下游订阅方感知到（下游才能同步删）。这个细节是订阅体系能闭环的关键。

5.3 两阶段全文搜索

C 端搜索入口 SearchService.searchMedia 的分流逻辑：

if (StringUtils.isNotEmpty(fuzzyMatchingParams.getKeyword())) {
    // 有关键词：内部库全文检索 → 返回 docId + mark（类型）
    resp = searchApi.matchSearch(keyword, marks, pageId, pageSize, tenantIds, params);
} else {
    // 无关键词：纯结构化筛选（找片页、分类浏览）
    resp = searchApi.find(marks, pageId, pageSize, tenantIds, params);
}
// 按 mark 分流 person / meta，回查详情索引取完整数据
openSearchUtil.batchGetDocuments(PERSON_DETAIL.getIndexName(), personDocIds, PersonDetail.class);
openSearchUtil.batchGetDocuments(META_DETAIL.getIndexName(), metaDocIds, MetaDetail.class);

查询条件从哪来？API 层收的是 SQL 风格的 where 模板（MetaQuery.whereTemplate + parameters），WhereClauseUtil 用正则把 in (:x)、between and、JSON_CONTAINS_ALL/ANY 解析成 ES 的 Condition（IN / GREATER_THAN 等），字段名经 FieldNameMappingEnum 做外部名→索引字段名映射。

这个设计的好处：对前端/上游服务来说，查询语法是稳定的数据库风格，不暴露 ES DSL；ES mapping 改名、换引擎，外部无感。

5.4 自动补全：completion suggester + 租户隔离

// SearchService.suggest
List<Prompt> prompts = searchApi.getPromptList(keyword, marks, true, companyId, size, uuid);
// 底层 = 搜索索引 suggest 字段的 completion suggester，
// context 里带 tenantCate=companyId → 补全结果按运营商隔离
// 拿到 docId 后再回查详情索引组装标题和海报

举例如"用户输入 int"：

sequenceDiagram
    participant U as 用户(运营商A)
    participant S as SearchService
    participant SE as 搜索索引 suggester
    participant D as 详情索引
    U->>S: suggest("int", companyId=A)
    S->>SE: completion suggest<br/>context: tenantCate=A
    SE-->>S: ["Interestelar", "Intocáveis"]<br/>+ docId 列表
    S->>D: mget(docIds)
    D-->>S: 标题 + 海报 URL
    S-->>U: 补全列表（带封面）

5.5 一个常被忽略的性能点：只取 ID 就别加载 _source

// fastGetDocumentById：判断文档存在/取 ID 时
// storedFields("_id") + size(1) + trackTotalHits(false)
// 注释原话：类似 MySQL 的 LIMIT 1

trackTotalHits(false)：不精确统计总数（默认只算到 10000），省掉一次全量计数；
storedFields("_id")：不加载 _source，网络传输量从几十 KB 降到几十 B。

列表页"先查 ID 再回查"的场景，这两招能把响应时间砍掉一个量级。

六、增量订阅：ES 作为"变更数据源"

下游服务（推荐、缓存、其他中台）需要感知媒资变更。项目没有用 CDC 或 MQ 广播，而是让下游基于水位游标主动拉取 ES：

sequenceDiagram
    participant SUB as 下游订阅方
    participant Q as SubqueryService
    participant ES as 详情索引

    Note over SUB: 记录上次水位 W0<br/>（lastModifiedIndicator 字符串）
    SUB->>Q: querySubQuery(from=W0, size=500)
    Q->>ES: range(lastModifiedIndicator: gt W0, lt 当前时间-2s)<br/>+ 按 lastModifiedIndicator 升序
    ES-->>Q: 本批变更文档（含软删除的）
    Q-->>SUB: 文档 + 新水位 W1
    SUB->>SUB: 落库/更新缓存，记录 W1
    Note over Q,ES: 对账：subQueryCount 用 count + sort desc + size(1)<br/>取区间最大水位，生产方/消费方核对数量

几个工程细节值得细说：

水位是字符串而非时间戳：lastModifiedIndicator = 时间戳 + "_" + docId。纯时间戳会在同一毫秒内有多个文档时漏数；拼上 docId 后字典序唯一，range gt 翻页不会漏、不会重。这是项目用手写游标替代 search_after 的原因——行为完全可控，且不依赖 ES 的 PIT（point in time）上下文。
lt 当前时间 - 2s 的回调偏移：规避"刚写入还没 refresh 可见"的窗口（第 2.2 节 NRT 原理的直接应用），宁可晚 2 秒，不可漏数据。
软删除文档也带着新水位出现，下游据此删除本地副本——和第 5.2 节的脚本闭环。

七、多租户设计：docId 里藏着租户

// OpenSearchUtil.getDocId：文档 ID = companyId + "#" + metaId
// 例："1001#mv_8848123"、"public#mv_8848123"（公共库）

同一部影片，A 运营商和 B 运营商是两份文档（各自的标题、定价、上架状态可能不同），天然物理隔离；
sourceType 字段区分 PRIVATE（私有）/ PUBLIC（公共）/ MIXED（混合），公共内容用 public# 前缀，查询时按租户策略合并；
所有查询 filter 里都带 companyId / tenant_id，补全用 context 隔离（第 5.4 节）。

经验：多租户搜索系统，把租户编进 docId 比单纯加过滤字段更稳——docId 冲突本身就是一道防串租户的保险。

八、回到原理：这个项目验证了哪些书里的论断

书中原理	项目里的体现
Mapping 先行，改 analyzer 要重建索引	索引 DDL 用 changelog 版本化管理，上线流程化
Filter 不算分、可缓存	租户/类型/软删除/状态全部进 filter，只有关键词算分
多字段映射解决"一个字段多种搜法"	mainTitle 四层子字段：分词/长ngram/短ngram/keyword
NRT 的 refresh 是性能旋钮	批量写入用 `refresh=WaitFor`；订阅端留 2s 偏移
深度翻页要避免 from+size 深分页	手写 `lastModifiedIndicator` 游标替代 search_after
聚合昂贵，慎用	项目几乎零聚合；取最大值用 sort+size(1) 替代 max agg
分片数创建时定死，规划要前置	详情索引 6 分片按数据增长预估；搜索索引刻意 1 分片

九、总结

如果把这套架构压缩成一张图：

graph LR
    W["写路径<br/>MySQL 事务<br/>+ 任务表兜底"] --> ES
    subgraph ES["OpenSearch"]
        S["搜索索引<br/>小而快：ngram+suggester<br/>+租户 context"]
        D["详情索引<br/>大而全：keyword+nested<br/>dynamic:false"]
    end
    ES --> R1["读路径 ①<br/>搜索/补全 → docId"]
    R1 --> R2["读路径 ②<br/>mget 详情组装"]
    ES --> R3["订阅路径<br/>水位游标增量拉取"]

三条核心经验：

索引按"查询模式"而不是"数据表"来设计：搜索索引和详情索引分开，一个为召回优化（ngram、suggester、多语分析器），一个为取数优化（keyword、nested、禁动态字段）；
一致性靠机制不靠运气：事务内直写是主路径，任务表 + 定时 Job + 失败重试是兜底，水位游标让下游最终一致——三层防护各管一段；
所有"黑科技"都是基本原理的应用：refresh 偏移、filter 缓存、storedFields 取 ID、游标翻页……吃透《Elasticsearch in Action》那套原理，生产方案都是它的排列组合。

参考资料：Radu Gheorghe, Matthew Lee Hinman, Roy Russo. 《Elasticsearch in Action》. Manning Publications, 2015；ftmao-meta 项目源码（OpenSearchConfig / OpenSearchUtil / SearchService / SubqueryService / changelog/elasticsearch）。