dockerfile-skill

Dockerfile 生成技能

概述

此技能通过一个 4 阶段流程生成可用于生产环境的 Dockerfile：

1. 深入分析 —— 了解项目结构、工作区、迁移和构建复杂度
2. 生成 —— 创建 Dockerfile，并处理迁移和优化构建
3. 构建并修复 —— 通过实际构建进行验证，迭代修复错误
4. 运行时验证 —— 确认迁移已运行、应用正常工作且数据库已填充

主要功能

• 工作区／Monorepo 支持：pnpm 工作区、Turborepo、npm 工作区
• 自定义 CLI 检测：自动检测自定义构建 CLI（turbo、nx、lerna、rush 或项目专用 CLI），并使用正确语法
• Git 哈希绕过：检测并处理需要 git commit 哈希（GITHUB_SHA）的项目
• 构建时环境变量：自动检测 Next.js SSG 并添加占位符
• 错误模式数据库：包含 40 多种已知错误模式及自动修复方法
• 智能 .dockerignore：避免排除工作区必需文件和 CLI 配置依赖项
• 自定义入口点：支持自定义服务启动器
• 迁移检测：自动检测 ORM 和迁移，并处理独立模式
• 构建优化：跳过耗费资源的 CI 任务（lint／类型检查），避免内存不足
• 运行时验证：确认迁移已运行、数据库已填充且应用正常工作
• 原生模块支持：自动检测 Rust／NAPI-RS 模块，支持多架构构建
• 静态资源映射：检测后端预期的静态资源路径，并映射前端输出
• 外部服务：自动检测 PostgreSQL、Redis、MinIO、ManticoreSearch 依赖项
• 无需人工交互：自动生成所有配置文件，包括密钥

用法

/dockerfile          # Analyze current directory
/dockerfile <github-url>    # Clone and analyze GitHub repo
/dockerfile <path>       # Analyze specific 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（完整部署指南）
• 环境变量文档

主要改进：

• 自动检测 Next.js Standalone + ORM → 单独安装依赖
• 自动检测高负载构建操作 → 优化构建命令
• 自动生成所有配置文件 → 无需用户输入

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

加载并执行：modules/build-fix.md

流程：

1. 执行 docker buildx build --platform linux/amd64 --load
2. 成功 → 进入阶段 4
3. 失败 → 解析错误、匹配模式、修复 Dockerfile 并重试
4. 根据复杂度级别设置最大迭代次数

阶段 4：运行时验证

关键新增内容：在运行时验证通过之前，不要宣布成功！

验证步骤：

1. 容器启动：运行 docker-compose up -d 并确认没有崩溃
2. 数据库迁移：

• 查询数据库：psql -c "\dt" → 确认表已创建
• 检查迁移数量是否符合预期（例如，76/76）
• 确认没有出现“relation does not exist”错误

3. 应用健康状况：

• 测试 HTTP 端点 → 200/302/401 均可接受，500 表示失败
• 检查日志中的错误
• 验证健康检查端点

4. 成功标准：只有全部通过后才能宣布成功

为何重要：

• 之前：运行 docker build 后就宣布成功，但应用在运行时无法工作
• 现在：确认迁移已运行、数据库已填充，且应用实际可用
• 避免迁移静默失败（例如，独立模式缺少 ORM 依赖）

支持资源

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

复杂度级别

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

常见问题与解决方案

1. 数据库迁移未运行 - 最关键

症状：运行时出现 relation "users" does not exist 原因：检测到迁移，但从未执行 预防：分析阶段的步骤 12 会检测迁移并配置执行方式 修复：

• 对于 Standalone + ORM：单独安装 ORM 依赖
• 在入口点脚本中添加运行时迁移
• 容器启动后使用 psql -c "\dt" 验证

2. 构建时内存不足

症状：退出代码 137、Killed、堆内存溢出 原因：构建脚本包含对 39+ 个工作区包执行的 lint/类型检查 预防：分析阶段的步骤 13 会检测高资源消耗操作 修复：在 Docker 构建中跳过 CI 任务，将 NODE_OPTIONS 增加到 8192MB

3. 找不到工作区文件

症状：ENOENT: no such file or directory, open '/app/e2e/package.json' 原因：.dockerignore 排除了工作区的 package.json 文件 修复：使用 e2e/* 替代 e2e，然后添加 !e2e/package.json

4. lockfile=false 项目

症状：Cannot generate lockfile because lockfile is set to false 原因：项目在 .npmrc 中设置了 lockfile=false 修复：使用 pnpm install 替代 pnpm install --frozen-lockfile

5. 缺少构建时环境变量

症状：KEY_VAULTS_SECRET is not set 原因：Next.js SSG 在构建时需要环境变量 修复：在构建阶段添加 ARG/ENV 占位符

6. Node 二进制文件路径

症状：spawn /bin/node ENOENT 原因：脚本硬编码了 /bin/node，但 node:slim 将其安装在 /usr/local/bin/node 修复：添加 RUN ln -sf /usr/local/bin/node /bin/node

7. Standalone 模式下找不到 ORM

症状：运行时出现 Cannot find module 'drizzle-orm' 原因：Next.js standalone 不包含全部 node_modules 预防：分析阶段会检测 standalone + ORM 组合 修复：在 /deps 中单独安装 ORM，并复制到最终镜像

8. 使用错误的 monorepo 自定义 CLI 构建命令

症状：构建成功，但缺少输出文件（例如，未找到 assets-manifest.json） 原因：使用了 yarn workspace @scope/pkg build，而不是检测到的自定义 CLI 语法 预防：分析阶段的 Step 14 会检测自定义 CLI 修复：所有构建命令都使用检测到的 CLI 语法

9. 需要 Git 哈希，但 Docker 上下文中没有 .git

症状：出现 Failed to open git repo 或 nodegit 错误 原因：构建工具需要 Git 提交哈希来进行版本管理 预防：分析阶段的 Step 14 会检测 Git 哈希依赖 修复：设置 ENV GITHUB_SHA=docker-build 以绕过 Git 要求

10. CLI 配置文件被 .dockerignore 排除

症状：CLI 初始化（例如，${CLI_NAME} init）静默失败 原因：.prettierrc、.prettierignore 或其他配置文件被排除 预防：分析阶段的 Step 14 会检测配置文件依赖 修复：从 .dockerignore 排除项中移除配置文件

11. 运行时找不到静态资源

症状：ENOENT: no such file or directory, open '/app/static/assets-manifest.json' 原因：前端构建输出路径与后端预期路径不同 预防：分析阶段的 Step 14 会检测静态资源路径映射 修复：在 Dockerfile 中将前端输出复制到后端预期的路径

成功标准

成功的 Dockerfile 必须满足以下要求：

构建阶段：

1. 构建无错误（docker buildx build 以 0 退出）
2. 镜像大小合理（大多数应用小于 2 GB）
3. 遵循生产环境最佳实践（多阶段构建、非 root 用户、固定版本）
4. 包含所有必要的支持文件（.dockerignore、docker-compose.yml 等）
5. 满足所有工作区/monorepo 要求

运行阶段 - 至关重要： 6. 容器成功启动（无崩溃） 7. 成功执行数据库迁移（如果检测到迁移） 8. 已创建数据库表（使用 psql 验证） 9. 应用返回有效的 HTTP 状态码（200/302/401，而不是 500） 10. 日志中没有运行时错误（没有“relation does not exist”等错误）

出现以下情况时，不要宣称成功：

• 构建通过，但运行时失败
• 检测到迁移，但缺少数据库表
• 应用返回 500 错误
• 日志显示数据库关系错误

构建后全面验证

构建成功后，执行完整验证：

# 1. Start services
docker-compose up -d
sleep 30 # Wait for startup

# 2. Check container status
docker-compose ps
# Expected: All containers UP and HEALTHY

# 3. Verify database migrations
if [ migrations_detected ]; then
 # List tables
 docker-compose exec postgres psql -U <user> -d <db> -c "\dt"
 # Expected: List of tables (users, sessions, etc.)
 # If "Did not find any relations" → FAIL

 # Count migrations
 MIGRATION_COUNT=$(docker-compose exec postgres psql -U <user> -d <db> -t -c "SELECT COUNT(*) FROM <migration_table>;")
 # Expected: Matches analysis count (e.g., 76)
fi

# 4. Test application health
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:3210)
# Expected: 200, 302, or 401
# Unacceptable: 500, 502, 503

if [ "$HTTP_CODE" = "500" ]; then
 echo "FAILURE: App returning 500 error"
 docker-compose logs app
 exit 1
fi

# 5. Check for errors in logs
docker-compose logs app | grep -i "error" | tail -20
# Should NOT contain:
# - "relation does not exist"
# - "table not found"
# - "Cannot find module"

# 6. Check image size
docker images <image-name>

# 7. Cleanup (if needed)
docker-compose down

验证清单：

• 镜像构建成功
• 容器启动且未崩溃
• 已建立数据库连接
• 已执行迁移（如适用）
• 数据库表已存在（如适用）
• HTTP 端点返回有效状态
• 应用日志中没有错误
• 健康检查通过