如何结合Docker与GitLab CI高效管理.NET Web API多环境配置？

基于你现有appsettings.json和docker-compose.yml的基础，推荐采用**「.NET原生配置分层 + Docker Compose覆盖文件 + GitLab CI环境变量」**的组合方案，既能兼顾本地开发的便捷性，又能满足CI自动化部署的安全性与可维护性。

一、本地开发阶段：最小改动实现环境快速切换 #

1. .NET配置分层复用
   保留appsettings.json存放通用配置（如日志基础规则、跨域设置），新增appsettings.{Environment}.json存放环境专属配置（如数据库连接串、API密钥）。.NET会自动根据ASPNETCORE_ENVIRONMENT环境变量加载对应文件，优先级为：环境变量 > 环境专属配置文件 > 通用配置文件。

   • 示例appsettings.Development.json：

     {
       "ConnectionStrings": {
         "DefaultConnection": "Server=localhost;Database=DevDB;Trusted_Connection=True;"
       },
       "Logging": {
         "LogLevel": {
           "Default": "Debug"
         }
       }
     }
     

2. Docker Compose覆盖文件简化切换
   保留基础docker-compose.yml定义通用服务结构，为各环境创建独立的覆盖文件（如docker-compose.dev.yml、docker-compose.test.yml），仅存放对应环境的差异化配置（镜像标签、端口映射、重启策略等）。

   • 示例docker-compose.prod.yml：

     version: '3.8'
     services:
       webapi:
         image: your-registry/webapi:prod-${CI_COMMIT_SHORT_SHA}
         environment:
           - ASPNETCORE_ENVIRONMENT=Production
         ports:
           - "80:80"
         restart: always
     

   • 本地切换环境命令示例：

     # 启动测试环境
     docker-compose -f docker-compose.yml -f docker-compose.test.yml up -d
     

3. 本地敏感信息管理
   创建.env文件（添加到.gitignore）存放本地开发用的敏感变量，避免硬编码：

   ASPNETCORE_ENVIRONMENT=Development
   DB_CONNECTION_STRING=Server=localhost;Database=DevDB;Trusted_Connection=True;
   

二、GitLab CI部署阶段：安全自动化的环境配置交付 #

1. GitLab CI变量配置 #

在项目「设置→CI/CD→变量」中，为dev、test、prod环境分别创建变量组，开启保护变量和掩码变量确保敏感信息安全：

• Dev组：DB_CONN_DEV、API_KEY_DEV
• Test组：DB_CONN_TEST、API_KEY_TEST
• Prod组：DB_CONN_PROD、API_KEY_PROD

2. GitLab CI脚本示例（.gitlab-ci.yml） #

stages:
  - build
  - deploy-dev
  - deploy-test
  - deploy-prod

# 通用构建阶段
build:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker build -t your-registry/webapi:$CI_COMMIT_SHORT_SHA .
    - docker push your-registry/webapi:$CI_COMMIT_SHORT_SHA
  only:
    - main
    - develop

# 自动部署开发环境
deploy-dev:
  stage: deploy-dev
  image: docker/compose:latest
  services:
    - docker:dind
  variables:
    ASPNETCORE_ENVIRONMENT: Development
    DB_CONNECTION_STRING: $DB_CONN_DEV
    API_KEY: $API_KEY_DEV
  script:
    - docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d
  only:
    - develop

# 手动触发部署测试环境
deploy-test:
  stage: deploy-test
  image: docker/compose:latest
  services:
    - docker:dind
  variables:
    ASPNETCORE_ENVIRONMENT: Test
    DB_CONNECTION_STRING: $DB_CONN_TEST
    API_KEY: $API_KEY_TEST
  script:
    - docker-compose -f docker-compose.yml -f docker-compose.test.yml up -d
  only:
    - main
  when: manual

# 手动审批部署生产环境
deploy-prod:
  stage: deploy-prod
  image: docker/compose:latest
  services:
    - docker:dind
  variables:
    ASPNETCORE_ENVIRONMENT: Production
    DB_CONNECTION_STRING: $DB_CONN_PROD
    API_KEY: $API_KEY_PROD
  script:
    - docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
  only:
    - main
  when: manual
  environment:
    name: production
    url: https://your-prod-domain.com
    on_stop: stop-prod

# 可选：停止生产环境服务
stop-prod:
  stage: deploy-prod
  image: docker/compose:latest
  services:
    - docker:dind
  script:
    - docker-compose -f docker-compose.yml -f docker-compose.prod.yml down
  when: manual
  environment:
    name: production
    action: stop

三、关键配置细节 #

1. .NET配置读取优先级
   在Program.cs中明确配置加载顺序，确保环境变量优先级最高，覆盖配置文件：

   var builder = WebApplication.CreateBuilder(args);
   builder.Configuration
       .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
       .AddJsonFile($"appsettings.{builder.Environment.EnvironmentName}.json", optional: true)
       .AddEnvironmentVariables(); // 关键：环境变量优先级高于配置文件
   

2. Docker Compose变量传递
   在基础docker-compose.yml中定义环境变量占位符，由CI或本地.env填充：

   services:
     webapi:
       build: .
       environment:
         - ASPNETCORE_ENVIRONMENT=${ASPNETCORE_ENVIRONMENT}
         - ConnectionStrings__DefaultConnection=${DB_CONNECTION_STRING}
         - ApiSettings__ApiKey=${API_KEY}
   

内容的提问来源于stack exchange，提问作者Lan Lin