从 Hadolint 平滑迁移到 droast:兼容模式、配置导入与规则映射矩阵全解
从 Hadolint 平滑迁移到 droast:兼容模式、配置导入与规则映射矩阵全解
droast(dockerfile-roast)是一个有"主见"的 Dockerfile linter。如果你团队已经在用 Hadolint,迁移并不痛苦:droast 提供了两条平滑路径——用 --hadolint-compatible 兼容模式直接顶替现有 Hadolint 调用(零改动试运行),或用 droast init --from-hadolint 把 .hadolint.yaml 配置导入为 droast.toml。等价检查会沿用原 DL#### 规则编号,行为不同的检查保留 DF#### 编号,迁移全程可审查、可回退。
为什么考虑从 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 --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 明确报出,但不中断检查
查看完整规则映射矩阵
不想翻文档?一条命令打印当前版本(带版本号)的完整对照矩阵:
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 等)不迁移 |
两个值得注意的细节:
- 一条 DL 规则可能映射到多条 DF 规则。例如
DL3025(JSON 数组形式)同时落到DF018(ENTRYPOINT)和DF025(CMD),DL3006/DL3007(基础镜像标签)都收敛到DF001 - 没有静默策略:无法对应的规则(如
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。
迁移验证清单:四步完成切换
- 灰度运行:CI 中并行跑 Hadolint 与
droast --hadolint-compatible,对比两者输出文件与退出码(0= 无阻断发现,1= 有) - 审查 stderr 诊断:逐条确认
unmatched规则与behaviorally different提示是否符合预期 - 落地配置:
droast init --from-hadolint生成droast.toml并提交,用droast .全仓库扫一遍 - 保留回退窗口:过渡期内不删除
.hadolint.yaml,确认稳定后再下线 Hadolint 调用
相关文件与延伸阅读
- 配置导入实现:src/hadolint.rs
- 兼容模式运行时:src/hadolint_compat.rs
- 官方文档「Hadolint replacement mode」章节:DOCS.md
- 兼容性测试:tests/hadolint_compatibility_test.rs
- 完整配置指南与 CLI 参考:DOCS.md


