包管理器操作系统【免费下载链接】nixpkgsNix Packages collection NixOS项目地址https://gitcode.com/GitHub_Trending/ni/nixpkgs点击查看免费下载Pi-hole 套件在 NixOS 上由两个互补的模块组成services.pihole-ftl提供基于 Dnsmasq 的 DNS 拦截引擎FTLservices.pihole-web则负责部署其 Web 图形界面Dashboard与统计 API用于控制、监控 pihole-FTL。读完本文你将掌握如何在 NixOS 上启用 Pi-hole 仪表盘、精确配置其监听端口与域名并通过services.pihole-ftl.settings的webserver子节对 Web 服务做深度调优同时理解 NixOS 模块如何将配置落盘为pihole.toml。模块定位Web 界面与 FTL 引擎的分工在 NixOS 中Pi-hole 被拆成两个可独立启用的服务模块本文的关联文档位于 nixos/modules/services/web-apps/pihole-web.md其核心定位是The Pi-hole suite provides a web GUI for controlling and monitoring pihole-FTL.即pihole-web是 Pi-hole 套件的控制与监控前端它本身不包含 DNS 解析逻辑而是把 Web 界面Pi-hole 官方 web 仓库构建出的静态资源交给 FTL 内嵌的 Web 服务器基于 CivetWeb来托管。因此services.pihole-web声明式地部署 Web 仪表盘资源、设定访问域名与端口并把结果写入 FTL 的配置services.pihole-ftl真正的 DNS 拦截守护进程同时内嵌 Web 服务器与 JSON API负责实际对外服务。这一分工直接体现在 pihole-web.nix 的配置段L91-L100中启用pihole-web后模块唯一要做的事情就是把hostName、ports、静态资源路径合并进services.pihole-ftl.settings.webserver。换句话说仪表盘是 FTL Web 服务器的一种配置组合。最小可用配置官方文档给出的最小示例原样继承{ services.pihole-web { enable true; ports [ 80 ]; }; }由于模块内部会把services.pihole-ftl.settings.webserver.port设为80FTL 的 Web 服务器而非 Nginx 等独立进程将直接监听 80 端口提供仪表盘。部署后浏览器访问http://pi.hole默认域名即可看到登录界面。值得注意的是仅启用pihole-web并不会自动让 FTL 开始做 DNS 拦截——如果你还需要 DNS 过滤功能应同时启用services.pihole-ftl。二者在 rl-2511.section.md 的发布说明中被一并引入作为 NixOS 25.11 的新功能services.pihole-ftl与services.pihole-web分别对应 DNS 引擎与 Web GUI/API。模块选项全解从 pihole-web.nix 的 options 定义看services.pihole-web只暴露了 4 个选项全部围绕把仪表盘挂到哪个域名、哪个端口这一件事enable布尔开关lib.mkEnableOption Pi-hole dashboard默认false。启用后模块才会向services.pihole-ftl.settings.webserver写入配置。packagelib.mkPackageOption pkgs pihole-web默认使用 nixpkgs 中的pihole-web包当前版本 v6.6见 pkgs/by-name/pi/pihole-web/package.nix。该包从 Pi-hole 官方 web 仓库拉取源码安装阶段把*.lp、img/、scripts/、style/、vendor/等静态资源复制到$out/share/下。你可以在需要锁定特定版本或本地修改资源时覆盖此选项。hostNamehostName lib.mkOption { type lib.types.str; default pi.hole; };仪表盘对外服务的域名默认pi.hole。该值最终写入 FTL 配置中的webserver.domain。如果该域名不在你网络的 DNS 中解析到本机浏览器将无法访问——很多用户在此处自定义为自家局域网域名或在/etc/hosts中做静态映射。ports端口与三种写法这是模块中最核心、也最灵活的选项定义于 pihole-web.nix。其类型为listOf (oneOf [port, str, submodule])即每个元素可以是以下三种形式之一纯端口号lib.types.port即整数如80等价于字符串80字符串可直接书写端口及其后缀如80r、443s、8080o子模块通过port、optional、redirectSSL、ssl四个子选项结构化描述同一语义。字符串后缀规则源码注释与apply转换函数共同确认后缀ooptional该端口绑定失败不视为错误适合与别的服务共用场景例如先启动的 nginx 已占住 80后缀ssecure/SSL该端口用于 TLS 加密连接后缀rredirect非 SSL 端口收到 HTTP 请求后 301 重定向到第一个可用的 SSL 端口。apply函数L70-L87会在求值期把上述三种写法统一规整为逗号分隔的字符串例如{ services.pihole-web { enable true; ports [ 80r 443s ]; }; }会被转换为webserver.port 80r,443s80 端口负责把 HTTP 流量重定向到 443 的 HTTPS 端口。若使用子模块写法{ services.pihole-web { enable true; ports [ { port 80; redirectSSL true; } { port 443; ssl true; } ]; }; }得到的效果与上面完全一致。官方示例中的ports [ 80 ]则被转换为80即仅在 80 端口提供明文 HTTP 服务。进阶配置直接驱动 FTL 的 webserver 子节文档明确指出仪表盘可进一步通过services.pihole-ftl.settings配置尤其是webserver子节。这是与底层配置模板对接的通道——services.pihole-ftl.settings会以 TOML 格式整体生成pihole.toml见 pihole-ftl.nix 的pkgs.formats.toml与 L490-L496 的/etc/pihole/pihole.toml落盘。模板本身随包分发即 pihole.tomlpihole-ftl.passthru.settingsTemplate其中[webserver]一节完整描述了所有可调项webserver 基础项domainWeb 界面服务的域名pihole-web的hostName会覆盖它默认pi.holeport监听端口列表支持80o,443os,[::]:80o,[::]:443os这类混合 IPv4/IPv6 写法也支持127.0.0.1:80指定绑定地址若为空字符串则 Web 服务器完全不启动——这正是 FTL 模块默认行为webserver.port 见 pihole-ftl.nix也是为什么必须靠pihole-web或手动设置该端口才能开启仪表盘acl访问控制列表允许、-拒绝遍历时最后匹配者生效。例如127.0.0.1,[::1]表示仅本机可访问192.168.0.0/16表示仅允许该网段threads工作线程数即最大并发 HTTP 连接数默认 500 表示使用 CivetWeb 默认值headers附加的 HTTP 响应头默认包含X-DNS-Prefetch-Control: off、Content-Security-Policy: default-src self unsafe-inline;、X-Frame-Options: DENY、X-Content-Type-Options: nosniff、Referrer-Policy: strict-origin-when-cross-origin等安全头serve_all是否开放webroot下全部文件默认false只开放webhome与/api。webserver.session / tls / paths / interfacewebserver.session.timeout会话超时秒数默认 180030 分钟restore为true时会话从数据库持久化恢复webserver.tls.certPEM 格式证书路径须同时包含 CERTIFICATE 与 RSA PRIVATE KEY 段。NixOS 模块默认把证书路径固定为${cfg.stateDirectory}/tls.pem即/var/lib/pihole/tls.pem见 pihole-ftl.nixwebserver.paths.webroot主机上的服务器根目录pihole-web会将其强制设为${cfg.package}/share/即 pihole-web 包内安装的静态资源目录见 pihole-web.nixwebserver.paths.webhomeWeb 界面所在子路径模块强制设为/默认模板是/admin/webserver.paths.prefix反向代理场景下的 URL 前缀如/pihole需代理剥离前缀非代理场景不要使用webserver.interface.boxed与theme界面布局与主题default-auto、default-light、default-dark、high-contrast等。webserver.api认证与 API 行为max_sessions并发 API 会话上限默认 16pwhash / totp_secret / app_pwhashAPI 密码哈希、TOTP 2FA 密钥与应用专用密码均与 FTL 端认证相关app_sudo是否允许应用密码会话修改配置默认false建议保持关闭cli_pw是否生成临时 CLI 密码存于/etc/pihole供pihole命令认证 API。注意NixOS 模块要求当你在services.pihole-ftl.lists中声明拦截列表时cli_pw必须为true否则求值会触发断言失败见 pihole-ftl.nix因为列表的自动加载依赖 Web API 与临时密码excludeClients / excludeDomains从查询日志、Top 客户端等 API 响应中排除的客户端/域名正则列表maxHistory / maxClientsAPI 返回的历史窗口秒上限 86400与活动图客户端数allow_destructive是否允许破坏性 API 调用清空查询、关机等默认true。一个完整的进阶配置示例在基础配置上叠加 HTTPS、ACL 与安全响应头{ services.pihole-web { enable true; hostName pi.hole; ports [ 80r 443s ]; }; services.pihole-ftl { enable true; openFirewallWebserver true; settings.webserver { acl 192.168.0.0/16; threads 100; session.timeout 86400; # 24 小时会话 api.max_sessions 32; }; }; }注意此处openFirewallWebserver trueFTL 模块默认不开放任何防火墙端口只有显式开启后才会根据settings.webserver.port模块会剥掉o/r/s等后缀并解析出纯端口写入networking.firewall.allowedTCPPorts见 pihole-ftl.nix。模块联动pihole-web 启用了什么启用pihole-web后除了上面提到的webserver配置合并外pihole-web.nix 还做了两件事写入/etc/pihole/versions中的WEB_VERSION${cfg.package.src.tag}与 FTL 模块写入的CORE_VERSION、FTL_VERSION一起用于界面展示版本号FTL 部分见 pihole-ftl.nix依赖services.pihole-ftl.enable生效pihole-web 的 config 段直接写入 FTL 的 settings若 FTL 未启用则这些配置无实际载体。此外FTL 模块会为 Web 服务器建立配套的日志轮转pihole-ftl轮转规则覆盖FTL.log与webserver.log按周轮转、保留 3 份并压缩见 pihole-ftl.nixpihole-dnsmasq规则按日轮转pihole.log并在轮转后向pihole-ftl.service发送SIGUSR2让 FTL 重新打开日志文件L506-L519。验证与测试仓库自带的 NixOS 集成测试可以佐证模块行为basic.nix在完全不开启 Web 服务器不设webserver.port的前提下验证 DNS 拦截能力测试pi.hole在本机解析到127.0.0.1、在客户端解析到机器地址dnsmasq.nix显式设置services.pihole-ftl.settings.webserver.port 9077并等待该端口打开验证 Web 服务器确实随 FTL 启动。你可以在本机用 NixOS 测试框架复现nix-build nixos/tests/pihole-ftl -A dnsmasq部署后通过systemctl status pihole-ftl.service确认服务状态访问http://host/登录仪表盘首次登录前可在/etc/pihole/pihole.toml中核对[webserver]段是否与期望一致该文件由 NixOS 声明式生成修改它不会生效一切以 Nix 配置为准。使用注意事项与 dnsmasq 互斥pihole-FTL 是 Dnsmasq 的派生分支NixOS 模块断言services.dnsmasq.enable与services.pihole-ftl.enable不能同时为真pihole-ftl.nix配置只读FTL 模块默认设置misc.readOnly true禁止通过 API/CLI 修改配置——NixOS 的哲学是一切配置声明式完成改动请编辑 Nix 配置后nixos-rebuild switch列表加载前提若在services.pihole-ftl.lists中声明拦截列表则 Web 服务器必须启用webserver.port非空典型做法即启用pihole-web且cli_pw必须为true否则求值期断言直接报错默认不开放防火墙无论是 DNS53、DHCP67还是 Websettings.webserver.port都需要分别打开openFirewallDNS、openFirewallDHCP、openFirewallWebserver才会放行外部访问。总而言之services.pihole-web是 NixOS 上把 Pi-hole 仪表盘挂载到 FTL Web 服务器的最简入口四个选项覆盖域名与端口而更精细的界面、会话、TLS 与 API 行为统一交由services.pihole-ftl.settings.webserver接管真正实现界面只负责呈现、引擎负责服务的模块化分工。赞分享包管理器操作系统【免费下载链接】nixpkgsNix Packages collection NixOS项目地址https://gitcode.com/GitHub_Trending/ni/nixpkgs点击查看免费下载相关推荐NixOS 上部署 Pi-hole FTLpihole-ftl 模块配置、DNS/DHCP 与集成管理实战指南NixOS 上部署 Pi hole FTLpihole ftl 模块配置、DNS/DHCP 与集成管理实战指南 导读 本指南以 NixOS 官方手册中 pih包管理器操作系统NixOS 上部署 GNS3 Server模块化配置、安全加固与源码级原理解析NixOS 上部署 GNS3 Server模块化配置、安全加固与源码级原理解析 GNS3Graphical Network Simulator 3是业界广包管理器操作系统在 NixOS 上用 services.glance 部署自托管仪表盘从 Quickstart 到源码级配置指南在 NixOS 上用 services.glance 部署自托管仪表盘从 Quickstart 到源码级配置指南 Glance 是一款自托管self hos包管理器操作系统上一篇GetQzonehistory 完整指南3步把QQ空间历史说说全部导出到Excel和图片下一篇虚拟显示驱动技术深度解析从架构到实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考