企业官网建设流程全解析

• 开发工具
• CLI

本文是一份面向开发者的 Varnish 服务配置实战指南，聚焦如何在 devenv 声明式开发环境中一键启用 Varnish 反向代理缓存，并以src/modules/services/varnish.nix模块源码为底层依据，深入讲解services.varnish各配置项的类型、默认值与真实作用。读完本文，你将掌握 VCL 配置编写、内存缓存分配、监听地址与端口自动分配机制，以及varnishadm、varnishlog等日常运维命令的完整用法。

一、模块概览：devenv 中的 Varnish 服务

devenv 通过 Nix 模块系统提供开箱即用的开发服务。services.varnish是其中的缓存服务模块，其全部声明位于 src/modules/services/varnish.nix，启用后会自动完成三件事：

1. 拉起 Varnish 进程：使用varnishd以前台模式（-F）运行，并通过 devenv 的 process 管理器纳入生命周期管理；
2. 暴露运维工具：自动生成varnishadm、varnishtop、varnishhist、varnishlog、varnishstat五个可直接调用的脚本；
3. 注入环境变量：将最终分配的监听端口写入VARNISH_PORT环境变量，方便应用进程读取。

该模块在 docs/src/content/docs/services/varnish.md 中生成了一份完整的选项参考文档，本文在此基础上结合模块源码展开实现细节。

二、启用服务与包选择

2.1 services.varnish.enable

是否启用 Varnish 进程并暴露相关工具。在devenv.nix中按如下方式开启：

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

对应源码中mkEnableOption "Varnish process and expose utilities"的定义（见 src/modules/services/varnish.nix）。

2.2 services.varnish.package

指定要使用的 Varnish 包。默认使用当前 nixpkgs 中的pkgs.varnish，你可以在 devenv.yaml 的nixpkgs配置下引入特定版本或自定义构建的 Varnish 包：

{ pkgs, ... }: { services.varnish = { enable = true; package = pkgs.varnish73; }; }

从源码看，该包决定了两类可执行文件的来源：

• 服务进程：${cfg.package}/bin/varnishd；
• 运维工具：${cfg.package}/bin/varnishadm、varnishtop、varnishhist、varnishlog、varnishstat。

因此更换package会同时影响服务二进制与全部配套工具的版本，保证工具与服务版本一致。

三、VCL 配置与缓存内存分配

3.1 services.varnish.vcl

Varnish 的核心缓存逻辑由 VCL（Varnish Configuration Language）编写。模块默认提供一份最小可用的 VCL 4.0 配置：

services.varnish.vcl = '' vcl 4.0; backend default { .host = "127.0.0.1"; .port = "80"; } '';

该默认配置将后端指向本机 80 端口。在开发环境中这通常不是你要代理的目标，因此几乎总是需要覆盖。例如要代理本机另一个 devenv 服务（如 Caddy 监听的8001端口），可写成：

services.varnish = { enable = true; vcl = '' vcl 4.0; backend default { .host = "127.0.0.1"; .port = "8001"; } sub vcl_recv { # 命中缓存即直接返回，无需回源 } ''; };

模块源码中通过pkgs.writeText "varnish.vcl" cfg.vcl将配置写入临时文件，再由varnishd -f加载，所以你可以使用完整的 VCL 语法，包括vcl_recv、vcl_backend_response、vcl_deliver等子例程，实现缓存策略定制。

3.2 services.varnish.memorySize

分配给 Varnish 的内存缓存大小，对应varnishd的-s malloc,<size>参数。默认"64M"适合轻量开发场景；若需要更大缓存可调整：

services.varnish.memorySize = "256M";

该值可以是64M、1G等任意varnishd支持的存储规格。源码将其直接拼接进启动命令：-s malloc,${toString cfg.memorySize}，并搭配-F（前台运行）、-n ${workingDir}（实例目录，位于${config.env.DEVENV_STATE}/varnish），确保状态文件落在 devenv 管理的可写目录中。

四、监听地址与端口自动分配

4.1 services.varnish.listen

指定 Varnish 监听的主机与端口。默认只监听回环地址127.0.0.1:6081，这是 devenv 的保守默认——开发服务默认不对外暴露。如需监听所有网卡接口可配置为：

services.varnish.listen = "0.0.0.0:6081";

4.2 端口自动分配机制（源码级说明）

这是本模块最有意思的实现细节。虽然你写出了端口，但模块并不会直接使用它，而是走 devenv 的端口分配器（process port allocation）。源码中：

• parsePort/parseHost从cfg.listen中拆出你声明的端口与主机，作为「期望端口」（basePort）；
• allocatedPort = config.processes.varnish.ports.main.value是进程管理器最终分配的端口；
• 实际监听地址为"${host}:${toString allocatedPort}"，且通过processes.varnish.ports.main.allocate = basePort将你的端口作为分配起点提交给端口分配器。

这意味着：当你声明的端口（如6081）已被其他进程占用时，devenv 会自动重新分配一个空闲端口，而你的 VCL 中backend default指向的回源地址不受影响。最终分配的端口会同时写入：

• 进程启动命令-a ${listenAddr}；
• 环境变量env.VARNISH_PORT = allocatedPort。

因此应用代码应通过读取VARNISH_PORT环境变量来获取真实端口，而不是硬编码6081。

五、加载额外 Varnish 模块（VMOD）

5.1 services.varnish.extraModules

Varnish 通过 VMOD 扩展功能。模块文档说明此选项用于加载除内置std之外的 Varnish 模块，例如官方varnish-modules集合：

services.varnish = { enable = true; extraModules = [ pkgs.varnish73Packages.modules ]; };

从源码看，该选项非空时会为varnishd追加两条参数：

• -p vmod_path='<搜索路径>'：将 VMOD 安装目录加入动态库搜索路径（${lib.makeSearchPathOutput "lib" "lib/varnish/vmods" ([cfg.package] ++ cfg.extraModules)}）；
• -r vmod_path：将vmod_path设为只读参数，防止运行时被修改。

也就是说，启用额外模块后，你就能在 VCL 中通过import <module>;使用对应 VMOD 提供的函数。

六、开箱即用的 Varnish 运维命令

启用服务后，devenv 会自动注册五个脚本（见 src/modules/services/varnish.nix），全部通过-n ${workingDir}连接到同一个 Varnish 实例：

例如排查缓存命中情况：

varnishstat # 观察 cache_hit / cache_miss 计数器 varnishlog -g request varnishadm ban 'req.url ~ ^/api/'

这些命令直接使用$@透传参数，行为与系统级 Varnish 完全一致，无需手动指定实例目录。

七、完整实战示例：Varnish 前置缓存 + Caddy 后端

仓库的 examples/varnish/devenv.nix 提供了一个完整的可运行组合：Varnish 作为前置缓存代理，后端由 Caddy 在8001端口提供「Hello, world!」响应。整体配置如下：

{ pkgs, ... }: { services.varnish = { enable = true; package = pkgs.varnish; vcl = '' vcl 4.0; backend default { .host = "127.0.0.1"; .port = "8001"; } ''; }; services.caddy = { enable = true; config = '' { admin off } ''; virtualHosts.":8001" = { extraConfig = '' respond "Hello, world!" ''; }; }; }

部署与验证步骤：

1. 在项目根目录放置上述devenv.nix，执行devenv up启动全部进程；
2. 读取实际端口：echo $VARNISH_PORT（若6081空闲则为6081）；
3. 通过 Varnish 访问后端：curl -s http://127.0.0.1:$VARNISH_PORT/，应看到后端返回的Hello, world!；
4. 用varnishstat观察缓存命中，用varnishlog查看回源细节。

这个示例直观展示了「devenv 服务编排 + Varnish 缓存代理 + 后端进程」三者如何在一个声明式环境中共存。

八、配置项速查表

下表汇总 docs/src/content/docs/services/varnish.md 中记录的全部选项，可直接作为配置速查：

九、小结

通过 devenv 的services.varnish模块，你可以把 Varnish 的安装、配置、启动、端口分配和运维工具全部纳入声明式开发环境，无需手动安装和初始化。核心要点有三：

• 声明式启用：enable = true即完成安装与进程托管，五个运维命令自动可用；
• 端口自动化：声明的listen端口作为分配起点，实际端口写入VARNISH_PORT，应用代码按环境变量读取；
• 完全可控的 VCL：vcl、memorySize、extraModules三个选项提供了对缓存逻辑、内存规格与 VMOD 扩展的完整控制面。

如需查看模块的完整源码声明与示例，可继续阅读 src/modules/services/varnish.nix 和 examples/varnish/devenv.nix。

• 开发工具
• CLI