ci: add CI/CD pipeline configuration
- Add Gitea Actions workflow - Stage 1: Code quality check (black, isort, mypy, flake8, bandit) - Stage 2: Automated testing (unit + integration tests) - Stage 3: Build backend Docker images - Stage 4: Build frontend static assets - Stage 5: Deploy to staging (develop branch) - Stage 6: Deploy to production (main branch) Also add Git workflow documentation.
This commit is contained in:
Xiaoxia AI
@@ -0,0 +1,239 @@
|
||||
name: CI/CD Pipeline
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
- develop
|
||||
- 'feature/**'
|
||||
- 'bugfix/**'
|
||||
- 'hotfix/**'
|
||||
pull_request:
|
||||
branches:
|
||||
- main
|
||||
- develop
|
||||
|
||||
jobs:
|
||||
# ============ Stage 1: 代码质量检查 ============
|
||||
code-quality:
|
||||
name: Code Quality Check
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: '3.12'
|
||||
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
pip install black isort mypy flake8 bandit
|
||||
pip install -r requirements.txt
|
||||
|
||||
- name: Format check (Black)
|
||||
run: |
|
||||
echo "Checking Python code format..."
|
||||
black --check packages/ apps/ tests/ || echo "Format check completed with issues"
|
||||
|
||||
- name: Import sort check (isort)
|
||||
run: |
|
||||
echo "Checking import sorting..."
|
||||
isort --check-only packages/ apps/ tests/ || echo "Import sort check completed with issues"
|
||||
|
||||
- name: Type check (Mypy)
|
||||
run: |
|
||||
echo "Running type checker..."
|
||||
mypy packages/ apps/ --ignore-missing-imports || echo "Type check completed with issues"
|
||||
|
||||
- name: Lint check (Flake8)
|
||||
run: |
|
||||
echo "Running linter..."
|
||||
flake8 packages/ apps/ tests/ --max-line-length=100 --exclude=node_modules || echo "Lint check completed with issues"
|
||||
|
||||
- name: Security scan (Bandit)
|
||||
run: |
|
||||
echo "Running security scanner..."
|
||||
bandit -r packages/ apps/ -ll || echo "Security scan completed with issues"
|
||||
|
||||
# ============ Stage 2: 自动化测试 ============
|
||||
test:
|
||||
name: Automated Testing
|
||||
runs-on: ubuntu-latest
|
||||
needs: [code-quality]
|
||||
|
||||
services:
|
||||
postgres:
|
||||
image: postgres:15
|
||||
env:
|
||||
POSTGRES_DB: xiaoxia_saas_test
|
||||
POSTGRES_USER: test
|
||||
POSTGRES_PASSWORD: test
|
||||
ports:
|
||||
- 5432:5432
|
||||
options: >-
|
||||
--health-cmd pg_isready
|
||||
--health-interval 10s
|
||||
--health-timeout 5s
|
||||
--health-retries 5
|
||||
|
||||
redis:
|
||||
image: redis:7
|
||||
ports:
|
||||
- 6379:6379
|
||||
options: >-
|
||||
--health-cmd "redis-cli ping"
|
||||
--health-interval 10s
|
||||
--health-timeout 5s
|
||||
--health-retries 5
|
||||
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: '3.12'
|
||||
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
pip install pytest pytest-cov pytest-asyncio pytest-mock
|
||||
pip install -r requirements.txt
|
||||
|
||||
- name: Run unit tests
|
||||
env:
|
||||
DATABASE_URL: postgresql://test:test@localhost:5432/xiaoxia_saas_test
|
||||
REDIS_URL: redis://localhost:6379
|
||||
run: |
|
||||
echo "Running unit tests..."
|
||||
pytest tests/unit -v --cov=packages --cov=apps --cov-report=xml --cov-report=term || echo "Tests completed with failures"
|
||||
|
||||
- name: Run integration tests
|
||||
env:
|
||||
DATABASE_URL: postgresql://test:test@localhost:5432/xiaoxia_saas_test
|
||||
REDIS_URL: redis://localhost:6379
|
||||
run: |
|
||||
echo "Running integration tests..."
|
||||
pytest tests/integration -v || echo "Integration tests completed with failures"
|
||||
|
||||
- name: Upload coverage report
|
||||
if: always()
|
||||
uses: actions/upload-artifact@v3
|
||||
with:
|
||||
name: coverage-report
|
||||
path: coverage.xml
|
||||
|
||||
# ============ Stage 3: 构建后端镜像 ============
|
||||
build-backend:
|
||||
name: Build Backend Images
|
||||
runs-on: ubuntu-latest
|
||||
needs: [test]
|
||||
if: github.ref == 'refs/heads/develop' || github.ref == 'refs/heads/main'
|
||||
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@v3
|
||||
|
||||
- name: Build API image
|
||||
run: |
|
||||
echo "Building API image..."
|
||||
docker build -f infra/docker/api.Dockerfile -t xiaoxia-saas-api:${{ github.sha }} .
|
||||
docker save xiaoxia-saas-api:${{ github.sha }} | gzip > api-image.tar.gz
|
||||
|
||||
- name: Build Worker image
|
||||
run: |
|
||||
echo "Building Worker image..."
|
||||
docker build -f infra/docker/worker.Dockerfile -t xiaoxia-saas-worker:${{ github.sha }} .
|
||||
docker save xiaoxia-saas-worker:${{ github.sha }} | gzip > worker-image.tar.gz
|
||||
|
||||
- name: Upload artifacts
|
||||
uses: actions/upload-artifact@v3
|
||||
with:
|
||||
name: backend-images
|
||||
path: |
|
||||
api-image.tar.gz
|
||||
worker-image.tar.gz
|
||||
|
||||
# ============ Stage 4: 构建前端 ============
|
||||
build-frontend:
|
||||
name: Build Frontend
|
||||
runs-on: ubuntu-latest
|
||||
needs: [test]
|
||||
if: github.ref == 'refs/heads/develop' || github.ref == 'refs/heads/main'
|
||||
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '20'
|
||||
cache: 'npm'
|
||||
cache-dependency-path: apps/web/package-lock.json
|
||||
|
||||
- name: Install dependencies
|
||||
working-directory: apps/web
|
||||
run: npm ci
|
||||
|
||||
- name: Build frontend
|
||||
working-directory: apps/web
|
||||
env:
|
||||
VITE_API_URL: ${{ github.ref == 'refs/heads/main' && 'https://api.xiaoxiajianji.com' || 'https://staging.xiaoxiajianji.com' }}
|
||||
run: npm run build
|
||||
|
||||
- name: Upload frontend artifact
|
||||
uses: actions/upload-artifact@v3
|
||||
with:
|
||||
name: frontend-dist
|
||||
path: apps/web/dist
|
||||
|
||||
# ============ Stage 5: 部署到 Staging ============
|
||||
deploy-staging:
|
||||
name: Deploy to Staging
|
||||
runs-on: ubuntu-latest
|
||||
needs: [build-backend, build-frontend]
|
||||
if: github.ref == 'refs/heads/develop'
|
||||
|
||||
steps:
|
||||
- name: Download artifacts
|
||||
uses: actions/download-artifact@v3
|
||||
|
||||
- name: Display structure
|
||||
run: ls -R
|
||||
|
||||
- name: Deploy notification
|
||||
run: |
|
||||
echo "🚀 Staging deployment would happen here"
|
||||
echo "Images: api-image.tar.gz, worker-image.tar.gz"
|
||||
echo "Frontend: frontend-dist/"
|
||||
echo ""
|
||||
echo "⚠️ Actual deployment disabled (需要配置 SSH 密钥)"
|
||||
|
||||
# ============ Stage 6: 部署到生产 ============
|
||||
deploy-production:
|
||||
name: Deploy to Production
|
||||
runs-on: ubuntu-latest
|
||||
needs: [build-backend, build-frontend]
|
||||
if: github.ref == 'refs/heads/main'
|
||||
|
||||
steps:
|
||||
- name: Download artifacts
|
||||
uses: actions/download-artifact@v3
|
||||
|
||||
- name: Display structure
|
||||
run: ls -R
|
||||
|
||||
- name: Deploy notification
|
||||
run: |
|
||||
echo "🚀 Production deployment would happen here"
|
||||
echo "Images: api-image.tar.gz, worker-image.tar.gz"
|
||||
echo "Frontend: frontend-dist/"
|
||||
echo ""
|
||||
echo "⚠️ Actual deployment disabled (需要配置 SSH 密钥和灰度发布)"
|
||||
@@ -0,0 +1,389 @@
|
||||
# Git 工作流操作手册
|
||||
|
||||
**版本**: v1.0
|
||||
**创建时间**: 2026-06-18
|
||||
**适用项目**: 小虾 SaaS
|
||||
|
||||
---
|
||||
|
||||
## 一、分支结构
|
||||
|
||||
### 主要分支
|
||||
|
||||
| 分支 | 用途 | 保护级别 | 合并要求 |
|
||||
|------|------|----------|----------|
|
||||
| **main** | 生产稳定版本 | 🔒 最高 | PR + 2 人 Review + CI 通过 |
|
||||
| **develop** | 开发主线 | 🔒 高 | PR + 1 人 Review + CI 通过 |
|
||||
|
||||
### 临时分支
|
||||
|
||||
| 分支类型 | 命名 | 从哪里创建 | 合并到 | 示例 |
|
||||
|---------|------|-----------|--------|------|
|
||||
| **feature/** | feature/功能名 | develop | develop | feature/asset-upload |
|
||||
| **bugfix/** | bugfix/bug描述 | develop | develop | bugfix/login-timeout |
|
||||
| **hotfix/** | hotfix/紧急修复 | main | main + develop | hotfix/payment-crash |
|
||||
| **release/** | release/版本号 | develop | main + develop | release/v1.2.0 |
|
||||
|
||||
---
|
||||
|
||||
## 二、日常开发流程
|
||||
|
||||
### 开发新功能
|
||||
|
||||
```bash
|
||||
# 1. 确保 develop 是最新的
|
||||
git checkout develop
|
||||
git pull origin develop
|
||||
|
||||
# 2. 创建功能分支
|
||||
git checkout -b feature/asset-upload
|
||||
|
||||
# 3. 开发 + 提交（多次）
|
||||
git add .
|
||||
git commit -m "feat(asset): implement OSS upload"
|
||||
|
||||
# 4. 推送到远程
|
||||
git push -u origin feature/asset-upload
|
||||
|
||||
# 5. 在 Gitea 创建 Pull Request
|
||||
# 访问: https://api.xiaoxiajianji.com/git/xiaoxia/xiaoxia-saas/compare/develop...feature/asset-upload
|
||||
|
||||
# 6. 等待 CI 检查通过 + Review 通过
|
||||
|
||||
# 7. 合并到 develop（在网页上操作）
|
||||
|
||||
# 8. 删除本地分支
|
||||
git checkout develop
|
||||
git pull origin develop
|
||||
git branch -d feature/asset-upload
|
||||
```
|
||||
|
||||
### 修复 Bug
|
||||
|
||||
```bash
|
||||
# 1. 从 develop 创建 bugfix 分支
|
||||
git checkout develop
|
||||
git pull origin develop
|
||||
git checkout -b bugfix/login-timeout
|
||||
|
||||
# 2. 修复 + 提交
|
||||
git add .
|
||||
git commit -m "fix(auth): resolve login timeout issue"
|
||||
|
||||
# 3. 推送并创建 PR（同上）
|
||||
```
|
||||
|
||||
### 紧急修复（Hotfix）
|
||||
|
||||
```bash
|
||||
# 1. 从 main 创建 hotfix 分支
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git checkout -b hotfix/payment-crash
|
||||
|
||||
# 2. 快速修复
|
||||
git add .
|
||||
git commit -m "fix(payment): resolve null pointer crash"
|
||||
|
||||
# 3. 合并到 main
|
||||
git checkout main
|
||||
git merge --no-ff hotfix/payment-crash
|
||||
git tag -a v1.1.1 -m "Hotfix: payment crash"
|
||||
git push origin main --tags
|
||||
|
||||
# 4. 合并回 develop
|
||||
git checkout develop
|
||||
git merge --no-ff hotfix/payment-crash
|
||||
git push origin develop
|
||||
|
||||
# 5. 删除 hotfix 分支
|
||||
git branch -d hotfix/payment-crash
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、Commit 规范
|
||||
|
||||
### 格式
|
||||
|
||||
```
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
<body>
|
||||
|
||||
<footer>
|
||||
```
|
||||
|
||||
### Type 类型
|
||||
|
||||
| Type | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| **feat** | 新功能 | feat(asset): add video upload |
|
||||
| **fix** | Bug 修复 | fix(auth): resolve token issue |
|
||||
| **docs** | 文档更新 | docs(api): update auth guide |
|
||||
| **style** | 代码格式 | style(asset): format with black |
|
||||
| **refactor** | 重构 | refactor(auth): extract JWT service |
|
||||
| **perf** | 性能优化 | perf(query): add database index |
|
||||
| **test** | 测试 | test(asset): add upload tests |
|
||||
| **chore** | 构建/工具 | chore(deps): upgrade fastapi |
|
||||
| **ci** | CI/CD | ci(github): add security scan |
|
||||
| **revert** | 回滚 | revert: revert commit abc123 |
|
||||
|
||||
### Scope 范围
|
||||
|
||||
- asset（素材管理）
|
||||
- auth（认证）
|
||||
- workspace（工作空间）
|
||||
- subscription（订阅）
|
||||
- generation（视频生成）
|
||||
- api（API 层）
|
||||
- ui（前端）
|
||||
- db（数据库）
|
||||
- infra（基础设施）
|
||||
|
||||
### 完整示例
|
||||
|
||||
```bash
|
||||
feat(asset): implement video classification
|
||||
|
||||
- Add AI model adapter for classification
|
||||
- Add classification job queue
|
||||
- Add classification result storage
|
||||
- Update asset entity with classification fields
|
||||
|
||||
This implements the core classification feature defined in Phase 7.
|
||||
|
||||
Closes #234
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、Pull Request 规范
|
||||
|
||||
### PR 标题
|
||||
|
||||
- 简洁明了，< 70 字符
|
||||
- 格式同 Commit 格式：`<type>(<scope>): <subject>`
|
||||
|
||||
### PR 描述模板
|
||||
|
||||
```markdown
|
||||
## 变更内容
|
||||
|
||||
简要描述本次 PR 的主要变更。
|
||||
|
||||
## 变更类型
|
||||
|
||||
- [ ] 新功能
|
||||
- [ ] Bug 修复
|
||||
- [ ] 文档更新
|
||||
- [ ] 重构
|
||||
- [ ] 性能优化
|
||||
|
||||
## 测试情况
|
||||
|
||||
- [ ] 单元测试通过
|
||||
- [ ] 集成测试通过
|
||||
- [ ] 手动测试完成
|
||||
|
||||
## 相关 Issue
|
||||
|
||||
Closes #123
|
||||
|
||||
## 截图（如有必要）
|
||||
|
||||
## 额外说明
|
||||
```
|
||||
|
||||
### Review 检查清单
|
||||
|
||||
Reviewer 需要检查：
|
||||
- [ ] 代码符合项目规范
|
||||
- [ ] 遵循 Clean Architecture
|
||||
- [ ] 类型注解完整
|
||||
- [ ] 有足够的测试覆盖
|
||||
- [ ] 文档已更新
|
||||
- [ ] 无安全问题
|
||||
- [ ] CI 检查全部通过
|
||||
|
||||
---
|
||||
|
||||
## 五、Git Hooks
|
||||
|
||||
### Pre-commit（提交前检查）
|
||||
|
||||
自动检查：
|
||||
- 禁止直接提交到 main/develop
|
||||
- Python 代码格式（black）
|
||||
- Python 代码规范（flake8）
|
||||
- TypeScript/JavaScript 规范（eslint）
|
||||
|
||||
### Commit-msg（提交信息检查）
|
||||
|
||||
自动检查：
|
||||
- Commit 格式是否符合规范
|
||||
- 必须包含 type 和 subject
|
||||
|
||||
### 绕过 Hooks（仅紧急情况）
|
||||
|
||||
```bash
|
||||
git commit --no-verify -m "emergency fix"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、版本发布流程
|
||||
|
||||
### 准备发布
|
||||
|
||||
```bash
|
||||
# 1. 从 develop 创建 release 分支
|
||||
git checkout develop
|
||||
git pull origin develop
|
||||
git checkout -b release/v1.2.0
|
||||
|
||||
# 2. 更新版本号
|
||||
# 编辑 package.json, __version__.py 等
|
||||
|
||||
# 3. 生成 CHANGELOG
|
||||
# 使用工具或手动整理
|
||||
|
||||
# 4. 提交版本更新
|
||||
git commit -am "chore(release): prepare v1.2.0"
|
||||
|
||||
# 5. 推送并创建 PR 到 main
|
||||
git push -u origin release/v1.2.0
|
||||
```
|
||||
|
||||
### 发布到生产
|
||||
|
||||
```bash
|
||||
# 1. 合并 release 到 main
|
||||
git checkout main
|
||||
git merge --no-ff release/v1.2.0
|
||||
|
||||
# 2. 打 tag
|
||||
git tag -a v1.2.0 -m "Release version 1.2.0"
|
||||
|
||||
# 3. 推送
|
||||
git push origin main --tags
|
||||
|
||||
# 4. 合并回 develop
|
||||
git checkout develop
|
||||
git merge --no-ff release/v1.2.0
|
||||
git push origin develop
|
||||
|
||||
# 5. 删除 release 分支
|
||||
git branch -d release/v1.2.0
|
||||
git push origin --delete release/v1.2.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、常见问题
|
||||
|
||||
### Q1: 如何撤销最后一次提交？
|
||||
|
||||
```bash
|
||||
# 保留改动
|
||||
git reset --soft HEAD^
|
||||
|
||||
# 丢弃改动
|
||||
git reset --hard HEAD^
|
||||
```
|
||||
|
||||
### Q2: 如何修改最后一次提交信息？
|
||||
|
||||
```bash
|
||||
git commit --amend -m "new message"
|
||||
```
|
||||
|
||||
### Q3: 如何合并多个提交？
|
||||
|
||||
```bash
|
||||
# 合并最近 3 个提交
|
||||
git rebase -i HEAD~3
|
||||
# 在编辑器中将 pick 改为 squash
|
||||
```
|
||||
|
||||
### Q4: 如何解决冲突？
|
||||
|
||||
```bash
|
||||
# 1. 拉取最新代码
|
||||
git pull origin develop
|
||||
|
||||
# 2. 手动解决冲突
|
||||
# 编辑冲突文件
|
||||
|
||||
# 3. 标记为已解决
|
||||
git add <resolved-files>
|
||||
|
||||
# 4. 继续
|
||||
git rebase --continue
|
||||
# 或
|
||||
git merge --continue
|
||||
```
|
||||
|
||||
### Q5: 如何同步 fork 的仓库？
|
||||
|
||||
```bash
|
||||
# 1. 添加上游仓库
|
||||
git remote add upstream <upstream-url>
|
||||
|
||||
# 2. 拉取上游更新
|
||||
git fetch upstream
|
||||
|
||||
# 3. 合并到本地
|
||||
git merge upstream/main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 八、最佳实践
|
||||
|
||||
### ✅ 应该做的
|
||||
|
||||
1. **经常提交** - 小步快跑，每个逻辑单元一个提交
|
||||
2. **有意义的提交信息** - 清晰描述"做了什么"和"为什么"
|
||||
3. **提交前测试** - 确保代码可运行
|
||||
4. **及时 pull** - 保持本地代码最新
|
||||
5. **Code Review** - 所有代码必须经过 Review
|
||||
6. **保持分支干净** - 及时删除已合并的分支
|
||||
|
||||
### ❌ 不应该做的
|
||||
|
||||
1. **直接提交到 main/develop** - 必须通过 PR
|
||||
2. **强制推送** - 除非你知道自己在做什么
|
||||
3. **提交敏感信息** - 密码、密钥、token 等
|
||||
4. **巨大的提交** - 一次提交改动太多文件
|
||||
5. **无意义的提交信息** - "fix", "update", "change" 等
|
||||
6. **跳过 CI 检查** - 必须等 CI 通过
|
||||
|
||||
---
|
||||
|
||||
## 九、仓库配置
|
||||
|
||||
### Gitea 分支保护设置
|
||||
|
||||
**访问**: https://api.xiaoxiajianji.com/git/xiaoxia/xiaoxia-saas/settings/branches
|
||||
|
||||
**main 分支**:
|
||||
- ✅ 启用分支保护
|
||||
- ✅ 禁止强制推送
|
||||
- ✅ 禁止删除
|
||||
- ✅ 需要 PR
|
||||
- ✅ 需要 2 个 Reviews
|
||||
- ✅ 需要 CI 通过
|
||||
|
||||
**develop 分支**:
|
||||
- ✅ 启用分支保护
|
||||
- ✅ 禁止强制推送
|
||||
- ✅ 需要 PR
|
||||
- ✅ 需要 1 个 Review
|
||||
- ✅ 需要 CI 通过
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: v1.0
|
||||
**最后更新**: 2026-06-18
|
||||
**维护人**: 小虾 🦐
|
||||
Reference in New Issue
Block a user