Enhance Docker configuration and update dependencies for Realtime Agent Studio

- Updated Dockerfile for the API to include build tools for C++11 required for native extensions. - Revised requirements.txt to upgrade several dependencies, including FastAPI and SQLAlchemy. - Expanded docker-compose.yml to add MinIO service for S3-compatible storage and improved health checks for backend and engine services. - Enhanced README.md in the Docker directory to provide detailed service descriptions and quick start instructions. - Updated mkdocs.yml to reflect new navigation structure and added deployment overview documentation. - Introduced new Dockerfiles for the engine and web services, including development configurations for hot reloading.
2026-03-04 10:01:00 +08:00
parent 4c05131536
commit 530d95eea4
20 changed files with 318 additions and 332 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,7 +1,18 @@
 # Documentation

-部署 MkDocs：
-pip install mkdocs
-mkdocs serve
+**安装依赖（推荐使用 1.x，避免与 Material 主题不兼容）：**

-访问 http://localhost:8000 查看文档网站。
+```bash
+cd docs
+pip install -r requirements.txt
+```
+
+或手动安装：`pip install "mkdocs>=1.6,<2" mkdocs-material`
+
+**本地预览：**
+
+```bash
+mkdocs serve
+```
+
+访问终端中显示的地址（如 http://127.0.0.1:8000）查看文档。
--- a/docs/content/deployment/index.md
+++ b/docs/content/deployment/index.md
@@ -1,13 +1,12 @@
-# 部署指南
+# 部署概览

-本章节介绍如何将 Realtime Agent Studio (RAS) 部署到生产环境。
+本章节介绍如何使用 Docker 部署 Realtime Agent Studio (RAS)。

 ## 部署方式

 | 方式 | 适用场景 | 复杂度 |
 |------|---------|--------|
-| [Docker 部署](docker.md) | 快速部署、容器化环境 | 简单 |
-| [生产环境](production.md) | Nginx 反向代理、高可用 | 中等 |
+| [Docker 部署](docker.md) | 快速启动、容器化运行 | 简单 |

 ## 快速开始

@@ -20,7 +19,7 @@ docker run -d -p 3000:80 --name ai-assistant-web ai-video-assistant-web

 ### 验证部署

-1. 访问 http://your-domain.com
+1. 访问 http://localhost:3000
 2. 检查页面是否正常加载
 3. 验证各功能模块是否可用

--- a/docs/content/deployment/production.md
+++ b/docs/content/deployment/production.md
@@ -1,191 +0,0 @@
-# 生产环境部署
-
-本文档介绍如何将 Realtime Agent Studio (RAS) 部署到生产环境，包括 Nginx 配置、SSL 证书、性能优化等。
-
-## Nginx 部署
-
-### 1. 构建前端
-
-```bash
-cd web
-npm run build
-```
-
-### 2. 部署静态文件
-
-```bash
-sudo mkdir -p /var/www/ai-assistant
-sudo cp -r dist/* /var/www/ai-assistant/
-```
-
-### 3. 配置 Nginx
-
-创建 `/etc/nginx/sites-available/ai-assistant`：
-
-```nginx
-server {
-    listen 80;
-    server_name your-domain.com;
-    root /var/www/ai-assistant;
-    index index.html;
-
-    # Gzip 压缩
-    gzip on;
-    gzip_types text/plain text/css application/json application/javascript;
-
-    # 静态文件缓存
-    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
-        expires 30d;
-        add_header Cache-Control "public, immutable";
-    }
-
-    # SPA 路由支持
-    location / {
-        try_files $uri $uri/ /index.html;
-    }
-
-    # API 反向代理
-    location /api {
-        proxy_pass http://localhost: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 代理
-    location /ws {
-        proxy_pass http://localhost:8000;
-        proxy_http_version 1.1;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
-        proxy_set_header Host $host;
-        proxy_read_timeout 86400;
-    }
-}
-```
-
-### 4. 启用站点
-
-```bash
-sudo ln -s /etc/nginx/sites-available/ai-assistant /etc/nginx/sites-enabled/
-sudo nginx -t
-sudo systemctl reload nginx
-```
-
-## SSL 证书配置
-
-### 使用 Let's Encrypt
-
-```bash
-# 安装 certbot
-sudo apt install certbot python3-certbot-nginx
-
-# 申请证书
-sudo certbot --nginx -d your-domain.com
-
-# 自动续期
-sudo certbot renew --dry-run
-```
-
-### HTTPS 配置
-
-```nginx
-server {
-    listen 443 ssl http2;
-    server_name your-domain.com;
-
-    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
-    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
-
-    # SSL 安全配置
-    ssl_protocols TLSv1.2 TLSv1.3;
-    ssl_prefer_server_ciphers on;
-    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
-
-    # HSTS
-    add_header Strict-Transport-Security "max-age=31536000" always;
-
-    # ... 其他配置同上
-}
-
-# HTTP 重定向到 HTTPS
-server {
-    listen 80;
-    server_name your-domain.com;
-    return 301 https://$server_name$request_uri;
-}
-```
-
-## 性能优化
-
-### Nginx 优化
-
-```nginx
-# 在 http 块中添加
-worker_processes auto;
-worker_connections 1024;
-
-# 开启 sendfile
-sendfile on;
-tcp_nopush on;
-tcp_nodelay on;
-
-# 缓冲区设置
-client_body_buffer_size 10K;
-client_header_buffer_size 1k;
-client_max_body_size 8m;
-```
-
-### 静态资源 CDN
-
-如果使用 CDN，修改构建配置：
-
-```env
-# .env.production
-VITE_CDN_URL=https://cdn.your-domain.com
-```
-
-## 监控与日志
-
-### 访问日志
-
-```nginx
-access_log /var/log/nginx/ai-assistant.access.log;
-error_log /var/log/nginx/ai-assistant.error.log;
-```
-
-### 日志轮转
-
-```bash
-# /etc/logrotate.d/nginx
-/var/log/nginx/*.log {
-    daily
-    rotate 14
-    compress
-    delaycompress
-    missingok
-    notifempty
-}
-```
-
-## 备份策略
-
-### 数据库备份
-
-```bash
-# PostgreSQL 备份
-pg_dump -U postgres ai_assistant > backup_$(date +%Y%m%d).sql
-
-# 定时备份（crontab）
-0 2 * * * pg_dump -U postgres ai_assistant > /backups/backup_$(date +\%Y\%m\%d).sql
-```
-
-## 高可用部署
-
-对于高可用需求，建议：
-
-1. **负载均衡** - 使用 Nginx upstream 或云负载均衡
-2. **数据库主从** - PostgreSQL 主从复制
-3. **Redis 集群** - 会话和缓存高可用
-4. **健康检查** - 定期检测服务状态
--- a/docs/content/getting-started/configuration.md
+++ b/docs/content/getting-started/configuration.md
@@ -57,23 +57,13 @@ VITE_GEMINI_API_KEY=your_api_key
 | `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
-    ```
-
-=== "生产环境"
-
-    ```env
-    # .env.production
-    VITE_API_URL=https://api.example.com
-    VITE_WS_URL=wss://ws.example.com
-    ```
+```env
+# .env.development
+VITE_API_URL=http://localhost:8080
+VITE_WS_URL=ws://localhost:8000
+```

 ---

@@ -219,7 +209,7 @@ services:

 ```env
 # Docker Compose 会自动加载
-SECRET_KEY=your-production-secret-key
+SECRET_KEY=your-secret-key-at-least-32-chars
 POSTGRES_PASSWORD=secure-db-password
 ```

@@ -286,4 +276,3 @@ python -c "from config import settings; print(settings)"

 - [安装部署](index.md) - 开始安装服务
 - [Docker 部署](../deployment/docker.md) - 容器化部署
- [生产环境](../deployment/production.md) - 生产配置指南
--- a/docs/content/getting-started/index.md
+++ b/docs/content/getting-started/index.md
@@ -187,4 +187,4 @@ python --version  # 需要 3.10+
 - [环境要求](requirements.md) - 详细的软件版本要求
 - [配置说明](configuration.md) - 环境变量配置指南
 - [快速开始](../quickstart/index.md) - 创建第一个助手
- [Docker 部署](../deployment/docker.md) - 生产环境部署
+- [Docker 部署](../deployment/docker.md) - 镜像构建与编排
--- a/docs/content/getting-started/requirements.md
+++ b/docs/content/getting-started/requirements.md
@@ -88,15 +88,6 @@
 | **磁盘** | 10GB | 20GB+ SSD |
 | **网络** | 10Mbps | 100Mbps |

-### 生产环境
-
-| 资源 | 小规模 (< 100 并发) | 中规模 (< 1000 并发) | 大规模 (> 1000 并发) |
-|------|---------------------|---------------------|---------------------|
-| **CPU** | 4 核心 | 8 核心 | 16 核心+ |
-| **内存** | 8GB | 16GB | 32GB+ |
-| **磁盘** | 50GB SSD | 200GB SSD | 500GB+ SSD |
-| **网络** | 100Mbps | 1Gbps | 10Gbps |
-
 ---

 ## 网络要求
--- a/docs/content/images/logo.png
+++ b/docs/content/images/logo.png
--- a/docs/content/index.md
+++ b/docs/content/index.md
@@ -1,4 +1,6 @@
-<h1 align="center">Realtime Agent Studio</h1>
+<p align="center">
+  <img src="images/logo.png" alt="Realtime Agent Studio" width="400">
+</p>

 <p align="center">
  <strong>构建实时交互音视频智能体的开源工作平台</strong>
@@ -14,7 +16,7 @@
 <p align="center">
  <a href="quickstart/index.md">快速开始</a> ·
  <a href="api-reference/index.md">API 文档</a> ·
-  <a href="deployment/index.md">部署指南</a> ·
+  <a href="getting-started/index.md">安装部署</a> ·
  <a href="roadmap.md">路线图</a>
 </p>

@@ -26,8 +28,6 @@ Realtime Agent Studio (RAS) 是一款以大语言模型为核心，构建实时

 可以将 RAS 看作 [Vapi](https://vapi.ai)、[Retell](https://retellai.com)、[ElevenLabs Agents](https://elevenlabs.io) 的**开源替代方案**。

-![仪表盘](images/dashboard.png)
-
 ---

 ## 核心特性
@@ -120,6 +120,7 @@ flowchart LR
 | **后端** | FastAPI (Python 3.10+) |
 | **引擎** | Python, WebSocket, asyncio |
 | **数据库** | SQLite / PostgreSQL |
+| **知识库** |  |
 | **部署** | Docker, Nginx |

 ---
@@ -144,7 +145,7 @@ flowchart LR

    ---

-    环境准备与本地开发配置
+    环境准备、本地开发与 Docker/生产部署

 -   :robot: **[助手管理](assistants/index.md)**

@@ -170,12 +171,6 @@ flowchart LR

    WebSocket 协议与 REST 接口文档

-   :cloud: **[部署指南](deployment/index.md)**
-
-    ---
-
-    Docker 与生产环境部署
-
 </div>

 ---
@@ -186,8 +181,10 @@ flowchart LR

 ```bash
 git clone https://github.com/your-org/AI-VideoAssistant.git
-cd AI-VideoAssistant
+cd docker
 docker-compose up -d
+# for development
+# docker compose --profile dev up -d
 ```

 访问 `http://localhost:3000` 即可使用控制台。
--- a/docs/content/overview/architecture.md
+++ b/docs/content/overview/architecture.md
@@ -257,48 +257,6 @@ flowchart LR
    Engine --> API
 ```

-### 生产环境
-
-```mermaid
-flowchart TB
-    subgraph Internet["互联网"]
-        User[用户]
-    end
-
-    subgraph LoadBalancer["负载均衡"]
-        Nginx[Nginx / Traefik]
-    end
-
-    subgraph Docker["Docker 集群"]
-        Web1[Web 容器]
-        Web2[Web 容器]
-        API1[API 容器]
-        API2[API 容器]
-        Engine1[Engine 容器]
-        Engine2[Engine 容器]
-    end
-
-    subgraph Storage["持久化存储"]
-        PG[(PostgreSQL)]
-        Redis[(Redis)]
-        S3[对象存储]
-    end
-
-    User --> Nginx
-    Nginx --> Web1
-    Nginx --> Web2
-    Nginx --> API1
-    Nginx --> API2
-    Nginx --> Engine1
-    Nginx --> Engine2
-    API1 --> PG
-    API2 --> PG
-    API1 --> Redis
-    Engine1 --> Redis
-```
-
---
-
 ## 技术选型

 | 组件 | 技术 | 选型理由 |
@@ -352,5 +310,5 @@ classDiagram
 ## 相关文档

 - [WebSocket 协议](../api-reference/websocket.md) - 详细的协议规范
- [部署指南](../deployment/index.md) - 生产环境部署
+- [部署概览](../deployment/index.md) - Docker 部署
 - [核心概念](../concepts/index.md) - 助手、管线等概念说明
--- a/docs/content/quickstart/index.md
+++ b/docs/content/quickstart/index.md
@@ -273,4 +273,4 @@ ws.onmessage = (event) => {
 - [配置知识库](../customization/knowledge-base.md) - 让助手回答专业问题
 - [添加工具](../customization/tools.md) - 扩展助手能力
 - [查看 API 文档](../api-reference/websocket.md) - 深入了解协议细节
- [部署到生产环境](../deployment/index.md) - 正式上线
+- [Docker 部署](../deployment/index.md) - 使用容器运行
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -1,8 +1,6 @@
 site_name: "Realtime Agent Studio"
 site_description: "构建实时交互音视频智能体的开源工作平台"
 site_url: "https://your-org.github.io/AI-VideoAssistant"
-repo_name: "AI-VideoAssistant"
-repo_url: "https://github.com/your-org/AI-VideoAssistant"
 copyright: "Copyright &copy; 2025 RAS Team"
 site_author: "RAS Team"

@@ -25,6 +23,8 @@ nav:
      - 概述: getting-started/index.md
      - 环境要求: getting-started/requirements.md
      - 配置说明: getting-started/configuration.md
+      - 部署概览: deployment/index.md
+      - Docker 部署: deployment/docker.md
  - 助手管理:
      - 概述: assistants/index.md
      - 配置选项: assistants/configuration.md
@@ -45,10 +45,6 @@ nav:
      - 概述: api-reference/index.md
      - WebSocket 协议: api-reference/websocket.md
      - 错误码: api-reference/errors.md
-  - 部署指南:
-      - 概述: deployment/index.md
-      - Docker 部署: deployment/docker.md
-      - 生产环境: deployment/production.md
  - 资源:
      - 常见问题: resources/faq.md
      - 故障排查: resources/troubleshooting.md
@@ -97,9 +93,6 @@ theme:
    - content.code.copy
    - content.code.annotate
    - content.tabs.link
-  icon:
-    repo: fontawesome/brands/github
-
 markdown_extensions:
  - abbr
  - admonition
@@ -152,8 +145,7 @@ plugins:
      minify_html: true

 extra:
-  version:
-    provider: mike
+  # version.provider: mike — only enable when deploying with mike (versions.json is generated on deploy)
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/your-org/AI-VideoAssistant
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -0,0 +1,4 @@
+# Pin MkDocs to 1.x; Material for MkDocs is not yet compatible with MkDocs 2.0
+# https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/
+mkdocs>=1.6,<2
+mkdocs-material