CI/CD 流水线：设计与 GitLab、GitHub Actions 实战

代码提交 → 触发 CI → 编译 → 单元测试 → 静态分析 → 构建产物 → 通知

持续集成 ⊂ 持续交付 ⊂ 持续部署

CI:   代码 → 构建 → 测试 → 制品
CD*:  制品 → 预发布环境 → [手动审批] → 生产环境（持续交付）
CD**: 制品 → 预发布环境 → 自动 → 生产环境（持续部署）

stages:
  - lint        # 30 秒
  - unit-test   # 2 分钟
  - build       # 3 分钟
  - integration # 10 分钟
  - deploy      # 2 分钟

lint:
  stage: lint
  script:
    - npm run lint
    - npm run type-check
  rules:
    - changes:
        - "src/**/*"

unit-test:
  stage: unit-test
  script:
    - npm run test:unit -- --coverage
  coverage: '/Lines\s*:\s*(\d+\.?\d*)%/'
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml

# GitLab CI 并行示例
unit-test:
  stage: test
  parallel: 4  # 分成 4 个并行 Job
  script:
    - jest --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL

# GitHub Actions 矩阵构建
jobs:
  test:
    strategy:
      matrix:
        node-version: [22, 24]
        os: [ubuntu-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm test

# 幂等部署脚本示例
deploy:
  stage: deploy
  script:
    # 检查当前版本，避免重复部署
    - CURRENT=$(kubectl get deployment app -o jsonpath='{.metadata.annotations.version}')
    - if [ "$CURRENT" = "$CI_COMMIT_SHA" ]; then echo "Already deployed"; exit 0; fi
    # 使用声明式部署
    - kubectl apply -f k8s/deployment.yaml
    - kubectl rollout status deployment/app --timeout=300s

# 保留最近 10 个版本的制品
deploy:
  artifacts:
    paths:
      - dist/
    expire_in: 30 days

# 回滚 Job
rollback:
  stage: deploy
  when: manual
  script:
    - kubectl rollout undo deployment/app
    - kubectl rollout status deployment/app --timeout=120s
  environment:
    name: production
    action: stop

dev (开发) → staging (预发布) → production (生产)
  ↓              ↓                  ↓
 自动部署      自动部署          手动审批后部署
 功能验证      集成验证          线上验证
 随时重置      接近生产          高可用保障

.deploy_template: &deploy_template
  stage: deploy
  image: bitnami/kubectl:latest
  script:
    - kubectl config use-context $KUBE_CONTEXT
    - envsubst < k8s/deployment.template.yaml | kubectl apply -f -
    - kubectl rollout status deployment/$APP_NAME -n $NAMESPACE --timeout=300s
  variables:
    APP_NAME: my-service

deploy:dev:
  <<: *deploy_template
  variables:
    KUBE_CONTEXT: dev-cluster
    NAMESPACE: dev
    REPLICAS: "1"
    CPU_LIMIT: "500m"
    MEMORY_LIMIT: "512Mi"
    LOG_LEVEL: "debug"
  environment:
    name: development
    url: https://dev.example.com
  rules:
    - if: $CI_COMMIT_BRANCH == "develop"

deploy:staging:
  <<: *deploy_template
  variables:
    KUBE_CONTEXT: staging-cluster
    NAMESPACE: staging
    REPLICAS: "2"
    CPU_LIMIT: "1000m"
    MEMORY_LIMIT: "1Gi"
    LOG_LEVEL: "info"
  environment:
    name: staging
    url: https://staging.example.com
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

deploy:prod:
  <<: *deploy_template
  variables:
    KUBE_CONTEXT: prod-cluster
    NAMESPACE: production
    REPLICAS: "5"
    CPU_LIMIT: "2000m"
    MEMORY_LIMIT: "2Gi"
    LOG_LEVEL: "warn"
  environment:
    name: production
    url: https://www.example.com
  rules:
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
  when: manual
  allow_failure: false

# k8s/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
  namespace: ${NAMESPACE}
data:
  DATABASE_HOST: "${DB_HOST}"
  REDIS_URL: "redis://${REDIS_HOST}:6379"
  LOG_LEVEL: "${LOG_LEVEL}"
  FEATURE_FLAG_NEW_UI: "true"

---
# k8s/secret.yaml (由 CI 变量注入)
apiVersion: v1
kind: Secret
metadata:
  name: app-secret
  namespace: ${NAMESPACE}
type: Opaque
data:
  DATABASE_PASSWORD: "${DB_PASSWORD_B64}"
  API_KEY: "${API_KEY_B64}"

# 使用 Vault Agent Sidecar 注入
annotations:
  vault.hashicorp.com/agent-inject: "true"
  vault.hashicorp.com/role: "my-service"
  vault.hashicorp.com/agent-inject-secret-db: "database/creds/my-service"
  vault.hashicorp.com/agent-inject-template-db: |
    {{- with secret "database/creds/my-service" -}}
    DATABASE_URL=postgresql://{{ .Data.username }}:{{ .Data.password }}@db:5432/mydb
    {{- end }}

# 定义流水线阶段（按顺序执行）
stages:
  - build
  - test
  - deploy

# 定义一个 Job
build-app:
  stage: build
  image: node:24-alpine
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/

# 添加官方仓库
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash

# 安装
sudo apt-get install gitlab-runner

# 验证版本
gitlab-runner --version

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.example.com/" \
  --registration-token "PROJECT_TOKEN_HERE" \
  --executor "docker" \
  --docker-image "alpine:latest" \
  --description "my-docker-runner" \
  --tag-list "docker,linux" \
  --run-untagged="true" \
  --locked="false"

# /etc/gitlab-runner/config.toml
concurrent = 4          # 最大并发 Job 数
check_interval = 3      # 轮询间隔（秒）

[[runners]]
  name = "docker-runner"
  url = "https://gitlab.example.com/"
  token = "RUNNER_TOKEN"
  executor = "docker"

  [runners.docker]
    image = "alpine:latest"           # 默认镜像
    privileged = false                # 是否特权模式（Docker-in-Docker 需要）
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache"]              # 挂载缓存卷
    shm_size = 0                      # 共享内存大小
    pull_policy = "if-not-present"    # 拉取策略：always/if-not-present/never
    allowed_images = ["ruby:*", "python:*", "node:*"]  # 镜像白名单

build-docker-image:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  script:
    - docker build -t my-app:$CI_COMMIT_SHA .
    - docker push registry.example.com/my-app:$CI_COMMIT_SHA

[[runners]]
  name = "shell-runner"
  url = "https://gitlab.example.com/"
  token = "RUNNER_TOKEN"
  executor = "shell"

  [runners.custom_build_dir]
    enabled = true    # 允许自定义构建目录

[[runners]]
  name = "autoscale-runner"
  url = "https://gitlab.example.com/"
  token = "RUNNER_TOKEN"
  executor = "docker+machine"
  limit = 10                    # 最大实例数

  [runners.machine]
    IdleCount = 2               # 空闲实例数
    IdleTime = 600              # 空闲超时（秒）
    MaxBuilds = 100             # 单实例最大构建次数
    MachineName = "runner-%s"
    MachineDriver = "amazonec2"
    MachineOptions = [
      "amazonec2-instance-type=t3.medium",
      "amazonec2-region=cn-north-1",
      "amazonec2-vpc-id=vpc-xxx",
      "amazonec2-subnet-id=subnet-xxx",
      "amazonec2-security-group=sg-xxx",
    ]

    [[runners.machine.autoscaling]]
      Periods = ["* * 8-18 * * mon-fri *"]   # 工作时间
      IdleCount = 5
      IdleTime = 300
      Timezone = "Asia/Shanghai"

    [[runners.machine.autoscaling]]
      Periods = ["* * * * * sat,sun *"]       # 周末
      IdleCount = 0
      IdleTime = 60

stages:
  - lint
  - build
  - test
  - security
  - deploy

# 同一 stage 的 jobs 会并行执行
lint-js:
  stage: lint
  script:
    - npx eslint . --max-warnings=0

lint-python:
  stage: lint
  script:
    - flake8 src/
    - mypy src/

build-frontend:
  stage: build
  script:
    - npm ci && npm run build
  artifacts:
    paths:
      - dist/frontend/

build-backend:
  stage: build
  script:
    - go build -o bin/server ./cmd/server
  artifacts:
    paths:
      - bin/

deploy-staging:
  stage: deploy
  dependencies:
    - build-frontend     # 只下载 frontend 的制品
    - build-backend      # 只下载 backend 的制品
  script:
    - scp dist/frontend/* staging:/var/www/html/
    - scp bin/server staging:/opt/app/

test-unit:
  stage: test
  script:
    - go test ./... -coverprofile=coverage.out -v 2>&1 | tee test-output.txt
  artifacts:
    when: always              # always/on_success/on_failure
    paths:
      - coverage.out
      - test-output.txt
    reports:
      junit: test-output.txt  # 解析测试报告在 MR 中展示
      coverage_report:
        coverage_format: cobertura
        path: coverage.xml
    expire_in: 7 days         # 制品过期时间

variables:
  npm_config_cache: "$CI_PROJECT_DIR/.npm"

cache:
  key:
    files:
      - package-lock.json     # 基于文件内容生成缓存 key
  paths:
    - .npm/
    - node_modules/

build:
  stage: build
  script:
    - npm ci --cache .npm
    - npm run build

# 在 script 中直接使用
deploy-production:
  stage: deploy
  script:
    - echo "项目: $CI_PROJECT_NAME"
    - echo "分支: $CI_COMMIT_REF_NAME"
    - echo "提交: $CI_COMMIT_SHA"
    - echo "短 SHA: $CI_COMMIT_SHORT_SHA"
    - echo "标签: $CI_COMMIT_TAG"
    - echo "MR 源分支: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"
    - echo "Pipeline ID: $CI_PIPELINE_ID"
    - echo "Job ID: $CI_JOB_ID"
    - echo "Runner 描述: $CI_RUNNER_DESCRIPTION"
    - echo "Registry: $CI_REGISTRY"
    - echo "Registry 镜像: $CI_REGISTRY_IMAGE"

# Pipeline 级变量
variables:
  APP_NAME: "my-awesome-app"
  DEPLOY_ENV: "staging"

build:
  stage: build
  variables:
    BUILD_TYPE: "release"       # Job 级变量
  script:
    - echo "Building $APP_NAME ($BUILD_TYPE)"
    - make BUILD_TYPE=$BUILD_TYPE

# 使用 Protected + Masked 变量（在 Settings 中配置，不在 YAML 中暴露）
deploy-production:
  stage: deploy
  script:
    - echo "$PROD_DB_PASSWORD" | docker secret create db_password -  # 日志中显示 [MASKED]
  only:
    - main                          # 仅 main 分支触发
  environment:
    name: production

# 需要在项目 Settings 中配置 Vault 集成
deploy-with-vault:
  stage: deploy
  id_tokens:
    VAULT_ID_TOKEN:
      aud: https://vault.example.com
  secrets:
    DB_PASSWORD:
      vault:
        engine: { name: kv-v2, path: secret }
        path: production/db
        field: password
  script:
    - echo "DB password loaded from Vault"   # 不要打印实际值
    - deploy --db-password "$DB_PASSWORD"

stages:
  - build
  - test
  - deploy

variables:
  DOCKER_REGISTRY: "registry.example.com"

# ============ Build ============
build:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  script:
    - docker build -t $DOCKER_REGISTRY/$CI_PROJECT_NAME:$CI_COMMIT_SHA .
    - docker push $DOCKER_REGISTRY/$CI_PROJECT_NAME:$CI_COMMIT_SHA

# ============ Test ============
test-unit:
  stage: test
  image: $DOCKER_REGISTRY/$CI_PROJECT_NAME:$CI_COMMIT_SHA
  script:
    - npm test -- --coverage
  coverage: '/All files\s*\|\s*([\d.]+)/'
  artifacts:
    reports:
      junit: junit.xml
      coverage_report:
        coverage_format: cobertura
        path: coverage.xml

test-integration:
  stage: test
  image: $DOCKER_REGISTRY/$CI_PROJECT_NAME:$CI_COMMIT_SHA
  services:
    - postgres:15
    - redis:7
  variables:
    POSTGRES_DB: test_db
    POSTGRES_USER: test
    POSTGRES_PASSWORD: test
    DATABASE_URL: "postgresql://test:test@postgres:5432/test_db"
    REDIS_URL: "redis://redis:6379"
  script:
    - npm run test:integration

# ============ Deploy ============
deploy-staging:
  stage: deploy
  environment:
    name: staging
    url: https://staging.example.com
  script:
    - kubectl set image deployment/$CI_PROJECT_NAME
        app=$DOCKER_REGISTRY/$CI_PROJECT_NAME:$CI_COMMIT_SHA
  only:
    - develop
  when: manual                  # 手动触发

.deploy_template: &deploy_template
  stage: deploy
  image: bitnami/kubectl:latest
  script:
    - kubectl config use-context $KUBE_CONTEXT
    - envsubst < k8s/deployment.yml | kubectl apply -f -
    - kubectl rollout status deployment/$CI_PROJECT_NAME -n $K8S_NAMESPACE

deploy-staging:
  <<: *deploy_template
  variables:
    KUBE_CONTEXT: staging
    K8S_NAMESPACE: staging
    REPLICAS: "2"
  environment:
    name: staging
    url: https://staging.example.com
  only:
    - develop

deploy-production:
  <<: *deploy_template
  variables:
    KUBE_CONTEXT: production
    K8S_NAMESPACE: production
    REPLICAS: "5"
  environment:
    name: production
    url: https://www.example.com
  only:
    - main
  when: manual
  allow_failure: false          # 不允许跳过

test-suite:
  stage: test
  parallel: 4                   # 启动 4 个并行 Job
  script:
    - |
      case $CI_NODE_INDEX in
        1) TEST_PATTERN="tests/unit/models/**" ;;
        2) TEST_PATTERN="tests/unit/services/**" ;;
        3) TEST_PATTERN="tests/unit/controllers/**" ;;
        4) TEST_PATTERN="tests/unit/middleware/**" ;;
      esac
    - pytest $TEST_PATTERN --junitxml=results-$CI_NODE_INDEX.xml
  artifacts:
    reports:
      junit:
        - results-*.xml

build-matrix:
  stage: build
  parallel:
    matrix:
      - GO_VERSION: ["1.21", "1.22"]
        OS: ["linux", "darwin"]
        ARCH: ["amd64", "arm64"]
  image: golang:$GO_VERSION
  script:
    - GOOS=$OS GOARCH=$ARCH go build -o bin/app-$OS-$ARCH ./cmd/app
  artifacts:
    paths:
      - bin/

build:
  stage: build
  script:
    - make build
    - make docs
  artifacts:
    name: "$CI_PROJECT_NAME-$CI_COMMIT_REF_SLUG-$CI_PIPELINE_ID"
    paths:
      - bin/
      - docs/
      - config/production.yml
    exclude:
      - "**/*.test"             # 排除测试文件
      - "**/*.log"
    when: on_success            # on_success（默认）/ on_failure / always
    expire_in: 30 days
    access: all                 # all / developer / none

# 快速过期的中间产物
test-results:
  artifacts:
    expire_in: 3 days

# 永久保留的发布制品
release-package:
  artifacts:
    expire_in: never            # 永不过期
  only:
    - tags                      # 仅标签触发

build-frontend:
  stage: build
  script: npm run build
  artifacts:
    paths: [dist/]

build-backend:
  stage: build
  script: go build ./...
  artifacts:
    paths: [bin/]

# 默认行为：每个 Job 会下载前面所有阶段的制品
# 显式控制：
deploy:
  stage: deploy
  dependencies:                 # 只下载指定 Job 的制品
    - build-frontend
  script:
    - ls dist/                  # [可用] 有 frontend
    - ls bin/ 2>/dev/null       # [不适用] 没有 backend

# 不下载任何制品
lint:
  stage: test
  dependencies: []              # 空数组 = 不下载
  script: eslint .

deploy-ssh:
  stage: deploy
  before_script:
    - apt-get update && apt-get install -y openssh-client
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
    - mkdir -p ~/.ssh && chmod 700 ~/.ssh
    - ssh-keyscan -H $DEPLOY_HOST >> ~/.ssh/known_hosts
  script:
    - scp -r dist/* deploy@$DEPLOY_HOST:/opt/app/
    - ssh deploy@$DEPLOY_HOST "cd /opt/app && docker compose pull && docker compose up -d"
  environment:
    name: production
    url: https://www.example.com

build-and-push:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  before_script:
    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin $CI_REGISTRY
  script:
    - |
      docker build \
        --cache-from $CI_REGISTRY_IMAGE:latest \
        --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA \
        --tag $CI_REGISTRY_IMAGE:latest \
        .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
    - docker push $CI_REGISTRY_IMAGE:latest

deploy-docker:
  stage: deploy
  before_script:
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | ssh-add -
  script:
    - |
      ssh deploy@$DEPLOY_HOST << 'EOF'
        docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
        docker pull $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
        docker stop app || true
        docker rm app || true
        docker run -d --name app \
          --restart unless-stopped \
          -p 8080:8080 \
          -e DATABASE_URL="$DATABASE_URL" \
          $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
      EOF

deploy-k8s:
  stage: deploy
  image:
    name: bitnami/kubectl:latest
    entrypoint: [""]
  before_script:
    - echo "$KUBE_CONFIG" | base64 -d > /tmp/kubeconfig
    - export KUBECONFIG=/tmp/kubeconfig
  script:
    # 替换镜像标签
    - kubectl set image deployment/$CI_PROJECT_NAME
        app=$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
        -n $K8S_NAMESPACE
    - kubectl rollout status deployment/$CI_PROJECT_NAME
        -n $K8S_NAMESPACE
        --timeout=300s
  after_script:
    - rm -f /tmp/kubeconfig
  environment:
    name: production
    url: https://www.example.com
    kubernetes:
      namespace: production

deploy-helm:
  stage: deploy
  image:
    name: alpine/helm:3.14
    entrypoint: [""]
  before_script:
    - echo "$KUBE_CONFIG" | base64 -d > /tmp/kubeconfig
    - export KUBECONFIG=/tmp/kubeconfig
    - helm repo add myrepo https://charts.example.com
    - helm repo update
  script:
    - |
      helm upgrade --install $CI_PROJECT_NAME myrepo/app-chart \
        --namespace $K8S_NAMESPACE \
        --create-namespace \
        --set image.repository=$CI_REGISTRY_IMAGE \
        --set image.tag=$CI_COMMIT_SHA \
        --set ingress.host=$DEPLOY_HOST \
        --values values-production.yaml \
        --wait --timeout 5m

# 项目根目录创建 .gitlab-ci.yml 仅需一行
include:
  - template: Auto-DevOps.gitlab-ci.yml

# 或者自定义覆盖
variables:
  AUTO_DEVOPS_DEPLOY_TARGET: kubernetes
  KUBE_NAMESPACE: my-namespace
  HELM_UPGRADE_EXTRA_ARGS: "--set replicas=3"

include:
  - template: Auto-DevOps.gitlab-ci.yml

# 全局缓存配置，所有 Job 继承
cache:
  key: "${CI_COMMIT_REF_SLUG}"    # 按分支隔离缓存
  paths:
    - node_modules/
    - .npm/
    - .cache/
  policy: pull-push                # pull / push / pull-push

# 仅 pull（不更新缓存，用于只读 Job）
test:
  stage: test
  cache:
    key: "${CI_COMMIT_REF_SLUG}"
    paths:
      - node_modules/
    policy: pull                   # 只读缓存
  script:
    - npm test

build-frontend:
  stage: build
  cache:
    - key: frontend-deps
      paths:
        - frontend/node_modules/
    - key: frontend-build-cache
      paths:
        - frontend/.cache/
  script:
    - cd frontend && npm ci && npm run build

build-backend:
  stage: build
  cache:
    - key: backend-deps
      paths:
        - backend/vendor/
  script:
    - cd backend && go mod download && go build ./...

# 策略 1：基于 Lock 文件生成缓存 key（推荐）
cache:
  key:
    files:
      - package-lock.json          # 文件内容变化 → 新缓存
  paths:
    - node_modules/

# 策略 2：分支 + Lock 文件组合
cache:
  key:
    files:
      - package-lock.json
    prefix: $CI_COMMIT_REF_SLUG
  paths:
    - node_modules/

# 策略 3：固定 key + 手动版本控制
cache:
  key: "deps-v2"                   # 需要清除缓存时改版本号
  paths:
    - node_modules/

# 清除缓存的技巧：
# 方式 1：在 GitLab UI → CI/CD → Pipelines → Clear runner caches
# 方式 2：修改 cache key 中的版本号
# 方式 3：使用 API
#   curl --request DELETE --header "PRIVATE-TOKEN: $TOKEN" \
#     "https://gitlab.example.com/api/v4/projects/$PROJECT_ID/clean"

include:
  - template: Security/SAST.gitlab-ci.yml

sast:
  variables:
    SAST_EXCLUDED_ANALYZERS: "spotbugs"     # 排除特定分析器
    SAST_EXCLUDED_PATHS: "test,spec,docs"   # 排除目录

include:
  - template: Security/DAST.gitlab-ci.yml

dast:
  variables:
    DAST_WEBSITE: "https://staging.example.com"
    DAST_FULL_SCAN_ENABLED: "true"
    DAST_AUTH_URL: "https://staging.example.com/login"
    DAST_USERNAME: "scanner@example.com"
    DAST_PASSWORD: "$DAST_PASSWORD"         # 在 CI Variables 中配置

include:
  - template: Security/Dependency-Scanning.gitlab-ci.yml

dependency_scanning:
  variables:
    DS_EXCLUDED_PATHS: "test,spec,docs"

include:
  - template: Security/Container-Scanning.gitlab-ci.yml

container_scanning:
  variables:
    CS_IMAGE: "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA"
    CS_SEVERITY_THRESHOLD: "high"           # 只报告 high 及以上

include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Security/Dependency-Scanning.gitlab-ci.yml
  - template: Security/Container-Scanning.gitlab-ci.yml
  - template: Security/Secret-Detection.gitlab-ci.yml

stages:
  - build
  - test
  - security-sast
  - security-container
  - deploy

build:
  stage: build
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

# 所有安全扫描 Job 自动从 include 模板继承配置
# 扫描结果会自动合并到 MR 的安全面板中

# 定义可复用的 Job 片段
.docker_login: &docker_login
  before_script:
    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin

.base_deploy: &base_deploy
  stage: deploy
  image: bitnami/kubectl:latest
  <<: *docker_login
  when: manual
  allow_failure: false

# 使用锚点扩展
deploy-staging:
  <<: *base_deploy
  variables:
    K8S_NAMESPACE: staging
  environment:
    name: staging
  only:
    - develop

deploy-production:
  <<: *base_deploy
  variables:
    K8S_NAMESPACE: production
  environment:
    name: production
  only:
    - main

.docker_login:
  before_script:
    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin

.base_deploy:
  stage: deploy
  image: bitnami/kubectl:latest
  extends: .docker_login
  when: manual

deploy-staging:
  extends: .base_deploy
  variables:
    K8S_NAMESPACE: staging
  environment:
    name: staging

deploy-production:
  extends: .base_deploy
  variables:
    K8S_NAMESPACE: production
  environment:
    name: production

# 使用 rules:changes 按文件变更路径触发
build-frontend:
  stage: build
  rules:
    - changes:
        - frontend/**/*
        - shared/**/*
      when: on_success
  script:
    - cd frontend && npm ci && npm run build

build-backend:
  stage: build
  rules:
    - changes:
        - backend/**/*
        - shared/**/*
      when: on_success
  script:
    - cd backend && go build ./...

deploy-frontend:
  stage: deploy
  rules:
    - changes:
        - frontend/**/*
      when: manual
  script:
    - echo "Deploy frontend"

deploy-backend:
  stage: deploy
  rules:
    - changes:
        - backend/**/*
      when: manual
  script:
    - echo "Deploy backend"

debug-job:
  stage: test
  image: ubuntu:22.04
  variables:
    CI_DEBUG_TRACE: "1"             # 开启 Shell 调试（set -x）
  script:
    - echo "Debug info:"
    - echo "Shell: $0"
    - echo "User: $(whoami)"
    - echo "PWD: $(pwd)"
    - echo "ENV:"
    - env | sort
    - echo "Network:"
    - ip addr show || ifconfig
    - echo "Disk:"
    - df -h

# 1. 本地运行 Job（需要安装 gitlab-runner）
gitlab-runner exec docker build-job

# 2. 使用 CI_DEBUG_SERVICES 查看 service 日志
#    在 Variables 中设置 CI_DEBUG_SERVICES=true

# 3. 在 Job 失败时保留容器（Docker Executor）
#    config.toml 中设置 [runners.docker] cleanup = false

# 4. 使用 after_script 查看失败后的环境状态
job:
  script:
    - make test
  after_script:
    - ls -la /builds/
    - cat /tmp/*.log 2>/dev/null || true

#  错误：直接打印密码
deploy:
  script:
    - echo "Connecting with password: $DB_PASSWORD"    # 日志中可见！
    - mysql -u root -p$DB_PASSWORD

#  正确：使用 Masked 变量 + 避免打印
deploy:
  script:
    - mysql -u root -p"$DB_PASSWORD" -e "SELECT 1"    # 变量在 Settings 中设为 Masked

# [不适用] 以 root 运行的容器中创建的文件，宿主机 runner 用户无法访问
build:
  script:
    - touch output.txt

# [可用] 使用 --user 指定用户，或在 script 中修改权限
build:
  script:
    - touch output.txt
    - chmod 644 output.txt

# [不适用] 不同分支使用相同缓存 key 但 Lock 文件不同
cache:
  key: "deps"

# [可用] 基于 Lock 文件生成 key
cache:
  key:
    files:
      - package-lock.json

# [不适用] 不要混用 rules 和 only/except（已废弃）
job:
  only:
    - main
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

# [可用] 统一使用 rules
job:
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
    - if: $CI_COMMIT_TAG

# [不适用] 打包整个 node_modules（可能上 GB）
artifacts:
  paths:
    - node_modules/

# [可用] 只打包构建产物，依赖用 cache 管理
artifacts:
  paths:
    - dist/
  expire_in: 7 days

# ============================================
# .gitlab-ci.yml - 完整项目模板
# ============================================

stages:
  - prepare
  - build
  - test
  - security
  - deploy

variables:
  DOCKER_REGISTRY: "$CI_REGISTRY"
  DOCKER_IMAGE: "$CI_REGISTRY_IMAGE"
  K8S_NAMESPACE: "default"

# ---- 全局缓存 ----
default:
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - node_modules/
      - .npm/
  image: node:24-alpine

# ---- 复用模板 ----
.docker_auth: &docker_auth
  before_script:
    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin $CI_REGISTRY

.kubectl_base: &kubectl_base
  image:
    name: bitnami/kubectl:latest
    entrypoint: [""]
  before_script:
    - echo "$KUBE_CONFIG" | base64 -d > /tmp/kubeconfig
    - export KUBECONFIG=/tmp/kubeconfig

# ============ Prepare Stage ============
install-deps:
  stage: prepare
  script:
    - npm ci --cache .npm
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - node_modules/
      - .npm/
    policy: pull-push

# ============ Build Stage ============
build-app:
  stage: build
  script:
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 7 days

build-docker:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  <<: *docker_auth
  script:
    - docker build --cache-from $DOCKER_IMAGE:latest -t $DOCKER_IMAGE:$CI_COMMIT_SHA -t $DOCKER_IMAGE:latest .
    - docker push $DOCKER_IMAGE:$CI_COMMIT_SHA
    - docker push $DOCKER_IMAGE:latest

# ============ Test Stage ============
test-unit:
  stage: test
  script:
    - npm run test:unit -- --coverage
  coverage: '/Lines\s*:\s*([\d.]+)/'
  artifacts:
    reports:
      junit: junit.xml
      coverage_report:
        coverage_format: cobertura
        path: coverage.xml

test-integration:
  stage: test
  services:
    - postgres:15
    - redis:7
  variables:
    POSTGRES_DB: test
    POSTGRES_USER: test
    POSTGRES_PASSWORD: test
    DATABASE_URL: "postgresql://test:test@postgres:5432/test"
  script:
    - npm run test:integration

# ============ Security Stage ============
include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Security/Dependency-Scanning.gitlab-ci.yml
  - template: Security/Secret-Detection.gitlab-ci.yml

# ============ Deploy Stage ============
deploy-staging:
  <<: *kubectl_base
  stage: deploy
  script:
    - kubectl set image deployment/app app=$DOCKER_IMAGE:$CI_COMMIT_SHA -n staging
    - kubectl rollout status deployment/app -n staging --timeout=300s
  environment:
    name: staging
    url: https://staging.example.com
  rules:
    - if: $CI_COMMIT_BRANCH == "develop"

deploy-production:
  <<: *kubectl_base
  stage: deploy
  script:
    - kubectl set image deployment/app app=$DOCKER_IMAGE:$CI_COMMIT_SHA -n production
    - kubectl rollout status deployment/app -n production --timeout=300s
  environment:
    name: production
    url: https://www.example.com
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
  allow_failure: false

# .github/workflows/ci.yml
name: CI Pipeline          # Workflow 名称，显示在 GitHub Actions 页面

on:                         # 触发条件
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

env:                        # 全局环境变量
  NODE_VERSION: '24'
  REGISTRY: ghcr.io

jobs:                       # 作业定义
  build:
    name: Build & Test
    runs-on: ubuntu-latest  # 运行环境
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

on:
  # 1. Push 事件 —— 推送代码到指定分支时触发
  push:
    branches: [main, 'release/**']
    tags: ['v*']
    paths: ['src/**', 'package.json']        # 只有这些路径的文件变更才触发
    paths-ignore: ['docs/**', '*.md']         # 排除这些路径

  # 2. Pull Request 事件
  pull_request:
    types: [opened, synchronize, reopened]    # PR 状态变更时触发
    branches: [main]

  # 3. 定时任务（Cron 表达式，UTC 时间）
  schedule:
    - cron: '0 2 * * 1'  # 每周一 UTC 02:00（北京时间 10:00）

  # 4. 手动触发
  workflow_dispatch:
    inputs:
      environment:
        description: '部署环境'
        required: true
        default: 'staging'
        type: choice
        options: [dev, staging, prod]
      dry_run:
        description: '模拟运行'
        required: false
        type: boolean
        default: false

  # 5. 其他 Workflow 完成后触发
  workflow_run:
    workflows: ["Build"]
    types: [completed]

  # 6. 当收到 issue comment 时触发（常用于 ChatOps）
  issue_comment:
    types: [created]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Linting..."

  test:
    runs-on: ubuntu-latest
    needs: lint              # lint 完成后才执行
    steps:
      - run: echo "Testing..."

  deploy:
    runs-on: ubuntu-latest
    needs: [lint, test]      # 两个都完成后才执行
    if: github.ref == 'refs/heads/main'  # 仅 main 分支部署
    steps:
      - run: echo "Deploying..."

steps:
  - name: Only on main
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    run: echo "Deploy to production"

  - name: Skip for bot PRs
    if: "!contains(github.event.pull_request.title, '[bot]')"
    run: echo "Run tests"

  - name: Continue on failure
    if: failure()           # 前一步失败时执行
    run: echo "Handling failure..."

  - name: Always run
    if: always()            # 无论前面成功失败都执行
    run: echo "Cleanup"

steps:
  - name: Step name              # 显示名称
    id: my_step                  # 唯一 ID，用于后续引用输出
    if: success()                # 条件执行
    working-directory: ./src     # 工作目录
    env:                         # Step 级别的环境变量
      MY_VAR: 'hello'
    run: |                       # Shell 命令
      echo "Value: $MY_VAR"
      echo "output=value" >> $GITHUB_OUTPUT  # 设置输出
    continue-on-error: true      # 允许失败而不中断

  - name: Use previous output
    run: echo "Got ${{ steps.my_step.outputs.output }}"

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node-version: [22, 24]
        exclude:                    # 排除特定组合
          - os: windows-latest
            node-version: 24
        include:                    # 追加额外组合
          - os: ubuntu-latest
            node-version: 22
            experimental: true
      fail-fast: false              # 一个失败不取消其他
      max-parallel: 3               # 最多并行 3 个
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci && npm test
      - name: Notify experimental failure
        if: failure() && matrix.experimental
        run: echo "Experimental build failed, not blocking"

env:
  GLOBAL_VAR: 'available to all jobs'

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      JOB_VAR: 'available to all steps in this job'
    steps:
      - name: Use env
        env:
          STEP_VAR: 'available to this step only'
        run: |
          echo "Global: $GLOBAL_VAR"
          echo "Job: $JOB_VAR"
          echo "Step: $STEP_VAR"
          echo "Secret: ${{ secrets.MY_SECRET }}"
          echo "Env from context: ${{ vars.MY_CONFIG }}"

- uses: actions/checkout@v4
  with:
    repository: owner/repo       # 检出其他仓库
    ref: develop                 # 指定分支/标签
    token: ${{ secrets.GH_PAT }} # 使用 PAT 访问私有仓库
    submodules: true             # 递归检出子模块
    fetch-depth: 0               # 完整历史（用于 changelog 生成）
    path: my-repo                # 检出到指定目录

- uses: actions/setup-node@v4
  with:
    node-version: '24'           # 支持 semver，如 '20.x'、'^20'
    cache: 'npm'                 # 自动缓存 npm/pnpm/yarn 依赖
    registry-url: 'https://registry.npmjs.org'
    scope: '@my-org'             # npm scope

- uses: actions/setup-java@v4
  with:
    distribution: 'temurin'      # temurin/zulu/adopt/microsoft/liberica/corretto
    java-version: '21'
    cache: 'gradle'              # 缓存 Gradle 或 Maven 依赖
    # cache: 'maven'
    server-id: github            # Maven settings.xml 配置
    settings-path: ${{ github.workspace }}

- uses: actions/setup-python@v5
  with:
    python-version: '3.12'
    cache: 'pip'
    # cache: 'pipenv'
    # cache: 'poetry'

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3

- name: Login to GHCR
  uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}

- name: Build and push
  uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    tags: |
      ghcr.io/${{ github.repository }}:latest
      ghcr.io/${{ github.repository }}:${{ github.sha }}
    cache-from: type=gha
    cache-to: type=gha,mode=max
    platforms: linux/amd64,linux/arm64  # 多架构构建

# 缓存任意目录
- uses: actions/cache@v4
  with:
    path: |
      ~/.cache/go-build
      ~/go/pkg/mod
    key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
    restore-keys: ${{ runner.os }}-go-

# 上传制品
- uses: actions/upload-artifact@v4
  with:
    name: build-output
    path: dist/
    retention-days: 7

# 下载制品
- uses: actions/download-artifact@v4
  with:
    name: build-output
    path: dist/

# 发送 Slack 通知
- uses: slackapi/slack-github-action@v2
  with:
    webhook: ${{ secrets.SLACK_WEBHOOK }}
    webhook-type: incoming-webhook
    payload: |
      {"text": "Build ${{ job.status }}: ${{ github.repository }}"}

# 创建目录
mkdir actions-runner && cd actions-runner

# 下载最新版本（Linux x64 为例）
curl -o actions-runner-linux-x64-2.319.1.tar.gz -L \
  https://github.com/actions/runner/releases/download/v2.319.1/actions-runner-linux-x64-2.319.1.tar.gz

tar xzf actions-runner-linux-x64-2.319.1.tar.gz

# 配置（从 GitHub 仓库 Settings > Actions > Runners 获取 token）
./config.sh --url https://github.com/your-org/your-repo \
  --token YOUR_REGISTRATION_TOKEN \
  --labels self-hosted,linux,x64,gpu \
  --name prod-runner-01 \
  --work _work

# 作为 systemd 服务安装运行
sudo ./svc.sh install
sudo ./svc.sh start
sudo ./svc.sh status

jobs:
  # 使用 GitHub 托管 Runner
  lint:
    runs-on: ubuntu-latest

  # 使用自托管 Runner（必须有所有指定标签）
  build:
    runs-on: [self-hosted, linux, gpu]

  # 使用标签做更细粒度的匹配
  deploy:
    runs-on: [self-hosted, linux, production]

jobs:
  deploy:
    runs-on: [self-hosted, linux, production]
    # 在仓库/组织设置中配置 Runner Group 的访问控制

# 对于公开仓库，强烈建议仅使用临时 Runner
jobs:
  build:
    runs-on: [self-hosted, linux]
    container:
      image: node:24-slim        # 在容器中运行，隔离环境
      options: --read-only        # 只读文件系统
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

# ARC Helm values 示例
# helm install arc --namespace arc-systems \
#   actions-runner-controller/actions-runner-controller \
#   -f arc-values.yaml

# arc-values.yaml
authSecret:
  create: true
  github_token: "ghp_xxxxxxxxxxxx"

runnerDeployment:
  name: org-runner
  replicas: 2
  spec:
    organization: your-org
    labels:
      - k8s
      - linux
    resources:
      limits:
        cpu: "2"
        memory: "4Gi"

# HorizontalRunnerAutoscaler 配置
horizontalRunnerAutoscaler:
  minReplicas: 1
  maxReplicas: 10
  scaleDownDelaySecondsAfterScaleOut: 300
  metrics:
    - type: PercentageRunnersBusy
      scaleUpThreshold: '0.75'
      scaleDownThreshold: '0.25'

steps:
  - name: Use secrets
    env:
      DB_PASSWORD: ${{ secrets.DB_PASSWORD }}           # Repository secret
      DEPLOY_KEY: ${{ secrets.PROD_DEPLOY_KEY }}        # Environment secret
      SHARED_API_KEY: ${{ secrets.ORG_API_KEY }}        # Organization secret
    run: |
      echo "Deploying with key..."
      # 不要 echo secret 值

# 使用 Environment
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production          # 引用 environment 名称
    steps:
      - name: Deploy
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: ./deploy.sh

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write              # 必须声明 id-token 权限
      contents: read
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
          aws-region: ap-southeast-1

      - name: Deploy to S3
        run: aws s3 sync ./dist s3://my-bucket

      # 同样支持 GCP、Azure
      - name: Authenticate to Google Cloud
        uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: projects/123456/locations/global/workloadIdentityPools/github/providers/github
          service_account: github-actions@my-project.iam.gserviceaccount.com

# Repository/Environment Variables（非敏感，日志中可见）
env:
  APP_URL: ${{ vars.APP_URL }}
  FEATURE_FLAG: ${{ vars.ENABLE_NEW_UI }}

# Secrets（敏感，日志中被遮蔽）
env:
  API_KEY: ${{ secrets.API_KEY }}

name: Node.js CI

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

permissions:
  contents: read
  pull-requests: write

jobs:
  ci:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: 'npm'

      - run: npm ci

      - name: Lint
        run: npm run lint

      - name: Type check
        run: npm run type-check

      - name: Unit tests
        run: npm test -- --coverage

      - name: Upload coverage
        if: github.event_name == 'pull_request'
        uses: actions/upload-artifact@v4
        with:
          name: coverage
          path: coverage/

      - name: Build
        run: npm run build

      - name: Upload build
        uses: actions/upload-artifact@v4
        with:
          name: build
          path: dist/
          retention-days: 3

name: Java CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '21'
          cache: 'gradle'

      - name: Grant execute permission for gradlew
        run: chmod +x gradlew

      - name: Build
        run: ./gradlew build -x test

      - name: Test
        run: ./gradlew test

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: build/reports/tests/

      - name: Upload JAR
        uses: actions/upload-artifact@v4
        with:
          name: app-jar
          path: build/libs/*.jar

name: Docker Build & Push

on:
  push:
    tags: ['v*']

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
      attestations: write
      id-token: write
    steps:
      - uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to GHCR
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}
            type=sha

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
          platforms: linux/amd64,linux/arm64

name: Release

on:
  push:
    tags: ['v*']

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: 'npm'
          registry-url: 'https://registry.npmjs.org'

      - run: npm ci

      - run: npm run build

      - name: Publish to npm
        run: npm publish --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v2
        with:
          generate_release_notes: true
          files: dist/*

name: Deploy

on:
  push:
    branches: [main]
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        type: choice
        options: [staging, production]

jobs:
  deploy-dev:
    runs-on: ubuntu-latest
    environment: dev
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to dev
        run: |
          echo "Deploying to dev..."
          # 实际部署命令

  deploy-staging:
    runs-on: ubuntu-latest
    needs: deploy-dev
    environment:
      name: staging
      url: https://staging.example.com
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to staging
        run: echo "Deploying to staging..."

  deploy-production:
    runs-on: ubuntu-latest
    needs: deploy-staging
    environment:
      name: production
      url: https://example.com
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to production
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: echo "Deploying to production..."

name: Multi-env Deploy

on:
  push:
    branches:
      - develop       # → dev 环境
      - 'release/*'   # → staging 环境
      - main          # → production 环境

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ github.ref_name == 'develop' && 'dev' || startsWith(github.ref_name, 'release/') && 'staging' || 'production' }}
    steps:
      - uses: actions/checkout@v4
      - name: Determine env
        id: env
        run: |
          if [[ "${{ github.ref_name }}" == "develop" ]]; then
            echo "target=dev" >> $GITHUB_OUTPUT
          elif [[ "${{ github.ref_name }}" == release/* ]]; then
            echo "target=staging" >> $GITHUB_OUTPUT
          else
            echo "target=production" >> $GITHUB_OUTPUT
          fi
      - name: Deploy to ${{ steps.env.outputs.target }}
        run: echo "Deploying to ${{ steps.env.outputs.target }}"

# .github/actions/setup-project/action.yml
name: 'Setup Project'
description: 'Install dependencies and setup environment'

inputs:
  node-version:
    description: 'Node.js version'
    required: false
    default: '20'
  install-command:
    description: 'Install command'
    required: false
    default: 'npm ci'

runs:
  using: 'composite'
  steps:
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}
        cache: 'npm'

    - name: Install dependencies
      shell: bash
      run: ${{ inputs.install-command }}

    - name: Verify setup
      shell: bash
      run: |
        echo "Node: $(node -v)"
        echo "npm: $(npm -v)"

steps:
  - uses: actions/checkout@v4
  - uses: ./.github/actions/setup-project
    with:
      node-version: '22'
  - run: npm test

# .github/workflows/reusable-deploy.yml（可重用 Workflow）
name: Reusable Deploy

on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
      image-tag:
        required: true
        type: string
      replicas:
        required: false
        type: number
        default: 2
    secrets:
      DEPLOY_TOKEN:
        required: true
    outputs:
      deploy-url:
        description: "Deployment URL"
        value: ${{ jobs.deploy.outputs.url }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    outputs:
      url: ${{ steps.deploy.outputs.url }}
    steps:
      - name: Deploy
        id: deploy
        env:
          TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: |
          echo "Deploying ${{ inputs.image-tag }} to ${{ inputs.environment }}"
          echo "Replicas: ${{ inputs.replicas }}"
          echo "url=https://${{ inputs.environment }}.example.com" >> $GITHUB_OUTPUT

# .github/workflows/deploy.yml
name: Deploy Application

on:
  push:
    branches: [main]

jobs:
  deploy-staging:
    uses: ./.github/workflows/reusable-deploy.yml
    with:
      environment: staging
      image-tag: ${{ github.sha }}
      replicas: 2
    secrets:
      DEPLOY_TOKEN: ${{ secrets.STAGING_DEPLOY_TOKEN }}

  deploy-production:
    needs: deploy-staging
    uses: ./.github/workflows/reusable-deploy.yml
    with:
      environment: production
      image-tag: ${{ github.sha }}
      replicas: 5
    secrets:
      DEPLOY_TOKEN: ${{ secrets.PROD_DEPLOY_TOKEN }}

jobs:
  ci:
    uses: your-org/shared-workflows/.github/workflows/node-ci.yml@main
    with:
      node-version: '24'
    secrets: inherit    # 继承调用方的所有 secrets

- name: Cache Go modules
  uses: actions/cache@v4
  with:
    path: |
      ~/.cache/go-build
      ~/go/pkg/mod
    key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
    restore-keys: |
      ${{ runner.os }}-go-

# Node.js —— 缓存 npm/pnpm/yarn
- uses: actions/setup-node@v4
  with:
    node-version: 24
    cache: 'npm'           # 自动检测 lockfile 并缓存

# Java —— 缓存 Gradle/Maven
- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: 21
    cache: 'gradle'

# Python —— 缓存 pip/poetry/pipenv
- uses: actions/setup-python@v5
  with:
    python-version: '3.12'
    cache: 'pip'

# Go —— 使用 actions/cache
- uses: actions/cache@v4
  with:
    path: |
      ~/.cache/go-build
      ~/go/pkg/mod
    key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}

# Rust —— 缓存 cargo
- uses: Swatinem/rust-cache@v2

# 方式一：使用 GitHub Actions 缓存后端（推荐）
- uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    tags: my-app:latest
    cache-from: type=gha
    cache-to: type=gha,mode=max

# 方式二：使用 Registry 缓存
- uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    tags: my-app:latest
    cache-from: type=registry,ref=ghcr.io/my-app:buildcache
    cache-to: type=registry,ref=ghcr.io/my-app:buildcache,mode=max

# 方式三：使用本地缓存
- uses: actions/cache@v4
  with:
    path: /tmp/.buildx-cache
    key: ${{ runner.os }}-buildx-${{ github.sha }}
    restore-keys: ${{ runner.os }}-buildx-

- uses: docker/build-push-action@v6
  with:
    context: .
    cache-from: type=local,src=/tmp/.buildx-cache
    cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max

# 防止缓存无限增长
- run: rm -rf /tmp/.buildx-cache && mv /tmp/.buildx-cache-new /tmp/.buildx-cache

# 1. 最小权限原则
permissions:
  contents: read          # 仅读取代码
  # 不要写 permissions: write-all

# 2. Pin Action 版本（避免供应链攻击）
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1
  # 或至少用主版本号
  # uses: actions/checkout@v4

# 3. 不要在日志中暴露敏感信息
- name: Safe logging
  run: |
    echo "::add-mask::$MY_SECRET"     # 手动遮蔽
    echo "Token length: ${#MY_SECRET}" # 只打印长度

# 4. 在任务权限范围内使用 GITHUB_TOKEN（自动过期，按需授权）
- uses: actions/checkout@v4
  with:
    token: ${{ secrets.GITHUB_TOKEN }}

# 5. 验证第三方 Action 的来源
# 优先使用 GitHub 官方 Action 和知名组织的 Action

# 1. 使用 Job 级别的 timeout
jobs:
  build:
    timeout-minutes: 15

# 2. 合理使用 needs 做并行
jobs:
  lint:
    runs-on: ubuntu-latest
    steps: [...]
  test:
    runs-on: ubuntu-latest      # 和 lint 并行
    steps: [...]
  build:
    needs: [lint, test]         # lint 和 test 都完成后
    steps: [...]

# 3. 条件跳过不必要的 Job
jobs:
  deploy:
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    steps: [...]

# 4. 合并多个小 Step 减少启动开销
- name: Setup and test
  run: |
    npm ci
    npm run lint
    npm test
    npm run build

# 5. 使用 paths 过滤避免不必要的触发
on:
  push:
    paths: ['src/**', 'tests/**', 'package.json', 'package-lock.json']

# 1. 启用调试日志（在仓库 Settings > Secrets 中设置）
# ACTIONS_STEP_DEBUG = true
# ACTIONS_RUNNER_DEBUG = true

# 2. 使用 act 在本地测试（https://github.com/nektos/act）
# act -j build

# 3. 打印上下文信息
- name: Debug context
  env:
    GITHUB_CONTEXT: ${{ toJson(github) }}
    JOB_CONTEXT: ${{ toJson(job) }}
    STEPS_CONTEXT: ${{ toJson(steps) }}
    RUNNER_CONTEXT: ${{ toJson(runner) }}
  run: |
    echo "Event: ${{ github.event_name }}"
    echo "Ref: ${{ github.ref }}"
    echo "SHA: ${{ github.sha }}"
    echo "Actor: ${{ github.actor }}"
    echo "Runner OS: ${{ runner.os }}"

# 4. tmate 远程调试（暂停 Workflow 并提供 SSH 访问）
- name: Setup tmate session
  if: failure()                        # 仅在失败时启动
  uses: mxschmitt/action-tmate@v3
  # 或者用 workflow_dispatch 手动触发调试

# 1. 使用 paths 过滤
on:
  push:
    paths: ['src/**']    # 只有源码变更才触发

# 2. 及时取消过时的 Workflow
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true     # 同一分支的新提交会取消旧的运行

# 3. 使用小型 Runner（按需选择）
runs-on: ubuntu-latest          # Linux 最便宜
# runs-on: macos-latest        # 按当前 Runner 类型、套餐和计费表核价

# 4. 缓存依赖，减少安装时间
- uses: actions/setup-node@v4
  with:
    node-version: 24
    cache: 'npm'

# 5. 精简 CI 步骤
# - 跳过 lint 如果有本地 pre-commit hook
# - 只在 PR 时跑完整测试，push 时只跑核心测试

# 6. 合并多个小 Workflow
# - 避免同一个事件触发多个 Workflow
# - 使用 reusable workflow 减少重复配置

# 1. 使用 YAML 锚点减少重复（GitHub Actions 不原生支持，但可以用 reusable workflow 替代）

# 2. 统一 Action 版本管理（使用 Dependabot）
# .github/dependabot.yml
# version: 2
# updates:
#   - package-ecosystem: "github-actions"
#     directory: "/"
#     schedule:
#       interval: "weekly"

# 3. 使用 Matrix 测试多版本
strategy:
  matrix:
    node: [18, 20, 22]

# 4. 为每个 Job 设置有意义的 name
jobs:
  test:
    name: "Test (Node ${{ matrix.node }})"

# 5. 使用 Workflow 链接相关 PR
- name: Add PR comment
  if: github.event_name == 'pull_request'
  uses: actions/github-script@v7
  with:
    script: |
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: `[可用] Build passed! [View logs](${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId})`
      })

                  ┌─────────────┐
  用户请求 ───→  │  负载均衡器   │
                  └──────┬──────┘
                         │
              ┌──────────┴──────────┐
              ▼                     ▼
        ┌──────────┐          ┌──────────┐
        │  蓝(当前) │          │  绿(新)   │
        │  v1.2.3  │          │  v1.3.0  │
        └──────────┘          └──────────┘

  发布前：流量 → 蓝
  发布后：流量 → 绿（蓝保留作回滚）

# /etc/nginx/conf.d/blue-green.conf
upstream app {
    # 切换这一行即可完成蓝绿切换
    server 10.0.1.10:8080;  # 蓝环境
    # server 10.0.2.10:8080;  # 绿环境
}

server {
    listen 80;
    server_name www.example.com;

    location / {
        proxy_pass http://app;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

#!/bin/bash
# switch-env.sh - 蓝绿切换脚本
CURRENT=$(grep -oP 'server \K[\d.]+' /etc/nginx/conf.d/blue-green.conf)
BLUE="10.0.1.10"
GREEN="10.0.2.10"

if [ "$CURRENT" = "$BLUE" ]; then
    NEW_TARGET=$GREEN
    ENV_NAME="green"
else
    NEW_TARGET=$BLUE
    ENV_NAME="blue"
fi

# 预检：确认新环境健康
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://${NEW_TARGET}:8080/health)
if [ "$HTTP_CODE" != "200" ]; then
    echo " 新环境健康检查失败 (HTTP $HTTP_CODE)，中止切换"
    exit 1
fi

# 执行切换
sed -i "s/server ${CURRENT}:8080/server ${NEW_TARGET}:8080/" /etc/nginx/conf.d/blue-green.conf
nginx -t && nginx -s reload

echo "[可用] 已切换到 ${ENV_NAME} 环境 (${NEW_TARGET})"
echo "回滚命令: sed -i 's/${NEW_TARGET}/${CURRENT}/' /etc/nginx/conf.d/blue-green.conf && nginx -s reload"

# docker-compose.blue-green.yml

services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - app-blue
      - app-green

  app-blue:
    image: registry.example.com/myapp:${BLUE_VERSION:-1.2.3}
    environment:
      - NODE_ENV=production
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 10s
      timeout: 5s
      retries: 3

  app-green:
    image: registry.example.com/myapp:${GREEN_VERSION:-1.3.0}
    environment:
      - NODE_ENV=production
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 10s
      timeout: 5s
      retries: 3

# k8s/blue-green-deployment.yaml
# 蓝环境（当前版本）
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app-blue
  labels:
    app: myapp
    version: blue
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
      version: blue
  template:
    metadata:
      labels:
        app: myapp
        version: blue
    spec:
      containers:
        - name: app
          image: registry.example.com/myapp:1.2.3
          ports:
            - containerPort: 8080
          readinessProbe:
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 10
            periodSeconds: 5

---
# Service 通过 selector 切换蓝绿
apiVersion: v1
kind: Service
metadata:
  name: myapp
spec:
  selector:
    app: myapp
    version: blue  # 改成 green 即切换
  ports:
    - port: 80
      targetPort: 8080

# 切换到绿环境
kubectl patch service myapp -p '{"spec":{"selector":{"version":"green"}}}'

# 回滚到蓝环境
kubectl patch service myapp -p '{"spec":{"selector":{"version":"blue"}}}'

  流量分配:
  ┌────────────────────────────────────────┐
  │ ████████████████████████████░░░░ 90%  │  ← 旧版本 (stable)
  │ ████████░░░░░░░░░░░░░░░░░░░░ 10%  │  ← 新版本 (canary)
  └────────────────────────────────────────┘

  时间线:
  0% → 10% → 25% → 50% → 100%
  │      │      │      │      │
  观察   观察   观察   观察   全量发布
  15min  15min  15min  15min

# 基于权重的金丝雀
upstream app {
    server 10.0.1.10:8080 weight=90;  # 稳定版
    server 10.0.2.10:8080 weight=10;  # 金丝雀
}

# 基于 Header 的金丝雀（内部测试用户）
map $http_x_canary $backend {
    "true"  canary_backend;
    default stable_backend;
}

upstream stable_backend {
    server 10.0.1.10:8080;
}

upstream canary_backend {
    server 10.0.2.10:8080;
}

server {
    listen 80;
    location / {
        proxy_pass http://$backend;
    }
}

# 稳定版 Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app-stable
spec:
  replicas: 9
  selector:
    matchLabels:
      app: myapp
      track: stable
  template:
    metadata:
      labels:
        app: myapp
        track: stable
    spec:
      containers:
        - name: app
          image: registry.example.com/myapp:1.2.3

---
# 金丝雀 Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app-canary
spec:
  replicas: 1
  selector:
    matchLabels:
      app: myapp
      track: canary
  template:
    metadata:
      labels:
        app: myapp
        track: canary
    spec:
      containers:
        - name: app
          image: registry.example.com/myapp:1.3.0

---
# Service 同时匹配 stable 和 canary
apiVersion: v1
kind: Service
metadata:
  name: myapp
spec:
  selector:
    app: myapp  # 不含 track，匹配两者
  ports:
    - port: 80
      targetPort: 8080

# prometheus-rules.yaml
groups:
  - name: canary-monitoring
    rules:
      - alert: CanaryHighErrorRate
        expr: |
          sum(rate(http_requests_total{track="canary",status=~"5.."}[5m]))
          /
          sum(rate(http_requests_total{track="canary"}[5m]))
          > 0.05
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "金丝雀错误率超过 5%"
          description: "金丝雀版本错误率 {{ $value | humanizePercentage }}，建议回滚"

      - alert: CanaryHighLatency
        expr: |
          histogram_quantile(0.95,
            sum(rate(http_request_duration_seconds_bucket{track="canary"}[5m])) by (le)
          ) > 2
        for: 3m
        labels:
          severity: warning
        annotations:
          summary: "金丝雀 P95 延迟超过 2 秒"

#!/bin/bash
# canary-rollback.sh
ERROR_RATE=$(curl -s 'http://prometheus:9090/api/v1/query' \
  --data-urlencode 'query=sum(rate(http_requests_total{track="canary",status=~"5.."}[5m]))/sum(rate(http_requests_total{track="canary"}[5m]))' \
  | jq -r '.data.result[0].value[1]')

if (( $(echo "$ERROR_RATE > 0.05" | bc -l) )); then
    echo " 金丝雀错误率 ${ERROR_RATE}，执行回滚"
    kubectl scale deployment app-canary --replicas=0
    kubectl scale deployment app-stable --replicas=10
    echo "[可用] 回滚完成"
else
    echo "[可用] 金丝雀指标正常，错误率 ${ERROR_RATE}"
fi

# Flagger Canary 资源（适用于 Istio/Linkerd/Nginx Ingress）
apiVersion: flagger.app/v1beta1
kind: Canary
metadata:
  name: myapp
spec:
  targetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: myapp
  progressDeadlineSeconds: 600
  service:
    port: 80
  analysis:
    interval: 1m
    threshold: 5           # 最大失败次数
    maxWeight: 50          # 最大金丝雀权重
    stepWeight: 10         # 每次增加的权重
    metrics:
      - name: request-success-rate
        thresholdRange:
          min: 99          # 成功率 > 99%
        interval: 1m
      - name: request-duration
        thresholdRange:
          max: 500         # P99 < 500ms
        interval: 1m
    webhooks:
      - name: load-test
        type: rollout
        url: http://flagger-loadtester.test/
        metadata:
          cmd: "hey -z 1m -q 10 -c 2 http://myapp-canary.test/"

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 10
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 3        # 最多多出 3 个 Pod（13 个总 Pod）
      maxUnavailable: 1  # 最多 1 个 Pod 不可用（至少 9 个可用）
  # 等价于：一次更新 3 个 Pod，保证至少 9 个健康
  template:
    spec:
      containers:
        - name: app
          image: registry.example.com/myapp:1.3.0
          readinessProbe:
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 15
            periodSeconds: 5
            successThreshold: 1
            failureThreshold: 3
          livenessProbe:
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 30
            periodSeconds: 10

containers:
  - name: app
    # 启动探针：慢启动应用专用，避免 liveness 误杀
    startupProbe:
      httpGet:
        path: /health
        port: 8080
      failureThreshold: 30    # 最多等 30*5=150 秒
      periodSeconds: 5

    # 就绪探针：决定是否接收流量
    readinessProbe:
      httpGet:
        path: /ready
        port: 8080
      initialDelaySeconds: 5
      periodSeconds: 5
      successThreshold: 1
      failureThreshold: 3     # 连续 3 次失败则摘除

    # 存活探针：决定是否重启容器
    livenessProbe:
      httpGet:
        path: /health
        port: 8080
      initialDelaySeconds: 30
      periodSeconds: 10
      failureThreshold: 3     # 连续 3 次失败则重启

# 查看发布历史
kubectl rollout history deployment/myapp

# 回滚到上一版本
kubectl rollout undo deployment/myapp

# 回滚到指定版本
kubectl rollout undo deployment/myapp --to-revision=3

# 查看回滚状态
kubectl rollout status deployment/myapp --timeout=120s

# 暂停发布（发现异常时）
kubectl rollout pause deployment/myapp

# 恢复发布
kubectl rollout resume deployment/myapp

# GitLab CI 自动回滚
deploy:
  stage: deploy
  script:
    - kubectl apply -f k8s/
    - kubectl rollout status deployment/myapp --timeout=300s || {
        echo "部署超时，自动回滚";
        kubectl rollout undo deployment/myapp;
        kubectl rollout status deployment/myapp --timeout=120s;
        exit 1;
      }

版本号: MAJOR.MINOR.PATCH (如 1.3.2)
  MAJOR: 不兼容的 API 变更
  MINOR: 向后兼容的功能新增
  PATCH: 向后兼容的 Bug 修复

制品标签: v1.3.2 / v1.3.2-abc1234 (带 commit hash)

# [不适用] 避免使用 latest
docker build -t myapp:latest .

# [可用] 使用语义化版本 + commit hash
docker build -t myapp:v1.3.2 -t myapp:v1.3.2-abc1234 .

# CI 中自动生成标签
VERSION=$(git describe --tags --always)
docker build -t registry.example.com/myapp:${VERSION} .
docker push registry.example.com/myapp:${VERSION}

第 1 步：新增列（Additive only）→ 部署新代码
第 2 步：新代码同时读写新旧列 → 验证
第 3 步：新代码只读写新列 → 停止写旧列
第 4 步：删除旧列（在下个版本）

-- migration/V3__add_email_column.sql (向前)
ALTER TABLE users ADD COLUMN email VARCHAR(255);
UPDATE users SET email = CONCAT(username, '@example.com');
ALTER TABLE users ALTER COLUMN email SET NOT NULL;

-- rollback/V3__rollback_email_column.sql (回滚)
ALTER TABLE users DROP COLUMN IF EXISTS email;

#!/bin/bash
# rollback.sh - 生产快速回滚 SOP
set -euo pipefail

APP_NAME="${1:?用法: ./rollback.sh <app-name> [revision]}"
REVISION="${2:-}"

echo " 开始回滚 ${APP_NAME}"

# Step 1: 确认当前版本
echo "当前版本:"
kubectl get deployment ${APP_NAME} -o jsonpath='{.spec.template.spec.containers[0].image}'
echo ""

# Step 2: 执行回滚
if [ -n "$REVISION" ]; then
    kubectl rollout undo deployment/${APP_NAME} --to-revision=${REVISION}
else
    kubectl rollout undo deployment/${APP_NAME}
fi

# Step 3: 等待回滚完成
kubectl rollout status deployment/${APP_NAME} --timeout=180s

# Step 4: 验证
NEW_IMAGE=$(kubectl get deployment ${APP_NAME} -o jsonpath='{.spec.template.spec.containers[0].image}')
echo "[可用] 回滚完成，当前镜像: ${NEW_IMAGE}"

# Step 5: 检查 Pod 状态
kubectl get pods -l app=${APP_NAME} -o wide

# Step 6: 健康检查
for i in {1..5}; do
    STATUS=$(curl -s -o /dev/null -w "%{http_code}" https://www.example.com/health || true)
    if [ "$STATUS" = "200" ]; then
        echo " 健康检查通过"
        exit 0
    fi
    echo "等待健康检查... (${i}/5)"
    sleep 5
done
echo " 健康检查失败，请人工介入"
exit 1

# Docker Compose 部署 Nexus
services:
  nexus:
    image: sonatype/nexus3:3.68.0
    ports:
      - "8081:8081"
      - "8082:8082"  # Docker registry port
    volumes:
      - nexus-data:/nexus-data
    environment:
      - NEXUS_SECURITY_RANDOMPASSWORD=false

volumes:
  nexus-data:

# 登录
docker login nexus.example.com:8082

# 推送镜像
docker tag myapp:v1.3.0 nexus.example.com:8082/myapp:v1.3.0
docker push nexus.example.com:8082/myapp:v1.3.0

# CI 中使用
# .gitlab-ci.yml
build:
  stage: build
  script:
    - docker login -u $NEXUS_USER -p $NEXUS_PASS nexus.example.com:8082
    - docker build -t nexus.example.com:8082/myapp:${CI_COMMIT_TAG} .
    - docker push nexus.example.com:8082/myapp:${CI_COMMIT_TAG}

# Harbor 安装 (docker-compose)
# 下载 Harbor 离线安装包
wget https://github.com/goharbor/harbor/releases/download/v2.11.0/harbor-offline-installer-v2.11.0.tgz
tar xzf harbor-offline-installer-v2.11.0.tgz
cd harbor

# 编辑 harbor.yml
# hostname: harbor.example.com
# harbor_admin_password: StrongPassword123!
# database.password: dbpassword

./install.sh --with-trivy  # 启用漏洞扫描

# 创建项目
curl -u admin:password -X POST https://harbor.example.com/api/v2.0/projects \
  -H "Content-Type: application/json" \
  -d '{"project_name": "myteam", "public": false}'

# 配置镜像保留策略（保留最近 30 个 tag）
curl -u admin:password -X POST \
  "https://harbor.example.com/api/v2.0/projects/myteam/repositories/myapp/policies" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [{
      "template": "latestPushedK",
      "params": {"latestPushedK": 30},
      "tag_selectors": [{"kind": "wildcard", "decoration": "matches", "pattern": "**"}],
      "repo_selectors": [{"kind": "doublestar", "decoration": "matches", "pattern": "**"}]
    }]
  }'

# GitLab CI 制品版本管理
variables:
  IMAGE_REGISTRY: harbor.example.com/myteam
  IMAGE_TAG: ${CI_COMMIT_TAG:-${CI_COMMIT_SHORT_SHA}}

build:
  stage: build
  script:
    - docker build -t ${IMAGE_REGISTRY}/myapp:${IMAGE_TAG} .
    - docker push ${IMAGE_REGISTRY}/myapp:${IMAGE_TAG}
    # 额外推送 latest（仅 main 分支）
    - if [ "$CI_COMMIT_BRANCH" = "main" ]; then
        docker tag ${IMAGE_REGISTRY}/myapp:${IMAGE_TAG} ${IMAGE_REGISTRY}/myapp:latest;
        docker push ${IMAGE_REGISTRY}/myapp:latest;
      fi
  rules:
    - if: $CI_COMMIT_TAG
    - if: $CI_COMMIT_BRANCH == "main"

# 手动触发垃圾回收
curl -u admin:password -X POST \
  "https://harbor.example.com/api/v2.0/system/gc/schedule" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {"delete_untagged": true},
    "schedule": {"type": "Weekly", "weekday": 1, "offtime": 0}
  }'

db/migration/
  V1__create_users_table.sql
  V2__add_email_column.sql
  V3__create_orders_table.sql
  V4__add_index_on_email.sql

-- V1__create_users_table.sql
CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY,
    username VARCHAR(100) NOT NULL UNIQUE,
    email VARCHAR(255),
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- V2__add_email_column.sql
ALTER TABLE users ADD COLUMN phone VARCHAR(20);
CREATE INDEX idx_users_phone ON users(phone);

# GitLab CI 数据库迁移
db:migrate:
  stage: migrate
  image: flyway/flyway:10
  script:
    - flyway -url=jdbc:postgresql://${DB_HOST}:5432/${DB_NAME}
             -user=${DB_USER}
             -password=${DB_PASS}
             -locations=filesystem:./db/migration
             migrate
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      changes:
        - "db/migration/**/*"

db:info:
  stage: check
  image: flyway/flyway:10
  script:
    - flyway -url=jdbc:postgresql://${DB_HOST}:5432/${DB_NAME}
             -user=${DB_USER}
             -password=${DB_PASS}
             -locations=filesystem:./db/migration
             info

db:repair:
  stage: fix
  image: flyway/flyway:10
  script:
    - flyway -url=jdbc:postgresql://${DB_HOST}:5432/${DB_NAME}
             -user=${DB_USER}
             -password=${DB_PASS}
             repair
  when: manual

databaseChangeLog:
  - changeSet:
      id: 1
      author: devteam
      changes:
        - createTable:
            tableName: users
            columns:
              - column:
                  name: id
                  type: bigint
                  autoIncrement: true
                  constraints:
                    primaryKey: true
                    nullable: false
              - column:
                  name: username
                  type: varchar(100)
                  constraints:
                    nullable: false
                    unique: true
      rollback:
        - dropTable:
            tableName: users

  - changeSet:
      id: 2
      author: devteam
      changes:
        - addColumn:
            tableName: users
            columns:
              - column:
                  name: phone
                  type: varchar(20)
        - createIndex:
            tableName: users
            indexName: idx_users_phone
            columns:
              - column:
                  name: phone
      rollback:
        - dropIndex:
            tableName: users
            indexName: idx_users_phone
        - dropColumn:
            tableName: users
            columnName: phone

代码合并 → CI 构建镜像 → 先跑 DB Migration → 再部署应用 → 健康检查
                          ↑ 数据库变更先于应用部署

# GitLab CI 集成 Semgrep
sast:
  stage: security
  image: returntocorp/semgrep
  script:
    - semgrep --config=auto --json --output=semgrep-results.json .
  artifacts:
    reports:
      sast: semgrep-results.json
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == "main"

# GitLab CI 集成 Trivy 扫描依赖漏洞
dependency-scan:
  stage: security
  image: aquasec/trivy:latest
  script:
    - trivy fs --format json --output trivy-results.json --severity HIGH,CRITICAL .
    - trivy fs --exit-code 1 --severity CRITICAL .  # 高危漏洞直接失败
  artifacts:
    reports:
      dependency_scanning: trivy-results.json

# Docker 镜像漏洞扫描
image-scan:
  stage: security
  image: aquasec/trivy:latest
  script:
    - trivy image --exit-code 1 --severity CRITICAL ${IMAGE_REGISTRY}/myapp:${CI_COMMIT_TAG}

# 集成 OWASP ZAP
dast:
  stage: security
  image: ghcr.io/zaproxy/zaproxy:stable
  script:
    - zap-baseline.py -t https://staging.example.com -r zap-report.html
  artifacts:
    paths:
      - zap-report.html
    when: always
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

# GitLab CI 多级审批
deploy:staging:
  stage: deploy
  environment:
    name: staging
  script:
    - ./deploy.sh staging
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

deploy:prod:
  stage: deploy
  environment:
    name: production
    deployment_tier: production
  script:
    - ./deploy.sh production
  rules:
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
  when: manual
  allow_failure: false

# GitLab Protected Environment 审批
# Settings → CI/CD → Protected Environments
# 添加 production 环境保护
# 允许部署的角色: Maintainer
# 所需审批人数: 2