BFE mod_session_sticky 模块基础配置详解:会话粘滞缓存与 Redis 分布式模式配置指南
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 两份样例,即可快速搭建起可运行的会话粘滞配置。