Docker 安装

本文档介绍如何在裸机 Linux 主机、EC2 实例或 Slurm 集群上使用 Docker 容器部署 Alluxio，无需 Kubernetes。

概述

架构

每个 Alluxio 组件运行在独立的 Docker 容器中，均使用 --net=host 共享宿主机网络，组件之间通过 IP 直接通信，无需配置端口映射。

本指南部署以下拓扑：

主机	运行的容器
Coordinator 节点	ETCD、Alluxio Coordinator、Prometheus、Grafana
Worker 节点（可多台）	Alluxio Worker（每台主机一个）
FUSE 客户端节点	Alluxio FUSE（每台主机一个）

制品

您将收到 Alluxio Docker 镜像的下载链接：

制品	文件名	用途
Alluxio 镜像	alluxio-enterprise-AI-3.8-15.1.2-linux-amd64-docker.tar	Coordinator、Worker 和 FUSE 的容器镜像
License		激活集群所需

平台：x86 主机使用 -linux-amd64-docker.tar，ARM 主机使用 -linux-arm64-docker.tar。

Docker 镜像是单一多角色镜像——每个节点加载相同的 .tar 文件。角色（coordinator、worker、fuse）由传递给 docker run 的入口参数决定。

开始之前

在开始之前运行以下检查。跳过此步骤是部署失败的最常见原因。

• Docker 已在每台主机上安装并运行：

  docker --version
  docker info

• 所有主机之间可以互相访问——从每台主机测试：

  ping <COORDINATOR_PRIVATE_IP>

• 安全组 / 防火墙 允许所有主机之间以下端口通信：

  端口	组件	用途
  2379	ETCD	客户端请求
  2380	ETCD	节点间通信
  19998	Coordinator	RPC
  19999	Coordinator	Web UI / 指标
  29998	Worker	S3 API
  29999	Worker	RPC
  30000	Worker	Web UI / 指标
  49998	FUSE	RPC
  49999	FUSE	指标

• Alluxio Docker 镜像 .tar 文件 已可用于加载

• Alluxio License 字符串 已准备就绪

• UFS 凭据 已准备就绪（S3 access key/secret，或主机绑定的 IAM role）

在 EC2 上使用 IAM role？ 在启动 EC2 实例之前将 IAM instance profile 附加到实例——无需在 Docker 运行命令中填写 access key。

安装步骤

0. 在每台主机上加载 Alluxio 镜像

在每台主机（coordinator、每个 worker、FUSE 客户端）上执行：

docker load -i alluxio-enterprise-AI-3.8-15.1.2-linux-amd64-docker.tar

✅ 验证：

docker images | grep alluxio

alluxio/alluxio-enterprise   AI-3.8-15.1.2   4091c3d8dbc4   ...   2.58GB

记录确切的镜像名称和标签——每个 docker run 命令都会用到。

1. 启动 ETCD

SSH 进入 ETCD 节点并启动单节点 ETCD 集群：

docker run -p 2379:2379 -p 2380:2380 -d --name etcd-standalone \
  quay.io/coreos/etcd:v3.5.9 etcd \
  --listen-client-urls http://0.0.0.0:2379 \
  --advertise-client-urls http://<COORDINATOR_PRIVATE_IP>:2379

将 <COORDINATOR_PRIVATE_IP> 替换为 coordinator 主机的私有 IP（例如 172.31.31.133）。使用私有 IP（而非主机名）以确保其他主机上的 worker 能可靠地访问 ETCD。

生产环境建议运行 3 节点 ETCD 集群以实现高可用。单节点 ETCD 适用于评估和非关键工作负载。

✅ 验证：

docker exec etcd-standalone etcdctl endpoint status --cluster -w table

+-----------------------------------+------------------+---------+---------+-----------+
|             ENDPOINT              |        ID        | VERSION | DB SIZE | IS LEADER |
+-----------------------------------+------------------+---------+---------+-----------+
| http://172.31.31.133:2379         | 8e9e05c52164694d |   3.5.9 |   20 kB |      true |
+-----------------------------------+------------------+---------+---------+-----------+

2. 启动 Coordinator（Coordinator 主机）

docker run -d --net=host --name=alluxio-coordinator \
  -e ALLUXIO_JAVA_OPTS="\
    -Dalluxio.license=<YOUR_LICENSE> \
    -Dalluxio.etcd.endpoints=http://<COORDINATOR_PRIVATE_IP>:2379 \
    -Dalluxio.coordinator.hostname=<COORDINATOR_PRIVATE_IP> \
    -Dalluxio.mount.table.source=ETCD" \
  alluxio/alluxio-enterprise:AI-3.8-15.1.2 coordinator

关键配置项：

配置项	说明
alluxio.license	Alluxio License 字符串
alluxio.etcd.endpoints	ETCD 端点（私有 IP + 端口 2379）
alluxio.coordinator.hostname	本主机私有 IP——worker 使用此地址注册
alluxio.mount.table.source=ETCD	挂载表存储在 ETCD 中（重启后持久保留）

✅ 验证：

docker logs alluxio-coordinator 2>&1 | grep -i "started\|listening\|etcd"

前 30 秒内没有 ERROR 行表示启动正常。

3. 启动 Worker（每台 Worker 主机）

SSH 进入每台 worker 主机 并运行：

docker run -d --net=host --name=alluxio-worker \
  -e ALLUXIO_JAVA_OPTS="\
    -Xmx8g -Xms2g -XX:MaxDirectMemorySize=8g \
    -Dalluxio.license=<YOUR_LICENSE> \
    -Dalluxio.etcd.endpoints=http://<COORDINATOR_PRIVATE_IP>:2379 \
    -Dalluxio.coordinator.hostname=<COORDINATOR_PRIVATE_IP> \
    -Dalluxio.mount.table.source=ETCD \
    -Dalluxio.worker.page.store.dirs=/data/alluxio-cache \
    -Dalluxio.worker.page.store.sizes=<CACHE_SIZE>" \
  alluxio/alluxio-enterprise:AI-3.8-15.1.2 worker

将 <CACHE_SIZE> 替换为用于页缓存的本地磁盘容量（例如 50GB、200GB、1TB）。设置为 /data/alluxio-cache 可用空间的约 80%。避免使用 /tmp——重启后会被清空，导致 worker 丢失所有缓存数据。

S3 API（可选）：如需通过 S3 API 访问 Alluxio，在每个 worker 的启动命令中添加 -Dalluxio.worker.s3.api.enabled=true，这将在 worker 上启用 S3 兼容端点（端口 29998）。

JVM 大小建议 — 对于页缓存位于本地磁盘（而非 RAM）的主机，JVM 堆内存不需要很大。Alluxio 将缓存数据存储在磁盘上，而非堆内存中。起始参考值：

主机内存	-Xmx	-XX:MaxDirectMemorySize
16 GB	4g	4g
32 GB	8g	8g
64 GB	16g	16g
128 GB+	32g	32g

✅ 验证（从 coordinator 主机执行）：

docker exec alluxio-coordinator alluxio info nodes

WorkerId                                         Address                          Status
worker-15ed4a17-2154-4454-ba0b-32b46ff06bfb     ip-172-31-26-247...:29999        ONLINE
worker-704c4d42-d189-41ff-b6f5-775a7d1551b3     ip-172-31-18-67...:29999         ONLINE

所有 worker 显示 ONLINE。容器启动后 worker 可能需要 10–15 秒完成注册。

4. 挂载存储

在任意能访问 coordinator 的主机上执行 alluxio mount add。完整的 UFS 配置选项请参阅底层存储。

使用 IAM role 挂载 S3（EC2 上推荐）：

docker exec alluxio-coordinator alluxio mount add \
  --path /s3 \
  --ufs-uri s3://<S3_BUCKET>/ \
  --option alluxio.underfs.s3.region=<S3_REGION>

使用 access key/secret 挂载 S3：

docker exec alluxio-coordinator alluxio mount add \
  --path /s3 \
  --ufs-uri s3://<S3_BUCKET>/ \
  --option alluxio.underfs.s3.region=<S3_REGION> \
  --option s3a.accessKeyId=<ACCESS_KEY> \
  --option s3a.secretKey=<SECRET_KEY>

✅ 验证：

docker exec alluxio-coordinator alluxio mount list

Listing all mount points
s3://<S3_BUCKET>/  on  /s3/  properties={alluxio.underfs.s3.region=<S3_REGION>}

5. 验证数据访问

docker exec alluxio-coordinator alluxio fs ls /s3/

✅ 验证： 返回 S3 存储桶内容，无报错。

6. 启动 FUSE（FUSE 客户端主机）

SSH 进入 FUSE 客户端主机。

创建挂载目录：

sudo mkdir -p /mnt/alluxio
sudo chown $(whoami) /mnt/alluxio
chmod 755 /mnt/alluxio

启动 FUSE 容器：

docker run -d --privileged --net=host --name=alluxio-fuse \
  -v /mnt/alluxio:/mnt/alluxio:shared \
  -e ALLUXIO_JAVA_OPTS="\
    -Xmx4g -Xms1g -XX:MaxDirectMemorySize=4g \
    -Dalluxio.etcd.endpoints=http://<COORDINATOR_PRIVATE_IP>:2379 \
    -Dalluxio.coordinator.hostname=<COORDINATOR_PRIVATE_IP> \
    -Dalluxio.mount.table.source=ETCD" \
  alluxio/alluxio-enterprise:AI-3.8-15.1.2 fuse -o allow_other /mnt/alluxio/fuse

--privileged 为必需项，用于在容器内挂载文件系统，并通过 -v /mnt/alluxio:/mnt/alluxio:shared 暴露给宿主机。

✅ 验证（等待约 10 秒）：

ls /mnt/alluxio/fuse/

s3

FUSE 挂载将每个 Alluxio 挂载点作为子目录暴露。/mnt/alluxio/fuse/s3/ 下的文件直接映射到 s3://<S3_BUCKET>/。

测试读写：

# 读取已有文件
cat /mnt/alluxio/fuse/s3/test.txt

# 写入新文件
echo "hello alluxio" > /mnt/alluxio/fuse/s3/hello.txt

# 验证文件已出现在 S3
aws s3 ls s3://<S3_BUCKET>/hello.txt

卸载

按相反顺序在每台主机上停止并删除容器：

FUSE 客户端主机：

docker stop alluxio-fuse && docker rm alluxio-fuse
sudo umount -l /mnt/alluxio/fuse   # 容器删除后挂载卡住时使用

每台 Worker 主机：

docker stop alluxio-worker && docker rm alluxio-worker

Coordinator 主机：

docker stop alluxio-coordinator && docker rm alluxio-coordinator
docker stop etcd-standalone && docker rm etcd-standalone

持久化数据：ETCD 容器将挂载表条目存储在容器文件系统中。执行 docker rm 后挂载表条目将丢失，需重新添加。如需在 ETCD 重启后保留挂载表，可挂载 ETCD 数据目录：在 ETCD docker run 命令中添加 -v /data/etcd:/etcd-data 和 --data-dir /etcd-data。

监控（可选）

在 coordinator 主机上使用 Docker Compose 搭建 Prometheus 和 Grafana。

创建目录结构：

mkdir -p ~/monitoring/prometheus ~/monitoring/grafana

创建 ~/monitoring/prometheus/prometheus.yml：

global:
  scrape_interval: 60s

scrape_configs:
  - job_name: "coordinator"
    static_configs:
      - targets: ["<COORDINATOR_PRIVATE_IP>:19999"]
  - job_name: "workers"
    static_configs:
      - targets: ["<WORKER1_PRIVATE_IP>:30000", "<WORKER2_PRIVATE_IP>:30000"]
  - job_name: "fuse"
    static_configs:
      - targets: ["<FUSE_PRIVATE_IP>:49999"]

创建 ~/monitoring/grafana/datasource.yml：

apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    url: http://prometheus:9090
    isDefault: true
    access: proxy
    editable: true

创建 ~/monitoring/compose.yaml：

services:
  prometheus:
    image: prom/prometheus
    container_name: prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
    ports:
      - 9090:9090
    restart: unless-stopped
    volumes:
      - ./prometheus:/etc/prometheus
      - prom_data:/prometheus
  grafana:
    image: grafana/grafana
    container_name: grafana
    ports:
      - 3000:3000
    restart: unless-stopped
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=grafana
    volumes:
      - ./grafana:/etc/grafana/provisioning/datasources
volumes:
  prom_data:

启动监控：

cd ~/monitoring && docker compose up -d

访问 Grafana：http://<COORDINATOR_PUBLIC_IP>:3000（登录：admin / grafana）。

从监控文档导入 Alluxio 仪表盘 JSON。

附录

A. 故障排查

Worker 未出现在 alluxio info nodes 中

1. 从 worker 主机验证 ETCD 是否可达：

   curl http://<COORDINATOR_PRIVATE_IP>:2379/health

   预期结果：{"health":"true"}

2. 检查 worker 容器日志：

   docker logs alluxio-worker 2>&1 | grep -i "error\|etcd\|register" | tail -20

3. 验证 coordinator IP 是否正确——worker 使用 alluxio.coordinator.hostname 进行注册。若该 IP 从 worker 不可达，注册会静默失败。

FUSE 容器启动后挂载不可见

1. 验证挂载目录是否在启动容器之前已创建：

   ls -la /mnt/alluxio/fuse

   若目录不存在，容器会成功启动但挂载会被静默跳过。

2. 检查容器日志：

   docker logs alluxio-fuse 2>&1 | tail -20

   类似 Mount point '/mnt/alluxio/fuse' does not exist 的日志行确认目录缺失。

3. 修复后删除并重新创建容器：

   docker rm -f alluxio-fuse
   # 重新执行步骤 6 中的 docker run 命令

容器删除后出现 Transport endpoint is not connected

FUSE 文件系统在容器退出后仍注册在内核中。手动卸载：

sudo umount -l /mnt/alluxio/fuse

alluxio mount add 报 unknown command

alluxio mount add CLI 使用具名参数。旧的位置参数语法（alluxio mount add /path s3://...）已不再支持。请使用：

alluxio mount add --path /s3 --ufs-uri s3://<BUCKET>/ --option alluxio.underfs.s3.region=<REGION>

B. 重启后 Worker 节点身份丢失

若 worker 主机重启，worker 容器会丢失其身份文件，并以新 worker 身份注册。旧条目在 ETCD 中以 OFFLINE 状态残留。清理方法：

docker exec alluxio-coordinator alluxio process remove-worker -n <WORKER_ID>

Worker ID 在 alluxio info nodes 输出中显示。

C. 收集日志用于技术支持

# Coordinator 日志
docker cp alluxio-coordinator:/opt/alluxio/logs /tmp/coordinator-logs

# Worker 日志（在每台 worker 主机上执行）
docker cp alluxio-worker:/opt/alluxio/logs /tmp/worker-logs

# 运行 collectInfo（从 coordinator 执行）
docker exec alluxio-coordinator bash -c "cd /tmp && /opt/alluxio/bin/collectinfo.sh"
docker cp alluxio-coordinator:/tmp/output.tar.gz /tmp/alluxio-collectinfo.tar.gz

相关文档

• Amazon S3 UFS — S3 凭据和配置选项

• POSIX API (FUSE) — FUSE 挂载选项和调优

• S3 API — 使用 Alluxio S3 兼容端点

• 监控 — Grafana 仪表盘导入和指标参考