Skip to Content
技术文档开发指南CI/CD

概述

本项目使用 GitHub Actions 实现完整的 CI/CD 流程，包括：

  • 代码质量检查（Lint、TypeCheck）
  • 自动化测试
  • Docker 镜像构建和推送
  • PR 自动化管理
  • 版本发布自动化

Workflows

1. CI Pipeline

文件: .github/workflows/ci.yml

触发条件:

  • 推送到 main 或 develop 分支
  • 向 main 或 develop 提交 PR

Jobs:

Lint (代码质量)

  • 运行 Biome 检查
  • 验证代码格式和规范
  • 检查 import 限制

TypeCheck (类型检查)

  • 生成 Prisma Client
  • 运行 TypeScript 类型检查

Test (测试)

  • 启动 PostgreSQL 服务
  • 运行数据库迁移
  • 执行所有测试

Build (Docker 镜像)

  • 构建 api、web、docs 三个镜像
  • 推送到配置的 Registry
  • 支持多平台: linux/amd64, linux/arm64
  • 使用 GitHub Actions 缓存加速

2. PR Workflow

文件: .github/workflows/pr.yml

功能:

  • 自动打标签（bug、feature、documentation 等）
  • PR 大小检查
  • 评论 PR 信息

3. Release Workflow

文件: .github/workflows/release.yml

触发: 推送到 main 分支

功能:

本项目使用 Release Please  实现自动化版本发布：

工作流程

1. 提交代码 - 使用 Conventional Commits 格式：

git commit -m "feat: add new feature"
git commit -m "fix: resolve bug"
git commit -m "feat!: breaking change"

2. 自动创建 Release PR - Release Please 分析提交：

  • 自动更新版本号（根据语义化版本）
  • 生成 CHANGELOG.md
  • 更新 package.json 版本
  • 创建 PR 等待合并

3. 合并 PR - 自动触发：

  • 创建 GitHub Release
  • 打上版本标签（如 v1.0.0）
  • 构建并推送 Docker 镜像（带版本标签）

Commit Types

Type版本更新说明
feat:Minor新功能 (1.0.0 → 1.1.0)
fix:PatchBug 修复 (1.0.0 → 1.0.1)
feat!: 或 BREAKING CHANGE:Major破坏性变更 (1.0.0 → 2.0.0)
docs:-文档更新（包含在 CHANGELOG）
refactor:-代码重构（包含在 CHANGELOG）
perf:-性能优化（包含在 CHANGELOG）
test:-测试相关（包含在 CHANGELOG）
build:-构建系统（包含在 CHANGELOG）
ci:-CI 配置（包含在 CHANGELOG）
chore:-其他杂项（隐藏）

配置文件

.github/release-please-config.json:

{
  "release-type": "node",
  "packages": {
    ".": {
      "package-name": "procure",
      "changelog-sections": [...]
    }
  }
}

.github/release-please-manifest.json:

{
  ".": "0.1.0"  // 当前版本
}

Docker 镜像标签

Release 时自动构建带版本的镜像：

ghcr.io/{owner}/{repo}/api:latest     # 最新版本
ghcr.io/{owner}/{repo}/api:v1.0.0     # 具体版本
ghcr.io/{owner}/{repo}/web:latest
ghcr.io/{owner}/{repo}/web:v1.0.0
ghcr.io/{owner}/{repo}/docs:latest
ghcr.io/{owner}/{repo}/docs:v1.0.0

示例工作流

# 1. 开发新功能
git checkout -b feature/new-feature
git commit -m "feat: add user authentication"
git push origin feature/new-feature
 
# 2. 创建并合并 PR 到 main
 
# 3. Release Please 自动创建 Release PR
#    - 标题: "chore(main): release 1.1.0"
#    - 更新 package.json: "version": "1.1.0"
#    - 更新 CHANGELOG.md
 
# 4. Review 并合并 Release PR
 
# 5. 自动完成：
#    ✓ 创建 GitHub Release
#    ✓ 打标签 v1.1.0
#    ✓ 构建 Docker 镜像
#    ✓ 推送到 Registry

手动触发 Release

如果需要手动控制版本：

# 在 Release PR 的描述中添加：
Release-As: 2.0.0

跳过 Release

某些提交不希望触发 release：

# 在 commit message 中添加：
git commit -m "chore: update docs
 
Release-As: SKIP"

4. Cleanup Workflow

文件: .github/workflows/cleanup.yml

功能:

  • 自动清理旧的 workflow runs
  • 保留最近 30 天的数据

Docker Registry 配置

默认配置 (GitHub Container Registry)

无需配置，自动使用：

  • Registry: ghcr.io
  • Username: ${{ github.actor }}
  • Password: ${{ secrets.GITHUB_TOKEN }}

镜像地址：

ghcr.io/{owner}/{repo}/api:latest
ghcr.io/{owner}/{repo}/web:latest
ghcr.io/{owner}/{repo}/docs:latest

自定义 Registry

设置以下 secrets 即可切换到其他 Registry：

# 使用脚本配置
cp .env.secrets.example .env.secrets
 
# 编辑 .env.secrets
DOCKER_REGISTRY=docker.io
DOCKER_USERNAME=your-username
DOCKER_PASSWORD=your-token
 
# 推送到 GitHub
./scripts/setup-secrets.sh

支持的 Registry：

  • Docker Hub: docker.io
  • AWS ECR: {account}.dkr.ecr.{region}.amazonaws.com
  • Google GCR: gcr.io
  • Azure ACR: {registry}.azurecr.io
  • Harbor: harbor.example.com
  • 阿里云 ACR: registry.{region}.aliyuncs.com

详见：GitHub Secrets 配置

镜像标签策略

CI 自动生成多种标签：

条件标签示例
Push to mainmain, latestghcr.io/org/repo/api:main
Push to developdevelopghcr.io/org/repo/api:develop
Pull Requestpr-{number}ghcr.io/org/repo/api:pr-123
Tag (semver)v{version}, v{major}.{minor}ghcr.io/org/repo/api:v1.0.0
Any branch{branch}-{sha}ghcr.io/org/repo/api:feature-abc1234

构建优化

缓存策略

使用 GitHub Actions 缓存加速构建：

- name: Build and push
  uses: docker/build-push-action@v6
  with:
    cache-from: type=gha
    cache-to: type=gha,mode=max

第一次构建：~10-15 分钟 后续构建（有缓存）：~3-5 分钟

并行构建

三个镜像并行构建：

strategy:
  matrix:
    app: [api, web, docs]

多平台支持

同时构建 amd64 和 arm64：

platforms: linux/amd64,linux/arm64

本地测试 Workflows

使用 act  在本地运行 workflows：

# 安装 act
brew install act  # macOS
 
# 运行 CI workflow
act -j lint
act -j typecheck
act -j test
 
# 运行整个 workflow
act push

注意: act 不支持某些 GitHub Actions 特性，本地测试仅供参考

环境变量

必需的 Secrets

Secret用途默认值
GITHUB_TOKENGitHub API 访问自动提供

可选的 Secrets

Secret用途默认值
DOCKER_REGISTRYDocker Registry 地址ghcr.io
DOCKER_USERNAMERegistry 用户名github.actor
DOCKER_PASSWORDRegistry 密码GITHUB_TOKEN

监控和调试

查看 Workflow 状态

  1. 进入仓库的 Actions 标签页
  2. 选择对应的 workflow run
  3. 查看各个 job 的日志

常见错误

依赖安装失败

# 确保 pnpm-lock.yaml 是最新的
pnpm install
git add pnpm-lock.yaml
git commit -m "chore: update lockfile"

类型检查失败

# 确保 Prisma Client 已生成
pnpm run db:generate
 
# 本地验证
pnpm run check-types

Docker 构建失败

# 检查 Dockerfile 语法
docker build -f apps/api/Dockerfile .
 
# 查看构建上下文大小
du -sh .
 
# 确保 .dockerignore 正确配置

认证失败

检查 secrets 配置：

gh secret list

最佳实践

1. 分支策略

main    - 生产环境，保护分支
develop - 开发环境
feature/* - 功能分支
bugfix/* - 修复分支

2. PR 规范

  • PR 描述清晰
  • 通过所有检查
  • 至少一个 reviewer 批准
  • Squash merge 保持提交历史清晰

3. Commit 规范

使用 Conventional Commits：

# 格式
<type>[optional scope]: <description>
 
[optional body]
 
[optional footer]

示例:

# 新功能
git commit -m "feat: add user profile page"
git commit -m "feat(api): add authentication endpoint"
 
# Bug 修复
git commit -m "fix: resolve login error"
git commit -m "fix(web): correct button alignment"
 
# 破坏性变更
git commit -m "feat!: change API response format"
git commit -m "feat(api)!: rename user field
 
BREAKING CHANGE: User.name changed to User.fullName"
 
# 文档
git commit -m "docs: update README"
 
# 其他
git commit -m "chore: update dependencies"
git commit -m "refactor: simplify authentication logic"

工具集成:

项目已配置 Husky，commit 时自动验证格式。

4. 缓存失效

如果缓存导致问题：

# 手动触发 workflow 时选择 "Clear cache"
# 或在 workflow 文件中添加：
cache-to: type=gha,mode=max,ignore-error=true

相关文档

Docker 开发部署指南