specsfy-specialist-docker

Docker

何时使用

• 用于编写或审查 Dockerfile、docker-compose.yml、.dockerignore、标签/镜像仓库策略，或排查无法构建、无法启动或未能通过 healthcheck 的容器。
• 也用于缩小镜像体积、清除泄漏到镜像层中的密钥，或修复未能正确接收 SIGTERM 的进程。
• 不用于多节点编排、带副本的滚动发布、集群密钥或 overlay 网络——这些情况请使用 $specsfy-specialist-docker-swarm；这里的 Docker Compose 适用于本地/CI 环境，而非多主机生产拓扑。
• 供应链审查（SBOM、来源证明、有漏洞的依赖项）请与 $specsfy-specialist-application-security 配合；构建内容本身请与项目所用语言/框架对应的 skill 配合。

流程

1. 提出变更前，先确定目标架构（amd64/arm64）、基础运行时（语言、版本）、实际构建上下文，以及预期的运行契约（变量、端口、卷）。
2. 检查项目当前使用的 Dockerfile、.dockerignore、docker-compose.yml 和镜像/标签策略。
3. 当镜像属于发布或部署的一部分时，请在 $specsfy-specialist-deploy 下执行此步骤。使用 $specsfy-specialist-versioning 提供的版本，通过 docker-tag 生成镜像引用；如果 verify-docker-tag 指出不一致，则拒绝该引用。
4. 使用清晰的多阶段构建（multi-stage build）分离构建依赖和运行时依赖——最终镜像不得包含生产环境中不会运行的编译器、软件包缓存或源文件。
5. 通过 lockfile、固定版本或 digest 固定基础镜像，确保制品可重复构建，并缩小构建上下文，减少可变层。
6. 使用非 root 用户运行进程，限制权限（cap_drop，不使用 --privileged），且绝不将密钥嵌入镜像。
7. 明确设置 healthcheck、信号处理（SIGTERM、SIGINT）、卷、网络和外部配置（env、挂载文件）。
8. 构建镜像、扫描漏洞，并严格按照生产环境中的运行方式进行测试（相同用户、相同变量）。

最佳实践

• 对于包含原生扩展的应用，按功能族拆分为独立的构建阶段。Redis、媒体或应用服务器的变更不必使整套工具链失效。
• 多个服务使用相同代码时，构建单个镜像，并在入口点选择进程模式，例如 HTTP、调度器、队列和 WebSocket。每种模式都应根据其功能配置合适的健康检查、信号处理和写入行为。
• 为 SemVer 和 commit 发布不可变引用，确认两者尚不存在，并记录部署使用的摘要。只有在镜像可从 registry 获取后，才能发布 Git 标签。
• 如果框架缓存依赖运行时提供的配置，就在入口点生成缓存。不要将构建期间创建的配置缓存带到值不同的环境中。
• 优先选择兼容的最小基础镜像（技术栈支持时使用 slim/alpine）；当逐字节可复现比自动更新补丁版本更重要时，通过摘要（@sha256:...）固定镜像。
• 对指令排序以最大限度利用缓存（先处理依赖，再处理源代码），同时不要妨碍依赖更新：先执行 COPY package*.json，再执行 RUN install，然后执行 COPY . .，这样代码变更时可以缓存安装过程，又不会锁定已安装的版本。
• 使用 BuildKit 的 secret 和缓存挂载（RUN --mount=type=secret、--mount=type=cache）来处理构建凭据和包管理器缓存；绝不要用 ARG/ENV 存放机密，因为两者都会保留在最终镜像的层历史中。
• 绝不要在没有 .dockerignore 的情况下复制整个仓库——.git、node_modules、本地构建产物和 .env 会泄漏到构建上下文中，并增加镜像大小和构建时间。
• 有意识地将主进程作为 PID 1 处理：使用 exec 形式的 ENTRYPOINT（["cmd"]，而不是 shell 形式的 CMD cmd args），以正确接收信号；或者在进程无法回收僵尸进程时使用最小化 init（--init/tini）。
• 将持久化数据保存在容器可写层之外（命名卷或绑定挂载）——容器可写层中的数据会随容器消失。
• 在工作负载允许时，设置资源限制并将根文件系统设为只读（--read-only，并为需要写入的内容显式挂载卷），以缩小运行时攻击面。

反模式

• 在生产环境中只使用 latest 标签——这种方式不可复现，也无法在不检查容器的情况下确定正在运行的代码。
• 使用 ADD 复制本地文件（而不是 COPY）——ADD 还会解压文件和获取 URL，这种隐式行为会让之后阅读 Dockerfile 的人感到意外。
• 在提供流量的镜像中隐式使用 USER root（未设置 USER）——容器内遭入侵的进程会拥有容器 root 权限，扩大应用中任何漏洞的影响。
• 未使用多阶段构建，却在同一最终层安装构建依赖（编译器、头文件）——这会增大镜像，并增加可扫描的漏洞面，却不会给运行时带来任何好处。
• 健康检查只验证“进程正在端口上监听”，却不检查关键依赖（数据库、队列）——即使容器实际上无法处理请求，编排器仍会认为它是健康的。

验证

• 无缓存的干净构建（--no-cache）和增量构建（使用缓存）—— 两者都应生成在功能上等效的镜像。
• 使用目标环境中的实际用户、架构和环境变量运行镜像，而不只是使用 开发环境的默认值。
• 测试 healthcheck、docker stop（在配置的期限内优雅关闭）、已发布的端口、卷、内部 DNS 解析，以及声明的依赖不可用时的行为。
• 生成 SBOM／运行项目中可用的漏洞扫描器，并检查最终镜像的大小和层数。
• 未运行扫描器时，不要宣称镜像“安全”；未通过重复构建确认基于同一 commit 得到功能相同的结果时，不要宣称镜像“可复现”。

相关技能

• $specsfy-specialist-server-report 使用 Ansible 进行只读采集，按主机汇总日志、服务和磁盘使用情况。

• $specsfy-specialist-deploy 负责协调完整交付；本技能仅处理开发环境的镜像和 Compose。

• $specsfy-specialist-versioning 准备 SEMVER，并在发布前核对镜像身份。

• $specsfy-specialist-docker-swarm 负责多节点编排、集群 secrets、overlay 网络和服务滚动更新——本专家负责镜像和本地 Compose，不负责生产集群。

• $specsfy-specialist-application-security 负责供应链（SBOM、来源证明、依赖项 CVE）以及容器之外的安全加固。

• $specsfy-specialist-observability 负责容器内进程的日志记录、指标和 tracing。

• $specsfy-specialist-postgres、$specsfy-specialist-redis 负责镜像／服务内部运行的内容（schema 建模、数据结构、持久化）——本技能负责打包（官方镜像、卷、healthcheck），不负责数据库／缓存的内部决策。

• $specsfy-specialist-supabase 适用于项目的本地环境由 Supabase CLI 通过 Docker 编排的情况。

• $specsfy-specialist-laravel 负责已打包应用的运行契约（队列 worker、scheduler、预期的环境变量）。

• $specsfy-specialist-debian-server 负责运行镜像的主机上的内核、文件系统、systemd、APT 和 Docker Engine。

请阅读 references/standards.md，了解构建、 Compose、安全、供应链和运维相关标准。