作者：吴金玲
爱可生 dble 项目团队成员，主要负责 dble 相关的日常测试工作，擅长对 dble 中出现的问题进行排查。热爱测试工作，余生欲将测试工作进行到底。
本文来源：原创投稿
*爱可生开源社区出品，原创内容未经授权不得随意使用，转载请联系小编并注明来源。
本文谨献给 dble 的新粉。在初次使用 dble 的时候，新手们经常会遭遇 dble 启动失败的情况，而且启动失败一般都是由于配置不正确导致的。众所周知，dble 启动失败了，我们可以去 wrapper.log 里面查找启动失败的原因，并且可喜的是一般都能从 wrapper.log 里很直观的找到启动失败的原因。但少数启动失败的原因就不是那么直观，要想快速的定位及解决问题，那就需要我们对dble启动时具体都做了些什么有所了解。本文以 3.22.01.0 版本为例，简单介绍一下 dble 在启动的时候是如何对配置文件的正确性进行校验的。
具体如何配置请参考 dble 的官方文档：https://actiontech.github.io/dble-docs-cn/1.config_file/1.00_config_file.html 。
一、首先让我们简单了解一下 dble 都有哪些配置文件，以及他们的主要作用是什么
下载 3.22.01.0 版本的安装压缩包，解压后进入 dble 安装目录的根目录，里面有个 conf 的配置文件目录（常用的配置文件里面都有模板文件），从配置文件目录可知，dble 主要分为4种类型的配置文件（.cnf、.xml、.properties、.txt），每个配置文件的主要作用如下表：
文件名 | 主要作用 | 注意点 | 参考链接 |
|---|---|---|---|
cluster.cnf | 集群参数配置文件 | 修改此文件需要停止多个dble实例，重新初始化集群元数据，然后再逐个启动dble | https://actiontech.github.io/dble-docs-cn/1.config_file/1.01_cluster.cnf.html |
bootstrap.cnf | dble实例启动时加载的系统参数配置文件 | 文件分为两部分，第一部分为JVM启动参数，第二部分为dble系统参数 | https://actiontech.github.io/dble-docs-cn/1.config_file/1.02_bootstrap.cnf.html |
bootstrap.dynamic.cnf | 一般为可以通过管理命令热生效的系统参数 | 当dble重启时会替换bootstrap.cnf中对应的值来生效配置 | https://github.com/actiontech/dble-docs-cn/blob/master/1.config_file/1.02_bootstrap.cnf.md |
user.xml | 登录用户配置文件（dble主要分四种用户） | 主要注意sql权限和ip白名单的配置 | https://actiontech.github.io/dble-docs-cn/1.config_file/1.03_user.xml.html |
db.xml | 后端数据库和组的配置文件 | 为了dble能正常工作，后端MySQL用户需开启特定的权限 | https://actiontech.github.io/dble-docs-cn/1.config_file/1.04_db.xml.html |
sharding.xml | 虚拟库、表、算法的配置文件 | 注意全局序列的配置方法 | https://actiontech.github.io/dble-docs-cn/1.config_file/1.05_sharding.xml.html |
sequence_conf.propertie | 分布式offset-step方式的全局序列配置文件 | 结合cluster.cnf配置，sequenceHandlerType=4 | https://actiontech.github.io/dble-docs-cn/1.config_file/1.7_global_sequence/1.7.4_distribute_offset-step.html |
sequence_db_conf.properties | MySQL-offset-step方式的全局序列配置文件 | 结合cluster.cnf配置，sequenceHandlerType=1 | https://actiontech.github.io/dble-docs-cn/1.config_file/1.7_global_sequence/1.7.1_MySQL-offset-setp.html |
.txt文件 | 不同分片算法对应的配置文件 | 常用，需要时可参照文档配置 | https://actiontech.github.io/dble-docs-cn/1.config_file/1.05_sharding.xml.html |
log4j2.xml | 日志归档规则及日志记录级别配置 | 当出错时可将日志级别调整为debug来定位详细的错误信息 | https://actiontech.github.io/dble-docs-cn/1.config_file/1.06_log4j2.xml.html |
cacheservice.properties | dble的cache的总配置文件 | 不常用，需要时可自行参照文档配置 | https://actiontech.github.io/dble-docs-cn/1.config_file/1.8_cache/1.8.1_cache_setting.html |
ehcache.xm | dble的缓存实现配置文件 | 不常用，需要时可自行参照文档配置 | https://actiontech.github.io/dble-docs-cn/1.config_file/1.8_cache/1.8.2_ehcache_setting.html |
$DBLE_HOME/lib目录下jar包 | 自定义拆分算法文件 | 不常用，需要时可自行参照文档配置 | https://actiontech.github.io/dble-docs-cn/1.config_file/1.09_dble_route_function_spec.html |
dble_alert.properties | 自定义告警配置文件 | 不常用，需要时可自行参照文档配置 | https://actiontech.github.io/dble-docs-cn/1.config_file/1.11_customized_alert.html |
二、下面通过列举几个新粉经常遇到的 dble 启动失败的例子，来说明 dble 在加载配置文件时做了哪些检测
1.首先以以下 boostrap.cnf 配置为例启动 dble (其他配置文件请按需配置，此处省略)：
进入 dble 安装的根目录，执行 dble 启动命令 bin/dble start ，然后执行 bin/dble status 查看 dble 的状态，发现启动失败了：
进入 wrapper.log 中查看，发现报错如下：
从日志中可以看出，报错是由于22端口被占用。这是由于 dble 在启动的时候会初始化一个虚拟机，从 bootstrap.cnf 读取 JVM 参数。dble 启动过程中会占用三个端口：业务端口（默认8066），管理端口（默认9066），jvm 对外提供 jmx 服务端口，所以配置的时候这三个端口不能相同，且不能被其他程序占用。具体参考：https://actiontech.github.io/dble-docs-cn/A.Faq/ErrorCode/Content/PortAlreadyInUse1984.html 。所以将端口改为未被占用的端口即可启动成功。
2.再以以下 boostrap.cnf 配置启动(其他配置文件请按需配置，此处省略)：
发现 dble 启动报错，报错信息如下：
从日志中可以看出，此处有4个错误：
- -D与参数名“NIOFrontRW”之间有个空格，这不符合JSW对配置文件的要求，也就是不能有空格，具体请参见 https://wrapper.tanukisoftware.com/doc/english/prop-app-parameter-n.html#file；
- sqlExecuteTimeout的属性值类型错误，此处应该是long类型，错配成了字符类型，将“30s”改成“30”即可；
- 误将“frontWorker”写成了“frontWorkers”。注意，bootstrap.cnf文件里的属性名要严格按照文档里的写法，大小写也需要严格一致，否则报错；
- fakeMySQLVersion的值不正确，将“5.7”改写成“5.7.26”即可。
3.针对 xml 文件，dble 启动时同样也会对配置文件格式、属性名、属性值、属性类型等做校验，此处不再赘述。另外，针对 db.xml ，dble 在启动时还会对后端 MySQL 节点的可连接性做检测，还会获取所有后端 MySQL 节点的版本号和大小写敏感参数值。
dble 用以下 db.xml 配置启动(其他配置文件请按需配置，此处省略)：
发现 dble 启动失败，检查 wrapper.log 日志，发现如下错误：
这个错误表示后端 MySQL 节点连接检测失败。针对这种报错，一般常见的排查手法就是用 MySQL 客户端按照配置里的连接参数登录后端 MySQL 节点，如下：
此处是由于连接端口配置错误，将数据库的连接端口“3306”修改成“3307”即可启动成功。这种报错还有可能是用户和密码不对，也有可能是用户没有权限，具体可能原因及解决办法请对照参考：https://actiontech.github.io/dble-docs-cn/A.Faq/ErrorCode/Content/Can'tGetVariablesFromShardingNode.html。
4.dble 用以下 db.xml 配置启动(其他配置文件请按需配置，此处省略)：
dble 启动报错，wrapper.log 中报错如下：
以上报错说明后端 MySQL 节点大小写敏感参数值不一致。dble 启动时，会根据 db.xml 的配置，获取所有节点的大小写敏感参数值，dble 要求此参数值在所有 MySQL 节点中必须保持一致，否则报错。将 hostM1 中的大小写改成敏感后 dble 即可启动成功。
5.dble 用以下 bootstrap.cnf 配置启动(其他配置文件请按需配置，此处省略)：
发现 dble 启动失败，且 wrapper.log 里报如下错误：
错误提示 dble 里配置的 version 值高于后端节点的版本值。这是由于 dble 在启动时会获取 db.xml 里配置的所有节点的 MySQL 版本，然后和 bootstrap.cnf 里配置的 fakeMySQLVersion 进行比较，要求配置的 fakeMySQLVersion 的值不能高于后端 MySQL 节点的最低版本号，否则报错。
除了以上列举的例子外，dble 还会对其他配置文件做各自特殊的校验，比如分片算法正确性，用户类型和实例组的正确配对，maxPacketSize 同步等等，由于篇幅原因，本文不再一一举例，因为一般 dble 启动失败都可以通过 wrapper.log 里的错误提示得到解决。
简单总结来说就是，dble 在启动的时候会对所有配置文件进行合法性校验，包括配置文件的格式，属性名，属性类型、属性值等。还会对后端 MySQL 节点做可连性测试，大小写一致性检测，fakeMySQLVersion 合法性检测，maxPacketSize 同步等。还会校验各配置文件之间是否正确配置等等。
