Budibase 本地 TLS Redis 复现环境搭建指南rediss:// 加密连接与 ACL 凭据完整实践【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibase本指南围绕 hosting/redis-tls/README.md 展开讲解如何在本地用 Docker 启动一个强制要求 TLSrediss://、ACL 用户名与 ACL 密码三重验证的 Redis 实例用于复现和排查 Budibase 的 Redis 连接问题。读完本文你将掌握证书生成、Docker 编排、自定义凭据注入、Budibase.env对接以及容器内redis-cli加密连通性测试的完整操作链并能从源码层面理解 Budibase 是如何解析REDIS_URL、判定 TLS 并注入用户名密码的。一、这套环境解决什么问题Budibase 的正常运行依赖 Redis 承担会话、缓存、锁、限流等职责参见 packages/backend-core/src/redis/utils.ts 中定义的Databases与SelectableDatabase枚举覆盖会话、用户缓存、标志位、许可证、Socket.IO、限流等十余个 keyspace。在生产或某些安全要求较高的部署中Redis 往往不是裸连接而是启用 TLS 加密传输连接串前缀为rediss://redis://对应非加密通过 Redis 6 的 ACL 机制限制访问要求显式提供 username 与 password。当此类环境出现连接失败、握手超时、认证被拒等问题时很难在纯内存 mock如ioredis-mock或普通本地 Redis 上复现。本仓库提供的hosting/redis-tls目录就是为此设计的本地复现沙箱它一次性把「TLS ACL 用户名 ACL 密码」三种条件全部拉满让你可以在本地稳定复现并排查 Budibase 的 Redis 连接问题。二、目录结构与三个核心文件在动手之前先看清hosting/redis-tls/与相关文件的角色文件作用generate-certs.sh用 OpenSSL 生成本地自签名 CA 与服务器证书redis.confRedis 服务端 TLS 与 ACL 加载配置start.sh容器启动入口动态生成 ACL 用户文件后拉起redis-serverdocker-compose.redis-tls.yaml编排 Redis 7.4 容器、端口映射、证书与数据卷挂载整个流程分为五步生成证书 → 启动容器 → 修改.env指向 → 连通性测试 → 停止清理。下面逐一展开。三、第 1 步生成本地证书Budibase 的 TLS Redis 需要一套本地自签名的 CA 与服务器证书。执行chmod x hosting/redis-tls/generate-certs.sh ./hosting/redis-tls/generate-certs.sh脚本会输出TLS certs generated in ...提示并在hosting/redis-tls/certs/下生成四个文件ca.crt、ca.key、server.crt、server.key其中ca.key与server.key权限被收紧为 600见脚本末尾的chmod 600。从脚本实现看generate-certs.sh它实际做了三层工作生成自签名根 CA使用openssl req -x509RSA 2048、SHA-256、有效期 3650 天主题为CNBudibase Redis TLS CA并显式附加basicConstraintscritical,CA:TRUE、keyUsagecritical,keyCertSign,cRLSign等扩展使其具备签发下级证书的能力生成服务器证书请求CSR主题为CNlocalhost用 CA 签发服务器证书通过server.ext扩展文件指定subjectAltNameDNS:localhost,IP:127.0.0.1、extendedKeyUsageserverAuth随后用 CA 私钥签发有效期为 3650 天最后清理 CSR、扩展文件与序列号文件。这一步的关键在于 SAN 同时覆盖了DNS:localhost与IP:127.0.0.1否则客户端按主机名或 IP 校验服务器身份时都会失败。四、第 2 步用 Docker 启动 TLS Redis证书生成完毕后启动容器docker compose -f hosting/docker-compose.redis-tls.yaml up -ddocker-compose.redis-tls.yaml会创建一个名为budi-redis-tls-dev的容器使用的镜像为redis:7.4-alpine并把宿主机端口6381可通过REDIS_TLS_PORT覆盖映射到容器内 Redis 的 TLS 端口6379。启动时依次挂载./redis-tls/redis.conf→ 容器内/usr/local/etc/redis/redis.conf只读./redis-tls/start.sh→ 容器内/usr/local/bin/redis-tls-start.sh只读作为启动命令./redis-tls/certs→ 容器内/certs只读命名卷redis_tls_data→ 容器内/data用于持久化数据。再看 redis.conf服务端的 TLS 形态一目了然bind 0.0.0.0 protected-mode no port 0 tls-port 6379 tls-cert-file /certs/server.crt tls-key-file /certs/server.key tls-ca-cert-file /certs/ca.crt tls-auth-clients no aclfile /usr/local/etc/redis/users.acl dir /data几个值得注意的细节port 0表示完全关闭明文端口只有tls-port 6379对外提供服务这意味着客户端只能走加密连接tls-auth-clients no表示服务端不要求客户端出示自己的证书只做服务端身份认证mTLS 之外最常见的单向 TLS 形态aclfile指向users.aclACL 用户由启动脚本动态写入。4.1 使用自定义凭据默认情况下用户名与密码分别是aaa/bbb。需要自定义时通过环境变量覆盖即可REDIS_TLS_USERNAMEaaa REDIS_TLS_PASSWORDbbb REDIS_TLS_PORT6381 docker compose -f hosting/docker-compose.redis-tls.yaml up -d对应的默认值定义在 compose 文件的environment段REDIS_TLS_USERNAME: ${REDIS_TLS_USERNAME:-aaa}、REDIS_TLS_PASSWORD: ${REDIS_TLS_PASSWORD:-bbb}端口为${REDIS_TLS_PORT:-6381}即三个变量均支持按需覆盖且带有安全默认值。4.2 ACL 用户是如何生成的容器启动命令是/bin/sh /usr/local/bin/redis-tls-start.sh即 start.sh。它依次做了三件事校验/certs下三个证书文件是否存在缺失时直接报错提示“先运行 generate-certs.sh”并退出校验REDIS_TLS_USERNAME与REDIS_TLS_PASSWORD是否已设置未设置同样报错退出在 compose 中因为有默认值一般不会触发动态写出 ACL 文件并启动 Rediscat /usr/local/etc/redis/users.acl EOF user default off user ${REDIS_TLS_USERNAME} on ${REDIS_TLS_PASSWORD} allcommands allkeys allchannels EOF exec redis-server /usr/local/etc/redis/redis.conf这段 ACL 的核心语义是user default off把默认用户彻底关闭任何不携带凭据的连接都会被拒绝随后为自定义用户名开启账户并绑定密码授予allcommands allkeys allchannels全量权限。这正好对应文档开头强调的“ACL username ACL password”双重认证要求——没有用户名密码连 TLS 握手之后的认证环节都过不去。五、第 3 步让 Budibase 指向本地 TLS Redis修改你本地的 Budibase.env加入或覆盖以下三个变量REDIS_URLrediss://localhost:6381 REDIS_USERNAMEaaa REDIS_PASSWORDbbbREDIS_URL的前缀rediss://是启用 TLS 的关键信号REDIS_USERNAME与REDIS_PASSWORD对应上一步配置的 ACL 凭据。若你使用了自定义凭据请同步替换后两个变量。5.1 源码视角Budibase 如何解析这些变量Budibase 在 packages/backend-core/src/environment.ts 中定义REDIS_URL: process.env.REDIS_URL || localhost:6379, REDIS_PASSWORD: process.env.REDIS_PASSWORD, REDIS_USERNAME: process.env.REDIS_USERNAME,注意REDIS_URL的默认值是localhost:6379非 TLS、无凭据因此只有当你在.env中显式设置rediss://前缀时连接才会走加密通道。真正的解析逻辑在 packages/backend-core/src/redis/utils.ts 的getRedisConnectionDetails()与getRedisOptions()getRedisConnectionDetails()会剥离//协议前缀若 URL 中内嵌了user:passhost或:passhost形式的凭据也会被解析出来且REDIS_USERNAME/REDIS_PASSWORD优先级更高username username || credentials[0]端口解析失败时回退为 6379 默认值getRedisOptions()中通过env.REDIS_URL.toLowerCase().startsWith(rediss://)判定是否启用 TLS——命中则向 ioredis 传入tls: {}选项否则tls为undefined。这就是为什么连接串前缀必须严格写作rediss://。此外packages/backend-core/src/redis/redis.ts 的init()会优先使用ioredis-mock当MOCK_REDIS为真时或根据REDIS_CLUSTERED选择单点new Redis(getRedisOptions())还是集群new Cluster(...)在真实复现场景中请确保MOCK_REDIS处于关闭状态否则不会真正打到本地 TLS Redis。5.2 测试佐证packages/backend-core/src/redis/tests/redis.spec.ts 用testcontainers启动真实 Redis 容器并设置requirepass然后以redis://username:passwordhost:port形式注入REDIS_URL断言getRedisConnectionDetails()能正确拆出host、port、username、password。这套测试印证了「URL 内嵌凭据 独立环境变量」两种注入方式在 Budibase 中的解析行为是一致的也说明凭据解析与连接细节是经过单测保障的关键逻辑。六、第 4 步快速连通性测试启动 Budibase或单独验证 Redis 可达性前可以直接在容器内使用真实 Redis 客户端做加密连通测试docker exec -it budi-redis-tls-dev redis-cli --tls --cacert /certs/ca.crt -h localhost -p 6379 --user aaa -a bbb ping参数说明参数含义--tls启用 TLS 连接--cacert /certs/ca.crt指定用于校验服务端证书的 CA 证书这是自签名场景下信任链的关键-h localhost -p 6379容器内直接访问自身 TLS 端口 6379--user aaa -a bbb携带 ACL 用户名与密码预期输出PONG如果这里能拿到PONG说明证书链、TLS 握手、ACL 认证三层全部打通此时 Budibase 侧连接失败通常应归结为.env变量问题如端口、用户名、密码不一致而非 Redis 本身。七、第 5 步停止并清理复现、排查完毕后停止并彻底清理环境含数据卷docker compose -f hosting/docker-compose.redis-tls.yaml down -v-v会连同redis_tls_data命名卷一并删除确保下次启动是从干净状态开始。若只想临时停用而保留数据可以去掉-v或改用docker compose stop。八、常见问题与排查要点结合文档步骤与源码实现遇到连接异常时建议按以下顺序检查证书是否已生成hosting/redis-tls/certs/下必须存在ca.crt、server.crt、server.key若缺失start.sh 会直接拒绝启动并提示先执行generate-certs.sh。REDIS_URL前缀是否正确必须为rediss://否则 utils.ts 中startsWith(rediss://)判定失败连接将退回明文而本环境明文端口port 0已关闭必然失败。凭据是否与 ACL 一致REDIS_USERNAME/REDIS_PASSWORD必须与启动容器时使用的REDIS_TLS_USERNAME/REDIS_TLS_PASSWORD默认aaa/bbb一致。端口是否对齐宿主机侧是6381对应.env中rediss://localhost:6381容器内是6379对应redis-cli的-p 6379二者不要混用。是否误用 mock确认MOCK_REDIS未被置位否则请求不会真正到达本地 TLS Redis 实例。九、总结hosting/redis-tls提供了一条从零到一的本地 TLS Redis 复现路径generate-certs.sh产出自签名 CA 与服务器证书redis.conf关闭明文端口并开启tls-portstart.sh动态写入 ACL 用户docker-compose.redis-tls.yaml把镜像、端口、证书与数据卷一次性编排好而 Budibase 侧只需在.env中配置REDIS_URLrediss://...与对应的 ACL 凭据即可在真实加密、带认证的 Redis 上复现和定位连接问题。配合 packages/backend-core/src/redis/utils.ts 的 URL 解析逻辑与 redis.spec.ts 的凭据解析测试这套本地沙箱既能当排障工具也能作为理解 Budibase Redis 连接模型的活教材。【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Budibase 本地 TLS Redis 复现环境搭建指南：rediss:// 加密连接与 ACL 凭据完整实践
Budibase 本地 TLS Redis 复现环境搭建指南rediss:// 加密连接与 ACL 凭据完整实践【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibase本指南围绕 hosting/redis-tls/README.md 展开讲解如何在本地用 Docker 启动一个强制要求 TLSrediss://、ACL 用户名与 ACL 密码三重验证的 Redis 实例用于复现和排查 Budibase 的 Redis 连接问题。读完本文你将掌握证书生成、Docker 编排、自定义凭据注入、Budibase.env对接以及容器内redis-cli加密连通性测试的完整操作链并能从源码层面理解 Budibase 是如何解析REDIS_URL、判定 TLS 并注入用户名密码的。一、这套环境解决什么问题Budibase 的正常运行依赖 Redis 承担会话、缓存、锁、限流等职责参见 packages/backend-core/src/redis/utils.ts 中定义的Databases与SelectableDatabase枚举覆盖会话、用户缓存、标志位、许可证、Socket.IO、限流等十余个 keyspace。在生产或某些安全要求较高的部署中Redis 往往不是裸连接而是启用 TLS 加密传输连接串前缀为rediss://redis://对应非加密通过 Redis 6 的 ACL 机制限制访问要求显式提供 username 与 password。当此类环境出现连接失败、握手超时、认证被拒等问题时很难在纯内存 mock如ioredis-mock或普通本地 Redis 上复现。本仓库提供的hosting/redis-tls目录就是为此设计的本地复现沙箱它一次性把「TLS ACL 用户名 ACL 密码」三种条件全部拉满让你可以在本地稳定复现并排查 Budibase 的 Redis 连接问题。二、目录结构与三个核心文件在动手之前先看清hosting/redis-tls/与相关文件的角色文件作用generate-certs.sh用 OpenSSL 生成本地自签名 CA 与服务器证书redis.confRedis 服务端 TLS 与 ACL 加载配置start.sh容器启动入口动态生成 ACL 用户文件后拉起redis-serverdocker-compose.redis-tls.yaml编排 Redis 7.4 容器、端口映射、证书与数据卷挂载整个流程分为五步生成证书 → 启动容器 → 修改.env指向 → 连通性测试 → 停止清理。下面逐一展开。三、第 1 步生成本地证书Budibase 的 TLS Redis 需要一套本地自签名的 CA 与服务器证书。执行chmod x hosting/redis-tls/generate-certs.sh ./hosting/redis-tls/generate-certs.sh脚本会输出TLS certs generated in ...提示并在hosting/redis-tls/certs/下生成四个文件ca.crt、ca.key、server.crt、server.key其中ca.key与server.key权限被收紧为 600见脚本末尾的chmod 600。从脚本实现看generate-certs.sh它实际做了三层工作生成自签名根 CA使用openssl req -x509RSA 2048、SHA-256、有效期 3650 天主题为CNBudibase Redis TLS CA并显式附加basicConstraintscritical,CA:TRUE、keyUsagecritical,keyCertSign,cRLSign等扩展使其具备签发下级证书的能力生成服务器证书请求CSR主题为CNlocalhost用 CA 签发服务器证书通过server.ext扩展文件指定subjectAltNameDNS:localhost,IP:127.0.0.1、extendedKeyUsageserverAuth随后用 CA 私钥签发有效期为 3650 天最后清理 CSR、扩展文件与序列号文件。这一步的关键在于 SAN 同时覆盖了DNS:localhost与IP:127.0.0.1否则客户端按主机名或 IP 校验服务器身份时都会失败。四、第 2 步用 Docker 启动 TLS Redis证书生成完毕后启动容器docker compose -f hosting/docker-compose.redis-tls.yaml up -ddocker-compose.redis-tls.yaml会创建一个名为budi-redis-tls-dev的容器使用的镜像为redis:7.4-alpine并把宿主机端口6381可通过REDIS_TLS_PORT覆盖映射到容器内 Redis 的 TLS 端口6379。启动时依次挂载./redis-tls/redis.conf→ 容器内/usr/local/etc/redis/redis.conf只读./redis-tls/start.sh→ 容器内/usr/local/bin/redis-tls-start.sh只读作为启动命令./redis-tls/certs→ 容器内/certs只读命名卷redis_tls_data→ 容器内/data用于持久化数据。再看 redis.conf服务端的 TLS 形态一目了然bind 0.0.0.0 protected-mode no port 0 tls-port 6379 tls-cert-file /certs/server.crt tls-key-file /certs/server.key tls-ca-cert-file /certs/ca.crt tls-auth-clients no aclfile /usr/local/etc/redis/users.acl dir /data几个值得注意的细节port 0表示完全关闭明文端口只有tls-port 6379对外提供服务这意味着客户端只能走加密连接tls-auth-clients no表示服务端不要求客户端出示自己的证书只做服务端身份认证mTLS 之外最常见的单向 TLS 形态aclfile指向users.aclACL 用户由启动脚本动态写入。4.1 使用自定义凭据默认情况下用户名与密码分别是aaa/bbb。需要自定义时通过环境变量覆盖即可REDIS_TLS_USERNAMEaaa REDIS_TLS_PASSWORDbbb REDIS_TLS_PORT6381 docker compose -f hosting/docker-compose.redis-tls.yaml up -d对应的默认值定义在 compose 文件的environment段REDIS_TLS_USERNAME: ${REDIS_TLS_USERNAME:-aaa}、REDIS_TLS_PASSWORD: ${REDIS_TLS_PASSWORD:-bbb}端口为${REDIS_TLS_PORT:-6381}即三个变量均支持按需覆盖且带有安全默认值。4.2 ACL 用户是如何生成的容器启动命令是/bin/sh /usr/local/bin/redis-tls-start.sh即 start.sh。它依次做了三件事校验/certs下三个证书文件是否存在缺失时直接报错提示“先运行 generate-certs.sh”并退出校验REDIS_TLS_USERNAME与REDIS_TLS_PASSWORD是否已设置未设置同样报错退出在 compose 中因为有默认值一般不会触发动态写出 ACL 文件并启动 Rediscat /usr/local/etc/redis/users.acl EOF user default off user ${REDIS_TLS_USERNAME} on ${REDIS_TLS_PASSWORD} allcommands allkeys allchannels EOF exec redis-server /usr/local/etc/redis/redis.conf这段 ACL 的核心语义是user default off把默认用户彻底关闭任何不携带凭据的连接都会被拒绝随后为自定义用户名开启账户并绑定密码授予allcommands allkeys allchannels全量权限。这正好对应文档开头强调的“ACL username ACL password”双重认证要求——没有用户名密码连 TLS 握手之后的认证环节都过不去。五、第 3 步让 Budibase 指向本地 TLS Redis修改你本地的 Budibase.env加入或覆盖以下三个变量REDIS_URLrediss://localhost:6381 REDIS_USERNAMEaaa REDIS_PASSWORDbbbREDIS_URL的前缀rediss://是启用 TLS 的关键信号REDIS_USERNAME与REDIS_PASSWORD对应上一步配置的 ACL 凭据。若你使用了自定义凭据请同步替换后两个变量。5.1 源码视角Budibase 如何解析这些变量Budibase 在 packages/backend-core/src/environment.ts 中定义REDIS_URL: process.env.REDIS_URL || localhost:6379, REDIS_PASSWORD: process.env.REDIS_PASSWORD, REDIS_USERNAME: process.env.REDIS_USERNAME,注意REDIS_URL的默认值是localhost:6379非 TLS、无凭据因此只有当你在.env中显式设置rediss://前缀时连接才会走加密通道。真正的解析逻辑在 packages/backend-core/src/redis/utils.ts 的getRedisConnectionDetails()与getRedisOptions()getRedisConnectionDetails()会剥离//协议前缀若 URL 中内嵌了user:passhost或:passhost形式的凭据也会被解析出来且REDIS_USERNAME/REDIS_PASSWORD优先级更高username username || credentials[0]端口解析失败时回退为 6379 默认值getRedisOptions()中通过env.REDIS_URL.toLowerCase().startsWith(rediss://)判定是否启用 TLS——命中则向 ioredis 传入tls: {}选项否则tls为undefined。这就是为什么连接串前缀必须严格写作rediss://。此外packages/backend-core/src/redis/redis.ts 的init()会优先使用ioredis-mock当MOCK_REDIS为真时或根据REDIS_CLUSTERED选择单点new Redis(getRedisOptions())还是集群new Cluster(...)在真实复现场景中请确保MOCK_REDIS处于关闭状态否则不会真正打到本地 TLS Redis。5.2 测试佐证packages/backend-core/src/redis/tests/redis.spec.ts 用testcontainers启动真实 Redis 容器并设置requirepass然后以redis://username:passwordhost:port形式注入REDIS_URL断言getRedisConnectionDetails()能正确拆出host、port、username、password。这套测试印证了「URL 内嵌凭据 独立环境变量」两种注入方式在 Budibase 中的解析行为是一致的也说明凭据解析与连接细节是经过单测保障的关键逻辑。六、第 4 步快速连通性测试启动 Budibase或单独验证 Redis 可达性前可以直接在容器内使用真实 Redis 客户端做加密连通测试docker exec -it budi-redis-tls-dev redis-cli --tls --cacert /certs/ca.crt -h localhost -p 6379 --user aaa -a bbb ping参数说明参数含义--tls启用 TLS 连接--cacert /certs/ca.crt指定用于校验服务端证书的 CA 证书这是自签名场景下信任链的关键-h localhost -p 6379容器内直接访问自身 TLS 端口 6379--user aaa -a bbb携带 ACL 用户名与密码预期输出PONG如果这里能拿到PONG说明证书链、TLS 握手、ACL 认证三层全部打通此时 Budibase 侧连接失败通常应归结为.env变量问题如端口、用户名、密码不一致而非 Redis 本身。七、第 5 步停止并清理复现、排查完毕后停止并彻底清理环境含数据卷docker compose -f hosting/docker-compose.redis-tls.yaml down -v-v会连同redis_tls_data命名卷一并删除确保下次启动是从干净状态开始。若只想临时停用而保留数据可以去掉-v或改用docker compose stop。八、常见问题与排查要点结合文档步骤与源码实现遇到连接异常时建议按以下顺序检查证书是否已生成hosting/redis-tls/certs/下必须存在ca.crt、server.crt、server.key若缺失start.sh 会直接拒绝启动并提示先执行generate-certs.sh。REDIS_URL前缀是否正确必须为rediss://否则 utils.ts 中startsWith(rediss://)判定失败连接将退回明文而本环境明文端口port 0已关闭必然失败。凭据是否与 ACL 一致REDIS_USERNAME/REDIS_PASSWORD必须与启动容器时使用的REDIS_TLS_USERNAME/REDIS_TLS_PASSWORD默认aaa/bbb一致。端口是否对齐宿主机侧是6381对应.env中rediss://localhost:6381容器内是6379对应redis-cli的-p 6379二者不要混用。是否误用 mock确认MOCK_REDIS未被置位否则请求不会真正到达本地 TLS Redis 实例。九、总结hosting/redis-tls提供了一条从零到一的本地 TLS Redis 复现路径generate-certs.sh产出自签名 CA 与服务器证书redis.conf关闭明文端口并开启tls-portstart.sh动态写入 ACL 用户docker-compose.redis-tls.yaml把镜像、端口、证书与数据卷一次性编排好而 Budibase 侧只需在.env中配置REDIS_URLrediss://...与对应的 ACL 凭据即可在真实加密、带认证的 Redis 上复现和定位连接问题。配合 packages/backend-core/src/redis/utils.ts 的 URL 解析逻辑与 redis.spec.ts 的凭据解析测试这套本地沙箱既能当排障工具也能作为理解 Budibase Redis 连接模型的活教材。【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考