# 多进程异步并行架构

## 架构说明

### 当前架构（改造前）

```
单进程 + 单事件循环
┌─────────────────────┐
│ Python 进程          │
│ ┌─────────────────┐ │
│ │ asyncio Loop    │ │
│ │ 所有客户 + Agent  │ │
│ └─────────────────┘ │
└─────────────────────┘
```

**问题**：
- ❌ 单 CPU 核心
- ❌ 一个客户卡住影响全局
- ❌ 无法利用多核 CPU

---

### 新架构（改造后）

```
多进程 + 多事件循环
┌─────────┐  ┌─────────┐  ┌─────────┐
│进程 1    │  │进程 2    │  │进程 3    │
│Loop +   │  │Loop +   │  │Loop +   │
│客户 A,B │  │客户 C,D  │  │客户 E,F  │
└─────────┘  └─────────┘  └─────────┘
     ↓            ↓            ↓
  独立运行    独立运行    独立运行
```

**优势**：
- ✅ 真正的多核并行
- ✅ 故障隔离
- ✅ 负载均衡
- ✅ 可动态扩缩容

---

## 使用方法

### 方式 1：systemd 服务（推荐）

```bash
# 启动多进程模式
systemctl start ai-cs-multi

# 查看状态
systemctl status ai-cs-multi

# 查看日志
journalctl -u ai-cs-multi -f

# 停止服务
systemctl stop ai-cs-multi
```

### 方式 2：命令行启动

```bash
cd /root/ai_customer_service/ai_cs

# 使用默认进程数（CPU 核心数）
python3 scripts/multi_process_launcher.py

# 指定进程数
python3 scripts/multi_process_launcher.py --workers 4
```

---

## 配置说明

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `AI_CS_WORKER_ID` | 工作进程 ID | 0 |
| `AI_CS_SHARD_KEYS` | 本进程负责的客户 key | 空 |

### 分片算法

客户按 `acc_id:from_id` 的 MD5 hash 值分配到不同进程：

```python
shard_id = int(md5(f"{acc_id}:{from_id}").hexdigest(), 16) % num_workers
```

**特点**：
- 同一客户始终分配到同一进程
- 不同客户均匀分布
- 动态增减进程时自动重新平衡

---

## 监控

### 查看进程状态

```bash
# 查看所有工作进程
ps aux | grep ai-cs-worker

# 查看每个进程的 CPU 使用
top -p $(pgrep -d, -f ai-cs-worker)
```

### 日志查看

```bash
# 查看主进程日志
journalctl -u ai-cs-multi -f

# 查看特定工作进程日志
journalctl -u ai-cs-multi -f | grep "Worker 2"
```

---

## 性能对比

| 指标 | 单进程 | 多进程 (4 核) |
|------|--------|-------------|
| **并发客户数** | ~50 | ~200 |
| **CPU 使用率** | 25% (单核) | 80% (4 核) |
| **响应延迟** | 高 | 低 |
| **故障影响** | 全局 | 局部 |

---

## 注意事项

1. **进程数选择**：
   - 默认 = CPU 核心数
   - 建议不超过 CPU 核心数 × 2

2. **内存占用**：
   - 每个进程独立内存空间
   - 总内存 = 进程数 × 单进程内存

3. **日志管理**：
   - 每个进程独立日志
   - 通过 `worker_id` 区分

4. **动态扩容**：
   - 修改 `--workers` 参数
   - 重启服务自动重新分片

---

## 故障排查

### Worker 进程退出

```bash
# 查看日志
journalctl -u ai-cs-multi -f | grep "Worker.*退出"

# 手动重启
systemctl restart ai-cs-multi
```

### 负载不均衡

```bash
# 查看每个进程处理的客户数
ps aux | grep ai-cs-worker | awk '{print $2}' | while read pid; do
  echo "PID $pid: $(ps -p $pid -o %cpu,%mem,cmd --no-headers)"
done
```

### 内存泄漏

```bash
# 监控内存使用
watch -n 1 'ps aux | grep ai-cs-worker | awk "{sum+=$6} END {print \"Total: \" sum/1024 \" MB\"}"'
```


---

## 使用 run.py 启动

### 单进程模式（默认）

```bash
cd /root/ai_customer_service/ai_cs

# 正常启动（含 AI Agent）
python3 run.py

# 不启用 AI Agent
python3 run.py --no-agent
```

### 多进程模式

```bash
cd /root/ai_customer_service/ai_cs

# 多进程模式（默认 CPU 核心数）
python3 run.py --multi

# 指定进程数
python3 run.py --multi --workers 4
```

### systemd 服务

```bash
# 单进程模式
systemctl start ai-cs
systemctl status ai-cs
journalctl -u ai-cs -f

# 多进程模式
systemctl start ai-cs-multi
systemctl status ai-cs-multi
journalctl -u ai-cs-multi -f
```