BFE mod_session_sticky 模块基础配置详解:会话粘滞缓存与 Redis 分布式模式配置指南

原创2026-10-11 11:40:561,968 阅读
文章标签:后端网络/通信云原生

BFE mod_session_sticky 模块基础配置详解:会话粘滞缓存与 Redis 分布式模式配置指南

mod_session_sticky.conf 是 BFE(Baidu Front End,百度自研的七层负载均衡)中 mod_session_sticky 会话粘滞模块的基础配置文件,用于声明规则配置文件路径、粘滞缓存类型(本地 LRU 或 Redis 分布式缓存)以及 Redis 连接参数。本文以该配置文件为核心,结合仓库源码、规则配置文件与真实示例,完整讲解每个配置项的含义、默认值与校验规则,并给出可直接落地的本地缓存与 Redis 两种模式配置方案,帮助你正确启用并调优会话粘滞能力。

模块定位:会话粘滞解决什么问题

在负载均衡场景中,同一用户的多次请求需要被持续转发到同一台后端实例(例如维持登录态、Session 数据、AI 对话上下文),这就是会话粘滞(Session Sticky)。mod_session_sticky 模块在 BFE 中承担这一职责,其内部按"产品(Product)维度"配置规则,支持两种粘滞实现:

  • Cookie 模式:BFE 将后端地址信息加密后写入用户 Cookie,后续请求通过解密 Cookie 直接定位后端;
  • Sticky 模式:从请求的 Cookie、Header、URL 参数或 JSON 请求体中提取 sticky ID,通过 ID 到后端的映射表(本地 LRU 缓存或 Redis)完成粘滞。

模块源码位于 bfe_modules/mod_session_sticky/mod_session_sticky.go,其注册入口见 bfe_modules/bfe_modules.go#L165-L166,在 conf/bfe.conf 中通过 Modules = mod_session_sticky 启用(见 conf/bfe.conf#L84)。

模块在初始化时注册两个过滤器(Filter)形成完整的"解码-编码"闭环(见 mod_session_sticky.go#L299-L308):

  • decodeHandler 注册于 HandleAfterLocation 阶段:在请求转发前解析 Cookie/Sticky ID,还原后端信息;
  • encodeHandler 注册于 HandleReadResponse 阶段:在响应返回前写入 Cookie 或更新 ID 到后端的映射缓存。

基础配置(Basic)逐项说明

mod_session_sticky.conf 使用 INI 格式(经 gopkg.in/gcfg.v1 解析,见 conf_mod_session_sticky.go#L55-L71)。基础配置项如下:

配置项 类型 含义 必填 补充说明 生效条件
Basic.DataPath String 规则配置文件路径 是 默认值为 mod_session_sticky/session_sticky.data;类型为 FilePath,支持相对或绝对路径,文件必须存在且可读 相对路径以 BFE 配置根目录为基准解析
Basic.CacheSize Integer Sticky 模式下的缓存容量 否 默认值为 10000;仅在 CacheType 为 local 时生效 非负整数
Basic.CacheType String 缓存类型 否 默认值为 local;合法值为 local(LRU 缓存)或 redis(Redis 分布式缓存) 取值仅限 local、redis
Log.OpenDebug Boolean 模块调试开关 否 开启后输出模块内部调试日志 -

关于默认值,源码 conf_mod_session_sticky.go#L73-L88 中的 Check() 方法给出了更精确的实现事实:

  • DataPath 未配置时自动回退为 mod_session_sticky/session_sticky.data,并通过 bfe_util.ConfPathProc 将其解析为基于配置根目录的绝对路径;
  • CacheSize 若小于 10000,会被强制抬升回 10000(即实际下限为 10000);
  • CacheType 为空时默认置为 local(保持向后兼容),若填写了 local/redis 之外的任意值,加载直接报错:CacheType must be 'local' or 'redis'。

Redis 配置(Redis)逐项说明

当 CacheType 设置为 redis 时,Sticky 模式的 ID→后端映射存放在 Redis 中,此时以下 Redis 参数全部为必填(条件必填),结构定义见 conf_mod_session_sticky.go#L38-L47:

配置项 类型 含义 必填 补充说明 生效条件
Redis.Bns String BNS 服务名 条件必填 当 CacheType 为 redis 时必须提供 需能解析出合法的 Redis 服务地址
Redis.ConnectTimeout Integer 连接超时(毫秒) 条件必填 当 CacheType 为 redis 时必须提供 正整数
Redis.ReadTimeout Integer 读超时(毫秒) 条件必填 当 CacheType 为 redis 时必须提供 正整数
Redis.WriteTimeout Integer 写超时(毫秒) 条件必填 当 CacheType 为 redis 时必须提供 正整数
Redis.MaxIdle Integer 最大空闲连接数 条件必填 当 CacheType 为 redis 时必须提供 非负整数
Redis.MaxActive Integer 最大活跃连接数 条件必填 当 CacheType 为 redis 时必须提供;0 表示不限制 非负整数
Redis.Password String Redis 密码 条件必填 当 CacheType 为 redis 时必须提供;空字符串表示无密码 -
Redis.ExpireSeconds Integer 缓存过期时间(秒) 条件必填 当 CacheType 为 redis 时必须提供 正整数

源码校验逻辑(conf_mod_session_sticky.go#L95-L112)会在 Redis 模式下依次检查:

  • 调用 redis_client.CheckRedisConf 校验 Bns 的可解析性(底层实现见 bfe_util/redis_client/client.go#L97-L104);
  • ConnectTimeout、ReadTimeout、WriteTimeout、ExpireSeconds 必须大于 0,否则返回对应错误。

初始化时,这些参数会被组装为 redis_client.Options 并创建 Redis 客户端(mod_session_sticky.go#L272-L287);其中 Wait 固定为 false,即连接池达到 MaxActive 上限时不等待归还连接。Redis 中粘滞映射的 key 统一带前缀 bfe:stickyid:(常量 StickyRedisKeyPrefix,见 mod_session_sticky.go#L40-L42),值为包含 addr、port、sub_cluster、created_at 的 JSON 结构(mod_session_sticky.go#L170-L176),写入使用带过期时间的 Setex 命令(mod_session_sticky.go#L492-L508)。

完整配置示例

本地缓存模式(Local Cache Mode)

以下为官方文档示例(docs/en_us/configuration/mod_session_sticky/mod_session_sticky.conf.md#L35-L45):

[Basic]
DataPath = mod_session_sticky/session_sticky.data
CacheSize = 10000
CacheType = local

[Log]
OpenDebug = true

仓库自带的真实运行配置(conf/mod_session_sticky/mod_session_sticky.conf)还展示了同时保留 Redis 段落、并实际启用本地模式的写法——Redis 段仅在 CacheType = redis 时才会被校验,可作为生产环境的参考模板:

[basic]
DataPath = mod_session_sticky/mod_session_sticky.data
CacheSize = 100000
CacheType = local

[redis]
# bns addr
bns = BFE.poc-redis-wx

# timeout in ms
connectTimeout = 20
readTimeout = 20
writeTimeout = 20
expireSeconds = 3600

# max idle connections
maxIdle = 20

[log]
OpenDebug = false

注意:gcfg 解析对 section 名大小写不敏感,[Basic]/[basic]、[Log]/[log] 均可。

Redis 缓存模式(Redis Cache Mode)

以下为官方文档示例(docs/en_us/configuration/mod_session_sticky/mod_session_sticky.conf.md#L47-L65):

[Basic]
DataPath = mod_session_sticky/session_sticky.data
CacheType = redis

[Redis]
Bns = redis.service
ConnectTimeout = 1000
ReadTimeout = 1000
WriteTimeout = 1000
MaxIdle = 10
MaxActive = 100
Password =
ExpireSeconds = 3600

[Log]
OpenDebug = true

几点实操建议:

  • Bns 在百度内部通常指向一个 BNS(Baidu Naming Service)服务名,由客户端负责按名字解析出 Redis 实例列表;部署在 BNS 之外的环境时,需确认使用的 Redis 客户端实现支持直连地址;
  • ExpireSeconds = 3600 表示映射 1 小时后过期,可结合粘滞会话的实际生命周期调整;
  • MaxActive = 0 表示连接数不设上限,高并发场景建议给出明确上限并配合 MaxIdle 一起规划;
  • 两种模式的差异在于:本地 LRU 缓存的容量受 Basic.CacheSize 限制且每个 BFE 实例独立,Redis 模式则跨实例共享映射并受 ExpireSeconds 控制过期——多实例部署下使用 Redis 模式才能保证粘滞一致性。

DataPath 指向的规则配置文件

Basic.DataPath 指向的规则文件(session_sticky.data)决定每个产品(Product)采用哪种粘滞方式,完整字段说明见 docs/en_us/configuration/mod_session_sticky/session_sticky.data.md,其中与本基础配置直接相关的要点包括:

  • Type 取值 Cookie(默认)或 Sticky——Sticky 模式下才需要本配置文件中的缓存(local/redis)来存放 ID→后端映射;
  • CookieKey 默认 bfe_ssbl,MaxAge 默认 3600 秒;
  • MaskCode / StandbyMaskCode 用于 Cookie 模式加密,长度不得小于 4(常量 MinMaskCodeLen,见 product_rule_load.go#L35);
  • 若规则里同时配置了 Cond,则仅当请求匹配条件时才应用该粘滞规则;Cond 语法参见 docs/en_us/condition/condition_grammar.md。

仓库中可供参考的规则文件示例包括 conf/mod_session_sticky/mod_session_sticky.data(空规则占位)以及测试用规则 bfe_modules/mod_session_sticky/test_data/mod_session_sticky/mod_session_sticky.data(含 default_t() 与 req_path_prefix_in("/unittest", true) 两种条件写法)。

两种缓存模式的底层实现

从 mod_session_sticky.go#L432-L508 可以看到,模块将缓存访问抽象为统一的读写接口:

  • 本地模式:初始化时创建 lru_cache.NewLRUCache(cfg.Basic.CacheSize)(mod_session_sticky.go#L288-L291),按 sticky ID 直接存取 *bfe_basic.SessionStickyBackend 对象;
  • Redis 模式:getBackendFromRedis 以 bfe:stickyid: + ID 为 key 执行 Get,反序列化 JSON 还原后端;setBackendToRedis 以 Setex 写入并设置过期时间。

后端信息的结构体定义为 SessionStickyBackend(bfe_basic/common.go#L110-L115),包含 ip、port、subcluster、renewtime 四个字段。Cookie 模式下,BFE 将后端信息 JSON 序列化后,用主掩码码(MaskCode)做逐字节异或(doMask,mod_session_sticky.go#L617-L625)再 Base64 编码写入 Cookie;解码时先尝试主掩码,失败则回退到备用掩码(StandbyMaskCode),这正是备用掩码存在的意义(mod_session_sticky.go#L340-L351)。

配置加载与热更新机制

模块初始化时通过 ConfLoad 读取 mod_session_sticky.conf(conf_mod_session_sticky.go#L54-L71),随后调用 loadConfData 加载 DataPath 指向的规则文件并写入 ProductRuleTable(带读写锁的规则表,见 product_rule_table.go)。规则文件支持热更新:模块注册了 WebHandleReload 处理器(mod_session_sticky.go#L316-L319),通过 BFE 的 web monitor 接口下发 reload 请求即可在不重启进程的情况下刷新粘滞规则;同时注册的 WebHandleMonitor 处理器可查询模块运行状态。模块状态指标(metrics.State)用于统计粘滞命中情况,可在 BFE 监控页面查看。

小结

mod_session_sticky.conf 虽短小,却是会话粘滞能力的总开关:Basic.DataPath 决定规则从哪来,Basic.CacheType 决定 Sticky 模式的映射缓存放哪里,Redis.* 一组参数则决定了分布式缓存的连接质量与数据生命周期。配置时把握三个要点即可:一是 CacheType 只能取 local/redis 且大小写敏感于取值校验;二是切到 Redis 模式必须补齐全部 8 个 Redis 参数,否则加载失败;三是多实例部署优先选择 Redis 模式以保证粘滞映射全局一致。结合仓库内的 conf/mod_session_sticky/mod_session_sticky.conf 与 conf/mod_session_sticky/mod_session_sticky.data 两份样例,即可快速搭建起可运行的会话粘滞配置。

登录后查看全文
bfe