Docker 容器化部署指南：Node.js/Python 最佳实践、常用命令与故障排除 | SkillsMDDocker 容器化部署指南：Node.js/Python 最佳实践、常用命令与故障排除
docker by claude-dev-suite/claude-dev-suite
npx skills add https://github.com/claude-dev-suite/claude-dev-suite --skill docker🇨🇳中文介绍
Docker 核心知识
深度知识：使用 mcp__documentation__fetch_docs 并指定技术为 docker 以获取全面的文档。
Dockerfile (Node.js)
# Build stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
# Production stage
FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./
USER node
EXPOSE 3000
CMD ["node", "dist/index.js"]
Dockerfile (Python)
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
USER nobody
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
常用命令
# Build
docker build -t myapp:latest .
docker build -f Dockerfile.prod -t myapp:prod .
# Run
docker run -d -p 3000:3000 --name myapp myapp:latest
docker run --env-file .env myapp:latest
# Manage
docker ps # List running
docker logs myapp # View logs
docker exec -it myapp sh # Shell access
docker stop myapp # Stop container
docker rm myapp # Remove container
# Images
docker images # List images
docker rmi myapp:latest # Remove image
docker system prune # Clean up
🇺🇸English
Docker Core Knowledge
Deep Knowledge : Use mcp__documentation__fetch_docs with technology: docker for comprehensive documentation.
Dockerfile (Node.js)
# Build stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
# Production stage
FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./
USER node
EXPOSE 3000
CMD ["node", "dist/index.js"]
Dockerfile (Python)
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
USER nobody
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
Common Commands
# Build
docker build -t myapp:latest .
docker build -f Dockerfile.prod -t myapp:prod .
# Run
docker run -d -p 3000:3000 --name myapp myapp:latest
docker run --env-file .env myapp:latest
# Manage
docker ps # List running
docker logs myapp # View logs
docker exec -it myapp sh # Shell access
docker stop myapp # Stop container
docker rm myapp # Remove container
# Images
docker images # List images
docker rmi myapp:latest # Remove image
docker system prune # Clean up
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者，精准高效
最佳实践
| 应该做 | 不应该做 |
|---|
| 使用多阶段构建 | 以 root 身份运行 |
| 使用 .dockerignore | 复制 node_modules |
| 使用特定的基础镜像标签 | 在生产环境中使用 latest |
| 每个容器一个进程 | 安装不必要的包 |
| 利用层缓存（先 COPY package.json） | 硬编码密钥 |
.dockerignore
node_modules
.git
.env*
dist
*.log
何时不使用此技能
- 使用 docker-compose.yml 管理多容器应用时 - 使用
docker-compose 技能
- 在 Kubernetes 中编排容器时 - 使用
kubernetes 技能
- CI/CD 流水线自动化时 - 使用
github-actions 技能
- 仅运行第三方镜像而不创建 Dockerfile 时
- 使用抽象了 Docker 的容器平台时（例如 Heroku、Google Cloud Run 配置）
反模式
| 反模式 | 问题 | 解决方案 |
|---|
在生产环境中使用 :latest | 部署不可预测 | 固定特定版本 node:20.10.0-alpine |
| 以 root 身份运行 | 安全漏洞 | 使用 USER node 或创建非 root 用户 |
复制 node_modules/ | 构建缓慢，平台问题 | 添加到 .dockerignore，在容器内运行 npm ci |
| 安装开发依赖项 | 镜像臃肿 | 使用 npm ci --only=production |
| 不使用多阶段构建 | 生产镜像过大 | 分离构建和运行时阶段 |
| 在 ENV 中硬编码密钥 | 密钥在镜像层中暴露 | 使用 Docker 密钥或在运行时挂载 |
| 每个命令一个 RUN | 层数过多 | 使用 && 链接相关命令 |
不使用 .dockerignore | 上下文传输缓慢 | 排除不必要的文件 |
| 安装不必要的包 | 攻击面增大，镜像体积变大 | 仅安装必需的包 |
| 没有健康检查 | 不健康的容器继续运行 | 添加 HEALTHCHECK 指令 |
快速故障排除
| 问题 | 诊断 | 修复方法 |
|---|
| 构建缓慢 | 构建上下文过大 | 添加 .dockerignore，优化层缓存 |
| 镜像体积过大 | 开发依赖项，未使用多阶段构建 | 使用多阶段构建，--only=production |
| 容器内出现"权限被拒绝" | 以 root 身份运行，文件所有权错误 | 使用 USER 指令，COPY --chown |
| 构建缓存不工作 | 在依赖安装前执行了 COPY | 先复制 package.json，然后安装依赖，最后复制代码 |
| 容器立即崩溃 | 错误的 CMD/ENTRYPOINT，缺少依赖 | 检查日志：docker logs <container> |
| 无法连接到数据库 | 网络错误，主机地址错误 | 使用服务名作为主机，检查网络 |
| "Exec format error" | 平台不匹配（ARM vs x86） | 为正确的平台构建：--platform linux/amd64 |
| 端口无法访问 | 未暴露或未发布端口 | 使用 EXPOSE + docker run -p |
| 文件未更新 | 缓存层 | 清除缓存：docker build --no-cache |
| 删除后卷数据仍然存在 | 命名卷未被移除 | 使用 docker volume rm 或 docker-compose down -v |
生产就绪
安全配置
# Security-hardened Dockerfile
FROM node:20-alpine AS builder
# Create non-root user
RUN addgroup -g 1001 appgroup && \
adduser -u 1001 -G appgroup -s /bin/sh -D appuser
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
# Production image
FROM node:20-alpine
# Security: install security updates
RUN apk update && apk upgrade && rm -rf /var/cache/apk/*
# Create non-root user
RUN addgroup -g 1001 appgroup && \
adduser -u 1001 -G appgroup -s /bin/sh -D appuser
WORKDIR /app
# Copy with correct ownership
COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
COPY --from=builder --chown=appuser:appgroup /app/package.json ./
# Drop privileges
USER appuser
# Security: read-only filesystem (use with docker run --read-only)
# Make /tmp writable if needed
VOLUME ["/tmp"]
# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
EXPOSE 3000
CMD ["node", "dist/index.js"]
镜像扫描
# Scan for vulnerabilities
docker scout cves myapp:latest
docker scout recommendations myapp:latest
# Alternative: Trivy scanner
trivy image myapp:latest
# Scan during CI/CD
docker build -t myapp:latest .
trivy image --exit-code 1 --severity HIGH,CRITICAL myapp:latest
资源限制
# docker-compose.yml with limits
services:
app:
image: myapp:latest
deploy:
resources:
limits:
cpus: '1.0'
memory: 512M
reservations:
cpus: '0.25'
memory: 256M
# Security options
security_opt:
- no-new-privileges:true
read_only: true
tmpfs:
- /tmp
cap_drop:
- ALL
cap_add:
- NET_BIND_SERVICE
# Run with limits
docker run -d \
--memory=512m \
--memory-swap=512m \
--cpus=1.0 \
--read-only \
--tmpfs /tmp \
--security-opt=no-new-privileges:true \
--cap-drop=ALL \
myapp:latest
密钥管理
# docker-compose.yml with secrets
services:
app:
image: myapp:latest
secrets:
- db_password
- api_key
environment:
- DB_PASSWORD_FILE=/run/secrets/db_password
secrets:
db_password:
external: true # Or use file: ./secrets/db_password.txt
api_key:
external: true
// Read secrets in application
import { readFileSync } from 'fs';
const dbPassword = process.env.DB_PASSWORD_FILE
? readFileSync(process.env.DB_PASSWORD_FILE, 'utf8').trim()
: process.env.DB_PASSWORD;
健康检查
# Dockerfile health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD curl -f http://localhost:3000/health || exit 1
# docker-compose.yml health check
services:
app:
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
interval: 30s
timeout: 3s
retries: 3
start_period: 10s
日志最佳实践
# docker-compose.yml logging
services:
app:
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
labels: "service,environment"
tag: "{{.Name}}/{{.ID}}"
# View logs with timestamps
docker logs --timestamps --tail 100 myapp
# Follow logs
docker logs -f myapp
# Logs from all containers
docker-compose logs -f --tail=100
网络安全
# docker-compose.yml network isolation
services:
app:
networks:
- frontend
- backend
db:
networks:
- backend # Not accessible from frontend
networks:
frontend:
driver: bridge
backend:
driver: bridge
internal: true # No external access
监控指标
| 指标 | 告警阈值 |
|---|
| 容器 CPU 使用率 | > 80% |
| 容器内存使用率 | > 80% |
| 容器重启次数 | > 3 次（5 分钟内） |
| 健康检查失败次数 | > 0 |
| 镜像漏洞（严重） | > 0 |
生产命令
# Cleanup unused resources
docker system prune -af --volumes
# Monitor resources
docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"
# Check container health
docker inspect --format='{{.State.Health.Status}}' myapp
# Update without downtime (with docker-compose)
docker-compose pull
docker-compose up -d --no-deps --build app
检查清单
- 容器内使用非 root 用户
- 多阶段构建（最终镜像最小化）
- 配置了 .dockerignore
- 特定的基础镜像标签（非 :latest）
- 安装了安全更新
- 进行了镜像漏洞扫描
- 设置了资源限制（CPU/内存）
- 根文件系统只读
- 删除了不必要的 capabilities
- 通过 Docker 密钥管理密钥（而非 ENV）
- 配置了健康检查
- 配置了日志轮转
- 网络隔离
- 镜像中不包含敏感数据
参考文档
Best Practices
| Do | Don't |
|---|
| Multi-stage builds | Run as root |
| Use .dockerignore | Copy node_modules |
| Specific base image tags | Use latest in prod |
| One process per container | Install unnecessary packages |
| Layer caching (COPY package.json first) | Hardcode secrets |
.dockerignore
node_modules
.git
.env*
dist
*.log
When NOT to Use This Skill
- Managing multi-container applications with docker-compose.yml - use
docker-compose skill
- Orchestrating containers in Kubernetes - use
kubernetes skill
- CI/CD pipeline automation - use
github-actions skill
- Only running third-party images without creating Dockerfiles
- Using container platforms that abstract Docker (e.g., Heroku, Google Cloud Run config)
Anti-Patterns
| Anti-Pattern | Problem | Solution |
|---|
Using :latest in production | Unpredictable deployments | Pin specific versions node:20.10.0-alpine |
| Running as root | Security vulnerability | Use USER node or create non-root user |
Copying node_modules/ | Slow builds, platform issues | Add to .dockerignore, run npm ci in container |
| Installing dev dependencies | Bloated images | Use npm ci --only=production |
| No multi-stage builds | Large production images | Separate build and runtime stages |
| Hardcoding secrets in ENV | Secret exposure in image layers | Use Docker secrets or mount at runtime |
| Single RUN per command | Excessive layers | Chain related commands with && |
Not using .dockerignore | Slow context transfer | Exclude unnecessary files |
| Installing unnecessary packages | Attack surface, image size | Install only required packages |
| No health checks | Unhealthy containers keep running | Add HEALTHCHECK directive |
Quick Troubleshooting
| Issue | Diagnosis | Fix |
|---|
| Build is slow | Large build context | Add .dockerignore, optimize layer caching |
| Image size too large | Dev dependencies, multiple stages | Multi-stage build, --only=production |
| "Permission denied" in container | Running as root, wrong file ownership | Use USER directive, COPY --chown |
| Build cache not working | COPY before dependency install | Copy package.json first, then install, then code |
| Container crashes immediately | Wrong CMD/ENTRYPOINT, missing deps | Check logs: docker logs <container> |
| Can't connect to database | Wrong network, wrong host | Use service name as host, check network |
| "Exec format error" | Wrong platform (ARM vs x86) | Build for correct platform: --platform linux/amd64 |
| Port not accessible | Not exposed or published | Use EXPOSE + docker run -p |
| Files not updating | Cached layers | Clear cache: docker build --no-cache |
| Volume data persists after deletion | Named volumes not removed | Use docker volume rm or docker-compose down -v |
Production Readiness
Security Configuration
# Security-hardened Dockerfile
FROM node:20-alpine AS builder
# Create non-root user
RUN addgroup -g 1001 appgroup && \
adduser -u 1001 -G appgroup -s /bin/sh -D appuser
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
# Production image
FROM node:20-alpine
# Security: install security updates
RUN apk update && apk upgrade && rm -rf /var/cache/apk/*
# Create non-root user
RUN addgroup -g 1001 appgroup && \
adduser -u 1001 -G appgroup -s /bin/sh -D appuser
WORKDIR /app
# Copy with correct ownership
COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
COPY --from=builder --chown=appuser:appgroup /app/package.json ./
# Drop privileges
USER appuser
# Security: read-only filesystem (use with docker run --read-only)
# Make /tmp writable if needed
VOLUME ["/tmp"]
# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
EXPOSE 3000
CMD ["node", "dist/index.js"]
Image Scanning
# Scan for vulnerabilities
docker scout cves myapp:latest
docker scout recommendations myapp:latest
# Alternative: Trivy scanner
trivy image myapp:latest
# Scan during CI/CD
docker build -t myapp:latest .
trivy image --exit-code 1 --severity HIGH,CRITICAL myapp:latest
Resource Limits
# docker-compose.yml with limits
services:
app:
image: myapp:latest
deploy:
resources:
limits:
cpus: '1.0'
memory: 512M
reservations:
cpus: '0.25'
memory: 256M
# Security options
security_opt:
- no-new-privileges:true
read_only: true
tmpfs:
- /tmp
cap_drop:
- ALL
cap_add:
- NET_BIND_SERVICE
# Run with limits
docker run -d \
--memory=512m \
--memory-swap=512m \
--cpus=1.0 \
--read-only \
--tmpfs /tmp \
--security-opt=no-new-privileges:true \
--cap-drop=ALL \
myapp:latest
Secrets Management
# docker-compose.yml with secrets
services:
app:
image: myapp:latest
secrets:
- db_password
- api_key
environment:
- DB_PASSWORD_FILE=/run/secrets/db_password
secrets:
db_password:
external: true # Or use file: ./secrets/db_password.txt
api_key:
external: true
// Read secrets in application
import { readFileSync } from 'fs';
const dbPassword = process.env.DB_PASSWORD_FILE
? readFileSync(process.env.DB_PASSWORD_FILE, 'utf8').trim()
: process.env.DB_PASSWORD;
Health Checks
# Dockerfile health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD curl -f http://localhost:3000/health || exit 1
# docker-compose.yml health check
services:
app:
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
interval: 30s
timeout: 3s
retries: 3
start_period: 10s
Logging Best Practices
# docker-compose.yml logging
services:
app:
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
labels: "service,environment"
tag: "{{.Name}}/{{.ID}}"
# View logs with timestamps
docker logs --timestamps --tail 100 myapp
# Follow logs
docker logs -f myapp
# Logs from all containers
docker-compose logs -f --tail=100
Network Security
# docker-compose.yml network isolation
services:
app:
networks:
- frontend
- backend
db:
networks:
- backend # Not accessible from frontend
networks:
frontend:
driver: bridge
backend:
driver: bridge
internal: true # No external access
Monitoring Metrics
| Metric | Alert Threshold |
|---|
| Container CPU usage | > 80% |
| Container memory usage | > 80% |
| Container restart count | > 3 in 5 minutes |
| Health check failures | > 0 |
| Image vulnerabilities (critical) | > 0 |
Production Commands
# Cleanup unused resources
docker system prune -af --volumes
# Monitor resources
docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"
# Check container health
docker inspect --format='{{.State.Health.Status}}' myapp
# Update without downtime (with docker-compose)
docker-compose pull
docker-compose up -d --no-deps --build app
Checklist
- Non-root user in container
- Multi-stage build (minimal final image)
- .dockerignore configured
- Specific base image tags (not :latest)
- Security updates installed
- Image vulnerability scanning
- Resource limits (CPU/memory)
- Read-only root filesystem
- Capabilities dropped
- Secrets via Docker secrets (not ENV)
- Health checks configured
- Log rotation configured
- Network isolation
- No sensitive data in image
Reference Documentation
agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试
147,400 周安装
