简介mycat2 install-template 是一份面向 MyCat 2 数据库中间件的安装模板包主要帮助开发者和运维人员在部署分布式数据库时快速获得可复用的配置与启动环境。压缩包体积仅 1.19MB共包含 52 个文件类型以 SQL 脚本、JSON 配置、跨平台动态库和启停脚本为主SQL 用于初始化分片与表结构JSON 保存服务与数据源等核心参数动态库则覆盖不同操作系统的兼容性配套脚本负责服务的启动与关闭。这样的结构贴近实际生产目录能减少手工整理依赖的时间同时为后续二次开发保留清晰入口。目前已有 640 人学习浏览适合刚接触 MyCat 分库分表、读写分离的初学者也适合需要快速搭建验证环境的中间件使用者。通过调整包内核心配置即可得到一个可运行的 MyCat 2 实例便于继续理解数据分片规则、SQL 路由以及读写分离机制。1. mycat2 install-template 是什么拿到的是一套能跑的地基不是成品第一次接触 Mycat2 的团队最容易在安装环节卡住jar 包缺一个、classpath 配错、启动脚本没有执行权限、logs 目录没生成最后都变成“中间件跑不起来”。mycat2 install-templatemycat2-install-template-1.21.zip反而不是那个成品它是一套已经整理好的最小运行骨架把 Java 进程、默认监听端口、日志目录和基础配置占位符都固定好了。你解压后要做的不是从头搭建环境而是把模板里的默认数据源、逻辑库和账号改成自己的业务连接。这套模板适合两类人一类是第一次部署 Mycat2 的后端工程师想先看到 8066 端口真正弹出来另一类是已经在其他环境上有分库分表经验的 DBA想用一个干净模板快速验证新版本的配置行为。反直觉的一点是模板默认能启动但启动成功不代表能查询你的业务数据它和你的真实库之间还差一次数据源配置。2. 用 install-template 在本地跑通最小 mycat2解压、改配置、启动连接2.1 模板目录里都有什么先认文件再动手把 mycat2-install-template-1.21.zip 解压后不要急着执行任何脚本先看一遍目录。模板核心结构一般就是bin/、conf/、lib/、logs/这四个位置bin/下是启动和停止脚本conf/下是 mycat 运行时的 YAML 配置lib/放着中间件本身和依赖的 JDBC 驱动logs/在启动后生成运行日志。常见做法是解压到/opt/mycat2这类固定路径因为模板里的相对路径脚本依赖当前工作目录挪动到带空格或中文的路径下容易出怪问题。unzip mycat2-install-template-1.21.zip -d /opt/mycat2 cd /opt/mycat2 ls -lh解压后先确认bin目录里的脚本有执行权限。很多从 Windows 解压再传到 Linux 的场景脚本会丢 x 权限直接执行会报 Permission denied。如果ls看到-rw-r--r--先补上执行权限再继续。chmod x bin/*这时候不要急着打开所有 YAML 文件。优先看conf/mycat.yml和conf下的 schema 目录这两个地方决定中间件监听什么端口、连哪个后端库、对外暴露哪些逻辑库。模板的价值就在这里它不是让你从零写配置而是让你在已有默认值上改名字、改地址、改密码。最典型的翻车操作是直接删掉模板自带的示例配置重写结果把prototype数据源删了启动后日志里报找不到默认连接。2.2 改配置前必须理解的两个端口和三个角色Mycat2 的模板启动后通常监听两个端口一个是面向业务连接的客户端端口默认 8066前端应用、Java 代码、命令行 mysql 客户端都通过它执行 SQL另一个是管理端口默认 9066用于执行数据源、逻辑库、逻辑表等在线管理指令。两个端口分离是 Mycat2 和传统单端口代理的重要区别日常业务查询走 8066初始化分片环境走 9066互不干扰。三段角色关系也在这个阶段理清最底下是真实物理库比如 MySQL 的多个实例或同一个实例下的多个 database中间是 Mycat2 进程它对上假装是一个 MySQL 服务对下持有多个后端数据源的连接池最上面是业务应用只看到逻辑库和逻辑表。模板默认只给你一个后端连接占位所以目录里看着是“完整配置”实际是“一个空壳”。我在项目里给团队讲解时经常用一句话概括模板把代理搭好了但代理背后要接哪个库必须你自己告诉它。在改配置之前先确认模板里默认的账号密码。不同打包方维护的 install-template 默认用户不同但常见组合是root/123456也有的是mycat/123456。你可以打开mycat.yml搜索包含password的字段确认后再用于后文连接测试。2.3 启动与连接最小命令和常见做法模板目录确认正常后最直接的验证方式是启动一次然后从管理端口检查状态。启动脚本一般在bin下不同版本可能叫mycat或startup.sh我习惯统一用bin/mycat入口因为它支持 start、stop、restart、status 子命令。cd /opt/mycat2 bin/mycat start bin/mycat status第一次启动如果失败不要反复执行 start先去logs/下看 wrapper 日志或 mycat 主日志。模板里日志文件名和版本有关但启动闪退时控制台通常会先打印一段 Java 版本和 classpath 信息后面的堆栈才是真因。bin/mycat status如果返回“running”说明 Java 进程正常端口未一定已绑定需要继续验证端口。ss -lntp | grep -E 8066|9066如果两个端口都在监听就分别用 mysql 客户端探测。数据端口连接后会看到逻辑库列表管理端口连接后可以先执行最简单的指令确认会话可用。下面这条命令如果返回错误不要继续往下配库先把连接问题解决。mysql -h127.0.0.1 -P8066 -uroot -p123456进入 mysql 交互后执行SHOW DATABASES;能看到模板自带的逻辑库就说明代理本身工作正常。这里有一个常见误判SHOW DATABASES列出的库不是后端 MySQL 的库而是 Mycat2 注册到 schema 元数据中的逻辑库。所以即使回显里只有一个默认库名也代表模板安装成功。2.4 配置持久化模板里的 YAML 与运行期生成的文件Mycat2 的配置有一个容易让新手迷惑的点模板里conf/*.yml是静态初始文件但当你通过管理端口执行CREATE DATASOURCE这类指令时中间件会把新配置持久化到 conf 目录下的对应文件中。也就是说配置系统是“文件 运行期指令”双通道。直接用编辑器和用管理端命令都能改但改的方式和生效时机不同。我一般建议第一次部署用管理端口在线创建因为模板自带的 YAML 只是骨架里面的数据源名和逻辑库经常是示例值直接改 YAML 容易漏掉配套的权限、默认节点等字段。在线指令会帮你把关联关系写全。但要注意在线指令执行成功后最好看一眼 conf 目录是否真的多了或改了文件。如果是用安装包自带的旧版本可能存在“指令成功但重启后配置丢失”的情况原因是进程没有权限写 conf 目录运行在 tmpfs 或只读挂载上。后面避坑章节会再展开。3. 从单模板到两节点分库分表数据源、逻辑库、逻辑表三层改造3.1 prototype 数据源模板默认连接的后端库为什么要留着打开模板配置第一眼看到的通常是prototype这个数据源。它不是业务库而是 Mycat2 内部用来存放元数据、全局序列、以及无法确定分片键的兜底执行节点的“默认落点”。很多人在起步阶段觉得 prototype 多余把模板自带的 prototype 删掉结果启动正常但一执行SELECT NOW()就报错因为这类不涉及分片逻辑的查询被路由到了 prototype。正确做法是保留 prototype并给它指定一个真实存在且账号权限足够的 MySQL 库。例如单独建一个名为mycat_meta的库专门给 Mycat2 做系统初始化和兜底查询。这样做不会和业务表空间冲突排查问题时也容易从 SQL 日志区分哪类语句走了系统节点。dataSource: prototype: url: jdbc:mysql://127.0.0.1:3306/mycat_meta?useSSLfalseserverTimezoneAsia/Shanghai user: root password: 123456 maxRetryCount: 3 connectionTimeout: 5000这段配置的意思是Mycat2 进程启动时会为prototype这个数据源创建连接池URL 指向本机 MySQL 的mycat_meta库连接超时 5 秒。maxRetryCount控制后端连接失败时重试次数connectionTimeout控制建立物理连接的超时。注意这里的root是指后端 MySQL 的账号不是连接 Mycat2 的账号两者很容易搞混。改完这段后重启再用管理端口执行状态检查确认数据源已注册。3.2 用管理端口建数据源与逻辑库在线配置步骤假设你有两台后端节点db0和db1分别承载分片数据。先连接管理端口 9066然后依次创建数据源和逻辑库。这里的核心顺序不能反必须先有数据源再创建逻辑库最后注册逻辑表。数据源定义了连接池逻辑库相当于给一组物理节点起了一个业务别名逻辑表则把业务表映射到具体节点。mysql -h127.0.0.1 -P9066 -uroot -p123456连接后执行以下指令/* mycat:createDataSource{ name:ds0, url:jdbc:mysql://127.0.0.1:3306/db0, user:root, password:123456 } */; /* mycat:createDataSource{ name:ds1, url:jdbc:mysql://127.0.0.1:3306/db1, user:root, password:123456 } */; /* mycat:createDatabase{ name:shop, targetName:ds0 } */;createDataSource指令里的name是后续逻辑表要引用的节点名url里的路径是真实物理库user/password必须是该物理库有 DDL 和 DML 权限的账号。createDatabase的targetName表面上是把逻辑库挂在ds0上实际上更准确的表达是给逻辑库设置了一个默认物理节点。这样做的原因是即使后续查询不带分片键Mycat2 也知道优先把语句发给哪个节点。执行完用SHOW DATABASES;在管理端口查看应该能看到新增的shop逻辑库。如果看不到检查指令括号内的双引号是否被 mysql 客户端转义Windows 终端尤其容易出现整体字符串被拆成多个 token 的问题。稳妥做法是将整条指令写成一行并且不要加多余空格。3.3 分片表与全局表模板示例改法逻辑库建好后开始建表。分片表和全局表是两种最常用的逻辑表。分片表按某个分片键把数据散布到多个数据节点全局表在每个数据节点都保留一份完整数据用于字典表、状态表这类配置维度。模板里的示例表通常是单节点普通表你要做的是把它替换成带dataNode和分片算法的定义。/* mycat:createTable{ schemaName:shop, sql:CREATE TABLE t_order (id bigint not null, user_id int, amount decimal(10,2), primary key(id)) ENGINEInnoDB DEFAULT CHARSETutf8mb4, dataNode:ds0,ds1, type:SHARING, shardingKey:id, shardingAlgorithm:mod } */;这条指令有四个关键参数dataNode是分片表落到的物理节点列表用逗号分隔type为SHARING表示这是分片表shardingKey指定分片键id是后续路由计算依据shardingAlgorithm用的是mod取模算法默认按ds0、ds1顺序取模。sql里的建表语句会真实地在每个dataNode上执行所以ds0和ds1都必须有相同的建表权限否则会出现“第一个节点有表、第二个节点没表”的诡异状态。全局表的写法类似但type改成GLOBAL不需要分片键/* mycat:createTable{ schemaName:shop, sql:CREATE TABLE t_dict (id int, name varchar(20)) ENGINEInnoDB DEFAULT CHARSETutf8mb4, dataNode:ds0,ds1, type:GLOBAL } */;为什么全局表也要写多个dataNode因为 Mycat2 收到对全局表的写入时会把同样的 SQL 分发到所有节点保证每个节点都有完整副本后续查询也优先读本地节点避免跨库 join。如果你只配一个节点那就等于一个只有一个副本的普通表失去了全局表的意义。3.4 验证分片explain 和路由打印配置完分片表后第一步不是插入数据而是先验证路由结果。Mycat2 支持类似 MySQLEXPLAIN的语法可以查看一条 SQL 真正会转发到哪些数据节点。用数据端口 8066 连接在shop逻辑库下执行查询前先加EXPLAINEXPLAIN SELECT * FROM t_order WHERE id 123;正常情况下回显会显示这条查询路由到ds0或ds1中的一个而不是两个都出现。如果显示dataNode是空的或者两个节点都出现说明分片规则没有绑定成功。另一种验证方式是执行带具体分片值的插入后直接去两个物理库分别查t_order数据只会落在一个库里。我在项目里喜欢写一个简单脚本循环插入一批 id再用物理库统计数量这样能快速确认取模分布是否符合预期。如果查询不带分片键比如SELECT * FROM t_order WHERE user_id 5模板无法确定该去哪个节点就只能走逻辑库的默认节点或者报错。这不算 bug而是分片中间件的通用限制。真正跑业务时要么强制所有查询都带分片键要么为这类查询额外建全局索引表。4. 模板参数与运行环境端口、JVM、连接池、日志怎么调4.1 修改监听端口client 和 manager 两个监听端口模板默认把 8066 作为业务端口9066 作为管理端口。如果你的机器上已经跑了别的 MySQL 实例或代理端口冲突是必然的启动日志会直接报Address already in use。修改端口的位置一般在conf/mycat.yml的 server 段下不同打包版本的字段名略有差异但语义是一致的一个叫 client port一个叫 manager port。server: ip: 0.0.0.0 port: 8066 managerPort: 9066ip最好保留0.0.0.0否则只监听本机其他机器上的应用没法连。port改成比如 8070managerPort改成 9070改完重启后连接字符串也要同步改。这里踩过一个坑只改了业务端口忘记改管理端口结果运维脚本里还在连 9066查状态报错白白排查了半小时。改端口属于低风险操作但一定记住两个端口是一对改哪个都要同步所有下游脚本。4.2 JVM 与线程参数模板里的启动脚本怎么传安装模板里的启动脚本对 JVM 内存通常只有一个保守默认值并不会根据你的机器自动调优。上线前建议调整堆内存尤其是处理分片聚合时过大结果集会直接把 JVM 顶到 OOM。模板脚本通常支持通过环境变量传入 JVM 参数常见是MYCAT_OPTS或JAVA_OPTS使用时先看bin/mycat脚本头部确认它读取哪个变量。export MYCAT_OPTS-Xms1g -Xmx2g -DioThreads4 -DworkerThreads32 cd /opt/mycat2 bin/mycat restart这段配置把初始堆和最大堆设置为 1G/2G同时指定 IO 线程和管理线程数。线程数需要和机器核数、预期并发挂钩4 核以下别把 workerThreads 调成 64线程切换开销反而比执行 SQL 更耗时。如果模板脚本不支持MYCAT_OPTS可以直接修改bin下启动脚本里JAVA_OPTS那一行但注意修改前备份原脚本升级模板时容易被覆盖。堆内存参数的验证方法也很简单启动后通过ps查看实际命令行参数是否生效或者看 logs 下的 JVM 启动日志。很多启动脚本会在日志里打印完整命令那里能确认-Xmx是否被正确读取。调整后跑一段压测观察 GC 频率更重要而不是盲目调大堆。4.3 后端连接池与心跳不调的后果Mycat2 对每个数据源都会维护一个连接池连接池大小、空闲回收、心跳检测这些参数决定后端连接是否稳定。模板默认值偏向保守和兼容不一定适合高并发。连接池相关配置通常写在数据源的配置段或连接池配置里。dataSource: ds0: url: jdbc:mysql://127.0.0.1:3306/db0?useSSLfalseconnectTimeout3000socketTimeout60000 user: root password: 123456 maxCon: 50 minCon: 5 idleTimeout: 600000maxCon是单个数据源最大连接数不是总连接数如果逻辑库挂了 4 个分片节点理论最大连接数是各节点之和。idleTimeout是空闲连接回收时间单位毫秒设太短会导致频繁建连设太长又会占用后端 MySQL 的连接数。心跳配置如果模板里有默认值我一般保留它负责在空闲连接被 MySQL 的wait_timeout回收前主动探测。如果你的后端 MySQL 有max_connections限制maxCon不能按 50 这种值拍脑袋定要按“前端并发量除以平均每个请求占用的连接数”倒推。4.4 日志级别与慢 SQL 记录模板默认日志级别通常是 DEBUG 或 INFO启动阶段 DEBUG 没问题生产环境保持 DEBUG 会刷爆磁盘。日志配置一般在conf/logback.xml或类似文件中找到root或sql的 logger 调整 level 为WARN。慢 SQL 记录是排查分片问题的利器可以单独开启让执行耗时超过阈值的 SQL 单独打到一个日志文件里方便对照分片键是否被有效利用。logger nameio.mycat.sql.recorder levelINFO appender-ref refSLOW_SQL_FILE/ /logger这段是日志框架层面的慢 SQL 归档配置实际字段名以模板里的 logback 文件为准但思路一致单独为慢 SQL 创建 appender不干扰主日志。我习惯把慢 SQL 阈值从 200ms 开始调分片键没命中时SQL 往往需要跨多节点聚合耗时上会产生明显尖刺。通过日志确认那些耗时异常的 SQL再回去看它的 where 条件是否包含分片键这是提升分片性能最快的一条路径。日志级别改完不需要重启但某些 JVM 参数还是需要重启才能生效所以先改日志再调 JVM最后再统一重启一次。5. mycat2 install-template 启动避坑5 个翻车现场5.1 启动闪退控制台只显示版本信息现象执行bin/mycat start后没有任何报错进程也没起来控制台只跳出一段 Java 版本和 classpath 信息。看 logs 目录发现只有一个刚生成的空文件或根本不存在日志文件。原因这个现象在模板场景里十有八九是启动脚本里的JAVA_HOME指向了错误的 JDK。系统默认 JDK 是 32 位而模板里的 Mycat2 是 64 位编译的中间件启动时 JVM 加载原生库失败但脚本没有把错误回显到控制台只留了一个退出码。还有一种情况是 JDK 版本过高模板依赖的旧版本 Mycat2 不兼容 Java 17 以上的模块化约束。解决先显式指定 JDK在启动脚本前设置环境变量export JAVA_HOME/usr/lib/jvm/java-8-openjdk-amd64 export PATH$JAVA_HOME/bin:$PATH cd /opt/mycat2 bin/mycat start启动后再看 logs确认日志里有 “JVM started” 或类似标记。如果仍然闪退用bin/mycat console或前台方式启动把 JVM 错误直接打到屏幕。模板本身不负责 JDK 安装所以这个坑和模板版本无关纯粹是运行环境不一致导致。5.2 连接 8066 提示 Access denied但账号密码看着没问题现象用mysql -uroot -p123456 -P8066连接报Access denied for user rootlocalhost。检查模板mycat.yml账号密码明明写的是 root/123456后端 MySQL 也能用这个账号正常登录。原因Mycat2 对外有自己的用户体系数据端口 8066 上的鉴权账号和后端物理库的 MySQL 账号不是一回事。模板里的user配置如果写的是后端数据源账号会直接影响对外连接。也就是说你改了对后端的数据源账号但 Mycat 代理层的业务用户还没配或者密码不匹配。解决在mycat.yml里找到 Mycat 代理层用户配置段把它改成你打算给业务应用用的密码例如users: root: password: 123456 schemas: - shopschemas字段必须列出允许访问的逻辑库不列的话即使账号密码对连接成功后USE shop也会报无权限。改完重启。这里的root是 Mycat 的业务账号不是后端库管理员可以单独建一个弱权限账号给业务从管理上避免后端库密码被直接暴露给应用。5.3 能连上但查询报 table not exists现象8066 连接正常SHOW DATABASES能看到shop但执行SELECT * FROM t_order提示表不存在。直接在管理端口查 schema 配置逻辑表已经存在。原因模板在启动时加载的逻辑表和当前执行的 SQL 不在同一个逻辑库下或者逻辑库名大小写不一致。MySQL 客户端默认表名和库名大小写敏感程度与后端有关Mycat2 的 schema 注册是精确匹配你在shop下注册的是T_ORDER查询时写t_order就会找不到。解决先确认逻辑表注册的实际名字SHOW TABLES FROM shop;如果显示是T_ORDER修改查询使用相同大小写。这种情况在 Windows 上更常见因为 Windows 文件系统不区分大小写模板元数据落盘时可能保留原始大小写而 Linux 下严格区分。我建议所有建表 SQL 统一写成小写表名字段和表名在业务代码里也统一小写从源头上消除大小写不一致。5.4 分片查询结果总缺数据只返回一部分现象t_order按 id 取模分到 ds0、ds1插入一批数据后通过 Mycat2 查询总数和物理库两个节点的数据总和对不上。单独连 ds0 或 ds1 查数据都在。原因查询 SQL 没有携带分片键或者分片键的值经过函数处理Mycat2 无法确定数据在哪个节点只能走默认节点导致只读到了默认节点上的那部分数据。模板里的默认defaultNode如果恰好指向 ds0那查询结果永远只有 ds0 的一半数据。解决给业务查询强制带上分片键并检查 WHERE 条件是否对分片字段做了函数转换SELECT * FROM t_order WHERE id 100 AND id 500;这条语句带分片键范围能正确路由到所有节点再聚合。如果业务确实需要按user_id查询而分片键是id只有两个选择在逻辑表上增加基于user_id的全局索引表或者接受全节点扫描。不要试图在配置里加一个“兜底路由”来解决问题那样会让每个查询都压到一个节点分片完全失去意义。5.5 修改配置后重启失效配置回到模板最初状态现象通过管理端口在线创建了数据源和逻辑库当时查询一切正常重启 Mycat2 后所有配置消失重新看起来和刚解压完一样。原因模板进程的工作目录并不是安装目录或者conf目录没有写权限。Mycat2 在线配置执行后需要把新的元数据写回到 conf 下持久化文件如果启动时是通过systemd或别的方式换了工作目录中间件会把配置文件写到错误路径而启动时又从模板原路径读配置导致修改丢失。解决先确认启动脚本的工作目录cat /proc/$(pidof mycat)/cwd如果 cwd 不是/opt/mycat2说明启动方式不干净。用绝对路径启动并确保 conf 目录可写cd /opt/mycat2 export MYCAT_HOME/opt/mycat2 bin/mycat restart在线修改后还可以手动备份 conf 目录cp -r conf conf.bak.$(date %s)备份不只是后悔药也是排查“重启后配置不一致”问题的最直接证据。如果备份和当前目录文件一致说明是进程写到了别处如果不一致说明配置根本没落盘。6. 用模板做最小验证从启动到分片结果确认一个技巧就够模板验证不需要一上来就写复杂压测脚本先建立一条最短路启动状态、逻辑库可见、分片路由正确。启动状态用bin/mycat status逻辑库可见用SHOW DATABASES分片路由正确用EXPLAIN。这三步都过了模板才算真正接入了你的业务环境。我长期保留的一个习惯是用“回归脚本模板”保存关键配置。每次调完参数把conf/目录打包成一个带日期的压缩包同时把验证 SQL 放进一个.sql文件里bin/mycat restart mysql -h127.0.0.1 -P8066 -uroot -p123456 verify.sqlverify.sql 里的内容不要只有SELECT 1至少包括一个带分片键的查询、一个不带分片键的查询、和一个EXPLAIN输出。这样每次环境变更后跑一遍能立刻发现路由是否被某个参数改动破坏。由于我只相信“可重复执行”的验证所以不会把检查结果记在自己脑子里而是让脚本输出到日志文件对比上次的结果差异。mycat2-install-template-1.21.zip的价值在于是“干净的初始状态”。踩过一次坑后我现在的做法是新环境一律先解压一份新模板验证成功后再把之前的 conf 备份覆盖回去而不是在坏配置上反复修。最后再说一句模板只是给你一个坚实的基础真正决定 Mycat2 能不能稳定跑起来的还是你后续每一次配库和改参时留下的检查记录。希望这些来自一线配置的经验能帮到你少走一点我当时走弯路的地方。本文还有配套的精品资源点击获取