Multi Tenancy

中文 | English

多租户与隔离

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

EnerOS v0.38.0 引入多租户安全共享部署，允许多个组织在同一 EnerOS 实例中安全共存，资源命名空间隔离 + 配额限制 + 跨租户默认拒绝。本页为特性摘要；完整配置请参阅主仓库 docs/user-manual.md §多租户 与 docs/deployment.md §3.3 + ADR-0006。

启用多租户

默认禁用（enabled = false），行为与单租户一致。

[tenant]
enabled = true
default_tenant_id = "default"
storage_path = "data/tenant.db"
default_max_devices = 1000
default_max_agents = 50
default_max_api_calls_per_day = 100000
default_max_storage_mb = 1024

命名空间隔离

所有资源 ID 采用 <tenant_id>:<resource_id> 命名空间前缀：

tenant_a:device_001
tenant_b:device_001   # 与 tenant_a 完全独立
default:device_001    # 无前缀的资源视为全局，所有租户可见

跨租户访问策略

操作	默认行为	备注
跨租户读	404 Not Found	不返回 403 以避免泄露资源存在性
跨租户写	404 Not Found	同上
全局资源访问	允许	无 : 前缀的资源
Emergency 超管	全部允许	详见下节

配额

TenantManager 在每次资源创建时检查配额：

配额项	默认值	配置项
最大设备数	1000	default_max_devices
最大 Agent 数	50	default_max_agents
每日 API 调用上限	100000	default_max_api_calls_per_day
存储上限（MB）	1024	default_max_storage_mb

配额超限返回 429 Too Many Requests。

Emergency 超管

AuthorityLevel::Emergency 级别用户可跨租户访问所有资源，用于：

• 紧急故障处理（如全网故障隔离）
• 跨租户协调（如分布式能源聚合调度）
• 监管审计

Emergency 权限由 eneros-trust 的 CA 签发专用证书，且所有跨租户访问记录到 WORM 审计日志（HMAC 链）。

持久化

TenantManager 使用 SQLite 持久化租户元数据与配额计数：

data/tenant.db
├── tenants          # 租户表（id / name / config / quota）
├── usage_counters   # 配额使用计数（按日重置）
└── api_call_log     # API 调用日志（用于日配额计算）

向后兼容

场景	迁移影响
现有 API Key	自动绑定到 default 租户，无需迁移
无 : 前缀的资源 ID	视为全局资源，所有租户可见
禁用多租户（enabled = false）	行为与 v0.37.0 完全一致

部署架构

┌─────────────────────────────────────────────┐
│              EnerOS 实例（单进程）            │
│                                              │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │ 租户 A  │  │ 租户 B  │  │ 租户 C  │    │
│  │ 地市公司│  │ 变电站群│  │ 综合能源│    │
│  └────┬────┘  └────┬────┘  └────┬────┘    │
│       │            │            │           │
│  ┌────┴────────────┴────────────┴────┐    │
│  │     TenantManager + UsageTracker   │    │
│  │     SQLite 持久化 (tenant.db)      │    │
│  └────────────────────────────────────┘    │
│                                              │
│  命名空间隔离: <tenant_id>:<resource_id>    │
│  跨租户访问: 404（默认拒绝）                 │
└─────────────────────────────────────────────┘

已知限制（v0.51.2）

• 仅单实例多租户，未支持跨实例租户联邦
• 配额计数为软限制，超限后拒绝新请求但不影响已运行资源
• 无租户级资源用量仪表盘（待 v0.52.0 dashboard 增强）
• Emergency 超管操作未在 dashboard 单独标记

相关文档

• ADR-0006 多租户
• 零信任安全 — 多租户 + 零信任组合部署
• 配置参考 — [tenant] 段配置项
• 主仓库 docs/deployment.md §3.3 — 多租户部署配置
• 主仓库 docs/user-manual.md §多租户 — 用户视角说明
• 主仓库 crates/eneros-tenant/ — 源码