React / 系统课时
使用 Docker 容器化
使用 Docker 容器化
本课把前端、后端和数据库封装为三个可重复运行的容器,并使用 Docker Compose 统一构建、网络、环境变量、数据卷和健康检查。完成后,只需一条命令即可启动完整应用并验证服务之间的连接。
学习目标
- 为 React 前端和 TypeScript 后端编写多阶段 Dockerfile
- 使用 Compose 组织前端、后端与 PostgreSQL 数据库
- 通过健康检查、日志和接口请求验收容器化结果
设计容器边界
本课假设项目包含 frontend、backend 两个目录,后端监听 3000 端口并提供 GET /health,前端通过同源路径 /api 调用后端。数据库示例使用 PostgreSQL;若项目使用其他数据库,只需替换数据库服务、驱动和连接串。
前端容器只负责提供构建后的静态资源,并由 Nginx 把 /api 请求转发到后端。后端容器运行编译后的 JavaScript。数据库容器只在内部网络暴露端口,并通过数据卷保存数据。

构建前端镜像
在 frontend/Dockerfile 中使用两阶段构建。第一阶段安装依赖并执行 Vite 构建,第二阶段只保留 Nginx 和静态文件,从而减少最终镜像体积。
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 代理。浏览器只访问前端容器,不需要知道后端容器地址。
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,再在运行阶段只安装生产依赖。这样不会把编译器、测试工具和源码全部带入最终镜像。
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。下面配置会创建三个服务、一个内部网络和一个数据库数据卷,并通过健康检查控制后端启动时机。
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 让服务在后台运行。
docker compose up --build -d预期结果
三个服务完成创建并启动。
postgres 先通过健康检查,随后 backend 启动,最后 frontend 启动。
镜像层名称、容器名称和构建耗时可能不同。使用 Compose 查看状态。
docker compose ps预期输出
NAME SERVICE STATUS
<PROJECT>-postgres-1 postgres Up ... (healthy)
<PROJECT>-backend-1 backend Up ... (healthy)
<PROJECT>-frontend-1 frontend Up ...<PROJECT> 由当前目录名或 Compose 项目名决定,实际值可能不同。若服务持续处于 starting 或反复重启,应立即查看对应日志。
验证页面、接口与数据库连接
先通过前端容器访问后端健康接口,确认浏览器入口、Nginx 代理和后端服务三段链路都正常。
curl -i http://127.0.0.1:8080/api/health预期输出
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"status":"ok"}再查看后端最近日志,确认没有数据库认证、迁移或连接错误。
docker compose logs --tail=50 backend预期结果
日志中可看到服务已启动,且没有持续出现数据库连接失败或进程崩溃信息。
具体日志文本取决于项目实现。打开 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 后重新创建,但该命令会删除数据库数据,生产环境禁止直接使用。停止服务但保留数据时执行下面命令。
docker compose down预期输出
frontend、backend 和 postgres 容器被停止并移除。
postgres-data 命名卷被保留。