配置说明

概述

EnderRealmServerCore 支持两种配置来源，按优先级从高到低：

1. 环境变量 - 优先级最高
2. config.yml 文件 - 次优先级

配置优先级：环境变量 > config.yml > 默认值

config.yml 配置文件

配置文件位于 plugins/EnderRealmServerCore/config.yml，首次启动时自动生成。

# EnderRealmServerCore 配置文件

# 日志配置（可选，不填则自动根据环境设置）
log:
  level: ""  # TRACE | DEBUG | INFO | WARN | ERROR，留空则自动

# Backend API 配置
backend:
  url: "http://localhost:8000"           # API 服务地址
  connect-timeout: 5000                   # 连接超时（毫秒）
  request-timeout: 10000                  # 请求超时（毫秒）
  max-retries: 3                          # 最大重试次数

# 环境配置
environment:
  fallback: "development"                 # API 服务不可用时的默认环境

# 服务器信息（可选，覆盖 API 服务返回值）
server:
  name: ""                                # 服务器名称，留空则使用 API 服务返回值
  region: ""                              # 服务器区域，留空则使用 API 服务返回值

配置项说明

日志配置 (log)

配置项	类型	默认值	说明
log.level	string	""	日志级别，留空则自动根据环境设置

自动级别映射：

• development → DEBUG（显示所有）
• staging → INFO
• production → WARN（只显示警告和错误）

Backend 配置 (backend)

配置项	类型	默认值	说明
backend.url	string	"http://localhost:8000"	API 服务地址
backend.connect-timeout	int	5000	连接超时（毫秒）
backend.request-timeout	int	10000	请求超时（毫秒）
backend.max-retries	int	3	最大重试次数

环境配置 (environment)

配置项	类型	默认值	说明
environment.fallback	string	"development"	API 服务不可用时的默认环境

可选值： production、staging、development

服务器信息 (server)

配置项	类型	默认值	说明
server.name	string	""	服务器名称，留空则使用 API 服务返回值
server.region	string	""	服务器区域，留空则使用 API 服务返回值

环境变量

环境变量优先级高于 config.yml，键名转换规则：

config.yml 键 → 环境变量名

backend.url        → BACKEND_URL
backend.timeout    → BACKEND_TIMEOUT
environment.fallback → ENVIRONMENT_FALLBACK
log.level          → LOG_LEVEL

转换规则：将点分隔的键转换为大写下划线格式。

Backend 环境变量

API 服务使用以下环境变量：

环境变量	必需	说明
ENVIRONMENT	是	当前环境：production、staging、development
SERVER_NAME	否	服务器名称
SERVER_REGION	否	服务器区域
CONFIG_*	否	自定义配置（自动收集所有 CONFIG_ 前缀的变量）

示例

# 设置环境
export ENVIRONMENT=production
export SERVER_NAME=EnderRealm-01
export SERVER_REGION=cn-east

# 自定义配置
export CONFIG_MAX_PLAYERS=100
export CONFIG_MOTD=Welcome to EnderRealm

# 启动 API 服务
uv run uvicorn app.main:app --reload

配置优先级

配置查找顺序（从高到低）：

1. 环境变量 - 最高优先级
2. config.yml 文件 - 次优先级
3. 代码默认值 - 最低优先级

示例：

// 假设环境变量 BACKEND_URL=https://prod.enderrealm.cn
// 假设 config.yml 中 backend.url=http://localhost:8000

ConfigManager config = ...;
String url = config.getString("backend.url", "http://default.enderrealm.cn");

// 结果：https://prod.enderrealm.cn（环境变量优先）

配置热重载

当前版本不支持配置热重载，修改配置后需要重启服务器。

配置验证

配置文件会在启动时自动验证：

• 无效的日志级别会被忽略，使用自动级别
• 无效的超时/重试值会使用默认值
• Backend 地址格式错误会在首次请求时报错

完整配置示例

生产环境 config.yml

log:
  level: "WARN"

backend:
  url: "https://api.enderrealm.cn"
  connect-timeout: 3000
  request-timeout: 5000
  max-retries: 5

environment:
  fallback: "production"

server:
  name: "EnderRealm-01"
  region: "cn-east"

开发环境 config.yml

log:
  level: "DEBUG"

backend:
  url: "http://localhost:8000"
  connect-timeout: 10000
  request-timeout: 30000
  max-retries: 1

environment:
  fallback: "development"

server:
  name: "Dev-Server"
  region: "local"