Macaroni OS Eagle Minimal 镜像文档

1. 镜像概述和主要用途

Macaroni OS Eagle Minimal 镜像是官方发布的基于 Macaroni OS Eagle 版本的最小化 Docker 镜像。该镜像以轻量级为核心设计目标，基于 Gentoo Linux 生态构建，仅包含维持系统基础运行的必要组件（如基础工具链、init 系统、包管理基础等），剔除了非必要服务和依赖，适用于对资源占用敏感、需要自定义底层环境的场景。

2. 核心功能和特性

2.1 轻量级与精简设计

• 镜像体积最小化：通过裁剪非必要组件，基础镜像体积显著小于标准发行版镜像。
• 启动速度优化：简化 init 流程，减少启动依赖，容器启动时间短。

2.2 兼容性与灵活性

• 基于 Gentoo 生态：支持 Portage 包管理系统（emerge 命令），可按需安装额外组件。
• 多架构支持：默认提供 amd64 架构支持，可通过构建参数扩展至其他架构（如 arm64，需官方多架构镜像支持）。

2.3 安全性与可定制性

• 最小攻击面：仅保留核心组件，降低潜在漏洞暴露风险。
• 高度可定制：支持通过 Dockerfile 或运行时配置（如环境变量、挂载文件）扩展功能，满足个性化需求。

3. 使用场景和适用范围

3.1 容器化应用基础镜像

作为微服务、轻量级应用（如静态文件服务、API 服务）的底层基础镜像，减少基础环境资源占用。

3.2 开发与测试环境

用于构建隔离的开发/测试环境，支持通过 emerge 快速安装开发工具链（如 gcc、make 等），避免宿主环境污染。

3.3 CI/CD 工作流

集成至 CI/CD 管道，作为编译、打包或测试阶段的执行环境，适配资源受限的 CI 节点。

3.4 嵌入式与资源受限场景

适用于边缘设备、嵌入式系统或低配置服务器，满足对内存、存储资源敏感的部署需求。

4. 使用方法和配置说明

4.1 前提条件

• 已安装 Docker 引擎（推荐版本 20.10+），并配置正确的镜像拉取源（如官方仓库或镜像加速器）。

4.2 镜像拉取

通过 Docker 官方仓库拉取最新版本镜像：

docker pull macaronios/eagle-minimal:latest

如需指定版本标签（如稳定版），可替换 latest 为具体版本号（需参考官方标签列表）：

docker pull macaronios/eagle-minimal:20240101  # 示例版本标签

4.3 容器运行与基础操作

4.3.1 基本运行（交互式模式）

启动交互式容器，用于临时调试或环境探索：

docker run -it --rm macaronios/eagle-minimal:latest /bin/bash

• -it：启用交互式终端；--rm：容器退出后自动删除。

4.3.2 后台运行（守护进程模式）

启动长期运行的容器，适用于作为服务基础环境：

docker run -d --name eagle-minimal-demo macaronios/eagle-minimal:latest /sbin/init

• -d：后台运行；--name：指定容器名称；/sbin/init：启动基础 init 系统（确保进程前台运行，避免容器退出）。

4.3.3 端口映射与数据持久化

如需暴露应用端口或持久化数据，可通过 -p（端口映射）和 -v（卷挂载）参数配置：

# 映射容器 8080 端口至宿主 8080 端口，挂载宿主 ./data 目录至容器 /app/data
docker run -d -p 8080:8080 -v $(pwd)/data:/app/data --name eagle-app macaronios/eagle-minimal:latest

4.3.4 进入运行中容器

通过 docker exec 进入后台运行的容器：

docker exec -it eagle-minimal-demo /bin/bash

4.4 自定义配置

4.4.1 通过环境变量配置

镜像支持通过环境变量调整基础系统参数，常用变量如下：

示例：通过环境变量设置时区和语言：

docker run -it -e LANG=en_US.UTF-8 -e TIMEZONE=Asia/Shanghai macaronios/eagle-minimal:latest

4.4.2 通过 Dockerfile 扩展功能

如需预装额外组件（如 curl、git），可基于该镜像构建自定义镜像，示例 Dockerfile：

FROM macaronios/eagle-minimal:latest

# 安装 curl 和 git（通过 Portage 包管理）
RUN emerge --sync && emerge -v net-misc/curl dev-vcs/git

# 设置工作目录
WORKDIR /app

# 暴露应用端口
EXPOSE 8080

# 启动命令
CMD ["/bin/bash"]

构建自定义镜像：

docker build -t my-eagle-custom .

5. 部署示例

5.1 docker run 完整示例（带服务部署）

部署一个基于该镜像的简单 HTTP 服务（需提前准备 server.sh 脚本，内容为启动 HTTP 服务的命令）：

# 宿主机准备服务脚本（示例：启动 Python 简易 HTTP 服务）
echo 'python3 -m http.server 8080' > server.sh && chmod +x server.sh

# 运行容器：挂载脚本、映射端口、设置时区
docker run -d \
  -p 8080:8080 \
  -v $(pwd)/server.sh:/app/server.sh \
  -e TIMEZONE=Asia/Shanghai \
  --name eagle-http-demo \
  macaronios/eagle-minimal:latest \
  /app/server.sh

5.2 docker-compose 部署示例

通过 docker-compose.yml 配置多容器应用（如前端静态服务 + 后端 API 服务，均基于该镜像）：

version: '3.8'

services:
  frontend:
    image: macaronios/eagle-minimal:latest
    ports:
      - "80:8080"
    volumes:
      - ./frontend:/usr/share/nginx/html  # 挂载静态文件
    environment:
      - TIMEZONE=Asia/Shanghai
    command: /bin/bash -c "emerge www-servers/nginx && nginx -g 'daemon off;'"  # 安装并启动 Nginx

  backend:
    image: macaronios/eagle-minimal:latest
    ports:
      - "8080:8080"
    volumes:
      - ./backend:/app  # 挂载后端代码
    environment:
      - LANG=en_US.UTF-8
    command: /bin/bash -c "emerge dev-lang/python && cd /app && python3 main.py"  # 安装 Python 并启动后端

启动服务：

docker-compose up -d

6. 注意事项

• 工具链缺失：最小化镜像默认不含部分常用工具（如 wget、vim），需通过 emerge 手动安装（安装前建议执行 emerge --sync 更新 Portage 树）。
• 持久化数据：避免直接在容器内存储持久化数据，建议通过 -v 参数挂载宿主机目录或 Docker Volume。
• 安全性：默认 root 用户运行容器，生产环境建议通过 --user 参数指定非特权用户（需提前在容器内创建用户）。
• 网络配置：如需容器间通信，建议使用 Docker 网络（如 --network 参数）而非直接端口映射。