dockerfile-skill

Dockerfile 生成技能

身份与发现

• 所有者： dockerfile-skill（/dockerfile，以及 Dockerfile、容器化、build-fix 或 Docker 构建请求）。
• 类别： local-artifact-mutation，并通过验证后的交接流程交给 sealos-deploy。
• 金丝雀： DFS-RUNTIME-ACCEPT、DFS-OWNED-FILES 和 DFS-REDACT。

范围与边界

接受本地路径或 GitHub URL，也可以附带来自 cloud-native-readiness 的就绪报告。分析并且只写入指定的打包产物（Dockerfile、.dockerignore、可选的 compose/entrypoint/文档及部署端构建证据）；默认保留现有文件和项目值。替换文件前，必须先记录明确的请求决策。接受结果前，必须完成构建、迁移、HTTP 和日志验证。

风险与确认

不要在报告中包含生成的密钥、环境值、数据库 URL 或连接详情。安装必需的软件包或系统工具时，遵循当前项目的确认边界。绝不能将成功的 docker build 视为运行时验收；DFS-RUNTIME-ACCEPT 金丝雀要求提供迁移/表、HTTP、健康状况和日志证据。

生命周期工作流

针对每个请求，分析项目、生成归属明确的打包产物、执行闭环构建/修复阶段，并运行运行时验证。输出请求范围内的 success、stopped 或 error；现有的四阶段工作流 Deep Analysis → Generate → Build & Fix → Runtime Validation 仍作为以下领域扩展。

渐进式披露

到达相应阶段时，逐层加载 modules/analyze.md、modules/generate.md 和 modules/build-fix.md。仅从这些归属分支加载知识/模板，并保留现有的错误模式路由。

输出、停止与错误状态

• success：来源/出处、指定的打包文件、成功的镜像/构建标识、迁移/数据库证明、HTTP/健康响应、无异常的运行时日志、验证证据和脱敏结果。
• stopped：尚未解决的分析问题、缺失的前置条件、替换或安装决策，或不可用的运行时输入；同时提供已观察到的证据、脱敏结果和安全的后续操作；不得声称已部分验收。
• error：构建、迁移、HTTP、健康状况或日志步骤失败；同时提供相关产物、已清理的诊断信息、脱敏结果和恢复操作。

交接

对于直接打包请求，发送以下完整的类型化交接内容。部署必须保留自身的资格条件和 Runtime Truth 门槛。

target: sealos-deploy
inputArtifact: validated Dockerfile and build/runtime result with source provenance
allowedAction: build or reuse an image within the selected deployment scope
failureReturn: failing packaging, migration, HTTP, health, or runtime-log phase
responseOwner: dockerfile-skill

验证

使用此条目中的运行时验证命令，对已更改的辅助程序运行 node --check，并运行基线案例 dockerfile-positive-build-runtime 和 dockerfile-violating-build-only。验证实际容器行为、迁移、HTTP、日志、文件范围和脱敏情况。

打包结果约定

结果必须限定于当前请求，并使用相对于仓库的路径。构建产物只有在运行时结果获验收后， 才能成为成功的交接内容。

source: local path or GitHub source, with readiness provenance when provided
owned_files: named files planned, created, preserved, or changed
build:
  dockerfile_valid: true | false
  image_identity: redacted tag or digest
  result_artifact: docker-build/build-result.json
runtime:
  migration: applicable | not_applicable | failed
  database_or_state_proof: observed evidence or null
  http_health: accepted response and health evidence or null
  log_analysis: error count and sanitized findings
  result_artifact: docker-build/validation-result.json
verification:
  redaction: pass | fail
  helper_checks: named commands and outcomes
terminal_state: success | stopped | error
safe_next_action: request-scoped recovery or handoff action

success 要求提供 Dockerfile 和构建结果，以及适用的迁移、HTTP/健康状况和运行时日志检查。结果绝不包含密码、令牌、环境值、数据库 URL 或完整连接字符串。

概述

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

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

核心功能

• 工作区/Monorepo 支持：pnpm workspace、Turborepo、npm workspaces
• 自定义 CLI 检测：自动检测自定义构建 CLI（turbo、nx、lerna、rush 或项目专用 CLI），并使用正确的语法
• Git 哈希绕过：检测并处理需要 Git 提交哈希（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 依赖
• 在 entrypoint 脚本中添加运行时迁移
• 容器启动后使用 psql -c "\dt" 验证

2. 构建期间内存不足

症状：退出代码 137、Killed、堆内存不足 原因：构建脚本包含针对 39+ 个工作区包的 lint/type-check 预防：分析阶段第 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. 使用自定义 CLI 的 Monorepo 构建命令错误

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

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

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

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

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

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

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

成功标准

成功的 Dockerfile 必须满足：

构建阶段：

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

运行阶段 — 至关重要： 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 端点返回有效状态
• 应用日志中没有错误
• 健康检查通过