[Step1]本机运行方案与环境补齐
# 一、说明
本文记录 Ambari Server 在本机启动前的环境补齐方案。
在本地做源码级调试时，最容易遇到的情况不是代码本身有问题，而是运行环境缺文件、缺目录、缺配置，导致程序还没进入真正的业务逻辑就提前失败。
这类问题如果不先处理干净，后面无论是接 PyCharm、debugpy，还是直接打断点、跟日志，都会被一堆前置报错打断。
本文以 dev1.test.com 作为演示环境，实际使用时请替换成你自己的服务器地址、数据库账号和密码。
本章先把 Ambari Server 本机调试过程中最常缺的几样内容补齐：
- MariaDB 远程授权
version文件- 运行时目录
- 数据库密码文件
- SSL keystore
本章定位
这一部分解决的是 “先把 Ambari Server 跑起来” 的问题。
只有把这些基础依赖补齐，后续的断点调试、远程附加、日志跟踪才有意义。
# 二、MariaDB 远程授权（首次配置）
Ambari Server 本地启动后，通常不会直接连本地数据库，而是连接已经准备好的远端 MariaDB。
因此第一步要先确保数据库允许远程访问，否则程序初始化阶段就会卡在 JDBC 连接这里。
# 1、登录数据库服务器并授权
SSH 登录数据库服务器后，执行如下命令：
ssh root@dev1.test.com
mysql -uroot -proot
2
进入 MariaDB 后执行授权语句：
GRANT ALL PRIVILEGES ON ambari.* TO 'root'@'%' IDENTIFIED BY 'root';
FLUSH PRIVILEGES;
EXIT;
2
3
# 2、验证远程连通性
授权完成后，不要急着启动 Ambari，先在本机把连接测通：
mysql -h dev1.test.com -P 3306 -uroot -proot ambari \
-e "SELECT metainfo_value FROM metainfo WHERE metainfo_key='version';"
# 应返回: 3.0.0
2
3
# 3、这一项为什么必须先做
如果数据库授权没配好，本地调试时常见现象有这些：
| 现象 | 本质原因 | 排查方向 |
|---|---|---|
| 启动早期直接报数据库连接失败 | 用户无远程权限 | 检查 GRANT 是否生效 |
| 用户名密码明明没错仍无法连接 | 主机访问范围不对 | 检查是否为 'root'@'%' |
| 本地能 ping 通但程序仍失败 | 3306 未放通或 JDBC 参数有误 | 检查端口、防火墙、连接串 |
| 偶发连通、偶发失败 | DNS 或主机名解析不一致 | 优先确认 /etc/hosts 与数据库地址 |
注意
这里演示使用的是 root/root，仅适合本地调试或测试环境。
生产环境建议单独创建 Ambari 专用账号，并限制来源地址。
# 三、创建 version 文件（首次配置）
Ambari 在启动过程中会读取：
ambari-server/src/main/resources/version
这个文件用于标识当前运行版本。 如果缺少它，很多初始化逻辑虽然表面看起来和版本无关，但实际都会在读取版本号时出现连锁问题。
# 1、创建 version 文件
echo -n "3.0.0" > ambari-server/src/main/resources/version
# 2、为什么不能忽略
这个文件虽然很小，但它属于 启动基础输入。 没有它时，常见结果通常不是直接给出一个特别明确的错误，而是在后续初始化流程中出现各种不容易第一眼看出来的异常。
建议
version 文件建议直接和当前源码分支保持一致。
例如你当前调试的是 3.0.0 代码，就明确写 3.0.0，不要随手写成别的值。
# 3、快速检查方式
cat ambari-server/src/main/resources/version
# 应输出：3.0.0
2
如果这里没有内容，或者末尾多写了空格、换行异常，最好重新覆盖一次。
# 四、创建运行时目录和文件（首次配置）
Ambari Server 本地运行时，不只是读取源码目录里的文件，还会依赖一批运行态目录和临时文件。 这些目录如果不存在，程序在读取密码、写日志、加载证书时都会报错。
项目里通常已经有 local-dev/，并且一般加入了 gitignore。
这里还需要补齐 local-runtime/ 下面的运行目录。
# 1、创建基础目录
mkdir -p local-runtime/keys local-runtime/data local-runtime/logs
建议先确认目录结构已经生成：
tree local-runtime
期望结构类似下面这样：
local-runtime
├── data
├── keys
└── logs
2
3
4
# 2、目录各自的作用
| 目录 | 作用 |
|---|---|
local-runtime/keys | 存放 keystore、密码文件等密钥材料 |
local-runtime/data | 存放本地运行过程中产生的数据文件 |
local-runtime/logs | 存放本地启动日志、调试日志 |
实战经验
本地调试时，把运行态文件统一放到 local-runtime/ 下，最大的好处就是好清理、好重建。
环境脏了以后，直接删掉整个目录再重建，定位问题会轻松很多。
# 五、数据库密码文件
这一项是本地调试里最容易踩坑的点之一。
Ambari 的部分配置不是直接把密码写在属性值里，而是把属性值当成 密码文件路径 去读。
也就是说，server.jdbc.user.passwd 对应的并不是明文密码，而是一个文件地址。
# 1、创建密码文件
echo -n "root" > local-runtime/db-password.txt
# 2、为什么必须用 -n
这里必须使用 echo -n，目的是 避免末尾写入换行符。
如果文件里多了一个 \n，有些场景下读取出来的密码就会变成错误值，排查起来非常浪费时间。
# 3、验证密码文件内容
先看可读内容：
cat local-runtime/db-password.txt
# 应输出：root
2
再看十六进制，确保末尾没有换行：
cat local-runtime/db-password.txt | xxd | head -1
# 00000000: 726f 6f74 root
2
# 4、这一项不对时会发生什么
如果密码文件不存在，或者路径配错，程序可能不会立刻报“找不到密码文件”，而是继续走默认逻辑。
在不少场景里，它会回退到默认密码 bigdata，最终表现为数据库认证失败。
高发误区
最容易误判的情况是： 你看到数据库报 “Access denied”，第一反应以为是数据库授权没配好，实际上可能只是 程序根本没读到你准备的密码文件。
# 六、SSL Keystore
如果本地调试过程中会走到 HTTPS、证书校验、Web 容器初始化等逻辑，那么 keystore 也要提前准备好。 否则程序可能在网络层、证书层直接失败，根本进不到后续业务代码。
# 1、创建 keystore 密码文件
echo -n "changeit" > local-runtime/keys/pass.txt
# 2、生成自签名 PKCS12 keystore
keytool -genkeypair \
-alias ambari-server \
-keyalg RSA -keysize 2048 -validity 3650 \
-storetype PKCS12 \
-keystore local-runtime/keys/keystore.p12 \
-storepass changeit \
-dname "CN=localhost, OU=Ambari, O=Apache, L=Local, ST=Dev, C=US" \
-ext "SAN=dns:localhost,ip:127.0.0.1"
2
3
4
5
6
7
8
# 3、验证 keystore 是否生成成功
keytool -list -keystore local-runtime/keys/keystore.p12 \
-storetype PKCS12 -storepass changeit
# 应显示: ambari-server, ...PrivateKeyEntry
2
3
# 4、为什么这里推荐 PKCS12
相较于旧格式，PKCS12 在本地开发环境里更通用，兼容性也更好。
配合 keytool 生成和查看都比较直接，适合本地快速起环境。
证书字段说明
这里的 CN=localhost、SAN=dns:localhost,ip:127.0.0.1，是为了适配本机调试场景。
如果你后续通过其他主机名或 IP 访问本地启动的服务，可以把 SAN 一并补进去。