tw/部署文档.md

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

📋 系统架构

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│  天网服务器  │ ───→ │  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：环境检查

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

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

步骤 2：启动 AI 客服 API

cd /root/ai_customer_service/ai_cs

# 前台运行（测试用）
python3 run_tianwang_simple.py

# 后台运行（生产用）
nohup python3 run_tianwang_simple.py > /tmp/tianwang.log 2>&1 &

# 查看进程
ps aux | grep run_tianwang

# 查看日志
tail -f /tmp/tianwang.log

步骤 3：测试 API

# 健康检查
curl http://localhost:6060/api/health

# 预期输出：
# {"code":200,"data":{"service":"ai-cs-tianwang-bridge","timestamp":"..."},"message":"OK"}

---

📝 API 接口说明

1. 接收任务

接口: POST /api/task/receive

请求示例:

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"
  }'

响应示例:

{
  "code": 200,
  "message": "任务接收成功",
  "data": {
    "task_id": "TASK_20260227_001",
    "status": "pending"
  }
}

---

2. 查询任务状态

接口: GET /api/task/status/:task_id

请求示例:

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

响应示例:

{
  "code": 200,
  "data": {
    "task_id": "TASK_20260227_001",
    "type": "send_file_after_reply",
    "status": "pending",
    "priority": "normal",
    "retry_count": 0,
    "created_at": "2026-02-27T18:00:00",
    "created_by": "设计师 lz",
    "triggered_at": null,
    "completed_at": null,
    "error_message": null
  }
}

---

3. 取消任务

接口: POST /api/task/cancel

请求示例:

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

响应示例:

{
  "code": 200,
  "message": "任务已取消",
  "data": {
    "task_id": "TASK_20260227_001",
    "status": "cancelled"
  }
}

---

4. 查询任务列表

接口: GET /api/task/list

请求参数:

• customer_id (可选): 客户 ID
• status (可选): 任务状态
• page (可选): 页码，默认 1
• page_size (可选): 每页数量，默认 20

请求示例:

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

---

5. 健康检查

接口: GET /api/health

请求示例:

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

响应示例:

{
  "code": 200,
  "message": "OK",
  "data": {
    "timestamp": "2026-02-27T18:00:00",
    "service": "ai-cs-tianwang-bridge"
  }
}

---

📊 触发条件类型

1. specified_customer_reply（推荐）

指定客户回复指定内容

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

匹配逻辑:

• ✅ 客户 ID 匹配
• ✅ 客户名称匹配（可选）
• ✅ 消息包含关键词

---

2. customer_reply

任意客户回复指定内容

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

---

3. customer_keyword

任意客户说某关键词

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

---

4. customer_payment

客户付款

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

---

5. time_reach

到达指定时间

{
  "trigger": {
    "type": "time_reach",
    "time": "2026-02-27 09:00:00"
  }
}

---

🔧 配置说明

环境变量文件

位置：/root/ai_customer_service/ai_cs/.env.tianwang

# AI 客服配置
AI_CS_HOST=127.0.0.1
AI_CS_PORT=6060

# AI 客服 HTTP API 地址（本地）
AI_CS_API_URL=http://127.0.0.1:6060

# 天网回调地址
TIANWANG_CALLBACK_URL=http://127.0.0.1:6060/api/task/callback

# API 接口
TASK_RECEIVE=/api/task/receive
TASK_STATUS=/api/task/status
TASK_CANCEL=/api/task/cancel
TASK_LIST=/api/task/list
HEALTH=/api/health

---

数据库配置

位置：/root/ai_customer_service/ai_cs/db/task_db/tasks.db

数据库结构:

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
);

---

📖 使用场景

场景 1：客户说"好的"后发送文件

天网下发任务:

{
  "task_id": "TASK_001",
  "type": "send_file_after_reply",
  "customer": {
    "id": "customer_123",
    "name": "小明"
  },
  "trigger": {
    "type": "specified_customer_reply",
    "customer_id": "customer_123",
    "customer_name": "小明",
    "keyword": "好的"
  },
  "action": {
    "type": "send_message",
    "message": "这是您要的文件"
  },
  "priority": "normal",
  "timeout_hours": 24,
  "created_by": "设计师 lz"
}

流程:

1. 天网下发任务 → AI 客服 API
2. 客户在群里说"好的"
3. AI 客服检测到匹配任务
4. 自动发送消息给客户
5. 任务标记为 completed
6. 回调通知天网

---

场景 2：客户付款后发送教程

天网下发任务:

{
  "task_id": "TASK_002",
  "type": "send_tutorial_after_payment",
  "customer": {
    "id": "customer_456",
    "name": "小红"
  },
  "trigger": {
    "type": "customer_payment"
  },
  "action": {
    "type": "send_message",
    "message": "感谢购买！这是使用教程：..."
  },
  "created_by": "设计师 lz"
}

---

场景 3：定时发送问候

天网下发任务:

{
  "task_id": "TASK_003",
  "type": "send_greeting",
  "customer": {
    "id": "customer_789"
  },
  "trigger": {
    "type": "time_reach",
    "time": "2026-02-28 09:00:00"
  },
  "action": {
    "type": "send_message",
    "message": "早上好！有什么可以帮您？"
  },
  "created_by": "设计师 lz"
}

---

🔍 监控与日志

查看进程状态

# 查看进程
ps aux | grep run_tianwang

# 查看端口
netstat -tlnp | grep 6060

查看日志

# 实时日志
tail -f /tmp/tianwang.log

# 最近 100 行
tail -100 /tmp/tianwang.log

# 搜索关键词
grep "任务" /tmp/tianwang.log

查看数据库

# 进入 SQLite
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

---

⚠️ 故障排查

问题 1：API 无法访问

症状: curl http://localhost:6060/api/health 无响应

解决:

# 1. 检查进程
ps aux | grep run_tianwang

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

# 3. 重启服务
pkill -f run_tianwang
cd /root/ai_customer_service/ai_cs
nohup python3 run_tianwang_simple.py > /tmp/tianwang.log 2>&1 &

# 4. 查看日志
tail -f /tmp/tianwang.log

---

问题 2：任务接收失败

症状: POST /api/task/receive 返回 500 错误

解决:

# 1. 查看日志
tail -f /tmp/tianwang.log | grep "ERROR"

# 2. 检查数据库
sqlite3 /root/ai_customer_service/ai_cs/db/task_db/tasks.db ".schema tasks"

# 3. 测试数据库
sqlite3 /root/ai_customer_service/ai_cs/db/task_db/tasks.db "SELECT 1;"

# 4. 如果数据库损坏，删除重建
rm /root/ai_customer_service/ai_cs/db/task_db/tasks.db
# 重启服务后会自动创建

---

问题 3：任务未触发

症状: 任务一直是 pending 状态

解决:

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

# 2. 查看触发日志
grep "任务触发" /tmp/tianwang.log

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

# 4. 手动触发测试
sqlite3 /root/ai_customer_service/ai_cs/db/task_db/tasks.db \
  "UPDATE tasks SET status='pending' WHERE task_id='TASK_ID';"

---

问题 4：内存占用过高

症状: 进程内存持续增长

解决:

# 1. 查看内存使用
ps aux | grep run_tianwang | awk '{print $6/1024 " MB"}'

# 2. 定期重启（建议每天）
crontab -e
# 添加：0 3 * * * pkill -f run_tianwang && sleep 2 && nohup python3 /root/ai_customer_service/ai_cs/run_tianwang_simple.py > /tmp/tianwang.log 2>&1 &

---

📞 技术支持

文件位置

文件	路径
启动脚本	/root/ai_customer_service/ai_cs/run_tianwang_simple.py
HTTP API	/root/ai_customer_service/ai_cs/api/http_server.py
任务调度	/root/ai_customer_service/ai_cs/core/task_scheduler.py
数据模型	/root/ai_customer_service/ai_cs/db/task_db/task_model.py
配置文件	/root/ai_customer_service/ai_cs/.env.tianwang
日志文件	/tmp/tianwang.log
数据库	/root/ai_customer_service/ai_cs/db/task_db/tasks.db

文档位置

文档	路径
部署文档	/root/ai_customer_service/ai_cs/部署文档.md
功能文档	/root/ai_customer_service/ai_cs/TIANWANG_INTEGRATION.md
使用示例	/root/ai_customer_service/ai_cs/SPECIFIED_CUSTOMER_REPLY_EXAMPLE.md

---

📧 发送文档

如需发送此文档，可以：

方式 1：复制内容

# 复制文档内容
cat /root/ai_customer_service/ai_cs/部署文档.md

方式 2：生成 PDF

# 安装 pandoc
apt-get install pandoc

# 转换为 PDF
pandoc /root/ai_customer_service/ai_cs/部署文档.md -o 部署文档.pdf

方式 3：发送邮件

# 使用 mail 命令
mail -s "AI 客服系统部署文档" recipient@example.com < /root/ai_customer_service/ai_cs/部署文档.md

---

🎯 快速参考卡片

┌─────────────────────────────────────────────┐
│  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_tianwang_simple.py        │
│ 日志：tail -f /tmp/tianwang.log             │
│ 数据库：sqlite3 db/task_db/tasks.db         │
└─────────────────────────────────────────────┘

---

文档版本: v1.0
更新日期: 2026-02-27
维护者: AI 客服系统团队