starmen1265
4e3ed1b849
- ci.yml: 代码检查 + 单元测试 - deploy.yml: 自动部署到 staging/production - test.yml: 功能分支快速测试 - docs/CI-CD-PLAN.md: 完整方案文档
470 lines
13 KiB
Markdown
470 lines
13 KiB
Markdown
# kb-web CI/CD 方案设计
|
||
|
||
## 架构概览
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||
│ CI/CD Pipeline │
|
||
├─────────────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 本地开发 Gitea仓库 CI测试 CD部署 │
|
||
│ ┌────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ 代码 │─────▶│ feature │────────▶│ 语法检查 │───┐ │ │ │
|
||
│ │ 编写 │ │ 分支 │ │ 单元测试 │ │ │ Staging │ │
|
||
│ └────────┘ └──────────┘ └──────────┘ │ │ 测试环境 │ │
|
||
│ │ │ │ │ │
|
||
│ │ PR + Review │ └────┬─────┘ │
|
||
│ ▼ │ │ │
|
||
│ ┌──────────┐ │ ┌────▼─────┐ │
|
||
│ │ develop │────────────────────────┼───▶│ 手动 │ │
|
||
│ │ 分支 │ │ │ 确认 │ │
|
||
│ └──────────┘ │ └────┬─────┘ │
|
||
│ │ │ │ │
|
||
│ │ PR + Review + 测试通过 │ ┌────▼─────┐ │
|
||
│ ▼ │ │Production│ │
|
||
│ ┌──────────┐ │ │ 正式环境 │ │
|
||
│ │ main │────────────────────────┴───▶│ │ │
|
||
│ │ 分支 │ └──────────┘ │
|
||
│ └──────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 一、分支策略
|
||
|
||
```
|
||
main (生产环境)
|
||
│
|
||
│ ← PR (需要 Review + CI 通过)
|
||
│
|
||
├── develop (测试环境主分支)
|
||
│ │
|
||
│ │ ← PR (需要 CI 通过)
|
||
│ │
|
||
│ ├── feature/xxx (功能开发)
|
||
│ ├── feature/yyy
|
||
│ ├── bugfix/zzz (Bug 修复)
|
||
│ └── refactor/aaa (重构)
|
||
│
|
||
└── hotfix/xxx (紧急修复，直接合并到 main 和 develop)
|
||
```
|
||
|
||
### 分支命名规范
|
||
|
||
| 类型 | 命名 | 示例 |
|
||
|------|------|------|
|
||
| 功能 | `feature/描述` | `feature/user-login` |
|
||
| 修复 | `bugfix/描述` | `bugfix/fix-redirect` |
|
||
| 重构 | `refactor/描述` | `refactor/database-layer` |
|
||
| 紧急 | `hotfix/描述` | `hotfix/security-patch` |
|
||
|
||
---
|
||
|
||
## 二、CI/CD 流水线
|
||
|
||
### 阶段 1: 代码检查 (Lint)
|
||
|
||
```bash
|
||
- PHP 语法检查
|
||
- 代码风格检查 (PHP-CS-Fixer)
|
||
- 安全漏洞扫描
|
||
```
|
||
|
||
### 阶段 2: 自动化测试
|
||
|
||
```bash
|
||
- 单元测试 (PHPUnit)
|
||
- 功能测试
|
||
- 测试覆盖率报告
|
||
```
|
||
|
||
### 阶段 3: 构建与打包
|
||
|
||
```bash
|
||
- 安装依赖 (composer install --no-dev)
|
||
- 生成版本信息文件
|
||
- 创建部署包
|
||
```
|
||
|
||
### 阶段 4: 部署
|
||
|
||
```bash
|
||
- Staging: 自动部署 (develop 分支)
|
||
- Production: 手动确认后部署 (main 分支)
|
||
```
|
||
|
||
---
|
||
|
||
## 三、Gitea Actions 配置
|
||
|
||
### 文件结构
|
||
|
||
```
|
||
kb-web/
|
||
├── .gitea/
|
||
│ └── workflows/
|
||
│ ├── ci.yml # 主 CI 流程
|
||
│ └── deploy.yml # 部署流程
|
||
├── tests/
|
||
├── deploy/
|
||
│ ├── deploy.sh
|
||
│ └── rollback.sh
|
||
└── ...
|
||
```
|
||
|
||
### 1. CI 配置 (.gitea/workflows/ci.yml)
|
||
|
||
```yaml
|
||
name: CI
|
||
|
||
on:
|
||
push:
|
||
branches: [main, develop, 'feature/**', 'bugfix/**']
|
||
pull_request:
|
||
branches: [main, develop]
|
||
|
||
env:
|
||
PHP_VERSION: '8.2'
|
||
|
||
jobs:
|
||
# 代码检查
|
||
lint:
|
||
name: 代码检查
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- name: 检出代码
|
||
uses: actions/checkout@v4
|
||
|
||
- name: 设置 PHP
|
||
uses: shivammathur/setup-php@v2
|
||
with:
|
||
php-version: ${{ env.PHP_VERSION }}
|
||
|
||
- name: PHP 语法检查
|
||
run: find . -name "*.php" -not -path "./vendor/*" -exec php -l {} \; | grep -v "No syntax errors"
|
||
|
||
- name: 安装依赖
|
||
run: composer install --prefer-dist --no-progress
|
||
|
||
# 单元测试
|
||
test:
|
||
name: 单元测试
|
||
runs-on: ubuntu-latest
|
||
needs: lint
|
||
steps:
|
||
- name: 检出代码
|
||
uses: actions/checkout@v4
|
||
|
||
- name: 设置 PHP
|
||
uses: shivammathur/setup-php@v2
|
||
with:
|
||
php-version: ${{ env.PHP_VERSION }}
|
||
coverage: xdebug
|
||
|
||
- name: 安装依赖
|
||
run: composer install --prefer-dist --no-progress
|
||
|
||
- name: 运行测试
|
||
run: composer test
|
||
|
||
- name: 上传覆盖率报告
|
||
uses: actions/upload-artifact@v4
|
||
with:
|
||
name: coverage-report
|
||
path: coverage/
|
||
retention-days: 7
|
||
|
||
# 构建确认
|
||
build-success:
|
||
name: 构建成功
|
||
runs-on: ubuntu-latest
|
||
needs: [lint, test]
|
||
if: success()
|
||
steps:
|
||
- name: 构建成功
|
||
run: echo "✅ CI 通过，可以合并"
|
||
```
|
||
|
||
### 2. 部署配置 (.gitea/workflows/deploy.yml)
|
||
|
||
```yaml
|
||
name: Deploy
|
||
|
||
on:
|
||
push:
|
||
branches: [main, develop]
|
||
workflow_dispatch:
|
||
inputs:
|
||
environment:
|
||
description: '部署环境'
|
||
required: true
|
||
default: 'staging'
|
||
type: choice
|
||
options:
|
||
- staging
|
||
- production
|
||
branch:
|
||
description: '部署分支'
|
||
required: true
|
||
default: 'develop'
|
||
type: string
|
||
|
||
env:
|
||
DEPLOY_SERVER: root@micecola.top
|
||
DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
|
||
|
||
jobs:
|
||
# 部署到测试环境
|
||
deploy-staging:
|
||
name: 部署测试环境
|
||
runs-on: ubuntu-latest
|
||
if: github.ref == 'refs/heads/develop' || (github.event_name == 'workflow_dispatch' && github.event.inputs.environment == 'staging')
|
||
environment:
|
||
name: staging
|
||
url: http://micecola.top:8080
|
||
steps:
|
||
- name: 检出代码
|
||
uses: actions/checkout@v4
|
||
|
||
- name: 设置 SSH
|
||
uses: webfactory/ssh-agent@v0.9.0
|
||
with:
|
||
ssh-private-key: ${{ secrets.DEPLOY_KEY }}
|
||
|
||
- name: 部署到测试环境
|
||
run: |
|
||
ssh -o StrictHostKeyChecking=no $DEPLOY_SERVER << 'EOF'
|
||
cd /var/www/kb-web-test
|
||
git fetch origin
|
||
git reset --hard origin/develop
|
||
composer install --no-dev --prefer-dist
|
||
echo "Deployed at $(date)" > .deploy_time
|
||
EOF
|
||
|
||
- name: 部署完成通知
|
||
run: echo "✅ 测试环境部署完成: http://micecola.top:8080"
|
||
|
||
# 部署到正式环境
|
||
deploy-production:
|
||
name: 部署正式环境
|
||
runs-on: ubuntu-latest
|
||
if: github.ref == 'refs/heads/main' || (github.event_name == 'workflow_dispatch' && github.event.inputs.environment == 'production')
|
||
environment:
|
||
name: production
|
||
url: https://kb.micecola.top
|
||
steps:
|
||
- name: 检出代码
|
||
uses: actions/checkout@v4
|
||
|
||
- name: 设置 SSH
|
||
uses: webfactory/ssh-agent@v0.9.0
|
||
with:
|
||
ssh-private-key: ${{ secrets.DEPLOY_KEY }}
|
||
|
||
- name: 备份当前版本
|
||
run: |
|
||
ssh -o StrictHostKeyChecking=no $DEPLOY_SERVER << 'EOF'
|
||
BACKUP_DIR="/var/www/kb-web-prod-backups"
|
||
mkdir -p $BACKUP_DIR
|
||
cd /var/www/kb-web-prod
|
||
CURRENT_COMMIT=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
|
||
tar -czf "$BACKUP_DIR/backup_${CURRENT_COMMIT}_$(date +%Y%m%d_%H%M%S).tar.gz" .
|
||
# 保留最近 10 个备份
|
||
cd $BACKUP_DIR && ls -t | tail -n +11 | xargs -r rm -f
|
||
EOF
|
||
|
||
- name: 部署到正式环境
|
||
run: |
|
||
ssh -o StrictHostKeyChecking=no $DEPLOY_SERVER << 'EOF'
|
||
cd /var/www/kb-web-prod
|
||
git fetch origin
|
||
git reset --hard origin/main
|
||
composer install --no-dev --prefer-dist
|
||
|
||
# 记录部署信息
|
||
cat > .deploy_info << DEPLOY_EOF
|
||
环境: production
|
||
分支: main
|
||
提交: $(git rev-parse HEAD)
|
||
时间: $(date '+%Y-%m-%d %H:%M:%S')
|
||
部署者: Gitea Actions
|
||
DEPLOY_EOF
|
||
EOF
|
||
|
||
- name: 部署完成通知
|
||
run: echo "✅ 正式环境部署完成: https://kb.micecola.top"
|
||
|
||
# 回滚
|
||
rollback:
|
||
name: 回滚
|
||
runs-on: ubuntu-latest
|
||
if: github.event_name == 'workflow_dispatch' && github.event.inputs.environment != ''
|
||
environment:
|
||
name: ${{ github.event.inputs.environment }}
|
||
steps:
|
||
- name: 设置 SSH
|
||
uses: webfactory/ssh-agent@v0.9.0
|
||
with:
|
||
ssh-private-key: ${{ secrets.DEPLOY_KEY }}
|
||
|
||
- name: 列出可用备份
|
||
run: |
|
||
ssh -o StrictHostKeyChecking=no $DEPLOY_SERVER << 'EOF'
|
||
echo "可用的备份:"
|
||
ls -la /var/www/kb-web-${{ github.event.inputs.environment }}-backups/
|
||
EOF
|
||
```
|
||
|
||
---
|
||
|
||
## 四、Runner 配置
|
||
|
||
### 方案 A: 使用 Gitea 官方 Runner（推荐）
|
||
|
||
```bash
|
||
# 在服务器上安装 Runner
|
||
curl -L -o gitea-runner https://gitea.com/gitea/actions/runner/releases/download/v3.4.1/act_runner-3.4.1-linux-amd64
|
||
chmod +x gitea-runner
|
||
sudo mv gitea-runner /usr/local/bin/
|
||
|
||
# 注册 Runner
|
||
gitea-runner register --instance https://your-gitea-server --token <your-token>
|
||
|
||
# 启动 Runner
|
||
gitea-runner daemon
|
||
```
|
||
|
||
### 方案 B: 使用 GitHub Actions 兼容 Runner
|
||
|
||
如果你有 GitHub 账号，可以使用 GitHub 托管的 Runner，只需在 Gitea 中配置镜像。
|
||
|
||
---
|
||
|
||
## 五、Gitea 仓库配置
|
||
|
||
### 1. 启用 Actions
|
||
|
||
仓库设置 → Actions → 启用
|
||
|
||
### 2. 配置 Secrets
|
||
|
||
| Secret 名称 | 用途 |
|
||
|-------------|------|
|
||
| `DEPLOY_KEY` | SSH 私钥（用于部署到服务器） |
|
||
| `DEPLOY_SERVER` | 部署服务器地址 |
|
||
|
||
### 3. 配置分支保护
|
||
|
||
| 分支 | 规则 |
|
||
|------|------|
|
||
| `main` | 需要 PR + 1 个 Review + CI 通过 |
|
||
| `develop` | 需要 PR + CI 通过 |
|
||
|
||
---
|
||
|
||
## 六、开发工作流
|
||
|
||
### 日常开发
|
||
|
||
```bash
|
||
# 1. 创建功能分支
|
||
git checkout develop
|
||
git pull
|
||
git checkout -b feature/new-feature
|
||
|
||
# 2. 开发 + 本地测试
|
||
composer test
|
||
|
||
# 3. 提交代码
|
||
git add .
|
||
git commit -m "feat: 新功能描述"
|
||
git push -u origin feature/new-feature
|
||
|
||
# 4. 创建 PR 到 develop
|
||
# Gitea 上操作，CI 自动运行
|
||
|
||
# 5. Review 通过后合并
|
||
# 自动部署到 Staging
|
||
|
||
# 6. 测试通过后，PR 到 main
|
||
# 手动确认后部署到 Production
|
||
```
|
||
|
||
### 紧急修复
|
||
|
||
```bash
|
||
# 1. 从 main 创建 hotfix 分支
|
||
git checkout main
|
||
git checkout -b hotfix/urgent-fix
|
||
|
||
# 2. 修复 + 测试
|
||
git commit -m "hotfix: 紧急修复描述"
|
||
git push
|
||
|
||
# 3. PR 到 main（跳过 develop）
|
||
# 快速 Review + 合并 + 部署
|
||
|
||
# 4. 同步到 develop
|
||
git checkout develop
|
||
git merge hotfix/urgent-fix
|
||
```
|
||
|
||
---
|
||
|
||
## 七、监控与告警
|
||
|
||
### 部署状态通知
|
||
|
||
可集成：
|
||
- 飞书机器人
|
||
- 企业微信
|
||
- 邮件
|
||
|
||
### 健康检查
|
||
|
||
```bash
|
||
# 部署后自动检查
|
||
curl -f https://kb.micecola.top/health || exit 1
|
||
```
|
||
|
||
---
|
||
|
||
## 八、实施步骤
|
||
|
||
### 第一阶段：基础设施（1-2天）
|
||
|
||
1. [ ] 确认 Gitea 版本支持 Actions（需要 1.19+）
|
||
2. [ ] 在服务器上安装 Gitea Runner
|
||
3. [ ] 配置 SSH 密钥和 Secrets
|
||
|
||
### 第二阶段：CI 流程（1天）
|
||
|
||
1. [ ] 创建 `.gitea/workflows/ci.yml`
|
||
2. [ ] 配置代码检查和测试
|
||
3. [ ] 设置分支保护规则
|
||
|
||
### 第三阶段：CD 流程（1天）
|
||
|
||
1. [ ] 创建 `.gitea/workflows/deploy.yml`
|
||
2. [ ] 配置自动部署到 Staging
|
||
3. [ ] 配置手动部署到 Production
|
||
|
||
### 第四阶段：优化（持续）
|
||
|
||
1. [ ] 添加测试覆盖率报告
|
||
2. [ ] 添加部署通知
|
||
3. [ ] 添加回滚脚本
|
||
|
||
---
|
||
|
||
## 九、当前项目待办
|
||
|
||
- [ ] 确认 Gitea 服务器版本
|
||
- [ ] 部署 feature/article-word-count 分支到测试环境验证
|
||
- [ ] 合并到 develop，测试 CI/CD 流程
|
||
|
||
---
|
||
|
||
*文档版本: 1.0*
|
||
*创建时间: 2026-03-01*
|