ai_learn_node/JENKINS_DEPLOY.md

Jenkins 部署配置说明

本文档说明如何通过 Jenkins 将项目部署到远程服务器 180.76.180.105 的 /opt/nginx/html/ai 目录。

前置要求

1. Jenkins 服务器要求

• Jenkins 已安装并运行
• 安装了必要的插件：
  • Pipeline 插件
  • SSH Pipeline Steps 插件（可选，用于更好的 SSH 支持）
• Node.js 和 npm 已安装（用于构建）

2. 远程服务器要求

• 服务器 IP: 180.76.180.105
• 部署目录: /opt/nginx/html/ai
• 需要安装：
  • Node.js (推荐 v18+)
  • npm
  • nginx
  • PM2（用于管理后端进程，可选）

3. SSH 配置

确保 Jenkins 服务器可以通过 SSH 无密码登录到远程服务器：

# 在 Jenkins 服务器上生成 SSH 密钥（如果还没有）
ssh-keygen -t rsa -b 4096

# 将公钥复制到远程服务器
ssh-copy-id root@180.76.180.105

# 测试连接
ssh root@180.76.180.105

或者在 Jenkins 中配置 SSH 凭据：

1. 进入 Jenkins → 系统管理 → 凭据管理
2. 添加 SSH 凭据
3. 在 Jenkinsfile 中使用 SSH_CREDENTIALS 环境变量

Jenkins 配置步骤

1. 创建 Pipeline 任务

1. 在 Jenkins 中创建新任务
2. 选择 "流水线" (Pipeline) 类型
3. 在 "流水线" 配置中：
   • 定义: Pipeline script from SCM
   • SCM: Git
   • Repository URL: 你的 Git 仓库地址
   • 脚本路径: Jenkinsfile

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

如果需要修改默认配置，可以在 Jenkinsfile 中修改 environment 部分：

environment {
    DEPLOY_HOST = '180.76.180.105'
    DEPLOY_USER = 'root'  // 根据实际情况修改
    DEPLOY_PATH = '/opt/nginx/html/ai'
}

3. 配置 SSH 凭据（推荐）

如果使用 SSH 凭据而不是密钥文件：

1. 在 Jenkins 中添加 SSH 凭据（ID: deploy-ssh-key）
2. 修改 Jenkinsfile 中的部署步骤，使用 withCredentials：

withCredentials([sshUserPrivateKey(credentialsId: 'deploy-ssh-key', keyFileVariable: 'SSH_KEY')]) {
    sh '''
        ssh -i $SSH_KEY -o StrictHostKeyChecking=no ${DEPLOY_USER}@${DEPLOY_HOST} ...
    '''
}

部署流程

Jenkins 流水线将执行以下步骤：

1. Checkout: 检出代码
2. Install Dependencies: 安装所有依赖
3. Build Frontend: 构建前端（生成 frontend/dist）
4. Build Backend: 构建后端（生成 backend/dist）
5. Prepare Deployment Package: 打包部署文件
6. Deploy to Remote Server:
   • 传输文件到远程服务器
   • 解压并部署到 /opt/nginx/html/ai/current
   • 备份旧版本
7. Restart Services: 重启后端服务和 nginx

远程服务器配置

1. 创建部署目录

sudo mkdir -p /opt/nginx/html/ai
sudo chown -R $USER:$USER /opt/nginx/html/ai

2. 配置 Nginx

将 nginx/nginx.conf 复制到系统 nginx 配置目录：

# Ubuntu/Debian
sudo cp /opt/nginx/html/ai/current/nginx/nginx.conf /etc/nginx/sites-available/ai-learning-platform
sudo ln -s /etc/nginx/sites-available/ai-learning-platform /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

注意: 需要修改 nginx.conf 中的前端文件路径：

location / {
    root /opt/nginx/html/ai/current;  # 修改这里
    index index.html;
    try_files $uri $uri/ /index.html;
}

3. 配置后端服务

使用 PM2（推荐）

# 安装 PM2
npm install -g pm2

# 启动后端服务
cd /opt/nginx/html/ai/current/backend
pm2 start dist/index.js --name ai-learning-backend
pm2 save
pm2 startup  # 设置开机自启

使用 systemd

创建 systemd 服务文件 /etc/systemd/system/ai-learning-backend.service:

[Unit]
Description=AI Learning Platform Backend
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/nginx/html/ai/current/backend
ExecStart=/usr/bin/node dist/index.js
Restart=always
RestartSec=10
Environment=NODE_ENV=production
Environment=PORT=3001

[Install]
WantedBy=multi-user.target

然后启用服务：

sudo systemctl daemon-reload
sudo systemctl enable ai-learning-backend
sudo systemctl start ai-learning-backend

手动部署（测试）

如果需要手动测试部署流程：

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

# 2. 创建部署包
mkdir -p deploy-package
cp -r frontend/dist deploy-package/frontend-dist
cp -r backend/dist deploy-package/backend/dist
cp -r backend/prisma deploy-package/backend/prisma
cp backend/package.json deploy-package/backend/
cp nginx/nginx.conf deploy-package/nginx/
cp scripts/deploy.sh deploy-package/
tar -czf deploy-package.tar.gz deploy-package/

# 3. 传输到远程服务器
scp deploy-package.tar.gz root@180.76.180.105:/tmp/

# 4. 在远程服务器上执行
ssh root@180.76.180.105
cd /tmp
tar -xzf deploy-package.tar.gz
mkdir -p /opt/nginx/html/ai/current
cp -r deploy-package/frontend-dist/* /opt/nginx/html/ai/current/
cp -r deploy-package/backend /opt/nginx/html/ai/current/
bash deploy-package/deploy.sh /opt/nginx/html/ai/current

故障排查

1. SSH 连接失败

• 检查网络连接
• 确认 SSH 密钥配置正确
• 检查防火墙设置

2. 构建失败

• 检查 Node.js 版本
• 确认所有依赖已安装
• 查看 Jenkins 构建日志

3. 部署后服务无法访问

• 检查 nginx 配置是否正确
• 确认后端服务是否运行：pm2 list 或 systemctl status ai-learning-backend
• 检查端口是否被占用：netstat -tulpn | grep 3001
• 查看日志：pm2 logs ai-learning-backend 或 journalctl -u ai-learning-backend

4. 数据库问题

• 确认数据库文件权限
• 检查 Prisma 迁移是否成功
• 查看数据库文件：ls -la /opt/nginx/html/ai/current/backend/prisma/

安全建议

1. 不要使用 root 用户: 建议创建专用部署用户
2. 使用 SSH 密钥: 避免使用密码认证
3. 限制 SSH 访问: 使用防火墙限制 SSH 访问来源
4. 定期备份: 自动备份数据库和配置文件
5. 监控日志: 设置日志监控和告警

更新部署

每次代码更新后，只需在 Jenkins 中触发构建即可。Jenkins 会自动：

• 构建最新代码
• 部署到远程服务器
• 备份旧版本
• 重启服务

回滚

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

ssh root@180.76.180.105
cd /opt/nginx/html/ai
# 查看备份目录
ls -la backup-*
# 恢复备份
mv current current-failed
mv backup-YYYYMMDD-HHMMSS current
# 重启服务
pm2 restart ai-learning-backend
nginx -s reload