SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场dockerfile-skill

dockerfile-skill

部署与运维

查看项目

更新于 10-15 02:21

技能介绍

用途

dockerfile-skill 用于为任意 GitHub 项目或本地路径生成生产级 Dockerfile。它面向需要将项目容器化的场景，支持 monorepo、多阶段构建、工作区检测，并通过迭代的构建-修复循环确保生成的 Dockerfile 能够实际构建并运行。

主要能力

  • 工作区/Monorepo 支持：识别 pnpm workspace、Turborepo、npm workspaces 等结构。
  • 自定义 CLI 检测：自动检测 turbo、nx、lerna、rush 或项目特定的构建 CLI，并使用正确语法。
  • Git Hash 绕过：检测需要 git commit hash（GITHUB_SHA）的项目并处理。
  • 构建时环境变量：自动检测并为 Next.js SSG 等场景添加占位符。
  • 错误模式数据库：内置 40 多个已知错误模式及自动修复方案。
  • 智能 .dockerignore：避免排除工作区必需文件和 CLI 配置依赖。
  • 自定义入口点：支持自定义服务器启动器。
  • 迁移检测：自动检测 ORM、迁移，并处理 standalone 模式。
  • 构建优化：跳过重型 CI 任务（lint/type-check）以防止内存溢出。
  • 运行时验证：验证迁移是否执行、数据库是否填充、应用是否正常工作。
  • 原生模块支持：自动检测 Rust/NAPI-RS 模块，支持多架构构建。
  • 静态资源映射：检测后端期望的静态路径并映射前端输出。
  • 外部服务：自动检测 PostgreSQL、Redis、MinIO、ManticoreSearch 依赖。
  • 零人工交互：自动生成所有配置文件，包括密钥。

使用方式

通过以下命令调用：

/dockerfile          # 分析当前目录
/dockerfile <github-url>    # 克隆并分析 GitHub 仓库
/dockerfile <path>       # 分析指定路径

调用后按顺序执行：

  1. 读取并执行 modules/analyze.md
  2. 读取并执行 modules/generate.md
  3. 读取并执行 modules/build-fix.md

工作流程

阶段 1：深度项目分析

加载并执行 modules/analyze.md，输出结构化项目元数据，包括：语言/框架/包管理器、构建命令/运行命令/端口、外部依赖（DB/Redis/S3）、系统库需求、迁移系统检测（ORM、迁移数量、执行方式）、构建复杂度分析（重型操作、内存风险）、复杂度等级（L1/L2/L3）。

阶段 2：生成 Dockerfile

加载并执行 modules/generate.md，输入阶段 1 的分析结果，输出：Dockerfile（含迁移处理和构建优化）、.dockerignore（工作区感知）、docker-compose.yml（如需外部服务）、.env.docker.local（仅可选占位键，绝不包含密钥值）、docker-entrypoint.sh（含迁移执行）、DOCKER.md（完整部署指南）、环境变量文档。

阶段 3：构建验证（闭环）

加载并执行 modules/build-fix.md，执行 docker buildx build --platform linux/amd64 --load。成功则进入阶段 4；失败则解析错误、匹配模式、修复 Dockerfile 并重试。最大迭代次数取决于复杂度等级。

阶段 4：运行时验证

在运行时验证通过前不声明成功。验证步骤包括：容器启动（docker-compose up -d 并确认无崩溃）、数据库迁移（查询数据库验证表存在、检查迁移数量匹配、确认无 "relation does not exist" 错误）、应用健康（测试 HTTP 端点，200/302/401 可接受，500 为失败）、检查日志错误。

复杂度等级

等级 标准 最大构建迭代次数
L1 单一语言，无构建步骤，无外部服务，无迁移 1
L2 有构建步骤，有外部服务（DB/Redis），简单迁移 3
L3 Monorepo，多语言，复杂依赖，构建时环境变量，复杂迁移（76+） 5

常见问题与解决方案

  1. 数据库迁移未运行：standalone + ORM 需单独安装 ORM 依赖，在入口脚本添加运行时迁移，容器启动后用 psql 验证。
  2. 构建时内存溢出：跳过 CI 任务，将 NODE_OPTIONS 增至 8192MB。
  3. 工作区文件未找到：.dockerignore 排除工作区 package.json 导致，使用 e2e/* 而非 e2e，再加 !e2e/package.json。
  4. lockfile=false 项目：使用 pnpm install 而非 pnpm install --frozen-lockfile。
  5. 构建时环境变量缺失：在构建阶段添加 ARG/ENV 占位符。
  6. Node 二进制路径：添加 RUN ln -sf /usr/local/bin/node /bin/node。
  7. Standalone 模式下 ORM 未找到：在 /deps 中单独安装 ORM 并复制到最终镜像。
  8. 自定义 CLI 的 monorepo 构建命令错误：使用检测到的 CLI 语法。
  9. 需要 Git hash 但 Docker 上下文中无 .git：设置 ENV GITHUB_SHA=docker-build。
  10. CLI 配置文件被 .dockerignore 排除：从排除列表中移除配置文件。
  11. 运行时静态资源未找到：在 Dockerfile 中将前端输出复制到后端期望路径。

成功标准

构建阶段：无错误构建（docker buildx build 退出码 0）、镜像大小合理（多数应用 < 2GB）、遵循生产最佳实践（多阶段、非 root、固定版本）、包含所有必要支持文件、处理所有工作区/monorepo 需求。

运行时阶段（关键）：容器成功启动、数据库迁移成功执行（如检测到）、数据库表已创建、应用返回有效 HTTP 状态码（200/302/401，非 500）、日志中无运行时错误。

以下情况不得声明成功：构建通过但运行时失败、检测到迁移但表缺失、应用返回 500 错误、日志显示数据库关系错误。

支持资源

  • 模板：templates/ - 按技术栈的基础 Dockerfile 模板
  • 错误模式：knowledge/error-patterns.md - 已知错误与修复
  • 系统依赖：knowledge/system-deps.md - NPM/Pip 包到系统库的映射
  • 最佳实践：knowledge/best-practices.md - Docker 生产最佳实践
  • 输出格式：examples/output-format.md - 预期输出结构

限制

该技能仅分析和写入指定的打包产物（Dockerfile、.dockerignore、可选的 compose/entrypoint/文档及部署侧构建证据），默认保留已有文件和项目值。替换已有文件需要明确的请求决策。生成的报告不包含密钥、环境值、数据库 URL 和连接详情。构建成功不等于运行时验收，必须通过迁移/表、HTTP、健康检查和日志证据。