docker-selenium 4.48.0 版本发布记录解读：Firefox 127.0.2 + GeckoDriver 0.37.1 镜像标签全解析

导读

本文基于 docker-selenium 仓库 CHANGELOG/4.48.0/firefox_127.md 中的发布记录，深度解析该版本 Firefox Node 与 Standalone 镜像的标签生成全过程。你将掌握：4.48.0 构建（build date 20260909）中 Firefox 127.0.2 与 GeckoDriver 0.37.1 对应的全部 10 个镜像标签、这些标签背后 tag_and_push_browser_images.sh 脚本的自动化生成逻辑、NodeFirefox/Dockerfile 中浏览器与驱动的安装实现，以及如何依据标签规范精确拉取并使用 selenium/node-firefox 与 selenium/standalone-firefox 镜像。

一、发布记录原文：4.48.0 构建的 Firefox 127 镜像标签清单

firefox_127.md 完整记录了发布流水线在 2026-09-09 这一天，针对 Firefox 127.0.2 与 GeckoDriver 0.37.1 执行标签生成命令的完整输出：

./tag_and_push_browser_images.sh 4.48.0 20260909 selenium false firefox true

命令执行后输出的关键版本信息如下：

项目	版本值
Selenium Grid 版本	4.48.0-20260909
Firefox 版本	127.0.2
Firefox 短版本（Short）	127.0
GeckoDriver 版本	0.37.1
GeckoDriver 短版本（Short）	0.37

脚本共生成并打标了 10 个镜像标签，覆盖 node-firefox 与 standalone-firefox 两个镜像名（下文统一以 <image> 代指）：

序号	标签	语义
1	<image>:127.0.2-geckodriver-0.37.1-grid-4.48.0-20260909	完整版本：浏览器精确版本 + 驱动精确版本 + Grid 版本 + 构建日期
2	<image>:127.0.2-geckodriver-0.37.1-20260909	浏览器精确版本 + 驱动精确版本 + 构建日期
3	<image>:127.0.2-20260909	浏览器精确版本 + 构建日期
4	<image>:127.0-geckodriver-0.37-grid-4.48.0-20260909	短版本组合：浏览器短版本 + 驱动短版本 + Grid 版本 + 构建日期
5	<image>:127.0-geckodriver-0.37-20260909	短版本组合：浏览器短版本 + 驱动短版本 + 构建日期
6	<image>:127.0-20260909	浏览器短版本 + 构建日期
7	<image>:127.0.2-geckodriver-0.37.1-grid-4.48.0-20260909（Standalone）	见上，Standalone 镜像同样应用全部标签
8-10	对应 2-6 的 Standalone 变体	同上

这 10 个标签完整覆盖了从"最精确的可追溯版本"到"简短的语义化版本"的各级粒度。关键结论：发布记录中 PUSH_IMAGE 参数为 false，说明该次执行只在本地产物上打标（docker tag），并未执行 docker push；实际推送到镜像仓库由后续发布流程完成。

二、标签是如何生成的：tag_and_push_browser_images.sh 脚本机制

发布记录中的命令格式为：

./tag_and_push_browser_images.sh <VERSION> <BUILD_DATE> <NAMESPACE> <PUSH_IMAGE> <BROWSER> [RELEASE_OLD_VERSION] [PLATFORM]

对照 tag_and_push_browser_images.sh 的参数定义：

位置	参数	本记录取值	说明
$1	VERSION	4.48.0	Selenium Grid 版本
$2	BUILD_DATE	20260909	构建日期（YYYYMMDD）
$3	NAMESPACE	selenium	镜像命名空间（默认 selenium）
$4	PUSH_IMAGE	false	是否执行 docker push，默认 false
$5	BROWSER	firefox	浏览器类型，进入对应分支
$6	RELEASE_OLD_VERSION	true	是否同时发布旧版本标签（见下）
$7	PLATFORM	未传	目标平台，默认 linux/amd64

2.1 Firefox 分支的版本探测逻辑

在 firefox 分支 中，脚本通过临时运行已构建好的 Node 镜像来探测实际内置的浏览器与驱动版本：

FIREFOX_VERSION=$(docker run --rm ${NAMESPACE}/node-firefox:${TAG_VERSION} firefox --version | awk '{print $3}')
GECKODRIVER_VERSION=$(docker run --rm ${NAMESPACE}/node-firefox:${TAG_VERSION} geckodriver --version | awk 'NR==1{print $2}')

即执行 firefox --version 与 geckodriver --version，再用 awk 抽取版本号——这正是发布记录中 Firefox version -> 127.0.2、GeckoDriver version -> 0.37.1 两行输出的来源。随后通过 short_version() 函数截取主版本与次版本：

function short_version() {
  local __version_split=(${__long_version//./ })
  echo "${__version_split[0]}.${__version_split[1]}"
}

将 127.0.2 截断为 127.0、0.37.1 截断为 0.37，对应发布记录中的两行 Short 版本输出。

2.2 标签组合规则

FIREFOX_TAGS 数组 由三组维度组合而成：

• Grid 维度：-grid-<VERSION>-<BUILD_DATE>（如 -grid-4.48.0-20260909）；
• 日期维度：-<BUILD_DATE>（如 -20260909）；
• 纯版本维度：不带日期与 Grid 信息的 127.0.2-geckodriver-0.37.1、127.0.2、127.0-geckodriver-0.37、127.0 四个标签。

注意：纯版本维度标签仅在 RELEASE_OLD_VERSION=false 时追加。由于本次命令传入 RELEASE_OLD_VERSION=true，最终只打标了 6 组（每组覆盖 node 与 standalone 两个镜像），与发布记录输出完全一致——这也解释了为什么记录中没有出现 selenium/node-firefox:127.0.2 这类"简洁标签"。

2.3 打标与可选推送

retag() 函数 默认执行 docker tag 并打印 Tagged <namespace>/<image>:<tag>（与发布记录输出逐行对应）；当 PUSH_IMAGE=true 时追加 docker push。脚本还支持 PROMOTE_TAGS 与 PROMOTE_GHCR_NAMESPACE 环境变量，用于在发布阶段直接通过 docker buildx imagetools create 在 registry 间复制 manifest（此时本地不保存镜像，镜像标签将保持多架构属性），这是发布流水线复用已验证镜像时的路径。

三、镜像内部实现：Firefox 与 GeckoDriver 的构建源码

3.1 Firefox 的两种安装路径

NodeFirefox/Dockerfile 通过 ARG FIREFOX_VERSION 控制安装版本。由于 127.0.2 属于 136 之前的旧版本，且架构分支判断（amd64 或版本 ≥136 才直接走官方 APT 源）不满足，镜像实际走 Mozilla 官方发布源下载安装 路径：

FIREFOX_DOWNLOAD_URL="https://download-installer.cdn.mozilla.net/pub/firefox/releases/$FIREFOX_VERSION/linux-$ARCH/en-US/firefox-$FIREFOX_VERSION.deb"

下载逻辑与三种包格式（.deb、.tar.bz2、.tar.xz）的安装处理实现在 install-firefox-package.sh 中：.deb 通过 apt-get install --allow-downgrades 安装，tar 包则解压到 /opt/firefox-<version> 并软链到 /usr/bin/firefox。而较新版本（≥136）及 latest/beta 等发行通道则优先走 install-firefox-apt.sh 配置的 Mozilla APT 源。此外，get_lang_package.sh 负责拉取对应语言包，构建末尾还会执行一次 apt-get upgrade 以修复 Firefox 依赖链上的 CVE。

3.2 GeckoDriver 的版本锁定

GeckoDriver 安装段 支持 ARG GECKODRIVER_VERSION=latest：当指定具体版本（如本记录中的 0.37.1）时，直接从 GitHub Releases 下载对应架构的 tar 包：

GK_VERSION=$(if [ ${GECKODRIVER_VERSION:-latest} = "latest" ]; then echo "${LATEST_VERSION}"; else echo $GECKODRIVER_VERSION; fi)
wget --no-verbose -O /tmp/geckodriver.tar.gz \
  https://github.com/mozilla/geckodriver/releases/download/${GK_VERSION}/geckodriver-${GK_VERSION}-${DRIVER_ARCH}.tar.gz

驱动被安装为 /opt/geckodriver-<version> 并软链至 /usr/bin/geckodriver，因此发布记录中的版本探测命令 geckodriver --version 在容器内可直接执行。

3.3 节点运行时的驱动路径

当 Node 启动时，NodeBase/start-selenium-node.sh 会通过 JVM 属性将 GeckoDriver 路径注入 Selenium Server：

GECKO_DRIVER_PATH_PROPERTY=-Dwebdriver.gecko.driver=/usr/bin/geckodriver

同时 Dockerfile 末段 会向 /opt/selenium/browsers/firefox/binary_location 写入 moz:firefoxOptions.binary 配置，默认指向 /usr/bin/firefox，供 Selenium Grid 自动发现浏览器能力使用。Node 镜像默认还启用了 SE_NODE_ENABLE_MANAGED_DOWNLOADS=true（managed downloads 特性），并设置 OTEL 服务名为 selenium-node-firefox。

3.4 残留进程清理

NodeFirefox 镜像内置 firefox-cleanup.sh，由 supervisord（见 firefox-cleanup.conf）周期性拉起：它会按 SE_BROWSER_LEFTOVERS_PROCESSES_SECS（默认 60 秒）清理超龄的 firefox-bin 进程，并按 SE_BROWSER_LEFTOVERS_INTERVAL_SECS（默认 3600 秒）的间隔循环执行，避免长跑节点积累僵尸浏览器进程耗尽资源。

四、实战：如何按标签拉取与运行 Firefox 127 镜像

4.1 推荐使用的标签

依据 docs/docker-hub/node-firefox.md 的标签规范，本发布记录最值得固定使用的两个精确标签为：

selenium/node-firefox:127.0.2-geckodriver-0.37.1-grid-4.48.0-20260909
selenium/standalone-firefox:127.0.2-geckodriver-0.37.1-grid-4.48.0-20260909

该标签同时锁定浏览器、驱动、Grid 与构建日期四个维度，是最可追溯的稳定选择。若只想锁定浏览器主版本而不在意补丁与日期，可选用 127.0-geckodriver-0.37-grid-4.48.0-20260909 这类短版本标签。

4.2 以 Hub + Node 方式运行

# 1. 创建 Grid 网络
docker network create grid

# 2. 启动 Hub（暴露 4442-4444 端口）
docker run -d -p 4442-4444:4442-4444 --net grid --name selenium-hub selenium/hub:4.48.0-20260909

# 3. 启动 Firefox 127 Node，通过事件总线与 Hub 通信
docker run -d --net grid \
  -e SE_EVENT_BUS_HOST=selenium-hub \
  --shm-size="2g" \
  selenium/node-firefox:127.0.2-geckodriver-0.37.1-grid-4.48.0-20260909

# 4. 测试脚本指向 http://localhost:4444 即可

注意事项：

• 浏览器容器务必使用 --shm-size="2g"，否则 Firefox 可能因共享内存不足而崩溃（见 node-firefox 文档）；
• 可在浏览器中打开 http://localhost:7900/?autoconnect=1&resize=scale&password=secret 查看容器内 Firefox 的实时画面（VNC 调试）；
• Node 启动脚本要求必须设置 SE_EVENT_BUS_HOST、SE_EVENT_BUS_PUBLISH_PORT、SE_EVENT_BUS_SUBSCRIBE_PORT，否则会直接退出（见 start-selenium-node.sh），Hub 容器启动时这些环境变量会通过 Grid 网络自动注入；
• 测试结束后可执行 docker network rm grid 清理网络。

4.3 Standalone 一键运行

若无需独立 Hub，可直接用 Standalone 镜像单机完成 Grid + 浏览器一体运行：

docker run -d -p 4444:4444 --shm-size="2g" \
  selenium/standalone-firefox:127.0.2-geckodriver-0.37.1-grid-4.48.0-20260909

五、小结

firefox_127.md 这份发布记录并非简单的构建日志，它背后映射了 docker-selenium 项目一套成熟的版本发布与镜像打标体系：tag_and_push_browser_images.sh 负责自动化探测版本并组合出全粒度标签，NodeFirefox/Dockerfile 及其配套安装脚本保证 Firefox 127.0.2 与 GeckoDriver 0.37.1 的精确落地，而 docs/docker-hub/node-firefox.md 提供了使用者侧的标签选择与运行指引。理解这三级链路后，你在选择 selenium/node-firefox 或 selenium/standalone-firefox 镜像时，就能精确锁定到浏览器、驱动、Grid 与构建日期任一维度的组合，从而获得可复现、可追溯的自动化测试环境。