upshow/pm2

node20-alpine-pm2 Docker镜像文档

1. 镜像概述与主要用途

1.1 概述

本镜像基于 Node.js 20 官方Alpine版本构建，集成 PM2进程管理器，旨在提供轻量级、高性能的Node.js应用运行环境。Alpine Linux的轻量级特性与PM2的进程管理能力结合，适用于需要高效资源利用和可靠进程守护的场景。

1.2 主要用途

• 作为Node.js 20应用的基础运行环境，支持开发与生产场景
• 通过PM2实现Node.js进程的生命周期管理（启动、停止、重启、监控）
• 适用于微服务、API服务、后端应用等Node.js生态场景

2. 核心功能与特性

2.1 基础环境特性

• 轻量级基础：基于Alpine Linux，镜像体积小（约120-150MB），资源占用低
• Node.js 20：集成Node.js 20.x LTS版本，支持ECMAScript模块（ESM）、性能优化（如V8引擎改进）、Web Streams API等特性
• PM2集成：预装PM2最新稳定版，支持进程管理、日志聚合、负载均衡、自动重启等核心功能

2.2 PM2核心功能

• 进程管理：支持多实例启动、集群模式（cluster mode）、负载均衡
• 可靠性保障：应用崩溃自动重启、异常退出恢复、CPU/memory阈值监控
• 日志处理：实时日志聚合、日志轮转（log rotation）、日志导出
• 部署支持：配置文件驱动（ecosystem.config.js）、环境变量注入、热重载

3. 使用场景与适用范围

3.1 适用场景

• 生产环境Node.js服务：微服务、API接口、后端应用（需进程守护与资源监控）
• 开发/测试环境：快速搭建Node.js 20开发环境，支持热重载与配置调试
• 资源受限环境：边缘设备、轻量级服务器（依赖Alpine的低内存/磁盘占用）
• 长时间运行服务：需自动重启、日志持久化的应用（如数据处理服务、消息队列消费者）

3.2 不适用场景

• 依赖Alpine不兼容库的Node.js应用（如部分原生Addon需glibc支持）
• 无进程管理需求的简单脚本（可直接使用官方Node.js Alpine镜像）

4. 使用方法与配置说明

4.1 前置要求

• Docker Engine 20.10+
• 应用代码需包含PM2配置文件（如ecosystem.config.js）或入口脚本（如app.js）

4.2 镜像拉取

bash
docker pull <镜像仓库地址>/node20-alpine-pm2:latest  # 替换为实际镜像仓库地址

4.3 基础运行方式

4.3.1 直接运行（单文件应用）

若应用仅有单个入口文件（如app.js），可通过pm2 start直接启动：

bash
docker run -d \
  --name node-app \
  -p 3000:3000 \  # 映射应用端口（根据实际应用调整）
  -v $(pwd)/app.js:/app/app.js \  # 挂载应用代码
  <镜像仓库地址>/node20-alpine-pm2 \
  pm2 start /app/app.js --no-daemon  # --no-daemon确保PM2前台运行（便于容器管理）

4.3.2 通过PM2配置文件运行

推荐使用PM2配置文件（如ecosystem.config.js）定义应用参数，示例配置文件：

javascript
// ecosystem.config.js
module.exports = {
  apps: [{
    name: "my-app",  # 应用名称
    script: "./app.js",  # 入口脚本路径（容器内路径）
    instances: "max",  # 启动实例数（"max"表示按CPU核心数自动扩展）
    exec_mode: "cluster",  # 集群模式（提升CPU利用率）
    env: {
      NODE_ENV: "production",  # 环境变量
    },
    log_date_format: "YYYY-MM-DD HH:mm:ss",  # 日志时间格式
    merge_logs: true  # 合并多实例日志
  }]
};

运行命令：

bash
docker run -d \
  --name node-app \
  -p 3000:3000 \
  -v $(pwd)/ecosystem.config.js:/app/ecosystem.config.js \  # 挂载PM2配置文件
  -v $(pwd)/app:/app \  # 挂载应用代码目录（若代码较多）
  <镜像仓库地址>/node20-alpine-pm2 \
  pm2 start /app/ecosystem.config.js --no-daemon

4.4 数据持久化

为避免容器重启后数据丢失，建议挂载以下目录：

4.4.1 日志持久化

PM2默认日志路径为/root/.pm2/logs，挂载该目录到宿主机：

bash
docker run -d \
  ...  # 其他参数（同上）
  -v $(pwd)/pm2-logs:/root/.pm2/logs \  # 挂载日志目录
  <镜像仓库地址>/node20-alpine-pm2 \
  pm2 start /app/ecosystem.config.js --no-daemon

4.4.2 依赖包持久化

若需避免每次重启容器重新安装依赖，可挂载node_modules目录：

bash
docker run -d \
  ...  # 其他参数（同上）
  -v $(pwd)/node_modules:/app/node_modules \  # 挂载依赖目录
  <镜像仓库地址>/node20-alpine-pm2 \
  pm2 start /app/ecosystem.config.js --no-daemon

5. 配置参数与环境变量

5.1 核心环境变量

5.2 PM2配置文件参数

通过ecosystem.config.js可自定义应用行为，关键参数说明：

6. 部署方案示例

6.1 Docker Compose配置

使用docker-compose.yml简化多容器或复杂配置管理，示例：

yaml
# docker-compose.yml
version: "3.8"

services:
  node-app:
    image: <镜像仓库地址>/node20-alpine-pm2:latest
    container_name: node-app
    restart: always  # 容器退出后自动重启（生产环境推荐）
    ports:
      - "3000:3000"  # 应用端口映射
    environment:
      - NODE_ENV=production
      - PM2_CONFIG_PATH=/app/ecosystem.config.js
    volumes:
      - ./app:/app  # 挂载应用代码目录（含ecosystem.config.js和app.js）
      - ./pm2-logs:/root/.pm2/logs  # 持久化日志
      - ./node_modules:/app/node_modules  # 持久化依赖（可选）
    command: pm2 start $PM2_CONFIG_PATH --no-daemon  # 使用环境变量指定配置文件路径

启动命令：

bash
docker-compose up -d

6.2 生产环境优化建议

• 资源限制：通过docker run --memory=2G --cpus=1限制容器资源
• 健康检查：添加HEALTHCHECK监控应用状态（如检查端口响应）
• 日志轮转：在ecosystem.config.js中配置log_date_format和merge_logs，结合宿主机日志工具（如logrotate）管理日志文件
• 配置文件外部化：将ecosystem.config.js挂载为外部文件，便于动态调整配置（无需重建镜像）

7. 注意事项

• Alpine兼容性：Alpine基于musl libc，部分依赖glibc的Node.js原生模块（如node-sass旧版本）可能无法运行，需使用Alpine兼容版本或调整依赖
• PM2前台运行：容器中必须通过--no-daemon参数启动PM2，否则PM2后台运行会导致容器立即退出
• 数据备份：挂载的日志、配置文件需定期备份，避免数据丢失
• 镜像更新：定期更新基础镜像（Node.js 20 Alpine）以修复安全漏洞