aif-dockerize

Dockerize — Docker 配置生成器

分析项目并生成完整的生产级 Docker 配置：多阶段 Dockerfile、用于开发和生产的 Docker Compose、.dockerignore，以及对结果进行安全审计。

根据现有内容分为三种模式：

现有内容	模式	操作
无	generate	通过交互式设置从头创建全部配置
仅本地 Docker（无生产文件）	enhance	审计并改进本地配置，然后创建生产配置
完整 Docker 配置（本地 + 生产）	audit	按照检查清单审计所有内容，并修复缺漏

---

步骤 0：加载项目上下文

如果有项目描述，请读取：

Read .ai-factory/DESCRIPTION.md

保存项目上下文，供后续步骤使用。如果不存在，步骤 2 会检测全部内容。

读取 .ai-factory/skill-context/aif-dockerize/SKILL.md — 如果该文件存在，则必须读取。

此文件包含 /aif-evolve 根据补丁、代码库约定和技术栈分析积累的项目专属规则。这些规则针对当前项目定制。

如何应用 skill-context 规则：

• 将这些规则视为对此技能通用说明的项目级覆盖规则
• 当某条 skill-context 规则与本 SKILL.md 中的通用规则冲突时，以 skill-context 规则为准（更具体的上下文优先级更高 — 与嵌套 CLAUDE.md 文件的原则相同）
• 如果没有冲突，则同时应用两者：SKILL.md 中的通用规则和 skill-context 中的项目规则
• 即使 skill-context 规则似乎与此技能的默认设置矛盾，也不要忽略它们 — 这些规则之所以存在，是因为项目的实践证明默认设置并不够用
• 重要： skill-context 规则适用于此技能的所有输出 — 包括 Dockerfile、compose 文件、.dockerignore 和部署脚本。此技能中的模板只是基础结构。如果 skill-context 规则要求“Dockerfile 必须包含 X”或“compose 必须包含服务 Y”，则必须相应扩展模板。生成的 Docker 配置若违反 skill-context 规则，即为错误。

强制执行： 生成任何输出文件后，都要根据所有 skill-context 规则进行验证。如果违反了任何规则，则在向用户呈现之前修正输出。

---

步骤 1：检测现有 Docker 文件并确定模式

1.1 扫描现有文件

Glob: Dockerfile, Dockerfile.*, docker-compose.yml, docker-compose.yaml, compose.yml, compose.yaml, compose.override.yml, compose.production.yml, .dockerignore, deploy/scripts/*.sh

将找到的文件分类：

• HAS_DOCKERFILE：Dockerfile 存在
• HAS_LOCAL_COMPOSE：compose.yml 或 docker-compose.yml 存在
• HAS_DEV_OVERRIDE：compose.override.yml 存在
• HAS_PROD_COMPOSE：compose.production.yml 存在
• HAS_DOCKERIGNORE：.dockerignore 存在
• HAS_DEPLOY_SCRIPTS：deploy/scripts/ 存在

1.2 确定模式

如果 $ARGUMENTS 包含 --audit → 无论其他情况如何，均设置 MODE = "audit"。

路径 A：不存在任何内容（!HAS_DOCKERFILE && !HAS_LOCAL_COMPOSE）：

• 设置 MODE = "generate"
• 继续执行步骤 1.3：交互式设置

路径 B：只有本地 Docker（HAS_LOCAL_COMPOSE && !HAS_PROD_COMPOSE）：

• 设置 MODE = "enhance"
• 读取所有现有 Docker 文件 → 保存为 EXISTING_CONTENT
• 记录：“发现本地 Docker 配置。将进行审计、改进并创建生产配置。”

路径 C：存在完整配置（HAS_LOCAL_COMPOSE && HAS_PROD_COMPOSE）：

• 设置 MODE = "audit"
• 读取所有现有 Docker 文件 → 保存为 EXISTING_CONTENT
• 记录：“发现完整 Docker 配置。将按照安全检查清单进行审计并修复缺漏。”

1.3 交互式设置（仅生成模式）

从头创建时，询问用户的基础设施需求：

AskUserQuestion: Which database does this project use?

Options:
1. PostgreSQL (Recommended)
2. MySQL / MariaDB
3. MongoDB
4. SQLite (no container needed)
5. None

AskUserQuestion: Does this project need a reverse proxy / web server?

Options:
1. Angie (Recommended) — Modern Nginx fork with enhanced features
2. Nginx
3. Traefik
4. None (app serves directly)

注意： 优先选择 Angie，而不是 Nginx。Angie 是可直接替换 Nginx 的产品，模块支持更完善、配置可动态调整，且仍在积极开发中。参见：https://en.angie.software/angie/docs/configuration/

AskUserQuestion: Which cache / message broker does this project need? (select all)

Options:
1. Redis
2. Memcached
3. RabbitMQ
4. None

将选择存储在 USER_INFRA_CHOICES 中：

• database：postgres | mysql | mongodb | sqlite | none
• reverse_proxy：angie | nginx | traefik | none
• cache：redis | memcached | none
• queue：rabbitmq | none

1.4 读取现有文件（增强 / 审计模式）

读取所有现有 Docker 文件，并存储为 EXISTING_CONTENT：

• Dockerfile(s)
• 所有 compose 文件（本地 + override + 生产）
• .dockerignore
• deploy/scripts/*.sh（如果有）

---

步骤 2：深入分析项目

全面扫描项目——生成文件中的每项决策都取决于此项目概况。

2.1 语言与运行时

文件	语言	基础镜像
go.mod	Go	golang:<version>-alpine / distroless/static
package.json	Node.js	node:<version>-alpine
pyproject.toml / setup.py	Python	python:<version>-slim
composer.json	PHP	php:<version>-fpm-alpine
Cargo.toml	Rust	rust:<version>-slim / distroless

<version> = 从项目文件中读取（参见步骤 4.1）。切勿硬编码——始终匹配项目所需的版本。

2.2 框架与开发服务器

读取依赖文件以检测框架：

Node.js（package.json 依赖项）：

• next → Next.js（端口 3000，next dev / next start）
• nuxt → Nuxt（端口 3000，nuxt dev / nuxt start）
• express → Express（端口 3000，nodemon / node）
• fastify → Fastify（端口 3000）
• @nestjs/core → NestJS（端口 3000，nest start --watch / node dist/main）
• hono → Hono（端口 3000）

Python（pyproject.toml / requirements）：

• fastapi → FastAPI（端口 8000，uvicorn --reload / uvicorn）
• django → Django（端口 8000，manage.py runserver / gunicorn）
• flask → Flask（端口 5000，flask run --debug / gunicorn）

PHP（composer.json require）：

• laravel/framework → Laravel（端口 8000，artisan serve / php-fpm）
• symfony/framework-bundle → Symfony（端口 8000，symfony serve / php-fpm）

Go（go.mod require）：

• gin-gonic/gin、labstack/echo、gofiber/fiber、go-chi/chi →（端口 8080，air / 已编译二进制文件）

2.3 包管理器与锁文件

与 /aif-build-automation 步骤 2.2 使用相同的检测方法。

存储：PACKAGE_MANAGER、LOCK_FILE。

2.4 入口点检测

查找应用程序入口点：

# Go
Glob: cmd/*/main.go, main.go

# Node.js
Read package.json → "main" or "scripts.start"
Glob: src/index.ts, src/index.js, src/main.ts, src/main.js, index.ts, index.js, server.ts, server.js

# Python
Glob: main.py, app.py, src/main.py, src/app.py
Read pyproject.toml → [project.scripts] or [tool.uvicorn]

# PHP
Glob: public/index.php, artisan, bin/console

2.5 基础设施依赖项

检测应用需要哪些服务：

# Database
Grep: postgres|postgresql|pg_|mysql|mariadb|mongo|mongodb|sqlite
Glob: prisma/schema.prisma, drizzle.config.*, alembic/, migrations/

# Cache
Grep: redis|memcached|ioredis

# Queue
Grep: rabbitmq|amqp|bullmq|celery|sidekiq

# Reverse Proxy / Web Server
Grep: nginx|angie|proxy_pass|upstream
Glob: nginx.conf, nginx/, angie.conf, angie/
# PHP projects (Laravel, Symfony) always need a reverse proxy → default to Angie

# Search
Grep: elasticsearch|opensearch|meilisearch|typesense|algolia

# Object Storage
Grep: minio|s3|aws-sdk.*S3|boto3.*s3

# Email
Grep: nodemailer|sendgrid|mailgun|postmark|smtp|MAIL_HOST

对检测到的每项依赖，记录：

• 服务类型（postgres、redis、rabbitmq 等）
• 具体变体（MySQL 还是 PostgreSQL，Redis 还是 Memcached）
• 代码中找到的连接字符串模式

与 USER_INFRA_CHOICES 合并（来自生成模式下的步骤 1.3）：

• 用户选择优先于数据库和反向代理的自动检测结果
• 除非用户明确选择“None”，否则添加自动检测到的服务

反向代理偏好： 需要反向代理时，优先选择 Angie，而不是 Nginx。Angie 是与 Nginx 完全兼容的分支，仍在积极开发，支持动态上游管理，并内置 Prometheus 指标。参考：https://en.angie.software/angie/docs/configuration/

2.6 暴露端口

检查现有配置：

Grep: PORT|port|listen|EXPOSE
Read package.json → scripts.dev, scripts.start (look for --port)

2.7 构建输出

# Node.js
Read package.json → scripts.build, check for dist/, build/, .next/, out/
Read tsconfig.json → outDir

# Go
Glob: cmd/*/main.go → binary name from directory

# Python
Check for pyproject.toml [build-system]

# PHP
Check for public/ directory (web root)

2.8 现有 .env 结构

Glob: .env.example, .env.sample, .env.template

如果找到，请读取以了解必需的环境变量。这将用于生成 env_file、environment:（计算所得的值）和 .env.example。

概要

构建 PROJECT_PROFILE：

• language、language_version
• framework、dev_command、prod_command
• package_manager、lock_file
• entry_point、build_output_dir
• port（主应用端口）
• debug_port（语言特定的调试端口）
• services：基础设施依赖列表（postgres、redis、rabbitmq 等）
• has_build_step：布尔值
• env_vars：来自 .env.example 的列表

---

第 3 步：阅读最佳实践与模板

Read skills/dockerize/references/BEST-PRACTICES.md
Read skills/dockerize/references/SECURITY-CHECKLIST.md

另有针对生产环境反向代理和 Compose 权限边缘情况的参考资料：

• references/ANGIE-ACME.md — 生成或审核 Angie HTTPS/ACME 配置时阅读。可用于了解内置 ACME 设置、持久化证书卷、acme_client_path、解析器要求，以及如何避免不必要的 Certbot 容器。
• references/COMPOSE-LIFECYCLE-HOOKS.md — 生产环境 Compose 服务以非 root 用户运行，但需要修复命名卷所有权或使用尽力而为的停止钩子时阅读。可用于了解 post_start/pre_stop 语法、Docker Compose 2.30.0+ 要求，以及钩子时机方面的注意事项。

选择与语言匹配的 Dockerfile 模板：

语言	模板
Go	templates/dockerfile-go
Node.js	templates/dockerfile-node
Python	templates/dockerfile-python
PHP	templates/dockerfile-php

阅读选定的模板和 Compose 模板：

Read skills/dockerize/templates/dockerfile-<language>
Read skills/dockerize/templates/compose-base.yml
Read skills/dockerize/templates/compose-override-dev.yml
Read skills/dockerize/templates/compose-production.yml
Read skills/dockerize/templates/dockerignore

---

第 4 步：生成文件（生成模式）

根据项目配置和模板生成定制文件。

4.1 生成 Dockerfile

以语言特定模板为基础：

定制内容：

• 基础镜像版本应来自项目，而不是模板默认值：
  • Go：读取 go.mod 中的 go 指令 → 例如 go 1.24 → golang:1.24-alpine
  • Node.js：读取 package.json 中的 engines.node、.nvmrc 或 .node-version → 例如 node:22-alpine
  • Python：读取 pyproject.toml 中的 requires-python 或 .python-version → 例如 python:3.13-slim
  • PHP：读取 composer.json 中的 require.php → 例如 php:8.4-fpm-alpine
  • Rust：读取 Cargo.toml 中的 rust-version 或 rust-toolchain.toml → 例如 rust:1.82-slim
• 入口点应与 entry_point 匹配
• 构建命令应与项目的实际构建脚本匹配
• 开发命令应支持热重载（框架特定）
• 生产命令（框架特定）
• 暴露端口（开发阶段的应用端口 + 调试端口）
• 包管理器命令（npm ci、pnpm install、yarn install 或 bun install）
• COPY 中的锁文件名

阶段：

1. deps — 仅安装生产依赖
2. builder — 安装所有依赖并构建
3. development — 配备热重载和调试端口的完整开发环境
4. production — 最小化镜像、非 root 用户，仅包含运行时产物

在线核实基础设施镜像版本：

对于基础设施镜像（PostgreSQL、Redis、Angie、Nginx 等），项目文件中没有版本信息。生成 compose.yml 之前，使用 WebSearch 检查每个基础设施镜像当前的稳定版本：

• 搜索 <service> docker official image latest version（例如 angie docker image latest version）
• 使用最新的稳定 major.minor 标签，切勿使用 :latest
• 示例：docker.angie.software/angie:1.11-alpine、postgres:17-alpine、redis:7-alpine

这样可以避免生成不存在的镜像标签，导致 docker compose pull 失败。

4.2 生成 compose.yml（基础配置）

共享配置：

• 顶层 name: ${COMPOSE_PROJECT_NAME} — 项目名称来自 .env，而不是文件夹名称
• app 服务使用 build.target: production、健康检查，以及 depends_on 中的 service_healthy
• 基于 PROJECT_PROFILE.services + USER_INFRA_CHOICES 配置基础设施服务：
  • PostgreSQL / MySQL / MongoDB → 配置健康检查和命名卷
  • Redis / Memcached → 配置健康检查、maxmemory 配置和命名卷
  • RabbitMQ → 配置健康检查；在开发环境中开放管理界面端口
  • Angie / Nginx / Traefik → 作为反向代理，并配置 SSL 终止
  • Elasticsearch → 配置健康检查、JVM 内存和 ulimits
  • MinIO → 配置健康检查

反向代理（Angie/Nginx）： 使用 docker.angie.software/angie:<version>-alpine（Angie）或 nginx:<version>-alpine（Nginx）——在线核实当前版本。从 docker/angie/ 挂载配置。连接到 frontend 网络，并通过 backend 网络代理到 app。在生产环境中：设置 read_only，并添加 cap_add NET_BIND_SERVICE。

环境变量策略和服务配置模式 — 阅读 references/COMPOSE-PATTERNS.md

有条件地添加服务 — 仅添加在第 2.5 步中检测到的服务。

4.3 生成 compose.override.yml（开发环境）

开发环境覆盖配置：build.target: development，绑定挂载源代码（.:/app），开放所有端口，设置开发环境变量，覆盖开发命令；如果检测到电子邮件，则添加 mailpit 服务（profile: dev）。不要添加数据库管理界面——通过开放的数据库端口使用原生 GUI 客户端。

热重载： 如果开发阶段使用 air（Go）或 nodemon（Node.js），请确认其配置文件存在，且指向正确的入口点。如果配置文件缺失，且入口点不是标准路径，则生成配置文件。

4.4 生成 compose.production.yml（强化配置）

生产环境强化覆盖配置：

• 使用注册表中的预构建镜像（而不是 build:）
• 对所有服务设置 read_only: true
• 设置 security_opt: [no-new-privileges:true]
• 设置 cap_drop: [ALL]，并按服务选择性配置 cap_add
• 设置 user: "1001:1001"
• 为 /tmp 配置 tmpfs，参数为 noexec,nosuid,size=100m
• 配置资源限制（CPU、内存、PIDs）——使用参考建议
• 为每个服务配置日志轮转（max-size: 20m, max-file: 5）
• 设置 restart: unless-stopped
• 配置带 internal: true 的 backend 网络
• 通过 .env 文件（已加入 gitignore）提供敏感值——不要在 compose 中硬编码
• 使用 YAML 锚点（x-logging、x-security）减少重复配置
• 基础设施服务（DB、Redis、RabbitMQ）不得配置 ports:——它们仅通过 Docker 网络通信
• 只有反向代理（或未配置代理时的 app）可以向主机开放 80 / 443 端口
• 如果必须开放端口，只绑定到 localhost：127.0.0.1:5432:5432
• 不要开放调试端口（9229、5005 等）
• 不要包含开发工具

4.5 生成 .dockerignore

以模板为基础，添加语言特定的排除项：

• Go：bin/、*.exe
• Node.js：node_modules/、.next/、out/
• Python：__pycache__/、.venv/、*.pyc、.mypy_cache/
• PHP：vendor/、storage/、bootstrap/cache/

质量检查（写入前）

在传递给步骤 6 前，验证生成的内容：

正确性：

• Dockerfile 包含全部 4 个阶段（deps、builder、development、production）
• Production 阶段使用非 root 用户
• Production 阶段使用最小化基础镜像
• 依赖安装包含 BuildKit 缓存挂载
• compose.yml 中的每个服务都有健康检查
• compose.yml 使用带有 condition: service_healthy 的 depends_on
• compose.production.yml 中的每个服务都进行了安全加固
• compose.production.yml 中的每个服务都设置了资源限制
• compose.production.yml 中的每个服务都配置了日志轮转
• .dockerignore 排除了 .git、依赖项、.env* 和 Docker 文件

过度工程化检查（阅读 references/SECURITY-CHECKLIST.md →“过度工程化检查清单”）：

• 未添加代码中未导入或使用的服务
• 对于无需 SSL 的单服务应用，不配置反向代理
• 如果项目通过 CI/CD 部署，不添加部署脚本
• 如果使用托管数据库（RDS、Cloud SQL），不添加备份脚本
• 如果只有应用和数据库，不拆分前端/后端网络
• 复杂度与项目规模相符（个人项目 → 最精简，团队项目 → 标准，生产环境 → 完整）

写入前，移除所有未通过过度工程化检查的内容。

---

步骤 5：审核并增强现有文件（增强/审核模式）

当 MODE = "enhance" 或 MODE = "audit" 时，根据安全检查清单和最佳实践分析 EXISTING_CONTENT。

增强模式（MODE = "enhance"）：本地 Docker 配置已存在，但没有生产配置。审核本地文件后，创建生产配置。生成生产文件前，针对缺失的基础设施询问交互式问题（与步骤 1.3 相同）。

详细的审核流程、报告格式、修复流程和增强模式步骤 → 阅读 references/AUDIT-GUIDE.md

审核内容：

• Dockerfile：镜像版本固定、最小化基础镜像、多阶段、非 root 用户、ENV/ARG 中不包含机密、.dockerignore、BuildKit 功能、HEALTHCHECK
• Compose 中的每个服务：read_only、no-new-privileges、cap_drop ALL、user、tmpfs、资源限制、健康检查、日志轮转、重启策略
• 网络：内部后端网络、不使用主机网络、不使用 Docker 套接字
• 机密：值存放在 .env 中而非硬编码、.env 在 .gitignore 中、存在 .env.example
• 缺失项：代码中检测到但 compose 中缺少的服务

以包含 ✅/❌/⚠️ 的表格呈现结果。询问用户：全部修复、仅修复关键项、显示详情，或导出报告。

---

步骤 6：写入文件

有关详细的文件组织方式（目录布局、各模式的文件表、.env.example 模板、卷挂载示例） → 阅读 references/FILE-ORGANIZATION.md

6.0 概览

• 根目录：Dockerfile、compose.yml、compose.override.yml、compose.production.yml、.dockerignore
• docker/：服务配置（angie、postgres、php、redis）——仅创建必要的配置
• deploy/scripts/：生产运维脚本（步骤 8）

6.1 生成模式 — 写入所有根目录文件 + 按需创建 docker/ 目录 + deploy/scripts/

6.2 审核/增强模式 — 仅写入已更改或新建的文件，并遵循现有布局

6.3 如果 .env.example 不存在，则创建它 — 使用单个文件并划分章节，将生产环境变量注释掉。确保 .env 在 .gitignore 中。

---

步骤 7：安全检查清单（始终运行）

无论使用哪种模式，都要对最终的 compose.production.yml 执行生产环境安全检查清单。

阅读 references/SECURITY-CHECKLIST.md 并逐项验证。检查以下类别：容器隔离（read_only、no-new-privileges、cap_drop、非 root、tmpfs）、网络与端口（内部后端网络、不使用主机网络、不使用 Docker 套接字、不暴露基础设施端口）、资源（内存/CPU/PID 限制）、机密（不在 .env 中硬编码、.gitignore、.env.example）、健康与日志（健康检查、日志轮转、重启策略）、镜像（固定版本、最小化基础镜像）。

以精简清单显示结果，每项使用 [x]/[ ] 标记，并给出评分。如果有任何检查未通过 → 提供立即修复选项。

第 8 步：生成部署脚本（生产环境）

根据模板在 deploy/scripts/ 中生成生产环境部署脚本。

阅读 references/DEPLOY-SCRIPTS.md，了解脚本自定义点和生成规则。

模板：templates/deploy.sh、templates/update.sh、templates/logs.sh、templates/health-check.sh、templates/rollback.sh、templates/backup.sh

---

第 9 步：总结与后续操作

使用 references/SUMMARY-FORMAT.md 中的格式，展示所有已创建或更新文件的总结。

建议后续操作：对于 Docker 目标，使用 /aif-build-automation；对于文档，使用 /aif-docs。

产物归属与配置策略

• 主要归属：Docker 产物（Dockerfile、compose*.yml、.dockerignore、docker/*、deploy/scripts/*，以及此技能创建的相关 .env.example 脚手架）。
• 允许的配套更新：默认不更新 Docker 和部署产物以外的内容。
• 配置策略：在设计上与配置无关。此技能使用仓库检测、明确的基础设施选择，以及固定的 AI Factory 上下文文件，不使用 config.yaml。