Docker Compose 实战：一键编排博客前端、后端与 Nginx

动手前先知道

这篇文章对应的真实任务是：讲清 Compose 文件如何组织服务、环境变量、网络、数据卷、健康检查和上线验收。

第一次阅读先弄清“为什么需要这一步、它改变了哪个运行对象、失败时去哪里检查”，再执行命令。命令可以查，运行模型和排障路径才是长期能力。

Docker Compose 是个人项目部署最实用的工具之一。它不复杂，但能把“前端、后端、Nginx、数据库、环境变量、网络、数据卷”组织成一套可重复运行的系统。

它从哪里来

Docker Compose 的前身之一是 Fig。Docker 在 2014 年收购相关团队后将它发展为 Compose，让多容器应用可以用一份 YAML 描述。它解决的不是“少敲几条命令”，而是把服务依赖、网络、数据卷与启动参数变成可重复的项目配置。

Compose 文件应该描述什么

一个完整的 Compose 文件至少应该描述：

服务名。
镜像或构建路径。
环境变量。
端口。
网络。
数据卷。
重启策略。
健康检查。

小艾知行录的核心服务可以这样理解：

nginx：唯一公网入口
web：Next.js 页面服务
api：Go API 服务
mysql：数据库

一个简化版结构

services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - web
      - api

  web:
    image: xiaoai-blog-web:2026-09-03
    environment:
      - API_BASE_URL=http://api:8080

  api:
    image: xiaoai-blog-api:2026-09-03
    env_file:
      - .env.production

  mysql:
    image: mysql:8
    volumes:
      - mysql_data:/var/lib/mysql

volumes:
  mysql_data:

这不是最终生产文件，但能说明服务关系。

depends_on 不是健康保证

depends_on 只能保证启动顺序，不保证数据库已经可用。

也就是说，api 在 mysql 后启动，不代表 MySQL 已经完成初始化。

更稳的做法是：

后端连接数据库时做重试。
MySQL 配置 healthcheck。
上线脚本里做健康检查。

环境变量放哪里

建议：

.env.production.example 进仓库
.env.production 不进仓库

example 文件告诉自己和未来维护者需要哪些配置；真实文件只放服务器。

配置可以包括：

数据库地址。
数据库账号。
JWT 密钥。
COS 配置。
AI 模型 Key。
前端访问地址。
CORS 允许域名。

Compose 常用命令

启动：

docker compose up -d

查看状态：

docker compose ps

查看日志：

docker compose logs -f api
docker compose logs -f web
docker compose logs -f nginx

重启某个服务：

docker compose restart api

停止整套服务：

docker compose down

如果生产数据库在 Compose 里，执行 down -v 要极其谨慎，因为它会删除 volume。

Compose 的上线验收

Compose 启动后，不要只看容器是 running。

还要检查：

curl -I http://127.0.0.1
curl http://127.0.0.1/api/v1/health
docker compose logs --tail=100 api
docker compose logs --tail=100 nginx

真正上线前，要确保：

页面返回 200。
API 健康检查正常。
后端能连接数据库。
静态资源加载正常。
管理端登录正常。
图片上传正常。
搜索正常。

这些都通过，才算 Compose 部署完成。