【Ray教程】小智本地化源码部署服务端全流程

资料链接：https://github.com/Zeng-Guo/xiaozhi

小智AI服务端代码：https://github.com/xinnan-tech/xiaozhi-esp32-server#

小智AI硬件代码：https://github.com/78/xiaozhi-esp32

小智AI百科全书：https://ccnphfhqs21z.feishu.cn/wiki/F5krwD16viZoF0kKkvDcrZNYnhb

001小智服务端首次部署

视频教程地址：手把手本地部署小智前后端代码教程_哔哩哔哩_bilibili

官方教程：xiaozhi-esp32-server/docs/Deployment_all.md at main · xinnan-tech/xiaozhi-esp32-server · GitHub

一、创建小智服务端的数据库

前置准备：下载并安装小皮面板（phpstudy）

下载地址：Windows 版 phpstudy 下载 - 小皮面板 (phpstudy)

具体操作步骤

1. 打开小皮面板，进入「软件管理」功能模块，找到并安装 MySQL 8.0.12 版本数据库。
2. 仍在「软件管理」界面，搜索并安装 Redis 3.0.504 版本（小智服务端需 Redis 做缓存）。
3. 继续在「软件管理」中，下载数据库管理工具 phpMyAdmin 4.8.5 版本。
4. 返回小皮面板首页，依次启动以下服务：apache 2.4.39、MySQL 8.0.12、Redis 3.0.504（确保所有服务状态为 “已启动”）。
5. 进入面板「数据库」模块，找到「修改 root 密码」选项，将密码修改为 123456 并保存（记牢该密码，后续连接数据库需用）。
6. 点击页面右上方的「数据库管理工具」按钮，在弹出选项中选择「phpmyadmin」。
7. 在跳转的 phpMyAdmin 网页登录界面，输入用户名 root、密码 123456，点击「登录」完成验证。
8. 登录成功后，点击左侧 / 主界面的「新建」按钮，在「数据库名」输入框中填写 xiaozhi_esp32_server，排序规则选择 utf8_unicode_ci，点击「创建」完成数据库初始化。

二、搭建小智服务端开发运行环境（JDK21 + Maven + VSCode）

1. 安装并配置 JDK21 环境（小智服务端核心运行依赖）

• 参考教程：Java 官网下载 JDK21 版本详细教程（下载、安装、环境变量配置）_jdk21 下载 - CSDN 博客

2. 安装并配置 Maven 环境（Java 项目构建 / 依赖管理工具）

• 参考教程：Maven 的安装和环境变量配置_安装 maven 并配置环境变量 - CSDN 博客

3. 安装 VSCode 并配置 Java 开发插件

• 参考教程：VSCode 安装配置使用教程（最新版超详细保姆级含插件）一文就够了_vscode 使用教程 - CSDN 博客

• 具体操作：

  ① 下载并安装 VSCode（建议选择 Windows 64 位版本）；

  ② 打开 VSCode，点击左侧栏「扩展」图标（快捷键 Ctrl+Shift+X），在搜索框输入

  Java Extension Pack
  

  点击「安装」（该插件包包含小智服务端开发所需的 Java 语言支持、调试、代码提示等核心功能）；

  ③ 安装完成后重启 VSCode，确保插件生效；

  ④ 可选补充：额外安装

  Chinese (Simplified) Language Pack
  

  插件，将 VSCode 切换为中文界面，降低新手操作难度。

三、启动小智服务端 Java 后端

前置准备

小智服务端项目地址：GitHub - xinnan-tech/xiaozhi-esp32-server（核心后端代码仓库）

具体操作步骤

1. 下载并整理项目文件

   ① 从 GitHub 下载项目压缩包，解压后默认文件夹名称为 xiaozhi-esp32-server-main，将其重命名为 xiaozhi-esp32-server；

   ② 打开 VSCode，点击「文件」→「打开文件夹」，选择重命名后的 xiaozhi-esp32-server 文件夹，确认打开（VSCode 会自动加载 Java 项目依赖）。

2. 修改数据库连接核心配置

   ① 在 VSCode 的文件管理器中，找到路径：xiaozhi-esp32-server\main\manager-api\src\main\resources，打开 application-dev.yml 文件（开发环境配置文件，核心配置入口）；

   ② 找到数据库（MySQL）和 Redis 相关配置项，按以下内容修改（匹配第一步创建的数据库信息）：

数据库配置（关键修改项）

spring:
datasource:
url: jdbc:mysql://127.0.0.1:3306/xiaozhi_esp32_server?useUnicode=true&characterEncoding=utf8mb4&useSSL=false&serverTimezone=Asia/Shanghai
username: root
password: 123456 # 对应第一步修改的MySQL root密码
# Redis配置（匹配小皮面板的Redis服务）
redis:
host: 127.0.0.1
port: 6379
password: ‘’ # 小皮面板默认Redis无密码，若有则填写

③ 保存 `application-dev.yml` 文件（快捷键 Ctrl+S），确保配置修改生效。



3. **启动后端程序**

① 在 VSCode 文件管理器中，找到路径：`xiaozhi-esp32-server\main\manager-api\src\main\java\xiaozhi`，打开 `AdminApplication.java` 文件（这是后端项目的启动类，含 main 方法）；

② 点击文件顶部 / 代码左侧的「运行」按钮（或右键选择「运行 Java」），启动程序；

③ 观察 VSCode 下方「终端」面板：若输出 “Started AdminApplication in XX seconds”（无红色报错），说明后端启动成功；若提示 “数据库连接失败”“Redis 连接失败”，需检查第一步的服务是否启动、配置文件的账号密码是否正确。



#### 四、启动小智服务端 Web 前端并配置 AI 模型

##### 1. 安装并验证 Node.js 环境（前端运行核心依赖）

- 参考教程：[2024 最新版 Node.js 下载安装及环境配置教程【保姆级】_nodejs 下载 - CSDN 博客](https://blog.csdn.net/whf__/article/details/129362462?ops_request_misc=elastic_search_misc&request_id=993b60bd6ddcf3742f9c2cb2c64ebbec&biz_id=0&utm_medium=distribute.pc_search_result.none-task-blog-2~all~top_positive~default-1-129362462-null-null.142^v102^pc_search_result_base3&utm_term=nodejs安装及环境配置&spm=1018.2226.3001.4187)

##### 2. 进入前端项目目录

① 右键点击「开始菜单」→ 选择「Windows 终端（管理员）」（或「命令提示符（管理员）」），以管理员身份打开 CMD；

② 在终端中执行目录切换命令（替换为你的实际项目路径）：

示例：若项目放在D盘根目录，路径为D:\xiaozhi-esp32-server

cd D:\xiaozhi-esp32-server\main\manager-web

##### 3. 安装前端项目依赖

① 在当前终端执行依赖安装命令：

npm install

##### 4. 启动 Web 前端服务

① 依赖安装完成后，执行启动命令：

npm run serve

② 验证启动成功：终端输出 “Compiled successfully” 或 “Server running at http://127.0.0.1:8001”（无红色报错）；

③ 打开浏览器，访问地址：`http://127.0.0.1:8001`，即可进入小智服务端管理前端页面。

##### 5. 配置智谱 AI API 密钥（核心功能）

① 首次访问页面，点击「注册账号」完成注册（**第一个注册的用户自动成为超级管理员**，需记牢账号密码）；

② 用注册的账号登录系统，点击顶部菜单「模型配置」，左侧导航栏选择「大语言模型」；

③ 找到「智谱 AI」选项，点击右侧「修改」按钮；

④ 前往智谱 AI 开放平台获取 API 密钥（链接：[智谱 AI 开放平台](https://www.bigmodel.cn/usercenter/proj-mgmt/apikeys)，需先注册并实名认证）；

⑤ 将获取的 API 密钥（api_key）填入输入框，点击「保存」，完成大语言模型的核心配置（保存后即可正常使用语音对话、AI 问答功能）。



#### 五、安装 Python 环境并运行小智核心语音服务

##### 1. 安装 Anaconda（Python 环境管理工具）

- 参考教程：[最新版最详细 Anaconda 新手安装 + 配置 + 环境创建教程_anaconda 配置 - CSDN 博客](https://blog.csdn.net/qq_44000789/article/details/142214660)

##### 2. 创建并配置专属 Python 虚拟环境

启动「Anaconda Prompt」（非管理员模式即可），按顺序逐行执行以下命令（每执行一行等待完成，建议复制输出结果给AI核对是否有报错）：

先删除同名旧环境（若有），避免冲突

conda remove -n xiaozhi-esp32-server --all -y

创建名为xiaozhi-esp32-server的虚拟环境，指定Python 3.10版本（核心依赖要求）

conda create -n xiaozhi-esp32-server python=3.10 -y

激活该虚拟环境（激活后终端前缀会显示(xiaozhi-esp32-server)）

conda activate xiaozhi-esp32-server

添加清华源（解决conda下载包缓慢/失败问题）

conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge

安装语音处理依赖（libopus用于音频编码，ffmpeg用于音频格式转换）

conda install libopus -y
conda install ffmpeg -y

##### 3. 安装项目 Python 依赖

① 打开「Anaconda Powershell Prompt」（或继续使用已激活环境的 Anaconda Prompt）；

② 切换到小智服务端 Python 项目目录（替换为你的实际路径）：

示例：若项目在D盘，路径为D:\xiaozhi-esp32-server

cd D:\xiaozhi-esp32-server\main\xiaozhi-server

③ 逐行执行以下命令（每执行一行核对无报错）：

确保激活目标虚拟环境

conda activate xiaozhi-esp32-server

配置阿里云pip镜像（解决pip下载依赖缓慢）

pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

安装项目所需全部依赖（核心步骤，耐心等待完成）

pip install -r requirements.txt

##### 4. 下载语音识别模型文件

① 下载地址：[SenseVoiceSmall 模型文件](https://modelscope.cn/models/iic/SenseVoiceSmall/resolve/master/model.pt)；

② 将下载的`model.pt`文件放入文件夹（文件夹路径：`xiaozhi-esp32-server\main\xiaozhi-server\models\SenseVoiceSmall`），**确认文件路径无误**（模型文件缺失会导致语音识别功能失效）。

##### 5. 配置项目核心参数文件

① 先确保 Web 前端已启动，访问智控台：`http://127.0.0.1:8001`，用超级管理员账号登录；

② 点击顶部菜单「参数管理」，在参数列表中找到**参数编码为 server.secret**的项，复制其对应的「参数值」；

③ 回到项目目录：`xiaozhi-esp32-server\main\xiaozhi-server`，新建文件夹命名为`data`；

④ 将该目录下的`config.yaml`文件复制到`data`文件夹中，并重命名为`.config.yaml`（注意开头有英文句号，是隐藏文件）；

⑤ 打开`.config.yaml`文件，删除原有所有内容，粘贴以下配置（替换`你的server.secret值`为实际复制的参数值）：

manager-api:
url: http://127.0.0.1:8002/xiaozhi # 后端API地址，默认无需修改
secret: 你的server.secret值 # 替换为复制的server.secret参数值

⑥ 保存文件（确保无格式错误，如空格缩进、冒号后空格）。

##### 6. 运行 Python 核心服务

① 确保终端仍在`xiaozhi-server`目录下，且已激活虚拟环境（`(xiaozhi-esp32-server)`前缀）；

② 执行启动命令：

python app.py

③ 验证启动成功：终端输出 “WebSocket server started on xxx”“TTS service ready” 等日志，无红色报错（若提示 “config.yaml not found”，检查`.config.yaml`路径和名称是否正确）；

④ 启动成功后，小智服务端的语音识别、AI 对话、TTS 合成等核心功能即可正常使用。





## 002小智服务端日常快速启动步骤（按顺序执行）

### 1. 启动基础服务（小皮面板）

双击小皮面板桌面快捷方式，进入面板首页后，**确保以下服务处于「已启动」状态**：

- apache 2.4.39

- MySQL 8.0.12

- Redis 3.0.504

  （若未启动，点击对应服务右侧「启动」按钮）

### 2. 启动 Java 后端服务API

① 打开 VSCode，加载小智服务端项目文件夹 `xiaozhi-esp32-server`；

② 在 VSCode 文件管理器中找到路径：`main\manager-api\src\main\java\xiaozhi`，打开 `AdminApplication.java`；

③ 点击文件内「运行」按钮（或右键选择「运行 Java」）；

### 3. 启动 Web 前端服务

① 右键点击 Windows「开始菜单」→ 选择「Windows 终端（管理员）」；

② 切换到前端项目目录（替换为实际路径）：

cd D:\xiaozhi-esp32-server\main\manager-web

③ 启动前端服务：

npm run serve

### 4. 启动 Python 核心服务Server

① 打开「Anaconda Powershell Prompt」；

② 切换到 Python 项目目录（替换为实际路径）：

cd D:\xiaozhi-esp32-server\main\xiaozhi-server

③ 激活虚拟环境并启动服务（逐行执行）：

激活专属虚拟环境

conda activate xiaozhi-esp32-server

启动Python语音服务

python app.py