Deployment Guide

中文 | English

部署指南

维护版本：v0.55.0 ｜ 最后更新：2026-07-08

本页概述 EnerOS 五种部署方式、OS 镜像构建、A/B 分区 OTA 与监控。完整部署文档请参阅主仓库 docs/deployment.md 与 os/*/README.md。

系统要求

项	最低	推荐
OS	Linux Ubuntu 22.04+ / Debian 12+ 或 Docker	同左
Rust	1.75+（仅源码编译）	—
内存	512MB	2GB+
磁盘	1GB（含时序存储）	10GB+
网络	开放 8080（API）	+ 16686（Jaeger）/ 9090（Prometheus）/ 3000（Grafana）

五种部署方式

1. Docker Compose（推荐）

git clone https://github.com/Gawg-AI/EnerOS.git eneros && cd eneros
cp eneros.toml eneros.toml.local
# 编辑 eneros.toml.local ...

docker compose -f deploy/docker/docker-compose.yml up -d
docker compose -f deploy/docker/docker-compose.yml logs -f eneros

curl http://localhost:8080/health

带监控和追踪的完整部署：

docker compose -f deploy/docker/docker-compose.yml --profile monitoring --profile tracing up -d

v0.55.0 加固：healthcheck 从 curl 改用 wget（修复 debian:bookworm-slim 无 curl）+ mem_limit/cpus/pids_limit + no-new-privileges/read_only/cap_drop + tmpfs/ulimits。

2. 源码编译

# 开发模式
./deploy/scripts/dev.sh

# 生产构建
./deploy/scripts/build.sh v0.55.0

# 直接运行 release 二进制
./target/release/eneros-api run --config eneros.toml

Windows 用户：使用 cargo run --package eneros-api -- run --config eneros.toml 替代 .sh 脚本。

3. systemd 部署（推荐用于生产服务器，v0.55.0+）

4 个核心服务独立 unit + CPUAffinity 调优 + IOSchedulingClass=realtime（Gateway/SCADA）+ NoNewPrivileges + ProtectSystem=strict。

# 安装（创建 eneros 用户/组 + 复制 unit + enable）
sudo bash deploy/systemd/install.sh --yes

# 查看状态
systemctl status eneros.target

# 启停
sudo systemctl start eneros.target
sudo systemctl stop eneros.target

# 卸载（保留数据目录）
sudo bash deploy/systemd/uninstall.sh

服务	Unit 文件	CPUAffinity	IOSchedulingClass	说明
API Server	eneros-api.service	0	—	HTTP/WS API
SafetyGateway	eneros-gateway.service	1	realtime	实时安全决策
Agent Orchestrator	eneros-agent.service	2-3	—	Agent 调度
SCADA Collector	eneros-scada.service	0	realtime	实时数据采集

4 核 CPU 调优建议：API=0, Gateway=1, Agent=2-3, SCADA=0（与 API 共享但 IOSchedulingClass=realtime 保障采集）。8 核 CPU 可将每个服务独占一核。

4. 裸机部署（推荐用于变电站就地部署，v0.55.0+）

# 生成可启动镜像（不写入设备）
bash deploy/bare-metal/install.sh --output-image /tmp/eneros.img --arch x86_64

# 写入物理介质（U盘/SSD）
sudo bash deploy/bare-metal/install.sh --device /dev/sdX --yes

# QEMU 测试启动（x86_64）
qemu-system-x86_64 -m 2G -drive format=raw,file=/tmp/eneros.img

# QEMU 测试启动（aarch64）
qemu-system-aarch64 -m 2G -machine virt -cpu cortex-a72 -drive format=raw,file=/tmp/eneros.img

5 分区 A/B 布局 + UEFI 启动 + eneros-init PID 1。

5. OS 镜像构建

os/ 目录提供完整 OS 镜像构建工具链：

子目录	用途
os/boot/	启动配置（U-Boot / GRUB）
os/kernel/	Linux 内核配置 + 补丁（PREEMPT_RT / isolcpus / mlockall）
os/kernel/patches/	内核补丁
os/rootfs/	根文件系统（init.toml / 配置文件 / 二进制）
os/image-builder/	镜像构建脚本（生成 .img / .iso）
os/tests/	OS 启动测试

详见 os/*/README.md 各子目录文档。

A/B 分区 OTA（v0.22.0+）

EnerOS 支持 A/B 分区 OTA 升级，使用 Ed25519 签名验证升级包完整性：

┌─────────────────────────────────────┐
│         Storage Layout              │
├─────────────────────────────────────┤
│  Bootloader │ A partition │ B partition │ User data │
│             │ (active)    │ (backup)    │           │
└─────────────────────────────────────┘

升级流程：

1. 下载升级包到 inactive 分区
2. Ed25519 签名验证
3. 写入 inactive 分区
4. 切换启动标志
5. 重启
6. 启动失败自动回滚到 active 分区

# 生成升级包
enerosctl ota pack --version 0.55.0 --output update.pkg

# 签名升级包
enerosctl ota sign update.pkg /etc/eneros/keys/private.key

# 应用升级
enerosctl ota apply update.pkg

A/B OTA 生产化（v0.55.0+）

v0.55.0 将 A/B OTA 从"代码可用"升级为"生产级可演练"：

• mark_slot_good：启动成功后标记活跃槽位为 Good，确认健康状态
• mark_slot_trying：启动早期标记活跃槽位为 Trying + boot_count 递增
• 自动回滚：boot_count ≥ 3 时自动回滚到上一个 Good 槽位
• ServiceManager 集成：start_all() 开头检查 OTA 启动状态，结尾确认启动成功

# OTA 管理 CLI
enerosctl ota pack --version 0.55.0 --output update.pkg
enerosctl ota sign update.pkg /etc/eneros/keys/private.key
enerosctl ota apply update.pkg

# 查看槽位状态
enerosctl ota status

监控

Prometheus + Grafana

docker compose -f deploy/docker/docker-compose.yml --profile monitoring up -d
# Grafana: http://localhost:3000
# Prometheus: http://localhost:9090

EnerOS 暴露的 metrics 端点：GET /api/v1/metrics（Prometheus 格式）

Jaeger 分布式追踪

docker compose -f deploy/docker/docker-compose.yml --profile tracing up -d
# Jaeger UI: http://localhost:16686

EnerOS 通过 OpenTelemetry 上送 traces 到 Jaeger。

日志

[observability]
log_level = "info"
enable_tracing = true
jaeger_endpoint = "http://localhost:4317"

支持日志级别动态调整（无需重启）：

curl -X POST http://localhost:8080/api/config/reload

多租户部署

详见本 wiki 多租户 页与 docs/deployment.md §3.3。

零信任部署

详见本 wiki 零信任安全 页与 docs/deployment.md §3.4。

运维自动化部署

详见本 wiki 运维与插件 页与 docs/deployment.md §3.5。

高可用部署

详见本 wiki 高可用与多区域 页与 docs/deployment.md §3.6。

已知限制（v0.55.0）

• Windows / macOS 仅支持核心库开发，不支持生产部署
• OS 镜像构建仅支持 Linux x86_64 / aarch64
• OTA 升级仅 A/B 分区，未支持 delta 升级
• 监控仪表盘需手动导入 Grafana JSON

相关文档

• 主仓库 docs/deployment.md — 完整部署文档
• 主仓库 os/boot/README.md — 启动配置
• 主仓库 os/kernel/README.md — 内核配置
• 主仓库 os/rootfs/README.md — 根文件系统
• 主仓库 os/image-builder/README.md — 镜像构建
• 主仓库 deploy/docker/docker-compose.yml — Docker Compose 配置
• 本 wiki 安装 — 安装方式速查
• 本 wiki 配置参考 — eneros.toml 段落速查