# 运维手册（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

# 有旧 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

# 在线 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

# 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（仅本地联调需要）：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
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`；测试/生产使用正式域名，不要用 Quick Tunnel |
| 公网访问到管理后台 | 网关白名单配置 | `services/public-gateway` 只放行 `/webhooks/whatsapp/*`、`/hc/*`、`/widget*`、`/static/public/*`，其余 404 |
| AI 回复"系统暂时无法查询订单" | RPC 不可达，bridge 8s 超时 | 本地开发跑 `bash scripts/rpc-tunnel.sh --apply`；测试/生产检查内网 RPC 地址/网络策略，不要用开发机隧道 |