简介：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-template（mycat2-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?useSSL=false&serverTimezone=Asia/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)) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4", "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)) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4", "dataNode":"ds0,ds1", "type":"GLOBAL" } */;为什么全局表也要写多个dataNode？因为 Mycat2 收到对全局表的写入时，会把同样的 SQL 分发到所有节点，保证每个节点都有完整副本；后续查询也优先读本地节点，避免跨库 join。如果你只配一个节点，那就等于一个只有一个副本的普通表，失去了全局表的意义。
3.4 验证分片：explain 和路由打印
配置完分片表后，第一步不是插入数据，而是先验证路由结果。Mycat2 支持类似 MySQLEXPLAIN的语法，可以查看一条 SQL 真正会转发到哪些数据节点。用数据端口 8066 连接，在shop逻辑库下执行查询前先加EXPLAIN：
EXPLAIN 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改成比如 8070，managerPort改成 9070，改完重启后连接字符串也要同步改。这里踩过一个坑：只改了业务端口，忘记改管理端口，结果运维脚本里还在连 9066，查状态报错，白白排查了半小时。改端口属于低风险操作，但一定记住两个端口是一对，改哪个都要同步所有下游脚本。
4.2 JVM 与线程参数：模板里的启动脚本怎么传
安装模板里的启动脚本对 JVM 内存通常只有一个保守默认值，并不会根据你的机器自动调优。上线前建议调整堆内存，尤其是处理分片聚合时，过大结果集会直接把 JVM 顶到 OOM。模板脚本通常支持通过环境变量传入 JVM 参数，常见是MYCAT_OPTS或JAVA_OPTS，使用时先看bin/mycat脚本头部，确认它读取哪个变量。
export MYCAT_OPTS="-Xms1g -Xmx2g -DioThreads=4 -DworkerThreads=32" 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?useSSL=false&connectTimeout=3000&socketTimeout=60000 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 name="io.mycat.sql.recorder" level="INFO"> <appender-ref ref="SLOW_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 'root'@'localhost'。检查模板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 能不能稳定跑起来的，还是你后续每一次配库和改参时留下的检查记录。希望这些来自一线配置的经验能帮到你，少走一点我当时走弯路的地方。
本文还有配套的精品资源，点击获取
