首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >数据鱼API「Dockerfile 生成器」接口功能介绍

数据鱼API「Dockerfile 生成器」接口功能介绍

原创
作者头像
用户12862874
发布于 2026-11-21 10:26:03
发布于 2026-11-21 10:26:03
80
举报

接口简介

「Dockerfile 生成器」是数据鱼API平台提供的容器构建文件生成接口,Base 路径 /api/dockerfile-gen,共 4 个端点。它按运行时类型从内置模板产出一份可直接落盘的多阶段 Dockerfile,并把构建阶段与运行阶段分开:构建阶段安装依赖、编译产物,运行阶段只保留产物与最小运行时,以 distroless 或 scratch 作为最终基础镜像。

模板覆盖 Node、Python、Go 三种运行时,产出的文件统一带三项加固特征:多阶段构建、非 root 用户、最小化基础镜像。接口在响应的 features 数组中把这三项显式列出,便于调用方在生成后做一致性断言,而不是靠阅读文本判断。

生成与检查是两个方向:本接口面向「从零得到一份 Dockerfile」,输入是运行时类型与监听端口,输出是完整文本;对已有文件做逐行规则检查属于另一个接口的职责。两者可以串联——先生成,再对生成的文本做静态检查,最后交给构建流程。

端点总览

方法

路径

说明

鉴权

GET

/api/dockerfile-gen/ping

健康检查,返回服务时间

免鉴权

GET

/api/dockerfile-gen/stats

返回服务版本等统计信息

需要

POST

/api/dockerfile-gen/generate

按类型与端口生成 Dockerfile

需要

POST

/api/dockerfile-gen/audit

对已有 Dockerfile 文本打分并列出问题

需要

通用约定

鉴权使用 X-API-Key 请求头或 ?api_key= 查询参数,缺失返回 4011、无效返回 4013。响应为 {code, msg, data} 三段结构,code 为 0 表示成功;ping 的成功消息为 pong,其余端点为 success。参数类错误包括 4001 缺少必填参数、4002 格式或取值非法、4003 取值不在支持列表、4004 查询目标未收录;4040 为路由不存在,4050 为方法不允许,5000/5001 为服务内部错误,5031/5032 表示上游依赖不可用且不会返回伪造数据。生成与打分均在本地模板与规则内完成,通常不会触发 5031/5032。这是数据鱼API平台开发工具类接口的共同约定。

核心端点详解

生成 Dockerfile(POST /generate)

用途:按运行时类型与端口产出一份加固后的多阶段 Dockerfile。

参数

类型

必填

默认

说明

type

string

否

node

运行时类型,可选 node、python、go;未识别值静默回退为 node

port

int

否

8080

写入 EXPOSE 的监听端口,按整数解析

API.md 把 type 标为「条件必填」、说明写作「regex 为空时必填」,这属于模板复用留下的描述,与实际参数无关;实际两个参数都有默认值,省略即可生成 Node 模板。

返回字段要点:type 为实际使用的模板类型(回退后也是回退值,不是请求原值),security 固定为 Production-Grade,features 固定为 Multi-stage、Non-root user、Distroless/Scratch base 三项,dockerfile 为完整文本,阶段之间以空行分隔。

代码语言:javascript
复制
POST /api/dockerfile-gen/generate?api_key=YOUR_KEY
Content-Type: application/json

{"type":"python","port":8000}

Node 模板的构建阶段执行 npm ci --only=production,运行阶段切换到 distroless 的 Node 镜像并以非 root 的固定 UID/GID 运行,CMD 指向应用入口;Python 模板在构建阶段安装编译依赖,运行阶段仅复制用户级依赖目录并通过 ENV PATH 暴露;Go 模板以 Alpine 编译静态二进制,运行阶段使用 scratch,只带入 CA 证书与产物。三份模板都以 EXPOSE 承接 port 参数,其它内容不随参数变化。

打分审计(POST /audit)

用途:对已有 Dockerfile 文本给出 0–100 的评分与问题列表,适合作为生成后的自检或存量文件的快速体检。

参数

类型

必填

默认

说明

dockerfile

string

是

—

待审计的 Dockerfile 全文

返回字段要点:score 为百分制得分,按命中的问题数每条扣 20 分;issues 为数组,元素含 severity(High/Medium/Critical)与 msg。当前判定三类问题:检测到 root 用户或完全缺少 USER 指令记 High,基础镜像使用 :latest 记 Medium,文本中出现敏感词记 Critical。全部命中时得分为 40,不会归零。

代码语言:javascript
复制
POST /api/dockerfile-gen/audit?api_key=YOUR_KEY
Content-Type: application/json

{"dockerfile":"FROM alpine:latest\nUSER root\nCMD [\"sh\"]"}

健康检查与统计(GET /ping、GET /stats)

ping 无参数、免鉴权,返回 data.time 服务时间;stats 返回 data.version,当前为 1.0。两者适合放在监控探针与版本核对脚本中,不携带业务数据。

数据与限制

  • 模板共 3 种:node、python、go;未识别的 type 回退 node,不报错、不提示。
  • port 默认 8080,按整数解析后写入 EXPOSE;传入非数字字符串会得到 0。
  • features 为固定三项,不随模板类型变化;security 为固定字符串。
  • audit 每条问题扣 20 分,最多检测三类问题,得分区间为 0–100(实际最低 40)。
  • 接口无持久化:不保存生成的文本,也不提供历史查询;响应均为 JSON,无文件下载或格式切换参数。
  • 生成不涉及网络访问与镜像拉取,仅做模板变量替换。

典型使用场景

  • 新项目脚手架:初始化仓库时按语言调用一次,把返回的 dockerfile 写入构建上下文,避免每个项目各写一份基线文件。
  • 统一基线:多团队并行开发时,用同一接口产出文件,保证多阶段、非 root、最小镜像三项特征一致,便于集中审计。
  • 生成后自检:把生成的文本再提交给审计端点,确认评分与问题列表符合预期,再进入构建流水线。
  • 教学与评审:对比三种模板的分阶段写法,作为容器化改造的参考样例。

注意事项

  • API.md 的示例请求传 type 为 daily,响应却回显 node,这正是静默回退的实际表现;不要把回显值当作请求值的校验结果,需要确认类型时应自行比对。
  • 参数描述的「regex 为空时必填」为文档残留,本接口没有 regex 参数,也不会因缺少 type 返回 4001。
  • audit 在缺少 dockerfile 时返回的 code 为 400,而通用错误码表中最接近的是 4001;调用方应同时用 HTTP 状态与 code 判断,不要只匹配 4001。
  • 审计采用字符串包含判断:任意位置出现 USER 即视为声明了用户,出现在注释里也会被算作已设置;敏感词判断同样只看是否出现,误报与漏报都可能存在。
  • 评分为线性扣分,不区分问题轻重,一个 Critical 与一个 Medium 扣分相同;需要按级别处置时应读取 issues[].severity。
  • 生成的文本与运行环境强相关:Python 模板依赖用户级安装目录的路径约定,Go 模板依赖静态编译成功;落盘后应在目标架构上实际构建验证。
  • 数据鱼API仅提供模板生成与文本打分,不保证产物可直接上线,安全基线仍应结合镜像扫描与运行时策略。

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

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

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