环境准备

本节介绍在搭建 EnerOS 开发与运行环境前所需的全部准备工作，包括操作系统要求、Rust 工具链安装、各平台系统依赖、Docker 镜像方案，以及环境验证与常见问题排查。

系统要求

EnerOS 由 56 个 Rust crate 组成，编译期需要较多内存与磁盘空间，运行期对延迟敏感。下表列出最低与推荐配置：

实时域扩展要求

若需要启用 EnerOS 的实时域（Protection / Control / Stability），需满足以下额外要求：

安装 Rust 工具链

EnerOS 使用 Rust 1.70+，推荐通过官方 rustup 工具安装与管理多版本工具链。

安装 rustup

Linux / macOS

# 下载并安装 rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 安装过程中选择默认选项（按 1 回车即可）

# 重新加载当前 shell 的环境变量
source $HOME/.cargo/env

# 验证安装
rustc --version
cargo --version
rustup --version

Windows

下载并运行 rustup-init.exe，按提示选择默认安装。安装完成后重新打开 PowerShell：

rustc --version
cargo --version
rustup --version

安装稳定版工具链

# 安装最新稳定版
rustup toolchain install stable

# 设为默认
rustup default stable

# 验证当前默认工具链
rustup show

rustup 组件

EnerOS 编译与开发推荐安装以下组件：

# 添加推荐组件
rustup component add rustfmt clippy rust-src rust-analyzer

# 添加可选组件（开发 unsafe 代码时使用）
rustup component add miri

工具链管理

# 列出已安装工具链
rustup toolchain list

# 安装 nightly（仅在使用某些 unstable feature 时需要）
rustup toolchain install nightly

# 升级所有工具链
rustup update

# 卸载某个工具链
rustup toolchain uninstall nightly

添加目标平台（交叉编译）

# 列出所有支持的目标
rustup target list

# 添加 aarch64-unknown-linux-gnu 目标（ARM64 Linux）
rustup target add aarch64-unknown-linux-gnu

# 添加 x86_64-pc-windows-gnu 目标（Windows GNU）
rustup target add x86_64-pc-windows-gnu

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

系统依赖

EnerOS 部分 crate 依赖 OpenSSL、SQLite、CMake 等系统原生库，请按操作系统安装。

Ubuntu / Debian

# 更新包索引
sudo apt update

# 安装编译工具链与基础依赖
sudo apt install -y \
    build-essential \
    pkg-config \
    libssl-dev \
    libsqlite3-dev \
    cmake \
    git \
    curl \
    clang \
    libclang-dev

CentOS / RHEL / Rocky Linux

# 启用 EPEL 仓库
sudo dnf install -y epel-release

# 安装依赖
sudo dnf install -y \
    gcc \
    gcc-c++ \
    make \
    pkgconfig \
    openssl-devel \
    sqlite-devel \
    cmake \
    git \
    clang \
    clang-devel

macOS

# 安装 Xcode Command Line Tools
xcode-select --install

# 安装 Homebrew（若未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装依赖
brew install openssl@3 sqlite pkg-config cmake

macOS 上若遇到 OpenSSL 链接问题，请将以下内容加入 ~/.zshrc 或 ~/.bash_profile：

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

Windows

Windows 推荐使用 MSVC 工具链。安装 Visual Studio Build Tools 并选择 “Desktop development with C++” 工作负载（包含 MSVC、Windows SDK、CMake）。

# 安装 Chocolatey（若未安装）
Set-ExecutionPolicy Bypass -Scope Process -Force
iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

# 安装依赖
choco install openssl pkgconfiglite cmake git -y

安装完成后设置环境变量（PowerShell）：

# 设置 OpenSSL 路径（按实际安装路径调整）
[Environment]::SetEnvironmentVariable("OPENSSL_DIR", "C:\Program Files\OpenSSL-Win64", "User")
[Environment]::SetEnvironmentVariable("PKG_CONFIG_PATH", "C:\Program Files\OpenSSL-Win64\lib\pkgconfig", "User")

# 重启 PowerShell 后验证
echo $env:OPENSSL_DIR

Docker 方式

如不想在宿主机安装大量依赖，可使用官方 Docker 镜像，已预装完整的 EnerOS 构建环境。

拉取官方镜像

# 拉取最新稳定版构建镜像
docker pull ghcr.io/gawg-ai/eneros-build:latest

# 拉取特定版本
docker pull ghcr.io/gawg-ai/eneros-build:0.47.0

在容器中构建

# 启动构建容器并挂载源码目录
docker run -it --rm \
    -v $(pwd):/workspace \
    -w /workspace \
    ghcr.io/gawg-ai/eneros-build:latest \
    bash

# 在容器内执行构建
cargo build --release

使用 Dockerfile 自定义

FROM ghcr.io/gawg-ai/eneros-build:latest

WORKDIR /workspace
COPY . .

RUN cargo build --release

EXPOSE 8080
CMD ["./target/release/eneros-api"]

# 构建自定义镜像
docker build -t my-eneros .

# 运行
docker run -d -p 8080:8080 --name eneros my-eneros

验证环境

1. 验证 Rust 工具链

# 检查 Rust 版本（应 ≥ 1.70）
rustc --version

# 检查 Cargo 版本
cargo --version

# 检查 rustup 组件
rustup component list --installed

预期输出示例：

rustc 1.75.0 (82e1608df 2023-12-21)
cargo 1.75.0 (1d8b05cdd 2023-11-20)
cargo-x86_64-unknown-linux-gnu (default)
rustfmt 1.7.0-stable (82e1608d 2023-12-21)
clippy 0.1.75 (82e1608d 2023-12-21)

2. 创建测试项目

# 创建测试项目
cargo new hello_eneros
cd hello_eneros

# 修改 main.rs 引用 OpenSSL（可选，验证系统库链接）
cat > src/main.rs <<'EOF'
fn main() {
    println!("Hello, EnerOS!");
    println!("OpenSSL version: {}", openssl::version::version());
}
EOF

# 添加 openssl 依赖
cargo add openssl

# 编译并运行
cargo run

预期输出：

Hello, EnerOS!
OpenSSL version: OpenSSL 3.0.x ...

3. 验证 SQLite 链接

cargo add rusqlite

修改 src/main.rs：

use rusqlite::Connection;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let conn = Connection::open_in_memory()?;
    conn.execute(
        "CREATE TABLE enerostest (id INTEGER PRIMARY KEY, name TEXT)",
        [],
    )?;
    println!("SQLite OK");
    Ok(())
}

cargo run
# 输出：SQLite OK

常见问题排查

问题 1：error: linker 'cc' not found

原因：未安装 C 编译器。

解决：

# Ubuntu / Debian
sudo apt install -y build-essential

# macOS
xcode-select --install

# Windows：安装 Visual Studio Build Tools，选择 C++ 工作负载

问题 2：error: failed to run custom build command for 'openssl-sys'

原因：未找到 OpenSSL 库或 pkg-config 未正确配置。

解决：

# Ubuntu
sudo apt install -y libssl-dev pkg-config

# macOS
brew install openssl@3 pkg-config
export OPENSSL_DIR=$(brew --prefix openssl@3)

# Windows
choco install openssl pkgconfiglite
# 设置 OPENSSL_DIR 环境变量指向安装目录

问题 3：error: could not find library 'sqlite3'

原因：未安装 SQLite 开发库。

解决：

# Ubuntu
sudo apt install -y libsqlite3-dev

# macOS
brew install sqlite

# Windows
choco install sqlite

问题 4：cargo build 时内存不足（OOM）

原因：EnerOS 是大型 workspace，并行编译 56 个 crate 时内存消耗大。

解决：限制并行度

# 限制同时编译的单元数
export CARGO_BUILD_JOBS=2

# 或在 ~/.cargo/config.toml 中配置
[build]
jobs = 2

问题 5：Windows 上 error: linking with 'link.exe' failed

原因：缺少 MSVC 工具链或 Windows SDK。

解决：

1. 重新运行 Visual Studio Installer
2. 选择 “Desktop development with C++” 工作负载
3. 确保 “Windows 10/11 SDK” 已勾选
4. 重新打开终端后重试

问题 6：网络下载 crates.io 失败

原因：网络访问受限。

解决：配置国内镜像源，编辑 ~/.cargo/config.toml：

[source.crates-io]
replace-with = "ustc"

[source.ustc]
registry = "sparse+https://mirrors.ustc.edu.cn/crates.io-index/"

或使用清华源：

[source.crates-io]
replace-with = "tuna"

[source.tuna]
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

下一步

• 安装与构建 - 克隆 EnerOS 仓库并构建