Gitea + Kubernetes + Registry + Logto CI/CD 方案

1. 目标与原则

本方案面向私有化部署或内网研发环境，目标是交付可审计、可回滚、权限最小化的持续集成与持续发布能力。

核心原则：

CI 与部署解耦：CI 负责验证和产出不可变制品；GitOps 控制器负责部署。
一次构建，逐环境晋级：开发、预发、生产使用同一个镜像 digest，不在环境切换时重新构建。
声明式环境管理：环境配置、镜像版本和发布记录全部保存在 Git。
最小权限：CI 不持有生产集群的 cluster-admin 权限。
可验证供应链：镜像扫描、SBOM、签名和准入策略共同保证部署制品可信。

2. 总体架构

开发者
  |
  v
Gitea (源代码、PR、代码审查、Actions)
  |
  v
Gitea Actions Runner (构建、测试、扫描、签名)
  |                         |
  |                         +--> 质量报告 / 测试结果
  v
Harbor Registry (镜像、扫描、签名、保留策略)
  |
  v
GitOps 配置仓库 (Helm/Kustomize，镜像 digest)
  |
  v
Argo CD / Flux (拉取配置、同步、健康检查)
  |
  v
Kubernetes 集群 (dev / staging / production)

Logto (OIDC SSO、MFA、组织/角色)
  |--> Gitea
  |--> Harbor
  |--> Argo CD
  |--> Grafana / 其他运维平台

3. 组件选型与职责

组件	推荐实现	职责
代码与 CI	Gitea + act_runner	源码托管、PR 审查、流水线执行
镜像仓库	Harbor	私有 OCI Registry、扫描、机器人账号、镜像保留和权限管理
集群交付	Argo CD	GitOps 同步、漂移修复、健康检查、审计
身份认证	Logto	OIDC 单点登录、MFA、组织与角色
发布策略	Argo Rollouts	金丝雀/蓝绿、指标驱动的自动回滚
策略准入	Kyverno 或 OPA Gatekeeper	阻止不符合规范的工作负载进入集群
可观测性	Prometheus + Grafana + Loki	指标、告警和日志，支持发布验证

说明：Harbor 优于单独的 Docker Distribution Registry，因为它提供镜像扫描、项目隔离、机器人账号、复制和保留策略等生产环境所需能力。

4. 仓库划分

建议将应用源码和环境部署声明拆分，避免应用 CI 获得集群配置的写权限。

service-a/                         # 应用仓库
  .gitea/workflows/
    pr.yml                          # PR 验证
    build.yml                       # 合并后构建与推送
  Dockerfile
  src/
  tests/
  deploy/                           # Helm chart 或 Kustomize base（可选）

platform-gitops/                   # GitOps 仓库
  apps/
    service-a/
      base/
      overlays/
        dev/
        staging/
        production/
  clusters/
    dev/
    staging/
    production/

环境目录只引用固定镜像 digest：

images:
  - name: harbor.example.internal/team/service-a
    digest: sha256:0123456789abcdef...

不要以 latest 或可变的分支标签部署生产环境。

5. 分支与环境策略

事件	目标	结果
创建/更新 PR	临时验证环境或共享 dev	测试、扫描、可选 Preview 环境
合并至 `main`	dev	构建并推送镜像，自动更新 dev GitOps 配置
创建 Release Candidate	staging	将已验证 digest 晋级，执行端到端和验收测试
生产发布 PR 合并	production	将同一 digest 晋级至生产，金丝雀或蓝绿发布
紧急回滚	production	回滚 GitOps 提交或 Rollout 修订版本

生产环境 GitOps 目录应设置分支保护和强制审批。建议至少要求服务负责人或发布负责人审批，不允许直接推送。

6. CI 流水线

6.1 PR 验证

检出代码并恢复依赖缓存。
执行格式检查、静态检查和单元测试。
执行依赖漏洞扫描、密钥扫描和 SAST。
构建镜像，执行基础镜像和应用依赖扫描。
生成测试报告；按需部署短生命周期 Preview Namespace。
所有质量门禁通过后，PR 才可合并。

6.2 合并后的制品构建

使用固定构建上下文构建 OCI 镜像。
镜像同时打版本标签与不可变提交标签，例如 1.8.0、main-a1b2c3d。
推送至 Harbor。
使用 Syft 生成 SBOM，存储为制品或附加到镜像。
使用 Trivy/Grype 进行镜像扫描；阻断达到组织阈值的高危漏洞。
使用 Cosign 对镜像 digest 签名。
自动创建 GitOps 仓库 PR，更新 dev 环境到该 digest；由机器人账号提交。

7. CD 与发布策略

Argo CD 持续监听 GitOps 仓库。合并环境配置后，它负责将声明同步到对应 Kubernetes 集群并报告健康状态。

Dev

GitOps 配置更新后自动同步。
允许自动部署和自动修复漂移。
运行冒烟测试并将结果回传 Gitea。

Staging

推荐通过 PR 把 dev 已验证的 digest 晋级至 staging。
同步后执行数据库迁移校验、端到端测试、性能基线或安全测试。
环境配置应尽量接近生产，差异仅限副本数、域名、数据源和资源额度。

Production

仅接受经过审批的 GitOps PR。
使用 Argo Rollouts 执行金丝雀发布：5% -> 25% -> 50% -> 100%。
每个阶段检查错误率、延迟、业务成功率和 Pod 健康度。
指标不达标时自动中止并回滚至上一稳定 ReplicaSet。
数据库变更采用向后兼容的 Expand / Migrate / Contract 模式，禁止应用与破坏性 DDL 同时上线。

8. 权限与安全设计

Logto 统一身份

Logto 作为 OIDC Provider，接入 Gitea、Harbor、Argo CD、Grafana 等平台。建议角色映射如下：

Logto 角色	Gitea	Harbor	Argo CD
Developer	项目读写、创建 PR	拉取开发项目镜像	只读 dev 应用状态
Maintainer	合并受保护分支	推送团队镜像	同步 dev/staging
Release Manager	审批生产 GitOps PR	生产项目读写	生产同步权限
Platform Admin	平台管理	Harbor 管理	Argo CD 管理

生产发布、平台管理员和机器人账号必须启用 MFA 或等效的强认证机制。

Kubernetes RBAC

Gitea Runner 不直接连接生产 Kubernetes API。
Argo CD 使用每个集群、每个环境独立的 ServiceAccount。
ServiceAccount 仅拥有其目标 namespace 所需的资源权限。
使用 NetworkPolicy 限制应用、Runner、Argo CD 和 Registry 的网络访问范围。
使用 External Secrets、Vault 或 Sealed Secrets 管理密钥；禁止将明文密钥提交到 Git。

制品准入

用 Kyverno 或 Gatekeeper 实施以下规则：

仅允许从指定 Harbor 项目拉取镜像。
禁止 latest 标签，要求镜像以 digest 固定。
要求镜像通过 Cosign 签名验证。
拒绝高危漏洞超过阈值的制品，或要求安全例外记录。
要求设置资源 requests/limits、非 root 用户、只读根文件系统和健康检查。

9. Runner 设计

Runner 部署在 Kubernetes 中，优先使用临时 Pod Runner 或按任务弹性扩缩。
构建使用 Kaniko、BuildKit rootless 或 Buildah，避免将宿主机 Docker Socket 暴露给任务。
按信任边界拆分 Runner 标签：普通 PR、受信任构建、发布任务分别运行在不同 Runner 池。
Fork/外部贡献 PR 不得使用可读取生产密钥的 Runner。
Runner 仅使用 Harbor 机器人账号推送指定项目，凭据通过短期 Token 或 Secret 注入。

10. 回滚与灾备

应用回滚

首选回滚 GitOps 仓库中镜像 digest 的提交，形成完整审计记录。金丝雀发布期间由 Argo Rollouts 自动回滚。

平台备份

Gitea：数据库、仓库数据、附件、Actions 制品定期备份。
Harbor：PostgreSQL、Registry 存储、配置与密钥备份；配置异地复制策略。
Logto：数据库、OIDC 应用配置、密钥与组织角色配置备份。
Argo CD：GitOps 仓库为配置事实来源，同时备份 Argo CD 项目、ApplicationSet 和密钥配置。
Kubernetes：使用 Velero 备份关键 namespace、PVC 和集群资源。

定期做恢复演练。备份存在不等于可恢复。

11. 推荐实施顺序

部署 Logto，定义组织、角色、MFA 和 OIDC 应用。
部署 Gitea 与 Harbor，并接入 Logto SSO。
部署 Kubernetes Runner，完成一个服务的 PR 检查和镜像推送。
建立 GitOps 仓库，部署 Argo CD 并接入 Logto。
为第一个服务打通 dev 自动部署和 Git 回滚。
接入 staging、生产审批和 Argo Rollouts。
增加 Trivy、SBOM、Cosign、Kyverno 与安全例外流程。
接入 Prometheus、Grafana、Loki，使用发布指标驱动发布决策。
完成备份、恢复和权限审计演练。

12. 最小可用版本

第一阶段可先交付：

Gitea + act_runner + Harbor + Argo CD + Logto

该阶段至少应具备：PR 测试、镜像构建和推送、镜像 digest 写入 GitOps、Argo CD 自动同步 dev、Logto SSO、生产 GitOps PR 审批。

后续增强：

Trivy + Syft + Cosign + Kyverno + Argo Rollouts + Prometheus/Grafana/Loki

13. 验收标准

任意生产运行版本可从 GitOps 提交追溯到镜像 digest、源码提交、构建记录和审批记录。
同一个 digest 能从 dev 晋级到 staging、production，整个过程无需重新构建。
CI 账号无法直接修改生产工作负载。
未签名、来自非受信任 Registry、含不可接受漏洞或未设资源限制的镜像无法部署。
生产发布失败可在分钟级通过 Argo Rollouts 或 Git 回滚恢复。
Gitea、Harbor、Argo CD 和 Grafana 均可通过 Logto 单点登录，并按角色授权。