配置文件

EnerOS 使用 TOML 格式的 eneros.toml 作为主配置文件。本节给出完整的配置示例，并对所有 section 与字段进行详解，同时介绍环境变量覆盖、多环境配置策略、配置验证、热加载与敏感信息管理等进阶用法。

完整配置示例

下面是一份涵盖所有 section 的完整配置示例：

# ============================================================
# EnerOS 主配置文件
# ============================================================

[server]
host = "0.0.0.0"
port = 8080
workers = 4
max_connections = 10000
request_timeout_s = 30
cors_origins = ["*"]

[database]
path = "data/eneros.db"
journal_mode = "wal"
cache_size_mb = 256
migrate_on_start = true

[security]
tls_enabled = false
cert_path = "certs/server.crt"
key_path = "certs/server.key"
ca_path = "certs/ca.crt"
mtls_required = false
auth_token_ttl_minutes = 60

[agent]
max_agents = 100
default_memory_size = 1024
llm_endpoint = "http://localhost:11434"
llm_model = "eneros-llm-7b"
llm_timeout_s = 30
default_max_iterations = 20

[powerflow]
default_method = "newton-raphson"
tolerance = 1e-8
max_iterations = 20
flat_start = false
q_limit_check = true
tap_adjust = true

[topology]
auto_validate = true
strict_mode = false
cache_ttl_s = 300

[gateway]
enabled = false
listen_port = 8443
heartbeat_interval_ms = 1000
max_clients = 100

[timeseries]
retention_days = 365
batch_size = 1000
flush_interval_ms = 100
compression = "zstd"

[observability]
log_level = "info"
log_format = "json"
metrics_enabled = true
metrics_port = 9090
tracing_enabled = false
tracing_endpoint = "http://localhost:4317"

[multi_tenant]
enabled = false
default_tenant = "default"
isolation_mode = "schema"

[realtime]
enabled = false
priority = 80
cpu_affinity = [2, 3]
isolated_cpus = true

配置项详解

[server] 服务器配置

控制 API 服务器的监听与并发行为。

参数	类型	默认值	说明
`host`	string	`0.0.0.0`	监听地址
`port`	integer	`8080`	监听端口
`workers`	integer	`4`	工作线程数，建议等于 CPU 核数
`max_connections`	integer	`10000`	最大并发连接数
`request_timeout_s`	integer	`30`	请求超时（秒）
`cors_origins`	array	`["*"]`	允许的跨域来源，`["*"]` 表示全部

[server]
host = "127.0.0.1"      # 仅本机访问
port = 8080
workers = 8
max_connections = 50000
request_timeout_s = 60
cors_origins = ["https://eneros.example.com", "https://dashboard.example.com"]

[database] 数据库配置

控制 SQLite 内核存储引擎。

参数	类型	默认值	说明
`path`	string	`data/eneros.db`	SQLite 数据库文件路径
`journal_mode`	string	`wal`	日志模式（wal/delete/truncate/memory）
`cache_size_mb`	integer	`256`	SQLite 缓存大小（MB）
`migrate_on_start`	boolean	`true`	启动时自动执行数据库迁移

[database]
path = "/var/lib/eneros/data.db"
journal_mode = "wal"
cache_size_mb = 1024
migrate_on_start = true

[security] 安全配置

控制 TLS、mTLS 与认证。

参数	类型	默认值	说明
`tls_enabled`	boolean	`false`	是否启用 TLS
`cert_path`	string	`certs/server.crt`	服务器证书路径
`key_path`	string	`certs/server.key`	服务器私钥路径
`ca_path`	string	`certs/ca.crt`	CA 证书路径（mTLS 时验证客户端）
`mtls_required`	boolean	`false`	是否强制双向 TLS
`auth_token_ttl_minutes`	integer	`60`	认证 token 有效期（分钟）

[security]
tls_enabled = true
cert_path = "/etc/eneros/certs/server.crt"
key_path = "/etc/eneros/certs/server.key"
ca_path = "/etc/eneros/certs/ca.crt"
mtls_required = true
auth_token_ttl_minutes = 30

[agent] Agent 配置

控制 Agent 运行时与 LLM 推理后端。

参数	类型	默认值	说明
`max_agents`	integer	`100`	最大并发 Agent 数量
`default_memory_size`	integer	`1024`	默认记忆容量（条数）
`llm_endpoint`	string	-	LLM 推理服务端点
`llm_model`	string	`eneros-llm-7b`	默认 LLM 模型名称
`llm_timeout_s`	integer	`30`	LLM 调用超时（秒）
`default_max_iterations`	integer	`20`	Agent 默认最大迭代次数

[agent]
max_agents = 200
default_memory_size = 2048
llm_endpoint = "http://gpu-node:11434"
llm_model = "eneros-llm-13b"
llm_timeout_s = 60
default_max_iterations = 50

[powerflow] 潮流计算配置

控制潮流求解器默认行为。

参数	类型	默认值	说明
`default_method`	string	`newton-raphson`	默认求解方法
`tolerance`	number	`1e-8`	收敛精度（标幺值）
`max_iterations`	integer	`20`	最大迭代次数
`flat_start`	boolean	`false`	是否平启动
`q_limit_check`	boolean	`true`	无功越限检查
`tap_adjust`	boolean	`true`	变压器变比调整

default_method 可选值：

值	说明	适用场景
`newton-raphson`	牛顿-拉夫逊法	通用，精度高
`fast-decoupled`	快速解耦法（PQ 分解）	大电网，速度优先
`dc`	直流潮流	近似计算，仅考虑有功
`gauss-seidel`	高斯-塞德尔法	老旧算法，教学用

[powerflow]
default_method = "newton-raphson"
tolerance = 1e-10
max_iterations = 50
flat_start = false
q_limit_check = true
tap_adjust = true

[topology] 拓扑配置

控制电网拓扑分析与缓存。

参数	类型	默认值	说明
`auto_validate`	boolean	`true`	加载拓扑时自动校验
`strict_mode`	boolean	`false`	严格模式，违规即报错
`cache_ttl_s`	integer	`300`	拓扑缓存有效期（秒）

[topology]
auto_validate = true
strict_mode = true
cache_ttl_s = 600

[gateway] 实时安全网关配置

控制实时安全网关（eneros-gateway）行为。

参数	类型	默认值	说明
`enabled`	boolean	`false`	是否启用网关
`listen_port`	integer	`8443`	网关监听端口
`heartbeat_interval_ms`	integer	`1000`	心跳间隔（毫秒）
`max_clients`	integer	`100`	最大客户端连接数

[gateway]
enabled = true
listen_port = 8443
heartbeat_interval_ms = 500
max_clients = 500

[timeseries] 时序存储配置

控制内核时序存储引擎。

参数	类型	默认值	说明
`retention_days`	integer	`365`	数据保留天数
`batch_size`	integer	`1000`	批量写入大小
`flush_interval_ms`	integer	`100`	刷新间隔（毫秒）
`compression`	string	`zstd`	压缩算法（zstd/lz4/none）

[timeseries]
retention_days = 730
batch_size = 5000
flush_interval_ms = 50
compression = "zstd"

[observability] 可观测性配置

控制日志、指标与链路追踪。

参数	类型	默认值	说明
`log_level`	string	`info`	日志级别
`log_format`	string	`json`	日志格式（json/text）
`metrics_enabled`	boolean	`true`	是否启用 Prometheus 指标
`metrics_port`	integer	`9090`	指标暴露端口
`tracing_enabled`	boolean	`false`	是否启用链路追踪
`tracing_endpoint`	string	`http://localhost:4317`	OTLP gRPC 端点

[observability]
log_level = "debug"
log_format = "json"
metrics_enabled = true
metrics_port = 9090
tracing_enabled = true
tracing_endpoint = "http://otel-collector:4317"

[multi_tenant] 多租户配置

控制多租户隔离策略。

参数	类型	默认值	说明
`enabled`	boolean	`false`	是否启用多租户
`default_tenant`	string	`default`	默认租户 ID
`isolation_mode`	string	`schema`	隔离模式（schema/database/row）

isolation_mode 可选值：

值	说明	隔离强度
`schema`	同库不同 schema	中
`database`	不同租户独立数据库	强
`row`	行级隔离（共享表 + tenant_id）	弱

[multi_tenant]
enabled = true
default_tenant = "tenant_default"
isolation_mode = "schema"

[realtime] 实时域配置

控制实时域守护进程（eneros-rt）。

参数	类型	默认值	说明
`enabled`	boolean	`false`	是否启用实时域
`priority`	integer	`80`	实时线程优先级（1-99）
`cpu_affinity`	array	`[2, 3]`	实时线程绑定的 CPU 核心
`isolated_cpus`	boolean	`true`	是否使用 isolcpus 隔离的核心

[realtime]
enabled = true
priority = 90
cpu_affinity = [2, 3]
isolated_cpus = true

环境变量覆盖

所有配置项均可通过环境变量覆盖，格式为 ENEROS_ 前缀 + 大写路径（用下划线分隔）。环境变量优先级高于配置文件。

命名规则

配置项	环境变量
`server.port`	`ENEROS_SERVER_PORT`
`database.path`	`ENEROS_DATABASE_PATH`
`security.tls_enabled`	`ENEROS_SECURITY_TLS_ENABLED`
`agent.max_agents`	`ENEROS_AGENT_MAX_AGENTS`
`powerflow.tolerance`	`ENEROS_POWERFLOW_TOLERANCE`
`observability.log_level`	`ENEROS_OBSERVABILITY_LOG_LEVEL`

使用示例

# 覆盖单个配置项
ENEROS_SERVER_PORT=9090 ./target/release/eneros-api

# 覆盖多个配置项
ENEROS_SERVER_PORT=9090 \
ENEROS_DATABASE_PATH=/var/lib/eneros/data.db \
ENEROS_SECURITY_TLS_ENABLED=true \
ENEROS_OBSERVABILITY_LOG_LEVEL=debug \
./target/release/eneros-api

# 数组类型用逗号分隔
ENEROS_SERVER_CORS_ORIGINS="https://a.com,https://b.com" \
./target/release/eneros-api

# 布尔值
ENEROS_SECURITY_MTLS_REQUIRED=true ./target/release/eneros-api

在 Docker 中使用

docker run -d \
  -p 8080:8080 \
  -e ENEROS_SERVER_PORT=8080 \
  -e ENEROS_DATABASE_PATH=/var/lib/eneros/data.db \
  -e ENEROS_OBSERVABILITY_LOG_LEVEL=info \
  -v eneros-data:/var/lib/eneros \
  eneros:latest

或在 docker-compose.yml 中：

services:
  eneros-api:
    image: eneros:latest
    environment:
      - ENEROS_SERVER_PORT=8080
      - ENEROS_DATABASE_PATH=/var/lib/eneros/data.db
      - ENEROS_OBSERVABILITY_LOG_LEVEL=info

在 systemd 中使用

[Service]
Environment="ENEROS_SERVER_PORT=8080"
Environment="ENEROS_DATABASE_PATH=/var/lib/eneros/data.db"
EnvironmentFile=/etc/eneros/env
ExecStart=/opt/eneros/bin/eneros-api

/etc/eneros/env 文件格式：

ENEROS_OBSERVABILITY_LOG_LEVEL=info
ENEROS_SECURITY_TLS_ENABLED=true

多环境配置策略

EnerOS 推荐为不同环境维护独立的配置文件。

配置文件命名约定

eneros.toml            # 默认（生产）
eneros.dev.toml        # 开发环境
eneros.test.toml       # 测试环境
eneros.staging.toml    # 预发布环境
eneros.prod.toml       # 生产环境

通过命令行切换

# 使用开发配置
./target/release/eneros-api --config eneros.dev.toml

# 使用生产配置
./target/release/eneros-api --config eneros.prod.toml

开发环境配置示例（eneros.dev.toml）

[server]
host = "127.0.0.1"
port = 8080
workers = 2

[database]
path = "data/dev.db"
journal_mode = "memory"

[security]
tls_enabled = false

[agent]
max_agents = 10
llm_endpoint = "http://localhost:11434"

[observability]
log_level = "debug"
log_format = "text"

生产环境配置示例（eneros.prod.toml）

[server]
host = "0.0.0.0"
port = 8080
workers = 16
max_connections = 50000

[database]
path = "/var/lib/eneros/prod.db"
journal_mode = "wal"
cache_size_mb = 2048

[security]
tls_enabled = true
cert_path = "/etc/eneros/certs/server.crt"
key_path = "/etc/eneros/certs/server.key"
mtls_required = true

[agent]
max_agents = 500
llm_endpoint = "http://gpu-cluster:11434"
llm_model = "eneros-llm-13b"

[observability]
log_level = "info"
log_format = "json"
metrics_enabled = true
tracing_enabled = true
tracing_endpoint = "http://otel-collector:4317"

通过环境变量选择配置

可在启动脚本中根据 ENV 变量选择配置文件：

#!/bin/bash
ENV=${ENEROS_ENV:-dev}
exec ./target/release/eneros-api --config eneros.${ENV}.toml

配置验证

EnerOS 在启动时自动验证配置文件。如果配置项非法，将拒绝启动并输出详细错误。

手动验证

# 验证配置文件
./target/release/eneros-api --config eneros.toml --check-config

# 输出示例：
# [OK] server.port: 8080
# [OK] database.path: data/eneros.db
# [WARN] security.tls_enabled: false (生产环境建议启用)
# [OK] agent.max_agents: 100
# [ERROR] powerflow.tolerance: -1 (必须为正数)

常见验证错误

错误	原因
`port must be between 1 and 65535`	端口越界
`tolerance must be positive`	收敛精度必须为正数
`workers must be at least 1`	工作线程数必须 ≥ 1
`cert_path does not exist`	证书文件不存在
`unknown field 'xxx'`	配置项名称错误

热加载

EnerOS 支持部分配置项的热加载，无需重启服务即可生效。

支持热加载的配置项

Section	字段	说明
`observability`	`log_level`	动态调整日志级别
`agent`	`max_agents`	调整最大 Agent 数
`timeseries`	`batch_size`, `flush_interval_ms`	调整时序写入参数
`topology`	`cache_ttl_s`	调整拓扑缓存时间

触发热加载

# 通过 SIGHUP 信号触发
kill -HUP $(cat eneros.pid)

# 通过 API 触发
curl -X POST http://localhost:8080/api/v1/config/reload

# 通过 CLI
./target/release/enerosctl config reload

修改配置文件后热加载

# 1. 修改配置
sed -i 's/log_level = "info"/log_level = "debug"/' eneros.toml

# 2. 发送 SIGHUP
kill -HUP $(cat eneros.pid)

# 3. 查看日志确认
tail -f eneros.log
# 应看到 "Configuration reloaded: log_level=debug"

不支持热加载的配置项（如 server.port、database.path、security.tls_enabled）需要重启服务才能生效。

敏感信息管理

避免在配置文件中硬编码密码、API key 等敏感信息。

方式 1：环境变量

[agent]
# 引用环境变量，不直接写出
llm_endpoint = "${LLM_ENDPOINT}"
llm_api_key  = "${LLM_API_KEY}"

EnerOS 在加载配置时会自动替换 ${VAR_NAME} 形式的占位符为对应环境变量值。

方式 2：Secret 文件

[security]
cert_path = "/etc/eneros/certs/server.crt"
key_path  = "/etc/eneros/secrets/server.key"

将敏感文件权限设为 600：

chmod 600 /etc/eneros/secrets/server.key
chown eneros:eneros /etc/eneros/secrets/server.key

方式 3：外部密钥管理

集成 HashiCorp Vault、AWS Secrets Manager 等：

[secrets]
provider = "vault"
vault_endpoint = "https://vault.example.com:8200"
vault_path = "secret/eneros"
# 通过 VAULT_TOKEN 环境变量传递 token

敏感信息检查清单

配置文件不包含明文密码
配置文件权限为 600，所有者为 eneros
密钥文件不在版本控制中
使用环境变量或密钥管理服务
生产环境启用 TLS
.gitignore 包含 *.toml、*.key、*.crt

# 设置配置文件权限
chmod 600 eneros.toml
chown eneros:eneros eneros.toml

# 确认 .gitignore 包含敏感文件
echo "eneros.prod.toml" >> .gitignore
echo "*.key" >> .gitignore
echo "*.crt" >> .gitignore

下一步

EnerOS 简介 - 回顾核心概念
首个 Agent - 创建并运行 Agent