React / 系统课时

使用 Docker 容器化

使用 Docker 容器化

本课把前端、后端和数据库封装为三个可重复运行的容器,并使用 Docker Compose 统一构建、网络、环境变量、数据卷和健康检查。完成后,只需一条命令即可启动完整应用并验证服务之间的连接。

学习目标

  • 为 React 前端和 TypeScript 后端编写多阶段 Dockerfile
  • 使用 Compose 组织前端、后端与 PostgreSQL 数据库
  • 通过健康检查、日志和接口请求验收容器化结果

设计容器边界

本课假设项目包含 frontend、backend 两个目录,后端监听 3000 端口并提供 GET /health,前端通过同源路径 /api 调用后端。数据库示例使用 PostgreSQL;若项目使用其他数据库,只需替换数据库服务、驱动和连接串。

前端容器只负责提供构建后的静态资源,并由 Nginx 把 /api 请求转发到后端。后端容器运行编译后的 JavaScript。数据库容器只在内部网络暴露端口,并通过数据卷保存数据。

Compose 多服务容器架构

构建前端镜像

在 frontend/Dockerfile 中使用两阶段构建。第一阶段安装依赖并执行 Vite 构建,第二阶段只保留 Nginx 和静态文件,从而减少最终镜像体积。

dockerfile
FROM node:20-alpine AS build
WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY . .
RUN npm run build

FROM nginx:1.27-alpine
COPY nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=build /app/dist /usr/share/nginx/html

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

在 frontend/nginx.conf 中配置单页应用回退和 API 代理。浏览器只访问前端容器,不需要知道后端容器地址。

nginx
server {
    listen 80;
    server_name _;

    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://backend:3000/;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

该配置会把 /api/users 转发为后端的 /users。若后端路由本身包含 /api 前缀,应把 proxy_pass 改为 http://backend:3000,保留原始路径。

构建后端镜像

在 backend/Dockerfile 中先编译 TypeScript,再在运行阶段只安装生产依赖。这样不会把编译器、测试工具和源码全部带入最终镜像。

dockerfile
FROM node:20-alpine AS build
WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY tsconfig.json ./
COPY src ./src
RUN npm run build

FROM node:20-alpine AS runtime
WORKDIR /app
ENV NODE_ENV=production

COPY package.json package-lock.json ./
RUN npm ci --omit=dev

COPY --from=build /app/dist ./dist

EXPOSE 3000
CMD ["node", "dist/server.js"]

若后端运行时依赖 Prisma Schema、模板、证书或上传目录,应使用额外的 COPY 明确加入。镜像构建成功并不代表这些文件会自动存在。

使用 Compose 组织服务

在项目根目录创建 compose.yaml。下面配置会创建三个服务、一个内部网络和一个数据库数据卷,并通过健康检查控制后端启动时机。

yaml
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: app
      POSTGRES_PASSWORD: change-me
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 5s
      timeout: 3s
      retries: 10
    restart: unless-stopped

  backend:
    build:
      context: ./backend
    environment:
      NODE_ENV: production
      PORT: "3000"
      DATABASE_URL: postgresql://app:change-me@postgres:5432/app
    depends_on:
      postgres:
        condition: service_healthy
    healthcheck:
      test:
        [
          "CMD",
          "node",
          "-e",
          "fetch('http://127.0.0.1:3000/health').then(r=>{if(!r.ok)process.exit(1)}).catch(()=>process.exit(1))"
        ]
      interval: 10s
      timeout: 3s
      retries: 5
    restart: unless-stopped

  frontend:
    build:
      context: ./frontend
    ports:
      - "8080:80"
    depends_on:
      backend:
        condition: service_healthy
    restart: unless-stopped

volumes:
  postgres-data:

示例中的密码只用于本地教学。生产环境应通过 .env、Compose secrets 或部署平台注入,并避免把真实密码提交到版本库。数据库没有声明 ports,因此不会直接暴露给宿主机和外部网络。

构建并启动容器

在项目根目录执行下面命令。--build 会在启动前重新构建前端和后端镜像,-d 让服务在后台运行。

bash
docker compose up --build -d

预期结果

text
三个服务完成创建并启动。
postgres 先通过健康检查,随后 backend 启动,最后 frontend 启动。
镜像层名称、容器名称和构建耗时可能不同。

使用 Compose 查看状态。

bash
docker compose ps

预期输出

text
NAME                 SERVICE    STATUS
<PROJECT>-postgres-1 postgres   Up ... (healthy)
<PROJECT>-backend-1  backend    Up ... (healthy)
<PROJECT>-frontend-1 frontend   Up ...

<PROJECT> 由当前目录名或 Compose 项目名决定,实际值可能不同。若服务持续处于 starting 或反复重启,应立即查看对应日志。

验证页面、接口与数据库连接

先通过前端容器访问后端健康接口,确认浏览器入口、Nginx 代理和后端服务三段链路都正常。

bash
curl -i http://127.0.0.1:8080/api/health

预期输出

text
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"status":"ok"}

再查看后端最近日志,确认没有数据库认证、迁移或连接错误。

bash
docker compose logs --tail=50 backend

预期结果

text
日志中可看到服务已启动,且没有持续出现数据库连接失败或进程崩溃信息。
具体日志文本取决于项目实现。

打开 http://127.0.0.1:8080 后,前端页面应能刷新任意客户端路由而不返回 404。若页面能打开但 API 返回 502,通常表示 Nginx 已运行,但后端容器未健康、端口不一致或代理路径配置错误。

排查典型容器问题

镜像构建失败时,先确认 package-lock.json 与 package.json 一致,并检查 .dockerignore 是否误排除了 src、tsconfig.json 或构建所需文件。不要通过删除锁文件掩盖依赖问题。

后端无法连接数据库时,连接地址必须使用 Compose 服务名 postgres,不能写 localhost。容器内的 localhost 只指向当前容器自身,并不代表数据库容器。

修改数据库密码后,旧数据卷仍保留初始化时的账号信息。教学环境可以执行 docker compose down -v 后重新创建,但该命令会删除数据库数据,生产环境禁止直接使用。停止服务但保留数据时执行下面命令。

bash
docker compose down

预期输出

text
frontend、backend 和 postgres 容器被停止并移除。
postgres-data 命名卷被保留。
按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 Docker 容器化

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通