Deployment Guide

中文 | English

部署指南

维护版本：v0.51.2 ｜ 最后更新：2026-07-06

本页概述 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

2. 源码编译

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

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

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

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

3. 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.51.2 --output update.pkg

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

# 应用升级
enerosctl ota apply update.pkg

监控

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.51.2）

• 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 段落速查