docs(deploy): 记录测试服部署与实例配置变更

README.md

@@ -3,7 +3,26 @@
 按官方文档 [docs.libredesk.io/getting-started/installation](https://docs.libredesk.io/getting-started/installation) 的 Docker 方式部署的独立实例，
 与本机 `crm-new` 项目里那套 LibreDesk 完全隔离（独立容器、独立数据卷、独立端口）。
 
-## 访问
+## 两套环境
+
+| 环境 | 访问地址 | 位置 | 说明 |
+| --- | --- | --- | --- |
+| 开发（本机） | https://192.168.31.61:9443 | 本机 `libredesk/` | 自签证书 TLS 容器，日常开发/验证 |
+| 测试（测试服） | https://wangliang-crm.dev.gaia888.com | `47.76.223.252:/data/dev/wangliang/libredesk` | 共享测试，宿主 nginx 提供 TLS |
+
+### 测试服实例要点（2026-10-29 迁移部署）
+
+- 目标机 ARM64，镜像 `libredesk/libredesk:v2.9.1`（多架构，自动取 arm64）。
+- **无 tls 容器**：宿主 nginx 已有 `wangliang-crm.dev.gaia888.com → 127.0.0.1:9000` 的 server 块，TLS 由 letsencrypt 证书提供。
+- 端口：app `9000`（`0.0.0.0`）、db `127.0.0.1:5440`、redis `127.0.0.1:6390`、bridge-tools `127.0.0.1:4100`。
+- bridge-tools 额外接入 `spug-net`，RPC 全部指向 wangliang 空间：`jsonrpc://wangliang-dev:9503/9505/9509/9506`。
+- 数据从本机迁移（`pg_dump` 恢复），`encryption_key` 与本机一致；`app.root_url` 已改为测试服域名。
+- 旧 `crm-ai`（`crmnew-*`）栈已下线，数据卷 `crm-new_pg-data` / `crm-new_redis-data` / `crm-new_twenty-data` 保留。
+- 运维：`ssh yw-dev` 后 `cd /data/dev/wangliang/libredesk && docker compose ps|logs|restart`。
+- 测试服版 compose 见 `deploy/testspace/docker-compose.yml`（与本仓库 `docker-compose.yml` 的差异即上述几项）；
+  实例配置变更（trusted_domains / widget 文案 / AI 问候规则）见 [docs/testspace-config-changes.md](docs/testspace-config-changes.md)。
+
+## 访问（本机开发实例）
 
 | 项 | 值 |
 | --- | --- |

deploy/testspace/docker-compose.yml

@@ -0,0 +1,106 @@
+# LibreDesk 测试服实例（/data/dev/wangliang/libredesk，47.76.223.252 ARM64）
+# 入口：宿主 nginx https://wangliang-crm.dev.gaia888.com -> 127.0.0.1:9000
+# 与仓库 docker-compose.yml（本机版）差异：
+#   - 无 tls 容器（宿主 nginx 提供 HTTPS/WSS）
+#   - app 直接绑宿主 9000，db/redis 端口沿用旧 crm-new 约定（5440/6390）
+#   - bridge-tools 接入 spug-net，直连 wangliang-dev:9503/9505/9506/9509
+#   - 镜像多架构，ARM64 自动取 arm64 variant
+services:
+  # Libredesk app
+  app:
+    image: ${LIBREDESK_IMAGE:-libredesk/libredesk:v2.9.1}
+    container_name: libredesk_app
+    restart: unless-stopped
+    ports:
+      - "9000:9000"
+    environment:
+      # 首次启动时设置 System 用户密码（已有数据库时为幂等空操作）
+      LIBREDESK_SYSTEM_USER_PASSWORD: ${LIBREDESK_SYSTEM_USER_PASSWORD:-}
+    healthcheck:
+      test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1:9000/health || exit 1"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 30s
+    networks:
+      - libredesk
+    depends_on:
+      - db
+      - redis
+    volumes:
+      - ./uploads:/libredesk/uploads:rw
+      - ./config.toml:/libredesk/config.toml:ro
+    command: [sh, -c, "./libredesk --install --idempotent-install --yes --config /libredesk/config.toml && ./libredesk --upgrade --yes --config /libredesk/config.toml && ./libredesk --config /libredesk/config.toml"]
+
+  # 业务工具服务：4 个 AI 工具（商品/订单/库存/客户资料）
+  bridge-tools:
+    build: ./bridge-tools
+    container_name: libredesk_bridge_tools
+    restart: unless-stopped
+    environment:
+      TOOLS_PORT: 4100
+      TOOLS_PUBLIC_BASE_URL: http://bridge-tools:4100
+      TOOLS_SHARED_KEY: ${BRIDGE_TOOLS_KEY}
+      TOOLS_DEV_BYPASS: "false"
+      RECOMMEND_URL: ${RPC_RECOMMEND_URL}
+      ORDER_API_URL: ${RPC_ORDER_URL}
+      INVENTORY_API_URL: ${RPC_INVENTORY_URL}
+      MEMBER_RPC_URL: ${RPC_MEMBER_URL}
+      RPC_TIMEOUT_MS: 8000
+      PRODUCT_TIMEOUT_MS: 30000
+      SITE_SEARCH_URL: https://www.yehwang.com/search.html?q=
+      DEFAULT_TENANT_ID: 2
+      DEFAULT_LANGUAGE_ID: 1
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    ports:
+      # 仅本机调试用；LibreDesk 通过容器名 bridge-tools:4100 访问
+      - "127.0.0.1:4100:4100"
+    depends_on:
+      - app
+    networks:
+      - libredesk
+      - spug-net
+
+  # PostgreSQL database
+  db:
+    image: ${POSTGRES_IMAGE:-pgvector/pgvector:pg18}
+    container_name: libredesk_db
+    restart: unless-stopped
+    networks:
+      - libredesk
+    ports:
+      - "127.0.0.1:5440:5432"
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-libredesk}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-libredesk}
+      POSTGRES_DB: ${POSTGRES_DB:-libredesk}
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-libredesk} -d ${POSTGRES_DB:-libredesk}"]
+      interval: 10s
+      timeout: 5s
+      retries: 6
+    volumes:
+      # PG18 官方镜像要求挂载 /var/lib/postgresql（数据在子目录）
+      - postgres-data:/var/lib/postgresql
+
+  # Redis
+  redis:
+    image: redis:7-alpine
+    container_name: libredesk_redis
+    restart: unless-stopped
+    networks:
+      - libredesk
+    ports:
+      - "127.0.0.1:6390:6379"
+    volumes:
+      - redis-data:/data
+
+networks:
+  libredesk:
+  spug-net:
+    external: true
+
+volumes:
+  postgres-data:
+  redis-data:

docs/testspace-config-changes.md

@@ -0,0 +1,40 @@
+# 测试服实例配置变更记录（2026-10-29 / 10-30）
+
+> 实例：测试服 47.76.223.252 `https://wangliang-crm.dev.gaia888.com`（LibreDesk v2.9.1）
+> 代码仓库：www 前端改动已推 `yehwang/storefront-web` 分支 `feature-20261030-libredesk-widget`
+> 本文记录的是**数据库/实例配置**变更（不在代码仓库里，随实例数据保存）。
+
+## 1. www 前端 widget 集成（代码）
+
+`/data/dev/wangliang/eu-store-front-web`：
+
+- 新增 `plugins/libredesk.client.js`：`window.LibredeskSettings = { baseURL, inboxID }` + 动态加载 `{baseURL}/widget.js`，全站加载、匿名访客。
+- `nuxt.config.js`：暴露 `LIBREDESK_BASE_URL` / `LIBREDESK_INBOX_ID`，注册插件。
+- `.env`（不入库）：`LIBREDESK_BASE_URL=https://wangliang-crm.dev.gaia888.com`、`LIBREDESK_INBOX_ID=81b679b0-33fb-4796-9f83-dcc0f43231cc`。
+- 运行方式：`yarn build` 后 `PORT=3015 NODE_ENV=production yarn start`（构建时注入 env，改 .env 后必须重新 build）。
+- 已提交：`ec123c4b feat(widget): 集成 LibreDesk 客服 widget`（分支 `feature-20261030-libredesk-widget`）。
+
+## 2. livechat inbox 配置（DB：inboxes.config）
+
+| 字段 | 值 |
+| --- | --- |
+| `trusted_domains` | 新增 `wangliang-www.dev.gaia888.com`（CSP `frame-ancestors` 白名单，缺了会导致 widget iframe 被浏览器拒绝、看不到按钮） |
+| `brand_name` | `Yehwang` |
+| `greeting_message` | `Hi! How can we help you today?` |
+| `chat_introduction` | `Ask about products, orders, shipping or returns.` |
+
+影响：widget 首页标题/欢迎语/副标题；trusted_domains 决定哪些站点能嵌入 widget。
+
+## 3. AI assistant 指令（DB：ai_assistants.instructions）
+
+在 `Yehwang Assistant` instructions 末尾追加一条规则：
+
+> When the customer greets you (e.g. hi / hello / 你好), reply exactly with: "Hi! How can we help you today? Welcome to Yehwang — ask about products, orders, shipping or returns." Do not add or change anything else in that greeting.
+
+效果：客户发 `hi` 时 AI 回复该固定话术（实测一致）。仍由模型生成，规则约束输出。
+
+## 4. 回滚方式
+
+- 前端代码：`git checkout main`（或 revert `ec123c4b`）后重新 `yarn build` + 重启。
+- inbox 配置：后台 Inbox → Widget 改回，或 `update inboxes set config = config || '{"trusted_domains": [...]}' ...`。
+- AI 规则：后台 AI Assistant → Instructions 删除该句即可。