ai_learn_node/DOCKER_DEPLOY.md

Docker 部署说明

本文档说明如何在已有 Docker nginx 运行的服务器上部署本项目，避免端口和资源冲突。

部署架构

• 前端 Nginx: 运行在 8080 端口（避免与现有 nginx 的 80 端口冲突）
• 后端服务: 运行在 3001 端口
• 部署路径: /opt/nginx/html/ai/current
• 容器名称:
  • ai-learning-nginx (前端)
  • ai-learning-backend (后端)

避免冲突的设计

1. 端口隔离

• 现有 nginx: 80:80, 443:443
• 本项目 nginx: 8080:80, 8443:443
• 后端: 3001:3001

2. 路径隔离

• 使用独立的部署路径: /opt/nginx/html/ai/current
• 独立的日志目录: /opt/nginx/html/ai/current/docker/logs
• 独立的配置文件: /opt/nginx/html/ai/current/docker/

3. 容器名称隔离

• 使用唯一的容器名称，避免与现有容器冲突

4. Docker 网络隔离

• 使用独立的 Docker 网络: ai-learning-network

文件结构

部署后的目录结构：

/opt/nginx/html/ai/current/
├── index.html              # 前端入口文件
├── assets/                 # 前端静态资源
├── backend/                # 后端文件
│   ├── dist/              # 后端构建产物
│   ├── prisma/            # 数据库文件
│   ├── Dockerfile         # 后端 Dockerfile
│   └── package.json
└── docker/                # Docker 配置
    ├── docker-compose.yml
    ├── nginx.conf.docker
    └── logs/               # Nginx 日志

部署步骤

1. 通过 Jenkins 自动部署

Jenkins 流水线会自动：

1. 构建前端和后端
2. 打包部署文件
3. 传输到远程服务器
4. 解压并部署
5. 启动 Docker 容器

2. 手动部署

如果需要手动部署：

# 1. 构建项目
npm install
npm run install:all
npm run build

# 2. 创建部署目录
ssh root@180.76.180.105 "mkdir -p /opt/nginx/html/ai/current"

# 3. 传输文件
scp -r frontend/dist/* root@180.76.180.105:/opt/nginx/html/ai/current/
scp -r backend/dist backend/prisma backend/package.json backend/Dockerfile root@180.76.180.105:/opt/nginx/html/ai/current/backend/
scp nginx/docker-compose.production.yml root@180.76.180.105:/opt/nginx/html/ai/current/docker/docker-compose.yml
scp nginx/nginx.conf.docker root@180.76.180.105:/opt/nginx/html/ai/current/docker/nginx.conf.docker

# 4. 在服务器上启动
ssh root@180.76.180.105 << 'ENDSSH'
    cd /opt/nginx/html/ai/current/docker
    docker-compose up -d --build
ENDSSH

访问地址

• 前端: http://180.76.180.105:8080
• 后端 API: http://180.76.180.105:3001
• 健康检查: http://180.76.180.105:8080/health

常用命令

查看容器状态

cd /opt/nginx/html/ai/current/docker
docker-compose ps

查看日志

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

# 查看 nginx 日志
docker-compose logs -f nginx

# 查看后端日志
docker-compose logs -f backend

重启服务

cd /opt/nginx/html/ai/current/docker
docker-compose restart

停止服务

cd /opt/nginx/html/ai/current/docker
docker-compose down

重新构建并启动

cd /opt/nginx/html/ai/current/docker
docker-compose up -d --build

故障排查

1. 端口冲突

如果 8080 端口被占用：

# 检查端口占用
netstat -tulpn | grep 8080
# 或
lsof -i :8080

# 修改 docker-compose.yml 中的端口映射
# 例如改为 8081:80

2. 容器无法启动

# 查看容器日志
docker-compose logs

# 检查容器状态
docker ps -a | grep ai-learning

# 检查 Docker 网络
docker network ls

3. 前端无法访问

# 检查 nginx 容器是否运行
docker ps | grep ai-learning-nginx

# 检查 nginx 配置
docker exec ai-learning-nginx nginx -t

# 查看 nginx 日志
docker-compose logs nginx

4. 后端 API 无法访问

# 检查后端容器是否运行
docker ps | grep ai-learning-backend

# 检查后端日志
docker-compose logs backend

# 测试后端连接
curl http://localhost:3001/api/health

5. 数据库问题

# 检查数据库文件权限
ls -la /opt/nginx/html/ai/current/backend/prisma/

# 进入后端容器执行迁移
docker exec -it ai-learning-backend sh
npx prisma migrate deploy
npx prisma generate

与现有 nginx 集成（可选）

如果希望通过现有 nginx（80 端口）访问本项目，可以在现有 nginx 配置中添加反向代理：

# 添加到现有 nginx 配置
location /ai/ {
    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;
}

location /ai/api/ {
    proxy_pass http://localhost:3001/api/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

然后访问：http://180.76.180.105/ai/

更新部署

每次代码更新后，Jenkins 会自动：

1. 构建新版本
2. 备份旧版本到 /opt/nginx/html/ai/backup-YYYYMMDD-HHMMSS
3. 部署新版本
4. 重启 Docker 容器

回滚

如果需要回滚到之前的版本：

ssh root@180.76.180.105 << 'ENDSSH'
    cd /opt/nginx/html/ai
    
    # 查看备份
    ls -la backup-*
    
    # 停止当前容器
    cd current/docker
    docker-compose down
    
    # 恢复备份
    cd /opt/nginx/html/ai
    mv current current-failed
    mv backup-YYYYMMDD-HHMMSS current
    
    # 重启服务
    cd current/docker
    docker-compose up -d
ENDSSH

安全建议

1. 不要使用 root 用户: 建议创建专用部署用户
2. 限制端口访问: 使用防火墙限制 8080 端口的访问来源
3. 定期备份: 自动备份数据库和配置文件
4. 监控日志: 设置日志监控和告警
5. 更新镜像: 定期更新 nginx:alpine 和 node:18-alpine 镜像