Docker Compose 部署记录

这篇日志记录的是一个服务从“能跑”到“可交付”的过程。对于很多内部工具、Demo 服务或 HomeLab 项目来说，Docker Compose 仍然是一个非常实用的中间层：比手工启动稳定，比上 Kubernetes 简单。

背景

最开始，这个服务通常只是在本地用 npm run dev、python app.py 或 java -jar 跑起来。随着使用场景变多，问题会逐渐暴露出来：

• 重启后配置容易丢
• 不同机器上的环境不一致
• 日志分散在控制台，不好收集
• 依赖服务需要手动启动
• 发布时需要重复执行同样的步骤

因此这次的目标是把运行方式整理成 Compose 文件，让部署过程尽量保持一致。

镜像准备

先做最基本的镜像构建检查。对大多数服务来说，构建层最好尽量稳定，避免不必要的缓存失效。

docker build -t demo-app:1.0.0 .
docker images | grep demo-app

如果镜像比较大，可以进一步确认以下点：

• 是否使用了合适的基础镜像
• 是否把无关文件一起打进镜像
• 是否利用了多阶段构建
• 是否把运行时和构建时依赖分开

一个常见经验是，先让镜像“能重复构建”，再追求“尽量小”。如果构建本身不稳定，后续部署就会一直被放大。

Compose 文件

一个比较稳妥的 Compose 文件通常不需要太花哨，核心就是服务、端口、挂载和重启策略：

services:
  app:
    image: demo-app:1.0.0
    container_name: demo-app
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      APP_ENV: production
    volumes:
      - ./data:/data

如果服务依赖数据库、缓存或消息队列，也建议写在同一个 Compose 文件里，至少在测试环境中保持可一键拉起。

部署过程

实际部署时我通常按以下节奏推进：

1. 先检查端口是否空闲
2. 再确认镜像是否存在
3. 然后执行 docker compose up -d
4. 紧接着看 docker compose ps
5. 最后检查服务日志和健康状态

docker compose up -d
docker compose ps
docker compose logs -f app

如果服务启动失败，优先看两类问题：

• 配置文件路径是否正确
• 环境变量是否缺失

很多部署失败并不是应用逻辑问题，而是容器内外的路径、权限、编码或者端口映射出了偏差。

验证方式

部署完成后，验证最好别只停留在“容器起来了”这一步。至少应该做三层检查：

• 进程层：容器是否持续运行
• 网络层：端口是否对外可达
• 业务层：接口是否返回预期结果

例如：

curl -I http://127.0.0.1:8080
docker compose exec app sh

如果有健康检查接口，最好把它作为部署后的唯一入口判断。这样后续无论是监控还是自动化回滚，都会更容易接上。

复盘

Compose 的价值在于把“部署动作”收敛成一个文件。它不一定最强，但通常足够稳定，也足够轻量。对于单机部署、演示环境、内部服务和过渡阶段项目，它依然非常合适。

这次整理之后，部署记录至少留下了三样东西：

• 一个可重复执行的启动方式
• 一个可直观看到状态的命令集合
• 一个后续可以迁移到 Kubernetes 的基础模板