dramaling-vocab-learning/backend/DramaLing.Api/Configuration/README.md

配置管理說明

概述

DramaLing API 使用 ASP.NET Core 標準配置系統，支援多環境配置、環境變數覆蓋、強型別配置驗證。

配置文件結構

Configuration/
├── README.md                        # 本文檔
├── appsettings.json                 # 主要配置檔案
├── appsettings.Development.json     # 開發環境配置
├── appsettings.Production.json      # 生產環境配置 (未建立)
├── appsettings.OptionsVocabulary.json # 詞彙選項配置
└── [Models/Configuration/]          # 強型別配置類別
    ├── GeminiOptions.cs            # Gemini 配置
    └── GeminiOptionsValidator.cs   # Gemini 配置驗證器

環境變數優先級

配置來源優先級 (由高到低)：

1. 環境變數
2. appsettings.{Environment}.json
3. appsettings.json
4. 預設值

核心配置項目

資料庫連接

{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=dramaling.db"
  }
}

環境變數覆蓋：

• DRAMALING_DB_CONNECTION - 資料庫連接字串
• USE_INMEMORY_DB=true - 使用記憶體資料庫

Gemini AI 配置

{
  "Gemini": {
    "ApiKey": "your-gemini-api-key",
    "Model": "gemini-1.5-flash",
    "BaseUrl": "https://generativelanguage.googleapis.com/v1beta/models/",
    "MaxTokens": 2048,
    "Temperature": 0.1,
    "TopP": 0.95,
    "TopK": 64,
    "Timeout": 30
  }
}

環境變數覆蓋：

• DRAMALING_GEMINI_API_KEY - Gemini API 金鑰
• DRAMALING_GEMINI_MODEL - 模型名稱

Supabase 認證配置

{
  "Supabase": {
    "Url": "https://your-project.supabase.co",
    "JwtSecret": "your-jwt-secret"
  }
}

環境變數覆蓋：

• DRAMALING_SUPABASE_URL - Supabase 專案 URL
• DRAMALING_SUPABASE_JWT_SECRET - JWT 密鑰

Replicate 服務配置

{
  "Replicate": {
    "ApiKey": "your-replicate-api-key",
    "BaseUrl": "https://api.replicate.com/v1/",
    "DefaultModel": "black-forest-labs/flux-schnell",
    "Timeout": 300
  }
}

環境變數覆蓋：

• DRAMALING_REPLICATE_API_KEY - Replicate API 金鑰

Azure Speech 服務配置

{
  "AzureSpeech": {
    "SubscriptionKey": "your-azure-speech-key",
    "Region": "eastus",
    "Language": "en-US",
    "Voice": "en-US-JennyNeural"
  }
}

環境變數覆蓋：

• DRAMALING_AZURE_SPEECH_KEY - Azure Speech 金鑰
• DRAMALING_AZURE_SPEECH_REGION - Azure Speech 區域

強型別配置

GeminiOptions 配置類別

public class GeminiOptions
{
    public const string SectionName = "Gemini";

    public string ApiKey { get; set; } = string.Empty;
    public string Model { get; set; } = "gemini-1.5-flash";
    public string BaseUrl { get; set; } = "https://generativelanguage.googleapis.com/v1beta/models/";
    public int MaxTokens { get; set; } = 2048;
    public double Temperature { get; set; } = 0.1;
    public double TopP { get; set; } = 0.95;
    public int TopK { get; set; } = 64;
    public int Timeout { get; set; } = 30;
}

配置驗證

public class GeminiOptionsValidator : IValidateOptions<GeminiOptions>
{
    public ValidateOptionsResult Validate(string name, GeminiOptions options)
    {
        var failures = new List<string>();

        if (string.IsNullOrWhiteSpace(options.ApiKey))
            failures.Add("Gemini API Key is required");

        if (options.MaxTokens <= 0)
            failures.Add("MaxTokens must be greater than 0");

        return failures.Count > 0
            ? ValidateOptionsResult.Fail(failures)
            : ValidateOptionsResult.Success;
    }
}

配置註冊

在 ServiceCollectionExtensions.cs 中：

public static IServiceCollection AddAIServices(this IServiceCollection services, IConfiguration configuration)
{
    // 強型別配置
    services.Configure<GeminiOptions>(configuration.GetSection(GeminiOptions.SectionName));
    services.AddSingleton<IValidateOptions<GeminiOptions>, GeminiOptionsValidator>();

    // 其他服務註冊...
    return services;
}

環境配置最佳實踐

開發環境 (appsettings.Development.json)

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information"
    }
  },
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=dramaling_dev.db"
  }
}

生產環境配置原則

1. 敏感資料: 全部使用環境變數
2. 連接逾時: 增加逾時設定
3. 日誌等級: 設為 Warning 或 Error
4. 快取設定: 啟用分散式快取

Docker Compose 環境變數

version: '3.8'
services:
  dramaling-api:
    image: dramaling-api
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
      - DRAMALING_DB_CONNECTION=Server=db;Database=dramaling;Uid=root;Pwd=password
      - DRAMALING_GEMINI_API_KEY=${GEMINI_API_KEY}
      - DRAMALING_SUPABASE_URL=${SUPABASE_URL}
      - DRAMALING_SUPABASE_JWT_SECRET=${SUPABASE_JWT_SECRET}
      - DRAMALING_REPLICATE_API_KEY=${REPLICATE_API_KEY}

配置安全性

敏感資料保護

1. 永不提交: 敏感配置不可提交到版本控制
2. 環境變數: 生產環境使用環境變數
3. Azure Key Vault: 考慮使用 Azure Key Vault
4. 加密: 敏感配置在傳輸和儲存時加密

.gitignore 設定

# 敏感配置文件
appsettings.Production.json
appsettings.*.local.json
*.secrets.json

# 環境變數文件
.env
.env.local
.env.production

配置驗證

啟動時驗證

public static void Main(string[] args)
{
    var builder = WebApplication.CreateBuilder(args);

    // 配置驗證
    builder.Services.AddOptions<GeminiOptions>()
           .Bind(builder.Configuration.GetSection(GeminiOptions.SectionName))
           .ValidateDataAnnotations()
           .ValidateOnStart();

    var app = builder.Build();
    app.Run();
}

健康檢查整合

builder.Services.AddHealthChecks()
                .AddCheck<ConfigurationHealthCheck>("configuration");

故障排除

常見問題

1. 配置未載入: 檢查檔案名稱和環境變數
2. 環境變數無效: 確認變數名稱正確
3. 強型別配置失敗: 檢查配置驗證器

偵錯配置

// 在 Program.cs 中加入偵錯輸出
var configuration = builder.Configuration;
Console.WriteLine($"Environment: {builder.Environment.EnvironmentName}");
Console.WriteLine($"Gemini API Key: {configuration["Gemini:ApiKey"]}");

---

版本: 1.0 建立日期: 2025-09-30 維護者: DramaLing 開發團隊