需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

部署后端服务

更新时间不可用

了解如何在语聊房中部署后端服务，包括适用场景、配置步骤、实现要点和注意事项。

本文介绍如何使用语聊 UI Kit 的后端服务。

源代码你可参考 AUIKit/backend 示例项目：

AUIKit/backend

项目简介

AUIKit/backend 项目基于 Spring Boot 框架开发，依赖以下组件：

  • Redis：用于缓存记录，例如缓存语聊 UI Kit 的后端上生成的用于环信 IM 服务的 Token。
  • MongoDB：用于维护房间列表。

如果你想深入了解项目源代码，可以参考项目文件介绍。

服务部署

1. 快速体验

本节介绍如何快速体验示例项目中已经搭建好的后端服务。

前提条件

请确保已经安装如下环境或工具：

你可以直接下载安装 Docker Desktop 工具，它已默认安装 docker-compose。

运行步骤

以下是运行服务的步骤：

  1. 在项目根目录创建 .env 文件，并填入以下字段：

    Text
    WHITELIST_TOKEN_APP_ID=<your_app_id>
WHITELIST_TOKEN_APP_CERT=<your_app_cert>
WHITELIST_CHAT_ROOM_APP_ID=<your_app_id>
WHITELIST_CHAT_ROOM_ORG_NAME=<your_easemob_org_name>
WHITELIST_CHAT_ROOM_APP_NAME=<your_easemob_app_name>
WHITELIST_CHAT_ROOM_CLIENT_ID=<your_easemob_client_id>
WHITELIST_CHAT_ROOM_CLIENT_SECRET=<your_easemob_client_secret>
WHITELIST_RTC_KICK_OUT_AUTH_APP_ID=<your_app_id>
WHITELIST_RTC_KICK_OUT_AUTH_BASIC_AUTH=<your_http_basic_auth>

    你可以在开通声网服务后，获取这些字段的值，详情如下：

    字段名字段描述获取方式
    • WHITELIST_TOKEN_APP_ID
    • WHITELIST_CHAT_ROOM_APP_ID
    • WHITELIST_RTC_KICK_OUT_AUTH_APP_ID
    		声网项目的 App ID，用于登录 RTC 和 RTM 系统获取 App ID
    WHITELIST_TOKEN_APP_CERT声网项目的 App 证书，用于登录 RTC 和 RTM 系统获取 App 证书
    WHITELIST_CHAT_ROOM_ORG_NAME环信 IM 服务的 Org Name，用于创建 IM 聊天室获取 IM 信息
    WHITELIST_CHAT_ROOM_APP_NAME环信 IM 服务的 App Name，用于创建 IM 聊天室获取 IM 信息
    WHITELIST_CHAT_ROOM_CLIENT_ID环信 IM 服务的 Client ID，用于创建 IM 聊天室登录环信管理后台，到应用列表 > 查看获取
    WHITELIST_CHAT_ROOM_CLIENT_SECRET环信 IM 服务的 Client Secret，用于创建 IM 聊天室登录环信管理后台，到应用列表 > 查看获取
    WHITELIST_RTC_KICK_OUT_AUTH_BASIC_AUTH声网频道管理 RESTful 服务所需的 HTTP 基本认证的 Authorization 值，该服务可用于实现封禁 RTC 频道内的用户权限获取客户 ID 和客户密钥，再生成 HTTP 基本认证的 Authorization 值
    表格内容超出当前宽度，可横向滚动查看更多列。

  2. 在项目根目录下执行以下命令启动服务：

    Shell
    docker compose up -d --build

    该命令会拉取所需的镜像并启动 Redis 和 MongoDB 服务，并对本后端服务进行编译。如果遇到镜像拉取失败的问题，你可以通过配置国内镜像源解决。

  3. 服务启动后，继续输入如下命令进行测试：

    Shell
    curl http://localhost:8080/health/check

  4. 如果你需要使用移动端 App 调试本地服务，你需要将移动端 App 上对应的后端服务域名替换成如下：

    Text
    http://<your_ip>:8080

    your_ip 为本地运行服务的机器 IP 地址。

  5. 如果你需要停止服务，执行如下命令：

    Shell
    docker compose down

2. 本地开发

本节介绍如何通过 Visual Studio Code（简称 VS Code）工具在本地开发语聊后端服务。如果你使用其他工具，你也可以参考本节步骤进行相应操作。

前提条件

除了满足快速体验时的前提条件外，还需确保已经安装如下环境或工具：

  • Java 11 或之后
  • VS Code 编辑器
  • VS Code 插件：Extension Pack for Java

开发步骤

以下是本地开发的步骤：

  1. 使用 VS Code 打开项目目录，并进入容器开发模式。

    在 Docker 容器中开发时可以使用示例项目中的 Dockerfile，相关配置项已经在该文件中设置。

  2. 修改 application.yml 配置文件中的以下内容：

    • spring.data.mongodb.uri：将应用连接到数据库。
    • spring.redis.host：配置 Redis 缓存。
    • spring.redis.password：配置 Redis 缓存。
    • whitelist.token.appId
    • whitelist.token.appCert
    • whitelist.chatRoom.appId
    • whitelist.chatRoom.orgName
    • whitelist.chatRoom.appName
    • whitelist.chatRoom.clientId
    • whitelist.chatRoom.clientSecret
    • whitelist.rtcKickOutAuth.appId
    • whitelist.rtcKickOutAuth.basicAuth

    spring.* 之外的内容含义详见字段描述。

  3. 构建并运行 Spring Boot 应用。

3. 上线部署

完成本地开发后，你还需要进行以下操作才能将服务部署上线：

  1. 根据本地开发中的步骤 2 检查 application.yml 中字段内容填写无误。

  2. 调整 Redis 和 MongoDB 配置。

  3. 将服务部署在网关。网关可提供鉴权和限流等能力。本示例项目中展示的服务暂时未包含网关能力。

  4. 设置指标收集。通过 https://<your_hostname>:9090/metrics/prometheus 收集指标进行服务监控。

  5. 将服务部署在云平台，例如阿里云容器服务（ACK）。

项目文件介绍

本节介绍 AUIKit/backend 下目录结构和各文件用途。

.
├── Dockerfile                                                          // 项目构建镜像
├── HELP.md
├── README.md
├── README_zh.md
├── docker-compose.yaml                                                 // 本地一键部署
├── init-mongo.js                                                       // MongoDB 初始化
├── mvnw
├── mvnw.cmd
├── pom.xml
├── src
│   ├── main
│   │   ├── java
│   │   │   └── io
│   │   │       └── agora
│   │   │           └── uikit
│   │   │               ├── Application.java                            // 启动文件
│   │   │               ├── bean                                        // 对象类
│   │   │               │   ├── domain                                  // 实体类
│   │   │               │   ├── dto                                     // 传输类
│   │   │               │   ├── entity                                  // DB 实体类
│   │   │               │   ├── enums                                   // 枚举
│   │   │               │   ├── exception                               // 异常处理
│   │   │               │   │   └── BusinessException.java
│   │   │               │   ├── req                                     // 请求类
│   │   │               │   └── valid                                   // 校验
│   │   │               │       ├── EnumValid.java
│   │   │               │       └── EnumValidator.java
│   │   │               ├── config                                      // 配置
│   │   │               │   ├── GlobalExceptionHandler.java             // 全局异常捕获
│   │   │               │   ├── RedisConfig.java                        // Redis 配置
│   │   │               │   ├── ChatRoomAPIClient.java                  // 环信 IM 配置
│   │   │               │   ├── RtcChannelAPIClient.java                // RTC 踢人配置
│   │   │               │   ├── WhitelistConfig.java                    // 白名单配置
│   │   │               │   └── WebMvcConfig.java                       // MVC 配置
│   │   │               ├── controller                                  // 控制器
│   │   │               │   ├── HealthController.java                   // 健康检查
│   │   │               │   ├── ChatRoomV2Controller.java               // 语言聊房
│   │   │               │   ├── RoomV2Controller.java                   // 房间管理
│   │   │               │   ├── UserController.java                     // 用户管理，提供踢人能力
│   │   │               │   └── TokenV2Controller.java                  // Token 管理
│   │   │               ├── interceptor                                 // 拦截器
│   │   │               │   ├── PrometheusMetricInterceptor.java        // 指标拦截器
│   │   │               │   └── TraceIdInterceptor.java                 // 链路追踪
│   │   │               ├── metric                                      // 指标上报
│   │   │               │   └── PrometheusMetric.java
│   │   │               │── repository                                  // DB 访问层
│   │   │               │   └── RoomListV2Repository.java
│   │   │               ├── service                                     // 服务层
│   │   │               │   ├── IRoomV2Service.java                     // 房间服务
│   │   │               │   ├── IChatRoomV2Service.java                 // 语聊房服务
│   │   │               │   ├── IEMAPIService.java                      // 语聊房接口 feign 定义
│   │   │               │   ├── IChatRoomAPIService.java                // 语聊房接口
│   │   │               │   ├── IUserService.java                       // 用户管理接口
│   │   │               │   ├── IRtcChannlAPIService.java               // 踢人接口 feign 定义
│   │   │               │   ├── IRtcChannlService.java                  // 踢人接口
│   │   │               │   ├── ITokenV2Service.java                    // Token 服务
│   │   │               │   └── impl
│   │   │               │       ├── RoomV2ServiceImpl.java
│   │   │               │       ├── ChatRoomV2ServiceImpl.java
│   │   │               │       ├── ChatRoomAPIServiceImpl.java
│   │   │               │       ├── RtcChannelServiceImpl.java
│   │   │               │       ├── UserServiceImpl.java
│   │   │               │       └── TokenV2ServiceImpl.java
│   │   │               └── utils                                       // 工具类
│   │   │                   ├── RedisUtil.java                          // Redis 操作
│   │   │                   └── TokenUtil.java                          // Token 操作
│   │   └── resources
│   │       ├── application.yml                                         // 配置文件
│   │       └── logback-spring.xml                                      // 日志配置

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利