174 lines
6.5 KiB
Markdown
174 lines
6.5 KiB
Markdown
# 运维手册（crm-new）
|
||
|
||
## 启动 / 停止
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
## 状态与日志
|
||
|
||
```bash
|
||
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 配置脚本
|
||
|
||
```bash
|
||
# 导入/更新知识库（帮助中心文章，幂等）
|
||
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
|
||
|
||
# 重建 KB parent-child 索引（旧 bridge indexer + 回填 text_tsv，自动备份）
|
||
bash scripts/rebuild-kb-index.sh
|
||
|
||
# 升级旧 kb_docs 支持 Hybrid RAG（text_tsv/parent_id/chunk_type）
|
||
node scripts/upgrade-kb-schema.js
|
||
|
||
# 全量商品页站点地图（官网 sitemap → bridge 库）
|
||
node scripts/build-site-map.js www us
|
||
|
||
# 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
|
||
|
||
# 真实模型离线评测（fake LibreDesk，不写真实会话；会调 LLM/RPC）
|
||
node scripts/eval-live.js
|
||
|
||
# 公网 HTTPS（WhatsApp webhook 需要）：Cloudflare Quick Tunnel + 路径白名单网关
|
||
bash scripts/public-https.sh
|
||
|
||
# 测试服 RPC 端口外网被封：建 SSH 隧道并让 bridge 指向隧道（网关 IP）
|
||
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
|
||
bash scripts/smoke.sh
|
||
```
|
||
|
||
## 常用运维操作
|
||
|
||
```bash
|
||
# 修改 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）
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
## 回滚
|
||
|
||
```bash
|
||
# 切回稳定版
|
||
sed -i 's#^LIBREDESK_IMAGE=.*#LIBREDESK_IMAGE=docker.1panel.live/libredesk/libredesk:latest#' .env
|
||
docker compose up -d --force-recreate libredesk
|
||
# 跨大版本回滚数据库需恢复备份（升级前 pg_dump）
|
||
```
|
||
|
||
## 端口冲突排查
|
||
|
||
```bash
|
||
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`，把输出的 `.../webhooks/whatsapp/<inbox_id>` 配到 Meta；quick tunnel URL 每次重启会变 |
|
||
| 公网访问到管理后台 | 网关白名单配置 | `services/public-gateway` 只放行 `/webhooks/whatsapp/*`、`/hc/*`、`/widget*`、`/static/public/*`，其余 404 |
|
||
| AI 回复"系统暂时无法查询订单" | 测试服 24503/24505/24506/24509 外网 TCP 被封，bridge 8s 超时 | 跑 `bash scripts/rpc-tunnel.sh --apply`，bridge RPC 指向 docker 网关（隧道只绑网关，不暴露 LAN） |
|