Update documentation and configuration for Realtime Agent Studio

- Revised mkdocs.yml to reflect the new site name and description, enhancing clarity for users. - Added a changelog.md to document important changes and updates for the project. - Introduced a roadmap.md to outline development plans and progress for future releases. - Expanded index.md with a comprehensive overview of the platform, including core features and installation instructions. - Enhanced concepts documentation with detailed explanations of assistants, engines, and their configurations. - Updated configuration documentation to provide clear guidance on environment setup and service configurations. - Added extra JavaScript for improved user experience in the documentation site.
2026-03-02 23:35:22 +08:00
parent 80fff09b76
commit 4c05131536
15 changed files with 2529 additions and 236 deletions
--- a/docs/content/getting-started/configuration.md
+++ b/docs/content/getting-started/configuration.md
@@ -1,83 +1,289 @@
 # 配置说明

-## 环境变量
+本页面介绍 Realtime Agent Studio 各组件的配置方法。

-在项目根目录或 `web` 目录下创建 `.env` 文件：
+---
+
+## 配置概览
+
+RAS 采用分层配置，各组件独立配置：
+
+```mermaid
+flowchart TB
+    subgraph Config["配置层级"]
+        ENV[环境变量]
+        File[配置文件]
+        DB[数据库配置]
+    end
+
+    subgraph Services["服务组件"]
+        Web[Web 前端]
+        API[API 服务]
+        Engine[Engine 服务]
+    end
+
+    ENV --> Web
+    ENV --> API
+    ENV --> Engine
+    File --> API
+    File --> Engine
+    DB --> API
+```
+
+---
+
+## Web 前端配置
+
+### 环境变量
+
+在 `web/` 目录创建 `.env` 文件：

 ```env
-# API 服务地址
+# API 服务地址（必填）
 VITE_API_URL=http://localhost:8080

-# Gemini API Key（可选）
-VITE_GEMINI_API_KEY=your_api_key_here
+# Engine WebSocket 地址（可选，默认同 API 服务器）
+VITE_WS_URL=ws://localhost:8000
+
+# Google Gemini API Key（可选，用于前端直连）
+VITE_GEMINI_API_KEY=your_api_key
 ```

-## 变量说明
+### 变量说明

 | 变量 | 必填 | 说明 | 默认值 |
-|------|------|------|--------|
-| `VITE_API_URL` | 是 | 后端 API 服务地址 | http://localhost:8080 |
-| `VITE_GEMINI_API_KEY` | 否 | Google Gemini API 密钥 | - |
+|------|:----:|------|--------|
+| `VITE_API_URL` | ✅ | 后端 API 服务地址 | - |
+| `VITE_WS_URL` | ❌ | WebSocket 服务地址 | 从 API URL 推断 |
+| `VITE_GEMINI_API_KEY` | ❌ | Gemini API 密钥 | - |

-## 后端服务配置
+### 多环境配置

-后端服务使用独立的配置文件，位于 `api/config/` 目录：
+=== "开发环境"

-### 数据库配置
+    ```env
+    # .env.development
+    VITE_API_URL=http://localhost:8080
+    VITE_WS_URL=ws://localhost:8000
+    ```
+
+=== "生产环境"
+
+    ```env
+    # .env.production
+    VITE_API_URL=https://api.example.com
+    VITE_WS_URL=wss://ws.example.com
+    ```
+
+---
+
+## API 服务配置
+
+### 环境变量
+
+```env
+# 数据库配置
+DATABASE_URL=sqlite:///./data/app.db
+# 或 PostgreSQL
+# DATABASE_URL=postgresql://user:pass@localhost:5432/ras
+
+# Redis 配置（可选）
+REDIS_URL=redis://localhost:6379/0
+
+# 安全配置
+SECRET_KEY=your-secret-key-at-least-32-chars
+CORS_ORIGINS=http://localhost:3000,https://your-domain.com
+
+# 日志级别
+LOG_LEVEL=INFO
+
+# 文件存储路径
+UPLOAD_DIR=./uploads
+```
+
+### 配置文件
+
+API 服务支持 YAML 配置文件 `api/config/settings.yaml`：

 ```yaml
+# 服务配置
+server:
+  host: "0.0.0.0"
+  port: 8080
+  workers: 4
+
+# 数据库配置
 database:
-  host: localhost
-  port: 5432
-  name: ai_assistant
-  user: postgres
-  password: your_password
-```
+  url: "sqlite:///./data/app.db"
+  pool_size: 5
+  max_overflow: 10

-### Redis 配置
-
-```yaml
+# Redis 配置
 redis:
-  host: localhost
-  port: 6379
-  db: 0
+  url: "redis://localhost:6379/0"
+  
+# 安全配置
+security:
+  secret_key: "your-secret-key"
+  token_expire_minutes: 1440
+
+# 日志配置
+logging:
+  level: "INFO"
+  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
 ```

+---
+
 ## Engine 服务配置

-Engine 服务配置位于 `engine/config/` 目录：
+### 环境变量

-### 助手默认配置
+```env
+# 后端 API 地址
+BACKEND_URL=http://localhost:8080

-参考 `engine/config/agents/default.yaml`：
+# WebSocket 服务配置
+WS_HOST=0.0.0.0
+WS_PORT=8000
+
+# 音频配置
+AUDIO_SAMPLE_RATE=16000
+AUDIO_CHANNELS=1
+
+# 日志级别
+LOG_LEVEL=INFO
+```
+
+### 引擎配置
+
+Engine 配置文件 `engine/config/engine.yaml`：

 ```yaml
-agent:
-  name: "默认助手"
-  language: "zh-CN"
+# WebSocket 服务
+websocket:
+  host: "0.0.0.0"
+  port: 8000
+  ping_interval: 30
+  ping_timeout: 10
+
+# 音频处理
+audio:
+  sample_rate: 16000
+  channels: 1
+  chunk_size: 640  # 20ms at 16kHz
+
+# VAD 配置
+vad:
+  enabled: true
+  threshold: 0.5
+  min_speech_duration: 0.25
+  min_silence_duration: 0.5
+
+# 引擎默认配置
+defaults:
+  engine_type: "pipeline"  # pipeline 或 multimodal
+  max_response_tokens: 512
  temperature: 0.7
-  max_tokens: 2048
 ```

-## 多环境配置
+---

-### 开发环境
+## Docker 配置
+
+### docker-compose.yml 环境变量
+
+```yaml
+version: '3.8'
+
+services:
+  web:
+    environment:
+      - VITE_API_URL=http://api:8080
+    
+  api:
+    environment:
+      - DATABASE_URL=postgresql://postgres:password@db:5432/ras
+      - REDIS_URL=redis://redis:6379/0
+      - SECRET_KEY=${SECRET_KEY}
+    
+  engine:
+    environment:
+      - BACKEND_URL=http://api:8080
+      - LOG_LEVEL=INFO
+```
+
+### 使用 .env 文件
+
+在项目根目录创建 `.env`：

 ```env
-# .env.development
-VITE_API_URL=http://localhost:8080
+# Docker Compose 会自动加载
+SECRET_KEY=your-production-secret-key
+POSTGRES_PASSWORD=secure-db-password
 ```

-### 生产环境
-
-```env
-# .env.production
-VITE_API_URL=https://api.your-domain.com
-```
+---

 ## 配置优先级

-1. 命令行参数
+配置按以下优先级加载（高优先级覆盖低优先级）：
+
+```
+1. 命令行参数（最高）
 2. 环境变量
-3. `.env` 文件
-4. 默认值
+3. .env 文件
+4. 配置文件 (yaml)
+5. 代码默认值（最低）
+```
+
+---
+
+## 敏感配置管理
+
+!!! danger "安全提醒"
+    不要将敏感信息提交到代码仓库！
+
+### 推荐做法
+
+1. **使用 .env 文件**，并将其加入 `.gitignore`
+2. **使用环境变量**，通过 CI/CD 注入
+3. **使用密钥管理服务**，如 AWS Secrets Manager、HashiCorp Vault
+
+### .gitignore 配置
+
+```gitignore
+# 环境配置文件
+.env
+.env.local
+.env.*.local
+
+# 敏感数据目录
+/secrets/
+*.pem
+*.key
+```
+
+---
+
+## 配置验证
+
+启动服务前验证配置是否正确：
+
+```bash
+# 验证 API 服务配置
+cd api
+python -c "from app.config import settings; print(settings)"
+
+# 验证 Engine 配置
+cd engine
+python -c "from config import settings; print(settings)"
+```
+
+---
+
+## 下一步
+
+- [安装部署](index.md) - 开始安装服务
+- [Docker 部署](../deployment/docker.md) - 容器化部署
+- [生产环境](../deployment/production.md) - 生产配置指南