stock-ai-agent/PM2_USAGE.md

# PM2 进程管理使用说明

## 📋 简介

PM2 是一个进程管理器，可以让你的应用在后台持续运行，并支持自动重启、日志管理等功能。

## 🚀 快速开始

### 1. 安装 PM2

```bash
# 全局安装 PM2
npm install -g pm2

# 验证安装
pm2 --version
```

### 2. 启动应用

```bash
# 开发模式启动
pm2 start ecosystem.config.js --env development

# 生产模式启动
pm2 start ecosystem.config.js --env production

# 或者直接使用默认配置
pm2 start ecosystem.config.js
```

### 3. 查看状态

```bash
# 查看所有进程状态
pm2 status

# 查看详细信息
pm2 show stock-agent

# 查看实时日志
pm2 logs stock-agent

# 查看错误日志
pm2 logs stock-agent --err

# 查看输出日志
pm2 logs stock-agent --out
```

### 4. 管理进程

```bash
# 停止应用
pm2 stop stock-agent

# 重启应用
pm2 restart stock-agent

# 删除应用
pm2 delete stock-agent

# 停止所有应用
pm2 stop all

# 重启所有应用
pm2 restart all
```

### 5. 监控

```bash
# 实时监控面板
pm2 monit

# 查看进程信息
pm2 list
```

### 6. 日志管理

```bash
# 清空所有日志
pm2 flush

# 查看日志文件位置
pm2 show stock-agent | grep log

# 日志轮转（安装模块）
pm2 install pm2-logrotate
```

## 🔧 配置说明

### ecosystem.config.js 配置文件

```javascript
module.exports = {
  apps: [{
    name: 'stock-agent',              // 应用名称
    script: 'backend/app/main.py',     // 启动脚本
    interpreter: 'python3',            // 解释器
    cwd: './',                         // 工作目录
    instances: 1,                      // 实例数量
    autorestart: true,                 // 自动重启
    watch: false,                      // 文件监控（生产环境建议关闭）
    max_memory_restart: '1G',          // 内存超限重启
    error_file: './logs/pm2-error.log', // 错误日志
    out_file: './logs/pm2-out.log',    // 输出日志
    log_file: './logs/pm2-combined.log',// 合并日志
    time: true,                        // 日志时间戳
    kill_timeout: 5000,                // 停止超时
    min_uptime: '10s',                 // 最小运行时间
    max_restarts: 10,                  // 最大重启次数
  }]
};
```

## 🛠️ 常用命令

### 开发环境

```bash
# 启动（开发模式）
pm2 start ecosystem.config.js --env development

# 查看日志
pm2 logs stock-agent

# 重启
pm2 restart stock-agent
```

### 生产环境

```bash
# 启动（生产模式）
pm2 start ecosystem.config.js --env production

# 保存进程列表
pm2 save

# 设置开机自启
pm2 startup
# 按照提示执行命令，然后运行
pm2 save
```

## 📊 日志管理

### 查看日志

```bash
# 实时查看所有日志
pm2 logs

# 查看最近 100 行
pm2 logs stock-agent --lines 100

# 查看错误日志
pm2 logs stock-agent --err

# 清空日志
pm2 flush
```

### 日志文件位置

```
./logs/pm2-error.log     # 错误日志
./logs/pm2-out.log       # 输出日志
./logs/pm2-combined.log  # 合并日志
```

## 🔍 故障排除

### 问题 1: 进程不断重启

```bash
# 查看重启次数
pm2 list

# 查看错误日志
pm2 logs stock-agent --err

# 检查配置
pm2 show stock-agent
```

### 问题 2: 内存占用过高

```bash
# 查看内存使用
pm2 monit

# 如果内存超过 max_memory_restart，会自动重启
```

### 问题 3: 端口被占用

```bash
# 查看端口占用
lsof -i :8000

# 停止应用
pm2 stop stock-agent

# 修改 .env 中的端口后重启
pm2 restart stock-agent
```

## 🚀 开机自启

### Linux/macOS

```bash
# 1. 保存当前进程列表
pm2 save

# 2. 生成启动脚本
pm2 startup

# 3. 按照提示执行命令

# 4. 验证
pm2 list
```

### 重启后恢复

```bash
# 恢复保存的进程列表
pm2 resurrect
```

## 📝 最佳实践

### 1. 开发环境

```bash
# 使用开发模式
pm2 start ecosystem.config.js --env development

# 开启文件监控（可选）
pm2 start ecosystem.config.js --watch
```

### 2. 生产环境

```bash
# 使用生产模式
pm2 start ecosystem.config.js --env production

# 保存进程列表
pm2 save

# 设置开机自启
pm2 startup
```

### 3. 日志管理

```bash
# 安装日志轮转模块
pm2 install pm2-logrotate

# 配置日志轮转
pm2 set pm2-logrotate:max_size 10M
pm2 set pm2-logrotate:retain 7
pm2 set pm2-logrotate:compress true
```

### 4. 监控告警

```bash
# 安装监控模块
pm2 install pm2-server-monit

# 查看监控
pm2 monit
```

## 🎯 完整工作流程

### 首次部署

```bash
# 1. 确保依赖已安装
cd backend
pip install -r requirements.txt
cd ..

# 2. 配置 .env 文件
cp .env.example .env
# 编辑 .env 文件

# 3. 创建日志目录
mkdir -p logs

# 4. 启动应用
pm2 start ecosystem.config.js

# 5. 保存进程列表
pm2 save

# 6. 查看状态
pm2 status

# 7. 查看日志
pm2 logs stock-agent
```

### 日常维护

```bash
# 查看状态
pm2 status

# 查看日志
pm2 logs stock-agent --lines 50

# 重启应用
pm2 restart stock-agent

# 清空日志
pm2 flush
```

### 更新代码后

```bash
# 1. 拉取最新代码
git pull

# 2. 重启应用
pm2 restart stock-agent

# 3. 查看日志确认
pm2 logs stock-agent --lines 20
```

## 📚 参考链接

- PM2 官方文档: https://pm2.keymetrics.io/
- PM2 GitHub: https://github.com/Unitech/pm2

## ⚠️ 注意事项

1. **生产环境**：关闭 `watch` 选项，避免性能问题
2. **日志管理**：定期清理或配置日志轮转，避免磁盘占满
3. **内存监控**：设置合理的 `max_memory_restart`
4. **开机自启**：生产环境建议设置开机自启
5. **环境变量**：确保 `.env` 文件配置正确

## 🎉 完成

配置完成后，你的应用将：

- ✅ 在后台持续运行
- ✅ 崩溃后自动重启
- ✅ 支持开机自启
- ✅ 自动管理日志
- ✅ 实时监控状态

所有系统（SmartAgent、CryptoAgent、StockAgent、模拟交易）都会自动启动并运行！