# 安装部署

本章节介绍如何安装和配置 Realtime Agent Studio (RAS) 开发环境。

---

## 系统组件

RAS 由三个核心服务组成：

```mermaid
flowchart LR
    subgraph Services["服务组件"]
        Web[Web 前端<br/>React + TypeScript]
        API[API 服务<br/>FastAPI]
        Engine[Engine 服务<br/>WebSocket]
    end

    subgraph Storage["数据存储"]
        DB[(SQLite/PostgreSQL)]
    end

    Web -->|REST| API
    Web -->|WebSocket| Engine
    API <--> DB
    Engine <--> API
```

| 组件 | 端口 | 说明 |
|------|------|------|
| **Web 前端** | 3000 | React + TypeScript 管理控制台 |
| **API 服务** | 8080 | Python FastAPI 后端 |
| **Engine 服务** | 8000 | 实时对话引擎（WebSocket） |

---

## 快速安装

### 方式一：Docker Compose（推荐）

最快捷的启动方式，适合快速体验和生产部署。

```bash
# 1. 克隆项目
git clone https://github.com/your-org/AI-VideoAssistant.git
cd AI-VideoAssistant

# 2. 启动服务
docker-compose up -d

# 3. 访问控制台
open http://localhost:3000
```

!!! tip "首次启动"
    首次启动需要构建镜像，可能需要几分钟时间。

### 方式二：本地开发

适合需要修改代码的开发者。

#### 1. 克隆项目

```bash
git clone https://github.com/your-org/AI-VideoAssistant.git
cd AI-VideoAssistant
```

#### 2. 启动 API 服务

```bash
cd api
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8080 --reload
```

#### 3. 启动 Engine 服务

```bash
cd engine
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python main.py
```

#### 4. 启动 Web 前端

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

访问 `http://localhost:3000`

---

## 验证安装

### 检查服务状态

| 服务 | URL | 预期结果 |
|------|-----|---------|
| Web | http://localhost:3000 | 看到登录/控制台页面 |
| API | http://localhost:8080/docs | 看到 Swagger 文档 |
| Engine | http://localhost:8000/health | 返回 `{"status": "ok"}` |

### 测试 WebSocket 连接

```javascript
const ws = new WebSocket('ws://localhost:8000/ws?assistant_id=test');
ws.onopen = () => console.log('Connected!');
ws.onerror = (e) => console.error('Error:', e);
```

---

## 目录结构

```
AI-VideoAssistant/
├── web/                    # React 前端
│   ├── src/
│   │   ├── components/     # UI 组件
│   │   ├── pages/          # 页面
│   │   ├── stores/         # Zustand 状态
│   │   └── api/            # API 客户端
│   └── package.json
├── api/                    # FastAPI 后端
│   ├── app/
│   │   ├── routers/        # API 路由
│   │   ├── models/         # 数据模型
│   │   └── services/       # 业务逻辑
│   └── requirements.txt
├── engine/                 # 实时交互引擎
│   ├── app/
│   │   ├── pipeline/       # 管线引擎
│   │   └── multimodal/     # 多模态引擎
│   └── requirements.txt
├── docker/                 # Docker 配置
│   └── docker-compose.yml
└── docs/                   # 文档
```

---

## 常见问题

### 端口被占用

```bash
# 查看端口占用
# Linux/Mac
lsof -i :3000

# Windows
netstat -ano | findstr :3000
```

修改对应服务的端口配置后重启。

### Docker 构建失败

```bash
# 清理 Docker 缓存
docker system prune -a

# 重新构建
docker-compose build --no-cache
```

### Python 依赖安装失败

确保使用 Python 3.10+：

```bash
python --version  # 需要 3.10+
```

---

## 下一步

- [环境要求](requirements.md) - 详细的软件版本要求
- [配置说明](configuration.md) - 环境变量配置指南
- [快速开始](../quickstart/index.md) - 创建第一个助手
- [Docker 部署](../deployment/docker.md) - 镜像构建与编排