Ubuntu 下 Node.js 应用 Docker 容器化全攻略：从环境配置到生产部署

将 Node.js 应用封装进 Docker 容器，是实现现代化部署和提升应用可移植性的关键步骤。本文将以 Ubuntu 系统为例，系统性地讲解从环境搭建、镜像构建、开发调试到生产优化的完整流程，帮助你高效、安全地实现应用容器化。

一、 环境准备：安装 Node.js 与 Docker 引擎

在开始容器化之前，需要在 Ubuntu 系统上配置好必要的运行环境，包括 Node.js 运行时和 Docker 容器平台。

• 安装 Node.js（三种常用方法）
  • 通过 Ubuntu 官方仓库安装：这是最快捷的方式，执行命令 sudo apt update && sudo apt install -y nodejs npm 即可完成安装。
  • 通过 NodeSource 仓库安装：如需安装特定或更新的 LTS 版本，推荐使用此方法。需先添加 NodeSource 的 GPG 密钥和软件源，再进行安装。
  • 使用 NVM（Node 版本管理器）安装：适用于需要在多个 Node.js 版本间切换的开发场景。安装 NVM 后，可通过 nvm install 18 && nvm use 18 等命令轻松管理版本。
• 安装 Docker 引擎（三种推荐方案）
  • 使用官方便捷脚本：执行 curl -fsSL https://get.docker.com | sudo sh，脚本会自动完成最新版 Docker 的安装与配置。
  • 通过 APT 安装 docker.io：使用 Ubuntu 仓库中的稳定版本，命令为 sudo apt update && sudo apt install -y docker.io。
  • 通过 APT 安装 docker-ce：从 Docker 官方仓库安装社区版。需先添加 Docker 的 GPG 密钥和 apt 源，安装后启动服务：sudo systemctl start docker && sudo systemctl enable docker。
• 验证环境安装
  • 运行 node -v 和 npm -v 检查 Node.js 与 npm 版本，确认安装成功。
  • 执行 docker run hello-world 命令，如果成功拉取并运行测试容器，并显示欢迎信息，则证明 Docker 环境已准备就绪。

二、 实战演练：构建并运行首个 Docker 化 Node.js 应用

我们通过一个简单的 Express.js 应用示例，快速掌握 Docker 镜像构建与容器运行的核心步骤。

• 创建示例 Node.js 应用
  • 新建项目目录并初始化：mkdir my-node-app && cd my-node-app && npm init -y。
  • 安装 Express 框架：npm install express。
  • 创建主程序文件 app.js，写入以下代码：

    const express = require('express');
    const app = express();
    app.get('/', (_, res) => res.send('Hello, Docker'));
    app.listen(3000, () => console.log('Server on 3000'));

• 编写生产级 Dockerfile
  • 在项目根目录创建名为 Dockerfile 的文件，内容如下：

    FROM node:18-alpine
    WORKDIR /usr/src/app
    COPY package*.json ./
    RUN npm ci --only=production
    COPY . .
    EXPOSE 3000
    USER node
    CMD ["node", "app.js"]

  • Dockerfile 优化解析：选用轻量级的 node:18-alpine 作为基础镜像；使用 npm ci 命令确保依赖安装的确定性与速度；通过 USER node 指令切换至非 root 用户运行，增强容器安全性；EXPOSE 3000 声明应用端口；CMD 指令定义容器启动命令。
• 构建镜像并启动容器
  • 构建 Docker 镜像：docker build -t my-node-app .
  • 以后台模式运行容器：docker run -d --name my-running-app -p 3000:3000 my-node-app
  • 在浏览器中访问 https://localhost:3000 或服务器的 https://<服务器IP>:3000，即可看到应用返回的 “Hello, Docker” 信息。

三、 开发环境优化：利用 Docker Compose 与热重载提升效率

在开发阶段，我们需要实现代码实时同步和快速重启。结合 Docker Compose 和 nodemon 工具可以极大提升开发体验。

• 使用 Docker Compose 编排多容器服务

  当应用依赖数据库（如 MongoDB）时，使用 docker-compose.yml 文件可以统一管理。创建文件内容如下：

  version: "3.8"
  services:
    app:
      build: .
      ports:
        - "3000:3000"
      environment:
        - NODE_ENV=development
        - MONGO_URI=mongodb://mongo:27017/mydb
      volumes:
        - .:/usr/src/app
        - /usr/src/app/node_modules
      depends_on:
        - mongo
    mongo:
      image: mongo:6
      environment:
        MONGO_INITDB_ROOT_USERNAME: root
        MONGO_INITDB_ROOT_PASSWORD: example
      volumes:
        - mongo-data:/data/db
  volumes:
    mongo-data:

  运行 docker-compose up -d 一键启动所有服务。关键技巧：通过 volumes 将本地代码目录挂载到容器，实现实时修改生效；单独挂载 node_modules 卷，避免本地目录覆盖容器内的依赖包。

• 集成 nodemon 实现自动重启
  • 安装 nodemon 为开发依赖：npm i -D nodemon。
  • 在 package.json 的 scripts 中添加："dev": "nodemon app.js"。
  • 在 docker-compose.yml 的 app 服务中，覆盖启动命令以使用开发脚本：

    command: ["npm", "run", "dev"]

• 环境变量配置管理

  将数据库连接字符串、API密钥等敏感或可变配置写入 .env 文件，在应用中使用 process.env 读取。这种方式安全且便于在不同部署环境（开发、测试、生产）间切换配置。

四、 生产部署优化与故障排查指南

面向生产环境时，需重点关注镜像体积、运行安全和应用稳定性。

• 采用多阶段构建缩小镜像

  多阶段构建是生产环境的最佳实践，它将构建环境和运行环境分离，最终生成一个仅包含运行所需文件的最小镜像。

  FROM node:18-alpine AS builder
  WORKDIR /usr/src/app
  COPY package*.json ./
  RUN npm ci
  COPY . .
  RUN npm run build
  
  FROM node:18-alpine
  WORKDIR /usr/src/app
  COPY --from=builder /usr/src/app/dist ./dist
  COPY package*.json ./
  RUN npm ci --only=production
  USER node
  CMD ["node", "dist/index.js"]

• 配置 .dockerignore 文件

  在项目根目录创建 .dockerignore 文件，忽略 node_modules、.git、.env、日志等非必要文件。这能加速镜像构建过程并减少构建上下文大小。

• 强化容器安全策略

  始终使用 USER node 指令以非特权用户运行容器进程。在 Docker Compose 中挂载卷时，需注意策略以防止本地空目录覆盖容器内关键的 node_modules 目录。

• 为服务添加健康检查

  在 docker-compose.yml 或 Dockerfile 中配置健康检查指令，使容器编排工具能够监控应用状态，实现自动恢复。

  healthcheck:
    test: ["CMD", "curl", "-f", "https://localhost:3000/health"]
    interval: 30s
    timeout: 5s
    retries: 3

• 常见问题与解决方案
  • 应用端口无法访问：检查宿主机防火墙或云服务商的安全组规则，确保已放行应用端口（例如3000）。本地测试请确认使用正确的地址 https://localhost:3000。
  • 容器内依赖被本地目录覆盖：在 Docker Compose 的 volumes 配置中，为 /usr/src/app/node_modules 使用匿名卷或命名卷进行隔离保护。
  • 依赖版本不一致问题：坚持使用 npm ci 命令安装依赖，并确保将 package-lock.json 文件纳入版本控制，以锁定确切的依赖版本，保证环境一致性。