# AI Router Docker 部署指南

本文档提供了 AI Router 项目的 Docker 容器化部署完整指南。

## 📋 目录

- [系统架构](#系统架构)
- [前置要求](#前置要求)
- [快速开始](#快速开始)
- [详细配置](#详细配置)
- [构建和运行](#构建和运行)
- [管理和维护](#管理和维护)
- [故障排查](#故障排查)
- [性能优化](#性能优化)
- [安全建议](#安全建议)

## 🏗️ 系统架构

本项目使用 Docker Compose 编排两个主要服务：

```
┌─────────────────────────────────────────┐
│          Docker Host                     │
│                                          │
│  ┌────────────────────────────────────┐ │
│  │   Frontend Container (Nginx)       │ │
│  │   端口: 3000 → 80                  │ │
│  │   - React 应用                     │ │
│  │   - Nginx 静态文件服务             │ │
│  │   - API 请求代理                   │ │
│  └────────────────┬───────────────────┘ │
│                   │                      │
│                   │ API 代理             │
│                   ↓                      │
│  ┌────────────────────────────────────┐ │
│  │   Backend Container (Go)           │ │
│  │   端口: 8080                       │ │
│  │   - Go API 服务                    │ │
│  │   - SQLite 数据库                  │ │
│  └────────────────┬───────────────────┘ │
│                   │                      │
│                   ↓                      │
│  ┌────────────────────────────────────┐ │
│  │   Volume: backend-data             │ │
│  │   持久化数据库文件                 │ │
│  └────────────────────────────────────┘ │
└─────────────────────────────────────────┘
```

### 容器说明

#### 前端容器 (ai-router-frontend)
- **基础镜像**: nginx:1.27-alpine
- **构建方式**: 多阶段构建（Node.js 构建 + Nginx 运行）
- **端口映射**: 3000:80
- **功能**:
  - 托管 React 静态文件
  - 支持 React Router 的 HTML5 History API
  - 将 `/api/*` 请求代理到后端服务
  - 提供健康检查端点 `/health`

#### 后端容器 (ai-router-backend)
- **基础镜像**: debian:bookworm-slim
- **构建方式**: 多阶段构建（Go 编译 + 精简运行环境）
- **端口映射**: 8080:8080
- **功能**:
  - 提供 RESTful API 服务
  - 管理 SQLite 数据库
  - 处理 AI 模型路由逻辑
  - 提供健康检查端点

## 📦 前置要求

### 必需软件

- **Docker**: 版本 20.10.0 或更高
- **Docker Compose**: 版本 2.0.0 或更高

### 检查安装

```bash
# 检查 Docker 版本
docker --version

# 检查 Docker Compose 版本
docker compose version

# 验证 Docker 运行状态
docker info
```

### 系统要求

- **最低配置**:
  - CPU: 2 核
  - 内存: 2GB
  - 磁盘空间: 5GB

- **推荐配置**:
  - CPU: 4 核或更多
  - 内存: 4GB 或更多
  - 磁盘空间: 10GB 或更多

## 🚀 快速开始

### 1. 克隆项目（如果还没有）

```bash
git clone <repository-url>
cd ai_router
```

### 2. 配置环境变量（可选）

```bash
# 复制环境变量示例文件
cp .env.example .env

# 根据需要编辑 .env 文件
# 默认配置已经可以直接使用
```

### 3. 构建并启动服务

```bash
# 构建镜像并启动所有服务
docker compose up --build -d
```

### 4. 验证部署

```bash
# 查看容器运行状态
docker compose ps

# 查看服务日志
docker compose logs -f

# 检查前端服务
curl http://localhost:3000/health

# 检查后端服务
curl http://localhost:8080/api/providers
```

### 5. 访问应用

- **前端界面**: http://localhost:3000
- **后端 API**: http://localhost:8080/api

## ⚙️ 详细配置

### 环境变量配置

项目支持通过环境变量进行配置。创建 `.env` 文件或在 `docker-compose.yml` 中直接设置。

#### 核心配置

```bash
# 数据库路径
DB_PATH=/app/data/gateway.db

# 服务端口
BACKEND_PORT=8080
FRONTEND_PORT=3000

# 日志级别
LOG_LEVEL=info

# 项目名称
COMPOSE_PROJECT_NAME=ai-router
```

#### 修改端口映射

如果需要修改对外暴露的端口，编辑 `docker-compose.yml`:

```yaml
services:
  backend:
    ports:
      - "自定义端口:8080"  # 例如 "9000:8080"
  
  frontend:
    ports:
      - "自定义端口:80"    # 例如 "8080:80"
```

### 数据持久化

后端数据库文件通过 Docker Volume 持久化：

```bash
# 查看数据卷
docker volume ls | grep ai-router

# 查看数据卷详情
docker volume inspect ai-router-backend-data

# 备份数据卷
docker run --rm -v ai-router-backend-data:/data -v $(pwd):/backup alpine tar czf /backup/backup-$(date +%Y%m%d-%H%M%S).tar.gz -C /data .

# 恢复数据卷
docker run --rm -v ai-router-backend-data:/data -v $(pwd):/backup alpine tar xzf /backup/backup-YYYYMMDD-HHMMSS.tar.gz -C /data
```

## 🔧 构建和运行

### 开发环境

```bash
# 启动服务（前台运行，可以看到实时日志）
docker compose up

# 启动服务（后台运行）
docker compose up -d

# 仅启动特定服务
docker compose up backend
docker compose up frontend

# 重新构建并启动
docker compose up --build
```

### 生产环境

```bash
# 构建生产镜像
docker compose build --no-cache

# 启动服务
docker compose up -d

# 查看服务状态
docker compose ps

# 查看资源使用情况
docker stats
```

### 单独构建镜像

```bash
# 构建后端镜像
cd backend
docker build -t ai-router-backend:latest .

# 构建前端镜像
cd frontend
docker build -t ai-router-frontend:latest .
```

## 🛠️ 管理和维护

### 查看日志

```bash
# 查看所有服务日志
docker compose logs

# 实时跟踪日志
docker compose logs -f

# 查看特定服务的日志
docker compose logs backend
docker compose logs frontend

# 查看最近 100 行日志
docker compose logs --tail=100

# 查看带时间戳的日志
docker compose logs -t
```

### 重启服务

```bash
# 重启所有服务
docker compose restart

# 重启特定服务
docker compose restart backend
docker compose restart frontend

# 优雅停止后重启
docker compose down && docker compose up -d
```

### 更新服务

```bash
# 拉取最新代码
git pull

# 重新构建并启动
docker compose up --build -d

# 查看更新后的状态
docker compose ps
```

### 停止和删除

```bash
# 停止所有服务
docker compose stop

# 停止并删除容器（保留数据卷）
docker compose down

# 停止并删除容器和数据卷（谨慎使用！）
docker compose down -v

# 停止并删除所有内容（包括镜像）
docker compose down -v --rmi all
```

### 清理系统

```bash
# 删除未使用的容器
docker container prune

# 删除未使用的镜像
docker image prune

# 删除未使用的数据卷
docker volume prune

# 清理所有未使用的资源
docker system prune -a
```

## 🔍 故障排查

### 常见问题

#### 1. 容器无法启动

```bash
# 检查容器状态
docker compose ps

# 查看详细错误信息
docker compose logs

# 检查端口占用
netstat -an | grep 3000
netstat -an | grep 8080

# Windows 系统
netstat -ano | findstr "3000"
netstat -ano | findstr "8080"
```

#### 2. 前端无法连接后端

```bash
# 检查网络连接
docker compose exec frontend ping backend

# 检查后端服务是否正常
docker compose exec backend wget -O- http://localhost:8080/api/providers

# 查看 Nginx 配置
docker compose exec frontend cat /etc/nginx/conf.d/default.conf

# 查看 Nginx 错误日志
docker compose logs frontend | grep error
```

#### 3. 数据库问题

```bash
# 进入后端容器
docker compose exec backend sh

# 检查数据库文件
ls -lh /app/data/

# 查看数据库文件权限
ls -l /app/data/gateway.db

# 检查数据库连接
# 在容器内执行应用的健康检查
```

#### 4. 构建失败

```bash
# 清理 Docker 缓存
docker builder prune

# 完全重新构建（不使用缓存）
docker compose build --no-cache

# 检查 Dockerfile 语法
docker compose config

# 查看构建日志
docker compose build --progress=plain
```

#### 5. 性能问题

```bash
# 查看容器资源使用
docker stats

# 查看容器详细信息
docker compose exec backend top
docker compose exec frontend top

# 检查磁盘空间
docker system df

# 查看网络延迟
docker compose exec frontend ping -c 5 backend
```

### 健康检查

```bash
# 前端健康检查
curl -f http://localhost:3000/health || echo "Frontend unhealthy"

# 后端健康检查
curl -f http://localhost:8080/api/providers || echo "Backend unhealthy"

# 查看容器健康状态
docker compose ps
```

### 调试模式

```bash
# 进入容器进行调试
docker compose exec backend sh
docker compose exec frontend sh

# 以 root 用户进入
docker compose exec -u root backend sh

# 运行临时调试容器
docker run -it --rm --network ai-router-network alpine sh
```

## ⚡ 性能优化

### 镜像优化

1. **使用多阶段构建**：已在 Dockerfile 中实现
2. **最小化镜像层**：合并 RUN 命令
3. **使用 .dockerignore**：已配置，排除不必要的文件

### 资源限制

编辑 `docker-compose.yml` 添加资源限制：

```yaml
services:
  backend:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 1G
        reservations:
          cpus: '1'
          memory: 512M
  
  frontend:
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M
```

### 网络优化

```yaml
networks:
  ai-router-network:
    driver: bridge
    driver_opts:
      com.docker.network.driver.mtu: 1500
```

### 日志优化

```yaml
services:
  backend:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
```

## 🔒 安全建议

### 1. 使用非 root 用户

修改 Dockerfile 添加专用用户：

```dockerfile
# 后端 Dockerfile
RUN groupadd -r appuser && useradd -r -g appuser appuser
USER appuser
```

### 2. 网络隔离

```yaml
# 限制容器间通信
networks:
  ai-router-network:
    internal: true  # 仅内部通信
```

### 3. 环境变量安全

- 不要在 `docker-compose.yml` 中硬编码敏感信息
- 使用 `.env` 文件，并将其添加到 `.gitignore`
- 生产环境使用 Docker Secrets

### 4. 定期更新

```bash
# 更新基础镜像
docker compose pull

# 重新构建
docker compose build --pull

# 重启服务
docker compose up -d
```

### 5. 限制容器权限

```yaml
services:
  backend:
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
```

## 📊 监控建议

### 使用 Docker Stats

```bash
# 实时监控
docker stats

# 监控特定容器
docker stats ai-router-backend ai-router-frontend
```

### 集成监控工具

推荐使用以下监控工具：

- **Prometheus + Grafana**: 指标收集和可视化
- **ELK Stack**: 日志聚合和分析
- **cAdvisor**: 容器性能监控

### 日志管理

```bash
# 设置日志轮转
# 在 docker-compose.yml 中配置
logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "5"
```

## 🌐 生产部署建议

### 1. 使用反向代理

在生产环境中，建议在 Docker 服务前部署 Nginx 或 Traefik 作为反向代理：

```nginx
# 示例 Nginx 配置
server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

### 2. 启用 HTTPS

使用 Let's Encrypt 免费证书：

```bash
# 使用 Certbot
certbot --nginx -d your-domain.com
```

### 3. 配置自动重启

```yaml
services:
  backend:
    restart: unless-stopped
  frontend:
    restart: unless-stopped
```

### 4. 数据备份策略

```bash
# 创建自动备份脚本
#!/bin/bash
BACKUP_DIR="/backup"
DATE=$(date +%Y%m%d-%H%M%S)
docker run --rm -v ai-router-backend-data:/data -v $BACKUP_DIR:/backup alpine tar czf /backup/db-$DATE.tar.gz -C /data .

# 添加到 crontab
0 2 * * * /path/to/backup-script.sh
```

### 5. CI/CD 集成

```yaml
# GitHub Actions 示例
name: Build and Deploy
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Build images
        run: docker compose build
      - name: Push images
        run: docker compose push
```

## 📝 维护清单

### 每日检查
- [ ] 查看容器运行状态
- [ ] 检查日志是否有错误
- [ ] 监控资源使用情况

### 每周检查
- [ ] 备份数据库
- [ ] 清理未使用的镜像和容器
- [ ] 检查磁盘空间

### 每月检查
- [ ] 更新基础镜像
- [ ] 审查安全更新
- [ ] 性能优化评估

## 🆘 获取帮助

如果遇到问题，可以：

1. 查看日志：`docker compose logs`
2. 检查本文档的故障排查部分
3. 查看 GitHub Issues
4. 联系项目维护者

## 📚 相关资源

- [Docker 官方文档](https://docs.docker.com/)
- [Docker Compose 文档](https://docs.docker.com/compose/)
- [项目 GitHub](https://github.com/your-repo)
- [API 文档](./backend/docs/)

---

**最后更新**: 2025-11-10

**版本**: 1.0.0