tic-tac-toe-game/CICD_SETUP_GUIDE.md

井字过三关游戏 - 完整CI/CD流水线配置指南

概述

本文档详细说明如何配置完整的CI/CD流水线，实现井字过三关游戏项目的自动化构建、测试和部署。

CI/CD 流水线结构

1. 触发机制

• Push触发: 当代码推送到main分支时自动触发
• Pull Request触发: 当创建或更新Pull Request到main分支时触发

2. 工作流详情

Job 1: build-and-test

• 运行环境: Ubuntu最新版
• 任务:
  • 检出代码
  • 设置Node.js环境
  • 验证HTML、CSS、JS文件完整性
  • 运行基本测试

Job 2: security-scan

• 运行环境: Ubuntu最新版
• 任务:
  • 对代码进行安全扫描
  • 检查潜在的安全漏洞

Job 3: deploy-dev

• 运行环境: 自托管Runner
• 依赖: build-and-test 和 security-scan
• 任务:
  • 部署到开发环境 /var/www/html/tic-tac-toe-dev
  • 设置适当权限

Job 4: deploy-prod

• 运行环境: 自托管Runner
• 依赖: deploy-dev
• 任务:
  • 部署到生产环境 /var/www/html/tic-tac-toe
  • 设置适当权限

Job 5: cleanup

• 运行环境: 自托管Runner
• 依赖: deploy-prod
• 任务:
  • 清理临时文件

部署路径

开发环境

• URL: http://<server-ip>/tic-tac-toe-dev/
• 文件路径: /var/www/html/tic-tac-toe-dev/

生产环境

• URL: http://<server-ip>/tic-tac-toe/
• 文件路径: /var/www/html/tic-tac-toe/

自托管Runner配置

要使CI/CD流水线正常工作，需要在目标服务器上配置Gitea Actions Runner:

# 1. 安装Gitea Actions Runner
sudo apt update
sudo apt install -y gitea-actions-runner

# 2. 配置Runner连接到Gitea服务器
# 获取Runner令牌（在Gitea管理面板中）

# 3. 启动Runner服务
sudo systemctl enable gitea-actions-runner
sudo systemctl start gitea-actions-runner

权限要求

Runner需要以下权限：

• 创建目录: /var/www/html/tic-tac-toe-dev 和 /var/www/html/tic-tac-toe
• 复制文件到Web目录
• 更改文件所有权为 www-data:www-data
• 设置文件权限为 644

验证部署

部署完成后，可以通过以下方式验证:

1. 访问开发环境URL检查功能
2. 访问生产环境URL确认部署成功
3. 检查Web服务器日志
4. 验证游戏功能是否正常

故障排除

常见问题

• Runner未运行: 检查服务状态 systemctl status gitea-actions-runner
• 权限错误: 确保Runner有足够的权限写入Web目录
• 网络问题: 确认服务器间网络连接正常

日志查看

• Gitea Actions日志: 在Gitea界面上查看
• Web服务器日志: /var/log/apache2/ 或 /var/log/nginx/
• Runner日志: /var/log/gitea-actions-runner/

扩展选项

环境变量

可以在Gitea中设置以下环境变量:

• DEV_SERVER: 开发服务器地址
• PROD_SERVER: 生产服务器地址
• WEB_ROOT: Web根目录路径

高级功能

• 添加单元测试步骤
• 集成代码质量检查工具
• 添加性能测试
• 配置通知机制