keymetrics/pm2

PM2 Docker镜像文档

镜像概述和主要用途

PM2 Docker镜像是一个生产就绪的Node.js环境镜像，集成了PM2运行时。该镜像旨在将Node.js应用程序封装到适合生产环境的容器中，解决在容器内运行Node.js应用时的关键问题，包括：

• 正确的PID 1信号处理与转发
• 应用的优雅启动与关闭
• 无缝应用集群化以提升性能和可靠性

此外，通过PM2作为容器与应用之间的中间层，可利用PM2的丰富特性，如应用声明文件、自定义日志系统、源码映射支持等，简化生产环境中Node.js应用的管理。

核心功能和特性

• 信号处理：正确处理并转发PID 1信号，确保容器生命周期管理符合预期
• 优雅启停：支持应用的平滑启动和关闭，避免数据丢失或连接中断
• 集群模式：内置应用集群化能力，充分利用多核CPU资源，提高应用吞吐量和可用性
• PM2生态集成：支持PM2应用声明文件(ecosystem.config.js/pm2.json)、日志管理、进程监控等核心功能
• 多环境支持：提供基于Alpine和多种Debian版本的镜像，满足不同场景下的系统依赖需求
• 可扩展性：支持PM2模块扩展，如自动Git拉取、服务器监控、Keymetrics集成等

使用场景和适用范围

• 生产环境中的Node.js应用部署
• 需要高可用性和性能的Node.js服务
• 需集中管理、监控和日志收集的Node.js应用集群
• 容器化部署的微服务架构中的Node.js服务
• 需要优雅关闭机制的有状态应用（如数据库连接、消息队列消费者）

可用标签

Alpine基础镜像

基于Alpine Linux，轻量级且资源占用低，适合对镜像大小敏感的场景。

Debian Bookworm基础镜像

基于Debian Bookworm，提供更完整的系统工具和库支持。

Debian Bullseye基础镜像

基于Debian Bullseye，适合需要稳定旧版本Debian环境的应用。

Debian Buster基础镜像

基于Debian Buster，支持旧版Node.js应用。

Debian Slim基础镜像

基于Debian Bookworm的精简版本，仅包含核心依赖，镜像体积更小。

有关镜像变体的更多信息，请参见https://github.com/nodejs/docker-node#image-variants%E3%80%82

详细使用方法和配置说明

项目结构准备

假设项目结构如下：

`-- your-app-name/
    |-- src/
        `-- app.js          # 应用入口文件
    |-- package.json        # 依赖配置
    |-- pm2.json            # PM2应用声明文件（需创建）
    `-- Dockerfile          # 镜像构建文件（需创建）

创建PM2应用声明文件

创建pm2.json文件，定义应用配置：

json
{
  "name": "your-app-name",       // 应用名称
  "script": "src/app.js",        // 入口文件路径
  "instances": "2",              // 启动实例数（"max"表示使用所有CPU核心）
  "env": {                       // 默认环境变量
    "NODE_ENV": "development"
  },
  "env_production": {            // 生产环境变量（通过--env production激活）
    "NODE_ENV": "production"
  },
  "kill_timeout": 3000           // 优雅关闭超时时间（毫秒）
}

应用声明文件支持更多配置项，详见PM2应用声明文档。

创建Dockerfile

dockerfile
# 选择基础镜像（根据需求替换标签，如latest-alpine、24-bookworm等）
FROM keymetrics/pm2:latest-alpine

# 复制应用代码和配置文件
COPY src/ src/
COPY package.json .
COPY pm2.json .

# 安装生产依赖
ENV NPM_CONFIG_LOGLEVEL warn
RUN npm install --production

# 显示目录结构（可选，用于调试）
RUN ls -al -R

# 使用pm2-runtime启动应用（必须使用pm2-runtime而非pm2 start以确保信号正确处理）
CMD ["pm2-runtime", "start", "pm2.json"]

构建和运行镜像

在项目根目录执行以下命令：

bash
# 构建镜像
docker build -t your-app-name .

# 运行容器
docker run -d -p 3000:3000 --name your-app-instance your-app-name

如需指定生产环境变量，可修改启动命令为：docker run -d your-app-name pm2-runtime start pm2.json --env production

Docker Compose部署示例

创建docker-compose.yml文件：

yaml
version: '3.8'

services:
  app:
    build: .
    image: your-app-name
    container_name: your-app-instance
    restart: always
    ports:
      - "3000:3000"  # 映射应用端口（根据实际应用调整）
    environment:
      - NODE_ENV=production
      # 如需集成Keymetrics，添加以下环境变量
      # - KEYMETRICS_PUBLIC=your_public_key
      # - KEYMETRICS_SECRET=your_secret_key
    volumes:
      - ./logs:/app/.pm2/logs  # 挂载日志目录（可选）
    command: ["pm2-runtime", "start", "pm2.json", "--env", "production"]

启动服务：

bash
docker-compose up -d

自定义配置

启用Git自动拉取

通过PM2模块实现应用代码与Git仓库自动同步：

1. 在Dockerfile中添加模块安装命令：

dockerfile
RUN pm2 install pm2-auto-pull

2. 确保应用源码中包含.git目录（构建时需复制.git文件夹）：

dockerfile
COPY .git/ .git/  # 添加到COPY步骤

详细配置参见https://github.com/pm2-hive/pm2-auto-pull%E3%80%82

启用服务器监控

安装PM2服务器监控模块，监控系统资源使用情况：

在Dockerfile中添加：

dockerfile
RUN pm2 install pm2-server-monit

监控数据可通过PM2日志或Keymetrics面板查看，详见https://github.com/keymetrics/pm2-server-monit%E3%80%82

集成Keymetrics.io监控面板

Keymetrics.io是基于PM2的监控服务，提供日志查看、进程重启、异常监控等功能。使用步骤：

1. 在Keymetrics创建Bucket，获取公钥（PUBLIC KEY）和密钥（SECRET KEY）

2. 通过环境变量配置密钥：

bash
docker run -d \
  -e KEYMETRICS_PUBLIC=your_public_key \
  -e KEYMETRICS_SECRET=your_secret_key \
  --name your-app-instance your-app-name

3. 确保容器可访问以下端口：
   • 80（TCP出站，HTTP）
   • 443（TCP出站，HTTPS）
   • 43554（TCP出站，Keymetrics专用）

集成问题排查参见Keymetrics故障排除文档。

启用优雅关闭

当容器接收关闭信号（如SIGINT、SIGTERM）时，PM2会将信号转发给应用，允许应用完成收尾工作（如关闭数据库连接、保存状态）。

在Node.js应用中添加信号处理逻辑：

javascript
process.on('SIGINT', () => {
  console.log('开始优雅关闭...');
  
  // 关闭数据库连接示例
  mongoose.connection.close(false, (err) => {
    console.log('MongoDB连接已关闭');
    process.exit(err ? 1 : 0);
  });
  
  // 其他清理操作（如停止定时任务、完成当前请求等）
});

调整关闭超时时间（默认1600ms）：在pm2.json中添加：

json
{
  "kill_timeout": 3000  // 超时时间（毫秒）
}

暴露健康检查端点

通过--web选项启用PM2健康检查API，暴露应用和容器的关键指标：

修改Dockerfile的CMD命令：

dockerfile
# 不指定端口时默认使用9615
CMD ["pm2-runtime", "start", "pm2.json", "--web"]

# 或指定自定义端口
CMD ["pm2-runtime", "start", "pm2.json", "--web", "3001"]

访问http://container-ip:9615可获取JSON格式的健康数据，包含：

• 进程状态、CPU/内存使用率
• 系统负载、内存、磁盘使用情况
• 应用重启次数、正常运行时间等

常用管理命令

文档与资源

• PM2官方文档
• PM2应用声明文件配置
• https://github.com/keymetrics/docker-pm2
• https://github.com/nodejs/docker-node#image-variants

许可证

• 本项目基于MIT许可证 - 详见https://github.com/keymetrics/docker-pm2/blob/master/LICENSE
• 镜像包含的软件许可证：
  • PM2: https://github.com/Unitech/pm2/blob/master/GNU-AGPL-3.0.txt
  • Node.js: https://github.com/nodejs/node/blob/master/LICENSE