wangliang/crm-ai
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3b8997b565f59507c5eea1c1db806808b4030072
crm-ai/docs/go-live.md
T

11 KiB
Raw Blame History

CRM-NEW 上线文档

项 内容
上线日期 2026-10-23
上线范围 方案 A：bridge 接管 Live chat AI；Email/WhatsApp 人工处理
当前状态 Live chat 已切 bridge AI；Email/WhatsApp 已切人工团队；Twenty 商机已打通
变更窗口 建议低峰期，预留 30–60 分钟
负责人 待填

1. 上线范围

上线内容

  • LibreDesk：Live chat / Email / WhatsApp 三个渠道
  • bridge AI：Live chat 的 LLM、工具、RAG、OTP、输出护栏、质量指标
  • Twenty CRM：联系人、公司、商机、备注、3 天跟进任务
  • Email/WhatsApp：不再由 AI 回复，进入 Wholesale Support 人工团队
  • 旧 bridge KB：Hybrid RAG（parent-child + 向量 + 全文 + RRF）
  • 全量商品页 sitemap：www 32,691 / us 22,625
  • 质量：逐会话指标、URL/数字审计、质量日报、离线评测

不在本次上线范围

  • Email / WhatsApp 的 bridge AI 回复
  • WhatsApp 模板消息 / 媒体 / 语音
  • 邮件每日 digest
  • A/B 实验
  • 多副本/高可用部署
  • PII 自动保留/删除策略
  • 真实客户邮件历史 ingest（当前 kb_mail_docs 只有测试邮件）

2. 当前架构

Live chat (inbox 1)
  LibreDesk widget
    → LibreDesk webhook message.created
    → bridge /libredesk/webhook
    → bridge AI（LLM + 工具 + RAG + OTP + 输出护栏）
    → LibreDesk API 回写 agent 消息

Email (inbox 2) / WhatsApp (inbox 3)
  → LibreDesk 自动化规则
  → assign_team = Wholesale Support
  → 人工团队队列
  → 不调用 AI

3. 访问入口

服务 地址 备注
LibreDesk http://localhost:9000 管理端 / 工作台
Twenty CRM http://localhost:3100 CRM
bridge http://localhost:4100 内部工具/健康检查
Widget 测试页 http://localhost:8088/demo.html 本机测试用
公网入口 .env 的 PUBLIC_BASE_URL Cloudflare Quick Tunnel，URL 会变
Postgres localhost:5440 仅本机
Redis localhost:6390 仅本机
IMAP proxy localhost:1993 仅本机

4. 当前切流配置

Live chat

项 状态
bridge webhook 启用
LibreDesk 规则 1“分配新会话给 AI Assistant” 关闭
bridge inbox 过滤 LIBREDESK_WEBHOOK_INBOX_IDS=1

Email / WhatsApp

项 状态
团队 Wholesale Support（id=1）
团队类型 Round robin
成员 agent1 (26)、agent2 (27)
规则 4 Email inbox 2 → assign_team 1
规则 5 WhatsApp inbox 3 → assign_team 1
AI Assistant 分配 已移除

agent1/agent2 当前是 offline。Round robin 只有坐席在线/可用时才会进一步分到个人；离线时停留在团队队列。若希望永远只进团队队列，可把团队类型改为 Manual。

5. 上线前检查

  • .env 已备份，且权限为 600
  • docker compose config -q 通过
  • RPC 隧道可用（商品/订单/库存）
  • LibreDesk webhook Bridge AI 为启用状态
  • LibreDesk 规则 1 关闭
  • 规则 4/5 指向 Wholesale Support
  • agent1/agent2 可登录，必要时设为在线
  • WhatsApp access token 未过期（当前 token 有到期时间）
  • 公网 URL 与 Meta webhook 已同步
  • 163 SMTP / IMAP 可用
  • 已做数据库备份
  • bridge 测试通过
  • 质量告警 cron 已配置（或本次上线后立即配置）

6. 部署/启动步骤

6.1 当前机器上启动

cd /home/dev/code/crm-new

# 1) 校验 compose
docker compose config -q

# 2) 启动/更新
docker compose up -d

# 3) 重建 bridge（代码变更时必须）
docker compose up -d --build --force-recreate bridge

# 4) 查看状态
docker compose ps

6.2 首次部署/新环境

cd /home/dev/code/crm-new
bash scripts/bootstrap.sh

首次部署后还需要：

node scripts/setup-defaults.js
node scripts/twenty-bootstrap.js
node scripts/register-tools.js
node scripts/configure-email.js

已有环境不要直接重跑 bootstrap.sh，会覆盖 .env/配置。

6.3 数据准备

# 全量商品页站点地图（每周/商品大更新后）
node scripts/build-site-map.js www us

# 重建 KB parent-child 索引（KB 更新后；会先备份旧表）
bash scripts/rebuild-kb-index.sh

# 旧 KB 补 text_tsv/parent_id（已执行过，幂等）
node scripts/upgrade-kb-schema.js

6.4 RPC 隧道

商品/订单/库存依赖本机到内网的 RPC 隧道：

bash scripts/rpc-tunnel.sh

隧道断了会导致 search_products/search_orders/search_inventory 失败。

6.5 公网 HTTPS / WhatsApp webhook

bash scripts/public-https.sh

Cloudflare Quick Tunnel URL 每次重启可能变化，需要同步：

  • LibreDesk app.root_url
  • Meta WhatsApp callback URL

7. 验收清单

7.1 基础健康

curl -s http://localhost:4100/healthz
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3100/healthz
cd bridge && npm test

预期：

  • bridge {"ok":true,...}
  • Twenty 200
  • tests 75/75

7.2 Live chat JWT

node scripts/e2e-widget-jwt.js "What is the minimum order value?"

预期：

  • AI 回复 €30
  • 调用 search_kb
  • 回复为 HTML
  • 无未验证 URL

7.3 匿名 OTP

node scripts/e2e-anon-otp.js

预期：

  • AI 先要求验证
  • 收到验证码邮件
  • 输入后 verified
  • 能查订单（或明确无订单）

该脚本会读取 163 邮箱并创建测试会话，生产环境谨慎执行。

7.4 商机

node scripts/e2e-widget-jwt.js "I want to buy 500 pieces of stainless steel rings"

然后发：

Our company is Test Buyer BV, contact name Jan Jansen.

到 Twenty 检查：

  • Company / Person / Opportunity
  • Opportunity 名称为 <company> — <need>
  • Note 已关联
  • Task 3 天后到期

7.5 离线评测

node scripts/eval-offline.js
node scripts/eval-live.js

预期：

  • 确定性评测 18/18
  • 真实模型 smoke 4/4

7.6 质量指标

node scripts/quality-report.js 24
node scripts/quality-alert.js 1 --dry-run

预期：

  • 无错误/无未验证 URL 告警
  • 当前健康时输出 {"ok":true,...}

8. 监控与告警

质量告警 cron

*/30 * * * * cd /home/dev/code/crm-new && node scripts/quality-alert.js 1 >> logs/quality-alert.log 2>&1

阈值：

  • AI 错误率 > 10%
  • 工具错误率 > 10%
  • 未验证 URL 占比 > 15%
  • 平均延迟 > 8000ms

必看日志

docker logs -f crmnew-bridge
docker logs -f crmnew-libredesk
docker logs -f crmnew-twenty-server
docker logs -f crmnew-cloudflared

bridge 关键日志：

  • webhook: message.created
  • agent: tool
  • agent: output_guard
  • agent: replied
  • crm: stage_advanced

外部依赖巡检

  • RPC 隧道进程
  • 163 SMTP/IMAP
  • WhatsApp token 剩余有效期
  • Cloudflare tunnel 状态
  • 未分配/团队队列积压

9. 日常运维

# 重启 bridge
docker compose restart bridge

# 重建 bridge
docker compose up -d --build --force-recreate bridge

# 查看资源
docker stats

# 数据库备份
docker exec crmnew-postgres pg_dump -U crmnew -d libredesk > backup-libredesk-$(date +%F).sql
docker exec crmnew-postgres pg_dump -U crmnew -d bridge   > backup-bridge-$(date +%F).sql
docker exec crm-postgres   pg_dump -U postgres -d products > backup-products-$(date +%F).sql

详细命令见 runbook.md。

10. 回滚方案

10.1 Live chat 回滚（最常用）

# 1) 停用 bridge webhook
# LibreDesk 后台 Webhooks → Bridge AI → 停用

# 2) 重新开启规则 1
# Automations → Assign new conversations to AI Assistant → 启用

# 3) 可选：停止 bridge
docker compose stop bridge

效果：Live chat 回到 LibreDesk 自带 AI。

10.2 Email / WhatsApp 回滚

# 规则 4/5 改回 assign_user = AI Assistant(id=3)

或直接停用规则 4/5，由人工在未分配队列处理。

10.3 数据回滚

  • KB 旧表：kb_docs_v1
  • rebuild 前备份：kb_docs_backup_20261022
  • 恢复前先确认表结构/索引
  • Twenty 测试数据删除需按 ID 精确操作，不要批量删

10.4 代码回滚

  • 保留上一版 bridge 镜像/commit
  • docker compose up -d --build --force-recreate bridge
  • 回滚后必须重跑：
    • npm test
    • scripts/eval-offline.js
    • 一条 Live chat smoke

11. 已知限制与风险

高

  1. 单点：bridge 只有一个实例；bridge 挂了 Live chat 无 AI 回复。
  2. RPC 隧道：依赖本机 SSH 隧道，断了商品/订单/库存工具不可用。
  3. 公网 URL：Cloudflare Quick Tunnel URL 不固定，重启可能失效。
  4. WhatsApp token：临时 token 有到期时间，需要提前续期。
  5. Email 历史数据为空：kb_mail_docs 只有测试邮件，真实客户历史未 ingest。

中

  1. 商机币种：USD 1000 目前存为 EUR。
  2. productNeed：可能把整句需求写入商机名。
  3. 输出护栏是规则型：可能漏掉未覆盖措辞，或重写后语句略生硬。
  4. 告警未落 cron/看板：需要上线后配置。
  5. PII：日志/指标可能包含客户消息片段；无自动保留/删除策略。
  6. agent1/agent2 offline：Email/WhatsApp 会停在团队队列，需要人工上线/认领。
  7. bridge 4100 暴露在局域网：建议防火墙限制，仅允许 LibreDesk/内网访问。

低

  1. KB/索引/sitemap 仍以手动脚本刷新为主。
  2. 无 A/B、无真实邮件 digest、无 WhatsApp 模板/媒体。
  3. 无多副本/跨机高可用。

12. 上线后待办

优先级 事项
P0 配置质量告警 cron + 确认邮件送达
P0 确认 agent1/agent2 上线流程和团队队列 SLA
P0 续期 WhatsApp token、固定公网域名
P1 Email/WhatsApp bridge AI 切流
P1 真实邮件 ingest + 索引
P1 商机币种 + productNeed 归一
P1 数据备份自动化
P2 告警看板、离线评测接 CI
P2 PII 保留/删除策略
P3 A/B 实验、WhatsApp 模板/媒体

13. 附录：关键配置

bridge 关键环境变量

LIBREDESK_BASE_URL
LIBREDESK_API_KEY
LIBREDESK_API_SECRET
LIBREDESK_WEBHOOK_SECRET
LIBREDESK_WEBHOOK_INBOX_IDS=1
LLM_BASE_URL / LLM_API_KEY / LLM_MODEL
RAG_PG_URL
EMB_BASE_URL / EMB_API_KEY / EMB_MODEL / EMB_DIM
SMTP_HOST / SMTP_PORT / SMTP_USER / SMTP_PASS / SMTP_FROM
TWENTY_BASE_URL / TWENTY_API_KEY

关键数据表

  • libredesk：conversations、messages、automation_rules、webhooks
  • bridge：bridge_ai_metrics、bridge_llm_cache、bridge_site_map_urls
  • products（旧 bridge 库）：kb_docs、kb_mail_docs

关键脚本

scripts/bootstrap.sh
scripts/rpc-tunnel.sh
scripts/public-https.sh
scripts/build-site-map.js
scripts/rebuild-kb-index.sh
scripts/e2e-widget-jwt.js
scripts/e2e-anon-otp.js
scripts/eval-offline.js
scripts/eval-live.js
scripts/quality-report.js
scripts/quality-alert.js

14. 变更记录

日期 变更 操作人
2026-10-23 初版上线文档 待填
Reference in New Issue View Git Blame Copy Permalink