通过Trino集成Hadoop OSS Connector V2访问OSS - 对象存储 OSS

基于 Hadoop OSS Connector V2，Trino 可直接读写阿里云 OSS，快速搭建一套完整的数据湖查询测试环境。通过 Docker Compose 一键部署 Trino 480、Hive Metastore 及 MySQL，所有配置文件存放在宿主机本地目录并通过 Docker Volume 挂载至容器，只需在宿主机上执行少量命令即可完成全部部署。

背景信息

Trino 是一款高性能的分布式 SQL 查询引擎，广泛用于数据湖分析场景。通过 OSS V2 Connector，Trino 可以使用 s3a:// 协议直接读写阿里云 OSS 中的数据文件（Parquet、ORC、CSV 等格式），并配合 Hive Metastore（HMS）管理表结构与数据位置。

OSS V2 Connector 是原 Hadoop OSS Connector 的性能优化版本，采用阿里云 OSS SDK V2 实现，支持 V4 签名协议，兼容性与稳定性更好。

架构说明

┌─────────────────────────────────────────────────────────────────┐
│                        宿主机 (Host Machine)                     │
│                                                                 │
│  /opt/trino-test/                                               │
│  ├── docker-compose.yml                                         │
│  ├── mysql/                                                     │
│  │   └── init.sql                    ← MySQL 初始化脚本           │
│  ├── hms/                                                       │
│  │   └── conf/                                                  │
│  │       └── hive-site.xml           ← HMS 配置文件              │
│  └── trino/                                                     │
│      ├── etc/                                                   │
│      │   ├── catalog/                                           │
│      │   │   └── hive.properties     ← Trino Hive Catalog 配置   │
│      │   ├── jvm.config              ← JVM 配置                  │
│      │   └── node.properties         ← 节点配置                  │
│      │   └── hadoop/                                            │
│      │       └── conf/                                          │
│      │           └── core-site.xml   ← Hadoop 核心配置           │
│      └── plugin/                                                │
│          └── hive/                                              │
│              └── hdfs/                                          │
│                  └── hadoop-oss-*.jar ← OSS V2 JAR 包           │
└─────────────────────────────────────────────────────────────────┘
         │                          │
         │ Docker Volume Mount      │ Docker Volume Mount
         ▼                          ▼
┌──────────────────┐      ┌──────────────────┐      ┌────────────────┐
│  MySQL Container │      │  HMS Container   │      │ Trino Container│
│  mysql:5.7.35    │      │  apache/hive:4.0 │      │ trinodb/trino: │
│                  │      │                  │      │     480        │
│  /var/lib/mysql  │      │ /opt/hive/conf/  │      │ /etc/trino/    │
│  /docker-entry.. │      │                  │      │ /usr/lib/trino │
└──────────────────┘      └──────────────────┘      └────────────────┘
         │                          │                      │
         │                          │                      │
         └──────────────────────────┼──────────────────────┘
                                    │
                          Docker Network: trino-net
                                    │
                                    ▼
                          ┌──────────────────┐
                          │  Alibaba Cloud   │
                          │  OSS (s3a://)    │
                          └──────────────────┘

数据流向

查询发起：用户通过 Trino CLI 执行 SQL。
元数据获取：Trino 通过 Thrift 协议连接 HMS（默认端口 9083），获取表结构和数据位置。
数据读取：Trino 根据 location（如 s3a://bucket/path）调用 OSS V2 Connector。
OSS 访问：OSS V2 Connector 使用 core-site.xml 中的 AK/SK 与 Endpoint 向 OSS 发起 HTTPS 请求。
数据返回：OSS 返回数据流，Trino 解析并返回查询结果。

环境准备

硬件要求

组件	实例规格	vCPU	内存	网络带宽	说明
宿主机	ecs.g9i.8xlarge	32	128 GiB	100 Mbps	运行所有 Docker 容器

软件要求

软件	最低版本	验证命令
Docker	20.10+	`docker --version`
Docker Compose	2.0+	`docker compose version`
阿里云 OSS Bucket	-	已创建 Bucket，记录 Bucket 名称与 Region
阿里云 AccessKey	-	已获取具有目标 Bucket 读写权限的 AK/SK

验证 Docker 环境

在宿主机上执行以下命令，确认 Docker 已安装且正常运行：

# 检查 Docker 版本
docker --version
# 预期输出: Docker version 20.10.x 或更高

# 检查 Docker Compose 版本
docker compose version
# 预期输出: Docker Compose version v2.x.x

# 检查 Docker 是否正常运行
docker ps
# 预期输出: 容器列表（可能为空）

前两条应分别输出 Docker 与 Docker Compose 的版本号；docker ps 应正常返回容器列表（首次安装时为空）。

1. 准备本地配置文件

本节在宿主机上创建部署所需的目录与配置文件，统一放在 /opt/trino-test/ 目录下。后续启动 Docker Compose 时，这些文件会通过 Volume 自动挂载到对应容器的指定路径。

创建工作目录

# 创建根目录
mkdir -p /opt/trino-test

# 进入工作目录
cd /opt/trino-test

# 验证目录创建成功
ls -la /opt/trino-test
# 预期输出: 空目录

创建子目录结构

# 创建 MySQL 相关目录
mkdir -p /opt/trino-test/mysql

# 创建 HMS 相关目录
mkdir -p /opt/trino-test/hms/conf

# 创建 Trino 相关目录
mkdir -p /opt/trino-test/trino/etc/catalog
mkdir -p /opt/trino-test/trino/etc/hadoop/conf
mkdir -p /opt/trino-test/trino/plugin/hive/hdfs

# 验证目录结构
tree /opt/trino-test
# 或使用以下命令（如果未安装 tree）
find /opt/trino-test -type d

预期输出：

/opt/trino-test/
├── docker-compose.yml (待创建)
├── mysql/
├── hms/
│   └── conf/
└── trino/
    ├── etc/
    │   ├── catalog/
    │   └── hadoop/
    │       └── conf/
    └── plugin/
        └── hive/
            └── hdfs/

1.2 下载 OSS V2 JAR 包

将 OSS V2 Connector JAR 包放入宿主机的插件目录，启动后会自动挂载到 Trino 容器内的 /usr/lib/trino/plugin/hive/hdfs/。

前往下载地址获取 JAR 包，推荐使用 hadoop-oss-3.3.5-2.0.25-alpha-shade.jar（shade 版本已内置核心依赖，无需额外引入）。

将 JAR 包复制至插件目录：

# 复制本地已有 JAR 包
cp /path/to/hadoop-oss-3.3.5-2.0.26-alpha-shade.jar \
  /opt/trino-test/trino/plugin/hive/hdfs/

# 验证：
ls -lh /opt/trino-test/trino/plugin/hive/hdfs/hadoop-oss-3.3.5-2.0.26-alpha-shade.jar
# 预期输出: 文件大小约 12MB

重要

JAR 包必须放置在宿主机的 /opt/trino-test/trino/plugin/hive/hdfs/ 目录下。Docker Compose 启动后该文件会自动出现在容器内的对应路径，无需手动 docker cp。

1.3 创建 MySQL 初始化脚本

该脚本用于在 MySQL 启动时初始化 HMS 元数据库与对应的访问账号。

文件路径：/opt/trino-test/mysql/init.sql

# 使用 cat 命令创建文件
cat > /opt/trino-test/mysql/init.sql << 'EOF'
CREATE DATABASE metastore CHARACTER SET 'utf8' COLLATE 'utf8_bin';
CREATE USER 'hive'@'%' IDENTIFIED BY 'hive_password';
GRANT ALL PRIVILEGES ON metastore.* TO 'hive'@'%';
FLUSH PRIVILEGES;
EOF

# 验证文件创建成功
cat /opt/trino-test/mysql/init.sql

预期输出：

CREATE DATABASE metastore CHARACTER SET 'utf8' COLLATE 'utf8_bin';
CREATE USER 'hive'@'%' IDENTIFIED BY 'hive_password';
GRANT ALL PRIVILEGES ON metastore.* TO 'hive'@'%';
FLUSH PRIVILEGES;

1.4 创建 HMS 配置文件

配置 HMS 连接 MySQL 元数据库以及 Thrift 服务监听地址。

文件路径：/opt/trino-test/hms/conf/hive-site.xml

cat > /opt/trino-test/hms/conf/hive-site.xml << 'EOF'
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="configuration.xsl"?>
<configuration>
    <!-- MySQL 连接配置 -->
    <property>
        <name>javax.jdo.option.ConnectionURL</name>
        <value>jdbc:mysql://mysql:3306/metastore?createDatabaseIfNotExist=true</value>
    </property>
    <property>
        <name>javax.jdo.option.ConnectionDriverName</name>
        <value>com.mysql.jdbc.Driver</value>
    </property>
    <property>
        <name>javax.jdo.option.ConnectionUserName</name>
        <value>hive</value>
    </property>
    <property>
        <name>javax.jdo.option.ConnectionPassword</name>
        <value>hive_password</value>
    </property>

    <!-- HMS Thrift 服务配置 -->
    <property>
        <name>hive.metastore.uris</name>
        <value>thrift://hms:9083</value>
    </property>
    <property>
        <name>hive.metastore.schema.verification</name>
        <value>false</value>
    </property>
</configuration>
EOF
# 验证文件创建成功
cat /opt/trino-test/hms/conf/hive-site.xml

1.5 创建 Trino Hive Catalog 配置

该配置启用 Hadoop 文件系统支持，让 Trino 通过 OSS V2 Connector 处理 s3a:// 路径。

文件路径：/opt/trino-test/trino/etc/catalog/hive.properties

cat > /opt/trino-test/trino/etc/catalog/hive.properties << 'EOF'
connector.name=hive
hive.metastore.uri=thrift://hms:9083

# 启用 Hadoop 文件系统支持（关键配置）
fs.hadoop.enabled=true

# 使用 Hadoop 默认文件系统（读取 core-site.xml）
hive.s3-file-system-type=HADOOP_DEFAULT

# 指定 Hadoop 配置文件路径（容器内路径）
hive.config.resources=/etc/hadoop/conf/core-site.xml
EOF

# 验证文件创建成功
cat /opt/trino-test/trino/etc/catalog/hive.properties

配置项说明：

fs.hadoop.enabled=true：启用 Hadoop 文件系统支持，使 Trino 能加载 hdfs/ 目录下的 JAR 包。
hive.s3-file-system-type=HADOOP_DEFAULT：指示 Trino 使用 Hadoop 的 FileSystem 实现（即 OSS V2 Connector）。
hive.config.resources：指向容器内的 core-site.xml 路径。

1.6 创建 Trino JVM 配置

文件路径：/opt/trino-test/trino/etc/jvm.config

cat > /opt/trino-test/trino/etc/jvm.config << 'EOF'
-server
-Xmx4G
-XX:+UseG1GC
-XX:G1HeapRegionSize=32M
-XX:+ExitOnOutOfMemoryError
-XX:+HeapDumpOnOutOfMemoryError
EOF

# 验证文件创建成功
cat /opt/trino-test/trino/etc/jvm.config

1.7 创建 Trino 节点配置

文件路径：/opt/trino-test/trino/etc/node.properties

cat > /opt/trino-test/trino/etc/node.properties << 'EOF'
node.environment=test
node.data-dir=/data/trino
node.id=trino-test-001
EOF

# 验证文件创建成功
cat /opt/trino-test/trino/etc/node.properties

1.8 创建 Hadoop core-site.xml

该文件指定 OSS V2 Connector 的实现类与访问凭证。文件路径需与 hive.config.resources 配置项保持一致。

重要

请将示例中的 YOUR_ACCESS_KEY_ID、YOUR_ACCESS_KEY_SECRET、Endpoint、Region 替换为实际值。其中 Region 必须与 Bucket 所在地域完全一致，否则 V4 签名会校验失败。

文件路径：/opt/trino-test/trino/etc/hadoop/conf/core-site.xml

cat > /opt/trino-test/trino/etc/hadoop/conf/core-site.xml << 'EOF'
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="configuration.xsl"?>
<configuration>
    <!-- 使用阿里云 OSS Connector V2 实现 s3a:// 协议 -->
    <property>
        <name>fs.s3a.impl</name>
        <value>org.apache.hadoop.fs.aliyun.oss.v2.AliyunOSSPerformanceFileSystem</value>
    </property>
    <property>
        <name>fs.AbstractFileSystem.s3a.impl</name>
        <value>org.apache.hadoop.fs.aliyun.oss.v2.OSSWithS3A</value>
    </property>

    <!-- OSS 认证配置 -->
    <property>
        <name>fs.oss.accessKeyId</name>
        <value>YOUR_ACCESS_KEY_ID</value>
    </property>
    <property>
        <name>fs.oss.accessKeySecret</name>
        <value>YOUR_ACCESS_KEY_SECRET</value>
    </property>

    <!-- OSS Endpoint（同地域 ECS 推荐使用内网地址） -->
    <property>
        <name>fs.oss.endpoint</name>
        <value>oss-cn-hangzhou-internal.aliyuncs.com</value>
    </property>

    <!-- OSS Bucket 所在 Region（V4 签名必填） -->
    <property>
        <name>fs.oss.region</name>
        <value>cn-hangzhou</value>
    </property>
</configuration>
EOF

# 验证文件创建成功
cat /opt/trino-test/trino/etc/hadoop/conf/core-site.xml

关键配置参数说明：

参数	是否必填	说明
`fs.s3a.impl`	是	覆盖 `s3a://` 协议的文件系统实现，固定为 `org.apache.hadoop.fs.aliyun.oss.v2.AliyunOSSPerformanceFileSystem`。
`fs.AbstractFileSystem.s3a.impl`	是	AbstractFileSystem 层的 OSS V2 实现，固定为 `org.apache.hadoop.fs.aliyun.oss.v2.OSSWithS3A`。
`fs.oss.accessKeyId`	是	阿里云 AccessKey ID。
`fs.oss.accessKeySecret`	是	阿里云 AccessKey Secret。
`fs.oss.endpoint`	是	OSS 访问端点。同地域 ECS 推荐使用内网格式 `oss-{region}-internal.aliyuncs.com`，可免流量费、延迟更低；跨地域或本机访问使用公网格式 `oss-{region}.aliyuncs.com`。
`fs.oss.region`	是	Bucket 所在 Region，例如 `cn-hangzhou`。V4 签名必填，需与 Bucket 实际所在地域一致。

1.9 创建 docker-compose.yml

文件路径：/opt/trino-test/docker-compose.yml

cat > /opt/trino-test/docker-compose.yml << 'EOF'
version: '3.8'

services:
  # MySQL 服务：存储 HMS 元数据
  mysql:
    image: mysql:5.7.35
    container_name: trino-test-mysql
    environment:
      MYSQL_ROOT_PASSWORD: root_password
    ports:
      - "3306:3306"
    volumes:
      - ./mysql/init.sql:/docker-entrypoint-initdb.d/init.sql
      - mysql_data:/var/lib/mysql
    networks:
      - trino-net
    restart: unless-stopped

  # HMS 服务：Hive Metastore
  hms:
    image: apache/hive:4.0.0
    container_name: trino-test-hms
    environment:
      SERVICE_NAME: metastore
    ports:
      - "9083:9083"
    volumes:
      - ./hms/conf/hive-site.xml:/opt/hive/conf/hive-site.xml
    depends_on:
      - mysql
    networks:
      - trino-net
    restart: unless-stopped

  # Trino 服务：查询引擎
  trino:
    image: trinodb/trino:480
    container_name: trino-test-trino
    ports:
      - "8080:8080"
    volumes:
      # 挂载 Trino 配置文件
      - ./trino/etc:/etc/trino
      # 挂载插件目录（包含 OSS V2 JAR 包）
      - ./trino/plugin:/usr/lib/trino/plugin
    depends_on:
      - hms
    networks:
      - trino-net
    restart: unless-stopped

networks:
  trino-net:
    driver: bridge

volumes:
  mysql_data:
EOF

# 验证文件创建成功
cat /opt/trino-test/docker-compose.yml

Docker Volume 挂载关系：

宿主机路径	容器内路径	说明
`./mysql/init.sql`	`/docker-entrypoint-initdb.d/init.sql`	MySQL 初始化脚本
`./hms/conf/hive-site.xml`	`/opt/hive/conf/hive-site.xml`	HMS 配置文件
`./trino/etc`	`/etc/trino`	Trino 全部配置文件
`./trino/plugin`	`/usr/lib/trino/plugin`	Trino 插件目录（含 OSS V2 JAR）

说明

在宿主机上修改任何挂载的配置文件或放置 JAR 包后，容器内的对应路径会同步生效。修改 Trino 相关配置后通过 docker compose restart trino 重启使其生效；无需进入容器手动复制文件。

1.10 验证完整目录结构

# 查看完整目录结构
find /opt/trino-test -type f | sort

应输出以下 8 个文件：

/opt/trino-test/docker-compose.yml
/opt/trino-test/hms/conf/hive-site.xml
/opt/trino-test/mysql/init.sql
/opt/trino-test/trino/etc/catalog/hive.properties
/opt/trino-test/trino/etc/hadoop/conf/core-site.xml
/opt/trino-test/trino/etc/jvm.config
/opt/trino-test/trino/etc/node.properties
/opt/trino-test/trino/plugin/hive/hdfs/hadoop-oss-3.3.5-2.0.26-alpha-shade.jar

同时确认：

JAR 包大小约 12 MB。
core-site.xml 中的 AK/SK、Endpoint、Region 已替换为实际值。

2. 启动并验证服务

完成本地配置文件准备后，使用 Docker Compose 一键启动 MySQL、HMS、Trino 三个容器，并依次验证各组件状态。

2.1 启动所有容器

cd /opt/trino-test
docker compose up -d

# 预期输出:
# ✔ Network trino-test_trino-net  Created
# ✔ Container trino-test-mysql    Started
# ✔ Container trino-test-hms      Started
# ✔ Container trino-test-trino    Started

应依次输出 Network ... Created 与三个容器的 Started。

2.2 查看容器状态

# 查看所有容器状态
docker compose ps

# 预期输出:
# NAME                 IMAGE              STATUS          PORTS
# trino-test-hms       apache/hive:4.0.0  Up (healthy)    0.0.0.0:9083->9083/tcp
# trino-test-mysql     mysql:5.7.35       Up (healthy)    0.0.0.0:3306->3306/tcp
# trino-test-trino     trinodb/trino:480  Up (healthy)    0.0.0.0:8080->8080/tcp

三个容器（trino-test-mysql、trino-test-hms、trino-test-trino）应均处于 Up 状态，端口分别映射 3306、9083、8080。若状态为 Exited，请用 docker compose logs <容器名> 查看日志定位原因（参见常见问题排查）。

2.3 等待服务就绪并验证 Trino

Trino 完全启动需要约 30~60 秒，等待后通过 HTTP 接口验证：

# 等待 Trino 完全启动（约 30-60 秒）
sleep 45

# 验证 Trino 是否启动成功
curl -s http://localhost:8080/v1/info | head -20
# 预期输出: 包含 "running": true 的 JSON 响应

响应中应包含 "starting": false 且 Trino 节点正常注册。

2.4 查看各组件日志（可选）

# 查看 MySQL 日志
docker compose logs mysql

# 查看 HMS 日志
docker compose logs hms

# 查看 Trino 日志
docker compose logs trino

# 实时跟踪 Trino 日志
docker compose logs -f trino
# 按 Ctrl+C 退出

2.5 验证 MySQL、HMS 与 Web UI

验证 MySQL：进入 MySQL 容器查看 metastore 数据库是否已初始化。

# 进入 MySQL 容器
docker exec -it trino-test-mysql mysql -uroot -proot_password

# 执行 SQL 验证
mysql> SHOW DATABASES;
# 预期输出: 包含 metastore 数据库

mysql> USE metastore;
mysql> SHOW TABLES;
# 预期输出: HMS 元数据表列表（如果 HMS 已初始化）

mysql> EXIT;

输出中应包含 metastore。

验证 HMS：检查 9083 端口是否在监听。

# 检查 HMS 端口是否监听
docker exec trino-test-hms netstat -tlnp | grep 9083
# 预期输出: 9083 端口处于 LISTEN 状态

# 或使用 telnet 从宿主机测试
telnet localhost 9083
# 预期输出: Connected to localhost
# 按 Ctrl+] 然后输入 quit 退出

输出 Connection to localhost 9083 port [tcp/*] succeeded! 表示 HMS 已就绪。

验证 Trino Web UI：浏览器访问 http://<宿主机IP>:8080，应进入 Trino Web UI，看到集群状态与查询历史。

3. 使用 Trino 查询 OSS 数据

服务启动并就绪后，通过 Trino CLI 执行 SQL 验证经 OSS V2 Connector 读写 OSS 的全链路是否畅通。本节依次完成连接 Catalog、创建 Schema、读写 CSV/Parquet 三类操作，覆盖元数据与数据面的常见场景。

3.1 进入 Trino CLI

# 方法 A：交互式
docker exec -it trino-test-trino trino

# 方法 B：单条 SQL（适合脚本化）
docker exec trino-test-trino trino --execute "SHOW CATALOGS;"

3.2 验证 Catalog 已加载

-- 查看可用的 Catalog 列表
SHOW CATALOGS;

-- 预期输出:
--  Catalog
-- ---------
--  hive
--  jmx
--  memory
--  system
--  tpcds
--  tpch

输出应包含 hive。若未出现，执行 docker exec trino-test-trino cat /etc/trino/catalog/hive.properties 检查配置文件是否被正确挂载，并执行docker compose logs trino | grep -i error查看 Trino 日志中的错误。

3.3 创建 Schema

将 your-bucket-name 替换为实际 OSS Bucket 名称。

-- 创建 Schema，location 使用 s3a:// 协议
CREATE SCHEMA hive.oss_test
WITH (location = 's3a://your-bucket-name/test/');

-- 验证
SHOW SCHEMAS FROM hive;
-- 预期输出: 包含 oss_test
SHOW CREATE SCHEMA hive.oss_test;
-- 预期输出: 包含 location = 's3a://your-bucket-name/test/'

Schema 创建成功并能查到 location 即说明 Trino 已经能通过 OSS V2 Connector 与 OSS 通信。

3.4 创建外部表、上传数据并查询

先创建外部表，然后将测试数据上传至 OSS，最后通过 SQL 查询。

创建 CSV 格式外部表：

CREATE TABLE hive.oss_test.sample_csv (
  col1 varchar,
  col2 varchar,
  col3 varchar
)
WITH (
  format = 'CSV',
  csv_separator = ',',
  external_location = 's3a://your-bucket-name/test/sample_csv/'
);

DESCRIBE hive.oss_test.sample_csv;

在宿主机上构造测试数据并上传到 OSS：

# 创建本地测试文件
cat > /tmp/test_data.csv << 'EOF'
1,alice,100
2,bob,200
3,charlie,300
EOF

# 使用 ossutil 上传 CSV 测试数据到 OSS（替换为您的 Bucket 名称）
ossutil cp /tmp/test_data.csv \
  oss://your-bucket-name/test/sample_csv/test_data.csv

# 验证上传成功
ossutil ls oss://your-bucket-name/test/sample_csv/

查询数据：

-- 查询数据量
SELECT COUNT(*) FROM hive.oss_test.sample_csv;
-- 预期输出: 3

-- 查询所有数据
SELECT * FROM hive.oss_test.sample_csv;
-- 预期输出:
--  col1 | col2    | col3
-- ------+---------+------
--  1    | alice   | 100
--  2    | bob     | 200
--  3    | charlie | 300

应分别返回 3 与三行数据。

3.5 创建 Parquet 格式表（可选，验证写入链路）

Parquet 是生产环境推荐格式。本步通过 INSERT 验证 Trino 经 OSS V2 Connector 向 OSS 写入数据的链路。

-- 创建 Parquet 格式表（生产环境推荐）
CREATE TABLE hive.oss_test.sample_parquet (
  id bigint,
  name varchar,
  score double
)
WITH (
  format = 'PARQUET',
  external_location = 's3a://your-bucket-name/test/sample_parquet/'
);

-- 插入测试数据
INSERT INTO hive.oss_test.sample_parquet VALUES 
  (1, 'alice', 95.5),
  (2, 'bob', 87.3),
  (3, 'charlie', 92.1);

-- 查询数据
SELECT * FROM hive.oss_test.sample_parquet;

回到宿主机查看 OSS 中新生成的 Parquet 文件：

# 查看 OSS 中生成的文件
ossutil ls oss://your-bucket-name/test/

# 预期输出:
# oss://your-bucket-name/test/sample_csv/test_data.csv
# oss://your-bucket-name/test/sample_parquet/xxxxx.parquet

常见问题排查

下表归纳了部署与查询过程中常见的报错及处置方法。

容器无法启动

现象：docker compose up -d 后某个容器状态变为 Exited。

排查方法：先用 docker compose ps 定位失败容器，再 docker compose logs <容器名> 查看具体错误。常见原因：

错误信息	可能原因	解决方法
`port is already allocated`	端口被占用	修改 `docker-compose.yml` 中的端口映射，如 `"8081:8080"`
`Cannot start service`	网络冲突	执行 `docker compose down` 后重新启动
`exec: "hive": executable file not found`	HMS 镜像问题	确认使用正确的 HMS 镜像

Trino 无法连接 HMS

现象：执行 SHOW SCHEMAS FROM hive 报错 Failed connecting to Hive metastore。

排查方法：

# 1. 检查 HMS 容器是否正常运行
docker compose ps hms

# 2. 检查 HMS 端口是否监听
docker exec trino-test-hms netstat -tlnp | grep 9083

# 3. 检查 Trino 到 HMS 的网络连通性
docker exec trino-test-trino nc -zv hms 9083
# 预期输出: Connection to hms 9083 port [tcp] succeeded!

# 4. 检查 hive.properties 配置
docker exec trino-test-trino cat /etc/trino/catalog/hive.properties
# 确认 hive.metastore.uri=thrift://hms:9083

报错：NoClassDefFoundError

现象：查询报错，例如 java.lang.NoClassDefFoundError: org/apache/commons/collections/CollectionUtils。

原因：JAR 包未正确放置或未挂载到容器内。