尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

Infisical 本地 Redis Cluster 搭建指南:从 docker-compose 到生产连接配置

Infisical 本地 Redis Cluster 搭建指南:从 docker-compose 到生产连接配置 Infisical 本地 Redis Cluster 搭建指南从 docker-compose 到生产连接配置【免费下载链接】infisicalInfisical is the open-source platform for secrets, certificates, and privileged access management.项目地址: https://gitcode.com/GitHub_Trending/in/infisical本指南围绕仓库中 sink/redis-cluster 目录下的 Redis Cluster 部署方案展开讲解如何用 Docker Compose 在单机拉起一套 3 节点 Redis Cluster含 RedisInsight 可视化管理端并将其接入 Infisical 后端Node.js 版backend与 Go 版backend-go作为分布式缓存与任务队列底座。读完本文你将掌握集群端口的含义与参数调优、初始化与验证命令、干净重启流程以及 Infisical 侧REDIS_CLUSTER_HOSTS环境变量的实际连接语义与源码级实现原理。为什么需要 Redis ClusterInfisical 对缓存后端的三种模式Infisical 的缓存与队列基础设施基于 Redis后端配置层为 Redis 预留了三种连接形态单机模式REDIS_URL、Cluster 集群模式REDIS_CLUSTER_HOSTS以及 Sentinel 哨兵模式REDIS_SENTINEL_HOSTS。这一点在 backend-go/internal/database/redis/redis.go 中有清晰体现NewClientFromEnvConfig会按 有REDIS_URL→ 走单机、有 Cluster 节点列表 → 走集群、有 Sentinel 列表 → 走哨兵 的优先级依次判断三者都未配置时直接返回错误no Redis configuration found: set REDIS_URL, REDIS_CLUSTER_HOSTS, or REDIS_SENTINEL_HOSTS。Cluster 模式的价值在于数据按哈希槽hash slot自动分片到多个主节点配合副本实现横向扩展与故障转移避免单点内存成为瓶颈。仓库在 sink/redis-cluster 下提供了一套开箱即用的本地集群编排文件本文后续的所有操作均以 docker-compose.yml 与 README.md 为蓝本。如果你需要的是高可用哨兵方案而非分片集群可参考仓库中并列提供的 sink/redis-sentinel 与 docker-compose.sentinel.yml。编排文件逐项拆解三个数据节点 初始化容器 管理界面sink/redis-cluster/docker-compose.yml 一共定义了 5 个服务其中 3 个是真正承载数据的 Redis 节点服务名角色对外端口集群总线端口持久化卷redis-node-1主节点 1700117001redis-node-1-data:/dataredis-node-2主节点 2700217002redis-node-2-data:/dataredis-node-3主节点 3700317003redis-node-3-data:/dataredis-insight可视化 UI5540——redis-cluster-init一次性初始化———每个数据节点都基于redis:7镜像并显式配置了以下服务端参数--port 7001/7002/7003客户端监听端口Infisical 后端通过该端口读写数据。--cluster-enabled yes开启集群模式节点会参与槽分配与 gossip 通信。--cluster-config-file nodes.conf节点本地保存的集群状态文件。--cluster-node-timeout 5000节点间互相判定失联的超时时间毫秒超过该值会触发故障转移。--appendonly yes开启 AOF 持久化数据落到挂载的 named volume 中容器重建不丢数据。--bind 0.0.0.0监听所有网卡允许宿主机及其他容器访问。--cluster-announce-ip 192.168.1.33向集群其他节点广播的对外 IP。这是整个方案中最关键的配置项必须替换为你宿主机的真实局域网 IP否则节点之间用容器内 IP 互相广播宿主机外的客户端如 Infisical 后端容器将无法连接。--cluster-announce-port 7001与--cluster-announce-bus-port 17001分别广播客户端端口与集群总线端口。总线端口固定为客户端端口 10000用于节点间的 gossip 与控制消息因此每个节点需要映射两个端口。redis-cluster-init是编排中的胶水容器它depends_on三个数据节点先sleep 10等待节点完全就绪然后执行redis-cli --cluster create 192.168.1.33:7001 192.168.1.33:7002 192.168.1.33:7003 --cluster-yes完成槽分配最后输出Cluster initialized。由于设置了restart: no它只会运行一次不会在集群初始化完成后反复重启。快速开始三步拉起集群第一步替换 IP 地址先把 docker-compose.yml 中所有192.168.1.33替换成你当前系统的局域网 IP共 3 处--cluster-announce-ip与初始化命令中的 3 个节点地址。README 给出了在 Linux 上快速获取本机 IP 的方法ifconfig | grep inet | grep -v 127.0.0.1 | awk {print $2} | head -1若ifconfig不可用也可用hostname -I | awk {print $1}获取。注意不要使用127.0.0.1或localhost否则宿主机之外的客户端尤其是以容器方式运行的 Infisical 后端将无法通过广播地址回连节点。第二步启动集群在 sink/redis-cluster 目录下执行docker compose up -d首次启动会依次拉起 3 个数据节点与 RedisInsight随后redis-cluster-init自动完成redis-cli --cluster create的槽分配。由于初始化容器内置了 10 秒等待可通过以下命令观察初始化结果docker logs redis-cluster-init # 期望输出: Cluster initialized第三步验证集群状态连接任意节点查看集群信息docker exec redis-node-1 redis-cli -p 7001 cluster info正常输出中cluster_state:ok表示集群健康、槽分配完整。还可进一步验证槽分布与节点视图docker exec redis-node-1 redis-cli -p 7001 cluster nodes docker exec redis-node-1 redis-cli -p 7001 cluster slots连接信息速查Redis Cluster 入口YOUR_IP:7001、YOUR_IP:7002、YOUR_IP:7003YOUR_IP替换为实际 IP。RedisInsight 管理界面http://localhost:5540可在 UI 中添加上述任意节点地址RedisInsight 会自动发现集群其余成员。干净重启彻底重置集群如果集群状态被污染例如 nodes.conf 中的 IP 与当前环境不一致、槽分配异常可先销毁全部容器与数据卷再重建docker compose down -v # 如宿主机 IP 发生变化先更新 docker-compose.yml 中的 IP docker compose up -d其中-v会删除redis-node-1-data、redis-node-2-data、redis-node-3-data三个命名卷让节点以全新的nodes.conf重新完成槽分配。需要说明的是由于本方案是3 个节点互为副本的主节点最小形态未额外配置--cluster-replicasdocker compose down -v属于破坏性操作会清空全部缓存数据仅适用于测试与开发环境。接入 Infisical 后端环境变量与连接语义README 提供了外部 Docker Compose 引用集群的片段原文使用REDIS_CLUSTER_URLS作为示例environment: - REDIS_CLUSTER_URLSredis://YOUR_IP:7001,redis://YOUR_IP:7002,redis://YOUR_IP:7003这里需要特别澄清该变量名是 README 的示意写法。从本仓库实际源码看Infisical 后端识别的环境变量是REDIS_CLUSTER_HOSTS且其取值不是带redis://前缀的 URL而是逗号分隔的host:port列表。证据如下在 backend/src/lib/config/env.ts 中REDIS_CLUSTER_HOSTS被声明为可选字符串描述为Comma-separated list of Redis Cluster host:port pairs. Eg: 192.168.65.254:6379,192.168.65.254:6380。在 backend-go/internal/config/config.go 中Go 版同样读取REDIS_CLUSTER_HOSTS并附带两个可选开关REDIS_CLUSTER_ENABLE_TLS默认 false与REDIS_CLUSTER_AWS_ELASTICACHE_DNS_LOOKUP_MODE默认 false。因此接入时正确写法是services: backend: environment: - REDIS_CLUSTER_HOSTS192.168.1.33:7001,192.168.1.33:7002,192.168.1.33:7003 # 如节点启用了密码/TLS还需补充 # - REDIS_USERNAMEdefault # - REDIS_PASSWORDyourpassword # - REDIS_CLUSTER_ENABLE_TLStrue完整的集群相关配置项可归纳如下与TRedisConfigKeys定义对应见 backend/src/lib/config/redis.ts环境变量说明默认值REDIS_CLUSTER_HOSTS逗号分隔的host:port节点列表至少给出一个可达节点无REDIS_CLUSTER_ENABLE_TLS是否以 TLS 连接集群节点falseREDIS_CLUSTER_AWS_ELASTICACHE_DNS_LOOKUP_MODEAWS ElastiCache 专用跳过 DNS 解析、原样直连地址falseREDIS_USERNAME/REDIS_PASSWORD集群认证凭据透传给 ioredis/go-redis无源码级原理Infisical 如何与 Cluster 协同Node.js 后端ioredis Cluster 客户端Node 版后端在 backend/src/lib/config/redis.ts 中基于ioredis构建集群客户端其行为与本仓库编排方案高度契合dnsLookup仅当REDIS_CLUSTER_AWS_ELASTICACHE_DNS_LOOKUP_MODEtrue时传入旁路解析函数(address, callback) callback(null, address)跳过 DNS 查询以适配 AWS ElastiCache 的集群寻址机制。retryDelayOnClusterDown: 300集群整体不可用CLUSTERDOWN时每 300ms 重试一次避免热点轮询。redisOptions透传username、password与tls配置。reconnectOnError当错误信息包含READONLY故障转移期间主节点降级为副本时旧连接会被拒绝写操作时返回2即重连并重发命令实现故障转移场景下的无缝重试。此外 redis.ts 的attachConnectionLogging为集群客户端挂了节流日志node error事件按错误码:节点地址维度分别节流10 秒窗口避免单个故障节点刷爆日志close/ready事件配合记录连接中断—恢复生命周期并在恢复时清空节流计数。Go 后端go-redis Cluster 客户端Go 版实现 backend-go/internal/database/redis/redis.go 与 Node 版保持行为对齐通过redis.NewClusterClient创建客户端Addrs由hostPortAddrs把REDIS_CLUSTER_HOSTS解析后的host:port拼装而成MaxRetries固定为 3并注释说明其对应 Node 版reconnectOnError在READONLY错误下的行为——go-redis 会把该连接标记为坏连接并从连接池剔除下次重试时重新建立连接并做新的 DNS 解析启用 TLS 时强制MinVersion: tls.VersionTLS12。文件头部注释还点明了设计意图go-redis 会自动处理 READONLY/MOVED/ASK 重定向这正是集群模式下客户端必须内建的能力。集群语义对业务代码的约束hash tag集群分片意味着多键操作必须落在同一个槽内否则服务端会返回CROSSSLOT错误。Infisical 的定时任务模块为此专门做了约束在 backend/src/lib/cron/cron-job.ts 与 cron-job.ts 中所有写入的 key 都统一挂在单个集群 hash tag 下并要求keyPrefix必须包含非空的 hash tag例如{cron}否则在构造时报错cron: keyPrefix ... must contain a non-empty Redis Cluster hash tag, e.g. {cron}。对应的单测 cron-job.test.ts 专门验证了这一不变量多键 LuaEVAL传入的 key 必须共享同一 hash tag否则集群模式下每个入队 tick 都会静默失败——这是从业务层面对集群安全的兜底。另一个底层组件 backend/src/lib/red-lock/index.ts 的分布式锁同样同时支持Redis与Cluster两种客户端类型说明锁的加解锁路径已按集群语义设计。常见问题与排查建议cluster_state:fail或-MISCONF Redis is configured to save RDB snapshots通常是槽分配未完成或节点间广播地址不通。确认docker-compose.yml中的--cluster-announce-ip与初始化命令的 IP 一致然后执行上述干净重启流程。外部容器连接超时检查--bind 0.0.0.0是否保留、宿主机防火墙是否放行7001-7003与17001-17003端口。总线端口10000漏映射或未放行是常见的隐蔽故障源。后端报CLUSTERDOWN Hash slot not served说明初始化容器尚未完成或失败docker logs redis-cluster-init查看redis-cli --cluster create输出。READONLY You cant write against a read only replica多为故障转移过程中的瞬时错误Infisical 两端客户端均已内置自动重连重发逻辑见上文reconnectOnError与 go-redis 的坏连接剔除机制通常无需干预。小结本方案用一份 docker-compose.yml 完成了 Redis Cluster 的单机仿真三个redis:7节点承载分片、redis-cluster-init自动建群、RedisInsight 提供可视化管理而 Infisical 的 Node.js 与 Go 后端分别通过 ioredis 与 go-redis 的 Cluster 客户端接入。理解--cluster-announce-ip的广播语义、端口与总线端口的映射关系以及REDIS_CLUSTER_HOSTS的真实取值格式是在本仓库基础上把测试集群平滑迁移到多机或云环境如 AWS ElastiCache的关键前提——后者的 TLS 与 DNS 旁路模式也已由REDIS_CLUSTER_ENABLE_TLS、REDIS_CLUSTER_AWS_ELASTICACHE_DNS_LOOKUP_MODE两个开关原生支持。【免费下载链接】infisicalInfisical is the open-source platform for secrets, certificates, and privileged access management.项目地址: https://gitcode.com/GitHub_Trending/in/infisical创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表