AI Chat Bot Widget 部署文档

一、架构概览


┌─────────────────────────────────────────────────────────────┐
│                        客户网站                               │
│                    (www.example.com)                         │
│                                                             │
│

注意： publicKey 和 apiBase 是必填参数。

优点：

  • 更轻量（按需加载）
  • 样式可自定义（通过 CSS 变量覆盖）

    • 缺点：

  • 可能被宿主 CSS 污染
  • 需要正确处理加载顺序

    • ---

    三、参数配置

    参数类型默认值说明
    `publicKey`string**必填**公钥，格式 `wpk_live_xxx`
    `apiBase`string**必填**API 地址
    `theme`string`light``light` / `dark`
    `primaryColor`string`#4f46e5`主题色
    `position`string`bottom-right`悬浮位置
    `homeMode`boolean`false`启用首页快捷问题模式
    `homeSubtitle`string-首页模式副标题
    `helpUrl`string-帮助中心链接
    `locale`string`zh-CN``zh-CN` / `en`
    `zIndex`number`999999`CSS z-index

    示例

    四、部署到客户网站

    Step 1：获取 Widget 配置

    登录 AI Chat Bot 管理后台 → 选择 Bot → 复制嵌入代码

    Step 2：修改客户网站

    将嵌入代码添加到页面 HTML 的 前：

    Step 3：常见平台操作

    平台操作方式
    **WordPress**主题编辑器 → footer.php → 加在 `` 前
    **Shopify**主题 → 编辑代码 → section.footer 或 theme.liquid
    **Wix**设置 → 跟踪分析工具 → 自定义代码
    **Squarespace**Settings → Advanced → Code Injection → Footer
    **Webflow**Project Settings → Custom Code → Footer Code
    **静态 HTML**直接编辑 .html 文件

    Step 4：验证

    1. 清除浏览器缓存（或 Ctrl+Shift+R 硬刷新）

    2. 访问页面，右下角应出现 💬 按钮

    3. 点击按钮，AI 对话框应正常打开

    五、网络要求

    客户网站必须能访问以下域名：

    域名用途
    `*.pages.dev`Widget 资源和页面
    `*.roger-chen.workers.dev`API 请求

    国内环境注意： .workers.dev 域名可能被部分网络屏蔽，建议：

  • 优先使用 iframe 方式（Pages 域名更稳定）
  • 如有问题，考虑将 `embed.html` 部署到客户自己的 CDN

    • 六、CDN 域名说明

    用途URL状态
    Widget embed（主）`https://master.ai-chat-bot-test.pages.dev/embed`✅ 稳定
    Widget Worker（备）`https://ai-chat-bot-widget.roger-chen.workers.dev/embed.html`⚠️ 部分网络屏蔽
    API`https://ai-chat-bot-prod.roger-chen.workers.dev`✅ 正常

    七、故障排查

    Widget 不显示

    1. 检查网络 — 浏览器开发者工具 → Network → 是否有红色请求

    2. 检查 Console — F12 → Console 是否有报错

    3. 检查 iframe — 右键 → 审查元素 → 是否有 #ai-chat-bot-widget iframe

    4. 清除缓存 — Ctrl+Shift+R 硬刷新

    API 请求失败

    
Failed to connect / 网络错误
  • 检查 `apiBase` 参数是否正确
  • 检查 `publicKey` 是否有效
  • 确认 API 域名可访问：`curl https://ai-chat-bot-prod.roger-chen.workers.dev/v1/widget/embed-config?publicKey=xxx`

    • Greeting 不显示

  • D1 查询可能过载，联系技术支持检查 KV 缓存状态
  • 确认 Bot 有设置 greeting 消息

    • 八、联系支持

    如遇到部署问题，提供以下信息：

    1. 客户网站 URL

    2. 浏览器 Console 错误截图

    3. Network 面板中失败的请求

    4. publicKey（可隐藏部分字符）