159 lines
6.8 KiB
Markdown
159 lines
6.8 KiB
Markdown
# libredesk（crm-new/libredesk）
|
||
|
||
位于 `/home/dev/code/crm-new/libredesk` 的 **LibreDesk 版 CRM 客服栈**，与旧项目 `/home/dev/code/crm/crm-ai-demo` 完全隔离（独立目录、独立 git、独立 Postgres/Redis、独立端口）。
|
||
|
||
- **定位**：验证「LibreDesk 作为客服平台 + 内置 AI Assistant + 外部业务工具」能否替代现有 Chatwoot + bridge 架构。
|
||
- **当前阶段**：POC 骨架（可启动、工具服务可跑、含单元测试），尚未接入真实 widget 和生产数据。
|
||
- **旧系统不受影响**：`crm-ai-demo` 仍在 3000/3001/4000 端口运行。
|
||
|
||
## 当前状态（2026-10-21）
|
||
|
||
| 项 | 状态 |
|
||
|---|---|
|
||
| 目录/配置/脚本脚手架 | ✅ 完成 |
|
||
| crm-tools 服务（4 工具 + 鉴权 + 验证门控） | ✅ 单测 18/18 通过，本机 :4010 可运行 |
|
||
| config.toml 渲染 / compose 校验 | ✅ 通过 |
|
||
| LibreDesk 容器 | ✅ 运行中（**v2.9.0-rc.10**，health 200）；Postgres 18 / Redis 健康 |
|
||
| 后台 AI/工具/助手配置 | ⏳ 登录 `http://localhost:9000` 后按 `docs/libredesk-setup.md` 执行 |
|
||
|
||
> 当前运行 **v2.9.0-rc.10**：渠道已包含 `email / livechat / whatsapp`，WhatsApp 表已迁移完成。
|
||
> RC 属于预发布版本，功能可用但生产使用前需评估稳定性（回滚方法见「镜像拉取」）。
|
||
|
||
## 架构
|
||
|
||
```
|
||
访客 ──► LibreDesk Live Chat Widget (:9000)
|
||
│
|
||
▼
|
||
LibreDesk AI Assistant ──HTTP tool calls──► crm-tools (:4010)
|
||
（snippets 向量检索 / 内置 OTP 验证） │
|
||
├──► 商品推荐 RPC (recommend)
|
||
├──► 订单 RPC (trading-service)
|
||
├──► 库存/ETA RPC (eta-service)
|
||
└──► Twenty CRM GraphQL (商机/备注/任务)
|
||
```
|
||
|
||
关键设计：**业务数据与身份验证不放进 LibreDesk 代码里**，而是通过它的自定义 HTTP 工具回调 `crm-tools`；工具服务二次校验 `X-Libredesk-Contact-Verified`，不信任模型参数里的邮箱。
|
||
|
||
详见 [docs/architecture.md](docs/architecture.md)。
|
||
|
||
## 目录
|
||
|
||
```
|
||
crm-new/libredesk/
|
||
├── docker-compose.yml # LibreDesk + 独立 Postgres(5433) + Redis(6380)
|
||
├── .env.example # 环境变量模板（bootstrap 自动生成 .env）
|
||
├── config/
|
||
│ └── config.toml.example # LibreDesk 配置模板（渲染成 config.toml，不入库）
|
||
├── scripts/
|
||
│ ├── bootstrap.sh # 生成密钥 + 渲染配置 + 启动 LibreDesk
|
||
│ ├── start-tools.sh # 宿主机启动 tools 服务
|
||
│ ├── render-config.js # config.toml 渲染
|
||
│ ├── register-tools.js # 把工具注册进 LibreDesk（可选）
|
||
│ └── smoke.sh # 冒烟测试
|
||
├── services/tools/ # 业务工具服务（Node 20+，零外部依赖）
|
||
│ ├── src/
|
||
│ │ ├── server.js # HTTP 入口 + 鉴权 + 验证门控
|
||
│ │ ├── tools.js # 4 个工具：商品/订单/库存/建商机
|
||
│ │ ├── twenty.js # Twenty GraphQL 客户端
|
||
│ │ ├── rpc.js # JSONRPC-TCP 客户端（Hyperf 协议）
|
||
│ │ ├── config.js / auth.js / errors.js
|
||
│ └── test/ # node:test 单元测试
|
||
├── docs/
|
||
│ ├── architecture.md # 架构与数据流
|
||
│ ├── libredesk-setup.md # 后台配置步骤（AI/工具/助手/自动化/Widget）
|
||
│ ├── api-mapping.md # Chatwoot → LibreDesk 接口/事件/字段对照
|
||
│ └── migration-plan.md # 6 层拆分、方案 A/B/C、代码存废清单
|
||
├── deploy/nginx.conf.example
|
||
└── uploads/ # LibreDesk 上传目录（运行时）
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
> 网络提示：本机可直连 Docker Hub。镜像直接使用 `libredesk/libredesk`、
|
||
> `pgvector/pgvector`、`redis`、`twentycrm/twenty`；如网络受限可在 Docker daemon
|
||
> 配 registry mirror。详见文末「镜像拉取」一节。
|
||
|
||
```bash
|
||
cd /home/dev/code/crm-new/libredesk
|
||
|
||
# 1) 启动 LibreDesk（自动生成 .env / config.toml，首次拉镜像）
|
||
bash scripts/bootstrap.sh
|
||
|
||
# 2) 另开终端，启动工具服务 :4010
|
||
bash scripts/start-tools.sh
|
||
|
||
# 3) 按 docs/libredesk-setup.md 配置 AI Provider / Inbox
|
||
# 然后在 Admin → Teammates → System 生成 API key，填入 .env
|
||
|
||
# 4) 自动注册 4 个 AI 工具（失败也可按文档手工创建）
|
||
node scripts/register-tools.js
|
||
|
||
# 5) 冒烟
|
||
bash scripts/smoke.sh
|
||
```
|
||
|
||
| 组件 | 地址 | 说明 |
|
||
|---|---|---|
|
||
| LibreDesk | http://localhost:9000 | `System` + bootstrap 生成的密码 |
|
||
| crm-tools | http://localhost:4010 | `/healthz`、`/tools/manifest`、`/tools/<name>` |
|
||
| Postgres | localhost:5433 | 独立实例，库 `libredesk` |
|
||
| Redis | localhost:6380 | 独立实例 |
|
||
|
||
## 工具清单
|
||
|
||
| 工具 | 需要验证 | 作用 |
|
||
|---|---|---|
|
||
| `search_products` | 否 | 商品关键词搜索（recommend RPC） |
|
||
| `search_orders` | **是** | 订单/物流查询，邮箱强制取自已验证身份头 |
|
||
| `search_inventory` | 否 | SKU 实时库存 + ETA |
|
||
| `create_opportunity` | **是** | Twenty 建商机 + 聊天摘要备注 + 3 天跟进任务，按邮箱去重 |
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
cd services/tools && npm test
|
||
```
|
||
|
||
覆盖：地址解析、鉴权 fail-closed、验证门控、邮箱作用域/IDOR 防护、商机去重。
|
||
|
||
## 本阶段边界（未做）
|
||
|
||
- 未接入真实网站 widget（JWT 签发仍是下一步）
|
||
- 未做 Chatwoot → LibreDesk 数据迁移（当前旧库仅 2 条会话，可忽略）
|
||
- 未接入观测/评估/飞轮（需要时按 [docs/migration-plan.md](docs/migration-plan.md) 的 L6 保留 bridge）
|
||
- WhatsApp 需 v2.9 预发布版（见 setup 文档最后一节）
|
||
|
||
## 镜像拉取
|
||
|
||
本机可直连 Docker Hub，直接拉取：
|
||
|
||
```bash
|
||
docker pull libredesk/libredesk:v2.9.0-rc.10
|
||
```
|
||
|
||
`.env`：
|
||
|
||
```ini
|
||
LIBREDESK_IMAGE=libredesk/libredesk:v2.9.0-rc.10
|
||
```
|
||
|
||
### 回滚到稳定版 v2.8.0
|
||
|
||
```bash
|
||
sed -i 's#^LIBREDESK_IMAGE=.*#LIBREDESK_IMAGE=libredesk/libredesk:latest#' .env
|
||
docker compose up -d --force-recreate app # 跨版本回退需用备份库，见下
|
||
```
|
||
|
||
## 与旧系统的关系
|
||
|
||
| | 旧栈 `crm-ai-demo` | 新栈 `crm-new/libredesk` |
|
||
|---|---|---|
|
||
| 客服平台 | Chatwoot 4.16（Rails） | LibreDesk（Go 单二进制） |
|
||
| AI 编排 | bridge 自研 agent loop | LibreDesk AI Assistant（POC 目标） |
|
||
| 业务工具 | bridge 内置 | 独立 `services/tools` |
|
||
| 数据 | crm-postgres:5432 | 独立 postgres:5433 |
|
||
| 端口 | 3000/3001/4000 | 9000/4010 |
|
||
|
||
两套可以并行跑，方便同一批问题做 A/B 对比。
|