RealmManagement 镜像文档

1. 镜像概述和主要用途

1.1 概述

RealmManagement 是 Astarte 平台的领域管理后端组件，专注于执行领域（Realm）级别的管理任务，是 Astarte 生态中实现领域生命周期管理的核心服务。

1.2 主要用途

• 执行领域管理任务，包括但不限于安装新接口（Interfaces）
• 处理领域配置更新、资源分配及权限管理等操作
• 通过 RPC 接口提供领域管理功能的程序化访问能力

2. 核心功能和特性

2.1 核心功能

• 领域管理任务执行：支持安装接口、更新配置、管理领域资源等核心操作
• RPC 接口支持：提供远程过程调用（RPC）接口，允许外部系统或服务通过编程方式调用管理功能
• Astarte 生态集成：与 Astarte 核心服务（如 Astarte Core、AppEngine）无缝协作，确保管理操作的一致性

2.2 特性

• 轻量级部署：基于容器化设计，支持快速集成到现有 Astarte 部署环境
• 操作原子性：确保领域管理任务的事务一致性，避免部分执行导致的状态异常
• 可扩展接口：支持通过配置扩展管理功能，适应不同场景下的领域需求

3. 使用场景和适用范围

3.1 适用场景

• Astarte 多租户环境下的领域创建与初始化
• 领域内接口（Interfaces）的动态安装、更新与卸载
• 跨领域资源分配与权限策略调整
• 自动化脚本或第三方系统通过 RPC 调用实现领域管理流程自动化

3.2 适用范围

• Astarte 平台用户（开发者、系统管理员）
• 需要对 Astarte 领域进行程序化管理的场景
• 多领域、多租户环境下的集中化领域运维

4. 使用方法和配置说明

4.1 Docker 快速启动

通过 docker run 命令启动容器：

bash
docker run -d \
  --name realm-management \
  -p 50051:50051 \  # RPC 服务端口（默认 50051）
  -e ASTARTE_CORE_ADDRESS=astarte-core:4000 \  # Astarte 核心服务地址
  -e LOG_LEVEL=info \  # 日志级别（debug/info/warn/error）
  -e REALM_NAME=default \  # 可选：默认管理的领域名称
  astarte/realm-management:latest

4.2 Docker Compose 配置示例

yaml
version: '3.8'

services:
  realm-management:
    image: astarte/realm-management:latest
    container_name: astarte-realm-management
    ports:
      - "50051:50051"
    environment:
      - ASTARTE_CORE_ADDRESS=astarte-core:4000  # Astarte 核心服务地址（必填）
      - RPC_PORT=50051  # RPC 服务监听端口（默认 50051）
      - LOG_LEVEL=info  # 日志级别
      - AUTH_TOKEN=${ASTARTE_AUTH_TOKEN}  # 访问 Astarte 核心服务的认证令牌（按需配置）
    depends_on:
      - astarte-core  # 依赖 Astarte 核心服务
    restart: unless-stopped

4.3 持久化配置（可选）

如需持久化配置文件或日志，可挂载本地目录：

bash
docker run -d \
  --name realm-management \
  -v ./realm-config:/etc/realm-management/config \  # 配置文件目录
  -v ./realm-logs:/var/log/realm-management \  # 日志目录
  astarte/realm-management:latest

5. 配置参数说明

5.1 环境变量

6. RPC 接口使用说明

RealmManagement 通过 RPC 接口提供服务，客户端可通过默认端口 50051 调用管理方法。常用 RPC 方法包括：

• InstallInterface：向指定领域安装新接口
• UpdateRealmConfig：更新领域配置参数
• GetRealmStatus：查询领域运行状态

具体 RPC 接口定义可参考 Astarte *** API 文档或镜像内置的 .proto 文件。

7. 注意事项

• 版本兼容性：确保与 Astarte 核心服务版本匹配，版本不一致可能导致功能异常
• 安全控制：未启用认证时，需通过网络策略限制 RPC 端口访问，避免未授权调用
• 数据备份：执行接口删除、配置重置等敏感操作前，建议备份领域数据
• 资源限制：根据管理任务规模调整容器 CPU/内存资源，避免任务积压