tw/DEPLOYMENT.md

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

📋 运行架构

单进程多模块架构：

• ✅ 一个 Python 进程
• ✅ 多个模块协同工作
• ✅ WebSocket 客户端 + HTTP API 服务器 + 任务调度器

优势：

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

---

🚀 部署步骤

步骤 1：环境检查

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

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

步骤 2：启动天网协作版

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

# 测试健康检查
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 服务（推荐）

创建服务文件：

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：

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"]

构建并运行：

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：后台运行（简单场景）

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	✅ 必须（外部）

防火墙配置：

# 开放 HTTP API 端口
firewall-cmd --add-port=5678/tcp --permanent
firewall-cmd --reload

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

---

🔍 监控与日志

查看运行状态

# systemd 方式
systemctl status ai-cs-tianwang

# 进程方式
ps aux | grep run_with_tianwang

查看日志

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

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

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

查看数据库

# 进入 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
   • 自动重启，故障恢复

---

🐛 故障排查

无法启动

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

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

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

任务未触发

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

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

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

HTTP API 无法访问

# 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