Files

T

wangliang 3b5314b2a5 chore(libredesk): 升级到 v2.9.0

2026-10-26 13:12:38 +08:00

10 KiB

Raw Permalink Blame History

LibreDesk 后台配置步骤

面向 crm-new 全栈（方案 B：LibreDesk 内置 AI 回复客户）。本栈已通过 scripts/setup-defaults.js 自动建好 Inbox / Assistant / Automation；本文用于手工核对或重建。登录：用户 System，密码见 .env 的 LIBREDESK_SYSTEM_USER_PASSWORD。

0. 前置检查

bash scripts/bootstrap.sh          # LibreDesk 已启动
bash scripts/start-tools.sh        # 另开终端，tools 服务 :4010
curl -s http://localhost:4100/healthz

1. AI Provider（必须先配）

Admin → AI → Providers，两个 provider 都要配（LibreDesk 要求 OpenAI 兼容端点）：

项	Completion	Embedding
Base URL	`https://dashscope.aliyuncs.com/compatible-mode/v1`	同左
API Key	DashScope key（与旧项目 `kb.config.json` 同一个）	同左
Model	`qwen-plus-latest`	`text-embedding-v4`
Dimensions	—	1024（必须与模型输出一致，否则报维度不匹配）
Temperature	0.3	—
Max tokens	800	—

点 Test connection 两个都通过再继续。改 embedding 模型/维度会自动重新嵌入全部 snippets。

成本上限在 config/config.toml 的 [ai_agent]：max_steps、max_history_messages、worker_count。

2. 知识库（帮助中心文章）

本栈已把旧 customer-service-kb 导入为帮助中心文章（而不是 snippets），原因：只有文章能被 AI 引用（[[cite:id]]），并且同时进入帮助中心站内搜索。

公开地址：http://localhost:9000/hc/yehwang-help/en（1 个帮助中心 / 9 个 collection / 108 篇文章，全部 published + ai_enabled）。

重新导入（幂等）：

cd /home/dev/code/crm-new
node scripts/import-kb-helpcenter.js --dry-run   # 只解析
node scripts/import-kb-helpcenter.js             # 登录 System 并导入

以下为 LibreDesk 原生 snippets 的用法（内部/敏感内容才用）：

手工：一条 Q&A 一个 snippet，正文写完整答案（不要写片段）
Import from URL：抓取官网 FAQ 页面
API 批量导入（迁移旧 KB 时用）：

curl -X POST http://localhost:9000/api/v1/ai/snippets \
  -H "Authorization: token ${LIBREDESK_API_KEY}:${LIBREDESK_API_SECRET}" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Minimum order","content":"The minimum order value is €30.","enabled":true}'

迁移建议：旧 customer-service-kb/*.md 按 ### Q: 切块，标题用问题，正文用答案，逐条 POST。Import from URL 走 POST /api/v1/ai/snippets/import-url。

RAG 差异：LibreDesk 是 纯向量 top-k，没有旧 bridge 的「向量+全文+RRF+rerank+翻译兜底」。EU 语种召回需要用真实问题抽检。

3. 注册业务工具

方式 A：自动（推荐）

Admin → Teammates → System → API Key 生成 key/secret，填进 .env：
```
LIBREDESK_API_KEY=...
LIBREDESK_API_SECRET=...
```
执行：
```
node scripts/register-tools.js
```

方式 B：手工

Admin → AI → Tools → New tool，4 个工具按下面填：

字段	search_products	search_orders	search_inventory	create_opportunity
URL	`http://bridge:4100/tools/search_products`	`.../search_orders`	`.../search_inventory`	`.../create_opportunity`
Method	POST	POST	POST	POST
Header	`X-Tools-Key: <TOOLS_SHARED_KEY>`	同	同	同
Parameters	见 `GET /tools/manifest`	同	同	同
Require verified contact	否	是	否	是
Copilot / Generate reply	开	开	开	开
Require agent approval	否	否	否	否

GET http://localhost:4100/tools/manifest（带 X-Tools-Key）会输出每个工具的完整 JSON Schema，可直接复制。

4. 创建 AI Assistant

Admin → AI → Assistants → New assistant：

项	建议值
Name	`Yehwang Assistant`
Tone / Length	Friendly / Concise
Languages	English, Dutch, German, French, Spanish, Italian（留空=跟随客户）
Max turns	8–10
Fallback team	`Support`（先建团队）
Offer handoff	开
Tools	勾选上一步的 4 个工具

Instructions 草稿（可直接改）：

You are the Yehwang B2B customer assistant for stainless-steel jewelry wholesale.
- Always reply in the customer's language.
- For product questions call search_products; never invent catalog items.
- For order questions call search_orders. If the result says verification is required,
  ask the customer to verify their email with the one-time code, then retry.
- For stock questions call search_inventory with the SKU digits.
- When you have company + contact name + product/need, call create_opportunity once.
- Never quote prices, discounts or stock that did not come from a tool result.
- If you cannot help or the customer asks for a human, hand off to the Support team.

Guardrails：

Never reveal another customer's data. Never promise discounts above the published tiers.
Never create an opportunity before the contact is verified.

AI Assistant 目前是 beta，官方建议先在低流量 inbox 验证。

5. 自动路由（关键）

Assistant 只有被分配给会话才会回复。配置：

Admin → Automations → New rule

触发：new_conversation
条件：inbox = Live chat（如需只处理工作时间，再加 business hours 条件）
动作：assign_user → Yehwang Assistant

可选第二条规则：conversation_update + status = Resolved → 发送 CSAT。

人工一旦在会话里回复，assistant 会自动 handoff 并取消分配。

Admin → Inboxes → New inbox → Live chat
- Name：Website
- Brand / Website URL：https://www.yehwang.com
Security 标签：生成 widget Secret key（用于签 JWT，绝不能放前端）
Installation 标签复制 snippet：

<script>
  window.LibredeskSettings = {
    baseURL: 'http://localhost:9000',
    inboxID: 'YOUR_INBOX_UUID'
  };
</script>
<script async src="http://localhost:9000/widget.js"></script>

登录用户身份锚定（已实现）

bridge 提供 POST /identity：站点 JWT → member RPC 取邮箱 → 用 inbox secret 签 LibreDesk widget JWT。本地 POC 也可用 IDENTITY_DEV_MODE=true 直接传 email 生成。前端拿到 userJWT 后传给 widget。

原始说明（LibreDesk 侧）

已在网站登录的客户，服务端用 inbox Secret 签 HS256 JWT 传给 userJWT：

// 服务端（Node 示例，密钥只在服务端）
const payload = {
  external_user_id: String(user.id),      // 与旧栈 yw_uid 对齐
  email: user.email,                       // 这才是可信邮箱
  first_name: user.firstName,
  last_name: user.lastName,
  contact_custom_attributes: { site: 'www', locale: user.locale },
  exp: Math.floor(Date.now() / 1000) + 3600
};
// HS256(payload, inboxSecret) → window.LibredeskSettings.userJWT

多站点（www / US）建两个 livechat inbox，各自 widget + secret；联系人按 email 全局共享，注意隐私口径。

参考 us-site/ai-snippet.js（旧栈 Chatwoot 版）需要改写的点：$chatwoot.setUser → userJWT，setCustomAttributes → contact_custom_attributes。

7. Email Inbox（可选）

Admin → Inboxes → New inbox → Other provider：

项	值
IMAP	`imap.163.com:993`，SSL/TLS
SMTP	`smtp.163.com:465`，SSL
用户名/密码	163 邮箱 + 授权码
Scan interval	`5m`（默认）

接完后旧桥的 bridge/mail/（IMAP 轮询 + 自动回复）可以退役；邮件摘要改为定时调 LibreDesk 报表 API。

8. WhatsApp（v2.9.0 已可用）

版本现状：本套已运行 v2.9.0 正式版（2026-10-22 发布，2026-10-26 从 rc.10 升级），channels 枚举为 email / livechat / whatsapp，whatsapp_templates 表已就绪。升级前已 pg_dump 备份；本次无 DB migration，回滚见 docs/runbook.md「回滚」。

Meta 侧准备：Business Account、WABA ID、Phone Number ID、Permanent Access Token、App Secret、Webhook Verify Token
Admin → Inboxes → New inbox → WhatsApp，填上述凭据
Meta App 的 Webhook 指向 https://你的域名/webhooks/whatsapp（以实际路由为准），订阅 messages
模板：whatsapp_templates 表 + 后台模板管理；24 小时窗口外的主动消息必须用已审核模板
AI 对 WhatsApp 的支持文档未覆盖（文档只写 email + live chat），需实测 assistant 是否在 WhatsApp 会话触发

切换镜像：.env 里改 LIBREDESK_IMAGE 后 docker compose up -d --force-recreate libredesk；升级前先 pg_dump 备份，并记录当前镜像 digest 便于回滚。

9. 验收清单

Admin → AI → Providers 两个 Test connection 通过
Snippets 至少 10 条，问一个政策问题能引用
Tools 4 个，crm-tools 日志能看到调用
Assistant 已建 + automation 已分配
widget 能开聊，收到 AI 回复
未验证时问订单 → AI 引导验证；验证后能查单
说“我要人工” → handoff 到 Support 团队
curl -s http://localhost:4100/healthz 正常

10. 常见问题

现象	原因	处理
登录后立刻掉登录	用 http 访问但 cookie 是 Secure	`config.toml` 里 `disable_secure_cookies = true`
容器反复重启，日志提示 `system user password is not strong`	System 密码不满足规则（10–72 位，含大小写+数字+特殊字符）	改 `.env` 的 `LIBREDESK_SYSTEM_USER_PASSWORD`，再 `docker compose up -d --force-recreate app`
工具 401	`X-Tools-Key` 与 `TOOLS_SHARED_KEY` 不一致	核对 `.env` 和工具 Header
工具 403 verification_required	未验证联系人 / 工具未开验证	先走 OTP 验证，或该工具不需要验证则关掉 `requires_verification`
工具 503 tools_key_not_configured	tools 服务未配置共享密钥	重启 `start-tools.sh`
AI 不回复	会话未分配给 assistant / 会话不是 open	检查 automation 规则与状态
embedding 维度报错	dimensions 与模型不符	`text-embedding-v4` 用 1024
容器访问不了 tools	`host.docker.internal` 未解析	compose 已配 `extra_hosts`；Linux 需 Docker 20.10+

10 KiB Raw Permalink Blame History Unescape Escape