Apache Amoro 0.8.1-incubating 配置参数详解

目标：详解 Apache Amoro 0.8.1-incubating AMS 的核心配置——conf/config.yaml（管理员与鉴权、服务端口、元数据库、目录刷新、自优化调度、数据维护）、conf/jvm.properties（JVM 堆 256-512MB）与 conf/log4j2.xml（日志），并给出可直接套用的生产模板。参数与默认值均基于真实环境实测（Ubuntu 22.04 / OpenJDK 11.0.32.1）。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
Java：OpenJDK 11.0.32.1
Apache Amoro：0.8.1-incubating（bin-hadoop3 发行包）
安装目录：/opt/amoro
配置文件目录：/opt/amoro/conf/
服务端口：1630（HTTP）/ 1260（表服务）/ 1261（优化服务）
元数据库：内嵌 derby，数据目录 /opt/amoro/derby
管理账号：admin / q1w2e3r4

二、前置条件

已按《Apache Amoro 0.8.1-incubating 安装指南》完成 AMS 安装并可正常启动。
配置修改后需重启服务生效：systemctl restart amoro-ams，用 systemctl is-active amoro-ams 确认回到 active。

三、参数查看与修改方式

AMS 的行为由 conf/ 下三类文件控制，改前先看清各自的加载机制：

文件	作用	加载方式
`config.yaml`	主配置：账号、端口、元数据库、调度与维护任务	AMS 启动时读入，YAML 键值
`jvm.properties`	JVM 参数：堆、JMX、附加选项	由 `bin/load-config.sh` 解析拼装为 `-Xms/-Xmx` 等参数
`log4j2.xml`	日志输出与滚动策略	经 `-Dlog4j.configurationFile` 传给 JVM
`env.sh`	环境变量覆盖（AMORO_HOME/AMORO_LOG_DIR 等，出厂为空文件）	由 load-config.sh source

查看当前生效配置（去注释后的有效内容）：

grep -vE '^\s*#|^\s*$' /opt/amoro/conf/config.yaml | head -8

ams:
  admin-username: admin
  admin-password: q1w2e3r4
  server-bind-host: "0.0.0.0"
  server-expose-host: "127.0.0.1"
  thrift-server:
    max-message-size: 100MB # 104857600
    selector-thread-count: 2
    selector-queue-size: 4

修改流程统一为：编辑文件 → systemctl restart amoro-ams → 用验证命令复核（每类参数的验证命令见对应小节）。示例（改 HTTP 端口后核对监听）：

systemctl restart amoro-ams
netstat -tlnp | grep 1630

tcp6       0      0 :::1630                 :::*                    LISTEN      4592/java

四、参数总览

参数	默认值（出厂）	说明
`ams.admin-username`	admin	管理员账号，首启初始化进元数据库
`ams.admin-password`	admin	管理员密码（本文改为 q1w2e3r4）
`ams.server-bind-host`	0.0.0.0	服务绑定地址
`ams.server-expose-host`	127.0.0.1	对外暴露地址（写进返回给计算引擎的元数据）
`ams.http-server.bind-port`	1630	Web 控制台 + REST 端口
`ams.http-server.rest-auth-type`	token	REST 鉴权方式：token / basic
`ams.http-server.session-timeout`	7d	Web 会话有效期
`ams.thrift-server.table-service.bind-port`	1260	表服务 Thrift 端口
`ams.thrift-server.optimizing-service.bind-port`	1261	优化服务 Thrift 端口
`ams.thrift-server.max-message-size`	100MB	Thrift 单消息上限
`ams.database.type`	derby	元数据库类型：derby / mysql / postgresql
`ams.database.url`	jdbc:derby:/tmp/amoro/derby;create=true	JDBC 连接串（本文持久化为 /opt/amoro/derby）
`ams.database.connection-pool-max-total`	20	连接池最大连接数
`ams.refresh-external-catalogs.interval`	3min	外部目录元数据刷新周期
`ams.refresh-tables.interval`	1min	表刷新周期
`ams.self-optimizing.commit-thread-count`	10	自优化提交线程数
`ams.optimizer.heart-beat-timeout`	1min	optimizer 心跳超时
`ams.expire-snapshots.enabled`	true	快照过期任务开关
`ams.clean-orphan-files.enabled`	true	孤儿文件清理开关
`ams.data-expiration.enabled`	true	数据过期任务开关
`ams.terminal.session.timeout`	30min	Web SQL 终端会话超时
`containers[0].name`	localContainer	本地 optimizer 容器（可选功能）
`jvm.properties: xms / xmx`	8196 / 8196	堆初始/最大值（本文 256/512）

关键解读：日常运维最常改的是「管理员密码、HTTP 端口、元数据库、JVM 堆」四类；调度与维护类参数出厂默认已适配大多数场景，湖仓规模上万表时才需要上调线程数。

五、核心参数分类详解

5.1 管理员与安全参数

首次启动时，AMS 用 admin-username/admin-password 初始化管理员账号并写入元数据库，Web 控制台与 REST 认证都基于它：

ams:
  admin-username: admin
  admin-password: q1w2e3r4
  http-server:
    session-timeout: 7d
    rest-auth-type: token
  shade:
    identifier: default
    sensitive-keywords: admin-password;database.password

参数	取值说明
`admin-username` / `admin-password`	出厂 admin/admin，必须改强口令；首启落库后作为 Web 登录与 Basic 认证凭据
`rest-auth-type`	`token`（默认）：API 调用需 apiKey+signature 签名；`basic`：直接用 HTTP Basic（账号即 admin-username/password）
`session-timeout`	Web 会话有效期，默认 7d
`shade.identifier`	敏感信息加密方式：default（不加密）/ base64
`shade.sensitive-keywords`	命中这些关键词的配置值（如各 catalog 密码）按 identifier 方式加密存储

验证：切换为 basic 后用 curl 复核（实测）：

curl -s -u admin:q1w2e3r4 http://127.0.0.1:1630/api/ams/v1/catalogs

{"message":"success","code":200,"result":[]}

不携带认证或密码错误时的实测回显：

{"message":"Invalid basicauth header. Value was 'null'.","code":500,"requestId":""}
{"message":"Signature check failed","code":403,"requestId":""}

5.2 服务端口与绑定参数

ams:
  server-bind-host: "0.0.0.0"
  server-expose-host: "127.0.0.1"
  thrift-server:
    max-message-size: 100MB
    selector-thread-count: 2
    selector-queue-size: 4
    table-service:
      bind-port: 1260
      worker-thread-count: 20
    optimizing-service:
      bind-port: 1261
  http-server:
    bind-port: 1630

参数	默认值	说明
`server-bind-host`	0.0.0.0	监听所有网卡；只允许本机访问可改 127.0.0.1
`server-expose-host`	127.0.0.1	返回给计算引擎的 AMS 地址；跨机接入 Iceberg/Flink 时必须改为本机对外 IP
`http-server.bind-port`	1630	Web + REST 端口
`table-service.bind-port`	1260	Iceberg/mixed-format 表读写接入的 Thrift 端口
`optimizing-service.bind-port`	1261	optimizer 心跳与任务领取的 Thrift 端口
`max-message-size`	100MB	单条 Thrift 消息上限，超大 schema 时上调
`worker-thread-count`	20	表服务工作线程数

验证：三端口监听 + 免登录版本接口（实测）：

netstat -tlnp | grep java | grep -E '1630|1260|1261'
curl -s http://127.0.0.1:1630/api/ams/v1/versionInfo

tcp6       0      0 :::1630                 :::*                    LISTEN      4592/java
tcp6       0      0 :::1260                 :::*                    LISTEN      4592/java
tcp6       0      0 :::1261                 :::*                    LISTEN      4592/java
{"message":"success","code":200,"result":{"version":"0.8.1-incubating(bc906c0)","commitTime":"2025-08-28T08:55:33+0800"}}

5.3 元数据库参数（database）

ams:
  database:
    type: derby
    jdbc-driver-class: org.apache.derby.jdbc.EmbeddedDriver
    url: jdbc:derby:/opt/amoro/derby;create=true
    connection-pool-max-total: 20
    connection-pool-max-idle: 16
    connection-pool-max-wait-millis: 30000

参数	默认值	说明
`type`	derby	derby / mysql / postgresql（驱动均随包内置）
`jdbc-driver-class`	org.apache.derby.jdbc.EmbeddedDriver	切换外部库时改为对应驱动类
`url`	jdbc:derby:/tmp/amoro/derby;create=true	derby 建库路径（`;create=true` 目录必须不存在）；MySQL/PostgreSQL 换对应 JDBC URL
`connection-pool-max-total`	20	连接池上限
`connection-pool-max-idle`	16	空闲连接数
`connection-pool-max-wait-millis`	30000	获取连接最长等待

💡 技术拓展：元数据库不止内嵌 derby 一种，常见选型对比——

类型特点适用场景
derby（内嵌）零外部依赖、单进程独占、无网络开销试用、POC、单机小规模
MySQL 独立部署、易备份、生态成熟生产推荐，多实例共享一套元数据
PostgreSQL 同为外置关系库、事务更强已有 PG 运维体系的团队

本文演示环境用默认 derby（零依赖启动）；生产建议切换 MySQL（初始化 SQL 位于 conf/mysql/ams-mysql-init.sql）。

类型	特点	适用场景
derby（内嵌）	零外部依赖、单进程独占、无网络开销	试用、POC、单机小规模
MySQL	独立部署、易备份、生态成熟	生产推荐，多实例共享一套元数据
PostgreSQL	同为外置关系库、事务更强	已有 PG 运维体系的团队

验证：derby 数据目录在首启后生成（实测）：

ls /opt/amoro/derby/

README_DO_NOT_TOUCH_FILES.txt  db.lck  dbex.lck  log  seg0  service.properties

5.4 目录与表刷新参数

ams:
  refresh-external-catalogs:
    interval: 3min
    thread-count: 10
    queue-size: 1000000
  refresh-tables:
    thread-count: 10
    interval: 1min
    max-pending-partition-count: 100
  catalog-meta-cache:
    expiration-interval: 60s
  table-manifest-io:
    thread-count: 20

参数	默认值	说明
`refresh-external-catalogs.interval`	3min	周期性同步外部 catalog（Hive/HDFS 等）发现新库表
`refresh-tables.interval`	1min	已纳管表的自优化状态刷新周期
`refresh-tables.max-pending-partition-count`	100	单表单次刷新待处理分区上限
`catalog-meta-cache.expiration-interval`	60s	catalog 元数据缓存过期时间
`table-manifest-io.thread-count`	20	读取表 manifest 文件的线程池

要点：湖仓表数量大（数万级）时优先上调两个 thread-count 并适当放宽 interval，避免刷新任务排队拖慢优化调度。

5.5 自优化调度参数

ams:
  self-optimizing:
    commit-thread-count: 10
    runtime-data-keep-days: 30
    runtime-data-expire-interval-hours: 1
    refresh-group-interval: 30s
  optimizer:
    heart-beat-timeout: 1min
    task-ack-timeout: 30s
    task-execute-timeout: 1h
    polling-timeout: 3s
    max-planning-parallelism: 1
  blocker:
    timeout: 1min

参数	默认值	说明
`self-optimizing.commit-thread-count`	10	优化结果提交 Iceberg 的并发线程
`self-optimizing.runtime-data-keep-days`	30	优化过程数据（任务明细）保留天数
`optimizer.heart-beat-timeout`	1min	optimizer 心跳超时即判离线
`optimizer.task-ack-timeout`	30s	任务领取确认超时后重新调度
`optimizer.task-execute-timeout`	1h	单任务执行上限
`optimizer.max-planning-parallelism`	1	计划（planning）并行度
`blocker.timeout`	1min	表级阻塞器超时（防止并发提交冲突）

⚠️ optimizer（执行器）对接 Flink/Spark/YARN 属可选高级功能，需要额外计算资源；AMS 自带的 localContainer（见 5.8）可在本机拉起独立 optimizer 进程，功能验证够用，生产规模建议外置 Flink/Spark optimizer。

5.6 数据维护任务参数

ams:
  expire-snapshots:
    enabled: true
    thread-count: 10
  clean-orphan-files:
    enabled: true
    thread-count: 10
    interval: 1d
  clean-dangling-delete-files:
    enabled: true
    thread-count: 10
  sync-hive-tables:
    enabled: false
    thread-count: 10
  data-expiration:
    enabled: true
    thread-count: 10
    interval: 1d
  auto-create-tags:
    enabled: true
    thread-count: 3
    interval: 1min

任务	默认	作用
`expire-snapshots`	true	过期 Iceberg 快照，回收历史版本
`clean-orphan-files`	true（每天）	清理未被引用的孤儿数据文件
`clean-dangling-delete-files`	true	清理悬空的 delete 文件
`data-expiration`	true（每天）	按 TTL 删除过期业务数据
`sync-hive-tables`	false	同步 Hive 外部表结构变更
`auto-create-tags`	true	按周期自动生成快照标签

⚠️ clean-orphan-files 与 data-expiration 直接删数据文件，接入生产存量表前先在测试表验证删除规则，避免误删。

5.7 Web 终端与控制台缓存参数

ams:
  terminal:
    backend: local
    result:
      limit: 1000
    stop-on-error: false
    session:
      timeout: 30min
  overview-cache:
    refresh-interval: 3min
    max-size: 3360

参数	默认值	说明
`terminal.backend`	local	Web SQL 终端执行引擎（local 为内置 Spark local）
`terminal.result.limit`	1000	单次查询返回行数上限
`terminal.session.timeout`	30min	终端会话空闲回收
`overview-cache.refresh-interval`	3min	首页 Overview 指标刷新周期
`overview-cache.max-size`	3360	指标历史保留条数（默认 7 天 × 每天 480 点）

5.8 optimizer 容器参数（containers）

containers:
  - name: localContainer
    container-impl: org.apache.amoro.server.manager.LocalOptimizerContainer
    properties:
      export.JAVA_HOME: "/usr/lib/jvm/java-11-openjdk-amd64"   # JDK environment

参数	说明
`name`	optimizer 容器名，创建优化器组时引用
`container-impl`	容器实现：LocalOptimizerContainer（本机进程）/ KubernetesContainer（出厂注释块中提供）
`export.JAVA_HOME`	拉起本地 optimizer 进程用的 JDK；出厂占位 `/opt/java` 必须改成真实路径

⚠️ 本节属可选高级功能：不创建优化器组时 AMS 照常运行（实测 overview/summary 返回 totalCpu/totalMemory 均为 0）。对接 Flink/Spark optimizer 时才需要修改本节。

5.9 JVM 参数（jvm.properties）

bin/load-config.sh 启动时解析该文件拼装 JVM 参数，出厂堆为 8GB，小规格部署必须下调：

xms=256
xmx=512
jmx.remote.port=
extra.options="-XX:NewRatio=1 -XX:SurvivorRatio=3 -XX:+ExitOnOutOfMemoryError"

参数	出厂值	本文值	说明
`xms`	8196	256	拼为 `-Xms{n}m`
`xmx`	8196	512	拼为 `-Xmx{n}m`，空表/小表场景 512MB 足够
`jmx.remote.port`	空	空	设置后开放 JMX 远程端口
`extra.options`	NewRatio=1 等	保留	附加 JVM 选项；`ExitOnOutOfMemoryError` 保证 OOM 时进程退出由 systemd 重拉

重启后用 jps -v 验证实际生效值（实测）：

jps -lv | grep AmoroServiceContainer | grep -oE '\-Xms[0-9]+m -Xmx[0-9]+m'

-Xms256m -Xmx512m

5.10 日志配置（log4j2.xml）

日志输出到 AMORO_LOG_DIR（默认 /opt/amoro/logs/），四个 RollingFile appender：

Appender	文件	说明
`debugFileAppender`	`ams-debug.log`	调试日志（Root 中默认注释未启用）
`infoFileAppender`	`ams-info.log`	主日志，按日期滚动到 `history/`
`errorFileAppender`	`ams-error.log`	错误日志，排障第一入口
`amoroMetricReporter`	`amoro-metrics.log`	Iceberg 指标日志

Root level 为 debug，但仅挂了 info 与 error appender；打开 debug 输出需取消 debugFileAppender 的 AppenderRef 注释。GC 日志固定输出到 logs/gc.log（ams.sh 内置参数）。日志目录可经 env.sh 写入 export AMORO_LOG_DIR=/var/log/amoro 整体迁移。

六、生产配置模板

适用场景：4 核 16GB 内存、NVMe SSD、纳管数千张 Iceberg 表、元数据库外置 MySQL 的单实例 AMS。

ams:
  admin-username: admin
  admin-password: q1w2e3r4            # 上线前务必改为强口令
  server-bind-host: "0.0.0.0"
  server-expose-host: "10.0.0.10"     # 本机对外 IP，供计算引擎回连
  http-server:
    bind-port: 1630
    rest-auth-type: basic             # 脚本化集成用 basic 更简单
    session-timeout: 7d
  thrift-server:
    table-service:
      bind-port: 1260
      worker-thread-count: 40         # 表数量大时上调
    optimizing-service:
      bind-port: 1261
  refresh-external-catalogs:
    interval: 3min
    thread-count: 10
  refresh-tables:
    thread-count: 20                  # 数千表上调线程
    interval: 1min
  self-optimizing:
    commit-thread-count: 10
  optimizer:
    heart-beat-timeout: 1min
    task-execute-timeout: 1h
  database:
    type: mysql                       # 生产用 MySQL
    jdbc-driver-class: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://10.0.0.20:3306/amoro?useUnicode=true&characterEncoding=UTF8&useSSL=false
    connection-pool-max-total: 20
  terminal:
    session:
      timeout: 30min
containers:
  - name: localContainer
    container-impl: org.apache.amoro.server.manager.LocalOptimizerContainer
    properties:
      export.JAVA_HOME: "/usr/lib/jvm/java-11-openjdk-amd64"

配套 jvm.properties（16GB 内存机器，AMS 独占约 4GB 时）：

xms=2048
xmx=4096
jmx.remote.port=
extra.options="-XX:NewRatio=1 -XX:SurvivorRatio=3 -XX:+ExitOnOutOfMemoryError"

说明：本模板在 512MB 小堆（xms=256/xmx=512）下已实测可稳定启动并服务控制台/REST；上表加大堆与线程是面向数千表规模的经验值，上线后按 ams-info.log 刷新耗时与 gc.log 回收表现微调。

七、常见问题

7.1 修改配置后不生效

现象：改了 config.yaml 或 jvm.properties，行为仍是旧值。

定位：AMS 只在启动时读配置，运行中不会热加载；systemd 场景下还需确认改动的是 /opt/amoro/conf/ 下的真实文件。

解决：重启并复核：

systemctl restart amoro-ams
systemctl is-active amoro-ams
jps -lv | grep AmoroServiceContainer | grep -oE '\-Xms[0-9]+m -Xmx[0-9]+m'

active
-Xms256m -Xmx512m

7.2 derby 报 Directory already exists

现象：ams-error.log 出现：

java.sql.SQLException: Cannot create PoolableConnectionFactory (Failed to create database '/opt/amoro/derby', see the next exception for details.)
Caused by: org.apache.derby.iapi.error.StandardException: Directory /opt/amoro/derby already exists.

定位与解决：;create=true 首次建库时目标目录必须不存在。若该目录是空目录（手工预建或被其他程序创建），删除后重启；若目录内已有 seg0、service.properties 则是正常库目录，直接启动即可，不要清空已有数据。

7.3 修改管理员密码的正确方式

AMS 每次启动都会以 config.yaml 中的 admin-username/admin-password 同步管理员凭据，因此改密码只需两步：改配置、重启。实测（先改配置再重启）：

sed -i 's/admin-password: q1w2e3r4/admin-password: admin123/' /opt/amoro/conf/config.yaml
systemctl restart amoro-ams

新密码登录成功、旧密码被拒绝（实测回显）：

{"message":"success","code":200,"result":"success"}
{"message":"invalid user admin or password!","code":500,"requestId":""}

⚠️ 出厂默认 admin/admin 属弱口令，首次启动前务必按《安装指南》4.4 改为强口令；改完密码记得同步更新所有使用该账号的脚本。

7.4 API 调用报 Signature check failed

现象：curl 直调受保护接口返回：

{"message":"Signature check failed","code":403,"requestId":""}

定位与解决：默认 rest-auth-type: token 要求 apiKey+signature 签名参数；改用 basic 模式最简单：

sed -i 's/rest-auth-type: token/rest-auth-type: basic/' /opt/amoro/conf/config.yaml
systemctl restart amoro-ams
curl -s -u admin:q1w2e3r4 http://127.0.0.1:1630/api/ams/v1/catalogs

{"message":"success","code":200,"result":[]}

7.5 切换 MySQL 元数据库后启动报驱动/连接错误

定位：常见三类——URL 未带时区/SSL 参数、MySQL 8 需 allowPublicKeyRetrieval=true、账号无建表权限（AMS 首启会执行 conf/mysql/ams-mysql-init.sql 建表）。

解决：按出厂注释中的 URL 形态书写（实测出厂模板原样）：

url: jdbc:mysql://127.0.0.1:3306/db?useUnicode=true&characterEncoding=UTF8&autoReconnect=true&useAffectedRows=true&allowPublicKeyRetrieval=true&useSSL=false

并确认账号对目标库有 CREATE/ALTER 权限后重启。

八、参考链接

官方配置文档：https://amoro.apache.org/docs/latest/managing/configuration/
AMS 部署文档：https://amoro.apache.org/docs/latest/deployment/
下载页：https://downloads.apache.org/incubator/amoro/