crm-ai/docs/runbook.md

运维手册（crm-new）

启动 / 停止

cd /home/dev/code/crm-new

# 启动（生成 .env / 渲染配置 / 构建 bridge / 等健康）
bash scripts/bootstrap.sh

# 只启动，不重新生成
docker compose up -d

# 停止（保留数据）
docker compose down

# 停止并删除数据（危险：会清空 LibreDesk/Twenty/业务库）
# docker compose down -v

状态与日志

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

# 健康
curl -s http://localhost:9000/health
curl -s http://localhost:3100/healthz
curl -s http://localhost:4100/healthz

内容与 AI 配置脚本

# 导入/更新知识库（帮助中心文章，幂等）
node scripts/import-kb-helpcenter.js --dry-run
node scripts/import-kb-helpcenter.js

# 配置 DashScope（Completion + Embedding，自动触发重建向量）
node scripts/configure-ai.js

# 验证 RAG + 引用（创建临时助手跑 preview 后自动删除）
node scripts/verify-rag.js "What is the minimum order value?"

# 注册 4 个业务工具
node scripts/register-tools.js

# 创建/更新默认 Inbox + Assistant + Automation（幂等）
node scripts/setup-defaults.js

# Twenty：创建初始 workspace + 在库内生成 API key（不走 UI）
node scripts/twenty-bootstrap.js

# 有旧 bridge 时：重建 KB parent-child 索引（自动备份）
bash scripts/rebuild-kb-index.sh

# 没有旧 bridge 时：直接导入 KB 快照（测试/生产常用）
bash scripts/import-kb-snapshot.sh
# 或指定目标库：TARGET_PG_DB=products bash scripts/import-kb-snapshot.sh

# 从 sitemap 生成类目 KB
node scripts/build-site-kb.js

# KB 审计
RAG_PG_URL=postgres://crmnew:<password>@127.0.0.1:5440/bridge node scripts/kb-audit.js

# KB 备份列表 / 回滚
RAG_PG_URL=postgres://crmnew:<password>@127.0.0.1:5440/bridge node scripts/kb-version.js list
RAG_PG_URL=postgres://crmnew:<password>@127.0.0.1:5440/bridge node scripts/kb-version.js rollback kb_docs_v...

# 在线 FAQ 同步 + 重建 KB（不依赖旧 bridge）
# 宿主机执行时 RAG_PG_URL 用 127.0.0.1:5440/bridge
RAG_PG_URL=postgres://crmnew:<password>@127.0.0.1:5440/bridge node scripts/sync-kb-online.js
# 仅用本地 bridge/kb 重建
node scripts/sync-kb-online.js --local-only --force

# 从当前环境重新生成快照（可选）
bash scripts/export-kb-snapshot.sh

# 全量商品页站点地图（官网 sitemap → bridge 库）
node scripts/build-site-map.js www us

# Prometheus 指标
curl -s http://127.0.0.1:4100/metrics

# AI 质量日报（最近 24 小时；可传小时数）
node scripts/quality-report.js 24

# 质量告警（默认最近 1 小时；--dry-run 只打印不发邮件）
node scripts/quality-alert.js 1 --dry-run
# 建议 cron：
# */30 * * * * cd /home/dev/code/crm-new && node scripts/quality-alert.js 1 >> logs/quality-alert.log 2>&1

# 离线回归评测（确定性逻辑，不调 LLM）
node scripts/eval-offline.js

# RAG 检索评测
RAG_PG_URL=postgres://... node scripts/eval-retrieval.js

# 真实模型离线评测（fake LibreDesk，不写真实会话；会调 LLM/RPC）
node scripts/eval-live.js

# 公网 HTTPS（仅本地联调需要）：Cloudflare Quick Tunnel + 路径白名单网关
# 测试/生产：不要跑这个脚本，使用正式域名 + Ingress/Nginx + TLS
bash scripts/public-https.sh

# 仅本地开发：测试服 RPC 端口外网被封时建 SSH 隧道
# 测试/生产：不要跑这个脚本，直接把 RPC URL 配成内网可达地址
bash scripts/rpc-tunnel.sh --apply

# 配置 163 SMTP（自动重启 LibreDesk）
node scripts/configure-email.js

# 配置 Email 渠道（163 收件走 imap-proxy + 默认外发模板 + AI 自动分配）
node scripts/add-email-inbox.js

# 本地静态测试页（widget 接入演示）
bash scripts/serve-web.sh   # http://localhost:8088/demo.html

# 端到端验证 widget JWT（登录用户可查订单）
node scripts/e2e-widget-jwt.js "Can you check the status of my order SO-1?" 

# 端到端模拟 widget 访客对话（等待 AI 回复）
node scripts/e2e-widget.js "What is the minimum order value?"

冒烟

bash scripts/smoke.sh

常用运维操作

# 修改 bridge 代码后
docker compose up -d --build bridge

# 修改 .env 后（如 Twenty API key）
docker compose up -d --force-recreate bridge

# 修改 LibreDesk 配置模板后
node scripts/render-config.js && docker compose up -d --force-recreate libredesk

# 备份数据库
docker exec crmnew-postgres pg_dump -U crmnew -d libredesk > backups/libredesk-$(date +%F).sql
docker exec crmnew-postgres pg_dump -U crmnew -d twenty  > backups/twenty-$(date +%F).sql

# 备份 Twenty 文件存储
docker run --rm -v crm-new_twenty-data:/data -v "$PWD/backups":/backup alpine \
  tar czf /backup/twenty-data-$(date +%F).tar.gz -C /data .

镜像升级（LibreDesk）

# 1. 备份
docker exec crmnew-postgres pg_dump -U crmnew -d libredesk > backups/libredesk-before-upgrade.sql

# 2. 修改 .env 的 LIBREDESK_IMAGE 后重建
docker compose up -d --force-recreate libredesk

# 3. 容器启动命令会自动执行 --upgrade；确认日志
docker compose logs --tail=50 libredesk

回滚

# 切回稳定版
sed -i 's#^LIBREDESK_IMAGE=.*#LIBREDESK_IMAGE=docker.1panel.live/libredesk/libredesk:latest#' .env
docker compose up -d --force-recreate libredesk
# 跨大版本回滚数据库需恢复备份（升级前 pg_dump）

端口冲突排查

ss -ltnp | grep -E ':(9000|3100|4100|5440|6390)\s'

已知坑

现象	原因	处理
容器启动报 database "xxx" does not exist	首次初始化脚本未执行	docker exec crmnew-postgres psql -U crmnew -d postgres -c 'CREATE DATABASE xxx;'
bridge 健康检查 connection refused	容器内 localhost 解析到 IPv6	健康检查固定用回环地址（避免 IPv6）
LibreDesk 反复重启	System 密码不满足强度（10–72 位、大小写+数字+特殊字符）	改 .env 的 LIBREDESK_SYSTEM_USER_PASSWORD 后重建
工具 401	X-Tools-Key 与 TOOLS_SHARED_KEY 不一致	核对 .env 与 LibreDesk 工具 Header
工具 403 verification_required	联系人未验证	先走平台 OTP 验证，或该工具不需要验证时关闭 requires_verification
Twenty API 调用失败	TWENTY_API_KEY / workspace 未配置	在 Twenty 后台创建 API key 填 .env 后重建 bridge
163 邮箱报 Unsafe Login	LibreDesk 的 go-imap 不发 IMAP ID	已加 imap-id-proxy，email inbox 的 IMAP host 指向 imap-proxy:1993，tls_type=none
管理员后台实时更新不工作	通过 http + IP 访问时 agent websocket 拒绝非 HTTPS 来源	POC 可忽略；生产用 HTTPS 或经 localhost 访问
collect_info 槽位丢失	Redis 不可用，退回了进程内存	检查 REDIS_URL=redis://redis:6379/3 和 docker logs crmnew-bridge 的 lead store 告警
多站点商品推荐串站	bridge/config/sites.json 的 inbox 映射没配	把对应 inbox 数字 ID 指到 us/eu/www profile，重建 bridge
WhatsApp webhook 收不到	没有公网 HTTPS / Meta 回调地址不对	本地联调跑 bash scripts/public-https.sh；测试/生产使用正式域名，不要用 Quick Tunnel
公网访问到管理后台	网关白名单配置	services/public-gateway 只放行 /webhooks/whatsapp/*、/hc/*、/widget*、/static/public/*，其余 404
AI 回复"系统暂时无法查询订单"	RPC 不可达，bridge 8s 超时	本地开发跑 bash scripts/rpc-tunnel.sh --apply；测试/生产检查内网 RPC 地址/网络策略，不要用开发机隧道