Cubbit Agent 官方基础镜像文档

一、镜像概述和主要用途

Cubbit Agent 官方基础镜像是构建 Cubbit Agent 官方镜像及自定义 Cubbit Agent 衍生镜像的底层基础环境。该镜像提供了 Cubbit Agent 运行所需的最小化系统依赖、运行时环境及基础配置框架，旨在简化 Cubbit Agent 镜像的构建流程，确保衍生镜像与 Cubbit Agent 核心功能的兼容性。

二、核心功能和特性

2.1 核心功能

• 提供 Cubbit Agent 运行所需的基础系统环境（如 glibc、核心系统库、工具链）。
• 预配置 Cubbit Agent 依赖的基础目录结构（如配置文件目录、数据存储目录、日志目录）。
• 内置基础初始化脚本，确保衍生镜像启动时的环境一致性。

2.2 关键特性

• 轻量级设计：基于精简的 Linux 发行版（如 Alpine 或 Debian Slim），最小化镜像体积，减少资源占用。
• 版本兼容性：严格匹配 Cubbit Agent 官方版本依赖，确保衍生镜像与 Cubbit Agent 核心组件版本兼容。
• 安全优化：默认启用非 root 用户运行基础配置，降低容器运行时的安全风险。
• 可扩展性：预留标准化的构建接口，支持通过 Dockerfile 指令或构建参数扩展自定义功能。

三、使用场景和适用范围

3.1 典型使用场景

• 官方 Cubbit Agent 镜像构建：Cubbit 官方团队基于此基础镜像集成 Agent 核心代码，生成可直接部署的 Cubbit Agent 官方镜像。
• 自定义 Agent 镜像开发：用户或企业基于此基础镜像添加自定义配置（如私有存储策略、日志集成、监控插件等），构建符合特定业务需求的 Cubbit Agent 衍生镜像。
• Agent 二次开发环境：开发者基于此镜像搭建 Cubbit Agent 插件开发或功能扩展的本地开发环境。

3.2 适用范围

• 需要构建自定义 Cubbit Agent 镜像的企业或个人用户。
• Cubbit Agent 插件开发者或二次开发团队。
• 对 Cubbit Agent 运行环境有定制化需求（如特定系统库版本、网络配置）的场景。

四、详细使用方法和配置说明

4.1 镜像获取

该镜像通常托管于 Cubbit 官方 Docker 仓库或 Docker Hub，获取命令如下（具体仓库地址需替换为官方指定地址）：

docker pull cubbit/agent-base:latest  # 拉取最新版本
# 或指定版本标签（如 v1.5.0）
docker pull cubbit/agent-base:v1.5.0

4.2 基于基础镜像构建自定义镜像

4.2.1 基础 Dockerfile 示例

通过以下 Dockerfile 可基于基础镜像添加自定义配置或代码：

# 基于 Cubbit Agent 基础镜像构建
FROM cubbit/agent-base:latest

# 示例 1：添加自定义配置文件（如私有存储节点配置）
COPY ./custom-storage-config.yaml /etc/cubbit/agent/config.d/

# 示例 2：安装额外依赖（如监控工具）
RUN apt-get update && apt-get install -y --no-install-recommends \
    prometheus-client \
    && rm -rf /var/lib/apt/lists/*

# 示例 3：设置环境变量（覆盖基础镜像默认值）
ENV AGENT_LOG_LEVEL=debug \
    AGENT_DATA_DIR=/data/cubbit/agent/custom

4.2.2 构建命令

在 Dockerfile 所在目录执行以下命令构建自定义镜像：

docker build -t custom-cubbit-agent:v1.0 .

4.3 基础镜像目录结构

基础镜像预定义以下关键目录（衍生镜像可直接使用或扩展）：

/etc/cubbit/agent/          # 配置文件根目录
  ├── config.d/             # 配置文件片段目录（支持多文件合并）
  └── base.env              # 基础环境变量配置文件
/var/log/cubbit/agent/      # 默认日志存储目录
/opt/cubbit/agent/          # Agent 核心运行目录
/data/cubbit/agent/         # 默认数据存储目录（建议通过 volumes 挂载）

4.4 环境变量说明

基础镜像支持通过环境变量调整基础配置，衍生镜像可通过 ENV 指令或运行时 -e 参数覆盖：

五、Docker 部署方案示例

5.1 基于基础镜像构建自定义 Agent 镜像（Dockerfile）

# 基于 Cubbit Agent 基础镜像
FROM cubbit/agent-base:v1.5.0

# 添加企业自定义存储策略配置
COPY ./enterprise-storage-policy.yaml /etc/cubbit/agent/config.d/

# 安装企业监控插件依赖
RUN apt-get update && apt-get install -y --no-install-recommends \
    jq \
    curl \
    && rm -rf /var/lib/apt/lists/*

# 调整数据目录权限（与宿主机挂载目录适配）
RUN chown -R ${AGENT_UID}:${AGENT_GROUP} ${AGENT_DATA_DIR}

# 覆盖默认日志级别为 info
ENV AGENT_LOG_LEVEL=info

5.2 构建与运行命令

# 构建自定义镜像
docker build -t enterprise-cubbit-agent:v1.0 -f Dockerfile .

# 运行自定义镜像（挂载数据目录和日志目录）
docker run -d \
  --name enterprise-agent \
  -e AGENT_LOG_LEVEL=debug \  # 运行时覆盖日志级别
  -v /host/data:/data/cubbit/agent \  # 挂载数据目录
  -v /host/logs:/var/log/cubbit/agent \  # 挂载日志目录
  enterprise-cubbit-agent:v1.0

5.3 docker-compose.yml 示例（适用于多实例部署）

version: '3.8'

services:
  cubbit-agent-1:
    build:
      context: ./agent-custom
      dockerfile: Dockerfile
    image: enterprise-cubbit-agent:v1.0
    container_name: agent-node-1
    environment:
      - AGENT_LOG_LEVEL=info
      - AGENT_NODE_ID=node-1
    volumes:
      - agent-data-1:/data/cubbit/agent
      - agent-logs-1:/var/log/cubbit/agent
    restart: unless-stopped

  cubbit-agent-2:
    image: enterprise-cubbit-agent:v1.0
    container_name: agent-node-2
    environment:
      - AGENT_LOG_LEVEL=info
      - AGENT_NODE_ID=node-2
    volumes:
      - agent-data-2:/data/cubbit/agent
      - agent-logs-2:/var/log/cubbit/agent
    restart: unless-stopped

volumes:
  agent-data-1:
  agent-logs-1:
  agent-data-2:
  agent-logs-2:

六、注意事项

1. 版本兼容性：衍生镜像的基础镜像版本需与 Cubbit Agent 核心版本严格匹配（如 Cubbit Agent v1.5.0 需对应基础镜像 v1.5.0），避免依赖冲突。
2. 权限管理：基础镜像默认使用非 root 用户运行，衍生镜像如需修改目录权限，需确保目标目录对 cubbit-agent 用户（UID/GID 1000）有读写权限。
3. 镜像体积控制：构建衍生镜像时建议使用 --no-install-recommends 减少依赖安装，并清理 apt/yum 缓存（如 rm -rf /var/lib/apt/lists/*）。
4. 数据持久化：/data/cubbit/agent 和 /var/log/cubbit/agent 目录建议通过 Docker volumes 或宿主机目录挂载，避免容器重建导致数据丢失。