Authelia 缓存集成指南:使用 Redis Standalone 与 Redis Sentinel 实现会话外部存储

原创2026-09-13 18:06:541,715 阅读
文章标签:认证鉴权单点登录身份认证后端网络安全前端

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):

  1. 模式选择:根据 config.Redis 是否为 nil 决定使用内存还是 Redis;Redis 分支再根据 HighAvailability.SentinelName 是否非空决定走 Sentinel(redis.NewFailover)还是 Standalone(redis.New)。
  2. 数据加密:只要使用 Redis 存储,会话数据都会通过 NewEncryptingSerializer(config.Secret) 加密后写入,即 session.secret 负责加密会话载荷,避免明文会话数据落入 Redis。
  3. 键前缀:写入 Redis 的会话键统一使用 authelia-session 前缀,便于与其他应用的数据隔离和排查。
  4. 连接参数映射:timeout → 拨号超时,max_retries → 失败重试次数,database_index → DB 编号,maximum_active_connections → 连接池大小,minimum_idle_connections → 最小空闲连接数,tls → TLS 配置,全部逐项映射到底层库的 Config 结构。
  5. 会话 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 到高可用的每一个环节,为生产环境构建稳定、无状态的会话层。

登录后查看全文
authelia