Docker on 超越网

Docker Compose 多环境管理：从开发到生产的优雅方案

Thu, 28 May 2026 10:20:00 +0800

前言

2025年，我经历过三次因为环境不一致导致的线上故障。每次排查都花费数小时，最终发现是开发环境和生产环境的配置差异造成的。

从那时起，我开始系统性地重构多环境管理方案。这篇文章记录完整的实践过程，包括目录结构、配置管理和部署流程。

一、问题根源

1.1 常见痛点

问题	现象	影响
配置硬编码	环境变量写死在 docker-compose.yml	切换环境需修改文件
镜像版本混乱	开发用 latest，生产用具体版本	行为不一致
依赖管理缺失	数据库迁移脚本未版本化	数据不一致
密钥管理不当	敏感信息明文存储	安全风险

1.2 根本原因

环境隔离不彻底：开发、测试、生产共用同一份配置模板，仅靠注释区分。

二、目录结构设计

2.1 推荐结构

project/
├── docker-compose.yml          # 基础配置（公共部分）
├── docker-compose.override.yml # 本地开发覆盖
├── environments/
│   ├── dev/
│   │   ├── docker-compose.dev.yml
│   │   └── .env.dev
│   ├── staging/
│   │   ├── docker-compose.staging.yml
│   │   └── .env.staging
│   └── prod/
│       ├── docker-compose.prod.yml
│       └── .env.prod
├── scripts/
│   ├── deploy.sh
│   └── rollback.sh
└── .gitignore

2.2 基础配置（docker-compose.yml）

version: "3.8"

services:
  app:
    image: ${APP_IMAGE:-myapp:latest}
    restart: unless-stopped
    environment:
      - NODE_ENV=${NODE_ENV:-development}
      - LOG_LEVEL=${LOG_LEVEL:-info}
    depends_on:
      - db
      - redis

  db:
    image: postgres:${POSTGRES_VERSION:-16}
    volumes:
      - db_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=${POSTGRES_DB:-app}
      - POSTGRES_USER=${POSTGRES_USER:-app}
      - POSTGRES_PASSWORD_FILE=/run/secrets/db_password

  redis:
    image: redis:${REDIS_VERSION:-7-alpine}
    command: redis-server --maxmemory 256mb

volumes:
  db_data:

2.3 生产环境覆盖（environments/prod/docker-compose.prod.yml）

version: "3.8"

services:
  app:
    image: myapp:${APP_VERSION:-1.0.0}
    deploy:
      resources:
        limits:
          cpus: "2"
          memory: 2G
        reservations:
          memory: 512M
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    secrets:
      - db_password
    networks:
      - frontend
      - backend

  db:
    deploy:
      resources:
        limits:
          memory: 4G
    volumes:
      - db_data:/var/lib/postgresql/data
      - ./backups:/backups

secrets:
  db_password:
    external: true

networks:
  frontend:
    driver: bridge
  backend:
    internal: true

三、环境变量管理

3.1 .env 文件规范

# .env.prod
# 应用配置
APP_VERSION=1.0.0
NODE_ENV=production
LOG_LEVEL=warn

# 数据库
POSTGRES_VERSION=16
POSTGRES_DB=app_prod
POSTGRES_USER=app

# Redis
REDIS_VERSION=7-alpine

# 镜像仓库
REGISTRY_URL=registry.example.com

3.2 密钥管理

不要将密钥存入 .env 文件！

# 使用 Docker secrets
echo "your-secure-password" | docker secret create db_password -

# 或在 Kubernetes 中使用 Secret
kubectl create secret generic db-credentials --from-literal=password=your-secure-password

四、部署脚本

4.1 部署脚本（scripts/deploy.sh）

#!/bin/bash
set -euo pipefail

ENV=${1:-dev}
PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"

echo "🚀 部署到环境: ${ENV}"

# 1. 加载环境变量
set -a
source "${PROJECT_DIR}/environments/${ENV}/.env.${ENV}"
set +a

# 2. 拉取最新镜像
docker compose -f docker-compose.yml \
               -f environments/${ENV}/docker-compose.${ENV}.yml \
               pull

# 3. 执行数据库迁移
docker compose -f docker-compose.yml \
               -f environments/${ENV}/docker-compose.${ENV}.yml \
               run --rm app npm run migrate

# 4. 启动服务
docker compose -f docker-compose.yml \
               -f environments/${ENV}/docker-compose.${ENV}.yml \
               up -d --remove-orphans

# 5. 健康检查
sleep 10
docker compose -f docker-compose.yml \
               -f environments/${ENV}/docker-compose.${ENV}.yml \
               ps

echo "✅ 部署完成"

4.2 回滚脚本（scripts/rollback.sh）

#!/bin/bash
set -euo pipefail

ENV=${1:-dev}
PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"

echo "⏪ 回滚环境: ${ENV}"

# 获取上一个版本
PREV_VERSION=$(docker images --format "{{.Tag}}" myapp | head -2 | tail -1)

# 更新环境变量
sed -i "s/APP_VERSION=.*/APP_VERSION=${PREV_VERSION}/" \
    "${PROJECT_DIR}/environments/${ENV}/.env.${ENV}"

# 重新部署
"${PROJECT_DIR}/scripts/deploy.sh" "${ENV}"

echo "✅ 回滚完成至版本: ${PREV_VERSION}"

五、CI/CD 集成

5.1 GitHub Actions 示例

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to Staging
        run: ./scripts/deploy.sh staging
        env:
          DOCKER_REGISTRY_TOKEN: ${{ secrets.DOCKER_TOKEN }}

  deploy-prod:
    needs: deploy-staging
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to Production
        run: ./scripts/deploy.sh prod
        env:
          DOCKER_REGISTRY_TOKEN: ${{ secrets.DOCKER_TOKEN }}

六、最佳实践总结

实践	说明
✅ 基础配置与覆盖分离	docker-compose.yml 放公共配置，环境文件放差异
✅ 使用 .env 文件	不要硬编码环境变量
✅ 密钥使用 secrets	不要将密钥存入版本控制
✅ 固定镜像版本	避免 latest 标签导致的不一致
✅ 健康检查	确保服务真正可用后再认为部署成功
✅ 回滚方案	每次部署前确认可以快速回滚
❌ 不要手动修改线上配置	所有变更通过代码审查
❌ 不要共享 .env 文件	每个环境独立文件

七、总结

多环境管理的核心原则：

配置即代码：所有环境配置版本化
最小差异：基础配置最大化，环境差异最小化
自动化部署：减少人为操作，提高一致性
可回滚：每次部署都有明确的回滚路径

如果你也在为环境不一致头疼，我的建议是：尽早建立规范，不要等到问题频发时才重构。

更新日志：本文基于2026年5月实践编写，具体命令和配置可能因项目而异，请以实际需求为准。

SSH密钥持久化：为什么容器内生成的密钥在重启后丢失

Wed, 27 May 2026 13:00:00 +0800

前言

2026年5月，我遇到一个反复出现的问题：容器内生成的SSH密钥在容器重启后丢失，导致无法通过SSH连接到宿主机。

这个问题看似简单，但背后涉及Docker容器的文件系统隔离机制。这篇文章记录完整的排查过程和最终解决方案。

一、问题现象

现象：SSH密钥在容器内生成，容器重启后密钥消失，无法连接宿主机
时间：2026-05-18
环境：fnOS虚拟化平台 + Ubuntu 24.04 VM + Docker

初始错误：

Warning: Permanently added '192.168.0.200' (ED25519) to the list of known hosts.
Permission denied (publickey).

二、根因分析

2.1 Docker容器的文件系统隔离

Docker容器使用联合文件系统（UnionFS），容器内的文件系统是独立的。当容器重启时：

容器内生成的文件 → 存储在容器的可写层
容器重启 → 可写层被销毁，所有未持久化的文件丢失
SSH密钥丢失 → 无法通过密钥认证连接宿主机

2.2 为什么宿主机SSH拒绝使用容器内密钥

即使密钥被挂载到容器，宿主机SSH服务也会拒绝使用：

# /var/log/auth.log
sshd[12345]: Authentication refused: bad ownership or modes for key file

原因：SSH要求私钥文件所有者必须是 root:root，且权限为 600。容器内生成的密钥，挂载后文件所有者可能不匹配。

三、解决方案

3.1 核心原则

密钥必须在宿主机生成，不能容器内生成。

3.2 完整步骤

步骤1：在宿主机生成SSH密钥

# 宿主机执行（192.168.0.200）
ssh-keygen -t ed25519 -C "hermes-agent" -f /home/ksboy/.ssh/hermes_key
# 设置权限
chmod 600 /home/ksboy/.ssh/hermes_key
chmod 644 /home/ksboy/.ssh/hermes_key.pub

步骤2：将公钥添加到宿主机授权文件

# 宿主机执行
cat /home/ksboy/.ssh/hermes_key.pub >> /home/ksboy/.ssh/authorized_keys
chmod 600 /home/ksboy/.ssh/authorized_keys

步骤3：在docker-compose.yml中挂载密钥

services:
 hermes-agent:
 image: hermes-agent:latest
 volumes:
 # 密钥挂载（只读模式）
 - /home/ksboy/.ssh/hermes_key:/root/.ssh/id_ed25519:ro
 - /home/ksboy/.ssh/hermes_key.pub:/root/.ssh/id_ed25519.pub:ro
 # SSH配置
 - /home/ksboy/.ssh/config:/root/.ssh/config:ro
 environment:
 - SSH_HOST=192.168.0.200
 - SSH_USER=ksboy

步骤4：宿主机SSH配置调整

# /etc/ssh/sshd_config
# 允许Docker网段访问
ListenAddress 0.0.0.0

# 重启SSH服务
systemctl restart sshd

3.3 验证

# 容器内测试
ssh -i /root/.ssh/id_ed25519 ksboy@192.168.0.200 "echo '连接成功'"

# 重启容器后再次测试
docker-compose restart hermes-agent
ssh -i /root/.ssh/id_ed25519 ksboy@192.168.0.200 "echo '重启后连接成功'"

四、关键要点

要点	说明
密钥生成位置	必须在宿主机，容器内生成的密钥重启后丢失
文件所有者	宿主机密钥必须为 `root:root`（容器以root运行）
挂载模式	使用 `:ro` 只读模式，防止容器内意外修改
SSH监听地址	宿主机需监听 `0.0.0.0`，允许Docker网段访问
网络隔离	容器在Docker网段，宿主机在LAN网段，需正确配置路由

五、常见错误

错误1：容器内生成密钥

# ❌ 错误做法
docker exec -it hermes-agent ssh-keygen -t ed25519 -f /root/.ssh/id_ed25519
# 容器重启后密钥丢失

错误2：密钥权限不正确

# ❌ 错误做法
chmod 644 /home/ksboy/.ssh/hermes_key # SSH拒绝使用
# ✅ 正确做法
chmod 600 /home/ksboy/.ssh/hermes_key

错误3：宿主机SSH只监听localhost

# ❌ 错误做法
ListenAddress 127.0.0.1 # Docker容器无法连接
# ✅ 正确做法
ListenAddress 0.0.0.0

六、总结

SSH密钥持久化的核心是理解Docker的文件系统隔离机制：