小智ESP32服务端一键部署工具

@小智服务端图形化部署工具感谢 github.com/xinnan-tech/xiaozhi-esp32-server 大佬们开源项目让我们体验本地的小智服务系统。

项目简介

小智ESP32服务端一键部署工具是一个图形化工具，专为 xiaozhi-esp32-server 项目设计，旨在简化服务端的部署和运行过程。通过直观的界面，用户可以轻松管理Python环境、安装依赖、启动和监控服务，无需手动执行复杂的命令行操作。

小智服务端图形化部署工具

下载

百度网盘：小智服务端图形化部署工具链接: https://pan.baidu.com/s/1kYEd7tbwQgNjC6A3KI4DDw?pwd=e4xc 提取码: e4xc

夸克网盘「小智服务端图形化部署工具」链接：https://pan.quark.cn/s/6b1539a1c130

夸克网盘「智能小智服务端配置编辑器」。链接：https://pan.quark.cn/s/2019bea0892d

通过网盘分享的文件：小智服务端配置编辑器链接: https://pan.baidu.com/s/1d0r_NIHe7CAabrR9AGWKtw?pwd=ucce 提取码: ucce

夸克网盘分享了「智能小智服务端」里面包含了v0.1.3到v0.1.16官方原版包链接：https://pan.quark.cn/s/e82f835a9abf

通过网盘分享的文件：智能小智服务端里面包含了v0.1.3到v0.1.16官方原版包链接: https://pan.baidu.com/s/1HDPaXrcSNTvcKevwhmZP0w?pwd=5wsj 提取码: 5wsj

主要功能

图形化界面：直观的用户界面，使部署和运行更加简单
Python环境管理：自动检测和管理Python环境，支持多环境切换
依赖管理：自动检查和安装项目所需依赖，支持国内镜像加速
服务管理：一键启动和停止服务，实时监控服务状态和日志
配置编辑器集成：内置配置编辑器，方便修改服务配置
系统托盘支持：支持最小化到系统托盘，方便后台运行
自动更新检测：启动时自动检查是否有新版本可用
首次运行引导：首次启动时自动检测环境并提供配置引导
多语言支持：界面元素使用中文显示，提升用户体验
日志管理：分类显示工具日志和服务日志，支持实时查看

功能详解

Python环境管理

自动检测系统Python环境
支持手动选择Python解释器
显示Python版本信息
支持多环境切换

依赖管理

自动检查项目依赖
使用国内镜像加速安装
显示详细的安装进度
支持批量安装缺失依赖

服务管理

一键启动/停止服务
实时显示服务状态
支持优雅停止服务
自动重试和错误处理

日志管理

分类显示工具日志和服务日志
支持实时查看日志输出
自动滚动到最新日志
支持日志过滤和搜索

配置管理

集成配置编辑器
支持配置文件备份
自动检测配置文件
配置文件格式验证

安装与使用

运行

解压下载的文件
双击运行 小智服务端部署工具.exe
首次运行时，程序会引导您完成初始配置：
- 选择Python环境
- 检查并安装依赖
- 配置服务参数

使用说明

启动程序后，首先检查Python环境
点击"检查依赖"按钮检查所需依赖
如有缺失依赖，点击"安装依赖"进行安装
配置完成后，点击"启动服务器"运行服务
使用"打开配置器"可以修改服务配置
服务运行时可以最小化到系统托盘

开发信息

技术栈

Qt 6.x (GUI框架)
C++17
CMake (构建系统)

依赖库列表

如果您想自行编译程序，需要安装以下开发环境：

bash
# 必需组件
Qt 6.x
CMake 3.15+
C++17 兼容的编译器

主要依赖说明：

Qt: 用于创建GUI界面和系统托盘
CMake: 用于项目构建
C++17: 用于现代C++特性支持

常见问题

Q: 为什么无法启动服务？
A: 请检查以下几点：

Python环境是否正确配置
所需依赖是否已安装
配置文件是否存在且格式正确

Q: 如何更新程序？
A: 程序会自动检查更新，您也可以：

点击"检查更新"按钮手动检查
访问GitHub Releases页面下载新版本
访问作者博客获取最新版本

Q: 如何修改服务配置？
A: 点击"打开配置器"按钮，使用内置的配置编辑器修改配置。

Q: 服务无法正常停止怎么办？
A: 程序会自动尝试多种方式停止服务，如果仍然无法停止，可以：

等待程序自动强制终止
手动关闭程序窗口
使用任务管理器结束进程

联系方式

作者：曾能混
博客：https://znhblog.com
B站：https://space.bilibili.com/298384872
QQ：7280051
邮箱：jwhna1@gmail.com

如有问题可加微信群一起沟通（在B站私信索取微信群加群二维码）

更新日志

v0.1.6 (2025-03-29)

优化了"关于"对话框的设计，采用一体化布局提升视觉体验
修改服务终端日志颜色方案，统一非错误/警告日志为浅绿色，提高可读性
移除了可能触发杀毒软件误报的代码，提高系统兼容性
优化了SSL错误处理机制，解决远程系统上的TLS初始化失败问题
简化了更新检查流程，使用HTTP连接提高兼容性
调整了整体UI界面字体大小和布局，提升在不同Windows系统上的显示效果
完全适配 xiaozhi-esp32-server v0.1.11 版本
向下兼容 xiaozhi-esp32-server v0.1.3 至 v0.1.16所有版本

v0.1.3 (重大更新)

使用C++/Qt6.8.2重构整个项目，彻底解决Python版本在嵌入式终端命令行兼容性问题
修复调用播放音乐函数时导致服务卡死的问题
优化服务启动和停止机制，提高稳定性
改进日志管理功能，支持实时查看和过滤
完全适配 xiaozhi-esp32-server v0.1.9 版本
向下兼容 xiaozhi-esp32-server v0.1.3 至 v0.1.9 所有版本

v0.1.2 (Python版本)

添加Python环境检测
优化依赖管理
改进服务控制
添加基本日志功能
适配 xiaozhi-esp32-server v0.1.3 至 v0.1.6 版本

v0.1.1 (Python版本)

添加配置文件管理
优化界面布局
改进错误处理
添加基本功能
适配 xiaozhi-esp32-server v0.1.3至v0.1.5 版本

v0.1.0 (Python版本)

初始版本发布
基于Python开发
适配 xiaozhi-esp32-server v0.1.3 版本

许可证

本项目基于 MIT 许可证开源。

致谢

特别感谢 github.com/xinnan-tech/xiaozhi-esp32-server 项目的开发者们，他们的开源项目让我们能够体验本地的小智服务系统。

如果您觉得这个工具有用，请给原项目 xiaozhi-esp32-server 点个星标⭐！

小智服务端问题修复指南

本指南帮助解决小智服务端部署工具可能遇到的常见问题。

问题修复工具

这里提供了几个工具脚本，用于解决以下问题：

Qt库文件加载问题 - Qt DLL无法在子目录中被正确加载
Opus库缺失问题 - opuslib_next库找不到opus.dll

使用方法

综合解决方案

使用 xiaozhi_helper.bat 提供了一个菜单式界面，可以：

启动小智服务端程序（自动处理Qt DLL）
安装Opus库
检查和修复Qt依赖


xiaozhi_helper.bat

修复Opus库问题

有两种方式修复Opus库问题：

1. Python脚本修复 (推荐)

这个方法通过修改opuslib_next库的加载方式，使其能够找到程序目录下的opus.dll：


python fix_opuslib.py

2. Python环境配置

这个方法会在Python环境中创建一个sitecustomize.py文件，为所有Python程序设置正确的DLL搜索路径：


python_env_helper.bat

文件结构说明

程序预期的文件结构：


xiaozhi_server_runner.exe      # 主程序
libs/                          # 库文件目录
  ├── Qt6Core.dll              # Qt核心库
  ├── Qt6Gui.dll               # Qt GUI库
  ├── Qt6Network.dll           # Qt网络库
  ├── Qt6Widgets.dll           # Qt控件库
  ├── opus.dll                 # Opus音频编解码库
  └── platforms/               # Qt平台插件目录
      └── qwindows.dll         # Windows平台插件

常见问题解答

Q: 为什么Qt库文件放在libs目录不能被正确加载?

A: Windows的DLL加载机制首先查找程序所在目录，然后是系统目录，最后才是PATH环境变量中的目录。辅助工具通过临时复制DLL到程序目录解决这个问题。

Q: 为什么会出现"Could not find Opus library"错误?

A: opuslib_next库需要opus.dll，但无法找到它。我们的修复方案通过直接修改opuslib_next库的加载机制，使其能够从程序目录或libs目录找到opus.dll。

Q: 服务正常启动但语音识别或合成功能不可用怎么办?

A: 请确保opus.dll已正确安装，并且Python环境变量设置正确。使用fix_opuslib.py脚本可以解决大多数相关问题。

注意事项

这些修复脚本不需要管理员权限，可由普通用户运行
所有DLL文件仍然保存在libs目录，保持目录结构的整洁
启动程序时会临时复制所需DLL，结束后自动清理