# xiaozhi-server-rust

**Repository Path**: jaesoon/xiaozhi-server-rust

## Basic Information

- **Project Name**: xiaozhi-server-rust
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-14
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xiaozhi-server

服务端 Agent 架构、协议与后端实现目录。

- [服务端架构设计](./docs/architecture_zh.md)
- [协议总览](./docs/protocol_zh.md)
- [音频与多模态架构设计](./docs/audio-multimodal_zh.md)
- [VAD 框架评估与选型建议](./docs/vad-framework-evaluation_zh.md)
- [账户、Agent 管理与计量设计](./docs/identity-agent-billing_zh.md)
- [模型 Provider 协议适配设计](./docs/model-provider-contract_zh.md)
- [Tool 与 Skill 扩展设计](./docs/tool-skill-extension_zh.md)

## 当前代码结构

当前仓库已经包含第一版 Rust workspace：

- `crates/xiaozhi-core`
  - 共享领域模型
  - LLM / 多模态 provider 抽象
  - ASR / TTS / Codec 抽象
- `crates/xiaozhi-admin-api`
  - Axum 管理 API
  - SQLite 持久化
  - JWT 鉴权
  - 邮箱验证码注册 / 登录
  - OpenAI-compatible 模型调用
  - 设备 OTA / WebSocket 实时接入
  - MediaProfile / 实时媒体配置
  - MQTT / UDP / 媒体管线骨架
- `web-console`
  - React + Vite 独立管理台
  - 登录、Agent 列表、ModelProfile 列表
  - MediaProfile 管理页
  - Agent 创建与 Agent / Model / Media / Persona / Memory / Dream 联动配置页
  - Realtime Gateway 状态页
  - Runtime 流式调试页

## 已实现范围

当前已落代码的能力：

- Workspace 与 crate 基础结构
- 共享领域模型与 provider 抽象
- LLM provider 统一抽象：
  - `LlmProvider`
  - `MultimodalProvider`
  - `LlmRequest`
  - `LlmResponse`
- 管理 API：
  - `GET /health`
  - `POST /api/auth/register`
  - `POST /api/auth/send-verification-code`
  - `POST /api/auth/verify-email`
  - `POST /api/auth/login`
  - `GET/POST /api/admin/accounts`
  - `GET/POST /api/admin/agents`
  - `GET/PUT /api/admin/agents/:agent_id`
  - `GET/POST /api/admin/media-profiles`
  - `GET/PUT /api/admin/media-profiles/:profile_id`
  - `GET/POST /api/admin/model-profiles`
  - `GET/PUT /api/admin/model-profiles/:profile_id`
  - `GET/POST /api/admin/persona-profiles`
  - `GET/PUT /api/admin/persona-profiles/:persona_id`
  - `GET/POST /api/admin/memory-policies`
  - `GET/PUT /api/admin/memory-policies/:policy_id`
  - `GET/POST /api/admin/dream-policies`
  - `GET/PUT /api/admin/dream-policies/:policy_id`
  - `GET/POST /api/admin/secrets`
  - `GET/POST /api/admin/agent-grants`
  - `GET/POST /api/admin/usage`
  - `POST /api/runtime/chat`
  - `POST /api/runtime/chat/stream`
  - `POST /api/device/ota/check`
  - `GET /api/device/realtime/ws`
  - `web-console` 独立前端工程

## 运行配置

常用环境变量：

- `XIAOZHI_ADMIN_API_ADDR`
  - 默认 `0.0.0.0:8080`
- `XIAOZHI_DATABASE_URL`
  - 默认 `sqlite://data/xiaozhi.db?mode=rwc`
- `XIAOZHI_BOOTSTRAP_ADMIN_PASSWORD`
  - 默认 `ChangeMe123!`
- `XIAOZHI_JWT_SECRET`
  - JWT 签名密钥
- `XIAOZHI_SECRET_KEY`
  - SecretRef 加密密钥
- `XIAOZHI_JWT_TTL_SECONDS`
  - 默认 `86400`
- `XIAOZHI_EXPOSE_DEV_VERIFICATION_CODE`
  - 默认 `true`
  - 开发期直接在注册 / 发码响应里返回验证码，便于联调
- `XIAOZHI_SMTP_HOST`
  - 配置后启用 SMTP 发信；未配置时退回日志输出 sender
- `XIAOZHI_SMTP_PORT`
  - 默认 `465`
- `XIAOZHI_SMTP_USERNAME`
- `XIAOZHI_SMTP_PASSWORD`
- `XIAOZHI_SMTP_FROM`
  - 例如 `XiaoZhi <noreply@example.com>`
- `XIAOZHI_PUBLIC_WS_URL`
  - 设备 OTA 返回给终端的 WebSocket 地址
  - 默认 `ws://127.0.0.1:8080/api/device/realtime/ws`
- `XIAOZHI_VAD_BACKEND`
  - VAD 后端，默认 `silero`
  - 可选 `energy` 作为轻量回退
- `XIAOZHI_VAD_SPEECH_PROB_THRESHOLD`
  - Silero 语音概率阈值，默认 `0.5`
- `XIAOZHI_VAD_ENERGY_THRESHOLD`
  - 旧版能量阈值回退参数，默认 `0.02`
- `XIAOZHI_VAD_MIN_SPEECH_MS`
  - 最短语音时长，默认 `500`
- `XIAOZHI_VAD_SILENCE_TIMEOUT_MS`
  - 静音判定超时，默认 `1000`
- `XIAOZHI_VAD_MAX_SPEECH_MS`
  - 单段语音最大时长，默认 `6000`

## 启动方式

在安装 Rust 工具链后，可在 `xiaozhi-server/` 下运行：

```bash
cargo run -p xiaozhi-admin-api
```

默认监听：

- `0.0.0.0:8080`

首次启动会自动引导基础数据，并创建 bootstrap `super_admin` 账户：

- `email = root@example.com`
- `password = $XIAOZHI_BOOTSTRAP_ADMIN_PASSWORD`

后台 API 现在使用标准 Bearer Token：

```http
Authorization: Bearer <jwt>
```

`/api/runtime/chat` 和 `/api/runtime/chat/stream` 都会按 `agent_id -> agent_config -> model_profile -> secret_ref` 装载模型配置，并通过 OpenAI-compatible `/chat/completions` 发起调用。

其中：

- `/api/runtime/chat`
  - 返回标准 JSON
- `/api/runtime/chat/stream`
  - 返回 `application/x-ndjson`
  - 每行一个 `LlmResponse` 分片
  - 当 provider 返回 usage 时会自动落 usage 记录

实时设备链路当前已实现第一版：

- `POST /api/device/ota/check`
  - 按 `agent_id -> agent_config -> media_profile` 返回 WebSocket / MQTT / UDP 运行配置
  - 同时返回 `server_time`，默认使用上海时间，旧版兼容 OTA 端点 `/xiaozhi/ota/` 也会透传该字段用于校时
- `GET /api/device/realtime/ws`
  - 设备控制面 WebSocket 接入
- UDP 音频面
  - 可按 `MediaProfile.transport.udp_*` 启用
- 阿里云 MQTT
  - 通过 `MediaProfile.transport.mqtt_*` 配置 broker、主题和凭据
  - 支持设备维度 topic 隔离
  - 支持 HMAC-SHA256 凭据签名模式
  - OTA 返回显式 ACL 与签名 payload
  - 提供 `GET /api/admin/realtime/status` 运行状态快照

媒体处理链路当前为：

- `CodecAdapter`
  - `passthrough`
  - `opus_native`
  - `mock_transcoder`
- `AsrProvider`
  - `mock`
  - `http`
- `TtsProvider`
  - `mock`
  - `http`

默认 bootstrap `MediaProfile` 会启用：

- WebSocket
- `opus_native` codec
- mock ASR
- mock TTS
- 多模态输入

## Web Console

前端在 `web-console/`，默认 Vite 开发端口为 `5174`。

```bash
cd web-console
npm install
npm run dev
```

生产构建：

```bash
npm run build
```

前端默认请求 `http://127.0.0.1:8080`，也可以在页面运行前通过全局变量 `__XIAOZHI_API_BASE__` 覆盖。

## 开发说明

- workspace 下新增了 [`.cargo/config.toml`](./.cargo/config.toml)
  - 默认使用 `rsproxy` sparse registry mirror，加快依赖解析
- 未配置 SMTP 时，验证码会写入日志，同时如果 `XIAOZHI_EXPOSE_DEV_VERIFICATION_CODE=true` 也会在接口响应里回传

## 说明

当前实现已经从内存 demo 进入可持久化的后端骨架，但仍未完成：

- 真正的邮件发送通道
- Anthropic / Gemini 的真实 provider 适配器
- Anthropic / Gemini provider
- 生产级 ASR / TTS 厂商适配
- 更细粒度的阿里云 MQTT 观测、告警和 broker ACL 自动下发
- UDP 音频面与真实设备的回传联调
- 更完整的 Gateway / Codec / Media Service
- Tool Hub / Skill Runtime
- 更细粒度的前端运营/审计页