# Bytedesk客服系统 - 前端工程师集成手册

**版本**: v1.0
**最后更新**: 2025-01-07
**适用项目**: vf_react
**后端服务器**: http://43.143.189.195

---

## 📋 目录

- [1. 集成概述](#1-集成概述)
- [2. 快速开始（5分钟集成）](#2-快速开始5分钟集成)
- [3. 详细集成步骤](#3-详细集成步骤)
- [4. 配置说明](#4-配置说明)
- [5. 高级功能](#5-高级功能)
- [6. 样式定制](#6-样式定制)
- [7. 故障排查](#7-故障排查)
- [8. 常见问题FAQ](#8-常见问题faq)
- [9. 性能优化](#9-性能优化)
- [10. 安全注意事项](#10-安全注意事项)

---

## 1. 集成概述

### 1.1 什么是Bytedesk客服系统？

Bytedesk是一个开源的在线客服系统，为您的网站提供实时客户服务功能。本手册将指导您将Bytedesk客服Widget集成到vf_react项目中。

### 1.2 集成架构

```
┌────────────────────────────────────────────────────────────┐
│                      vf_react前端项目                        │
│  ┌────────────────────────────────────────────────────┐   │
│  │                    App.jsx                          │   │
│  │  ┌──────────────────────────────────────────────┐  │   │
│  │  │       BytedeskWidget组件                      │  │   │
│  │  │  - 动态加载客服脚本                          │  │   │
│  │  │  - 显示悬浮客服图标                          │  │   │
│  │  │  - 处理用户交互                              │  │   │
│  │  └──────────────────────────────────────────────┘  │   │
│  └────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────┘
                            │
                            │ HTTP/WebSocket
                            ↓
┌────────────────────────────────────────────────────────────┐
│           Bytedesk后端服务 (43.143.189.195)                 │
│  - API接口: :9003                                          │
│  - WebSocket: :9885                                        │
│  - Nginx反向代理: :80                                       │
└────────────────────────────────────────────────────────────┘
```

### 1.3 集成特点

- ✅ **零侵入**: 不修改vf_react原有代码逻辑
- ✅ **即插即用**: 复制文件 + 修改配置即可使用
- ✅ **样式隔离**: 使用Shadow DOM，不影响全局样式
- ✅ **异步加载**: 不阻塞页面渲染
- ✅ **跨页面**: 在所有页面显示客服图标
- ✅ **响应式**: 自动适配移动端和PC端

---

## 2. 快速开始（5分钟集成）

### 步骤1: 复制集成文件

将`bytedesk-integration`文件夹复制到vf_react项目的`src/`目录下：

```bash
# 在vf_react项目根目录执行
cd D:\【Git】\vf_react
cp -r bytedesk-integration src/
```

文件结构：
```
vf_react/
├── src/
│   ├── bytedesk-integration/         # 客服集成文件夹
│   │   ├── components/
│   │   │   └── BytedeskWidget.jsx   # 客服Widget组件
│   │   ├── config/
│   │   │   └── bytedesk.config.js   # 配置文件
│   │   ├── App.jsx.example          # 集成示例代码
│   │   ├── .env.bytedesk.example    # 环境变量示例
│   │   └── 前端工程师集成手册.md     # 本手册
│   ├── App.jsx                       # 您的主App文件
│   └── ...
└── package.json
```

### 步骤2: 配置环境变量

复制环境变量模板到项目根目录并配置：

```bash
# 复制模板
cp src/bytedesk-integration/.env.bytedesk.example .env.local

# 编辑配置文件
vim .env.local
```

**必需配置项**（在.env.local中）:
```bash
# Bytedesk服务器地址
REACT_APP_BYTEDESK_API_URL=http://43.143.189.195

# 组织ID（由管理员提供）
REACT_APP_BYTEDESK_ORG=df_org_uid

# 工作组ID（由管理员提供）
REACT_APP_BYTEDESK_SID=df_wg_aftersales
```

> **注意**: ORG和SID需要从管理员处获取，或登录后台http://43.143.189.195/admin/查看。

### 步骤3: 集成到App.jsx

打开`src/App.jsx`，参考`App.jsx.example`添加以下代码：

```jsx
// 1. 导入组件和配置（在文件顶部添加）
import BytedeskWidget from './bytedesk-integration/components/BytedeskWidget';
import { getBytedeskConfig } from './bytedesk-integration/config/bytedesk.config';

function App() {
  // 2. 获取配置
  const bytedeskConfig = getBytedeskConfig();

  return (
    <div className="App">
      {/* 您的原有代码保持不变 */}

      {/* 3. 添加客服Widget（在return的JSX最后添加） */}
      <BytedeskWidget
        config={bytedeskConfig}
        autoLoad={true}
      />
    </div>
  );
}

export default App;
```

### 步骤4: 启动项目测试

```bash
# 安装依赖（如果需要）
npm install

# 启动开发服务器
npm start
```

打开浏览器，您应该在页面右下角看到客服图标（💬）。

---

## 3. 详细集成步骤

### 3.1 文件说明

#### BytedeskWidget.jsx
React组件，负责加载和管理Bytedesk客服Widget。

**主要功能**:
- 动态加载客服脚本（https://www.weiyuai.cn/embed/bytedesk-web.js）
- 初始化客服Widget
- 生命周期管理（加载、卸载、清理）
- 错误处理

**Props**:
```typescript
interface BytedeskWidgetProps {
  config: Object;          // 配置对象（必需）
  autoLoad?: boolean;      // 是否自动加载（默认true）
  onLoad?: (bytedesk) => void;    // 加载成功回调
  onError?: (error) => void;      // 加载失败回调
}
```

#### bytedesk.config.js
配置文件，包含客服系统的所有配置项。

**主要函数**:
- `getBytedeskConfig()`: 获取基础配置
- `getBytedeskConfigWithUser(user)`: 获取带用户信息的配置
- `shouldShowCustomerService(pathname)`: 判断是否在当前页面显示客服

### 3.2 集成方式选择

根据您的需求，选择合适的集成方式：

#### 方式一: 全局集成（推荐）

**适用场景**: 所有页面都需要客服功能

```jsx
import BytedeskWidget from './bytedesk-integration/components/BytedeskWidget';
import { getBytedeskConfig } from './bytedesk-integration/config/bytedesk.config';

function App() {
  const bytedeskConfig = getBytedeskConfig();

  return (
    <div className="App">
      {/* 您的页面内容 */}

      <BytedeskWidget config={bytedeskConfig} autoLoad={true} />
    </div>
  );
}
```

#### 方式二: 按页面显示

**适用场景**: 只在特定页面显示客服（如排除登录页、支付页）

```jsx
import { useLocation } from 'react-router-dom';
import BytedeskWidget from './bytedesk-integration/components/BytedeskWidget';
import { getBytedeskConfig, shouldShowCustomerService } from './bytedesk-integration/config/bytedesk.config';

function App() {
  const location = useLocation();
  const bytedeskConfig = getBytedeskConfig();
  const showBytedesk = shouldShowCustomerService(location.pathname);

  return (
    <div className="App">
      {/* 您的页面内容 */}

      {showBytedesk && (
        <BytedeskWidget config={bytedeskConfig} autoLoad={true} />
      )}
    </div>
  );
}
```

自定义页面规则（修改`bytedesk.config.js`）:

```javascript
export const shouldShowCustomerService = (pathname) => {
  // 在以下页面显示客服
  const allowedPages = [
    '/',
    '/home',
    '/products',
    '/pricing',
  ];

  // 在以下页面隐藏客服
  const blockedPages = [
    '/login',
    '/register',
    '/payment',
  ];

  if (blockedPages.some(page => pathname.startsWith(page))) {
    return false;
  }

  return allowedPages.some(page => pathname.startsWith(page));
};
```

#### 方式三: 带用户信息集成

**适用场景**: 需要将登录用户信息传递给客服端

```jsx
import { useContext } from 'react';
import BytedeskWidget from './bytedesk-integration/components/BytedeskWidget';
import { getBytedeskConfigWithUser } from './bytedesk-integration/config/bytedesk.config';
import { AuthContext } from './contexts/AuthContext';

function App() {
  const { user } = useContext(AuthContext);
  const bytedeskConfig = getBytedeskConfigWithUser(user);

  return (
    <div className="App">
      {/* 您的页面内容 */}

      <BytedeskWidget config={bytedeskConfig} autoLoad={true} />
    </div>
  );
}
```

用户信息格式:
```javascript
const user = {
  id: '12345',              // 用户ID（必需）
  name: '张三',             // 用户名
  email: 'user@example.com', // 邮箱
  mobile: '13800138000',     // 手机号
};
```

---

## 4. 配置说明

### 4.1 环境变量配置

在`.env.local`文件中配置（项目根目录）:

```bash
# ========== 必需配置 ==========

# 后端服务地址
REACT_APP_BYTEDESK_API_URL=http://43.143.189.195

# 组织ID
REACT_APP_BYTEDESK_ORG=df_org_uid

# 工作组ID
REACT_APP_BYTEDESK_SID=df_wg_aftersales

# ========== 可选配置 ==========

# 客服类型 (2=人工客服, 1=机器人)
REACT_APP_BYTEDESK_TYPE=2

# 语言 (zh-cn, en, ja, ko)
REACT_APP_BYTEDESK_LOCALE=zh-cn

# 图标位置 (bottom-right, bottom-left, top-right, top-left)
REACT_APP_BYTEDESK_PLACEMENT=bottom-right

# 图标边距（像素）
REACT_APP_BYTEDESK_MARGIN_BOTTOM=20
REACT_APP_BYTEDESK_MARGIN_SIDE=20

# 主题模式 (system, light, dark)
REACT_APP_BYTEDESK_THEME_MODE=system

# 主题色
REACT_APP_BYTEDESK_THEME_COLOR=#0066FF

# 自动弹出（不推荐）
REACT_APP_BYTEDESK_AUTO_POPUP=false
```

### 4.2 代码配置

在`bytedesk.config.js`中直接修改:

```javascript
export const bytedeskConfig = {
  // API服务地址
  apiUrl: 'http://43.143.189.195',
  htmlUrl: 'http://43.143.189.195/chat/',

  // 客服图标位置
  placement: 'bottom-right',

  // 边距设置
  marginBottom: 20,
  marginSide: 20,

  // 自动弹出
  autoPopup: false,

  // 语言设置
  locale: 'zh-cn',

  // 客服图标配置
  bubbleConfig: {
    show: true,
    icon: '💬',           // 可以使用emoji或图片URL
    title: '在线客服',
    subtitle: '点击咨询',
  },

  // 主题配置
  theme: {
    mode: 'system',       // light | dark | system
    backgroundColor: '#0066FF',
    textColor: '#ffffff',
  },

  // 聊天配置
  chatConfig: {
    org: 'df_org_uid',
    t: '2',               // 2=人工客服, 1=机器人
    sid: 'df_wg_aftersales',
  },
};
```

---

## 5. 高级功能

### 5.1 多工作组支持

根据页面显示不同工作组的客服：

```javascript
// bytedesk.config.js
export const getBytedeskConfigByPath = (pathname) => {
  const config = getBytedeskConfig();

  // 根据路径选择工作组
  if (pathname.startsWith('/sales')) {
    return {
      ...config,
      chatConfig: {
        ...config.chatConfig,
        sid: 'df_wg_sales',  // 销售组
      },
    };
  } else if (pathname.startsWith('/support')) {
    return {
      ...config,
      chatConfig: {
        ...config.chatConfig,
        sid: 'df_wg_support',  // 技术支持组
      },
    };
  }

  return config;  // 默认售后组
};
```

使用示例:
```jsx
import { useLocation } from 'react-router-dom';
import { getBytedeskConfigByPath } from './bytedesk-integration/config/bytedesk.config';

function App() {
  const location = useLocation();
  const bytedeskConfig = getBytedeskConfigByPath(location.pathname);

  return (
    <div className="App">
      <BytedeskWidget config={bytedeskConfig} autoLoad={true} />
    </div>
  );
}
```

### 5.2 条件性显示

根据用户登录状态或角色显示客服：

```jsx
function App() {
  const { user } = useContext(AuthContext);
  const bytedeskConfig = getBytedeskConfig();

  // 只为普通用户显示客服（管理员不显示）
  const showBytedesk = user && user.role === 'customer';

  return (
    <div className="App">
      {showBytedesk && (
        <BytedeskWidget config={bytedeskConfig} autoLoad={true} />
      )}
    </div>
  );
}
```

### 5.3 事件回调

监听客服系统的加载状态：

```jsx
function App() {
  const bytedeskConfig = getBytedeskConfig();

  const handleLoad = (bytedesk) => {
    console.log('客服系统加载成功', bytedesk);
    // 可以在这里执行自定义逻辑
    // 例如: 发送统计事件
  };

  const handleError = (error) => {
    console.error('客服系统加载失败', error);
    // 可以在这里显示降级方案
    // 例如: 显示备用联系方式
  };

  return (
    <div className="App">
      <BytedeskWidget
        config={bytedeskConfig}
        autoLoad={true}
        onLoad={handleLoad}
        onError={handleError}
      />
    </div>
  );
}
```

### 5.4 自定义触发按钮

隐藏默认图标，使用自定义按钮：

```jsx
import { useState } from 'react';

function App() {
  const [showBytedesk, setShowBytedesk] = useState(false);

  // 隐藏默认图标
  const bytedeskConfig = {
    ...getBytedeskConfig(),
    bubbleConfig: {
      show: false,  // 隐藏默认图标
    },
  };

  return (
    <div className="App">
      {/* 自定义按钮 */}
      <button
        onClick={() => setShowBytedesk(true)}
        className="custom-service-btn"
      >
        联系客服
      </button>

      {showBytedesk && (
        <BytedeskWidget config={bytedeskConfig} autoLoad={true} />
      )}
    </div>
  );
}
```

---

## 6. 样式定制

### 6.1 修改主题色

在配置中修改主题色：

```javascript
// bytedesk.config.js
theme: {
  mode: 'light',
  backgroundColor: '#FF6600',  // 您的品牌色
  textColor: '#ffffff',
},
```

### 6.2 修改图标位置

```javascript
// bytedesk.config.js
placement: 'bottom-left',  // 左下角
marginBottom: 30,           // 距底部30px
marginSide: 30,             // 距左侧30px
```

### 6.3 使用自定义图标

使用图片URL替换emoji:

```javascript
// bytedesk.config.js
bubbleConfig: {
  show: true,
  icon: 'https://yourdomain.com/images/service-icon.png',
  title: '在线客服',
  subtitle: '点击咨询',
},
```

### 6.4 样式不冲突

Bytedesk Widget使用Shadow DOM技术，样式完全隔离，不会影响您的全局CSS。

---

## 7. 故障排查

### 7.1 客服图标不显示

**可能原因**:
1. 环境变量未配置
2. 配置文件路径错误
3. 后端服务未启动
4. 脚本加载失败

**解决方案**:
```bash
# 1. 检查.env.local文件是否存在
ls -la .env.local

# 2. 检查环境变量是否加载
console.log(process.env.REACT_APP_BYTEDESK_API_URL);

# 3. 检查后端服务状态
curl http://43.143.189.195/api/health

# 4. 查看浏览器控制台错误
# 打开浏览器开发者工具 -> Console标签页
```

### 7.2 连接不上后端

**检查清单**:
```bash
# 1. 后端服务是否运行
# 联系后端工程师确认docker容器状态

# 2. 防火墙是否开放
# 确认80端口可访问

# 3. CORS配置
# 后端需要在.env.production中添加您的前端地址:
# BYTEDESK_CORS_ALLOWED_ORIGINS=http://your-frontend-domain.com
```

### 7.3 ORG或SID错误

**获取正确配置**:
1. 登录管理后台: http://43.143.189.195/admin/
2. 导航到"设置" -> "组织信息"，复制`组织UID`
3. 导航到"客服管理" -> "工作组"，复制`工作组ID`
4. 更新`.env.local`文件
5. 重启开发服务器: `npm start`

### 7.4 开发环境正常，生产环境异常

**检查清单**:
```bash
# 1. 确认生产环境的环境变量
# 查看构建时的配置

# 2. 检查CORS配置
# 后端需要添加生产域名到CORS白名单

# 3. 检查HTTPS/HTTP
# 如果前端使用HTTPS，后端也应使用HTTPS

# 4. 查看生产环境日志
npm run build
# 检查构建产物中的配置
```

---

## 8. 常见问题FAQ

### Q1: 客服系统会影响页面性能吗？

**A**: 不会。客服脚本采用异步加载，不会阻塞页面渲染。Widget总大小约50KB（gzip后），首次加载后会被浏览器缓存。

### Q2: 可以在移动端使用吗？

**A**: 可以。Bytedesk Widget完全响应式，自动适配移动端和PC端。

### Q3: 是否支持离线消息？

**A**: 支持。用户在客服离线时发送的消息会被保存，客服上线后可以查看。

### Q4: 可以集成到React Native吗？

**A**: BytedeskWidget是为Web设计的。React Native需要使用Bytedesk的原生SDK（另外提供）。

### Q5: 如何隐藏特定页面的客服？

**A**: 使用`shouldShowCustomerService`函数（见3.2节"方式二"）。

### Q6: 可以同时配置多个工作组吗？

**A**: 可以。参考5.1节"多工作组支持"。

### Q7: 用户信息是否安全？

**A**: 是的。所有通信使用WebSocket加密传输，用户信息不会被第三方获取。建议生产环境使用HTTPS。

### Q8: 是否需要付费？

**A**: Bytedesk社区版（当前使用）完全免费，License有效期至2040年12月31日。

---

## 9. 性能优化

### 9.1 按需加载

只在需要时加载客服系统：

```jsx
import { useState, useEffect } from 'react';

function App() {
  const [loadBytedesk, setLoadBytedesk] = useState(false);

  // 延迟5秒加载（页面渲染完成后）
  useEffect(() => {
    const timer = setTimeout(() => {
      setLoadBytedesk(true);
    }, 5000);

    return () => clearTimeout(timer);
  }, []);

  return (
    <div className="App">
      {/* 您的页面内容 */}

      {loadBytedesk && (
        <BytedeskWidget config={getBytedeskConfig()} autoLoad={true} />
      )}
    </div>
  );
}
```

### 9.2 Lazy Import

使用React.lazy延迟导入组件：

```jsx
import { lazy, Suspense } from 'react';

const BytedeskWidget = lazy(() => import('./bytedesk-integration/components/BytedeskWidget'));

function App() {
  return (
    <div className="App">
      {/* 您的页面内容 */}

      <Suspense fallback={null}>
        <BytedeskWidget config={getBytedeskConfig()} autoLoad={true} />
      </Suspense>
    </div>
  );
}
```

### 9.3 缓存优化

客服脚本会自动被浏览器缓存，无需额外配置。

---

## 10. 安全注意事项

### 10.1 环境变量安全

```bash
# ❌ 错误: 不要在代码中硬编码配置
const config = {
  apiUrl: 'http://43.143.189.195',
  org: 'df_org_uid',
};

# ✅ 正确: 使用环境变量
const config = {
  apiUrl: process.env.REACT_APP_BYTEDESK_API_URL,
  org: process.env.REACT_APP_BYTEDESK_ORG,
};
```

### 10.2 敏感信息保护

```javascript
// ❌ 不要传递敏感信息
const user = {
  id: '12345',
  password: 'user-password',  // 不要传递密码
  creditCard: '1234-5678',    // 不要传递信用卡
};

// ✅ 只传递必要信息
const user = {
  id: '12345',
  name: '张三',
  email: 'user@example.com',
};
```

### 10.3 HTTPS使用

生产环境强烈建议使用HTTPS:

```bash
# 开发环境
REACT_APP_BYTEDESK_API_URL=http://43.143.189.195

# 生产环境
REACT_APP_BYTEDESK_API_URL=https://kefu.yourdomain.com
```

### 10.4 内容安全策略（CSP）

如果您的项目使用CSP，需要允许以下域名：

```html
<meta http-equiv="Content-Security-Policy" content="
  default-src 'self';
  script-src 'self' https://www.weiyuai.cn;
  connect-src 'self' http://43.143.189.195;
  img-src 'self' data: http://43.143.189.195;
"/>
```

---

## 11. 获取帮助

### 11.1 联系方式

- **技术支持**: 访问 http://43.143.189.195/chat/ 在线咨询
- **管理员**: 联系您的项目管理员获取ORG和SID
- **后端工程师**: 联系后端团队确认服务器状态

### 11.2 日志查看

```javascript
// 在浏览器控制台查看Bytedesk日志
// 日志前缀为 [Bytedesk]

// 示例:
[Bytedesk] 开始加载客服Widget...
[Bytedesk] Widget脚本加载成功
[Bytedesk] 初始化Widget
[Bytedesk] Widget初始化成功
```

### 11.3 调试技巧

```javascript
// 1. 检查配置是否正确
console.log('Bytedesk配置:', getBytedeskConfig());

// 2. 检查环境变量
console.log('API URL:', process.env.REACT_APP_BYTEDESK_API_URL);
console.log('ORG:', process.env.REACT_APP_BYTEDESK_ORG);
console.log('SID:', process.env.REACT_APP_BYTEDESK_SID);

// 3. 检查Widget是否加载
console.log('BytedeskWeb对象:', window.BytedeskWeb);
```

---

## 12. 版本历史

| 版本 | 日期 | 更新内容 |
|------|------|---------|
| v1.0 | 2025-01-07 | 初始版本，支持基础集成功能 |

---

## 13. 附录

### 13.1 完整配置示例

```javascript
// bytedesk.config.js - 完整配置
export const bytedeskConfig = {
  apiUrl: 'http://43.143.189.195',
  htmlUrl: 'http://43.143.189.195/chat/',
  placement: 'bottom-right',
  marginBottom: 20,
  marginSide: 20,
  autoPopup: false,
  locale: 'zh-cn',
  bubbleConfig: {
    show: true,
    icon: '💬',
    title: '在线客服',
    subtitle: '点击咨询',
  },
  theme: {
    mode: 'system',
    backgroundColor: '#0066FF',
    textColor: '#ffffff',
  },
  chatConfig: {
    org: 'df_org_uid',
    t: '2',
    sid: 'df_wg_aftersales',
  },
};
```

### 13.2 文件清单

集成所需的所有文件：

```
bytedesk-integration/
├── components/
│   └── BytedeskWidget.jsx          # React组件（必需）
├── config/
│   └── bytedesk.config.js          # 配置文件（必需）
├── App.jsx.example                 # 集成示例（参考）
├── .env.bytedesk.example           # 环境变量示例（参考）
└── 前端工程师集成手册.md            # 本手册（参考）
```

---

**祝您集成顺利！**

如有任何问题，请随时联系技术支持。