docker

Docker

采用安全优先默认设置的生产级 Docker 容器化方案。

---

资源检测与适配

生成 Dockerfile/Compose 前，检测环境：

# Detect host machine memory
sysctl -n hw.memsize 2>/dev/null | awk '{print $0/1024/1024/1024 " GB"}' || \
  grep MemTotal /proc/meminfo | awk '{print $2/1024/1024 " GB"}'

# Detect Docker allocated resources
docker info --format 'Memory: {{.MemTotal}}, CPUs: {{.NCPU}}'

# Detect available disk space
docker system df

根据检测结果调整配置：

检测到的 Docker 内存	配置档	构建内存	容器限制
< 4GB	受限	1GB	256Mi
4-8GB	最小	2GB	512Mi
8-12GB	标准	4GB	1Gi
> 12GB	扩展	8GB	2Gi

Agent 行为

1. 检测生成 compose.yaml 前的 Docker 资源
2. 调整资源限制，使其适应可用内存
3. 警告资源不足可能导致构建失败
4. 计算安全限制：docker_memory * 0.6 / container_count

自适应 Compose 模板

受限（Docker 内存 < 4GB）：

services:
  app:
    deploy:
      resources:
        limits:
          memory: 256M
          cpus: '0.25'
    build:
      args:
        - BUILDKIT_STEP_LOG_MAX_SIZE=10000000

⚠️ Agent 应警告：“Docker 内存不足。多阶段构建可能失败。”

标准（Docker 内存为 4-8GB）：

services:
  app:
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '0.5'
        reservations:
          memory: 256M

扩展（Docker 内存 > 8GB）：

services:
  app:
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: '1.0'
        reservations:
          memory: 512M

构建前验证

运行 docker build 前，Agent 应验证：

# Check available memory
docker info --format '{{.MemTotal}}' | awk '{if ($1 < 4000000000) print "WARNING: Low memory"}'

如果资源受限：使用 --memory 标志，并提醒用户构建可能失败。

---

此技能的功能

分析与检测：

• 自动检测运行时、框架、版本和入口点（无需提问）
• 扫描 .env 文件，将内容分类为机密、构建参数或运行时配置
• 检测原生依赖项，生成正确的构建依赖项
• 识别缺失的配置（Next.js standalone、健康检查端点）

生成：

• 根据你的项目结构创建定制的多阶段 Dockerfile
• 生成采用安全默认设置（非 root、只读、资源限制）的 compose.yaml
• 缺少健康检查端点时添加
• 修复配置问题（例如，为 Next.js 添加 output: 'standalone'）

验证：

• 交付前构建开发和生产目标
• 验证健康检查端点是否正常工作
• 确认生产环境使用非 root 用户
• 警告可能泄露到镜像中的机密
• 报告镜像大小

安全：

• 绝不将机密写入镜像
• 默认使用非 root 用户
• 尽量缩小攻击面（多阶段构建）
• 固定版本（不使用 :latest）
• 包含安全扫描命令

此技能不包含的功能

• 生成 Kubernetes 清单（请使用专用的 k8s 技能）
• 创建 Helm 图表（请使用专用的 helm 技能）
• 处理 Bun/Deno（请使用专用技能）
• 不经定制而盲目复制模板

---

实施前

收集上下文，确保成功实施：

来源	收集内容
代码库	包文件、现有 Dockerfile、.env 模式
对话	开发或生产目标、基础镜像偏好
技能参考	框架模式、多阶段构建、安全性
用户指南	镜像仓库惯例、命名标准

---

需要澄清的信息

无法自动检测时进行询问：

问题	何时询问
目标环境	“要为开发环境还是生产环境构建？”
基础镜像偏好	“使用标准精简镜像还是企业加固镜像？”
现有 Docker 文件	“增强现有 Dockerfile，还是新建一个？”
目标镜像仓库	“仅用于本地，还是要推送到镜像仓库？”

---

检测运行时

存在的文件	运行时	包管理器
requirements.txt、pyproject.toml、uv.lock	Python	pip/uv
pnpm-lock.yaml	Node.js	pnpm
yarn.lock	Node.js	yarn
package-lock.json	Node.js	npm

---

自动检测（不要提问——从文件中检测）

Python

内容	检测依据
Python 版本	pyproject.toml (requires-python)、.python-version、runtime.txt
框架	代码中的导入（from fastapi、from flask、import django）
包管理器	uv.lock → uv、poetry.lock → poetry，否则使用 pip
原生依赖	扫描依赖项：psycopg2、cryptography、numpy、pillow
应用入口点	查找 app = FastAPI()、app = Flask() 或 manage.py

Node.js

内容	检测依据
Node 版本	.nvmrc、.node-version、package.json (engines.node)
框架	package.json 中的依赖项（next、express、@nestjs/core）
包管理器	pnpm-lock.yaml → pnpm、yarn.lock → yarn，否则使用 npm
输出类型	Next.js：检查 next.config.js 中的 output: 'standalone'

自动修复问题

问题	操作
Next.js 缺少 output: 'standalone'	在 next.config.js 中添加该配置
未找到健康检查端点	创建 /health/live 和 /health/ready
使用 uv 但没有 uv.lock	先运行 uv lock
有 pyproject.toml 但没有构建系统	使用 uv pip install -r pyproject.toml

---

工作流

1. SCAN PROJECT
   - Detect runtime, framework, version, entrypoint
   - Find dependency files, native deps
   - Locate existing Docker files (don't blindly overwrite)
         ↓
2. ANALYZE ENVIRONMENT
   - Scan all .env* files
   - Classify: SECRET (never bake) / BUILD_ARG / RUNTIME
   - Flag security issues
         ↓
3. FIX CONFIGURATION
   - Add Next.js `output: 'standalone'` if missing
   - Create health endpoints if missing
   - Generate .env.example with safe placeholders
         ↓
4. GENERATE FILES
   - Dockerfile (customized CMD, paths, build deps)
   - .dockerignore (excludes .env, secrets)
   - compose.yaml (with security defaults)
         ↓
5. VALIDATE & TEST
   - docker build --target dev -t app:dev .
   - docker build --target production -t app:prod .
   - Test health endpoints
   - Verify non-root user
   - Report image size
         ↓
6. DELIVER WITH CONTEXT
   - All files with explanations
   - Security scan command
   - Any warnings about secrets
   - Rollback instructions if replacing existing

仅在确实存在歧义时提问（例如，单体仓库中有多个应用、配置相互冲突）

---

基础镜像决策矩阵

选项	适用场景	权衡
Slim {runtime}:X-slim	通用生产环境（默认）	适用范围广，无需身份验证
DHI dhi.io/{runtime}:X	SOC2/HIPAA、企业级场景	需要执行 docker login dhi.io
Alpine {runtime}:X-alpine	追求最小体积	原生依赖可能存在 musl 问题

默认：Slim（适用范围广，无需身份验证）

---

阶段结构

deps/base  → Install dependencies (cached layer)
    ↓
builder    → Build/compile application
    ↓
dev        → Hot-reload, volume mounts (--target dev)
    ↓
production → Minimal DHI runtime (--target production)

构建命令

docker build --target dev -t myapp:dev .
docker build --target production -t myapp:prod .

---

Python 模式

框架 CMD

框架	开发环境	生产环境
FastAPI	uvicorn app.main:app --reload	uvicorn app.main:app --workers 4
Flask	flask run --debug	gunicorn -w 4 app:app
Django	python manage.py runserver	gunicorn -w 4 project.wsgi

缓存挂载（uv/pip）

RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=cache,target=/root/.cache/pip \
    uv pip install -r requirements.txt

优雅关闭（FastAPI）

@asynccontextmanager
async def lifespan(app: FastAPI):
    yield  # startup
    # shutdown logic here

---

Node.js 模式

框架构建

框架	构建	输出
Next.js	next build	.next/standalone
Express	tsc	dist/
NestJS	nest build	dist/

缓存挂载

# pnpm
RUN --mount=type=cache,target=/root/.local/share/pnpm/store \
    pnpm install --frozen-lockfile

# npm
RUN --mount=type=cache,target=/root/.npm npm ci

# yarn
RUN --mount=type=cache,target=/usr/local/share/.cache/yarn \
    yarn install --frozen-lockfile

优雅关闭（Node.js）

process.on('SIGTERM', () => {
  server.close(() => process.exit(0));
});

---

安全检查清单

交付前，请验证：

• 生产阶段使用非 root 用户 USER
• Dockerfile 或镜像层中不包含密钥
• .dockerignore 排除 .env、.git 和密钥
• 多阶段构建将构建工具与运行环境分开
• 使用 DHI 或加固后的基础镜像
• 已定义 HEALTHCHECK 指令
• 生产阶段不安装软件包
• 通过运行时环境变量或挂载文件提供密钥

---

输出文件

文件	用途
Dockerfile	多阶段、多目标构建
.dockerignore	排除敏感或不必要的文件
compose.yaml	本地开发环境堆栈
health.py / 健康检查端点	框架专用的健康检查

---

参考文件

始终先阅读

文件	用途
references/env-analysis.md	关键：密钥检测、.env 分类
references/production-checklist.md	关键：交付前验证

特定框架

文件	阅读时机
references/python/fastapi.md	FastAPI：uvicorn、lifespan
references/python/flask.md	Flask：gunicorn、蓝图
references/python/django.md	Django：gunicorn、中间件
references/python/native-deps.md	检测 psycopg2、cryptography 等
references/node/nextjs.md	Next.js：standalone、ISR
references/node/package-managers.md	npm/yarn/pnpm 缓存

可选

文件	阅读时机
references/docker-hardened-images.md	用户需要企业级安全（DHI）时
references/multi-stage-builds.md	复杂的构建模式

模板（参考模式）

templates/ 中的模板是参考模式，不是可直接复制粘贴的文件。

Agent 必须：

1. 阅读模板以了解结构
2. 根据实际项目自定义路径、CMD 和构建阶段
3. 生成入口点正确的 Dockerfile（例如，src.app.main:app）
4. 绝不输出类似“# Replace based on framework”的占位注释

自定义示例：

# Template says:
CMD ["uvicorn", "app.main:app", ...]

# Agent detects app at src/api/main.py, generates:
CMD ["uvicorn", "src.api.main:app", ...]