# AI 客服系统 - 部署与运维文档

**版本**: v1.0 | **更新日期**: 2026-02-28

---

## 目录

1. [系统架构](#系统架构)
2. [快速部署](#快速部署)
3. [启动方式](#启动方式)
4. [生产环境部署](#生产环境部署)
5. [多进程架构](#多进程架构)
6. [API 接口文档](#api-接口文档)
7. [触发条件详解](#触发条件详解)
8. [数据库](#数据库)
9. [配置说明](#配置说明)
10. [监控与日志](#监控与日志)
11. [故障排查](#故障排查)

---

## 系统架构

```
┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│  天网服务器  │ ───→ │  AI 客服 API  │ ───→ │  企业微信   │
│  (公网 IP)   │      │ (127.0.0.1:6060)│    │  (轻简软件)  │
└─────────────┘      └──────────────┘      └─────────────┘
       ↑                     │
       └─────────────────────┘
                      ┌──────────────┐
                      │   SQLite     │
                      │  任务数据库   │
                      └──────────────┘
```

### 核心组件

| 组件 | 地址 | 说明 |
|------|------|------|
| AI 客服 HTTP API | `http://127.0.0.1:6060` | 接收天网任务 |
| 天网服务器 | 公网 IP | 任务调度中心 |
| 轻简软件 | `ws://127.0.0.1:9528` | 企业微信连接 |
| 任务数据库 | SQLite 本地存储 | 任务持久化 |

---

## 快速部署

### 步骤 1：环境检查

```bash
python3 --version  # 需要 3.8+
cd /root/ai_customer_service/ai_cs
pip3 install -r requirements.txt
```

### 步骤 2：启动服务

```bash
cd /root/ai_customer_service/ai_cs

# 前台运行（测试用）
python3 run.py --api-only

# 后台运行（生产用）
nohup python3 run.py --api-only > /tmp/tianwang.log 2>&1 &
```

### 步骤 3：验证

```bash
curl http://localhost:6060/api/health
# 预期: {"code":200,"data":{"service":"ai-cs-tianwang-bridge",...},"message":"OK"}
```

---

## 启动方式

统一入口 `run.py`，通过参数切换模式：

```bash
# 仅 HTTP API（天网简化版，推荐）
python3 run.py --api-only

# 完整版（HTTP API + WebSocket + AI Agent）
python3 run.py --tianwang

# WebSocket 客服模式（默认）
python3 run.py

# 多进程模式
python3 run.py --multi --workers 4

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

# 指定 HTTP 端口
python3 run.py --api-only --port 8080
```

---

## 生产环境部署

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

```bash
cat > /etc/systemd/system/ai-cs-tianwang.service << 'SERVICE'
[Unit]
Description=AI Customer Service with Tianwang
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/root/ai_customer_service/ai_cs
ExecStart=/usr/bin/python3 run.py --api-only
Restart=always
RestartSec=10
LimitNOFILE=65535
Environment="HTTP_API_PORT=6060"
StandardOutput=journal
StandardError=journal
SyslogIdentifier=ai-cs-tianwang

[Install]
WantedBy=multi-user.target
SERVICE

systemctl daemon-reload
systemctl enable ai-cs-tianwang
systemctl start ai-cs-tianwang
systemctl status ai-cs-tianwang
journalctl -u ai-cs-tianwang -f
```

### 方式 2：Docker 部署

```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 6060
CMD ["python3", "run.py", "--api-only"]
```

```bash
docker build -t ai-cs-tianwang .
docker run -d \
  --name ai-cs \
  -p 6060:6060 \
  -v /root/ai_customer_service/ai_cs/db:/app/db \
  --restart unless-stopped \
  ai-cs-tianwang
```

### 方式 3：后台运行（简单场景）

```bash
nohup python3 run.py --api-only > /tmp/tianwang.log 2>&1 &
ps aux | grep "run.py"
tail -f /tmp/tianwang.log
pkill -f "run.py"  # 停止
```

---

## 多进程架构

### 架构说明

```
单进程（默认）                 多进程（可选）
┌─────────────────┐           ┌─────────┐  ┌─────────┐  ┌─────────┐
│ Python 进程     │           │进程 1    │  │进程 2    │  │进程 3    │
│ asyncio Loop    │           │客户 A,B  │  │客户 C,D  │  │客户 E,F  │
│ 所有客户 + Agent │           └─────────┘  └─────────┘  └─────────┘
└─────────────────┘
```

### 使用方法

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

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

# 或使用专用启动器
python3 scripts/multi_process_launcher.py --workers 4
```

### 分片算法

客户按 `acc_id:from_id` 的 MD5 hash 值分配到不同进程，同一客户始终在同一进程。

### 性能对比

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

---

## API 接口文档

### 1. 接收任务

**POST** `/api/task/receive`

```bash
curl -X POST http://localhost:6060/api/task/receive \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "TASK_20260227_001",
    "type": "send_file_after_reply",
    "customer": {"id": "customer_123", "name": "小明"},
    "trigger": {
      "type": "specified_customer_reply",
      "customer_id": "customer_123",
      "customer_name": "小明",
      "keyword": "好的",
      "exact_match": false
    },
    "action": {"type": "send_message", "message": "这是您要的文件"},
    "priority": "normal",
    "timeout_hours": 24,
    "created_by": "设计师 lz"
  }'
```

**响应**:
```json
{"code": 200, "message": "任务接收成功", "data": {"task_id": "TASK_20260227_001", "status": "pending"}}
```

### 2. 查询任务状态

**GET** `/api/task/status/:task_id`

```bash
curl http://localhost:6060/api/task/status/TASK_20260227_001
```

### 3. 取消任务

**POST** `/api/task/cancel`

```bash
curl -X POST http://localhost:6060/api/task/cancel \
  -H "Content-Type: application/json" \
  -d '{"task_id": "TASK_20260227_001", "reason": "客户取消订单"}'
```

### 4. 任务列表

**GET** `/api/task/list`

参数: `customer_id`(可选)、`status`(可选)、`page`(默认1)、`page_size`(默认20)

```bash
curl "http://localhost:6060/api/task/list?status=pending&page=1&page_size=10"
```

### 5. 健康检查

**GET** `/api/health`

```bash
curl http://localhost:6060/api/health
```

---

## 触发条件详解

### 1. specified_customer_reply（推荐）

指定客户回复指定内容时触发。

```json
{
  "trigger": {
    "type": "specified_customer_reply",
    "customer_id": "customer_123",
    "customer_name": "小明",
    "keyword": "好的",
    "exact_match": false
  }
}
```

| 字段 | 必填 | 说明 |
|------|------|------|
| `customer_id` | 是 | 指定客户 ID |
| `customer_name` | 否 | 指定客户名称 |
| `keyword` | 是 | 回复关键词 |
| `exact_match` | 否 | 是否精确匹配（默认 false）|

**exact_match 说明**:
- `false`: 消息**包含**关键词即触发（"好的谢谢" 匹配 "好的"）
- `true`: 消息**完全等于**关键词才触发

**匹配逻辑**:
```
客户发送消息 → 检查客户 ID → 检查客户名称(可选) → 检查关键词 → 触发
```

### 2. customer_reply

任意客户回复指定内容。

```json
{"trigger": {"type": "customer_reply", "keyword": "好的"}}
```

### 3. customer_keyword

任意客户说某关键词（支持多个）。

```json
{"trigger": {"type": "customer_keyword", "keywords": ["好的", "可以", "行"]}}
```

### 4. customer_payment

客户付款时触发。

```json
{"trigger": {"type": "customer_payment", "keywords": ["已付款", "拍下了"]}}
```

### 5. time_reach

到达指定时间触发。

```json
{"trigger": {"type": "time_reach", "time": "2026-02-28 09:00:00"}}
```

---

## 数据库

### 天网任务数据库

路径: `db/task_db/tasks.db`

```sql
CREATE TABLE tasks (
    task_id TEXT PRIMARY KEY,
    specified_customer_id TEXT,
    specified_customer_name TEXT,
    type TEXT NOT NULL,
    customer_name TEXT,
    customer_id TEXT,
    trigger_type TEXT,
    trigger_keyword TEXT,
    trigger_keywords TEXT,
    action_type TEXT,
    action_file_url TEXT,
    action_message TEXT,
    priority TEXT DEFAULT 'normal',
    timeout_hours INTEGER DEFAULT 24,
    status TEXT DEFAULT 'pending',
    retry_count INTEGER DEFAULT 0,
    max_retry INTEGER DEFAULT 3,
    created_at TEXT,
    created_by TEXT,
    triggered_at TEXT,
    completed_at TEXT,
    error_message TEXT,
    result TEXT
);
```

**任务状态流转**: `pending → waiting → running → completed / failed`

### 图片任务数据库

路径: `db/image_tasks.db`（详见 **项目功能汇总.md - 图片任务数据库**）

---

## 配置说明

### 环境变量

文件: `.env.tianwang`

```bash
AI_CS_HOST=127.0.0.1
AI_CS_PORT=6060
AI_CS_API_URL=http://127.0.0.1:6060
TIANWANG_CALLBACK_URL=http://127.0.0.1:6060/api/task/callback
```

### 天网回调配置

在 `core/task_scheduler.py` 中修改回调 URL:

```python
await client.post('http://tianwang-server/api/task/callback', json={...})
```

### 端口说明

| 端口 | 用途 |
|------|------|
| 6060 | HTTP API 服务器 |
| 9528 | 轻简软件 WebSocket（外部）|

**防火墙**:
```bash
firewall-cmd --add-port=6060/tcp --permanent && firewall-cmd --reload
```

---

## 监控与日志

### 查看进程状态

```bash
ps aux | grep "run.py"
netstat -tlnp | grep 6060
systemctl status ai-cs-tianwang  # systemd 方式
```

### 查看日志

```bash
tail -f /tmp/tianwang.log                              # 文件方式
journalctl -u ai-cs-tianwang -f                        # systemd 方式
grep "任务" /tmp/tianwang.log                           # 搜索任务日志
grep "派单" /tmp/tianwang.log                           # 搜索派单日志
grep "转接人工" /tmp/tianwang.log                       # 搜索转接日志
```

### 查看数据库

```bash
sqlite3 /root/ai_customer_service/ai_cs/db/task_db/tasks.db

SELECT task_id, type, status, created_at FROM tasks ORDER BY created_at DESC LIMIT 10;
SELECT * FROM tasks WHERE status='pending';
SELECT task_id, error_message FROM tasks WHERE status='failed';
SELECT status, COUNT(*) as count FROM tasks GROUP BY status;
.exit
```

---

## 故障排查

### API 无法访问

```bash
ps aux | grep "run.py"               # 检查进程
netstat -tlnp | grep 6060           # 检查端口
pkill -f "run.py"                    # 停止
nohup python3 run.py --api-only > /tmp/tianwang.log 2>&1 &
tail -f /tmp/tianwang.log            # 查看日志
```

### 任务接收失败（500 错误）

```bash
tail -f /tmp/tianwang.log | grep "ERROR"
sqlite3 db/task_db/tasks.db ".schema tasks"   # 检查数据库
# 如果数据库损坏：rm db/task_db/tasks.db 然后重启（自动重建）
```

### 任务未触发

```bash
curl http://localhost:6060/api/task/status/TASK_ID   # 检查状态
grep "任务触发" /tmp/tianwang.log                     # 查看触发日志
# 确认客户消息包含触发关键词
```

### 内存占用过高

```bash
ps aux | grep run_tianwang | awk '{print $6/1024 " MB"}'
# 建议每天定时重启
crontab -e
# 添加: 0 3 * * * pkill -f "run.py" && sleep 2 && nohup python3 /root/ai_customer_service/ai_cs/run.py --api-only > /tmp/tianwang.log 2>&1 &
```

### Worker 进程退出（多进程模式）

```bash
journalctl -u ai-cs-multi -f | grep "Worker.*退出"
systemctl restart ai-cs-multi
```

---

## 文件位置速查

| 文件 | 路径 |
|------|------|
| 启动脚本 | `run.py`（通过 `--api-only` / `--tianwang` 切换模式）|
| HTTP API | `api/http_server.py` |
| 任务调度 | `core/task_scheduler.py` |
| 数据模型 | `db/task_db/task_model.py` |
| 配置文件 | `.env.tianwang` |
| 日志文件 | `/tmp/tianwang.log` |
| 任务数据库 | `db/task_db/tasks.db` |

---

## 快速参考

```
┌─────────────────────────────────────────────┐
│  AI 客服 API - 快速参考                      │
├─────────────────────────────────────────────┤
│ 地址：http://localhost:6060                  │
│                                             │
│ POST /api/task/receive    - 接收任务        │
│ GET  /api/task/status/:id - 查询状态        │
│ POST /api/task/cancel     - 取消任务        │
│ GET  /api/task/list       - 任务列表        │
│ GET  /api/health          - 健康检查        │
│                                             │
│ 启动：python3 run.py --api-only             │
│ 日志：tail -f /tmp/tianwang.log             │
│ 数据库：sqlite3 db/task_db/tasks.db         │
└─────────────────────────────────────────────┘
```