即时通信 IM 快速接入（React）

一、概述

可根据业务需求选择以下两种接入方式：

注意：说明：

注意：直播管理系统不提供托管的后台服务，需要自行部署服务端，用于生成登录凭证并调用腾讯云相关能力。仓库中提供了一份服务端示例代码，可直接部署使用，也可以将相关能力集成到已有的后端服务中。

二、快速体验

在进行快速体验之前，需要 开通 TUILiveKit 服务，满足相关环境配置及开通对应服务。

将开通后获取的 SDKAppId 和 SDKSecretKey 填入体验 demo 的登录框中。

注意：快速体验只有基础功能展示，完整功能需阅读这篇后本地搭建测试以及自行部署后使用。

三、功能介绍

五、快速接入

注意：环境要求：

六、步骤 1：环境配置及开通服务

在进行快速接入之前，需要参考 准备工作（Web React），满足相关环境配置及开通对应服务。

七、步骤 2：下载项目

从 GitHub Release 页面下载最新发布包，或通过 git clone：

git clone https://github.com/Tencent-RTC/TUILiveKit_Managercd TUILiveKit_Managerpnpm install

八、步骤 3：配置服务端

1. 编辑 packages/server/config/.env：

SDK_APP_ID=1400000001 # 请替换 SDKAppIDSECRET_KEY=xxxxxxx # 请替换 SecretKeyUSER_ID=administrator # 请替换管理员 userID

注意：说明：

2. 启动服务：

pnpm run start:server

注意：默认端口为 9000，可以通过配置 .env 中的 PORT 来修改端口号，且需要允许防火墙访问该端口。

九、步骤 4：配置前端

编辑 packages/react/.env：

VITE_API_BASE_URL=http://localhost:9000/api

注意：VITE_API_BASE_URL 中的端口号要和之前配置 server 启动的端口一致。

十、步骤 5：启动前端

pnpm run dev:react

启动成功后，打开浏览器访问 http://localhost:2028 即可看到页面。

十二、配置图片上传

系统的礼物缩略图、礼物素材、房间封面等功能依赖图片上传，需要配置存储服务。如果不配置，前端会自动降级为 URL 手动输入模式，不影响其他功能使用。

在 packages/server/config/.env 中追加存储配置，系统支持三种方式：

十三、方式一：腾讯云 COS 对象存储（默认）

注意：说明：

注意：前往 腾讯云 COS 控制台 创建存储桶并获取 API 密钥。

STORAGE_PROVIDER=cosCOS_SECRET_ID=your_secret_id # 腾讯云 API SecretIdCOS_SECRET_KEY=your_secret_key # 腾讯云 API SecretKeyCOS_BUCKET=your-bucket-1250000000 # COS 存储桶名称COS_REGION=ap-guangzhou # 存储桶所在地域COS_CDN_DOMAIN=web.sdk.qcloud.com # （可选）CDN 加速域名，不配置则使用默认 COS 域名COS_PATH_PREFIX=uploads # （可选）存储路径前缀，文件将存储在此目录下

十四、方式二：自定义 HTTP 上传接口

适用于已有图片上传服务的场景，系统会将文件以 multipart/form-data 方式转发到上传接口。

STORAGE_PROVIDER=customCUSTOM_UPLOAD_URL=https://your-api.com/upload # 上传接口地址（必填）CUSTOM_ACCESS_DOMAIN=https://cdn.your-api.com # （可选）文件访问域名前缀CUSTOM_UPLOAD_FIELD=file # （可选）上传文件字段名，默认 fileCUSTOM_RESPONSE_URL_FIELD=data.url # （可选）响应中 URL 字段的 JSON 路径，默认 data.urlCUSTOM_AUTH_HEADER=Authorization: Bearer token # （可选）自定义认证请求头CUSTOM_PATH_PREFIX=uploads # （可选）存储路径前缀

注意：自定义上传接口应返回 JSON 格式，示例：{ "code": 0, "data": { "url": "https://cdn.example.com/xxx.png" } }。

十五、方式三：扩展其他存储服务

如果需要接入 AWS S3、阿里云 OSS 等，可按以下步骤扩展：

1. 在 packages/server/src/services/storage/ 下创建 YourProvider.js，继承 StorageProvider 基类。

2. 在 packages/server/src/services/storage/index.js 的 PROVIDER_MAP 中注册。

3. 在 .env 中设置 STORAGE_PROVIDER=your_key 并添加对应配置项。

十六、内容审核能力

内容审核能力需要使用云 API 功能，因此需要开通对应能力以及配置相关密钥才能使用。

编辑 packages/server/config/.env：

# 腾讯云 API 密钥（内容审核、违规标签等功能依赖）TENCENT_CLOUD_SECRET_ID=xxxx # 请替换腾讯云 SecretIdTENCENT_CLOUD_SECRET_KEY=xxxx # 请替换腾讯云 SecretKey

注意：说明：

注意：TENCENT_CLOUD_SECRET_ID 和 TENCENT_CLOUD_SECRET_KEY 用于调用腾讯云 IM 审核 API（文本审核、纠错白名单）及 TRTC 审核标签查询 API（违规标签展示）。如何获取参见 腾讯云 API 密钥管理。

十七、音视频违规标签展示

需要接入 音视频内容理解 能力。

十八、直播间评论内容审核（机器审核）

需要接入 文本审核 能力。

十九、二次开发

入口项目（packages/react）完全开源，可自由调整页面结构、导航菜单、品牌标识和页面样式。业务能力可通过以下方式灵活扩展：

·品牌与外观定制：通过 live-manager.ts 自定义页面标题、Logo、品牌信息等。

·组件定制：通过设置组件的属性和插槽来渲染自定义内容。

·服务端扩展：通过 packages/server 中的 Provider 机制扩展存储、鉴权等后端能力。

注意：如有更高的定制化需求，我们提供更为灵活的 SDK 方式来进行开发。

20、品牌与菜单配置

项目中的 packages/react/src/live-manager.ts 是统一的配置文件，修改此文件即可定制品牌、菜单、插槽等所有内容：

import type { ComponentType, LazyExoticComponent } from 'react';import { configureLiveManager } from 'tuikit-live-manager-sdk-react';export default configureLiveManager<ComponentType | LazyExoticComponent<any>>({ brand: { appName: '我的直播管理系统', pageTitle: '直播管理后台', logoUrl: '/assets/my-logo.png', primaryColor: '#0052D9', }, menus: { hidden: [], rename: { 'live-list': '直播间管理' }, order: ['live-list', 'live-monitor', 'gift-config'], extraMenus: [], }, components: {}, features: { enableGift: true }, runtime: { apiBaseUrl: 'http://localhost:9000/api', language: 'zh-CN', },});

注意：说明：

注意：项目默认从 .env 文件读取环境变量，上述示例中使用的是硬编码值。实际使用时，建议通过 import.meta.env.VITE_* 从环境变量读取。

21、组件插槽

预置页面组件在关键位置提供了插槽，可通过 configureLiveManager 注入自定义 React 组件来扩展页面功能：

布局插槽

export default configureLiveManager<ComponentType | LazyExoticComponent<any>>({ components: { layout: { headerRight: MyHeaderWidget }, },});

LiveMonitor 直播监控页

示例：在监控卡片上添加自定义按钮

// live-manager.tsimport MyMonitorButton from './components/MyMonitorButton.tsx';export default configureLiveManager({ components: { liveMonitor: { userActionExtraItems: MyMonitorButton, }, },});

// MyMonitorButton.tsximport type { MonitorLiveInfo } from 'tuikit-live-manager-sdk-react';interface Props { live: MonitorLiveInfo }function MyMonitorButton({ live }: Props) { return ( <t-button variant="text" size="small"> 自定义操作 — {live.liveName} </t-button> );}

LiveList 直播间列表页

示例：在表格中添加自定义列

// live-manager.tsimport CustomColumn from './components/CustomColumn.tsx';export default configureLiveManager({ components: { liveList: { tableExtraColumns: CustomColumn, }, },});

// CustomColumn.tsximport type { MonitorLiveInfo } from 'tuikit-live-manager-sdk-react';import { Tag as TTag } from 'tdesign-react';interface Props { live: MonitorLiveInfo;}function CustomColumn({ live }: Props) { return ( <TTag theme={live.isMuted ? 'warning' : 'success'} variant="light"> {live.isMuted ? '已禁言' : '正常'} </TTag> );}export default CustomColumn;

LiveControl 直播间详情页

示例：添加自定义统计面板

// live-manager.tsimport CustomPanel from './components/CustomPanel.tsx';export default configureLiveManager({ components: { liveControl: { customControlPanel: CustomPanel, }, },});

// CustomPanel.tsximport { useMemo } from 'react';import type { MonitorLiveInfo, LiveStats } from 'tuikit-live-manager-sdk-react';interface Props { liveInfo: MonitorLiveInfo | null; stats: LiveStats;}function CustomPanel({ liveInfo, stats }: Props) { const revenueRate = useMemo(() => { if (!stats || stats.viewCount === 0) return '0'; return ((Number(stats.giftUserCount ?? 0) / stats.viewCount) * 100).toFixed(2); }, [stats]); return ( <t-card title="自定义统计" class="custom-panel"> <p>送礼转化率：{revenueRate}%</p> <p>累计点赞：{stats.likeCount.toLocaleString()}</p> <p>累计评论：{stats.commentCount.toLocaleString()}</p> </t-card> );}

GiftConfig 礼物配置页

示例：在礼物表格中显示分类标签

// live-manager.tsimport GiftCategoryTag from './components/GiftCategoryTag.tsx';export default configureLiveManager<ComponentType | LazyExoticComponent<any>>({ components: { giftConfig: { giftTableExtraColumns: GiftCategoryTag, }, },});

// GiftCategoryTag.tsximport type { GiftItem } from 'tuikit-live-manager-sdk-react';import { Space as TSpace, Tag as TTag } from 'tdesign-react';interface Props { gift: GiftItem;}function GiftCategoryTag({ gift }: Props) { const categories = gift.categories ?? []; return ( <TSpace size="small"> {categories.map(cat => ( <TTag key={cat} size="small" variant="light"> {cat} </TTag> ))} </TSpace> );}export default GiftCategoryTag;

22、生产部署

注意：说明：

23、方式一：自建部署

·服务端：修改配置后将 packages/server 部署到服务器，在该目录下运行 pnpm install，然后运行 node src/index.js 启动服务器。

·前端：修改 VITE_API_BASE_URL 后在根目录下 pnpm run build:react，将构建产物部署到静态资源服务器如 Nginx，也可以把构建产物放到之前服务器的 public 目录下，可以和服务器共用端口，此时可以配置 VITE_API_BASE_URL=/api，前端使用相对路径请求 api 接口。

24、方式二：云函数 + COS / EdgeOne Pages

·服务端：在根目录下运行 pnpm run deploy:server 然后将 packages/server/dist/scf-deploy.zip 上传至腾讯 云函数（Web 函数，Node.js 20.19）。

·前端：创建 .env.production 设置云函数请求地址后，在根目录下 pnpm run build:react，将构建产物上传至 COS 或 EdgeOne Pages。

VITE_API_BASE_URL=https://your-scf-url.com/api

注意：your-scf-url.com 要替换成实际的域名和端口。

25、相关文档

·准备工作（Web React）

·开通 TUILiveKit 服务

·TUILiveKit 管理员账号管理

·开通内容理解服务（国内）

·云端审核

·云函数新手指引

·COS ( 对象存储 ) 快速入门

·EdgeOne ( 边缘安全加速平台 ) Pages