ljwx-shiti/CI_CD_SETUP_SUMMARY.md

GitHub Actions CI/CD 设置完成总结

✅ 已完成的工作

1. Dockerfile 优化

• ✅ 更新为使用 pyproject.toml
• ✅ 添加健康检查
• ✅ 使用非 root 用户运行
• ✅ 修复系统依赖包名（libgl1）
• 📁 文件: backend/Dockerfile

2. GitHub Actions Workflow

• ✅ 创建完整的 CI/CD pipeline
• ✅ 包含测试、构建、部署三个阶段
• ✅ 自动推送镜像到 Harbor
• ✅ 自动更新 ljwx-deploy 仓库
• 📁 文件: .github/workflows/ci.yml

3. 文档

• ✅ CI/CD 架构文档 (.github/workflows/README.md)
• ✅ Secrets 设置详细指南 (.github/workflows/SECRETS_SETUP_GUIDE.md)
• ✅ 快速开始指南 (.github/workflows/QUICKSTART.md)
• ✅ 设置指南 (.github/workflows/SETUP.md)
• ✅ 文档索引 (.github/workflows/INDEX.md)

4. 自动化脚本

• ✅ Secrets 设置脚本 (scripts/setup-github-secrets.sh)
• ✅ 本地 CI 验证脚本 (scripts/verify-ci.sh)

---

🚀 下一步操作

步骤 1: 设置 GitHub Secrets（必需）

运行交互式设置脚本：

./scripts/setup-github-secrets.sh

或手动设置（需要 3 个 secrets）：

Secret 1: HARBOR_USERNAME

echo "admin" | gh secret set HARBOR_USERNAME --repo BrunoGao/ljwx-shiti

Secret 2: HARBOR_PASSWORD

# 会提示输入密码
gh secret set HARBOR_PASSWORD --repo BrunoGao/ljwx-shiti

Secret 3: DEPLOY_REPO_TOKEN

首先创建 GitHub Personal Access Token:

1. 访问: https://github.com/settings/tokens
2. 点击 "Generate new token (classic)"
3. 名称: ljwx-shiti-deploy-access
4. 权限:
   • ✅ repo (完整仓库访问)
   • ✅ workflow (更新 workflow 文件)
5. 生成并复制 token

然后设置 secret:

# 会提示输入 token
gh secret set DEPLOY_REPO_TOKEN --repo BrunoGao/ljwx-shiti

验证 secrets:

gh secret list --repo BrunoGao/ljwx-shiti

# 应该看到:
# HARBOR_USERNAME     Updated 2026-02-26
# HARBOR_PASSWORD     Updated 2026-02-26
# DEPLOY_REPO_TOKEN   Updated 2026-02-26

---

步骤 2: 提交代码触发 CI/CD

# 添加所有新文件
git add .github/ backend/Dockerfile scripts/ docs/

# 提交
git commit -m "ci: add GitHub Actions CI/CD pipeline

- Add Dockerfile with health check and non-root user
- Add complete CI/CD workflow (test, build, deploy)
- Add documentation and setup scripts
- Add secrets setup guide"

# 推送到 GitHub（触发 CI/CD）
git push origin master

---

步骤 3: 监控 CI/CD 运行

方式 A: 浏览器

访问: https://github.com/BrunoGao/ljwx-shiti/actions

方式 B: GitHub CLI

# 查看运行列表
gh run list --repo BrunoGao/ljwx-shiti

# 实时监控
gh run watch --repo BrunoGao/ljwx-shiti

# 查看日志
gh run view --log --repo BrunoGao/ljwx-shiti

---

📊 CI/CD 流程说明

阶段 1: Test (约 20 分钟)

✅ Checkout code
✅ Setup Python 3.11
✅ Install dependencies
✅ Run linter (ruff)
✅ Run type checker (mypy)
✅ Run migrations (alembic)
✅ Run tests with coverage (pytest)
✅ Upload coverage to Codecov

阶段 2: Build and Push (约 30 分钟)

✅ Checkout code
✅ Setup Docker Buildx
✅ Login to Harbor
✅ Build Docker image
✅ Push to Harbor
   - Image: harbor.omniverseai.net/ljwx/ljwx-shiti:<commit-sha>
   - Tag: latest

阶段 3: Update Deploy (约 10 分钟)

✅ Clone ljwx-deploy repository
✅ Update kustomization.yaml
   - Path: apps/ljwx-shiti/overlays/prod/kustomization.yaml
   - Update image tag to <commit-sha>
✅ Create Pull Request
   - Title: release(ljwx-shiti): <commit-sha>
   - Base: main

阶段 4: ArgoCD 自动部署 (约 30 秒)

✅ ArgoCD 检测 Git 变更
✅ 应用 Kustomize 配置
✅ 滚动更新 Deployment
✅ 健康检查通过
✅ 应用运行在 K8s 集群

---

🔍 验证清单

✅ Secrets 配置

# 检查 secrets
gh secret list --repo BrunoGao/ljwx-shiti

# 应该有 3 个 secrets:
# - HARBOR_USERNAME
# - HARBOR_PASSWORD
# - DEPLOY_REPO_TOKEN

✅ Workflow 文件

# 检查 workflow 文件
cat .github/workflows/ci.yml

# 验证语法
gh workflow view ci.yml --repo BrunoGao/ljwx-shiti

✅ Harbor 访问

# 测试 Harbor 登录
docker login harbor.omniverseai.net
# 输入用户名和密码

# 应该看到: Login Succeeded

✅ Deploy Repo 访问

# 测试 token 权限
curl -H "Authorization: token YOUR_TOKEN" \
  https://api.github.com/repos/BrunoGao/ljwx-deploy

# 应该返回仓库信息

---

🐛 故障排查

问题 1: Secrets 未设置

症状: Workflow 失败，提示 "Secret not found"

解决:

# 重新设置 secrets
./scripts/setup-github-secrets.sh

问题 2: Harbor 登录失败

症状: "Error response from daemon: unauthorized"

解决:

# 1. 验证本地登录
docker login harbor.omniverseai.net

# 2. 检查 secrets
gh secret list --repo BrunoGao/ljwx-shiti

# 3. 重新设置 Harbor secrets
echo "admin" | gh secret set HARBOR_USERNAME --repo BrunoGao/ljwx-shiti
gh secret set HARBOR_PASSWORD --repo BrunoGao/ljwx-shiti

问题 3: Deploy Repo 访问失败

症状: "Repository not found"

解决:

# 1. 测试 token
curl -H "Authorization: token YOUR_TOKEN" \
  https://api.github.com/repos/BrunoGao/ljwx-deploy

# 2. 重新生成 token（确保有 repo 和 workflow 权限）
# 3. 更新 secret
gh secret set DEPLOY_REPO_TOKEN --repo BrunoGao/ljwx-shiti

问题 4: 测试失败

症状: pytest 失败

解决:

# 1. 本地运行测试
cd backend
pytest -v

# 2. 检查测试日志
gh run view --log --repo BrunoGao/ljwx-shiti

# 3. 修复测试后重新推送

---

📚 参考文档

快速参考

• QUICKSTART.md - 快速开始
• INDEX.md - 文档索引

详细指南

• SECRETS_SETUP_GUIDE.md - Secrets 设置
• README.md - CI/CD 架构
• SETUP.md - 完整设置

脚本

• scripts/setup-github-secrets.sh - Secrets 设置脚本
• scripts/verify-ci.sh - 本地验证脚本

---

🎯 成功标志

当你看到以下内容时，说明 CI/CD 设置成功：

1. ✅ GitHub Actions 运行成功（绿色勾）
2. ✅ Harbor 中有新镜像: ljwx-shiti:<commit-sha>
3. ✅ ljwx-deploy 仓库有新 PR
4. ✅ ArgoCD 自动部署应用
5. ✅ 应用在 K8s 集群中运行

---

📞 获取帮助

如果遇到问题:

1. 查看 故障排查 部分
2. 运行验证脚本: ./scripts/setup-github-secrets.sh
3. 查看 GitHub Actions 日志: gh run view --log
4. 查看详细文档: .github/workflows/SECRETS_SETUP_GUIDE.md
5. 联系 DevOps 团队

---

祝你成功！🎉

最后更新: 2026-02-26