common-workflows/docs/deploy-docker.md

# WorkFlows —— Deploy-docker.yaml调用示例

### 示例 1: 基本部署（broccoli-api offline 分支）

```yaml
# .gitea/workflows/deploy-offline.yml
name: Deploy Offline Branch

on:
  push:
    branches:
      - offline
  workflow_dispatch:

jobs:
  deploy:
    uses: your-org/common-workflows/.gitea/workflows/reusable-docker-deploy.yml@main
    with:
      compose_file: 'docker-compose-offline.yml'
      checkout_ref: 'offline'
      enable_sparse_checkout: true
      sparse_checkout: |
        .gitea/
        config/
        docker-compose-offline.yml        
      cleanup_containers: true
```

### 示例 2: 完整部署（包含数据导入）

```yaml
# .gitea/workflows/deploy.yml
name: Deploy Services

on:
  workflow_dispatch:

jobs:
  deploy:
    uses: your-org/common-workflows/.gitea/workflows/reusable-docker-deploy.yml@main
    with:
      compose_file: 'docker-compose.yml'
      startup_wait: 30
      run_importer: true
      importer_service: 'importer'
      cleanup_containers: true
      cleanup_volumes: false
```

### 示例 3: 带环境变量的部署

```yaml
# .gitea/workflows/deploy-prod.yml
name: Deploy Production

on:
  workflow_dispatch:

jobs:
  deploy:
    uses: your-org/common-workflows/.gitea/workflows/reusable-docker-deploy.yml@main
    with:
      compose_file: 'docker-compose.prod.yml'
      checkout_ref: 'main'
      env_vars: |
        ENVIRONMENT=production
        LOG_LEVEL=info
        ENABLE_METRICS=true        
      startup_wait: 60
```

### 示例 4: 子目录 Compose 文件

```yaml
# .gitea/workflows/deploy-services.yml
name: Deploy Microservices

on:
  workflow_dispatch:

jobs:
  deploy:
    uses: your-org/common-workflows/.gitea/workflows/reusable-docker-deploy.yml@main
    with:
      compose_file: 'services/docker-compose.yml'
      compose_dir: 'services'
      enable_sparse_checkout: true
      sparse_checkout: |
        services/        
      cleanup_containers: true
```

### 示例 5: 多环境部署

```yaml
# .gitea/workflows/deploy-multi-env.yml
name: Deploy Multiple Environments

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        type: choice
        options:
          - dev
          - staging
          - prod

jobs:
  deploy-dev:
    if: ${{ github.event.inputs.environment == 'dev' }}
    uses: your-org/common-workflows/.gitea/workflows/reusable-docker-deploy.yml@main
    with:
      compose_file: 'docker-compose.dev.yml'
      checkout_ref: 'develop'
      cleanup_containers: true

  deploy-staging:
    if: ${{ github.event.inputs.environment == 'staging' }}
    uses: your-org/common-workflows/.gitea/workflows/reusable-docker-deploy.yml@main
    with:
      compose_file: 'docker-compose.staging.yml'
      checkout_ref: 'staging'
      startup_wait: 30
      cleanup_containers: true

  deploy-prod:
    if: ${{ github.event.inputs.environment == 'prod' }}
    uses: your-org/common-workflows/.gitea/workflows/reusable-docker-deploy.yml@main
    with:
      compose_file: 'docker-compose.prod.yml'
      checkout_ref: 'main'
      startup_wait: 60
      run_importer: true
      cleanup_containers: true
```

### 示例 6: 完整的构建+部署流程

```yaml
# .gitea/workflows/ci-cd.yml
name: Build and Deploy

on:
  push:
    branches:
      - offline
  workflow_dispatch:

jobs:
  build:
    uses: your-org/common-workflows/.gitea/workflows/reusable-docker-build.yml@main
    with:
      dockerfile: 'Dockerfile.api'
      context: '.'
      image_name: 'broccoli-api'
      image_tag: 'v3.2.1'
      checkout_ref: 'offline'

  deploy:
    needs: build
    uses: your-org/common-workflows/.gitea/workflows/reusable-docker-deploy.yml@main
    with:
      compose_file: 'docker-compose-offline.yml'
      checkout_ref: 'offline'
      enable_sparse_checkout: true
      sparse_checkout: |
        .gitea/
        config/
        docker-compose-offline.yml        
      startup_wait: 30
      run_importer: true
      cleanup_containers: true
```

### 示例 7: 仅部署特定服务

```yaml
# .gitea/workflows/deploy-api-only.yml
name: Deploy API Service Only

on:
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Deploy API
        run: |
          docker compose -f docker-compose.yml up -d api
                    
      # 或者调用可复用工作流处理完整流程
```

## 核心特性

✅ **灵活配置** - 支持任意 Compose 文件路径和工作目录  
✅ **稀疏检出** - 可选的稀疏检出节省空间和时间  
✅ **资源清理** - 可控的容器和卷清理  
✅ **数据导入** - 支持一次性导入任务  
✅ **环境变量** - 支持传递部署时环境变量  
✅ **服务验证** - 自动检查服务状态并显示失败日志  
✅ **超时控制** - 可配置停止和启动等待时间  
✅ **详细日志** - 完整的部署过程和服务日志  

这样你就有了两个专注、可复用的工作流：
1. `reusable-docker-build.yml` - 专注于镜像构建
2. `reusable-docker-deploy.yml` - 专注于容器编排部署

两者可以独立使用，也可以组合成完整的 CI/CD 流程！