ljwx-health/docs/03-deployment/gitops/ci-cd-workflow.md

LJWX Health CI/CD 工作流

适用范围：本地 Gitea 仓库 + Argo CD 部署

---

📋 架构概述

LJWX Health 使用 Gitea Actions + Argo CD 实现 GitOps 工作流：

┌─────────────────┐
│  开发者         │
│  git push       │
│  local main     │
└────────┬────────┘
         │
         ▼
┌─────────────────────────────┐
│  Gitea Actions              │
│  (.gitea/workflows/ci.yml)  │
│                             │
│  1. 测试 (test-*)           │
│  2. 构建镜像 (build-push)    │
│  3. 推送到Harbor            │
│  4. 更新ljwx-deploy仓库      │
└────────┬────────────────────┘
         │
         ▼
┌─────────────────────────────┐
│  ljwx-deploy 仓库           │
│  (GitOps配置仓库)           │
│                             │
│  apps/ljwx-health/overlays/ │
│  ├── ljwx-boot/             │
│  ├── ljwx-admin/            │
│  └── ljwx-bigscreen/        │
│      └── kustomization.yaml │
└────────┬────────────────────┘
         │
         ▼
┌─────────────────────────────┐
│  Argo CD                    │
│  (监控ljwx-deploy仓库)       │
│                             │
│  检测到kustomization.yaml    │
│  变更后自动同步到K3s         │
└────────┬────────────────────┘
         │
         ▼
┌─────────────────────────────┐
│  K3s Cluster                │
│  (ljwx-health namespace)    │
│                             │
│  Deployments更新             │
│  └── 滚动部署新镜像          │
└─────────────────────────────┘

关键分离：

• CI（Gitea Actions）：代码测试、镜像构建、GitOps仓库更新
• CD（Argo CD）：监控GitOps仓库、自动部署到K3s

---

🚀 开发者工作流

日常开发

# 1. 在 feature 分支开发
git checkout -b feature/new-feature

# 2. 本地测试
cd ljwx-boot && ./run-local.sh
cd ljwx-admin && pnpm dev
cd ljwx-bigscreen && python run.py

# 3. 提交代码
git add .
git commit -m "feat: add new feature"

# 4. 推送到 Gitea（触发 CI/CD）
git push local main

自动触发：

• ✅ Gitea Actions 自动运行 CI Pipeline
• ✅ 测试通过后构建镜像推送到 Harbor
• ✅ 更新 ljwx-deploy 仓库的镜像标签
• ✅ Argo CD 检测到变更，自动部署到 K3s

---

📝 CI Pipeline 详解

Workflow 文件

位置：.gitea/workflows/ci.yml

触发条件

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

说明：

• push 到 main 分支：完整 CI/CD（测试 + 构建 + 部署）
• pull_request：仅测试和构建验证（不推送镜像）

Job 1: 测试 ljwx-boot

Runner: ubuntu-latest (容器) 基础镜像: harbor.omniverseai.net/ljwx-base-images/maven3.9-jdk21:latest

steps:
  - 构建 ljwx-boot-starter（依赖）
  - 运行 Checkstyle（代码质量检查）
  - 运行单元测试 + JaCoCo 覆盖率
  - 构建 JAR 包

Job 2: 测试 ljwx-admin

Runner: ubuntu-latest (容器) 基础镜像: harbor.omniverseai.net/ljwx-base-images/node20-pnpm:latest

steps:
  - pnpm install（依赖安装）
  - ESLint（代码检查）
  - TypeScript类型检查
  - 单元测试 + 覆盖率报告

Job 3: 测试 ljwx-bigscreen

Runner: ubuntu-latest (容器) 基础镜像: harbor.omniverseai.net/ljwx-base-images/python3.12-pip:latest

steps:
  - uv pip install（依赖安装）
  - Ruff Linter（代码检查）
  - Black格式化检查
  - Pytest + 覆盖率报告
  - Safety安全检查

Job 4: 安全扫描

Runner: docker-builder (self-hosted)

steps:
  - Trivy扫描 ljwx-boot
  - Trivy扫描 ljwx-admin
  - Trivy扫描 ljwx-bigscreen
  - 生成安全报告（JSON格式）

Job 5: 构建并推送镜像

Runner: docker-builder (self-hosted) 依赖: 所有测试 Job 必须通过 触发条件: 仅 push 到 main 分支

strategy:
  matrix:
    component:
      - ljwx-boot
      - ljwx-admin
      - ljwx-bigscreen

镜像标签：

main-<short_sha>  # 例如: main-a1b2c3d
latest            # 始终指向最新 main 分支构建

Dockerfile 路径：

• ljwx-boot: ljwx-boot/ljwx-boot-admin/Dockerfile.gitea
• ljwx-admin: ljwx-admin/Dockerfile.gitea
• ljwx-bigscreen: ljwx-bigscreen/Dockerfile.gitea

推送目标：

harbor.omniverseai.net/ljwx-health/ljwx-boot:main-a1b2c3d
harbor.omniverseai.net/ljwx-health/ljwx-admin:main-a1b2c3d
harbor.omniverseai.net/ljwx-health/ljwx-bigscreen:main-a1b2c3d

Job 6: 更新 GitOps 仓库

Runner: ubuntu-latest 依赖: 构建推送 Job 完成

steps:
  - 克隆 ljwx-deploy 仓库
  - 更新所有组件的 kustomization.yaml:
    * apps/ljwx-health/overlays/ljwx-boot/kustomization.yaml
    * apps/ljwx-health/overlays/ljwx-admin/kustomization.yaml
    * apps/ljwx-health/overlays/ljwx-bigscreen/kustomization.yaml
  - 提交并推送到 ljwx-deploy 仓库

kustomization.yaml 示例：

# apps/ljwx-health/overlays/ljwx-boot/kustomization.yaml
images:
  - name: harbor.omniverseai.net/ljwx-health/ljwx-boot
    newTag: "main-a1b2c3d"  # CI 自动更新这一行

---

🔄 Argo CD 部署流程

Argo CD 职责

1. 监控 ljwx-deploy 仓库：

   • 检测到 kustomization.yaml 变更
   • 自动触发同步

2. 自动部署到 K3s：

   • 拉取新镜像标签
   • 滚动更新 Deployment
   • 健康检查

3. 状态同步：

   • 确保集群状态与 Git 仓库一致
   • 自动修复配置漂移

Argo CD 配置

Application 配置位置：

ljwx-deploy/apps/ljwx-health/application.yaml

自动同步策略：

syncPolicy:
  automated:
    prune: true      # 自动删除不再需要的资源
    selfHeal: true   # 自动修复配置漂移
    allowEmpty: false
  syncOptions:
    - CreateNamespace=true

查看 Argo CD 状态

方法 1: Argo CD UI

# 访问 Argo CD Web 界面
# URL: https://argocd.your-domain.com
# 查看 ljwx-health Application 状态

方法 2: CLI

# 查看应用状态
argocd app get ljwx-health

# 查看同步历史
argocd app history ljwx-health

# 手动触发同步（通常不需要）
argocd app sync ljwx-health

方法 3: kubectl

# 检查 Deployment 状态
kubectl get deployments -n ljwx-health

# 查看 Pod 状态
kubectl get pods -n ljwx-health

# 查看部署历史
kubectl rollout history deployment/ljwx-boot -n ljwx-health

---

🔐 必需的 Secrets

在 Gitea 仓库中配置以下 Secrets：

配置路径：

Gitea仓库 → Settings → Secrets → Add secret

Secret Name	描述	用途
HARBOR_USERNAME	Harbor用户名	推送镜像到Harbor
HARBOR_PASSWORD	Harbor密码	推送镜像到Harbor
DEPLOY_REPO_TOKEN	ljwx-deploy仓库访问token	更新GitOps仓库

生成 DEPLOY_REPO_TOKEN：

# Gitea UI:
# Settings → Applications → Generate New Token
# Scopes: repo (read/write)

---

📊 版本命名规则

镜像标签格式

main-<short_sha>  # 基于 git commit SHA

示例：

# Git commit: a1b2c3d4e5f6g7h8i9j0
# 镜像标签: main-a1b2c3d
harbor.omniverseai.net/ljwx-health/ljwx-boot:main-a1b2c3d

优势：

• ✅ 唯一标识每次构建
• ✅ 可追溯到具体 commit
• ✅ 支持回滚到任意版本

---

🐛 常见问题排查

问题 1: CI 构建失败 - 基础镜像拉取失败

症状：

Error response from daemon: pull access denied for harbor.omniverseai.net/ljwx-base-images/java-maven-otel

原因：基础镜像不存在或 Harbor 认证失败

解决方案：

# 1. 验证基础镜像是否存在
docker pull harbor.omniverseai.net/ljwx-base-images/java-maven-otel:21-alpine

# 2. 检查 Harbor Secrets
# Gitea UI → Settings → Secrets

# 3. 重新推送基础镜像
cd docker/base-images
./build-java-maven-otel.sh

问题 2: Argo CD 未自动部署

症状：ljwx-deploy 仓库已更新，但 K3s 未部署新镜像

排查步骤：

# 1. 检查 Argo CD Application 状态
argocd app get ljwx-health

# 2. 查看同步状态
kubectl get application ljwx-health -n argocd -o yaml

# 3. 检查 Argo CD Controller 日志
kubectl logs -n argocd deployment/argocd-application-controller

# 4. 手动触发同步
argocd app sync ljwx-health --force

常见原因：

• Argo CD 自动同步被禁用
• ljwx-deploy 仓库访问权限问题
• kustomization.yaml 语法错误

问题 3: 镜像构建成功但部署失败

症状：镜像推送到 Harbor 成功，但 Pod 无法拉取镜像

排查步骤：

# 1. 检查 Pod 事件
kubectl describe pod <pod-name> -n ljwx-health

# 2. 检查 ImagePullSecrets
kubectl get secret -n ljwx-health | grep harbor

# 3. 验证镜像存在
docker pull harbor.omniverseai.net/ljwx-health/ljwx-boot:main-a1b2c3d

# 4. 检查 Harbor 仓库权限
# Harbor UI → ljwx-health project → Members

问题 4: 测试 Job 失败

ljwx-boot 测试失败：

# 检查 Maven 依赖
cd ljwx-boot
mvn dependency:tree

# 清理本地缓存重试
mvn clean test -U

ljwx-admin 测试失败：

# 检查 pnpm lock 文件
cd ljwx-admin
pnpm install --frozen-lockfile

# 类型检查
pnpm typecheck

ljwx-bigscreen 测试失败：

# 检查 Python 依赖
cd ljwx-bigscreen
uv pip install -r requirements.txt

# 运行测试
pytest -v

---

🔄 部署回滚

方法 1: 通过 Argo CD

# 1. 查看部署历史
argocd app history ljwx-health

# 2. 回滚到指定版本
argocd app rollback ljwx-health <revision-id>

方法 2: 通过 kubectl

# 1. 查看 Deployment 历史
kubectl rollout history deployment/ljwx-boot -n ljwx-health

# 2. 回滚到上一个版本
kubectl rollout undo deployment/ljwx-boot -n ljwx-health

# 3. 回滚到指定版本
kubectl rollout undo deployment/ljwx-boot -n ljwx-health --to-revision=2

方法 3: 通过 Git（推荐）

# 1. 克隆 ljwx-deploy 仓库
git clone http://192.168.1.83:33000/gao/ljwx-deploy.git

# 2. 回滚 kustomization.yaml 到旧版本
cd ljwx-deploy/apps/ljwx-health/overlays/ljwx-boot
git log kustomization.yaml  # 查看历史提交

# 3. 恢复到指定版本
git checkout <commit-hash> kustomization.yaml

# 4. 提交并推送
git commit -m "rollback: revert ljwx-boot to main-abc1234"
git push origin main

# 5. Argo CD 会自动检测并部署旧版本

---

📚 相关文档

核心文档

• 自定义基础镜像指南
• Kubernetes 部署指南

CI/CD 配置

• .gitea/workflows/ci.yml - CI Pipeline 配置
• .gitea/workflows/README.md - Workflow 说明

Argo CD

• ljwx-deploy 仓库 - GitOps 配置仓库
• Argo CD Application 配置

故障排查

• OpenTelemetry 集成修复
• 常见问题解答

---

⚠️ 重要注意事项

1. 远程仓库名称

正确：

git push local main  ✅

错误：

git push gitea main  ❌  # 远程仓库名不是 gitea
git push origin main ❌  # 远程仓库名不是 origin

2. GitOps 仓库分离

• ljwx-health: 应用代码仓库（本仓库）
• ljwx-deploy: GitOps 配置仓库（Argo CD 监控）

不要在 ljwx-health 仓库中直接修改 K8s 配置。

3. 镜像标签不可变

镜像标签格式 main-<sha> 确保不可变性：

• ✅ 每次构建生成唯一标签
• ✅ 避免 :latest 标签的不确定性
• ✅ 支持精确回滚

4. Argo CD 自动同步

Argo CD 配置了自动同步，通常不需要手动触发部署。

如果需要立即部署：

argocd app sync ljwx-health --force

---

维护者：运维团队 最后更新：2026-01-05 基于 CI/CD 版本：.gitea/workflows/ci.yml (真实配置)