# 配置说明

本页面介绍 Realtime Agent Studio 各组件的配置方法。

---

## 配置概览

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 服务地址（必填）
VITE_API_URL=http://localhost:8080

# Engine WebSocket 地址（可选，默认同 API 服务器）
VITE_WS_URL=ws://localhost:8000

# Google Gemini API Key（可选，用于前端直连）
VITE_GEMINI_API_KEY=your_api_key
```

### 变量说明

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

### 开发环境配置

```env
# .env.development
VITE_API_URL=http://localhost:8080
VITE_WS_URL=ws://localhost:8000
```

---

## 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:
  url: "sqlite:///./data/app.db"
  pool_size: 5
  max_overflow: 10

# Redis 配置
redis:
  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 服务配置

### 环境变量

```env
# 后端 API 地址
BACKEND_URL=http://localhost:8080

# 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
# 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
```

---

## 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
# Docker Compose 会自动加载
SECRET_KEY=your-secret-key-at-least-32-chars
POSTGRES_PASSWORD=secure-db-password
```

---

## 配置优先级

配置按以下优先级加载（高优先级覆盖低优先级）：

```
1. 命令行参数（最高）
2. 环境变量
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) - 容器化部署