从 Hadolint 平滑迁移到 droast:兼容模式、配置导入与规则映射矩阵全解

原创2026-10-14 21:07:551,957 阅读

从 Hadolint 平滑迁移到 droast:兼容模式、配置导入与规则映射矩阵全解

droast(dockerfile-roast)是一个有"主见"的 Dockerfile linter。如果你团队已经在用 Hadolint,迁移并不痛苦:droast 提供了两条平滑路径——用 --hadolint-compatible 兼容模式直接顶替现有 Hadolint 调用(零改动试运行),或用 droast init --from-hadolint 把 .hadolint.yaml 配置导入为 droast.toml。等价检查会沿用原 DL#### 规则编号,行为不同的检查保留 DF#### 编号,迁移全程可审查、可回退。

droast Dockerfile linter 终端输出,展示 Hadolint 迁移后对 Dockerfile 的规则检查与 roast 提示

为什么考虑从 Hadolint 迁移到 droast

先说结论:droast 不是"换个提示语"的同质替代,而是在解析能力和工程体验上的升级:

  • 85 条规则:覆盖 base image、安全、包管理器、层卫生、指令质量等类别,规则清单可用 droast --list-rules 随时查看
  • Span 感知解析器:能理解 heredoc、# escape / # syntax 指令、shell 与 JSON 两种形式、RUN --mount 等 BuildKit 语法、Windows 路径与 PowerShell,语法错误统一报 DF071
  • 仓库级扫描:直接 droast . 递归发现全部 Dockerfile,并读取 Compose YAML 与 Bake HCL/JSON 定位非标准路径
  • 安全自动修复:droast --fix 只改 4 类机械问题(大小写一致性、EXPOSE 协议名等),可先 --dry-run 预览
  • 更快更小:官方基准测试中,扫描 321 个真实 Dockerfile(49,563 行)的中位耗时约 1 秒,单二进制仅 7.5 MB

droast 兼容输出格式示例:compact 一行一条发现与 json 机器可读输出

迁移的两种路径,怎么选?

维度 路径一:兼容模式 路径二:配置导入
命令 droast --hadolint-compatible Dockerfile droast init --from-hadolint .hadolint.yaml
是否改动现有配置 不动,直接读 .hadolint.yaml 生成新的 droast.toml
适用场景 CI 灰度切换、先跑一周对比结果 决定全面迁移,提交团队级策略
规则编号 等价检查输出 DL#### 转译为 DF####
回退成本 删掉 flag 即回退 删掉 droast.toml 即回退

建议的顺序:先走路径一在 CI 里灰度,确认无差异后再走路径二落地配置。

路径一:用兼容模式直接替换 Hadolint 调用

一行命令顶替现有 Hadolint

droast --hadolint-compatible Dockerfile

这个模式的目标是"让现有 Hadolint 工作流原地继续跑":

  • 自动发现配置:不传 --config 时,按 Hadolint 的惯例依次查找 .hadolint.yaml、.hadolint.yml、XDG 配置目录与 ~/.hadolint/ 等位置;--config 在此模式下指向的是 Hadolint YAML 而非 droast.toml
  • 接收 Hadolint 常用 flag:--ignore、--error/--warning/--info/--style(严重度覆盖)、--trusted-registry、--require-label、--strict-labels、-t/--failure-threshold、--no-fail、--no-color 等
  • 读取 HADOLINT_* 环境变量:HADOLINT_NOFAIL、HADOLINT_IGNORE、HADOLINT_FORMAT、HADOLINT_FAILURE_THRESHOLD、四个 HADOLINT_OVERRIDE_* 列表、HADOLINT_TRUSTED_REGISTRIES、HADOLINT_REQUIRE_LABELS 等——CI 里靠环境变量传参的流水线不用改一行
  • 内联 pragma 原样生效:# hadolint ignore=DL3003 与 # hadolint global ignore=DL3006 都会被识别
  • 10 种输出格式:tty、json、checkstyle、codeclimate、gitlab_codeclimate、gnu、codacy、sonarqube、sarif、junit,直接接进 GitLab 代码质量报告、SonarQube 等下游工具
# 例如产出 GitLab 代码质量报告
droast --hadolint-compatible --format gitlab_codeclimate \
  --file-path-in-report Dockerfile Dockerfile > gl-code-quality-report.json

编号规则:什么时候是 DL,什么时候是 DF

这是迁移中最容易踩坑的地方,droast 的处理原则是不冒充:

  • 与 Hadolint 规则行为等价的检查,输出原始 DL#### 编号——下游已有的 ignore 列表、告警过滤器继续生效
  • droast 检查范围更宽或行为不同时,保留 DF#### 编号,并在 stderr 打印诊断说明,避免"看起来静默变了策略"
  • 配置中引用了无对应关系的规则或设置(如某些 ShellCheck 类 SC 编号),同样会在 stderr 明确报出,但不中断检查

VS Code 中 droast 扩展对 Dockerfile 的内联检查与规则提示

查看完整规则映射矩阵

不想翻文档?一条命令打印当前版本(带版本号)的完整对照矩阵:

droast --hadolint-compatible --hadolint-compatibility-report

输出形如 DL3007: DF001 equivalent identity,每条规则标注 equivalent identity(等价)或 behaviorally different(行为不同),末尾列出所有 unmatched 规则。

路径二:配置导入生成 droast.toml

确认要全面迁移后,把 Hadolint YAML 一次性转成 droast 原生配置:

# 读取当前目录的 .hadolint.yaml
droast init --from-hadolint

# 或显式指定路径
droast init --from-hadolint .config/hadolint.yml

配置项映射对照表

Hadolint YAML 设置 droast.toml 设置 说明
ignored skip DL 规则自动翻译为对应 DF 编号
override(error/warning/info) [severity-overrides] 直接平移
override.style 映射为 info Hadolint 的 style 档在 droast 中并入 info
trustedRegistries approved-registries 对应 DF065 注册表白名单
label-schema + strict-labels [required-labels] + strict-labels 对应 DF074
no-fail no-fail 直接平移
disable-ignore-pragma inline-suppressions(取反) 注意语义相反
failure-threshold min-severity style/ignore 折算为 info;none 转为 no-fail
format: tty/json/sarif format 其余格式(checkstyle 等)不迁移

两个值得注意的细节:

  1. 一条 DL 规则可能映射到多条 DF 规则。例如 DL3025(JSON 数组形式)同时落到 DF018(ENTRYPOINT)和 DF025(CMD),DL3006/DL3007(基础镜像标签)都收敛到 DF001
  2. 没有静默策略:无法对应的规则(如 SC2086 这类 ShellCheck 编号)和设置会逐条打印到 stderr 并被排除在生成的策略之外,你需要人工审查后再决定

导入逻辑源码在 src/hadolint.rs,生成的配置开头会带上 # Generated from a Hadolint configuration 注释,方便 code review 时识别来源。

规则映射矩阵:DL 与 DF 高频对照表

以下为映射矩阵中最常见的一批条目(完整列表以 --hadolint-compatibility-report 输出为准):

Hadolint 规则 droast 规则 常见含义
DL1000 DF071 Dockerfile 语法/指令序列错误
DL3000 DF009 WORKDIR 使用绝对路径
DL3002 DF002 不要以 root 运行
DL3003 DF008 用 WORKDIR 代替内联 cd
DL3006 / DL3007 DF001 避免 latest 等未固定标签
DL3009 DF004 清理 apt/apk 缓存(行为不同*)
DL3013 DF051 pip install 固定版本
DL3014 DF015 apt-get 需要 -y
DL3015 DF016 使用 --no-install-recommends
DL3018 DF052 apk add 固定版本
DL3019 DF029 apk add 使用 --no-cache
DL3025 DF018 + DF025 CMD/ENTRYPOINT 使用 JSON 数组(一对多)
DL3026 DF065 强制使用批准的注册表
DL3030 DF027 yum 需要 -y
DL3042 DF030 pip 使用 --no-cache-dir
DL3043 DF068 禁止的 ONBUILD 触发器
DL3059 DF003 合并 RUN 减少层数
DL3061 DF037 Dockerfile 必须以 FROM 开头
DL4000 DF019 弃用 MAINTAINER,改用 LABEL
DL4004 DF039 多个 ENTRYPOINT 只有最后一个生效

* 标注为 behaviorally different 的规则(如 DL3009、DL3016、DL3033、DL3037、DL3041):droast 侧检查范围更宽,输出时保留 DF 编号,配置中引用它们会在 stderr 收到提示。

映射数据与运行逻辑分别位于 src/hadolint.rs 的 aliases() 与 src/hadolint_compat.rs,回归测试见 tests/hadolint_compatibility_test.rs。

迁移验证清单:四步完成切换

  1. 灰度运行:CI 中并行跑 Hadolint 与 droast --hadolint-compatible,对比两者输出文件与退出码(0 = 无阻断发现,1 = 有)
  2. 审查 stderr 诊断:逐条确认 unmatched 规则与 behaviorally different 提示是否符合预期
  3. 落地配置:droast init --from-hadolint 生成 droast.toml 并提交,用 droast . 全仓库扫一遍
  4. 保留回退窗口:过渡期内不删除 .hadolint.yaml,确认稳定后再下线 Hadolint 调用

相关文件与延伸阅读

登录后查看全文
dockerfile-roast