「Dockerfile 规范检查」是数据鱼API平台提供的静态检查接口,Base 路径 /api/docker-lint,共 2 个端点。它接收一份已有的 Dockerfile 文本,按内置规则逐行扫描,返回问题清单,每条包含行号、说明与严重级别,最后给出整份文件的总体状态。它不构建镜像、不访问仓库,只做文本层面的规则匹配,因此调用成本低,可以放进保存、提交、合并等任何一道关卡。
检查范围集中在基础镜像标签、运行用户、指令选择与包管理四类常见问题上:基础镜像使用 :latest、USER 指向 root、用 ADD 做普通文件复制、apt-get install 缺少 -y,以及整份文件缺少 FROM 或 USER 这两类结构性缺失。严重级别分 critical、warning、info 三档,status 只有 clean 与 issues_found 两种取值,是否阻断流水线由调用方按级别自行决定,接口本身不做判定。
这个接口与生成类工具的方向相反:它面向「已经存在的 Dockerfile」,回答「这份文件哪里写得不对」;从零产出 Dockerfile 属于生成能力,两者不互相替代。把检查放在生成之后、构建之前,可以形成「生成—检查—构建」的固定链路。
方法 | 路径 | 说明 | 鉴权 |
|---|---|---|---|
GET | /api/docker-lint/ping | 健康检查,返回规则数量 | 免鉴权 |
POST | /api/docker-lint/lint | 检查一份 Dockerfile 文本,返回问题清单与总体状态 | 需要 |
鉴权使用 X-API-Key 请求头或 ?api_key= 查询参数,缺失返回 4011、无效返回 4013。响应为 {code, msg, data} 三段结构,code 为 0 表示成功。参数类错误包括 4001 缺少必填参数、4002 格式或取值非法、4003 取值不在支持列表、4004 查询目标未收录;4040 为路由不存在,4050 为方法不允许,5000/5001 为服务内部错误,5031/5032 表示上游依赖不可用且不会返回伪造数据。检查过程不依赖外部服务,5031/5032 通常不会触发。这些是数据鱼API平台开发工具类接口的共同约定,接入方可复用同一套错误分支。
用途:提交 Dockerfile 文本,返回逐行问题与文件级缺失项。
参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
content | string | 是 | — | 待检查的 Dockerfile 全文,按换行切分为行 |
API.md 将 content 标为可选、类型写成 array/object,但实现按字符串读取,取不到内容即返回 4001 Missing parameter: content。按字符串提交整份文本是唯一可靠用法;请求体为 JSON,字段名固定为 content。
返回字段要点:warnings 为问题数组,元素含 line(行号,1 起算;文件级问题固定为 0)、msg(英文说明)、severity(critical/warning/info);status 在 warnings 为空时为 clean,否则为 issues_found。接口不返回修改建议的补丁,也不回显原文。
POST /api/docker-lint/lint?api_key=YOUR_KEY
Content-Type: application/json
{"content":"FROM alpine:latest\nRUN apt-get install curl\n"}上面的输入会命中基础镜像 :latest 与 apt-get install 缺少 -y 两条告警,并因未声明 USER 追加一条文件级 warning。若提交空字符串或省略字段,返回 4001 而不是空结果——「没有内容」与「内容完全合规」被明确区分。
用途:探活与读取规则数量。无参数,免鉴权,响应 data.rules_count 固定为 8,可用于客户端展示「本次检查基于多少条规则」。需要注意该数字是声明值,与单次检查可能产出的规则类别数并不一致,详见「注意事项」。
GET /api/docker-lint/pingrules_count 声明为 8;实际逐行判定覆盖 6 类问题(:latest、root 用户、ADD 误用、apt-get 缺 -y、缺 FROM、缺 USER)。\n 切分,空行与 # 开头的注释行跳过检查,但其存在仍计入行号,返回的 line 与原始文件一致。from、From 与 FROM 等价;缩进会被 trim 去掉后再判断。severity 过滤 critical 决定是否中断,把基础镜像标签与 root 用户问题挡在构建之前。line 与 msg 直接贴到合并请求的对应行,评审者无需通读整份 Dockerfile。status 统计不合规比例,形成治理清单。content 在 API.md 中标注为可选,实际缺失返回 4001;类型标注为 array/object,实际必须为字符串;rules_count 为 8,而实际判定类别为 6。接入应以实测行为为准。line 为 0 表示与具体行无关的文件级结论(缺 FROM、缺 USER),不能当作第一行处理;只有大于 0 的行号才对应原文位置。ADD 后的判断依赖字符串是否含 .tar.gz 或 http,条件写法、多行续行(\)与变量替换都可能影响结果。FROM 即视为满足,不会校验每个阶段;同理,任意一条非 root 的 USER 即可消除缺失告警。WORKDIR 不会产生告警,尽管源码中保留了相关标记;不要依赖本接口检查工作目录设置。status 只有 clean 与 issues_found 两值,不代表合规等级;info 级问题也会使状态变为 issues_found,调用方应自行按级别加权。原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。