«

小智服务端部署步骤（OpenCloudOS 专用精简版）

熊猫老师 发布于 阅读：27

🎯 最稳定可靠的部署步骤（OpenCloudOS 专用精简版）

你只需要严格按照下面流程操作，保证一次成功。
我会把复杂点全部标红、全部避坑。
项目地址：https://github.com/xinnan-tech/xiaozhi-esp32-server

✅ 第一步：创建目录结构

执行：

mkdir -p /root/xiaozhi-server/data
mkdir -p /root/xiaozhi-server/models/SenseVoiceSmall

✅ 第二步：把 model.pt 放到正确目录

上传 model.pt 到：

/root/xiaozhi-server/models/SenseVoiceSmall/model.pt

⚠ 千万不要放错目录，不然 8000 端口永远启动失败。

✅ 第三步：下载 docker-compose_all.yml

进入目录：

cd /root/xiaozhi-server
wget https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/refs/heads/main/main/xiaozhi-server/docker-compose_all.yml

下载成功后，保证文件结构如下：

xiaozhi-server
  ├── docker-compose_all.yml
  ├── data
  ├── models/SenseVoiceSmall/model.pt

✅ 第四步：下载 config_from_api.yaml 并改名

cd /root/xiaozhi-server/data
wget https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/refs/heads/main/main/xiaozhi-server/config_from_api.yaml
mv config_from_api.yaml .config.yaml

确认：

/root/xiaozhi-server/data/.config.yaml

🚨 第五步（非常重要）：完全清理旧容器 + 镜像

进入目录：

cd /root/xiaozhi-server

执行：

docker compose -f docker-compose_all.yml down

强制删除所有旧容器：

docker stop xiaozhi-esp32-server 2>/dev/null
docker rm   xiaozhi-esp32-server 2>/dev/null

docker stop xiaozhi-esp32-server-web 2>/dev/null
docker rm   xiaozhi-esp32-server-web 2>/dev/null

docker stop xiaozhi-esp32-server-db 2>/dev/null
docker rm   xiaozhi-esp32-server-db 2>/dev/null

docker stop xiaozhi-esp32-server-redis 2>/dev/null
docker rm   xiaozhi-esp32-server-redis 2>/dev/null

删除旧镜像：

docker rmi ghcr.nju.edu.cn/xinnan-tech/xiaozhi-esp32-server:server_latest 2>/dev/null
docker rmi ghcr.nju.edu.cn/xinnan-tech/xiaozhi-esp32-server:web_latest 2>/dev/null

现在你的系统已经干净了。

🌟 第六步：启动新版本（关键步骤）

cd /root/xiaozhi-server
docker compose -f docker-compose_all.yml up -d

📌 第七步：查看 8002（后台 web）日志

docker logs -f xiaozhi-esp32-server-web

出现：

Started AdminApplication in xx seconds

说明你的后台管理系统 OK 了。

现在访问后台：

http://你的服务器公网IP:8002/

第一次访问要注册超级管理员账号（非常关键）。

🧩 第八步：配置 server.secret（关键）

后台 → 参数管理 → 找到 server.secret
复制值。

然后修改你的 /root/xiaozhi-server/data/.config.yaml：

manager-api:
  url: http://xiaozhi-esp32-server-web:8002/xiaozhi
  secret: 你的server.secret

⚠ 注意：
docker 环境必须使用容器名 xiaozhi-esp32-server-web
不能使用 127.0.0.1
不能使用主机 IP

🔄 第九步：重启 8000 服务

docker restart xiaozhi-esp32-server
docker logs -f xiaozhi-esp32-server

看到：

Websocket地址是 ws://你的ip:8000/xiaozhi/v1/

说明 语音服务成功启动！

笔者记：在腾讯云上安装了多次这一步始终无法成功，一直卡在反复拉取api配置。重启服务器，防火墙端口开放8000 8003，经过20多个小时的排查，终于发现 xiaozhi-esp32-server 容器并没有读取/root/xiaozhi-server/data/.config.yaml 里的配置文件，而是挂载了/opt/xiaozhi-esp32-server/data/.config.yaml（容器目录下找），这儿是空的，根本没有配置文件，所以反复卡无法读取api配置，把.config.yaml复制到这个目录。

1.删除旧容器
docker rm -f xiaozhi-esp32-server

2.然后再启动：

docker run -d \
  --name xiaozhi-esp32-server \
  --network xiaozhi-net \
  -p 8000:8000 -p 8003:8003 \
  -v /root/xiaozhi-server/data/.config.yaml:/opt/xiaozhi-esp32-server/data/.config.yaml \
  ghcr.nju.edu.cn/xinnan-tech/xiaozhi-esp32-server:server_latest

这样保证容器干净，能够读取 .config.yaml

3.查看日志
docker logs -f xiaozhi-esp32-server

🏁 第十步：在后台参数管理配置 OTA/Websocket 地址

后台 → 参数管理：

  1. server.websocket
    填：
    ws://你的公网IP:8000/xiaozhi/v1/

  2. server.ota
    填：
    http://你的公网IP:8002/xiaozhi/ota/

保存。

🎉 完成！

你的小智服务器（docker 版）已成功部署并完全干净升级！