Authelia 缓存集成指南:使用 Redis Standalone 与 Redis Sentinel 实现会话外部存储
Authelia 缓存集成指南:使用 Redis Standalone 与 Redis Sentinel 实现会话外部存储
Authelia 在默认情况下使用进程内(in-memory)会话存储,这在单实例部署中开箱即用,但在多实例、高可用架构下会让每个实例各自持有用户会话状态,导致会话不一致。本指南以官方缓存集成参考文档(docs/content/reference/integrations/cache-integrations.md)为主体,结合配置参考(docs/content/configuration/session/redis.md)与源码实现,系统讲解 Authelia 唯一支持的两种外部缓存集成方式——Redis Standalone 与 Redis Sentinel,包括版本支持策略、完整配置示例、参数逐项说明以及底层实现原理,帮助你为生产环境搭建真正无状态、可横向扩展的会话层。
支持范围:只有 Redis 是外部缓存选项
Authelia 目前为"会话(session)"这类缓存信息提供的外部存储支持仅有两种 Redis 部署形态,其余场景全部回退到内存存储:
- Redis Standalone(单实例):适合中小规模部署,配置简单,一个连接地址即可。
- Redis Sentinel(哨兵高可用):提供主从自动故障转移,适合生产环境与高可用部署。
- memory(进程内):默认选项,即完全不配置
session.redis时使用的存储,会话数据仅存在于当前 Authelia 进程内存中。
这一点在官方缓存集成参考文档中明确说明:当前只为会话等缓存信息支持 Redis Standalone 与 Redis Sentinel(除内存之外)。从源码看,会话存储的选择逻辑集中在 internal/session/provider_config.go 的 NewSessionProvider 函数中:当 config.Redis != nil 时走 Redis 分支,否则回退到 memory provider。
为什么生产环境必须关注这一点? 内存会话存储使 Authelia 处于"有状态"(stateful)状态——如果部署了多个 Authelia 实例,用户登录后写入实例 A 的会话,后续请求被负载均衡转发到实例 B 时会话失效。在 Kubernetes 或多副本的高可用场景下,必须配置外部会话存储,使所有实例共享同一份会话数据。
Redis 版本支持策略
关于 Redis 的版本支持,官方文档给出的策略非常明确:
- Standalone 模式:支持 Redis 官方自身仍在维护支持周期内的版本,具体以 Redis 官方的 release cycle 文档为准,通常即当前最新可用版本。
- Sentinel 模式:同样支持 Redis 官方维护的版本,通常为最新可用版本。
需要特别注意的是,在缓存集成参考文档编写时存在一条明确的限制说明(callout):
由于 Redis Sentinel 在 7.x 中引入了破坏性变更,目前仅支持 Redis Sentinel 6.x,该问题计划在近期解决。
也就是说,如果你计划使用 Sentinel 高可用方案,请以官方 release 与更新日志中关于 Sentinel 版本支持的说明为准,选择兼容的 Redis Sentinel 版本;而 Standalone 模式没有这一限制。这一限制源于底层使用的 Go 会话库(github.com/fasthttp/session/v2 的 redis provider,见 internal/session/provider_config.go)与 Redis Sentinel 协议之间的兼容性问题。
在配置文件中启用 Redis 会话存储
Redis 会话存储的配置位于全局配置文件的 session.redis 小节。官方配置模板给出了完整的注释示例,见 internal/configuration/config.template.yml。
一个覆盖 Standalone 与 Sentinel 的完整配置骨架如下:
session:
secret: 'your_session_secret'
redis:
host: '127.0.0.1'
port: 6379
timeout: '5s'
max_retries: 0
username: 'authelia'
password: 'authelia'
database_index: 0
maximum_active_connections: 8
minimum_idle_connections: 0
tls:
server_name: 'myredis.example.com'
skip_verify: false
minimum_version: 'TLS1.2'
maximum_version: 'TLS1.3'
high_availability:
sentinel_name: 'mysentinel'
sentinel_username: 'sentinel_user'
sentinel_password: 'sentinel_specific_pass'
nodes:
- host: 'sentinel-node1'
port: 26379
- host: 'sentinel-node2'
port: 26379
route_by_latency: false
route_randomly: false
其中 session.secret 用于加密写入 Redis 的会话数据(详见下文"数据加密"小节),在使用 Redis 存储时是必填项。
Standalone 模式配置详解
Standalone 模式只需要 host 与 port 即可工作,其余参数可选。以下逐项说明各配置参数的含义、默认值与注意事项(默认值定义见 internal/configuration/schema/session.go 的 DefaultRedisConfiguration)。
host
- 类型:string,必填
- 含义:Redis 服务器主机名或 Unix socket 路径。
当使用 Unix socket 时,直接填写 socket 文件路径(此时无需设置 port):
session:
redis:
host: '/var/run/redis/redis.sock'
当使用 IPv6 字面量地址时,必须用方括号包裹并加引号:
session:
redis:
host: '[fd00:1111:2222:3333::1]'
从源码看,Authelia 通过 port 是否为 0 来区分 TCP 与 Unix socket 连接:当 port == 0 时网络协议自动切换为 unix,地址直接使用 host;否则按 host:port 建立 TCP 连接(见 internal/session/provider_config.go)。相应地,配置校验器要求 Standalone 模式下 host 必填(见 internal/configuration/validator/session.go)。
port
- 类型:integer,默认
6379 - 含义:Redis 监听端口。
timeout
- 类型:duration,默认
5 seconds - 含义:Redis 连接超时时间,支持
5s、5 seconds等常见时长语法。
max_retries
- 类型:integer,默认
0 - 含义:命令失败时的最大重试次数,设置为
0表示完全禁用重试。注意源码中的默认值是0,与官方配置模板注释示例中的3略有差异,实际生效默认值以 schema 中的DefaultRedisConfiguration为准。
username 与 password
- 类型:string,均可选;
password标记为 secret,支持通过 Authelia 的 secrets 机制注入 - 含义:Redis 认证凭据。
username仅在 Redis 6.0+ 的 ACL 认证中需要,普通requirepass密码认证场景通常无需配置用户名。
配置参考文档强烈建议 password 使用 64 位以上的随机字母数字字符串(可通过 authelia crypto rand --length 64 --charset alphanumeric 之类的命令生成),并同步修改 Redis 侧的用户密码。
database_index
- 类型:integer,默认
0 - 含义:Redis 数据库索引号,等价于 Redis
SELECT命令指定的数据库编号。多租户或与其他应用共享 Redis 实例时可用此参数隔离数据。
maximum_active_connections
- 类型:integer,默认
8 - 含义:同一时刻允许打开的 Redis 最大连接数。配置校验器会将其校正为至少为 1(
<= 0时回落到默认值 8)。
minimum_idle_connections
- 类型:integer,默认
0 - 含义:保持空闲的最小连接数(不超过最大活跃连接数)。当建立连接的延迟较高时,保持一定数量的空闲连接可以降低请求等待时间。
tls
- 类型:结构体,可选
- 含义:一旦定义即启用 TLS 连接,并控制 TLS 校验参数,包括
server_name、skip_verify、minimum_version(默认TLS1.2)、maximum_version(默认TLS1.3)、certificate_chain与private_key(用于 Redis 要求双向 TLS 客户端认证的场景)。
默认情况下,Authelia 使用系统证书信任库校验 TLS 证书,并可通过全局 certificates_directory 选项追加信任的 CA 证书。校验器会将 TLS 配置的默认 server_name 自动填充为 redis.host(见 internal/configuration/validator/session.go),因此只要证书 SAN 匹配主机名,通常无需显式配置 server_name。
Sentinel 高可用模式配置详解
启用 Sentinel 只需在 session.redis 下定义 high_availability 小节,同时必须指定 sentinel_name。Sentinel 模式下 Authelia 通过哨兵节点发现当前 Redis 主节点,并在故障转移后自动切换,实现会话层的高可用。相关默认值见 internal/configuration/schema/session.go 的 DefaultRedisHighAvailabilityConfiguration(默认端口 26379)。
sentinel_name
- 类型:string,必填
- 含义:Redis Sentinel 的 master 名称。注意这是 Sentinel 配置中定义的主节点别名,不是主机名。校验器强制要求该值非空,否则报错(见 internal/configuration/validator/session.go)。
sentinel_username 与 sentinel_password
- 类型:string,均可选(
sentinel_password在提供sentinel_username时必填,且标记为 secret) - 含义:Sentinel 连接凭据。二者同时提供时使用 ACL 认证;仅提供密码时使用传统
requirepass认证。注意 Sentine l自身的凭据与上方普通 Redis 节点的username/password是独立配置的。
nodes
- 类型:列表,可选但推荐
- 含义:Sentinel 节点列表,用于负载均衡地与哨兵通信。每个节点包含
host与port(默认26379)。
配置规则:session.redis.host 与 nodes 至少定义其一,二者可同时定义并自动合并;这里的 host 必须是 Sentinel 主机,而不是普通 Redis 节点。实际的数据读写节点由 Sentinel 命令动态发现,无需手工指定。
route_by_latency 与 route_randomly
- 类型:boolean,默认均为
false - 含义:二者控制如何从多个 Sentinel 节点中选择连接目标:
route_by_latency: true优先选择低延迟节点;route_randomly: true随机选择节点。
从源码看,Sentinel 分支通过 redis.NewFailover 构建故障转移 provider,RouteByLatency 与 RouteRandomly 会被原样传递给底层库(见 internal/session/provider_config.go)。
底层实现:会话存储是怎么被选中的
理解 NewSessionProvider 的实现有助于把握两种模式的行为差异(完整逻辑见 internal/session/provider_config.go):
- 模式选择:根据
config.Redis是否为nil决定使用内存还是 Redis;Redis 分支再根据HighAvailability.SentinelName是否非空决定走 Sentinel(redis.NewFailover)还是 Standalone(redis.New)。 - 数据加密:只要使用 Redis 存储,会话数据都会通过
NewEncryptingSerializer(config.Secret)加密后写入,即session.secret负责加密会话载荷,避免明文会话数据落入 Redis。 - 键前缀:写入 Redis 的会话键统一使用
authelia-session前缀,便于与其他应用的数据隔离和排查。 - 连接参数映射:
timeout→ 拨号超时,max_retries→ 失败重试次数,database_index→ DB 编号,maximum_active_connections→ 连接池大小,minimum_idle_connections→ 最小空闲连接数,tls→ TLS 配置,全部逐项映射到底层库的Config结构。 - 会话 ID:会话 ID 由 32 字节加密随机数生成,字符集经过过滤映射,保证 ID 的不可预测性(见 internal/session/provider_config.go)。
配置校验阶段(internal/configuration/validator/session.go)会在启动前拦截常见错误:使用 Redis 时 session.secret 必填、Standalone 模式 host 必填、端口必须在 1–65535 之间、Sentinel 模式必须提供 sentinel_name 且 host/nodes 至少其一、节点主机不能为空等,确保错误配置在服务启动时即被发现。
选型建议与安全要点
结合上述内容,给出实践层面的建议:
- 单实例/测试环境:保持默认的内存 provider 即可,无需引入 Redis。
- 生产多副本部署:务必配置 Redis。若对可用性要求较高,优先选择 Sentinel 高可用模式,并确认 Redis Sentinel 版本符合官方支持策略(参考上文版本说明)。
- 安全基线:为 Redis 设置强密码(推荐 64 位以上随机字符串)、启用 TLS 传输加密、通过
database_index隔离数据,并妥善保管session.secret(可通过 Authelia secrets 机制注入,避免明文写入配置文件)。 - 高可用前提:Redis 会话存储使 Authelia 变为无状态组件,这是多副本横向扩展的前提;但请同步评估 Redis 自身的高可用(Sentinel 故障转移)与存储持久化策略,避免 Redis 成为新的单点。
总结
Authelia 的外部缓存集成围绕会话数据展开,官方支持且仅支持 Redis 这一种外部缓存后端,并提供 Standalone 与 Sentinel 两种部署形态。Standalone 配置轻量、适用于常规生产部署;Sentinel 提供故障转移能力,是高可用架构下的推荐选择。结合 config.template.yml 的完整注释模板、redis.md 的参数级参考以及 provider_config.go 的源码实现,你可以精确掌控从连接、认证、TLS 到高可用的每一个环节,为生产环境构建稳定、无状态的会话层。