小智聊天機器人本地后臺服務器源碼全模塊部署
作者：林甲酸 -不是小女子也不是女漢子 是大女子
更新日期：2025年4月29日
🎯 前言：為什么要寫這篇教程？
上周按照蝦哥小智服務器的教程去部署本地后臺，我用的是本地源碼運行全模塊的方法去部署，雖然照著文字教程去部署了，但是教程一看要安裝好多東西啊，我是一個硬件的，對于服務器這塊也不熟悉，一路坎坎坷坷，還好借助各類gpt解決了問題。感謝AI工具🙏。如果你也跟我一樣看著教程有些下不去手，或許你可以參考我這篇文章開始動手，幫您少走一步彎路。：
本文將用最直白的語言+圖解，帶你完成全模塊部署！
注：部署過程也不是一次就能搞定的，出現問題可以備注交流，文章是經過驗證后才寫的，如果錯誤請指正，歡迎交流！
采用本地源碼運行全模塊的好處是，你可以體驗最全的小智大模型各類工具。
聲明，本文參考了：
小智源碼文檔
本地源碼運行全模塊步驟
小智硬件源碼
下面跟著蝦哥本地源碼運行全模塊的流程來吧！
📦 環境總覽
| 組件 | 版本 | 用途 |
|---|---|---|
| Docker | 最新版 | 容器化部署數據庫 |
| MySQL | 8.0+ | 數據存儲 |
| Redis | 7.0+ | 緩存服務 |
| JDK | 21 | 后端運行環境 |
| Python | 3.10 | AI模型推理 |
🔧 一、安裝MySQL數據庫
1. 先安裝Docker
通過docker安轉MySQL。這里因為我是沒有MySQL，所以我采取了使用Docker安裝。我用的Docker是在官方下載的，我并沒有按照他上面給的方式去安裝，感覺看的不清晰。
（1）安裝Docker我是win11系統，我選擇了第3個。
（2）安裝的時候記得要關閉所有殺毒軟件！關閉所有防火墻！安裝的時候使用管理員運行.exe文件，安裝的時候按照默認選擇。
（2）安裝好后關閉，然后重新管理員運行打開軟件。進入界面時Accept一下條款，然后Skip跳過介紹。
（3）Docker設置。這一步是在 Docker Desktop 里開啟 WSL 2 集成，目的是讓 Docker 可以直接在你的 WSL 2（例如 Ubuntu）環境中運行容器。點擊設置->Resources->WSL integration，然后打開Ubuntu的按鈕，為了讓你的 Ubuntu WSL 環境可以直接用 Docker。
這里我當時安裝的時候沒有出現Ubuntu的按鈕，是因為當時我的系統尚未安裝任何WSL 2發行版。如果你沒有遇到這個問題可以跳過這里。解決方法：
① 安裝WSL 2發行版
wsl –install
②將發行版設置為WSL 2模式
wsl --set-version Ubuntu 2
③驗證是否成功
wsl --list –verbose
確認輸出中包含Ubuntu且版本為WSL 2。然后在關閉、管理員重啟Docker，就可以看到這里有這個Ubuntu選項了。
（4）接下來。在Docker Desktop 中設置 磁盤鏡像存儲位置，Docker Desktop 會把所有的數據（包括鏡像、容器、卷）存在 C 盤，如果不改路徑，時間長了 C 盤可能爆滿。我選擇了D盤。然后點擊Apply&restart。
等待安裝好后，管理員打開Docker，這樣就安裝好這個大部頭。
2. 通過docker安轉MySQL
安裝好 Docker 后，確保Docker打開的狀態。你可以通過 命令行終端PowerShell，通過docker安裝mysql。
這個時候你可以看到在Docker中看到當前系統正在運行一個MySQL容器
🔧 二、安裝redis
如果還沒有Redis，你可以通過docker安裝redis
回車之后，可以看到redis啟動運行
🔧 三、運行manager-api程序（后端服務）
1. 安裝JDK21
① JDK下載網址：Java 。我是window系統行4位。解壓后，可安裝到D盤。D:\JDK21_0_6
② 設置JDK的path環境變量。首先是Path環境變量設置。在“系統變量”區域找到并選中 Path，然后點擊“編輯”。 在編輯窗口中，點擊“新建”，添加以下JDK的安裝路徑
③ 設置JDK的JAVA_HOME 環境變量。在“系統變量”部分點擊“新建”， 變量名：JAVA_HOME，變量值：JDK 安裝路徑。
④ 可以打開PowerShell，驗證 JDK 是否安裝成功
java -version
如果返回類似下面的結果，說明 JDK 已正確安裝
java version "21" 2025-03-21
Java(TM) SE Runtime Environment (build 21+36-2239)
Java HotSpot(TM) 64-Bit Server VM (build 21+36-2239, mixed mode)
2.安裝Maven
① Maven 壓縮包（下載 Maven 的二進制 zip 文件）。我安裝到D:\JDK21_0_6
②解壓 Maven 到 D 盤，例如：D:\Apache\Maven。
③設置環境變量
? MAVEN_HOME：指向你解壓 Maven 的目錄（例如：D:\Apache\Maven）。
? Path：將 Maven 的 bin 目錄添加到 Path 環境變量中（例如：D:\Apache\Maven\bin）。
3.安裝Java環境相關插件
打開 VSCode，安裝 Java 插件（例如：Java Extension Pack）以支持 Java 開發
4.使用Vscode編程工具加載manager-api模塊
首先你需要去下載源碼
蝦哥源碼地址 解壓后按照蝦哥的教程你需要“把它重命名成xiaozhi-esp32-server，我把工程放在了E盤，然后使用VScode打開路徑“E:\xiaozhi-esp32-server\main\manager-api”。
①按照蝦哥提供的配置，將數據庫連接信息填入
src/main/resources/application-dev.yml中：
spring:datasource:username: root
password: 123456
② 在src/main/resources/application-dev.yml中配置Redis連接信息
spring:data:redis:host: localhostport: 6379password:database: 0
5.運行manager-api程序
一定要確保你的Docker是打開的，這倆是在運行的情況下，再去運行程序。
當你看到輸出日志時，說明你的manager-api啟動成功了。
🔧四、運行manager-web程序（前端控制臺）
1. 安裝nodejs
（下面的步驟都是按照蝦哥的教程來的）
nodejs的安裝地址：Node.js — 在任何地方運行 JavaScript
2. 使用Vscode編程工具加載manager-web模塊
①終端命令進入manager-web目錄下。
npm install
② 啟動
npm run serve
③ 到這一步，運行成功后，打開智控臺，鏈接：http://127.0.0.1:8001，注冊第一個用戶。第一個用戶即是超級管理員，以后的用戶都是普通用戶。然后在里面配置你的LLM密鑰。這一步可以去申請阿里或者智譜的密鑰，網上很多，我就不描述了。
重要：注冊成功后，使用超級管理員賬號，登錄智控臺，在頂部菜單找到模型配置，然后在左側欄點擊大語言模型，找到第一條數據智譜AI，點擊修改按鈕， 彈出修改框后，將你注冊到的智譜AI的密鑰填寫到API密鑰中。然后點擊保存。然后窗口別關閉了。
注意：采用豆包語音識別請看，沒有可跳過這里。你如果使用豆包然后tts報錯的話，你應該是voice_type參數出錯了。別問我為啥知道…
如果你開通了豆包的語音識別，然后有這些參數
你可以按照我這個參數去修改豆包的語音合成。
然后要記得在外面這里音色管理修改參數編碼，根據你開通填的音色去修改
🔧五、安裝Python環境
我按照蝦哥的教程使用 Conda 創建 Python 環境，這一步是為本地化運行的語音交互、設備通信、AI模型推理等關鍵功能提供隔離、穩定的Python運行時環境。因此需要先去安裝Anaconda。
1. 安裝清華鏡像源的Anaconda
盡量安裝Anaconda3-5.3.0后面的版本，python版本3.6。安裝我是安裝在D盤的
2. 通過conda_prompt運行指令
(1) 使用管理員身份運行
（2）執行命令
conda remove -n xiaozhi-esp32-server --all -y
conda create -n xiaozhi-esp32-server python=3.10 -y
conda activate xiaozhi-esp32-server# 添加清華源通道
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-forgeconda install libopus -y
conda install ffmpeg -y
安裝libopus可能會出現如下報錯：
你可以嘗試：指定conda-forge安裝
libopus主要在conda-forge倉庫中，可以指定從conda-forge安裝：
conda install -c conda-forge libopus -y
上面的命令都要一步一步執行下來。出現問題，及時問AI。
🔧六、運行源碼依賴
1. 安裝依賴
# 繼續使用conda環境
conda activate xiaozhi-esp32-server
# 進入到你的項目根目錄，再進入main/xiaozhi-server
cd main/xiaozhi-server
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
pip install -r requirements.txt
🔧七、 下載語音識別模型文件
還是按照蝦哥的教程去下載語音識別模塊，然后下載后把model.pt文件放在models/SenseVoiceSmall目錄下線路 百度網盤下載SenseVoiceSmall 提取碼:qvna
🔧八、 配置項目文件
1. 復制server.secret參數
使用 超級管理員賬號 登錄系統管理后臺（智控臺），在頂部菜單找到參數管理（參數編碼為server.secret），找到列表中第一條數據，參數編碼是server.secret,它是隨機生成的，每次重新部署都會隨機生成，復制它到參數值。
2. 配置.config.yaml文件
打開整一個源碼文件，進入xiaozhi-server目錄，檢查是否存在data文件夾，如果沒有data目錄，請手動創建。如果 data 目錄下沒有 .config.yaml 文件，執行以下操作：
將 xiaozhi-server 目錄下的 config_from_api.yaml 復制到 data 目錄。重命名復制的文件為 .config.yaml
將復制的server.secret值粘貼到secret字段中。
🔧九、 運行xiaozhi-esp32-server項目
1.運行本地服務端
在剛剛安裝依賴的環境下繼續執行
# 確保在xiaozhi-server目錄下執行
conda activate xiaozhi-esp32-server
python app.py
如果出現上面的結果，表示你的server端已經部署好了。接下來就是跟小智硬件的結合。注意看返回的ws://xxx.xx.xx.xx:8000/xiaozhi/v1/，其中xxx.xx.xx.xx就是你本地的地址，后面都會用到。
2.硬件接口更新
接下來你可以去在智控臺更新硬件接口。
①使用超級管理員賬號，登錄智控臺，在頂部菜單找到參數管理，找到參數編碼是server.websocket，輸入你的Websocket接口。
②使用超級管理員賬號，登錄智控臺，在頂部菜單找到參數管理，找到數編碼是server.ota，輸入你的OTA接口。
不知道為啥我沒找到，所以我通過手動新增了這兩個參數
🔧十、 小智硬件燒錄
打開小智的硬件源碼程序。
- OTA接口更新
http://你電腦局域網的ip:8002/xiaozhi/ota/
- Websocket接口更新
ws://你電腦局域網的ip:8000/xiaozhi/v1/
這里我是寫在Kconfig.projbuild文件里面，后面配置的時候會根據這個文件去更新。記得保存
你可以點擊下方的設置那里，查看右邊配置有沒有更新到，沒有問題可以下載到小智硬件了。
硬件燒錄成功后，根據屏幕播報的設備碼填寫到控制臺。點擊智能體管理，還沒新建智能體的話，就新建一個，然后填寫設備管理，綁定播報的6位驗證碼。
然后點擊硬件重啟設備。接下來就是見證奇跡的時候。
總結：
通過上述步驟，你已經成功在本地部署了小智服務器。無論是后端服務的管理、前端控制臺的操作，還是語音交互與硬件控制的集成，都可以在本地環境中完成。這種部署方式給開發者提供了極大的靈活性，同時也幫助你更深入地理解整個系統的工作流程。希望本文能幫助你少走彎路，順利搭建起屬于自己的智能硬件系統。
)
)
