安装与构建

本节介绍如何从 GitHub 克隆 EnerOS 源码、理解项目结构、选择合适的构建选项、运行测试、进行交叉编译以及使用 Docker 构建可分发镜像。

克隆仓库

EnerOS 源码托管在 GitHub：https://github.com/Gawg-AI/EnerOS。

通过 HTTPS 克隆（最常用）

git clone https://github.com/Gawg-AI/EnerOS.git
cd EnerOS

通过 SSH 克隆（适合贡献者）

git clone git@github.com:Gawg-AI/EnerOS.git
cd EnerOS

通过 GitHub CLI 克隆

# 安装 GitHub CLI（如未安装）
# Ubuntu
sudo apt install gh
# macOS
brew install gh

# 克隆
gh repo clone Gawg-AI/EnerOS
cd EnerOS

浅克隆（节省带宽）

# 只拉取最新一次提交
git clone --depth 1 https://github.com/Gawg-AI/EnerOS.git

# 拉取最近 10 次提交
git clone --depth 10 https://github.com/Gawg-AI/EnerOS.git

切换到特定版本

# 列出所有 tag
git tag -l

# 切换到 0.47.0 版本
git checkout v0.47.0

# 或切换到 main 分支最新代码
git checkout main
git pull

项目结构概览

EnerOS 采用 Cargo workspace 组织 56 个 crate：

EnerOS/
├── crates/           # 56 个 Rust crate（库 + 二进制）
│   ├── eneros-core/             # 内核基础
│   ├── eneros-topology/         # 电网拓扑
│   ├── eneros-powerflow/        # 潮流计算
│   ├── eneros-constraint/       # 安全约束
│   ├── eneros-equipment/        # 设备模型
│   ├── eneros-agent/            # Agent 运行时
│   ├── eneros-tool/             # Agent 工具
│   ├── eneros-reasoning/        # 推理引擎
│   ├── eneros-gateway/          # 实时安全网关
│   ├── eneros-trust/            # 信任与 CA
│   ├── eneros-ids/              # 入侵检测
│   ├── eneros-audit/            # 审计日志
│   ├── eneros-timeseries/       # 时序存储
│   ├── eneros-multiregion/      # 多区域
│   ├── eneros-tenant/           # 多租户
│   └── ...                      # 其余 41 个 crate
├── os/               # OS 服务层
│   ├── init/                    # 初始化
│   ├── rt/                      # 实时域
│   ├── agentos/                 # AgentOS 抽象
│   └── hal/                     # 硬件抽象层
├── docs/             # 项目文档
├── examples/         # 示例代码
├── tests/            # 集成测试
├── benches/          # 性能基准
├── Cargo.toml        # Workspace 配置
├── Cargo.lock        # 依赖锁定
├── eneros.toml       # 默认运行配置
└── Dockerfile        # 容器构建

关键二进制

构建

Release 构建（推荐生产使用）

cargo build --release

构建产物位于 target/release/，已开启全部优化（opt-level=3，LTO 可选）。

Debug 构建（开发调试）

cargo build

构建产物位于 target/debug/，编译更快，包含调试符号与断言。

构建特定 crate

# 只构建核心库
cargo build -p eneros-core

# 只构建 Agent 运行时
cargo build -p eneros-agent

# 只构建 API 服务器
cargo build -p eneros-api

# 只构建命令行工具
cargo build -p enerosctl

构建选项详解

Feature Flags

EnerOS 通过 Cargo features 控制可选功能：

# 启用实时域
cargo build --release --features "realtime"

# 启用 Dashboard
cargo build --release --features "dashboard"

# 启用多租户
cargo build --release --features "multi-tenant"

# 启用所有可选功能
cargo build --release --all-features

# 不启用默认特性
cargo build --release --no-default-features

LTO 与优化配置

如需更激进的优化，可编辑 .cargo/config.toml：

[profile.release]
opt-level = 3
lto = "fat"
codegen-units = 1
panic = "abort"
strip = true

构建产物说明

构建完成后，target/release/ 目录包含：

target/release/
├── eneros-api             # API 服务器主二进制
├── enerosctl              # CLI 工具
├── eneros-gateway         # 安全网关
├── eneros-agent           # Agent 运行时
├── eneros-rt              # 实时域守护
├── libeneros_core.rlib    # 静态库
├── libeneros_topology.rlib
└── ...                    # 其他 crate 产物

查看二进制体积：

ls -lh target/release/eneros-api

运行测试

EnerOS 拥有 7300+ 测试用例，覆盖所有核心功能。

运行全部测试

# 运行全部测试（包括单元测试与集成测试）
cargo test

# 释放模式运行（更快）
cargo test --release

# 不运行测试，只编译
cargo test --no-run

运行特定 crate 测试

# 潮流计算测试
cargo test -p eneros-powerflow

# 拓扑分析测试
cargo test -p eneros-topology

# 约束校验测试
cargo test -p eneros-constraint

# Agent 运行时测试
cargo test -p eneros-agent

运行特定测试函数

# 按名称过滤
cargo test -p eneros-powerflow newton_raphson

# 多个关键词
cargo test -p eneros-topology -- "test_island"

# 显示 println! 输出
cargo test -- --nocapture

# 只运行被忽略的测试
cargo test -- --ignored

集成测试

# 运行 tests/ 目录下的集成测试
cargo test --test '*'

# 运行特定集成测试文件
cargo test --test powerflow_integration

性能基准（Benchmark）

# 运行所有 benchmark
cargo bench

# 运行特定 crate 的 benchmark
cargo bench -p eneros-powerflow

# 输出到文件
cargo bench -- --save-baseline my_baseline

测试覆盖率

# 安装 tarpaulin（仅 Linux）
cargo install cargo-tarpaulin

# 生成覆盖率报告
cargo tarpaulin --workspace --out Html

# 查看报告
# 输出在 tarpaulin-report.html

测试结果示例

running 7342 tests
test result: ok. 7342 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

     Running tests/powerflow_integration.rs
test powerflow_ieee14 ... ok
test powerflow_ieee30 ... ok
test powerflow_ieee118 ... ok

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

交叉编译

EnerOS 支持交叉编译到多种目标平台。

交叉编译到 ARM64 Linux

# 添加目标
rustup target add aarch64-unknown-linux-gnu

# 安装交叉工具链（Ubuntu）
sudo apt install -y gcc-aarch64-linux-gnu

# 配置 linker，编辑 ~/.cargo/config.toml
[target.aarch64-unknown-linux-gnu]
linker = "aarch64-linux-gnu-gcc"

# 构建
cargo build --release --target aarch64-unknown-linux-gnu

产物位于 target/aarch64-unknown-linux-gnu/release/。

交叉编译到 Windows

# 添加目标（MSVC）
rustup target add x86_64-pc-windows-msvc

# 构建（需安装 MSVC 工具链）
cargo build --release --target x86_64-pc-windows-msvc

交叉编译到 WebAssembly

# 添加 WASI 目标
rustup target add wasm32-wasi

# 构建
cargo build --release --target wasm32-wasi -p eneros-core

使用 cross 工具

# 安装 cross（依赖 Docker）
cargo install cross

# 一键交叉编译（无需手动配置工具链）
cross build --target aarch64-unknown-linux-gnu

# 交叉运行测试
cross test --target aarch64-unknown-linux-gnu

Docker 构建

EnerOS 提供多阶段 Dockerfile，可直接构建可分发的容器镜像。

构建镜像

# 构建默认镜像
docker build -t eneros:latest .

# 构建特定版本
docker build -t eneros:0.47.0 .

# 指定平台
docker buildx build --platform linux/amd64,linux/arm64 -t eneros:latest .

Dockerfile 说明

EnerOS 的 Dockerfile 采用多阶段构建：

最终镜像体积约 80 MB，仅包含二进制与必要运行时库。

运行容器

# 运行 API 服务器
docker run -d \
    -p 8080:8080 \
    -v $(pwd)/eneros.toml:/etc/eneros/eneros.toml \
    -v $(pwd)/data:/var/lib/eneros \
    --name eneros-api \
    eneros:latest

# 查看日志
docker logs -f eneros-api

# 进入容器
docker exec -it eneros-api bash

docker-compose 示例

version: '3.8'
services:
  eneros-api:
    image: eneros:latest
    ports:
      - "8080:8080"
    volumes:
      - ./eneros.toml:/etc/eneros/eneros.toml
      - eneros-data:/var/lib/eneros
    environment:
      - ENEROS_LOG=info
    restart: unless-stopped

volumes:
  eneros-data:

docker compose up -d

常见构建问题

问题 1：OpenSSL 链接错误

error: failed to run custom build command for `openssl-sys`

解决：

# Ubuntu / Debian
sudo apt install -y libssl-dev pkg-config
export OPENSSL_DIR=/usr/lib/ssl
export PKG_CONFIG_PATH=/usr/lib/pkgconfig

# macOS
export OPENSSL_DIR=$(brew --prefix openssl@3)
export PKG_CONFIG_PATH="$(brew --prefix openssl@3)/lib/pkgconfig"

# 使用 vendored OpenSSL（无需系统库）
cargo build --release --features openssl-vendored

问题 2：SQLite 链接错误

error: linking with `cc` failed: exit code: 1
note: undefined reference to `sqlite3_open`

解决：

# Ubuntu
sudo apt install -y libsqlite3-dev

# macOS
brew install sqlite
export SQLITE3_LIB_DIR=$(brew --prefix sqlite)/lib

# 使用 bundled SQLite
cargo build --release --features sqlite-bundled

问题 3：ring crate 编译失败

error: failed to run custom build command for `ring`

原因：缺少 cmake 或 C 编译器。

解决：

# Ubuntu
sudo apt install -y cmake build-essential

# macOS
brew install cmake

问题 4：构建超时或卡在下载依赖

# 使用离线模式（需先在线 cargo fetch 一次）
cargo build --offline

# 增加网络超时
export CARGO_NET_TIMEOUT=120
export CARGO_NET_RETRY=5

# 配置镜像源（见 prerequisites.md）

问题 5：error: package 'eneros-core' not found in workspace

原因：未在仓库根目录执行命令，或 workspace 配置被破坏。

解决：

# 确认在仓库根目录
cd /path/to/EnerOS

# 检查 workspace 配置
cat Cargo.toml | head -10
# 应看到 [workspace] 段落

# 重新生成 Cargo.lock
rm Cargo.lock
cargo generate-lockfile

问题 6：编译时 error[E0463]: can't find crate

原因：feature 未启用导致依赖缺失。

解决：

# 检查 crate 的 features
cargo tree -p eneros-agent --features default

# 启用所需 feature
cargo build --release --features "realtime,dashboard"

问题 7：内存不足 (OOM killed)

# 限制并行任务数
CARGO_BUILD_JOBS=2 cargo build --release

# 添加 swap（Linux）
sudo fallocate -l 8G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

下一步

• 首次运行 - 启动 API 服务器并执行潮流计算