网络安全后端【免费下载链接】docker-pi-holeThe official Pi-hole Docker image from pi-hole.net项目地址https://gitcode.com/gh_mirrors/do/docker-pi-hole点击查看免费下载本篇指南以官方仓库 docker-pi-hole 的测试文档 test/TESTING.md 为核心系统讲解如何在本机完整运行该项目的自动化测试从一条命令构建pihole:test镜像、启动多组测试容器、执行 BATSBash Automated Testing System测试套件到测试结束自动清理。同时结合仓库内 test/run.sh、test/helpers.sh 以及三个 BATS 测试文件的源码级实现说明每一条测试断言背后的原理并演示如何通过CIPLATFORM环境变量在模拟环境下测试linux/arm64等非宿主架构。读完本文你将具备对 Pi-hole Docker 镜像进行本地验证、跨平台模拟测试以及排查测试失败的能力。一、前置条件运行测试前你的环境需要满足两个基本要求已安装并可使用docker包括docker buildx插件构建阶段依赖它来按平台构建镜像并加载到本地镜像库已安装git用于在首次运行时拉取 BATS 相关测试库。从 test/run.sh 第 4-6 行可以看到脚本会自行切换到test/目录执行因此你既可以在仓库根目录、也可以在任意路径下直接调用test/run.sh脚本都会保证以test/为工作目录运行。二、一键运行bash test/run.sh的完整流程官方文档给出的核心命令非常简单bash test/run.sh这条命令一次完成四件事构建镜像构建一个名为pihole:test的镜像基于 src/Dockerfile启动容器针对每种待测配置启动一组容器默认配置、自定义环境变量、Docker Secrets 各一组运行 BATS 测试对上述容器执行 BATS 测试套件退出清理测试结束无论成功与否后移除所有测试容器。其中“移除所有测试容器”并非靠 run.sh 本身执行而是由每个 BATS 文件的teardown_file()钩子完成——例如 test/test_default.bats 第 15-17 行执行docker rm -f $CONTAINER。这种设计让容器生命周期与测试文件的 setup/teardown 严格绑定既保证隔离也避免容器残留占用端口。2.1 构建阶段的细节test/run.sh 第 10-19 行负责构建镜像使用的是 BuildKit 风格的docker buildx buildPLATFORM_ARGS() [ -n ${CIPLATFORM:-} ] PLATFORM_ARGS(--platform ${CIPLATFORM}) docker buildx build \ --load \ ${PLATFORM_ARGS[]} \ --progress plain \ -f ../src/Dockerfile \ -t pihole:test \ ../src/关键点解读--load将跨平台构建产物加载进本地 docker 镜像列表否则后续docker run无法引用pihole:test--progress plain在 CI 或无 TTY 环境下输出平铺日志便于回溯构建错误-f ../src/Dockerfile使用仓库src/目录下的 src/Dockerfile 作为构建定义当设置了CIPLATFORM时--platform会被透传给 buildx用于模拟目标架构详见第五节。值得注意的是src/Dockerfile 第 2-10 行定义了一系列可被覆盖的构建参数FTL_SOURCEremote或local控制 FTL 二进制下载来源、WEB_BRANCH、CORE_BRANCH、FTL_BRANCH、PIHOLE_DOCKER_TAG等默认均为development分支。如果你的测试目标是本地构建的 FTL 二进制可以通过--build-arg FTL_SOURCElocal配合 src/Dockerfile 第 130-133 行的local-ftl-install阶段实现——不过test/run.sh默认不传额外 build-arg按默认值走remote-ftl-install阶段下载正式发布的 FTL。2.2 启动容器的机制test/helpers.sh 中的start_container()是所有测试容器的统一入口start_container() { local platform_args() [ -n ${CIPLATFORM:-} ] platform_args(--platform ${CIPLATFORM}) docker run -d -t ${platform_args[]} -e TZEurope/London $ pihole:test }它固定以-d -t后台 分配 TTY方式运行pihole:test统一注入TZEurope/London其余环境变量则由各测试文件通过$追加。例如 test/test_env_vars.bats 第 8-15 行就通过追加参数一次性注入PIHOLE_UID、PIHOLE_GID、FTLCONF_webserver_api_password、FTLCONF_webserver_port、FTLCONF_dns_upstreams、ADDITIONAL_PACKAGES、TAIL_FTL_LOG等环境变量。容器“就绪”的判断依赖wait_for_log()它轮询docker logs直到出现指定模式如########## FTL started或 60 秒超时。超时时会打印完整容器日志并返回 1便于直接定位启动失败原因。三、BATS 测试套件解析test/run.sh第 43-47 行固定指定三个测试文件TEST_FILES( test_default.bats test_env_vars.bats test_secrets.bats )3.1 test_default.bats默认配置冒烟测试test/test_default.bats 覆盖一个无任何自定义环境变量的标准容器验证镜像开箱即用性共 13 个测试用例断言组具体验证内容FTL 二进制pihole-FTL -vv能输出Version:第 21-25 行设置了CIPLATFORM时还校验Architecture:与目标平台一致第 27-33 行容器配置/crontab.txt可被crontab命令正常载入第 37-40 行Web 密码全新启动时日志出现assigning random password:第 44-48 行对应 src/bash_functions.sh 第 209-210 行的随机密码生成逻辑容器服务crond进程存活第 52-55 行/etc/pihole/logrotate存在第 57-60 行默认配置未配置任何上游 DNS 时pihole-FTL --config -q dns.upstreams返回8.8.8.8与8.8.4.4第 64-69 行对应 src/bash_functions.sh 第 146-149 行的 Google DNS 兜底逻辑Web 界面curl http://localhost/admin/可访问第 73-76 行镜像产物/pihole.docker.tag由 src/Dockerfile 第 102 行写入与/macvendor.db均存在且 FTL 配置中files.macvendor指向/macvendor.db第 80-94 行运行时FTL 以pihole用户运行pgrep -u pihole pihole-FTLgetcap /usr/bin/pihole-FTL显示包含cap_net_raw第 98-107 行印证 src/bash_functions.sh 第 228-267 行fix_capabilities()的能力设置流程特别注意文件末尾的“FTL 启停”测试第 111-120 行执行docker stop优雅停机后日志必须出现########## FTL terminated after与(code 0)。该测试会销毁整个容器因此 test/test_default.bats 第 12 行设置了BATS_NO_PARALLELIZE_WITHIN_FILEtrue强制文件内串行执行避免后续测试依赖一个已被删除的容器。3.2 test_env_vars.bats环境变量生效测试test/test_env_vars.bats 启动一个注入 7 个环境变量的容器验证用户自定义配置确实被容器采纳FTL 配置注入FTLCONF_webserver_port8080与FTLCONF_dns_upstreams8.8.8.8;1.1.1.1生效后pihole-FTL --config输出应为dns.upstreams [ 8.8.8.8, 1.1.1.1 ]和webserver.port 8080第 26-31 行。其底层机制见 src/bash_functions.sh 第 132-152 行的ftl_config()通过pihole-FTL --config读取并落盘环境变量UID/GID 覆盖PIHOLE_UID456、PIHOLE_GID456时id -u pihole、id -g pihole均应为456第 35-45 行对应 src/bash_functions.sh 第 31-63 行set_uid_gid()中usermod/groupmod的实现Web 密码日志出现Assigning password defined by Environment Variable第 49-53 行证明优先级为“环境变量密码 配置文件中已有密码 随机密码”与 src/bash_functions.sh 第 193-226 行setup_web_password()的分支顺序一致附加软件包ADDITIONAL_PACKAGESwget安装后which wget成功第 57-60 行对应install_additional_packages()src/bash_functions.sh 第 65-80 行内部的apk update apk add --no-cache自定义端口 Web 界面http://localhost:8080/admin可访问第 64-67 行日志开关TAIL_FTL_LOG0时日志出现FTL log output is disabled且不出现########## FTL started第 71-77 行对应 src/start.sh 第 93-98 行关闭日志跟随的逻辑。3.3 test_secrets.batsDocker Secrets 密码注入测试test/test_secrets.bats 演示了如何通过 Docker Secrets 提供 Web 密码而不是明文写在环境变量里secret_file$(mktemp) echo -n mysecretpassword $secret_file CONTAINER$(start_container \ -e WEBPASSWORD_FILEpihole_password \ -v ${secret_file}:/run/secrets/pihole_password:ro)容器内以只读卷将宿主机临时文件挂载为/run/secrets/pihole_password并声明WEBPASSWORD_FILEpihole_password。断言要求启动日志出现Setting FTLCONF_webserver_api_password from file。对应的实现位于 src/bash_functions.sh 第 194-198 行当环境变量FTLCONF_webserver_api_password未设置、WEBPASSWORD_FILE存在且/run/secrets/${WEBPASSWORD_FILE}可读时从该文件读取内容并导出为FTLCONF_webserver_api_password。这一机制让密码不会出现在docker inspect或进程列表中适合密钥合规场景。四、BATS 的运行参数与并行化test/run.sh第 49-61 行根据运行环境自动调整 BATS 参数输出格式自适应当 stdout 是终端[[ -t 1 ]]时追加-ppretty 输出否则保持默认的 TAP 格式——TAP 便于 CI 解析自动并行检测到 GNUparallel时追加--jobs $(nproc)按 CPU 核数并行执行测试文件缩短 CI 与本地测试时间。测试文件内部可自主声明是否允许并行如 test/test_default.bats 因末尾启停测试会销毁容器通过BATS_NO_PARALLELIZE_WITHIN_FILEtrue强制文件内串行。BATS 依赖库bats-support、bats-assert与 BATS 本体在 test/run.sh 第 23-35 行以固定版本克隆到test/libs/下BATSv1.13.0、bats-supportv0.3.0、bats-assertv2.2.4。若目录已存在则跳过克隆因此重复运行不会重复下载你也可以通过设置BATS环境变量直接指向本机已安装的 bats 可执行文件跳过仓库内安装流程。各测试文件通过load libs/bats-support/load等语句引入断言函数assert_success、assert_output --partial、refute_output。五、跨平台模拟测试CIPLATFORM官方文档指出测试非宿主架构如 ARM时只需设置CIPLATFORMCIPLATFORMlinux/arm64 bash test/run.shCIPLATFORM的取值会沿三条路径传递构建阶段test/run.sh 第 11 行将其转成docker buildx build --platform参数运行阶段test/helpers.sh 第 6 行将其转成docker run --platform参数断言阶段test/run.sh 第 41 行将其export供 test/test_default.bats 第 28-32 行的架构断言比对pihole-FTL -vv输出的Architecture:字段。因此CIPLATFORMlinux/arm64 bash test/run.sh会完整地按 ARM64 平台构建镜像 → 以 ARM64 平台模拟运行容器 → 校验 FTL 二进制上报的架构确为linux/arm64。这依赖于 Docker 的 QEMU 模拟层binfmt且 src/Dockerfile 第 115-122 行本身支持amd64、386、arm/v6、arm/v7、arm64、riscv64等目标平台的 FTL 下载分支为跨平台测试提供了镜像侧基础。六、测试失败排查与常见问题结合测试基础设施源码遇到失败时可按下述思路排查容器未就绪超时 60 秒wait_for_log会先输出TIMEOUT再转储完整容器日志test/helpers.sh 第 19-23 行。此时重点查看启动日志中是否出现FTL started之外的错误例如fix_capabilities()的能力检测失败src/bash_functions.sh 第 262-266 行或 src/start.sh 第 81-83 行 30 秒内未等到 FTL 就绪而退出架构断言被跳过本地不设置CIPLATFORM时架构相关测试会以skip CIPLATFORM not set, running locally跳过test/test_default.bats 第 28 行这是预期行为不代表失败端口冲突三个测试文件各启动一个容器若本机 53、80 等端口被占用会导致docker run失败。测试容器默认不映射宿主端口仅容器内端口冲突概率较低但仍建议关闭本机占用 53 端口的服务buildx 不可用构建阶段依赖docker buildx build旧版 Docker 需要先启用 BuildKit 或升级 Docker残留容器若测试中断可用docker ps -a检查并手动清理名称包含测试容器的实例每个文件通过teardown_file()负责清理见 test/test_env_vars.bats 第 20-22 行。七、小结Docker Pi-hole 的本地测试体系是一套自包含、可并行、可跨平台的镜像验证方案test/TESTING.md 提供入口bash test/run.sh完成从构建到清理的全流程三个 BATS 文件分别从默认配置、环境变量注入、Docker Secrets 三个维度验证镜像行为并将 src/start.sh、src/bash_functions.sh、src/Dockerfile 中的关键运行机制随机密码、FTL 配置注入、能力设置、macvendor 数据库、日志开关、UID/GID 覆盖全部纳入断言CIPLATFORM则让开发者无需 ARM 实体设备即可验证多架构镜像。这套模式同样可以作为其他 Docker 镜像项目搭建 CI 测试矩阵的参考范本。赞分享网络安全后端【免费下载链接】docker-pi-holeThe official Pi-hole Docker image from pi-hole.net项目地址https://gitcode.com/gh_mirrors/do/docker-pi-hole点击查看免费下载相关推荐docker-pi-hole 代码贡献指南从 development 分支策略到 BATS 本地测试全流程docker pi hole 代码贡献指南从 development 分支策略到 BATS 本地测试全流程 本指南基于仓库根目录的 CONTRIBUTING.网络安全后端在 Docker 中运行与扩展 Bats 测试bats-core 官方镜像使用指南在 Docker 中运行与扩展 Bats 测试bats core 官方镜像使用指南 BatsBash Automated Testing System是一测试开发工具Buildah 与 Docker 镜像构建一致性验证Conformance 测试套件实战指南Buildah 与 Docker 镜像构建一致性验证Conformance 测试套件实战指南 本指南面向希望验证 Buildah 构建结果与 Docker 构云原生上一篇如何挑选通信方式go-cqhttp的HTTP、WebSocket四种模式终极对比指南下一篇30天吃掉TensorFlow2损失函数losses完全指南——从内置损失函数到自定义Focal Loss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考