小智服务器开源版从零部署指南：AI智能体私有化部署实战

小智服务器开源版自建指南：从零部署到生产可用

1. 背景与工程定位

小智服务器开源版本（XiaoZhi Server）是面向本地化、私有化AI服务部署的轻量级智能体运行时平台。它并非传统意义上的“大模型推理服务器”，而是一个结构清晰、职责分离的 多模块协同架构系统 ，其核心价值在于将语音识别（ASR）、语音合成（TTS）、意图理解（NLU）、记忆管理、智能体编排等能力解耦为可插拔组件，并通过标准化API进行通信。这种设计使得开发者既能快速启动一个功能完备的AI交互后端，又能按需替换其中任一模块——例如将默认的SenseVoice ASR模型替换为Whisper微调版本，或将Redis记忆层升级为向量数据库支持长期上下文。

该系统明确区分三类服务进程： – xiao-zhi-server ：主服务模块，负责接收前端（如桌面宠物、电视端App）的原始音频流或文本请求，调用ASR/TTS/NLU等子系统完成端到端处理，并维护会话状态； – manager-api ：管理接口服务，提供RESTful API供Web控制台调用，完成智能体创建、角色配置、模型参数更新、数据库连接管理等运维操作； – manager-web ：基于Vue/React构建的前端管理界面，完全静态化，通过HTTP请求与 manager-api 交互，不包含任何业务逻辑。

三者之间无直接进程依赖，仅通过HTTP/HTTPS和Redis消息队列通信，天然支持分布式部署。这种松耦合架构决定了其部署方式必须以 环境隔离、配置显式、依赖可控 为基本原则，而非简单执行一键脚本。

2. 环境准备与基础依赖

2.1 操作系统与硬件要求

推荐在Linux发行版（Ubuntu 22.04 LTS / Debian 12）上部署。虽然官方README提及Windows兼容性，但实际工程实践中发现Windows子系统（WSL2）对FFmpeg音频重采样、CUDA加速推理等环节存在不可忽略的时序偏差和权限问题，故生产环境应避免使用Windows原生环境。

最低硬件配置如下： | 组件 | CPU | 内存 | 存储 | 说明 | |——–|—–|——|——|——| | xiao-zhi-server | 4核 | 8GB | ≥50GB | 需承载ASR模型加载（SenseVoice-small约1.2GB）、实时音频流解码与推理 | | manager-api | 2核 | 4GB | ≥20GB | 主要承担HTTP路由、数据库查询、配置序列化，负载较轻 | | manager-web | 无 | 无 | ≥5GB | 静态资源，可由Nginx直接托管 | | MySQL | 2核 | 4GB | ≥30GB | 存储智能体元数据、用户会话日志、配置快照 | | Redis | 2核 | 4GB | ≥10GB | 缓存会话状态、作为任务队列中转站（如TTS异步合成） |

若采用云服务器，建议选择 计算优化型实例 （如AWS c6i.xlarge、阿里云ecs.c7.large），而非通用型。原因在于ASR模块在音频预处理阶段大量使用SIMD指令（特别是librosa底层调用的FFTW库），计算优化型实例的AVX-512指令集支持可使实时音频帧处理延迟降低37%以上。

2.2 基础软件栈安装

所有组件均需在同一台物理机或虚拟机内完成部署（开发验证阶段），后续再按需拆分至不同节点。以下命令基于Ubuntu 22.04：

# 更新系统并安装基础工具
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget git unzip build-essential python3-dev python3-pip \\
ffmpeg libsm6 libxext6 libglib2.0-0 libglib2.0-dev libasound2-dev \\
libportaudio2 portaudio19-dev libatlas-base-dev libopenblas-dev

# 安装Node.js v18.x（manager-web构建必需）
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash –
sudo apt-get install -y nodejs

# 安装Java 17（manager-api编译必需，注意非JDK 21，官方文档存在笔误）
sudo apt install -y openjdk-17-jdk

# 验证版本
python3 –version # 应输出 3.10.x 或 3.11.x
node –version # 应输出 v18.x
java -version # 应输出 17.x

关键经验 ： libasound2-dev 与 libportaudio2 必须同时安装。仅安装前者会导致PyAudio在初始化输入流时抛出 OSError: [Errno -9997] Invalid sample rate ；仅安装后者则无法链接ALSA后端，造成实时麦克风采集失败。这是社区高频踩坑点。

2.3 数据库服务部署

MySQL 8.0 配置要点

小智服务器要求MySQL开启 utf8mb4 字符集支持（用于存储emoji及长上下文），且必须禁用 sql_mode=STRICT_TRANS_TABLES ——否则在插入含NULL字段的会话日志时触发 Data too long for column 错误。

— 创建专用数据库与用户
CREATE DATABASE xiaozhi DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER \’xiaozhi\’@\’localhost\’ IDENTIFIED BY \’StrongPassw0rd!\’;
GRANT ALL PRIVILEGES ON xiaozhi.* TO \’xiaozhi\’@\’localhost\’;
FLUSH PRIVILEGES;

— 修改MySQL配置文件 /etc/mysql/mysql.conf.d/mysqld.cnf
[mysqld]
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
sql_mode = \”NO_ENGINE_SUBSTITUTION\”

重启MySQL后，务必执行以下校验：

SELECT DEFAULT_CHARACTER_SE