14 KiB
14 KiB
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 或更高
检查安装
# 检查 Docker 版本
docker --version
# 检查 Docker Compose 版本
docker compose version
# 验证 Docker 运行状态
docker info
系统要求
-
最低配置:
- CPU: 2 核
- 内存: 2GB
- 磁盘空间: 5GB
-
推荐配置:
- CPU: 4 核或更多
- 内存: 4GB 或更多
- 磁盘空间: 10GB 或更多
🚀 快速开始
1. 克隆项目（如果还没有）
git clone <repository-url>
cd ai_router
2. 配置环境变量（可选）
# 复制环境变量示例文件
cp .env.example .env
# 根据需要编辑 .env 文件
# 默认配置已经可以直接使用
3. 构建并启动服务
# 构建镜像并启动所有服务
docker compose up --build -d
4. 验证部署
# 查看容器运行状态
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 中直接设置。
核心配置
# 数据库路径
DB_PATH=/app/data/gateway.db
# 服务端口
BACKEND_PORT=8080
FRONTEND_PORT=3000
# 日志级别
LOG_LEVEL=info
# 项目名称
COMPOSE_PROJECT_NAME=ai-router
修改端口映射
如果需要修改对外暴露的端口，编辑 docker-compose.yml:
services:
backend:
ports:
- "自定义端口:8080" # 例如 "9000:8080"
frontend:
ports:
- "自定义端口:80" # 例如 "8080:80"
数据持久化
后端数据库文件通过 Docker Volume 持久化：
# 查看数据卷
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
🔧 构建和运行
开发环境
# 启动服务（前台运行，可以看到实时日志）
docker compose up
# 启动服务（后台运行）
docker compose up -d
# 仅启动特定服务
docker compose up backend
docker compose up frontend
# 重新构建并启动
docker compose up --build
生产环境
# 构建生产镜像
docker compose build --no-cache
# 启动服务
docker compose up -d
# 查看服务状态
docker compose ps
# 查看资源使用情况
docker stats
单独构建镜像
# 构建后端镜像
cd backend
docker build -t ai-router-backend:latest .
# 构建前端镜像
cd frontend
docker build -t ai-router-frontend:latest .
🛠️ 管理和维护
查看日志
# 查看所有服务日志
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
重启服务
# 重启所有服务
docker compose restart
# 重启特定服务
docker compose restart backend
docker compose restart frontend
# 优雅停止后重启
docker compose down && docker compose up -d
更新服务
# 拉取最新代码
git pull
# 重新构建并启动
docker compose up --build -d
# 查看更新后的状态
docker compose ps
停止和删除
# 停止所有服务
docker compose stop
# 停止并删除容器（保留数据卷）
docker compose down
# 停止并删除容器和数据卷（谨慎使用！）
docker compose down -v
# 停止并删除所有内容（包括镜像）
docker compose down -v --rmi all
清理系统
# 删除未使用的容器
docker container prune
# 删除未使用的镜像
docker image prune
# 删除未使用的数据卷
docker volume prune
# 清理所有未使用的资源
docker system prune -a
🔍 故障排查
常见问题
1. 容器无法启动
# 检查容器状态
docker compose ps
# 查看详细错误信息
docker compose logs
# 检查端口占用
netstat -an | grep 3000
netstat -an | grep 8080
# Windows 系统
netstat -ano | findstr "3000"
netstat -ano | findstr "8080"
2. 前端无法连接后端
# 检查网络连接
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. 数据库问题
# 进入后端容器
docker compose exec backend sh
# 检查数据库文件
ls -lh /app/data/
# 查看数据库文件权限
ls -l /app/data/gateway.db
# 检查数据库连接
# 在容器内执行应用的健康检查
4. 构建失败
# 清理 Docker 缓存
docker builder prune
# 完全重新构建（不使用缓存）
docker compose build --no-cache
# 检查 Dockerfile 语法
docker compose config
# 查看构建日志
docker compose build --progress=plain
5. 性能问题
# 查看容器资源使用
docker stats
# 查看容器详细信息
docker compose exec backend top
docker compose exec frontend top
# 检查磁盘空间
docker system df
# 查看网络延迟
docker compose exec frontend ping -c 5 backend
健康检查
# 前端健康检查
curl -f http://localhost:3000/health || echo "Frontend unhealthy"
# 后端健康检查
curl -f http://localhost:8080/api/providers || echo "Backend unhealthy"
# 查看容器健康状态
docker compose ps
调试模式
# 进入容器进行调试
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
⚡ 性能优化
镜像优化
- 使用多阶段构建：已在 Dockerfile 中实现
- 最小化镜像层：合并 RUN 命令
- 使用 .dockerignore：已配置，排除不必要的文件
资源限制
编辑 docker-compose.yml 添加资源限制：
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
网络优化
networks:
ai-router-network:
driver: bridge
driver_opts:
com.docker.network.driver.mtu: 1500
日志优化
services:
backend:
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
🔒 安全建议
1. 使用非 root 用户
修改 Dockerfile 添加专用用户：
# 后端 Dockerfile
RUN groupadd -r appuser && useradd -r -g appuser appuser
USER appuser
2. 网络隔离
# 限制容器间通信
networks:
ai-router-network:
internal: true # 仅内部通信
3. 环境变量安全
- 不要在
docker-compose.yml中硬编码敏感信息 - 使用
.env文件，并将其添加到.gitignore - 生产环境使用 Docker Secrets
4. 定期更新
# 更新基础镜像
docker compose pull
# 重新构建
docker compose build --pull
# 重启服务
docker compose up -d
5. 限制容器权限
services:
backend:
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
cap_add:
- NET_BIND_SERVICE
📊 监控建议
使用 Docker Stats
# 实时监控
docker stats
# 监控特定容器
docker stats ai-router-backend ai-router-frontend
集成监控工具
推荐使用以下监控工具：
- Prometheus + Grafana: 指标收集和可视化
- ELK Stack: 日志聚合和分析
- cAdvisor: 容器性能监控
日志管理
# 设置日志轮转
# 在 docker-compose.yml 中配置
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "5"
🌐 生产部署建议
1. 使用反向代理
在生产环境中，建议在 Docker 服务前部署 Nginx 或 Traefik 作为反向代理：
# 示例 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 免费证书：
# 使用 Certbot
certbot --nginx -d your-domain.com
3. 配置自动重启
services:
backend:
restart: unless-stopped
frontend:
restart: unless-stopped
4. 数据备份策略
# 创建自动备份脚本
#!/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 集成
# 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
📝 维护清单
每日检查
- 查看容器运行状态
- 检查日志是否有错误
- 监控资源使用情况
每周检查
- 备份数据库
- 清理未使用的镜像和容器
- 检查磁盘空间
每月检查
- 更新基础镜像
- 审查安全更新
- 性能优化评估
🆘 获取帮助
如果遇到问题，可以：
- 查看日志：
docker compose logs - 检查本文档的故障排查部分
- 查看 GitHub Issues
- 联系项目维护者
📚 相关资源
最后更新: 2025-11-10
版本: 1.0.0