265 lines
15 KiB
Markdown
265 lines
15 KiB
Markdown
# crm-ai 在 wangliang 工作区的部署记录
|
||
|
||
> 部署时间：2026-10-23 ｜ 部署位置：`/data/dev/wangliang/crm-ai` ｜ 代码版本：`main @ 1ae25f1`
|
||
>
|
||
> 本文件记录这套栈**实际跑成什么样**、和仓库默认配置差在哪、怎么运维、以及还缺哪些凭据。
|
||
> 环境相关的临时信息写在这里，通用约定见 `/data/dev/_shared/NOTES.md`。
|
||
|
||
## 1. 交付摘要
|
||
|
||
一套自包含的客服 + CRM 栈（与仓库 `docker-compose.yml` 一致，Compose 项目名 `crm-new`）：
|
||
|
||
| 组件 | 容器 | 宿主端口 | 状态 |
|
||
|---|---|---|---|
|
||
| LibreDesk v2.9.0-rc.10（客服工作台 + 内置 AI） | `crmnew-libredesk` | `9000` | ✅ healthy |
|
||
| Twenty CRM v2.30.1（server） | `crmnew-twenty-server` | `3100` | ✅ healthy |
|
||
| Twenty worker | `crmnew-twenty-worker` | — | ✅ running |
|
||
| bridge（业务工具 / RPC 集成） | `crmnew-bridge` | `4100` | ✅ healthy |
|
||
| PostgreSQL 18 + pgvector | `crmnew-postgres` | `127.0.0.1:5440` | ✅ healthy |
|
||
| Redis 8.8 | `crmnew-redis` | `127.0.0.1:6390` | ✅ healthy |
|
||
| IMAP ID 注入代理（163 专用） | `crmnew-imap-proxy` | `127.0.0.1:1993` | ✅ running |
|
||
|
||
数据卷：`crm-new_pg-data`、`crm-new_redis-data`、`crm-new_twenty-data`（`docker compose down` 不会删）。
|
||
|
||
## 2. 访问地址与账号
|
||
|
||
| 入口 | 地址 | 账号 |
|
||
|---|---|---|
|
||
| LibreDesk（工作台 / 帮助中心 / widget） | https://wangliang-crm.dev.gaia888.com | `System` ／密码见下方命令 |
|
||
| Twenty CRM | https://wangliang-twenty.dev.gaia888.com | `admin@yehwang.com` ／密码见下方命令 |
|
||
| bridge（调试/集成） | https://wangliang-crmbridge.dev.gaia888.com | 请求头 `X-Tools-Key`，值见下方命令 |
|
||
|
||
```bash
|
||
cd /data/dev/wangliang/crm-ai
|
||
grep '^LIBREDESK_SYSTEM_USER_PASSWORD=' .env # LibreDesk System 密码
|
||
grep '^TWENTY_ADMIN_PASSWORD=' .env # Twenty 管理员密码
|
||
grep '^TOOLS_SHARED_KEY=' .env # bridge 工具密钥
|
||
```
|
||
|
||
> 密钥只存在 `.env`（600）与 `libredesk/config/config.toml`（600），两者都已被 `.gitignore` 排除，**不要提交**。
|
||
|
||
## 3. 与仓库默认配置的差异（重要）
|
||
|
||
| 项 | 仓库默认 | 本环境 | 原因 |
|
||
|---|---|---|---|
|
||
| `LIBREDESK_IMAGE` | `libredesk/libredesk:v2.9.0-rc.10` | `libredesk/libredesk:v2.9.0-rc.10-**arm64**` | 宿主是 ARM64，`v2.9.0-rc.10` 只有 amd64；官方另发了 `-arm64` 同版本 tag，实测原生 `linux/arm64` 运行 |
|
||
| `LIBREDESK_BASE_URL` | `http://localhost:9000` | `https://wangliang-crm.dev.gaia888.com` | 走宿主 nginx 的 HTTPS |
|
||
| `TWENTY_SERVER_URL` | `http://192.168.31.61:3100` | `https://wangliang-twenty.dev.gaia888.com` | 前端 `REACT_APP_SERVER_BASE_URL` 用的就是它（已核对页面内联配置） |
|
||
| `RECOMMEND_URL` | 测试服地址 | `jsonrpc://wangliang-dev:9503` | 用 **本工作区** 的 product-service |
|
||
| `ORDER_API_URL` | 测试服地址 | `jsonrpc://wangliang-dev:9505` | trading-service |
|
||
| `INVENTORY_API_URL` | 测试服地址 | `jsonrpc://wangliang-dev:9509` | eta-service |
|
||
| `MEMBER_RPC_URL` | 测试服地址 | `jsonrpc://wangliang-dev:9506` | member-service |
|
||
| `IDENTITY_DEV_MODE` | `false` | `true` | dev 环境方便 widget 联调；**上生产前改回 `false`** |
|
||
| `PRODUCT_TIMEOUT_MS` | 未透传（bridge 默认 15s） | `30000`（compose 增加透传） | 冷门长查询会偶发 >15s，超时会降级成无价格的站点地图结果，模型易编价 |
|
||
| `public-gateway` / `cloudflared` | compose 里默认启动 | **未启动** | 已有宿主 nginx 直出 HTTPS，不需要 Cloudflare 临时隧道 |
|
||
| bridge 网络 | 只挂 `crm-new_default` | 额外接入 `spug-net` | 直连 `wangliang-dev:9503/9505/9506/9509`，去掉对宿主 socat 转发的依赖 |
|
||
|
||
RPC 走 **容器网络直连**：compose 把 `bridge` 同时接入外部网络 `spug-net`（与 `wangliang-dev` 同网络），
|
||
直接按容器名解析到 `wangliang-dev`，不再依赖宿主 `socat` 24503-24509 转发。容器重建后 DNS 名不变，
|
||
比 socat 需要按 IP 重建更稳。宿主侧的 `conf/dev/rpc-forward.sh` 仍保留（供宿主/不在 spug-net 的容器使用），
|
||
但本栈已不依赖它。
|
||
|
||
## 4. 已完成初始化
|
||
|
||
### LibreDesk
|
||
- `System` 账号可登录（浏览器实测落到 `/inboxes/assigned`）。
|
||
- **AI Provider 已配置**：DashScope `qwen-plus-latest`（completion）+ `text-embedding-v4` 1024 维（embedding），
|
||
`configure-ai.js` 的两项连通性测试均通过。密钥只存在 LibreDesk 库内与 `.env`（600），未写入文档。
|
||
- 助理指令已加固（见第 9 节）：`search_products` 必须用 2-5 个词的关键词、不得编造价格/商品，`price=null` 时明确说“暂不可用”。
|
||
- `app.root_url = https://wangliang-crm.dev.gaia888.com`（`scripts/set-public-url.js`）。
|
||
- 10 个 bridge 工具已注册（`scripts/register-tools.js`）：`search_products / search_orders / search_inventory /
|
||
search_kb / search_email_history / collect_info / send_verification_code / verify_email_code / handoff_to_human /
|
||
create_opportunity`。
|
||
- 默认助理 `Yehwang Assistant`（#1，10 个工具、引用与 handoff 开启）。
|
||
- Live chat Inbox `Website`（#1，uuid `ad25d7a4-722d-4561-aebf-9d8f60952d09`）。
|
||
- Automation：新会话自动分配给助理（#1，enabled）。
|
||
|
||
### Twenty
|
||
- Workspace `Yehwang`：`2ff5a56b-95d8-40e1-85cf-529ad3a70ed7`（`ACTIVE`）。
|
||
- API key 已生成并写入 `.env` 的 `TWENTY_API_KEY`；GraphQL `companies` 查询验证通过。
|
||
- 浏览器实测可登录，首次进入 `/install-apps`（Twenty 的新工作区引导页，正常现象）。
|
||
|
||
### bridge
|
||
- `/healthz` 正常，10 个工具就绪。
|
||
- 实测 `search_products` 直接命中**本工作区真实商品数据**（如 `Stainless Steel Y-Chain Necklace` / `$6.73` /
|
||
`product_id=11079`），说明 `wangliang-dev:9503` 的 JSONRPC 直连链路是通的（工具调用 925ms，source=catalog）。
|
||
- `search_orders` 未验证身份时按设计返回 `verification_required`。
|
||
|
||
## 5. 运维命令
|
||
|
||
```bash
|
||
cd /data/dev/wangliang/crm-ai
|
||
|
||
docker compose ps # 状态
|
||
docker compose logs -f --tail=100 libredesk
|
||
docker compose logs -f --tail=100 twenty-server
|
||
docker compose logs -f --tail=100 bridge
|
||
|
||
docker compose start # 启动已有容器
|
||
docker compose stop # 停止（保留数据）
|
||
docker compose restart libredesk # 重启单个服务
|
||
|
||
# 改 .env 后（bridge 必做；libredesk 也要重建才会读到新 env）
|
||
docker compose up -d --force-recreate bridge
|
||
docker compose up -d --force-recreate libredesk
|
||
|
||
# 改 LibreDesk 配置模板后
|
||
node scripts/render-config.js && docker compose up -d --force-recreate libredesk
|
||
|
||
# 备份（DB + Twenty 自带数据都在 PG 里；卷里是上传文件）
|
||
mkdir -p backups
|
||
docker exec crmnew-postgres pg_dump -U crmnew -Fc libredesk > backups/libredesk-$(date +%F).dump
|
||
docker exec crmnew-postgres pg_dump -U crmnew -Fc twenty > backups/twenty-$(date +%F).dump
|
||
docker exec crmnew-postgres pg_dump -U crmnew -Fc bridge > backups/bridge-$(date +%F).dump
|
||
|
||
# 恢复
|
||
docker exec -i crmnew-postgres pg_restore -U crmnew -d libredesk --clean --if-exists < backups/libredesk-YYYY-MM-DD.dump
|
||
```
|
||
|
||
所有容器都是 `restart: unless-stopped`，Docker 守护进程重启后会自己拉起来。
|
||
|
||
## 6. 域名反向代理
|
||
|
||
宿主 nginx 新增了**独立**配置文件 `/etc/nginx/conf.d/zz-wangliang-crm.conf`：
|
||
|
||
- `wangliang-crm.dev.gaia888.com` → `127.0.0.1:9000`
|
||
- `wangliang-twenty.dev.gaia888.com` → `127.0.0.1:3100`
|
||
- `wangliang-crmbridge.dev.gaia888.com` → `127.0.0.1:4100`
|
||
- 80 → 308 跳 HTTPS；证书复用 `*.dev.gaia888.com`（通配一级域名，三个域名都被覆盖）。
|
||
|
||
它**没有改** `devstack.conf` 的 map/正则，因此不影响其它工作区。
|
||
|
||
改完后的自检 / 重载（query 用户没有 root，用容器代跑）：
|
||
|
||
```bash
|
||
docker run --rm --privileged --pid=host redis:7-alpine \
|
||
sh -c 'nsenter -t 1 -m -u -i -n -p /usr/sbin/nginx -t'
|
||
docker run --rm --privileged --pid=host redis:7-alpine \
|
||
sh -c 'nsenter -t 1 -m -u -i -n -p /usr/sbin/nginx -s reload'
|
||
```
|
||
|
||
回滚（只需删掉这个文件并 reload，其它站点不受影响）：
|
||
|
||
```bash
|
||
docker run --rm -v /etc/nginx/conf.d:/c redis:7-alpine rm -f /c/zz-wangliang-crm.conf
|
||
# 再执行上面的 nginx -t / -s reload
|
||
```
|
||
|
||
## 7. 尚未配置（需要真实凭据，不是代码问题）
|
||
|
||
| 项 | 现状 | 补法 |
|
||
|---|---|---|
|
||
| ~~AI Provider（DashScope）~~ | ✅ **已配置**（qwen-plus-latest / text-embedding-v4），端到端已验证 | 换 key：`DASHSCOPE_API_KEY=sk-xxx node scripts/configure-ai.js` |
|
||
| **SMTP / 163 邮件** | `SMTP_*` 为空，OTP 与邮件渠道不可用 | 填 `.env` 后 `node scripts/configure-email.js` + `node scripts/add-email-inbox.js` |
|
||
| **知识库 RAG（search_kb）** | 无 `RAG_PG_URL`，工具返回 503；旧 KB 数据源本机不存在（见第 10 节） | 提供旧 `products.kb_docs` dump 或 `customer-service-kb/*.md` 后导入 |
|
||
| **WhatsApp 渠道** | 无 Meta 凭据 | 填 `WA_*` 后 `scripts/add-whatsapp-inbox.js`；需要公网回调（本栈已有 HTTPS，可不用 cloudflared） |
|
||
| **public-gateway / cloudflared** | 未启动 | 需要 Cloudflare 临时隧道时再 `docker compose up -d public-gateway cloudflared` |
|
||
|
||
> `IDENTITY_DEV_MODE=true` 只适合 dev；上生产前改回 `false`。
|
||
|
||
## 8. 验证记录（2026-10-23）
|
||
|
||
```text
|
||
$ curl -o /dev/null -w '%{http_code}' https://wangliang-crm.dev.gaia888.com/health # 200
|
||
$ curl -o /dev/null -w '%{http_code}' https://wangliang-twenty.dev.gaia888.com/healthz # 200
|
||
$ curl -o /dev/null -w '%{http_code}' https://wangliang-crmbridge.dev.gaia888.com/healthz # 200
|
||
$ curl -s https://wangliang-crmbridge.dev.gaia888.com/healthz
|
||
{"ok":true,"service":"crm-tools","tools":[10 个],"sites":["www","us","eu"]}
|
||
$ curl -s -X POST http://127.0.0.1:4100/tools/search_products -H 'X-Tools-Key: …' -d '{"query":"stainless steel necklace"}'
|
||
{"ok":true,"products":[{"name":"Stainless Steel Y-Chain Necklace","price":"$6.73","product_id":11079}]}
|
||
```
|
||
|
||
AI 端到端（`node scripts/e2e-widget.js "Show me 3 stainless steel necklaces with prices and stock."`）：
|
||
助手调用 `search_products`（612ms，source=catalog）并返回真实数据 —— Y-Chain `$6.73`/237、Necklace `$6.85`/186、
|
||
Necklace Star `$5.70`/110，与 RPC 直查一致（首次调试时的编价问题见第 9 节）。
|
||
|
||
浏览器（Playwright 真 Chrome，1440×900）：
|
||
|
||
- LibreDesk 登录成功 → `/inboxes/assigned`（截图 `docs/screenshots/wangliang-libredesk-inbox.png`）
|
||
- Twenty 登录成功 → `/install-apps` 引导页（截图 `docs/screenshots/wangliang-twenty-onboarding.png`）
|
||
- 回归：`wangliang-www` 仍 200，`wangliang-agent` 仍 302（宿主 nginx 未被改坏）
|
||
|
||
资源占用：约 1.9 GB 内存（Twenty worker 约 1.0 GB + server 0.6 GB + PG/Redis/bridge/LibreDesk 约 0.3 GB）。
|
||
|
||
## 9. 上线当天修的一个 AI 质量问题（编造价格）
|
||
|
||
首次用 `e2e-widget.js` 问“3 条不锈钢项链的价格和库存”时，助手返回了三款**不存在的商品**和虚高价格。
|
||
排查（临时把 LibreDesk `log_level` 调到 `debug`）定位到：
|
||
|
||
1. 模型把用户**整句**（含 "under 10 dollars" 等）直接当成 `search_products` 的 query；
|
||
2. 这类长查询偶发 >15s（bridge 的 `PRODUCT_TIMEOUT_MS` 默认 15s），超时后走降级：只返回名字、`price=null`；
|
||
3. 模型面对 `price=null` 时自行编了价格（LibreDesk 的 guardrails 只是提示词，不是硬拦截）。
|
||
|
||
修复（已落地并验证）：
|
||
|
||
- `docker-compose.yml` 给 bridge 透传 `PRODUCT_TIMEOUT_MS`，`.env` 设为 `30000`；
|
||
- 助理的 instructions 追加严格规则（`scripts/setup-defaults.js` 同步）：短关键词查询、工具输出是唯一事实来源、
|
||
`price=null`/`stock=null` 时必须说“暂不可用”并建议转人工，禁止估算/换算币种。
|
||
- 复测：同一条问题，工具调用 612ms 返回真实商品，回复价格/库存与 RPC 完全一致。
|
||
|
||
⚠️ 仍存在的结构性问题：LibreDesk 内置 AI 的回复**不经过** bridge 的 `输出护栏`（output_guard）。
|
||
若后续要硬性拦截虚假价格/链接，需要走 bridge 自己的 agent 路径，或在 LibreDesk 侧加后置校验。
|
||
|
||
验证完已把 `log_level` 恢复为 `info`。
|
||
|
||
## 10. 数据面初始化（5.1 KB / 5.2 sitemap / 5.3 质量表）
|
||
|
||
### 5.3 质量表 ✅
|
||
`node scripts/quality-report.js 1`：自动建表成功。
|
||
|
||
```text
|
||
table_exists = bridge_ai_metrics；当前 rows=0
|
||
{"summary":{"runs":0,"errors":0,...},"tools":[],"hours":1}
|
||
```
|
||
|
||
⚠️ 表建好了，但**会一直是 0 行**：`bridge_ai_metrics` 只在 bridge 自己的 agent 路径（webhook 编排）里写入，
|
||
而本栈的 AI 回复走的是 LibreDesk 内置 assistant。要让质量报表有数据，需要改用 bridge agent 或另接埋点。
|
||
|
||
### 5.2 全量 sitemap ✅
|
||
官网 `sitemap.xml` 受阿里云 WAF 的 JS 挑战保护（直接 fetch 返回 4KB 挑战 HTML、0 个 `<loc>`）。
|
||
处理：用真 Chrome（Playwright）过挑战后抓取，缓存到 `var/sitemap-{www,us}.xml`（已 gitignore），
|
||
并给 `scripts/build-site-map.js` 增加本地 XML 回退（`var/sitemap-<site>.xml` 或 `SITEMAP_XML_<SITE>`）。
|
||
|
||
```text
|
||
[site-map] www: total=32710, products=32070, nav=640
|
||
[site-map] us: total=22644, products=22324, nav=320
|
||
```
|
||
|
||
表 `bridge_site_map_urls` 已核对：
|
||
|
||
```text
|
||
site | total | products
|
||
us | 22644 | 22324
|
||
www | 32710 | 32070
|
||
```
|
||
|
||
刷新方式（sitemap 会变）：先用浏览器重新抓 `var/sitemap-{www,us}.xml`，再 `node scripts/build-site-map.js www us`。
|
||
直接跑脚本在 WAF 下会明确报错「返回 0 个 <loc>」，不会静默写空表。
|
||
|
||
### 5.1 旧 KB（products.kb_docs）❌ 本机无数据源
|
||
|
||
按清单实际执行的结果：
|
||
|
||
```text
|
||
$ node scripts/upgrade-kb-schema.js
|
||
[upgrade-kb-schema] password authentication failed for user "postgres"
|
||
$ bash scripts/rebuild-kb-index.sh
|
||
Error response from daemon: No such container: crm-postgres
|
||
$ ls /home/dev/code/crm/crm-ai-demo/customer-service-kb
|
||
No such file or directory
|
||
$ docker ps -a | grep -E '^crm-(postgres|bridge)$'
|
||
（无）
|
||
```
|
||
|
||
原因：这两个脚本是为**旧栈**写的 —— `products.kb_docs` 在旧 `crm-postgres` 里，
|
||
`rebuild-kb-index.sh` 还会 `docker exec crm-bridge` 调旧 bridge 的 `faq/kbIndexer`（新仓库已没有这段代码）。
|
||
本工作区是全新栈：宿主 PG 5432 只有 `postgres/storefront` 两个库，没有 `products`；也没有旧容器的数据卷。
|
||
|
||
要补齐需要**数据源**，二选一：
|
||
|
||
1. 旧测试服导出 `products.kb_docs`：`pg_dump -t kb_docs products > kb_docs.sql`；
|
||
2. 或直接给 `customer-service-kb/*.md`（9 个文件，108 篇文章的来源）。
|
||
|
||
拿到后我按新栈方式接入（推荐导入 LibreDesk 帮助中心，AI 原生 RAG + 引用；旧的 `search_kb` 可保留为兜底）。
|
||
在此之前，商品/库存/订单/商机等 9 个工具不受影响，只有 `search_kb` 返回 503。
|