Apache Polaris 1.3 Docker Compose 部署指南

目标：使用 Docker Compose 编排部署 Apache Polaris 1.3.0-incubating（数据湖目录服务，支持 Iceberg REST Catalog），覆盖镜像选型、compose 文件、环境变量、数据/配置持久化、等价 docker run 与运维命令。本文已在 Ubuntu 22.04 上实测通过，服务监听 8181/8182。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（Kernel 6.8.0-138-generic）
Docker：Docker Engine 29.x 系列（支持 Compose v2 命令）
组件：Apache Polaris 1.3.0-incubating（Java/Quarkus 3.29.4）
部署方式：Docker Compose 单机编排
工作目录：/opt/polaris-compose/
数据目录：/opt/polaris-compose/data/（容器内数据映射到宿主机）
配置目录：/opt/polaris-compose/conf/（application 配置映射到宿主机）
监听端口：8181（REST Catalog API）、8182（Management 接口）

二、镜像选型说明

项	说明
官方镜像仓库	Apache 官方暂未在 Docker Hub 提供独立的 `apache/polaris` 二进制镜像，二进制发布以 `polaris-bin-1.3.0-incubating.tgz` 形式分发
部署基准	官方基础映像为带 Java SE 21 的 JRE 运行环境（Polaris 要求 Java 21+）
通用做法	Compose 中基于开箱基础映像（含 JDK 21）装载二进制包并运行 `bin/server`
数据卷	挂载宿主机目录承载日志与元数据
端口映射	将容器内 8181/8182 映射到宿主机对应端口

💡 说明：需 Java 21 运行时，基础映像可选用任意自带 openjdk-21 的发行版本，通过 JAVA_HOME 指定即可。

三、前置条件

宿主机已安装 Docker Engine 与 Compose v2：

docker --version
docker compose version

已能访问 Docker Hub 拉取基础映像，且能在宿主机访问 Apache 下载站拉取 Polaris 二进制包。
已在宿主机创建数据/配置目录：

mkdir -p /opt/polaris-compose/data /opt/polaris-compose/conf

四、部署步骤

4.1 拉取基础映像

docker pull ubuntu:22.04

💡 也可选择已内置 JDK21 的运行映像；本文以 Ubuntu 22.04 为基础并在容器内安装 JDK21，思路清晰。

4.2 准备 Polaris 二进制包

下载并校验后解压到工作目录：

cd /opt/downloads
wget https://downloads.apache.org/incubator/polaris/1.3.0-incubating/polaris-bin-1.3.0-incubating.tgz
echo "$(awk '{print $1}' polaris-bin-1.3.0-incubating.tgz.sha512)  polaris-bin-1.3.0-incubating.tgz" | sha512sum -c -
mkdir -p /opt/polaris-compose/polaris
tar -xzf polaris-bin-1.3.0-incubating.tgz -C /opt/polaris-compose/polaris

解压后目录为 /opt/polaris-compose/polaris/polaris-bin-1.3.0-incubating/。

4.3 编写 Dockerfile（构建运行镜像）

在 /opt/polaris-compose/ 下创建 Dockerfile，装入 JDK21 与 Polaris 二进制：

FROM ubuntu:22.04

RUN apt-get update && \
    apt-get install -y --no-install-recommends openjdk-21-jre-headless wget && \
    rm -rf /var/lib/apt/lists/*

ENV JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
ENV POLARIS_JAVA_OPTS="-Xms256m -Xmx512m"

COPY polaris/polaris-bin-1.3.0-incubating /opt/polaris

WORKDIR /opt/polaris
EXPOSE 8181 8182
CMD ["bin/server"]

4.4 构建镜像

cd /opt/polaris-compose
docker build -t apache/polaris:1.3.0-incubating .

💡 说明：CMD bin/server 即官方启动脚本，等价于 java -jar server/quarkus-run.jar。

4.5 编写 docker-compose.yml

在 /opt/polaris-compose/ 下创建 docker-compose.yml：

services:
  polaris:
    image: apache/polaris:1.3.0-incubating
    container_name: polaris
    restart: unless-stopped
    environment:
      POLARIS_JAVA_OPTS: "-Xms256m -Xmx512m"
      POLARIS_BOOTSTRAP_CREDENTIALS: "POLARIS,c6a6dcd313a5d7fb,28de31ce9b53445982f37ec2ee3cce27"
      JAVA_HOME: "/usr/lib/jvm/java-21-openjdk-amd64"
    ports:
      - "8181:8181"
      - "8182:8182"
    volumes:
      - ./data:/opt/polaris/server/logs
      - ./conf:/opt/polaris/conf

⚠️ 注意：POLARIS_BOOTSTRAP_CREDENTIALS 固定 root 凭证，格式为逗号分隔的 realm,clientId,clientSecret，分号分隔可配置多组。

4.6 启动服务

cd /opt/polaris-compose
docker compose up -d

等待约 15-20 秒（Quarkus 冷启动），确认容器状态：

docker compose ps

预期出现 polaris 处于 Up 状态。查看启动日志：

docker compose logs polaris

预期回显中包含：

Apache Polaris Server (incubating) 1.3.0-incubating on JVM (powered by Quarkus 3.29.4)
      started in 15.675s. Listening on: http://0.0.0.0:8181. Management interface listening on http://0.0.0.0:8182.

4.7 验证运行

健康检查：

curl -s http://localhost:8182/q/health

预期输出：

{"status":"UP","checks":[{"name":"Database connections health check","status":"UP"}]}

获取 root 凭证并换取 token（凭证列在 compose 的 POLARIS_BOOTSTRAP_CREDENTIALS 中）：

curl -s -X POST http://localhost:8181/api/catalog/v1/oauth/tokens \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=c6a6dcd313a5d7fb&client_secret=28de31ce9b53445982f37ec2ee3cce27" \
  -d "scope=PRINCIPAL_ROLE:ALL"

创建 catalog：

TOKEN=<access_token>
curl -s -X POST http://localhost:8181/api/management/v1/catalogs \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"quickstart_catalog","type":"INTERNAL",
       "storageConfigInfo":{"storageType":"S3","allowedLocations":["s3://mybucket/polaris"]},
       "properties":{"default-base-location":"s3://mybucket/polaris"}}'

预期返回 201 Created 与 catalog JSON。

五、数据持久化说明

compose 通过 volumes 将容器内目录映射到宿主机，实现重启不丢失：

宿主机目录	容器内目录	作用
`/opt/polaris-compose/data`	`/opt/polaris/server/logs`	服务运行日志（Quarkus 文件日志）
`/opt/polaris-compose/conf`	`/opt/polaris/conf`	应用配置文件挂载点（application.properties / polaris-server.yml）

💡 说明：默认使用嵌入式测试元数据库（polaris.persistence.type=IN_MEMORY），数据不落盘；生产应配置关系型数据库（见配置参数详解篇）并将数据目录映射到数据库卷。

六、常用环境变量表

环境变量	容器内默认	说明
`POLARIS_JAVA_OPTS`	空	传给 java 的 JVM 参数（如 `-Xms256m -Xmx512m`、`-Dquarkus.http.port=8080`）
`POLARIS_BOOTSTRAP_CREDENTIALS`	空	root 凭证，格式 `realm,clientId,clientSecret`，未给则自动生成并打印 stdout
`JAVA_HOME`	`/usr/lib/jvm/java-21-openjdk-amd64`	JDK 路径
`POLARIS_REALM_CONTEXT_REALMS`	`POLARIS`	默认 realm 列表（对应配置键 `polaris.realm-context.realms`）

七、常用配置参数说明（command）

compose 中的 CMD 与 JVM 参数示例：

配置	示例	说明
修改 REST 端口	`-Dquarkus.http.port=8080`	通过 `POLARIS_JAVA_OPTS` 注入
修改管理端口	`-Dquarkus.management.port=8183`	通过 `POLARIS_JAVA_OPTS` 注入
堆内存	`-Xms256m -Xmx512m`	限定 JVM 堆，见 JVM 说明

⚠️ 注意：POLARIS_JAVA_OPTS 请放在 -jar server/quarkus-run.jar 之前传递给 java，与官方 bin/server 一致。

八、配置文件持久化（conf 挂载）

将宿主机的 application.properties（或 polaris-server.yml）挂载进容器，容器启动时读取。示例 conf/application.properties：

quarkus.http.port=8181
quarkus.management.port=8182
polaris.persistence.type=IN_MEMORY

挂载关系已在 docker-compose.yml 中声明（./conf:/opt/polaris/conf）。修改后需重建容器让配置生效。

九、等价 docker run 运行方式

除 compose 外，可用单条 docker run 等价启动：

docker run -d --name polaris \
  --restart unless-stopped \
  -p 8181:8181 \
  -p 8182:8182 \
  -e JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64 \
  -e POLARIS_JAVA_OPTS="-Xms256m -Xmx512m" \
  -e POLARIS_BOOTSTRAP_CREDENTIALS="POLARIS,c6a6dcd313a5d7fb,28de31ce9b53445982f37ec2ee3cce27" \
  -v /opt/polaris-compose/data:/opt/polaris/server/logs \
  -v /opt/polaris-compose/conf:/opt/polaris/conf \
  apache/polaris:1.3.0-incubating

十、常用运维命令

docker compose ps          # 查看容器状态
docker compose logs -f polaris   # 跟踪日志
docker compose restart polaris   # 重启服务
docker compose stop        # 停止服务
docker compose down        # 停止并移除容器（数据卷保留）
docker compose down -v     # 连同数据卷一并移除
docker exec -it polaris bash      # 进入容器内排障

⚠️ 注意：down -v 会删除 data/conf 卷映射的目标（若用 named volume 则删除数据），谨慎使用。

十一、常见问题（FAQ）

Q1：为什么 8080 端口无监听？

1.3.0-incubating 无内置 Web UI，服务监听 8181（REST Catalog API）与 8182（Management 接口），8080 未使用。

Q2：容器内如何固定 root 凭证？

在 environment 中设置 POLARIS_BOOTSTRAP_CREDENTIALS=POLARIS,<clientId>,<clientSecret>，重启后仍以此凭证登录。

Q3：数据重启后丢失怎么办？

默认 polaris.persistence.type=IN_MEMORY 仅测试用；生产需改为 relational-jdbc 并配置数据库，把数据库数据目录作持久化卷。

Q4：为什么创建 catalog 用 FILE 类型报错？

二进制发行版不支持 storageType: FILE，应用 S3/GCS/AZURE 类型（元数据校验），不影响本地功能测试。

十二、参考链接

Apache Polaris 官方文档：https://polaris.apache.org/
Apache Polaris 下载页：https://downloads.apache.org/incubator/polaris/
Docker Compose 文档：https://docs.docker.com/compose/