tw/DEPLOYMENT.md

# AI 客服系统 - 天网协作版部署文档

## 📋 运行架构

**单进程多模块架构**：
- ✅ 一个 Python 进程
- ✅ 多个模块协同工作
- ✅ WebSocket 客户端 + HTTP API 服务器 + 任务调度器

**优势**：
- 部署简单（一条命令）
- 资源共享（数据库连接、内存）
- 通信高效（进程内调用）

---

## 🚀 部署步骤

### 步骤 1：环境检查

```bash
# 检查 Python 版本
python3 --version  # 需要 3.8+

# 检查依赖
cd /root/ai_customer_service/ai_cs
pip3 list | grep -E "flask|pydantic|sqlite"
```

### 步骤 2：启动天网协作版

```bash
cd /root/ai_customer_service/ai_cs

# 启动（包含 AI Agent）
python3 run_with_tianwang.py

# 启动（不包含 AI Agent，仅基础回复）
python3 run_with_tianwang.py --no-agent
```

**启动后会看到**：
```
============================================================
AI 客服系统 - 天网协作版
============================================================
正在启动 HTTP API 服务器...
HTTP API 服务器已启动：http://0.0.0.0:5678

天网任务接口:
  POST /api/task/receive    - 接收任务
  POST /api/task/cancel     - 取消任务
  GET  /api/task/status/:id - 查询任务状态
  GET  /api/task/list       - 任务列表
  GET  /api/health          - 健康检查
============================================================
正在连接轻简 API...
AI Agent: 已启用
============================================================
系统已就绪，等待消息和任务...
```

### 步骤 3：测试 API

```bash
# 测试健康检查
curl http://localhost:5678/api/health

# 接收任务
curl -X POST http://localhost:5678/api/task/receive \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "TEST_001",
    "type": "test",
    "customer": {"id": "test_001"},
    "trigger": {"type": "customer_reply", "keyword": "测试"},
    "action": {"type": "send_message", "message": "测试消息"},
    "created_by": "测试"
  }'

# 查询任务
curl http://localhost:5678/api/task/status/TEST_001
```

---

## 🔧 生产环境部署

### 方式 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_with_tianwang.py
Restart=always
RestartSec=10
LimitNOFILE=65535

# 环境变量（可选）
Environment="HTTP_API_PORT=5678"
Environment="TASK_DB_PATH=/root/ai_customer_service/ai_cs/db/task_db/tasks.db"

# 日志
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：

```dockerfile
FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 5678

CMD ["python3", "run_with_tianwang.py"]
```

构建并运行：

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

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

```bash
cd /root/ai_customer_service/ai_cs

# 使用 nohup 后台运行
nohup python3 run_with_tianwang.py > /var/log/ai-cs.log 2>&1 &

# 查看进程
ps aux | grep run_with_tianwang

# 查看日志
tail -f /var/log/ai-cs.log

# 停止进程
pkill -f run_with_tianwang
```

---

## 📊 端口说明

| 端口 | 用途 | 是否必须 |
|------|------|----------|
| 5678 | HTTP API 服务器 | ✅ 必须 |
| 9528 | 轻简软件 WebSocket | ✅ 必须（外部） |

**防火墙配置**：
```bash
# 开放 HTTP API 端口
firewall-cmd --add-port=5678/tcp --permanent
firewall-cmd --reload

# 或者使用 iptables
iptables -A INPUT -p tcp --dport 5678 -j ACCEPT
```

---

## 🔍 监控与日志

### 查看运行状态

```bash
# systemd 方式
systemctl status ai-cs-tianwang

# 进程方式
ps aux | grep run_with_tianwang
```

### 查看日志

```bash
# systemd 方式
journalctl -u ai-cs-tianwang -f

# 文件方式
tail -f /var/log/ai-cs.log

# 只看任务相关日志
journalctl -u ai-cs-tianwang -f | grep "任务"
```

### 查看数据库

```bash
# 进入 SQLite
sqlite3 /root/ai_customer_service/ai_cs/db/task_db/tasks.db

# 查看所有任务
SELECT task_id, 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';

# 退出
.exit
```

---

## ⚠️ 注意事项

1. **HTTP 端口**：
   - 默认 5678，确保未被占用
   - 可在 `.env` 中修改：`HTTP_API_PORT=5679`

2. **数据库路径**：
   - 确保有写权限
   - 建议定期备份：`cp tasks.db tasks.db.backup`

3. **天网回调**：
   - 配置正确的回调 URL
   - 确保天网服务器能访问 AI 客服

4. **资源限制**：
   - 建议内存：≥ 512MB
   - 建议 CPU：≥ 1 核心

5. **进程守护**：
   - 推荐使用 systemd
   - 自动重启，故障恢复

---

## 🐛 故障排查

### 无法启动

```bash
# 检查端口占用
netstat -tlnp | grep 5678

# 检查依赖
pip3 list | grep -E "flask|pydantic"

# 手动运行查看错误
python3 run_with_tianwang.py
```

### 任务未触发

```bash
# 1. 检查任务状态
curl http://localhost:5678/api/task/status/TASK_ID

# 2. 查看日志
journalctl -u ai-cs-tianwang -f | grep "任务触发"

# 3. 检查触发条件
# 确认客户消息包含触发关键词
```

### HTTP API 无法访问

```bash
# 1. 检查服务状态
systemctl status ai-cs-tianwang

# 2. 检查端口
netstat -tlnp | grep 5678

# 3. 检查防火墙
firewall-cmd --list-ports

# 4. 本地测试
curl http://localhost:5678/api/health
```

---

## 📞 技术支持

- 完整文档：`/root/ai_customer_service/ai_cs/TIANWANG_INTEGRATION.md`
- 使用示例：`/root/ai_customer_service/ai_cs/SPECIFIED_CUSTOMER_REPLY_EXAMPLE.md`
- 日志位置：`journalctl -u ai-cs-tianwang -f`
- 数据库位置：`/root/ai_customer_service/ai_cs/db/task_db/tasks.db`