项目配置说明

当你需要切换环境、排查“本地能跑线上不行”、或要把某个组件（Redis/MinIO 等）正确接入时，优先查这篇。

本文介绍 youlai-aspnet 的配置体系，你将了解：

• 多环境配置与环境变量的使用方式
• .NET 配置加载优先级
• 核心组件的常用配置项与注意事项

多环境配置

配置文件结构：

src/Youlai.Api/
├── appsettings.json            # 主配置文件（公共配置）
├── appsettings.Development.json # 开发环境配置
└── appsettings.Production.json  # 生产环境配置

配置文件加载优先级：

.NET 配置加载遵循 外层覆盖内层、特定覆盖通用 的原则：

优先级	配置来源	示例
1	命令行参数	--urls=http://localhost:8000
2	环境变量	Database__ConnectionString=...
3	appsettings.{Environment}.json	appsettings.Production.json
4	appsettings.json	公共配置

激活环境配置：

方式一：环境变量激活（推荐生产环境）

# Linux/Mac
export ASPNETCORE_ENVIRONMENT=Production

# Windows PowerShell
$env:ASPNETCORE_ENVIRONMENT="Production"

# Docker
docker run -e ASPNETCORE_ENVIRONMENT=Production youlai-aspnet

方式二：命令行激活

dotnet run --environment Production

配置覆盖策略：

• appsettings.json 定义所有默认值
• appsettings.{Environment}.json 只需覆盖变化的配置项
• 环境变量可覆盖任意配置项

数据库配置

"Database": {
  "ConnectionString": "Server=localhost;Port=3306;Database=youlai_admin;User=root;Password=123456;CharSet=utf8mb4;"
}

参数	说明
Server	MySQL 服务器地址
Port	MySQL 端口
Database	数据库名称
User	用户名
Password	密码

Redis 配置

"Redis": {
  "ConnectionString": "localhost:6379,password=,defaultDatabase=0"
}

参数	说明
ConnectionString	Redis 连接字符串

JWT 配置

"Security": {
  "Session": {
    "Jwt": {
      "SecretKey": "your-secret-key-at-least-32-characters-long",
      "Issuer": "youlai-aspnet",
      "AccessTokenTTL": 7200,
      "RefreshTokenTTL": 604800
    }
  }
}

参数	说明	默认值
SecretKey	JWT 签名密钥（至少 32 字符）	-
Issuer	Token 签发者	youlai-aspnet
AccessTokenTTL	访问令牌有效期（秒）	7200（2 小时）
RefreshTokenTTL	刷新令牌有效期（秒）	604800（7 天）

文件存储配置

"Oss": {
  "Type": "local",
  "Local": {
    "StoragePath": "/data/upload",
    "BaseUrl": "http://localhost:8000"
  },
  "Minio": {
    "Endpoint": "localhost:9000",
    "AccessKey": "minioadmin",
    "SecretKey": "minioadmin",
    "Bucket": "youlai"
  },
  "Aliyun": {
    "Endpoint": "oss-cn-hangzhou.aliyuncs.com",
    "AccessKeyId": "your-key",
    "AccessKeySecret": "your-secret",
    "Bucket": "youlai"
  }
}

参数	说明
Type	存储类型：local / minio / aliyun
Local.*	本地存储配置
Minio.*	MinIO 对象存储配置
Aliyun.*	阿里云 OSS 配置

限流配置

"RateLimit": {
  "Enabled": true,
  "PermitLimit": 100,
  "Window": 60
}

参数	说明
Enabled	是否启用限流
PermitLimit	时间窗口内允许的最大请求数
Window	时间窗口（秒）

日志配置

"Logging": {
  "LogLevel": {
    "Default": "Information",
    "Microsoft.AspNetCore": "Warning",
    "Microsoft.EntityFrameworkCore": "Warning"
  }
}

参数	说明
Default	默认日志级别
Microsoft.AspNetCore	ASP.NET Core 框架日志级别
Microsoft.EntityFrameworkCore	EF Core 日志级别

Kestrel 配置

"Kestrel": {
  "Endpoints": {
    "Http": {
      "Url": "http://*:8000"
    }
  }
}

参数	说明
Url	监听地址和端口

环境变量覆盖

生产环境可通过环境变量覆盖配置：

环境变量	对应配置
Database__ConnectionString	数据库连接字符串
Redis__ConnectionString	Redis 连接字符串
Security__Session__Jwt__SecretKey	JWT 密钥
Oss__Type	存储类型

示例：

export Database__ConnectionString="Server=prod-mysql;Port=3306;Database=youlai_admin;User=prod_user;Password=prod_password"
export Security__Session__Jwt__SecretKey="your-production-secret-key"

配置类映射

配置通过 Options 模式映射到强类型：

// Options/JwtOptions.cs
public class JwtOptions
{
    public string SecretKey { get; set; } = string.Empty;
    public string Issuer { get; set; } = "youlai-aspnet";
    public int AccessTokenTTL { get; set; } = 7200;
    public int RefreshTokenTTL { get; set; } = 604800;
}

// Program.cs
builder.Services.Configure<JwtOptions>(
    builder.Configuration.GetSection("Security:Session:Jwt"));

相关文件

文件	说明
appsettings.json	基础配置
appsettings.Development.json	开发环境配置
appsettings.Production.json	生产环境配置
Options/*.cs	Options 类定义