企业官网建设流程全解析

• 开发工具
• CLI

本篇技术指南围绕 devenv 项目的services.redis模块展开，系统讲解如何在声明式的 devenv 开发环境中一键启用 Redis 进程、自定义监听端口与绑定地址、追加redis.conf配置，以及利用 unix socket 模式规避端口冲突。读者读完本文后，将能根据项目需求灵活编排 Redis 的启动、就绪检查与数据目录，并理解该功能在 redis.nix 模块 中的具体实现原理。

services.redis是 devenv 内置的服务模块之一，用于在开发环境中声明式地启动一个受进程管理器监督的 Redis 实例。它默认提供完整的数据目录、TCP 或 unix socket 两种监听方式，以及内置的 readiness（就绪）探针，使 Redis 无需手工守护进程即可随devenv up自动启动并参与进程间的依赖编排。该模块的官方选项文档位于 docs/src/content/docs/services/redis.md，其选项定义与实现代码集中在 src/modules/services/redis.nix。

快速启用：最小配置示例

在项目的devenv.nix中加入以下配置即可启用 Redis：

{ pkgs, ... }: { services.redis.enable = true; }

启用后，devenv 会把redis-server加入当前环境的packages，注册一个名为redis的受监督进程，并暴露REDISDATA环境变量。随后运行：

devenv up

Redis 即会在默认端口6379上启动并进入就绪状态。停止后台进程可执行devenv down（即devenv processes down的简写），在 CI 等场景中也可用devenv processes wait --timeout 120等待所有进程就绪。

配置选项全解析

本节完整覆盖 services/redis 选项文档 中定义的 5 个配置项，并逐一结合 redis.nix 的源码实现说明其作用与边界。

services.redis.enable

是否启用 Redis 进程并暴露相关工具与环境变量。

• 类型：boolean
• 默认值：false
• 示例：true

services.redis.enable = true;

对应源码中mkEnableOption "Redis process and expose utilities"（redis.nix）。置为true后，模块才会注册redis进程、注入环境变量并把 Redis 包加入packages。此外，模块通过lib.mkRenamedOptionModule [ "redis" "enable" ] [ "services" "redis" "enable" ]（redis.nix）兼容了旧版顶层redis.enable写法，迁移时旧配置会被自动重定向到新命名空间，无需手工修改。

注意：由于config.services.redis.enable是一个可被其他模块读取的普通选项，cli-options 测试用例 演示了如何在env中引用它（如REDIS_ENABLED = builtins.toString config.services.redis.enable），说明该选项同样可以作为跨模块组合的输入。

services.redis.package

指定要使用的 Redis 软件包，便于切换到特定版本或自定义构建。

• 类型：package
• 默认值：pkgs.redis

services.redis.package = pkgs.redis;

在源码中，package被用于生成启动脚本（redis.nix）：exec ${cfg.package}/bin/redis-server ...，同时以cfg.package的形式加入packages。也就是说，最终运行的二进制、启动脚本中的redis-server以及就绪探测用的redis-cli都来自同一个包实例，保证客户端与服务器版本一致。

services.redis.bind

Redis 监听的 IP 接口地址。

• 类型：null or string
• 默认值："127.0.0.1"
• 示例："127.0.0.1"

当值为null时表示监听所有网络接口（"all interfaces"）；值为具体字符串时，该字符串会作为bind指令写入生成的redis.conf（redis.nix）：

services.redis.bind = "127.0.0.1"; # 仅本机访问 # services.redis.bind = null; # 监听所有接口（慎用，存在暴露风险）

从源码看，bind默认"127.0.0.1"是面向本地开发的安全默认值；需要被局域网或容器内其他服务访问时才应显式放宽。

services.redis.port

Redis 接受 TCP 连接所用的端口号。

• 类型：16 bit unsigned integer（取值范围 0～65535，含两端）
• 默认值：6379

services.redis.port = 6379;

关键行为（源码 redis.nix）：当port = 0时，Redis 完全不监听 TCP socket，而是改用 unix socket，socket 文件路径通过环境变量$REDIS_UNIX_SOCKET暴露；只有port != 0时才会走进程端口分配机制，把basePort交由config.processes.redis.ports.main.value解析（redis.nix）。也就是说，即使多个 devenv 项目同时启用 Redis，端口分配器也能避免冲突；而 unix socket 模式则从根本上绕开了端口占用问题。

services.redis.extraConfig

追加到redis.conf末尾的额外文本，用于按需覆盖或补充 Redis 行为。

• 类型：strings concatenated with "\n"（多行字符串按换行拼接）
• 默认值："locale-collate C"

services.redis.extraConfig = '' maxmemory 128mb maxmemory-policy allkeys-lru appendonly yes '';

源码中extraConfig以原样追加在port、bind、unixsocket指令之后（redis.nix），因此可通过它设置持久化（AOF/RDB）、内存上限、日志级别等任何受支持的redis.conf指令。默认值locale-collate C用于固定排序规则，保证在不同系统 locale 下行为一致。

模块实现原理：从配置到进程

要理解上述选项如何生效，可以跟踪 src/modules/services/redis.nix 中配置到进程的完整转换链路。

生成 redis.conf

模块先把所有监听相关选项渲染成一份独立的配置文件（redis.nix）：

redisConfig = pkgs.writeText "redis.conf" '' port ${toString allocatedPort} ${optionalString (cfg.bind != null) "bind ${cfg.bind}"} ${optionalString (allocatedPort == 0) "unixsocket ${REDIS_UNIX_SOCKET}"} ${optionalString (allocatedPort == 0) "unixsocketperm 700"} ${cfg.extraConfig} '';

可见其生成的指令与选项一一对应：port写入解析后的实际端口；bind仅在非null时写入；unix socket 模式下同时写入unixsocket路径与unixsocketperm 700（socket 权限限定为当前用户）；最后追加extraConfig。

启动脚本与数据目录

启动脚本（redis.nix）负责创建数据目录并以非守护模式前台运行：

if [[ ! -d "$REDISDATA" ]]; then mkdir -p "$REDISDATA" fi exec ${cfg.package}/bin/redis-server ${redisConfig} --daemonize no --dir "$REDISDATA"

其中$REDISDATA默认指向${config.env.DEVENV_STATE}/redis（redis.nix），即 devenv 项目状态目录下的redis/子目录，保证每个项目的 Redis 数据彼此隔离；--daemonize no确保redis-server以前台方式运行，便于进程管理器接管监督与退出码跟踪。

环境变量注入

启用后模块向环境中注入（redis.nix）：

• REDISDATA：Redis 数据目录，始终可用；
• REDIS_UNIX_SOCKET：仅当port = 0（unix socket 模式）时设置，路径为${config.env.DEVENV_RUNTIME}/redis.sock（redis.nix）；TCP 模式下该变量为null，不进入环境。

应用代码可通过读取这两个环境变量来适配连接方式，无需硬编码端口。

就绪检查（readiness probe）

redis进程自带就绪探测（redis.nix），两种模式分别使用redis-cli ping：

ready = { exec = if allocatedPort == 0 then unixSocketPing else tcpPing; initial_delay = 2; probe_timeout = 4; failure_threshold = 5; };

• TCP 模式：redis-cli -p <port> ping
• unix socket 模式：redis-cli -s ${REDIS_UNIX_SOCKET} ping

参数含义：启动 2 秒后开始探测（initial_delay），单次探测超时 4 秒（probe_timeout），连续 5 次失败判定进程不健康（failure_threshold）。这使依赖 Redis 的其他进程可以在其就绪后再启动，实现声明式的启动顺序编排。

实战场景：unix socket 模式与端口冲突规避

当services.redis.port = 0时，模块完全不监听 TCP 端口，只创建权限为700的 unix socket。仓库中的 tests/redis-socket/devenv.nix 给出了官方测试配置：

{ ... }: { services.redis = { enable = true; port = 0; }; }

适用场景包括：

• 端口占用频繁的开发环境：多项目并存时无需管理端口号；
• 只允许本机进程访问：unix socket 天然不暴露到网络接口，安全性更高；
• 与bind协同：unix socket 模式下bind指令不写入配置，TCP 层完全关闭。

连接方式改为读取环境变量：

redis-cli -s "$REDIS_UNIX_SOCKET"

结合其他模块的组合用法

services.redis常与其他 devenv 模块组合使用：

• 进程编排：Redis 作为受监督进程之一，可被devenv up统一拉起，并参与 processes 文档 描述的依赖与就绪机制；
• Profiles 多环境切换：在 profiles.mdx 中，Redis 启用项可放入特定 profile，实现不同环境（如本地/CI）下按需开启；
• 第三方应用集成：如 WordPress 集成文档 所示，启用services.redis.enable = true后即可为应用提供 Redis 后端。

配置项速查表

下表汇总services.redis全部选项，便于快速查阅（与 选项文档 保持一致）：

注意事项与限制

• port = 0时进程端口分配机制不再生效，$REDIS_UNIX_SOCKET指向${DEVENV_RUNTIME}/redis.sock，应用需显式使用该路径；
• 默认绑定127.0.0.1仅限本机访问；如需跨主机访问，请显式设置bind并自行评估暴露风险；
• 本模块生成的是单实例 Redis；高可用集群、哨兵等拓扑需通过extraConfig或自定义进程另行实现；
• 数据目录默认位于${DEVENV_STATE}/redis，随 devenv 项目状态管理，清理状态目录会同时清除 Redis 数据。

• 开发工具
• CLI