我用 go-zero 搭了一套海外短剧推荐系统：全景架构拆解

标题备选我用 go-zero 搭了一套海外短剧推荐系统从 API 网关到 MMoE 精排的全景架构规则先行、模型可插拔一个短剧推荐系统的完整架构拆解go-zero gRPC ES Redis Triton推荐系统落地全景附踩坑清单摘要本文按「服务拓扑 → 契约生成 → 数据分层 → 推荐双链路 → 媒体与支付 → 部署形态 → 踩坑」的顺序完整拆解一个面向海外市场的短剧推荐系统。核心思路是事实只存一份派生数据全部可重建算法链路可插拔可降级。标签go-zero、gRPC、推荐系统、Elasticsearch、Redis、MMoE、Tauri微信联系zifeng6257我用 go-zero 搭了一套海外短剧推荐系统全景架构拆解0. 这个项目在解决什么问题海外短剧的业务形态很特殊内容按「剧」分发用户点进去是连续追集市场是多个国家 × 多种语言变现靠单剧解锁付费。所以系统要同时满足四件事内容管理剧目 / 剧集 / 上下架 / 多国家多语言元数据视频链路原始视频不能过应用服务器要直传对象存储 HLS 转码 CDN 播放推荐链路先跑通「曝光 → 观看 → 埋点 → 画像 → 推荐」的数据闭环再谈模型交易链路Stripe / PayPal 支付成功后写权益表剧集实时解锁我把它做成了1 个 Web 网关 1 个管理网关 6 个 RPC 服务 2 个 Tauri 客户端的结构。下面逐层展开。1. 技术栈一览层次选型版本微服务框架go-zeroREST zRPCv1.10.3代码生成goctl / protoc-gen-go / Ent generatorgoctl v1.10.3IDL / 契约.apiREST、.protoRPC、Ent Schema—ORMEnt 手写 Repository数据库结构以 SQL migration 为准ent v0.14.6存储MySQL事实源、Redis派生缓存、Elasticsearch召回投影—对象存储阿里云 OSS SDK v2、AWS S3 SDK v2抽象成统一 Storage 接口—转码FFmpegHLSmaster.m3u8 TS 分片—排序模型PyTorch MMoE → ONNX → Triton ServerHTTP/v2/models/mmoe/infer—客户端Tauri 2 Vue 3 Vite 7 Element Plus hls.js—支付Stripe PaymentIntent、PayPal Orders v2含 webhook—语言运行时Go 1.27.1—一句总结Go 负责工程链路Python 只负责训练模型产物通过 ONNX 交付给 Go 调用。2. 服务拓扑与端口规划client-tauri (C端) admin-tauri (管理端) | | ┌──────────┴──────────┐ ┌───────┴────────┐ v v v v auth-api:8085 drama-api:8080 drama-admin-api:8081 登录/注册/JWT 业务 REST 网关 内容/上传/设置/订单 | | | | ┌─────────┬───────┼────────┬─────────────┐ v v v v v v user-rpc:9001 drama-rpc:9002 behavior-rpc:9003 recommend-rpc:9004 | | media-rpc:9006 payment-rpc:9005 | | v v OSS / S3 / 本地磁盘 FFmpeg Stripe / PayPal 基础设施MySQL(13306) Redis(16379) Elasticsearch(19200) Triton(8000) 离线/实验recdemo独立 go module -mode seed|index|rebuild|serve|train几个刻意的取舍zRPC 直连而非 etcd 注册中心。单机本地开发时Target: 127.0.0.1:9002这种直连方式启动链路最短要上生产再换 etcd只改配置不改代码。网关按受众拆分drama-apiC 端、drama-admin-api管理端、auth-api鉴权。管理端的重上传、密钥测试等能力不会污染 C 端网关。实验链路独立成 modulerecdemo有自己的go.mod训练/灌数/重建 Redis 等一次性工具全塞进去主模块依赖不被污染。3. 契约先行三条互不反生的代码生成链go-zero 项目最容易腐化的地方是「生成代码被手改重生成就丢」。我用 Makefile 固化了三条链并明确它们的边界api/*.api - goctl api go - api/*-api/handler types routes proto/*.proto - goctl rpc protoc - rpc/*-rpc/pb server logic 骨架 rpc/ent/schema/*.go - ent generate - rpc/ent/ORM 代码三条链的产物分别维护、互不自动生成.api改了不会帮你想到.proto.proto改了不会帮你改 SQL。配套的两条纪律Proto 只新增字段永不复用旧字段编号MySQL 只做增量 migration不改历史文件。生成物落 CIGitHub Actions 里顺序是 protobuf 生成 → Ent 生成 →go test→ 服务 build。用 CI 客观验证「Schema 能不能生成」而不是在本地凭感觉说通过。一个必须记住的坑goctl api go重新生成routes.go会把手写注册的路由冲掉。我加过的 LOCAL 媒体上传/播放路由就被清过一次后来统一改成「需要额外路由时在.api里声明或生成后立即 diff 校验」。4. 数据分层一个 Drama 的三种身份推荐系统里最贵的返工是把业务实体直接当模型输入。所以从第一天就把内容数据切成三层Drama业务实体MySQL dramas 为准 ├── 展示层title / subtitle / description / cover / preview_url / genres[] / tags[] ├── 运营层country / language / status / is_paid / free_episode_count / total_episodes └── 指标层popularity / completion_rate / pay_rate / published_at | -- ES content document召回用字段归一化后投影 | -- RecommendationFeature模型用经 Feature Builder ├── sparseuser_id / drama_id / region_id / language_id / genre_id ├── dense 用户观看时长、完播、付费率、session 数剧热度、完播率、付费率、剧龄 └── semantictitle / description / genre / tag embedding预留 | v MMoE关键约定推荐单位是「剧」不是「集」。用户从首页进一部剧后连续观看Feed 返回drama_id播放和续播交给 drama / episode / media 域。country/language默认是特征和 boost不做无条件硬过滤。否则新市场、冷启动阶段直接返回空 Feed。原始文本永远保留翻译结果和 embedding 版本单独记录不许用机翻覆盖原文字段。5. 埋点与 Redis派生数据必须可重建这是我认为整套架构里最值钱的约束——Redis 里不许存任何丢了就没了的东西。事实源只有一份MySQLbehavior_events明细永久保存。Redis 的三个结构都是它的投影Key类型语义TTLdrama:event:{drama_id}:{event_type}String事件累计次数INCR无user:recent:{user_id}List最近观看剧 ID最新在头定长 507 天heat:{country}:{language}ZSet加权热度榜score 事件加权和7 天滑动写入链路是「MySQL 落库成功即业务成功Redis 三写全部只记日志」client - POST /api/v1/behaviors - drama-api薄网关只转发 - behavior-rpc.RecordEvent ├─ [必须成功] INSERT behavior_events └─ [失败仅 log不影响返回] ├─ INCR drama:event:{id}:{type} ├─ ZINCRBY heat:{country}:{lang} {weight} {drama_id} └─ LPUSHLTRIM(0,49) user:recent:{uid}为什么 Redis 写失败绝不能返回错误给客户端因为客户端会重试重试会往behavior_events重复插入把唯一的事实源污染掉。为了保住一份可随时丢弃的缓存而搞坏事实源是最差的一笔交易。热度按信号强度分层加权弱信号强降权防刷榜事件权重事件权重PURCHASE8NEXT_EPISODE3COMPLETE5CLICK / SEARCH1FAVORITE / SHARE4PAUSE0.5PLAY / LIKE2IMPRESSION / WATCH_PROGRESS0.1Redis 挂了怎么办recdemo -mode rebuild先 SCAN 清理三类旧 key再从behavior_events全量重放COUNT(*) GROUP BY、按时间正序 LPUSH、SUM(CASE 权重) GROUP BY country,language,drama_id覆盖式、幂等、可任意重跑。有了这条Redis 甚至可以不开 AOF。6. Elasticsearch只是 MySQL 的投影只负责召回初排ES 索引dramas共 10 个字段写侧一次性完成归一化country→region、language→lang、status 1→published、published_at 秒→毫秒读侧只按归一化后的值匹配——禁止两侧各自转换否则口径一定漂。召回用纯 ES 侧的function_scorefilter : statuspublished AND (region?) AND (lang?) must_not : id ∈ 已看剧 score sqrt(0.35·popularity) sqrt(0.30·completion) sqrt(0.25·pay_rate) gauss(published_at, originnow, scale30d, decay0.5) sort _score desc, id desc两条硬规矩ES_score只做初排、圈定 Top 3N 候选不进最终排序分。最终顺序由 Go 侧粗排 Redis 热度叠加决定。写 ES 只有一条路径indexer 全量灌_iddrama_idrefreshtrue天然幂等 upsert。业务服务一律不许直接写 ES。refreshtrue是个小细节但不写就一定会踩默认 1s refresh 周期会造成「灌完立刻查不到」然后开始怀疑查询写错了。增量同步选型是 go-mysql canal 包内嵌一个-mode cdc只订阅dramas维表behavior_events这种高频流明确不走 CDC——它的实时信号已经由 RedisZINCRBY同步写解决了。7. 推荐链路规则打底模型可插拔双链路7.1 生产链路recommend-rpc.GetFeed1) 召回 ES function_scoresize*3未配置/失败 - MySQL popularity 兜底候选 2) 热度 Redis ZREVRANGE heat:{country}:{lang} - 榜内缺失的剧按 id 回 MySQL 补元数据 3) 粗排 rank.Ranker加权特征 region/lang boost 新鲜度衰减 已看降权 4) 精排 MMoE.Enabled 时用精排分**覆盖**粗排分调用失败则保留粗排分 5) 融合 统一叠加热度score 0.15 × rel命中打 hot 理由 6) 输出 排序 - 游标分页 - 页级 MySQL 补查 preview_url/is_paid/free_episode_count第 6 步值得单独说Feed 的展示字段不进 ES 索引。召回文档只带排序需要的字段分页后仅对当前页drama_id做一次SELECT id,preview_url,is_paid,free_episode_count ... WHERE id IN (...)。这样换封面、改预览视频、调免费集数都不需要重建索引。整条链路每一层都能降级ES 挂 → MySQL 召回Redis 挂 → 无热度加成Triton 挂 → 规则粗排分。接口不中断是硬要求宁可掉排序质量。规则粗排本身长这样权重全在 yaml 里可调score0.35·Popularity0.30·Completion0.25·PayRate0.10·exp(-age/30d)(regionMatch ?0.08:0)(langMatch ?0.12:0)-(Seen ?0.40:0)第一阶段故意用可解释规则而不是模型——目的不是排得好而是把数据闭环跑起来曝光 → 点击/观看 → watch_seconds → behavior_events → 推荐。没有这一步MMoE 连训练样本都造不出来。7.2 精排模型mmoe.v1 契约MMoE 一次前向输出 4 个目标融合成单一精排分输入 concat( 5 个 embedding(各 16 维), 8 维 dense ) → 88 │ 4 个 ExpertMLP 88→128→88, ReLU │ 4 个 Gate每目标一个 Linear(88→4)softmax ctr / watch / completion / pay │ 4 个 TowerMLP 88→64→out ctr:1 watch:7 completion:1 pay:1 watch Σ softmax(watch_logits)[i] · midpoints[i] / 900 score 0.20·CTR 0.35·watch 0.25·Completion 0.20·Pay5 个 sparse IDINT64user_id/drama_id基数 1e6 取模region_id/language_id用 FNV-1a 哈希到 256genre_id取模 5128 维 denseFP32user_watch_seconds, user_completion, user_pay_rate, user_sessions, drama_popularity, drama_completion, drama_pay_rate, drama_age_days观看时长 7 分桶中点秒[5,20,45,120,240,450,900]训练样本按 timestamp80/10/10 时间切分禁用随机切分防特征穿越契约一致性是这个模块最容易出事的地方schema.py训练、config.pbtxtTriton I/O、builder.go的Names/BuildV1在线、mmoe_client.go调用四处必须完全一致任一顺序/维度漂移都是静默错位打分——不报错只是排序莫名其妙变差。所以约定任何契约变更必须 bump 版本mmoe.v2并新建版本目录不就地改 v1。回滚也简单紧急情况下把MMoE.Enabled置 falseFeed 立刻退回规则粗排零停机。ONNX 二进制和训练 checkpoint 一律不入 Git仓库只存配方。8. 媒体链路预签名直传 FFmpeg HLS 多云抽象业务服务只保存视频元数据和播放地址视频字节一律不过应用服务器Admin - POST /api/v1/admin/episodes/:id/upload 只传 filename/content_type/provider - media-rpc.CreateUpload ├─ 读存储设置system_settings密钥字段 AES-256-GCM 加密 └─ 生成 OSS / S3 预签名 PUT URL - 浏览器直传对象存储API 不承载视频带宽 - POST .../upload/complete ├─ 预签名 HEAD 校验对象存在 记录 provider/key/size └─ 异步启动 FFmpeg worker - 生成 master.m3u8 TS 分片 - 回传对象存储 - video_statusREADY - 播放返回短时签名 URL付费剧先查 user_entitlements对象布局按国家/语言分片直接支撑 CDN 路由和多语言版本管理short-drama/{country}/{language}/{drama_id}/{episode_id}/ ├── source/original.mp4 └── source/hls/master.m3u8 seg_*.ts几个设计点Storage 接口 AdapterOSS/S3/LOCAL三个实现未来加 R2、COS 不动业务层。请求里的provider优先于全局default_provider允许一部剧的不同集放不同后端。LOCAL后端只为单机跑通全链路不需要云凭证。它带来一个真实约束go-zero 路由没有*通配object key 只能走 query 参数于是master.m3u8在写入时就改写成绝对 URL每个分片引用变成{base}/media/files?object...否则 hls.js 解析相对路径必然 404。异步 worker 必须处理重启残留。worker 是普通 goroutine进程重启会留下一堆永久卡在UPLOADED/PROCESSING的剧集所以启动时把所有这类行翻成FAILED并附重试提示——此刻必然没有 worker 在跑动作是安全的。video_status的列默认值曾经写成READY导致从没上传过视频的剧集被标成「可播放」。修默认值 修历史数据012_video_status_empty.sql并在新建 episode 时显式写EMPTY。列默认值是能骗人的状态机要显式初始化。9. 鉴权、权益与密钥管理用户端auth-api负责注册/登录签发 JWTHS256C 端网关和管理端各自校验。解锁判定以剧级字段为准逐集is_paid退居次要freeAll !drama.is_paid unlocked freeAll || episode_no drama.free_episode_count // 付费剧前 N 集免费 || 命中 user_entitlements已购买unlockedfalse时后端直接抹空该集video_url前端据此显示 并引导去结算。门禁必须在后端做、并且以「返回空字段」而不是「返回地址靠前端不播」的方式实现。支付Stripe 走 PaymentIntent服务端建单 → 客户端拿client_secret→ webhook 确认 → 写user_entitlementsPayPal 走 Orders v2CAPTURE → approve URL → capture → webhook。密钥只存在于服务端环境变量客户端只拿 publishable key。运行时配置存数据库system_settings密钥类字段用SETTINGS_ENCRYPTION_KEY必须正好 32 字节做 AES-256-GCM 加密管理端 UI 里配 OSS/S3 参数并能一键测试。这里有个精妙的坑见第 11 节。10. 客户端Tauri 2 Vue 3C 端和管理端各一个 Tauri 应用共享技术栈Vue 3 Vite 7 Element Plus hls.jsC 端采用移动端壳层模式底部 Tab 导航 顶部精简标题栏播放页用 hls.js 直接吃 master.m3u8。管理端覆盖剧目 CRUD、剧集管理与上传、订单、用户、系统设置。上传进度和失败原因在列表页显式展示包括把 OSS 返回的Code/MessageXML 前 300 字符抖出来因为云存储的 CORS 失败在浏览器侧连状态码都看不到不显示就等于让运维猜。11. 部署形态业务进容器基础设施留宿主机docker compose 起6 个 rpc 3 个 api共用一个 DockerfileSERVICE 构建参数区分 本机直跑MySQL(13306) / Redis(16379) / Elasticsearch(19200) / Triton(8000) 容器访问宿主机extra_hosts host.docker.internal:host-gateway entrypoint.sh 把配置里的 127.0.0.1 改写成 host.docker.internal这个组合是为了本地开发体验数据库和 ES 用容器起会让每次重装/丢数据变成灾难而业务服务是需要反复重建的那一层。entrypoint.sh那步改写很关键——同一份配置文件要在宿主机和容器里都能跑否则就得维护两份然后一定会漂。12. 踩过的坑可直接当 checklistSETTINGS_ENCRYPTION_KEY二次解密。system_settings.is_secret1的行在设置读取内部就已经解密调用方再Decrypt一次会得到illegal base64 data at input byte N。报错看着像存储配置坏了其实偏移量取决于密钥长度——排查方向完全被带偏。规则读取处解密一次返回明文禁止外层再解。OSS region 必须是 region ID。V4 签名把 region 放进 credential scope写hangzhou而不是cn-hangzhou会得到预签名 URL 403。现在的做法是从标准 endpoint 反推 region推不出就拒绝。预签名 PUT 绕不过 CORS。带Content-Type的 PUT 会触发 preflight桶上没规则时请求根本不到 OSSfetch在任何状态码之前就抛。所以「测试存储参数」会主动发一次未签名 OPTIONS到/_cors-probe——preflight 在鉴权前应答凭证是错的时候也能拿到 CORS 结论。预签名是纯本地计算不联网。所以CreateUpload慢绝不等于「OSS 慢」DeadlineExceeded只能说明 media-rpc 没在应答挂了或者停在调试断点上。端口被抢会让「连不上 ES」看起来像代码问题。本机一个打印控件CLodop长期占 9200容器映射改 19200 后宿主机侧所有配置和文档必须同步改——不同服务用不同端口就是这类事故的温床。event_type存在两套命名裸名PLAY与枚举名EVENT_TYPE_PLAY导致 rebuild 的CASE WHEN EVENT_TYPE_*匹配不到在线写入的数据统计静默漏。教训枚举值必须单一来源且判定「逐集观看」应改用不变特征episode_id 0。ONNX sparse 输入必须导出成[batch,1]。dummy 写成torch.zeros(1)会导出 rank-1Tritondims:[1]max_batch:64直接报InvalidArgument: Invalid rank。模型内部用reshape(-1)展平喂nn.Embeddingdummy 用torch.zeros(1,1)。同一 MySQL 用户127.0.0.1与localhost是两个独立账号DSN 必须按服务的真实访问路径逐个验证别拿一个能连就认为都能连。GOOSlinux 环境变量残留会让 Windows 下go test ./...全军覆没报的错还和测试本身无关。多个 vite dev 实例共享.vite缓存会造成 browserHash 漂移表现为「页面莫名白屏/资源 404」。13. 当前进度与下一步诚实版清单不宣称没做的东西已完成阶段状态P0 数据闭环服务端埋点 → MySQL Redis✅ 已通C 端前台埋点 ❌ 待接P1 ES 索引构建recdemo indexer 全量幂等灌数✅P3 热度榜 ZSet事件加权 7 天滑动 rebuild 重放✅P2 ES 召回进生产含三层降级✅P4 MMoE 精排Triton 契约 mmoe.v1代码就绪默认EnabledfalseP5 重排去重、多样性、运营位、付费引导❌ 待做-mode stats从 behavior_events 聚合回写 popularity/completion/pay_rate❌ 待做——否则 ES 三个 float 字段恒为 0打分退化-mode cdcgo-mysql canal 订阅 dramas❌ 规划中用户侧特征接 user-rpc / behavior-rpc❌ 目前 dense 里user_*是占位精排的用户信号很弱下一步顺序基本锁死前台埋点 → stats 产出真实 dense → 前台埋点攒出样本 → 打开 MMoE → 重排。14. 四条我认为值得抄走的原则事实源唯一派生全部可重建。每个 Redis / ES 结构都要能回答「从哪张表重放」。答不上来就不许上线。可插拔 ≠ 可选。模型层必须带默认关闭的开关和一条真正跑过的降级路径否则「可插拔」只是 PPT。契约集中定义、多点校验、变更即 bump 版本。三处以上消费同一契约训练/serving/在线时靠纪律不如靠版本号。先把闭环跑通再谈算法。规则排序很土但它能立刻暴露出「哪个指标根本没有产生方」——这类问题越早发现越便宜。附仓库结构api/ drama.api / drama-admin.api / auth.api 3 个 goctl 生成的网关 rpc/ 6 个 zRPC 服务 ent/Ent schema 与生成代码 pb/ internal/ cache(Redis) / db(MySQL) / model / repository / settings(加解密) / medialocal recdemo/ 独立 moduleseed / index / rebuild / serve / train含 model/mmoe(PyTorchONNX) 与 deploy/triton/model_repository/mmoe pkg/auth/ JWT 签发与校验 proto/ .proto 契约源 deploy/ dockerDockerfile entrypoint、mysql/init/*.sql、es admin-tauri/ 管理端Tauri2 Vue3 client-tauri/ C 端Tauri2 Vue3 hls.js Stripe docs/ 分层文档架构、内容契约、ES、Redis、MMoE 排序/训练、媒体上传、支付、设置 scripts/ goctl 生成脚本、smoke test Makefile infra-up / gen / gen-api / gen-rpc / gen-ent / test需要我把它调成更短的「公众号/知乎版」或者补一节具体代码比如GetFeed的降级实现、Feature Builder 的哈希归一化作为技术深挖附录吗