699 lines
14 KiB
Markdown
699 lines
14 KiB
Markdown
# 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 |