Revamp documentation structure in mkdocs.yml by reorganizing navigation for improved accessibility. Remove outdated content from previous sections and introduce new topics including detailed guides on assistant management, configuration options, and tool integrations. Enhance API reference documentation with comprehensive error codes and WebSocket protocol details. Add new sections for automated testing, data analysis, and knowledge base management, ensuring a cohesive and user-friendly documentation experience.

2026-03-01 22:38:50 +08:00
parent 6a46ec69f4
commit 2418df80e5
33 changed files with 3664 additions and 693 deletions
--- a/docs/content/deployment/docker.md
+++ b/docs/content/deployment/docker.md
@@ -0,0 +1,161 @@
+# Docker 部署
+
+Docker 是推荐的部署方式，可以快速启动服务并确保环境一致性。
+
+## 前提条件
+
+- Docker 20.10+
+- Docker Compose 2.0+（可选）
+
+## 构建镜像
+
+### Web 前端
+
+```bash
+docker build -t ai-video-assistant-web ./web
+```
+
+### API 服务
+
+```bash
+docker build -t ai-video-assistant-api ./api
+```
+
+### Engine 服务
+
+```bash
+docker build -t ai-video-assistant-engine ./engine
+```
+
+## 运行容器
+
+### 单独运行
+
+```bash
+# Web 前端
+docker run -d \
+  --name ai-assistant-web \
+  -p 3000:80 \
+  ai-video-assistant-web
+
+# API 服务
+docker run -d \
+  --name ai-assistant-api \
+  -p 8080:8080 \
+  ai-video-assistant-api
+
+# Engine 服务
+docker run -d \
+  --name ai-assistant-engine \
+  -p 8000:8000 \
+  ai-video-assistant-engine
+```
+
+## Docker Compose
+
+推荐使用 Docker Compose 管理多个服务：
+
+```yaml
+version: '3.8'
+
+services:
+  web:
+    build: ./web
+    ports:
+      - "3000:80"
+    environment:
+      - VITE_API_URL=http://api:8080
+    depends_on:
+      - api
+
+  api:
+    build: ./api
+    ports:
+      - "8080:8080"
+    environment:
+      - DATABASE_URL=postgresql://postgres:password@db:5432/ai_assistant
+    depends_on:
+      - db
+
+  engine:
+    build: ./engine
+    ports:
+      - "8000:8000"
+    environment:
+      - BACKEND_URL=http://api:8080
+
+  db:
+    image: postgres:15
+    environment:
+      - POSTGRES_DB=ai_assistant
+      - POSTGRES_PASSWORD=password
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+volumes:
+  postgres_data:
+```
+
+### 启动服务
+
+```bash
+# 启动所有服务
+docker-compose up -d
+
+# 查看日志
+docker-compose logs -f
+
+# 停止服务
+docker-compose down
+```
+
+## 镜像优化
+
+### 多阶段构建
+
+Web 前端 Dockerfile 示例：
+
+```dockerfile
+# 构建阶段
+FROM node:18-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# 运行阶段
+FROM nginx:alpine
+COPY --from=builder /app/dist /usr/share/nginx/html
+COPY nginx.conf /etc/nginx/nginx.conf
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]
+```
+
+## 健康检查
+
+```yaml
+services:
+  api:
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+```
+
+## 常见问题
+
+### 容器启动失败
+
+```bash
+# 查看容器日志
+docker logs ai-assistant-web
+
+# 进入容器调试
+docker exec -it ai-assistant-web sh
+```
+
+### 端口冲突
+
+修改 `docker-compose.yml` 中的端口映射，例如 `3001:80`。
--- a/docs/content/deployment/index.md
+++ b/docs/content/deployment/index.md
@@ -0,0 +1,42 @@
+# 部署指南
+
+本章节介绍如何将 AI Video Assistant 部署到生产环境。
+
+## 部署方式
+
+| 方式 | 适用场景 | 复杂度 |
+|------|---------|--------|
+| [Docker 部署](docker.md) | 快速部署、容器化环境 | 简单 |
+| [生产环境](production.md) | Nginx 反向代理、高可用 | 中等 |
+
+## 快速开始
+
+### Docker 一键部署
+
+```bash
+docker build -t ai-video-assistant-web ./web
+docker run -d -p 3000:80 --name ai-assistant-web ai-video-assistant-web
+```
+
+### 验证部署
+
+1. 访问 http://your-domain.com
+2. 检查页面是否正常加载
+3. 验证各功能模块是否可用
+
+## 环境变量配置
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| VITE_API_URL | 后端 API 地址 | http://localhost:8080 |
+| VITE_GEMINI_API_KEY | Gemini API Key | - |
+
+## 故障排查
+
+| 问题 | 解决方案 |
+|------|---------|
+| 页面空白 | 检查浏览器控制台错误 |
+| API 请求失败 | 确认 VITE_API_URL 配置正确 |
+| 静态资源 404 | 检查 nginx try_files 配置 |
+
+更多问题请参考 [故障排查](../resources/troubleshooting.md)。
--- a/docs/content/deployment/production.md
+++ b/docs/content/deployment/production.md
@@ -0,0 +1,191 @@
+# 生产环境部署
+
+本文档介绍如何将 AI Video Assistant 部署到生产环境，包括 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. **健康检查** - 定期检测服务状态