首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >数据鱼API接口详解:Dockerfile 规范检查

数据鱼API接口详解:Dockerfile 规范检查

原创
作者头像
用户12862874
发布于 2026-11-21 10:25:37
发布于 2026-11-21 10:25:37
20
举报

接口简介

「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平台开发工具类接口的共同约定,接入方可复用同一套错误分支。

核心端点详解

规范检查(POST /lint)

用途:提交 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。接口不返回修改建议的补丁,也不回显原文。

代码语言:javascript
复制
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 而不是空结果——「没有内容」与「内容完全合规」被明确区分。

健康检查(GET /ping)

用途:探活与读取规则数量。无参数,免鉴权,响应 data.rules_count 固定为 8,可用于客户端展示「本次检查基于多少条规则」。需要注意该数字是声明值,与单次检查可能产出的规则类别数并不一致,详见「注意事项」。

代码语言:javascript
复制
GET /api/docker-lint/ping

数据与限制

  • 端点共 2 个;检查为单次同步调用,无任务队列、无结果查询端点。
  • rules_count 声明为 8;实际逐行判定覆盖 6 类问题(:latest、root 用户、ADD 误用、apt-get 缺 -y、缺 FROM、缺 USER)。
  • 输入按 \n 切分,空行与 # 开头的注释行跳过检查,但其存在仍计入行号,返回的 line 与原始文件一致。
  • 指令识别为行首前缀匹配,且先统一转大写,因此 from、From 与 FROM 等价;缩进会被 trim 去掉后再判断。
  • 接口无持久化:不保存提交的 Dockerfile,也不提供历史记录。响应为 JSON,无分页与批量参数。
  • 单次提交的文本长度在文档中未给出上限,按整段文本一次解析处理,超大文件应自行分片或截断。

典型使用场景

  • 持续集成卡点:在镜像构建前调用一次,按 severity 过滤 critical 决定是否中断,把基础镜像标签与 root 用户问题挡在构建之前。
  • 代码评审辅助:把返回的 line 与 msg 直接贴到合并请求的对应行,评审者无需通读整份 Dockerfile。
  • 存量资产盘点:批量读取仓库中的 Dockerfile 逐份提交,按 status 统计不合规比例,形成治理清单。
  • 编辑器即时提示:保存时调用,按行号在编辑器内标注,不阻塞编辑。

注意事项

  • 文档与实现不一致有三处:content 在 API.md 中标注为可选,实际缺失返回 4001;类型标注为 array/object,实际必须为字符串;rules_count 为 8,而实际判定类别为 6。接入应以实测行为为准。
  • line 为 0 表示与具体行无关的文件级结论(缺 FROM、缺 USER),不能当作第一行处理;只有大于 0 的行号才对应原文位置。
  • 判定为文本匹配而非 Dockerfile 语法解析:ADD 后的判断依赖字符串是否含 .tar.gz 或 http,条件写法、多行续行(\)与变量替换都可能影响结果。
  • 多阶段构建中只要出现任意一个 FROM 即视为满足,不会校验每个阶段;同理,任意一条非 root 的 USER 即可消除缺失告警。
  • 缺少 WORKDIR 不会产生告警,尽管源码中保留了相关标记;不要依赖本接口检查工作目录设置。
  • status 只有 clean 与 issues_found 两值,不代表合规等级;info 级问题也会使状态变为 issues_found,调用方应自行按级别加权。
  • 规则结论反映当前内置规则集,规则调整不会另行通知;数据鱼API仅对文本做静态判定,不保证镜像可构建或运行安全。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • 规范检查(POST /lint)
    • 健康检查(GET /ping)
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档