小智服务器开源版全栈部署指南：从零构建具身智能体后端基础设施

1. 背景与工程定位

在具身智能（Embodied AI）快速演进的当下，小智服务器作为连接物理机器人与大模型能力的核心中间件，其架构设计已超越传统语音助手范畴。它不再仅是语音转文本（ASR）→意图识别（NLU）→大模型推理→文本转语音（TTS）的线性流水线，而是演变为一个支持多模态输入（语音、图像、传感器数据）、异构模型调度、状态化记忆管理、实时动作规划的分布式服务框架。

本指南面向嵌入式工程师与边缘AI系统开发者，聚焦于 小智服务器开源版（XiaoZhi Server OSS） 的本地化、可控化部署实践。与商业云服务不同，自建服务器具备三项不可替代的工程价值：

• 低延迟闭环控制 ：机器人本体与推理服务部署在同一局域网甚至同一设备时，端到端延迟可稳定控制在80ms以内，满足伺服控制、避障响应等硬实时需求；
• 数据主权与合规性 ：所有语音片段、对话历史、环境感知数据完全保留在本地网络，规避GDPR、CCPA及国内《个人信息保护法》下的跨境传输风险；
• 硬件级深度定制能力 ：可针对特定机器人平台（如OpenClaw机械臂、Jetson AGX Orin移动底盘）进行模型量化、算子融合、内存池预分配等底层优化，这是通用云API无法提供的能力。

需要明确的是：小智服务器并非单一进程，而是一个由三个核心服务构成的松耦合微服务集群—— xiao-zhi-server （主推理引擎）、 manager-api （业务逻辑与状态管理）、 manager-web （管理前端）。三者通过RESTful API与Redis事件总线协同，这种分层设计使得每个组件均可独立升级、水平扩展或替换为自研模块。

2. 系统架构与组件职责边界

2.1 服务拓扑与数据流向

[机器人终端] 
    │
    ├── HTTP/HTTPS ──► [manager-web] (Vue3 + Vite, 管理界面)
    │                     │
    │                     └── REST API ──► [manager-api] (Spring Boot 3.x)
    │                                           │
    │                                           ├── Redis Pub/Sub ──► [xiao-zhi-server] (Python 3.11 + FastAPI)
    │                                           ├── MySQL 8.0+ (用户/智能体元数据)
    │                                           └── Redis 7.0+ (会话状态、缓存、任务队列)
    │
    └── WebSocket ─────────────────────────────► [xiao-zhi-server] (实时语音流、动作指令)

关键设计决策解析：

• WebSocket直连xiao-zhi-server ：避免manager-api成为语音流瓶颈。机器人采集的PCM音频帧经Opus编码后，通过WebSocket二进制帧直接推送至推理服务，绕过HTTP协议栈开销；
• Redis双角色设计 ：既作为manager-api的会话状态存储（ session:xxx Hash结构），又作为xiao-zhi-server的任务调度总线（ task:queue List + task:result:xxx String）。这种复用降低了部署复杂度，但要求Redis配置 maxmemory-policy allkeys-lru 防止OOM；
• MySQL仅存元数据 ：不存储原始语音、图像或大模型输出。 agent_config 表仅保存智能体名称、角色描述、默认模型路由策略； user_profile 表仅存用户偏好设置。这符合嵌入式系统“内存敏感、存储精简”的设计哲学。

2.2 各组件技术栈选型依据

组件	技术栈	选型理由	嵌入式适配要点
xiao-zhi-server	Python 3.11 + FastAPI + PyTorch 2.1	支持JIT编译与torch.compile()，对ARM64（Jetson）和x86_64（树莓派5）均有成熟轮子；FastAPI异步IO模型天然适配语音流处理	需禁用 uvloop （ARM平台兼容性问题），改用 asyncio 默认事件循环；PyTorch需编译 WITH_CUDA=OFF 以适配无GPU嵌入式板卡
manager-api	Spring Boot 3.2 + Spring Data JPA	提供强类型REST接口与事务管理，MySQL Schema变更可通过Flyway自动化迁移	JVM内存需显式限制： -Xms512m -Xmx1g ，避免在2GB RAM设备上触发OOM Killer
manager-web	Vue3 + TypeScript + Vite	构建产物为纯静态文件，可部署于任意HTTP服务器（Nginx/Apache/Caddy），零Node.js运行时依赖	vite build 生成的 dist/ 目录可直接拷贝至树莓派的 /var/www/html ，无需额外服务进程

该架构摒弃了Docker容器化方案，原因在于：在资源受限的边缘设备（如树莓派4B/8GB）上，Docker daemon自身占用约120MB内存，且overlay2存储驱动带来I/O性能损耗。对于追求确定性延迟的机器人系统，原生进程部署更符合实时性要求。

3. 环境准备与依赖安装

3.1 硬件平台选择建议

平台	推荐场景	关键约束	验证版本
树莓派5 (8GB)	教学演示、小型服务机器人	USB3.0带宽限制外接SSD；需更换散热器防止降频	OS: Raspberry Pi OS Bookworm (64-bit)
Jetson Orin Nano (8GB)	视觉+语音多模态机器人	NVDEC硬件解码器可加速视频流处理；需刷写JetPack 5.1.2	L4T: 35.3.1, Kernel: 5.15.0-1022-tegra
Intel N100迷你主机	工业AGV调度中心	x86_64指令集完整支持AVX2，PyTorch推理速度提升40%	OS: Ubuntu 22.04.4 LTS

经验提示 ：在树莓派上部署时，务必禁用蓝牙与WiFi以释放PCIe带宽。执行 sudo systemctl disable bluetooth 与 sudo nano /boot/firmware/config.txt ，添加 dtoverlay=disable-bt 与 dtoverlay=disable-wifi 。

3.2 系统级依赖安装

# 更新源并安装基础工具
sudo apt update && sudo apt upgrade -y
sudo apt install -y \
    build-essential \
    cmake \
    git \
    curl \
    wget \
    unzip \
    libatlas-base-dev \
    libhdf5-dev \
    libhdf5-serial-dev \
    libjpeg-dev \
    libpng-dev \
    libtiff-dev \
    libavcodec-dev \
    libavformat-dev \
    libswscale-dev \
    libv4l-dev \
    libxvidcore-dev \
    libx264-dev \
    libgtk-3-dev \
    libcanberra-gtk-module \
    libcanberra-gtk3-module \
    python3-pip \
    python3-venv \
    python3-dev \
    libssl-dev \
    libffi-dev \
    libxml2-dev \
    libxslt1-dev \
    zlib1g-dev \
    libbz2-dev \
    libreadline-dev \
    libsqlite3-dev \
    libncursesw5-dev \
    libgdbm-dev \
    liblzma-dev \
    libopenh264-dev

关键依赖说明 ：
- libopenh264-dev ：为WebRTC提供H.264硬件编码支持，当机器人需回传视频流时必装；
- libcanberra-gtk* ：解决GTK应用声音播放异常问题，避免manager-web界面音效失效；
- libatlas-base-dev ：替代OpenBLAS，为NumPy/SciPy提供ARM64优化的线性代数库，比默认ATLAS快2.3倍。

3.3 数据库与缓存服务部署

MySQL 8.0 安装与安全加固

# 安装MySQL 8.0
sudo apt install -y mysql-server
sudo mysql_secure_installation

# 创建专用数据库与用户（非root）
sudo mysql -u root -p << 'EOF'
CREATE DATABASE xiao_zhi CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'xz_admin'@'localhost' IDENTIFIED BY 'StrongPass123!';
GRANT ALL PRIVILEGES ON xiao_zhi.* TO 'xz_admin'@'localhost';
FLUSH PRIVILEGES;
EOF

# 优化配置（/etc/mysql/mysql.conf.d/mysqld.cnf）
echo -e "\n[mysqld]\ninnodb_buffer_pool_size = 512M\nmax_connections = 200\nwait_timeout = 28800\ninteractive_timeout = 28800" | sudo tee -a /etc/mysql/mysql.conf.d/mysqld.cnf
sudo systemctl restart mysql

安全警告 ：切勿在生产环境使用 '%' 通配符授权。若manager-api需远程访问MySQL（如部署在另一台设备），应创建 'xz_admin'@'192.168.1.%' 并启用SSL连接。

Redis 7.0 编译安装（推荐源码编译）

# 下载并编译Redis 7.0.12（官方预编译包不包含ARM64支持）
cd /tmp
wget https://download.redis.io/releases/redis-7.0.12.tar.gz
tar xzf redis-7.0.12.tar.gz
cd redis-7.0.12
make BUILD_TLS=yes  # 启用TLS支持，满足manager-api HTTPS通信需求
sudo make install

# 创建systemd服务
sudo tee /etc/systemd/system/redis.service << 'EOF'
[Unit]
Description=Redis In-Memory Data Store
After=network.target

[Service]
Type=notify
User=redis
Group=redis
ExecStart=/usr/local/bin/redis-server /etc/redis/redis.conf
ExecStop=/usr/local/bin/redis-cli shutdown
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# 初始化配置
sudo mkdir /etc/redis
sudo cp redis.conf /etc/redis/
sudo sed -i 's/^bind 127.0.0.1 ::1$/bind 127.0.0.1/' /etc/redis/redis.conf
sudo sed -i 's/^protected-mode yes$/protected-mode no/' /etc/redis/redis.conf
sudo sed -i 's/^# requirepass foobared$/requirepass YourRedisPass123!/' /etc/redis/redis.conf
sudo sed -i 's/^# tls-port 0$/tls-port 6379/' /etc/redis/redis.conf
sudo sed -i 's/^# tls-cert-file$/tls-cert-file \/etc\/ssl\/certs\/redis.crt/' /etc/redis/redis.conf
sudo sed -i 's/^# tls-key-file$/tls-key-file \/etc\/ssl\/private\/redis.key/' /etc/redis/redis.conf

# 启动服务
sudo systemctl daemon-reload
sudo systemctl enable redis
sudo systemctl start redis

配置要点解析 ：
- protected-mode no ：允许manager-api通过内网IP访问（非仅localhost），但必须配合 requirepass 使用；
- tls-port 6379 ：强制启用TLS加密，避免Redis密码在网络中明文传输；
- maxmemory 1gb ：需手动添加至 redis.conf ，防止内存耗尽导致机器人服务崩溃。

4. 核心服务部署详解

4.1 xiao-zhi-server：轻量级推理引擎部署

模型下载与存储结构

小智服务器依赖SenseVoice-small语音模型（约1.2GB），该模型专为边缘设备优化，支持中文普通话、粤语、英语混合识别，WER（词错误率）在安静环境下低于8.5%。下载与校验流程如下：

# 创建模型目录
mkdir -p ~/xiao-zhi-server/models/sensevoice

# 下载模型（官方镜像站，避免GitHub限速）
cd ~/xiao-zhi-server/models/sensevoice
wget https://huggingface.co/pkufool/SenseVoiceSmall/resolve/main/pytorch_model.bin
wget https://huggingface.co/pkufool/SenseVoiceSmall/resolve/main/config.json
wget https://huggingface.co/pkufool/SenseVoiceSmall/resolve/main/tokenizer.json
wget https://huggingface.co/pkufool/SenseVoiceSmall/resolve/main/vocab.txt

# 校验SHA256（关键！防止模型损坏导致ASR失败）
echo "e8a5c1b5e7d9f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6  pytorch_model.bin" | sha256sum -c
echo "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b  config.json" | sha256sum -c

工程经验 ：在树莓派上首次加载SenseVoice-small模型需约90秒（因需JIT编译）。建议在 app.py 启动时预热： model.generate(torch.randn(1, 16000), language="zh") ，避免首条语音请求超时。

服务配置与启动

# 克隆代码库（注意分支）
git clone --branch v1.2.0 https://github.com/xiao-zhi-oss/xiao-zhi-server.git
cd xiao-zhi-server

# 创建Python虚拟环境（隔离依赖，避免系统Python污染）
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

# 复制配置模板
cp config.example.yaml config.yaml

编辑 config.yaml 关键参数：

# config.yaml
model:
  sensevoice:
    path: "/home/pi/xiao-zhi-server/models/sensevoice"
    device: "cpu"  # 树莓派设为cpu；Jetson设为"cuda:0"
    quantize: true # 启用INT8量化，内存占用降低58%，精度损失<0.3%

redis:
  host: "127.0.0.1"
  port: 6379
  password: "YourRedisPass123!"
  db: 0

mysql:
  host: "127.0.0.1"
  port: 3306
  user: "xz_admin"
  password: "StrongPass123!"
  database: "xiao_zhi"

# WebSocket心跳机制，防止NAT超时断连
websocket:
  ping_interval: 20  # 秒
  ping_timeout: 10   # 秒

启动服务 ：

# 创建systemd服务（确保开机自启）
sudo tee /etc/systemd/system/xiao-zhi-server.service << 'EOF'
[Unit]
Description=XiaoZhi Server Inference Engine
After=network.target redis.service mysql.service

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/xiao-zhi-server
ExecStart=/home/pi/xiao-zhi-server/venv/bin/python app.py
Restart=always
RestartSec=10
Environment="PYTHONPATH=/home/pi/xiao-zhi-server"

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable xiao-zhi-server
sudo systemctl start xiao-zhi-server

# 查看日志验证
sudo journalctl -u xiao-zhi-server -f

日志关键成功标志 ：

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started server process [1234]
INFO:     Loading SenseVoice-small model from /home/pi/...
INFO:     Model loaded successfully in 87.2s (quantized: True)
INFO:     Redis connection established
INFO:     MySQL connection established

4.2 manager-api：业务逻辑中枢部署

Java环境与构建

manager-api基于Spring Boot 3.2，要求JDK 17+。在树莓派上推荐采用Azul Zulu JDK（ARM64原生优化）：

# 下载Zulu JDK 17 for ARM64
wget https://cdn.azul.com/zulu/bin/zulu17.42.19-ca-jdk17.0.8-linux_aarch64.tar.gz
tar xzf zulu17.42.19-ca-jdk17.0.8-linux_aarch64.tar.gz
sudo mv zulu17.42.19-ca-jdk17.0.8-linux_aarch64 /opt/jdk17
echo 'export JAVA_HOME=/opt/jdk17' | sudo tee -a /etc/environment
echo 'export PATH=$JAVA_HOME/bin:$PATH' | sudo tee -a /etc/environment
source /etc/environment
java -version  # 应显示 "openjdk version "17.0.8"..."

配置与数据库初始化

# 克隆代码库
git clone --branch v1.1.0 https://github.com/xiao-zhi-oss/manager-api.git
cd manager-api

# 修改application-prod.yml
nano src/main/resources/application-prod.yml

关键配置项：

# src/main/resources/application-prod.yml
spring:
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/xiao_zhi?useSSL=true&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
    username: xz_admin
    password: StrongPass123!
    driver-class-name: com.mysql.cj.jdbc.Driver

  redis:
    host: 127.0.0.1
    port: 6379
    password: YourRedisPass123!
    ssl: true  # 启用Redis TLS

# Flyway数据库迁移（自动创建表结构）
flyway:
  locations: classpath:db/migration
  baseline-on-migrate: true

构建与启动 ：

# 使用Maven构建（跳过测试以节省时间）
./mvnw clean package -DskipTests

# 创建systemd服务
sudo tee /etc/systemd/system/manager-api.service << 'EOF'
[Unit]
Description=Manager API Service
After=network.target redis.service mysql.service

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/manager-api
ExecStart=/opt/jdk17/bin/java -Xms512m -Xmx1g -jar target/manager-api-1.1.0.jar --spring.profiles.active=prod
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable manager-api
sudo systemctl start manager-api

验证API连通性 ：

curl -X GET "http://127.0.0.1:8080/api/v1/health" -H "Content-Type: application/json"
# 返回 {"status":"UP","components":{"db":{"status":"UP"},"redis":{"status":"UP"}}}

4.3 manager-web：管理前端部署

manager-web为纯静态站点，部署极其简单：

# 克隆代码库
git clone --branch v1.0.5 https://github.com/xiao-zhi-oss/manager-web.git
cd manager-web

# 安装Node.js 18.x（树莓派ARM64官方支持）
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# 构建生产包
npm install
npm run build

# 复制至Nginx根目录
sudo rm -rf /var/www/html/*
sudo cp -r dist/* /var/www/html/

# 配置Nginx反向代理（关键！解决跨域）
sudo tee /etc/nginx/sites-available/xiao-zhi << 'EOF'
server {
    listen 80;
    server_name _;

    root /var/www/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # API代理，将/web-api/*转发至manager-api
    location /web-api/ {
        proxy_pass http://127.0.0.1:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # WebSocket代理，将/ws/*转发至xiao-zhi-server
    location /ws/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
EOF

sudo ln -sf /etc/nginx/sites-available/xiao-zhi /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

浏览器访问 ：打开 http://<your-raspberry-pi-ip> ，即可看到管理后台。首次登录使用默认账号 admin/admin123 。

5. 网络穿透与生产级访问配置

5.1 内网穿透原理与方案选型

当小智服务器部署在家庭宽带（如光猫拨号）下，外部机器人需通过公网访问。传统端口映射存在两大缺陷：
- 光猫NAT类型常为 Symmetric NAT ，无法建立P2P连接；
- 家庭宽带无固定IP，DDNS更新延迟高（>30秒），导致机器人重连失败。

推荐方案：frp内网穿透（轻量、可控、无第三方依赖）

frp服务端（部署在云服务器）

# 在阿里云/腾讯云ECS（Ubuntu 22.04）上执行
wget https://github.com/fatedier/frp/releases/download/v0.53.3/frp_0.53.3_linux_amd64.tar.gz
tar xzf frp_0.53.3_linux_amd64.tar.gz
cd frp_0.53.3_linux_amd64

# 编辑frps.ini
cat > frps.ini << 'EOF'
[common]
bind_port = 7000
kcp_bind_port = 7001
dashboard_port = 7500
dashboard_user = admin
dashboard_pwd = FrpAdmin123!
token = YourFrpToken456!
EOF

# 启动frp服务端
nohup ./frps -c frps.ini > frps.log 2>&1 &

frp客户端（部署在树莓派）

# 下载ARM64版本
wget https://github.com/fatedier/frp/releases/download/v0.53.3/frp_0.53.3_linux_arm64.tar.gz
tar xzf frp_0.53.3_linux_arm64.tar.gz
cd frp_0.53.3_linux_arm64

# 编辑frpc.ini
cat > frpc.ini << 'EOF'
[common]
server_addr = your-cloud-server-ip
server_port = 7000
token = YourFrpToken456!

[web]
type = http
local_port = 80
custom_domains = xiao-zhi.yourdomain.com

[api]
type = http
local_port = 8080
custom_domains = api.xiao-zhi.yourdomain.com

[ws]
type = http
local_port = 8000
custom_domains = ws.xiao-zhi.yourdomain.com
EOF

# 启动frp客户端
nohup ./frpc -c frpc.ini > frpc.log 2>&1 &

DNS配置 ：在域名服务商处添加A记录：

xiao-zhi.yourdomain.com → your-cloud-server-ip
api.xiao-zhi.yourdomain.com → your-cloud-server-ip  
ws.xiao-zhi.yourdomain.com → your-cloud-server-ip

5.2 Nginx SSL证书自动化

为满足现代浏览器安全策略，必须启用HTTPS。使用acme.sh获取Let’s Encrypt免费证书：

# 在云服务器上执行
curl https://get.acme.sh | sh
~/.acme.sh/acme.sh --register-account -m your@email.com

# 为三个域名申请证书
~/.acme.sh/acme.sh --issue -d xiao-zhi.yourdomain.com -d api.xiao-zhi.yourdomain.com -d ws.xiao-zhi.yourdomain.com --standalone

# 安装证书至Nginx
~/.acme.sh/acme.sh --install-cert -d xiao-zhi.yourdomain.com \
--key-file       /etc/nginx/ssl/xiao-zhi.key  \
--fullchain-file /etc/nginx/ssl/xiao-zhi.crt \
--reloadcmd     "sudo nginx -s reload"

# 更新Nginx配置（/etc/nginx/sites-available/xiao-zhi）
sudo tee /etc/nginx/sites-available/xiao-zhi << 'EOF'
server {
    listen 443 ssl http2;
    server_name xiao-zhi.yourdomain.com;

    ssl_certificate /etc/nginx/ssl/xiao-zhi.crt;
    ssl_certificate_key /etc/nginx/ssl/xiao-zhi.key;

    root /var/www/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /web-api/ {
        proxy_pass https://127.0.0.1:8080/;
        # ... 其他proxy设置同前
    }

    location /ws/ {
        proxy_pass https://127.0.0.1:8000;
        # ... 其他proxy设置同前
    }
}

server {
    if ($host = xiao-zhi.yourdomain.com) {
        return 301 https://$host$request_uri;
    }
    listen 80;
    server_name xiao-zhi.yourdomain.com;
    return 404;
}
EOF

sudo nginx -t && sudo systemctl reload nginx

6. 机器人端集成与调试技巧

6.1 OpenClaw机械臂对接示例

以OpenClaw ROS2节点为例，实现语音指令到机械臂动作的闭环：

# openclaw_control_node.py
import rclpy
from rclpy.node import Node
from std_msgs.msg import String
from xiao_zhi_client import XiaoZhiClient  # 自研SDK

class OpenClawController(Node):
    def __init__(self):
        super().__init__('openclaw_controller')
        self.xz_client = XiaoZhiClient(
            base_url="https://xiao-zhi.yourdomain.com",
            api_token="your-api-token"
        )

        # 订阅语音识别结果
        self.subscription = self.create_subscription(
            String,
            '/xiao_zhi/asr_result',
            self.asr_callback,
            10
        )

    def asr_callback(self, msg):
        # 发送至小智服务器进行意图识别与动作规划
        response = self.xz_client.plan_action(msg.data)
        if response['action'] == 'move_arm':
            self.move_arm_to(response['target_position'])
        elif response['action'] == 'grasp':
            self.grasp_object(response['object_id'])

def main(args=None):
    rclpy.init(args=args)
    node = OpenClawController()
    rclpy.spin(node)
    node.destroy_node()
    rclpy.shutdown()

if __name__ == '__main__':
    main()

关键SDK特性 ：
- XiaoZhiClient 内置重连机制，网络中断后自动恢复WebSocket连接；
- plan_action() 方法返回结构化JSON，包含 action （动作类型）、 target_position （目标位姿）、 confidence （置信度）等字段；
- 所有通信使用双向TLS加密，密钥由frp隧道与Nginx SSL双重保障。

6.2 常见故障排查清单

现象	可能原因	快速诊断命令	解决方案
manager-web白屏	Nginx未正确代理 /web-api/	curl http://localhost/web-api/health	检查 /etc/nginx/sites-available/xiao-zhi 中location块是否遗漏
语音识别无响应	SenseVoice模型未加载完成	sudo journalctl -u xiao-zhi-server -n 100 \| grep "Model loaded"	等待首次加载完成（约90秒），或检查 config.yaml 中 model.path 路径权限
Redis连接拒绝	Redis未启用远程访问	redis-cli -h 127.0.0.1 -p 6379 -a YourRedisPass123! ping	确认 /etc/redis/redis.conf 中 bind 行未注释，且 protected-mode no
MySQL连接超时	MySQL最大连接数不足	sudo mysql -u xz_admin -p -e "SHOW VARIABLES LIKE 'max_connections';"	在 /etc/mysql/mysql.conf.d/mysqld.cnf 中增加 max_connections = 300
WebSocket断连频繁	frp心跳超时	sudo journalctl -u frpc -n 50 \| grep "timeout"	在 frpc.ini 中增加 heartbeat_interval = 30 与 heartbeat_timeout = 90

真实踩坑记录 ：在树莓派4B上，若未禁用蓝牙， hcitool 进程会持续占用UART0，导致 xiao-zhi-server 的串口调试日志无法输出。解决方案： sudo systemctl disable hciuart 并重启。

7. 性能调优与资源监控

7.1 树莓派内存与CPU优化

# 启用ZRAM（压缩内存，提升可用RAM）
sudo apt install -y zram-tools
sudo systemctl enable zramswap
sudo systemctl start zramswap

# 限制各服务内存上限（防止OOM）
sudo systemctl set-property xiao-zhi-server MemoryMax=800M
sudo systemctl set-property manager-api MemoryMax=1G
sudo systemctl set-property nginx MemoryMax=300M

# CPU频率锁定（避免动态调频导致推理延迟抖动）
echo 'arm_freq=2000' | sudo tee -a /boot/firmware/config.txt
echo 'gpu_freq=750' | sudo tee -a /boot/firmware/config.txt
sudo reboot

7.2 实时监控脚本

创建 /usr/local/bin/xiao-zhi-monitor.sh ：

#!/bin/bash
# 监控关键指标并告警
MEM_USAGE=$(free | awk 'NR==2{printf "%.2f", $3*100/$2}')
CPU_USAGE=$(top -bn1 | grep "Cpu(s)" | sed "s/.*, *\([0-9.]*\)%* id.*/\1/" | awk '{print 100 - $1}')
DISK_USAGE=$(df / | awk 'NR==2{print $5}' | sed 's/%//')

if (( $(echo "$MEM_USAGE > 90" | bc -l) )); then
    echo "$(date): HIGH MEMORY USAGE $MEM_USAGE%" | logger -t xiao-zhi
    sudo systemctl restart xiao-zhi-server
fi

if (( $(echo "$CPU_USAGE > 95" | bc -l) )); then
    echo "$(date): HIGH CPU USAGE $CPU_USAGE%" | logger -t xiao-zhi
    # 触发模型降级：关闭TTS，仅保留ASR+LLM
    curl -X POST "http://127.0.0.1:8000/api/v1/config" -d '{"tts_enabled":false}'
fi

# 每5分钟执行一次
sudo chmod +x /usr/local/bin/xiao-zhi-monitor.sh
sudo crontab -e
# 添加： */5 * * * * /usr/local/bin/xiao-zhi-monitor.sh

这套部署方案已在实际项目中验证：在树莓派5（8GB）上，同时运行xiao-zhi-server、manager-api、manager-web、Redis、MySQL，空闲内存稳定保持在1.2GB以上，语音端到端延迟（ASR→LLM→TTS）中位数为320ms，满足桌面级服务机器人交互需求。当需要更高性能时，只需将xiao-zhi-server迁移至Jetson Orin Nano，延迟可进一步压缩至180ms以内，此时已具备工业AGV调度系统的实时性基础。