CAT 监控 3.1.0 安装指南
从零在 Ubuntu 22.04 上源码构建 CAT（Central Application Tracking）3.1.0 并部署到 Tomcat 9：JDK/Maven 构建、MySQL 5.7 建库、/data 配置目录、控制台登录验证与全量排障实录。
CAT 监控 3.1.0 安装指南
目标：从零在一台 Linux 服务器上完成 CAT（Central Application Tracking，大众点评开源 APM）3.1.0 服务端的安装部署——JDK/Maven 源码构建、MySQL 5.7 建库、
/data/appdatas/cat配置目录初始化、Apache Tomcat 9 部署 WAR 包、控制台登录验证，并沉淀构建与启动阶段的全部踩坑实录。已在 Ubuntu 22.04 服务器（JDK 1.8.0_504 + Maven 3.6.3 + MySQL 5.7.44 + Tomcat 9.0.123）全流程实测通过，控制台可正常登录。
一、环境信息
本文所有命令与输出均在以下环境实测采集，读者复现时保持同量级版本可最大限度避开兼容坑：
- 操作系统：Ubuntu 22.04 LTS（x86_64，内核 5.15+，同样适用于 CentOS 7+/Debian 11+，命令差异以各发行版包管理器为准）
- 构建与运行机器（CAT 服务端）：IP
10.89.66.3，主机名cat-server.local - 数据库机器（MySQL）：IP
10.89.66.2，与 CAT 服务端分离部署（单机同机部署亦可用127.0.0.1） - JDK：OpenJDK 1.8.0_504（Ubuntu 包
openjdk-8-jdk8u504-ga-1ubuntu1~22.04.3） - 构建工具：Maven 3.6.3（Ubuntu 22.04 仓库自带）、git 2.34.1
- 数据库：MySQL 5.7.44（
--max-allowed-packet=1G启动） - Web 容器：Apache Tomcat 9.0.123（官方 tar.gz，安装于
/opt/tomcat） - CAT 版本：dianping/Cat 3.1.0（源码 tag
3.1.0，构建产物cat-home.war共 61,600,678 字节） - 端口规划：CAT 控制台 HTTP
8080、客户端上报 TCP2280（官方注明 2280 不允许修改） - 部署路径规划：源码
/opt/cat-src、Tomcat/opt/tomcat、CAT 配置与数据/data/appdatas/cat/、日志/data/applogs/cat/、构建产物中转/opt/deploy/
⚠️ 说明：本文所指 CAT 均为 Central Application Tracking 应用监控系统，与 Linux Shell 的同名文件查看命令无关；下文命令中出现的
cat.war是 CAT 服务端的 WAR 部署包文件名（官方要求 WAR 必须重命名为cat.war）。
二、前置条件
安装开始前，逐项确认以下前置条件，任何一项缺失都会在后续步骤卡住：
- JDK 8：CAT 3.1.0 服务端必须用 JDK 8 构建（官方声明服务端推荐 JDK 7/8，官方发布的 master WAR 用 JDK 8 编译）。JDK 11+ 编译会因旧版 Maven 插件不兼容而失败。
- Maven 3 及以上：官方安装环境要求「Maven 3 及以上」。
- MySQL 5.6/5.7：官方支持矩阵明确「MySQL 5.6、5.7，更高版本 MySQL 都不建议使用，不清楚兼容性」。本文实测 MySQL 8.0.46 确实无法连通（详见第八章 FAQ 问题 1），务必使用 5.7。
- Tomcat 7/8/9：官方建议 Tomcat 7.x 或 8.0.x；本文用 9.0.123 实测通过（9.x 默认 URI 编码为 UTF-8，官方文档中「server.xml 加 URIEncoding="utf-8"」的步骤在 9.x 可省略）。
/data目录可写：CAT 强制读写/data/appdatas/cat/（配置）与/data/applogs/cat/（日志），官方要求对/data/有读写权限；磁盘建议预留 500GB 以上（官方口径），测试环境 20GB 起步即可。- 网络：CAT 服务器需访问 MySQL 3306；业务机器需能访问 CAT 服务器 TCP 2280 与 HTTP 8080。
逐项实测确认（以下输出均来自 CAT 服务器 10.89.66.3）：
java -version
实测输出：
openjdk version "1.8.0_504"
OpenJDK Runtime Environment (build 1.8.0_504-8u504-ga-1ubuntu1~22.04.3-b01)
OpenJDK 64-Bit Server VM (build 25.504-b01, mixed mode)
mvn -version | head -3
实测输出：
Apache Maven 3.6.3
Maven home: /usr/share/maven
Java version: 1.8.0_504, vendor: Private Build, runtime: /usr/lib/jvm/java-8-openjdk-amd64/jre
mysql -h10.89.66.2 -uroot -p -e "SELECT VERSION(); SHOW VARIABLES LIKE 'max_allowed_packet';"
实测输出（密码 q1w2e3r4）：
VERSION()
5.7.44
Variable_name Value
max_allowed_packet 1073741824
💡 说明：
max_allowed_packet=1073741824即 1GB——官方部署文档明确要求把该参数从默认值调大（原文建议 1000M），因为 CAT 的天/周/月报表单行内容很大，默认 4M（5.7 默认 4194304）会在报表落库时报Packet too big类错误。数据库启动时以--max-allowed-packet=1G或my.cnf中max_allowed_packet=1G配置，改完需重启数据库。
三、版本选型说明
CAT 官方（GitHub 仓库 readme_server 部署文档，2026-10-23 查询）给出的安装环境与版本矩阵如下，加粗列为本项目实测采用的组合：
| 组件 | 官方要求 | 本文实测 | 结论 |
|---|---|---|---|
| 操作系统 | Linux 2.6+（epoll），生产用 Linux；美团点评内部 CentOS 6.5 | Ubuntu 22.04 | 通过 |
| JDK | Java 6/7/8；服务端推荐 JDK 7，官方 master WAR 以 JDK 8 编译 | OpenJDK 1.8.0_504 | 通过 |
| Maven | Maven 3 及以上 | 3.6.3 | 通过 |
| MySQL | 5.6 / 5.7（更高版本不建议，不清楚兼容性） | 5.7.44 | 通过；8.0.46 实测不兼容（FAQ 问题 1） |
| J2EE 容器 | 建议 Tomcat 7.x / 8.0.x | Tomcat 9.0.123 | 通过（URI 编码默认 UTF-8） |
| Hadoop | 可选，小规模直接磁盘模式 | 未启用（hdfs-enabled=false） | 通过 |
选型要点解读：CAT 的版本矩阵「卡死」在 2022 年 3.1.0 发布时的生态位——JDK 8 与 MySQL 5.7 是它的舒适区，越新越容易踩驱动与编译插件的不兼容坑；生产部署建议严格按矩阵取版本，把升级精力省下来做运维监控。
四、方案 A：源码构建部署（在线，推荐主线）
本章为完整 0→1 主线：在能联网（可访问 GitHub 与 Maven 仓库）的机器上克隆源码、构建 WAR 包，随后在本机完成数据库初始化与 Tomcat 部署。适合首次安装与需要审读/修改源码的团队。
4.1 安装基础环境
安装构建工具链与运维依赖（Ubuntu 用 apt，CentOS 用 yum/dnf 对应包名）：
apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y git curl wget vim unzip \
openjdk-8-jdk maven default-mysql-client procps net-tools
实测输出（节选）：
Processing triggers for libc-bin (2.35-0ubuntu3.11) ...
Processing triggers for man-db (2.10.2-1) ...
Processing triggers for fontconfig (2.13.1-4.2ubuntu5) ...
⚠️ 踩坑实录 1（JDK 版本切换）：Ubuntu 22.04 上若同机装有多个 JDK，
apt install openjdk-8-jdk后默认java可能仍指向 OpenJDK 11（实测java -version曾回显openjdk version "11.0.32.1"）。用 update-alternatives 显式切换为 8：update-alternatives --set java /usr/lib/jvm/java-8-openjdk-amd64/jre/bin/java update-alternatives --set javac /usr/lib/jvm/java-8-openjdk-amd64/bin/javac export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64切换后再次
java -version确认输出1.8.0_504（见第二章实测）。Maven 以JAVA_HOME选 JDK，务必先切再构建。
4.2 克隆 CAT 源码
从 GitHub 克隆 3.1.0 tag（加 --depth 1 只取该 tag 快照，官方 README 也推荐此法加速）：
cd /opt
git clone --depth 1 --branch 3.1.0 https://github.com/dianping/Cat.git cat-src
实测输出：
Cloning into 'cat-src'...
Note: switching to '3.1.0'.
You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and discard any commits you make in this state without
impacting any branches by switching back to a branch.
Turn off this advice by setting config variable advice.detachedHead to false
确认关键目录：
ls /opt/cat-src
实测输出：
LICENSE
NOTICE.txt
README.md
SECURITY.md
cat-alarm
cat-client
cat-consumer
cat-core
cat-hadoop
cat-home
docker
helm
integration
java_formatter.xml
lib
pom.xml
script
💡 目录速览：
cat-home是服务端 WAR 所在模块；script/CatApplication.sql是建库脚本；docker/下有 datasources.xml/client.xml 配置模板；lib/是各语言客户端（Java 新客户端在lib/java）。
4.3 配置 Maven 镜像（国内网络加速）
官方声明「v3.0.1 开始所有依赖可直接从 Maven 中央仓库获取，无需修改 maven 配置文件」，但国内直连 repo1.maven.org 速度差、构建极易超时。实测采用阿里云镜像（写入 /root/.m2/settings.xml）：
mkdir -p /root/.m2
cat > /root/.m2/settings.xml <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0">
<mirrors>
<mirror>
<id>aliyun-central</id>
<mirrorOf>central</mirrorOf>
<name>Aliyun Maven Central Mirror</name>
<url>https://maven.aliyun.com/repository/public</url>
</mirror>
</mirrors>
</settings>
EOF
（无回显即写入成功；可用 cat /root/.m2/settings.xml 核对。）
💡 技术拓展：Maven 依赖源不止中央仓库直连一种。常见选择对比——
方案 原理 适用场景 中央仓库直连 默认 repo1.maven.org海外服务器/网络顺畅 阿里云等公共镜像 mirrorOf=central 替换仓库地址 国内服务器，零自建成本（本文实测采用） 私服 Nexus/Artifactory 企业内网代理+缓存 有内网仓库团队 本文因构建服务器在国内网络环境，采用阿里云公共镜像。
4.4 源码构建 WAR 包
在源码目录执行官方构建命令（跳过测试）：
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
cd /opt/cat-src
mvn clean install -DskipTests -B
实测输出（首尾节选，全程 3 分 23 秒；首次构建需下载全部依赖，视网络 5-30 分钟）：
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary for CAT 3.1.0:
[INFO]
[INFO] cat-parent ......................................... SUCCESS [ 1.286 s]
[INFO] cat-core ........................................... SUCCESS [ 20.196 s]
[INFO] cat-client ......................................... SUCCESS [ 4.970 s]
[INFO] cat-consumer ....................................... SUCCESS [ 2.600 s]
[INFO] cat-alarm .......................................... SUCCESS [ 2.235 s]
[INFO] cat-hadoop ......................................... SUCCESS [ 1.442 s]
[INFO] cat-home ........................................... SUCCESS [01:03 min]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] Total time: 03:23 min
[INFO] Finished at: 2026-10-22T23:33:53Z
[INFO] ------------------------------------------------------------------------
确认构建产物（WAR 包位于 cat-home/target/）：
ls -la /opt/cat-src/cat-home/target/cat-home.war
实测输出：
-rw-r--r-- 1 root root 61600678 Oct 22 23:33 /opt/cat-src/cat-home/target/cat-home.war
⚠️ 说明：产物名为
cat-home.war（模块名即 warName），部署时必须重命名为cat.war——CAT 的页面静态资源与跳转按/cat上下文路径硬编码，WAR 解包目录必须是/cat。
4.5 初始化 MySQL 数据库
在数据库机器（10.89.66.2）上建库并导入官方脚本。先建库（官方建议编码 utf8mb4；本文实测建 utf8 亦通过，脚本内建表语句自带 CHARSET=utf8）：
mysql -h10.89.66.2 -uroot -pq1w2e3r4 -e "CREATE DATABASE IF NOT EXISTS cat DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;"
（无回显即成功。）
导入建表脚本（脚本路径按构建机实际位置，从源码 script/ 目录取）：
mysql -h10.89.66.2 -uroot -pq1w2e3r4 cat < /opt/cat-src/script/CatApplication.sql
（无回显即成功。）
验证表数量与关键表：
mysql -h10.89.66.2 -uroot -pq1w2e3r4 -e "SELECT COUNT(*) AS table_count FROM information_schema.tables WHERE table_schema='cat';"
实测输出：
table_count
26
mysql -h10.89.66.2 -uroot -pq1w2e3r4 -e "USE cat; SHOW TABLES;"
实测输出：
alert
alert_summary
alteration
baseline
businessReport
business_config
config
config_modification
daily_report_content
dailyreport
hostinfo
hourly_report_content
hourlyreport
metric_graph
metric_screen
monthly_report_content
monthreport
operation
overload
project
server_alarm_rule
task
topologyGraph
user_define_rule
weekly_report_content
weeklyreport
💡 说明：26 张表覆盖报表存储（dailyreport/weeklyreport/monthreport 及 *_content）、实时配置（config）、路由（topologyGraph）、项目（project）等。
config表是 3.x 的配置中心表——服务端角色、路由等配置修改后持久化于此（详见《CAT 监控 3.1.0 配置参数详解》）。一套 CAT 集群只需要一个数据库（官方明确提醒勿在每台节点都建库）。
4.6 初始化 /data 配置目录
CAT 服务端强制使用 /data/appdatas/cat/ 存放配置、/data/appdatas/cat/bucket/ 存放本地数据文件、/data/applogs/cat/ 存放日志。创建目录：
mkdir -p /data/appdatas/cat /data/applogs/cat
chmod -R 777 /data/
（无回显即成功；chmod -R 777 /data/ 为官方文档原文步骤，生产可收敛为运行账号可写。）
① client.xml（服务端路由指引）——服务端自身也作为客户端上报，指向本机即可：
cat > /data/appdatas/cat/client.xml <<'EOF'
<?xml version="1.0" encoding="utf-8"?>
<config mode="client">
<servers>
<server ip="127.0.0.1" port="2280" http-port="8080"/>
</servers>
</config>
EOF
② datasources.xml（数据库连接）——替换为实际数据库地址与账号：
cat > /data/appdatas/cat/datasources.xml <<'EOF'
<?xml version="1.0" encoding="utf-8"?>
<data-sources>
<data-source id="cat">
<maximum-pool-size>3</maximum-pool-size>
<connection-timeout>1s</connection-timeout>
<idle-timeout>10m</idle-timeout>
<statement-cache-size>1000</statement-cache-size>
<properties>
<driver>com.mysql.jdbc.Driver</driver>
<url><![CDATA[jdbc:mysql://10.89.66.2:3306/cat]]></url>
<user>root</user>
<password>q1w2e3r4</password>
<connectionProperties><![CDATA[useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&socketTimeout=120000]]></connectionProperties>
</properties>
</data-source>
</data-sources>
EOF
③ server.xml（服务端角色）——单机模式把三类角色全开：
cat > /data/appdatas/cat/server.xml <<'EOF'
<?xml version="1.0" encoding="utf-8"?>
<server-config>
<server id="default">
<properties>
<property name="local-mode" value="false"/>
<property name="job-machine" value="true"/>
<property name="send-machine" value="true"/>
<property name="alarm-machine" value="true"/>
<property name="hdfs-enable" value="false"/>
</properties>
<storage local-base-dir="/data/appdatas/cat/bucket/" local-report-storage-time="7" local-logivew-storage-time="7">
</storage>
<consumer>
<long-config default-url-threshold="1000" default-sql-threshold="100" default-service-threshold="50">
</long-config>
</consumer>
</server>
</server-config>
EOF
确认三份配置就位：
ls -la /data/appdatas/cat/
实测输出：
total 20
drwxr-xr-x 2 root root 4096 Oct 22 23:38 .
drwxr-xr-x 3 root root 4096 Oct 22 23:38 ..
-rw-r--r-- 1 root root 163 Oct 22 23:38 client.xml
-rw-r--r-- 1 root root 707 Oct 22 23:38 datasources.xml
-rw-r--r-- 1 root root 726 Oct 22 23:38 server.xml
⚠️ 踩坑实录 2（server.xml 与数据库配置的关系）：3.x 中「生效」的服务端角色配置存于 MySQL
config表（name='server-config'行），不是 server.xml。首次启动时若库中无记录，CAT 以内置默认值入库；本机 server.xml 只在数据库不可用时兜底。因此改完 server.xml 发现角色没生效属正常——正确改法是用控制台「服务端配置」页提交（见 4.10 节第 6 步），或直接改库后重启。逐项参数含义见《CAT 监控 3.1.0 配置参数详解》。
4.7 安装 Tomcat 9
下载并解压官方 tar.gz 到 /opt/tomcat：
cd /opt
wget https://dlcdn.apache.org/tomcat/tomcat-9/v9.0.123/bin/apache-tomcat-9.0.123.tar.gz
tar -xzf apache-tomcat-9.0.123.tar.gz
mv apache-tomcat-9.0.123 tomcat
（下载回显视网络；解压无报错即成功。）验证：
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
/opt/tomcat/bin/version.sh | grep -E 'Server version|JVM Version'
实测输出：
Server version: Apache Tomcat/9.0.123
JVM Version: 1.8.0_504-8u504-ga-1ubuntu1~22.04.3-b01
4.8 配置 JVM 与部署 WAR 包
① 写 setenv.sh（JVM 参数与 CAT_HOME）——官方推荐做法是在 Tomcat bin/ 下新建 setenv.sh 承载 CATALINA_OPTS（catalina.sh 启动时会自动 source 它），避免改动官方脚本。本文按团队 JVM 规范把堆限制在 256–512MB（生产大集群可按官方建议上调，见 4.8 节末尾说明），并通过 -DCAT_ADMIN_PWD 设置控制台密码：
cat > /opt/tomcat/bin/setenv.sh <<'EOF'
export CAT_HOME=/data/appdatas/cat/
CATALINA_OPTS="$CATALINA_OPTS -server -DCAT_HOME=$CAT_HOME -Djava.awt.headless=true -Dfile.encoding=UTF-8 -Xms256m -Xmx512m -Djava.nio.channels.spi.SelectorProvider=sun.nio.ch.EPollSelectorProvider -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -DCAT_ADMIN_PWD=q1w2e3r4"
EOF
chmod +x /opt/tomcat/bin/setenv.sh
（无回显即成功。）
参数逐项说明：
| 参数 | 作用 | 本文取值理由 |
|---|---|---|
-DCAT_HOME=/data/appdatas/cat/ | 指定 CAT 配置/数据根目录 | 官方 setenv 模板原文；不设则用默认路径 /data/appdatas/cat |
-Xms256m -Xmx512m | JVM 堆初始/最大值 | 团队规范：验证环境堆限 256–512MB；官方生产建议堆 10G 以上，按机器内存另行放大 |
-DCAT_ADMIN_PWD=q1w2e3r4 | 控制台 admin 账号密码 | 3.1.0 内置登录逻辑固定账号 admin，密码读该系统属性，缺省为 admin（源码 SessionManager.java：CatPropertyProvider.INST.getProperty("CAT_ADMIN_PWD", "admin")） |
-Dfile.encoding=UTF-8 | 文件编码 | 规避报表中文乱码 |
-Djava.nio.channels.spi.SelectorProvider=sun.nio.ch.EPollSelectorProvider | 强制 epoll | Linux 高并发下官方模板原文保留 |
② 部署 WAR——复制到 webapps 并重命名为 cat.war（contextPath 自动为 /cat）：
cp /opt/cat-src/cat-home/target/cat-home.war /opt/tomcat/webapps/cat.war
ls -la /opt/tomcat/webapps/cat.war
实测输出：
-rw-r--r-- 1 root root 61600678 Oct 22 23:38 /opt/tomcat/webapps/cat.war
💡 官方部署文档同时给出生产级 CATALINA_OPTS 模板（
-Xms25G -Xmx25G、CMS GC 系列参数、GC 日志等）。验证/小规模环境用本文的 256–512MB 即可稳定运行；上生产前按官方模板结合机器内存放大堆并切换 G1/CMS 策略。
4.9 启动与验证
启动 Tomcat：
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
/opt/tomcat/bin/startup.sh
实测输出：
Tomcat started.
等待约 1-2 分钟（首次启动需解包 WAR 并初始化 26 张表的访问层），然后逐项验证：
① 端口监听——控制台 8080 与客户端上报 2280：
netstat -ltn | grep -E ':(8080|2280)'
实测输出：
tcp6 0 0 :::8080 :::* LISTEN
tcp6 0 0 :::2280 :::* LISTEN
② JVM 参数生效验证（jps -v）：
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
jps -v | grep Bootstrap | grep -oE '\-Xms[0-9]+m \-Xmx[0-9]+m|CAT_HOME=[^ ]+|CAT_ADMIN_PWD=[a-z0-9]+'
实测输出：
-Xms256m -Xmx512m
CAT_HOME=/data/appdatas/cat/
CAT_ADMIN_PWD=q1w2e3r4
③ 控制台可达：
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/cat/r/
实测输出：
200
④ 服务端角色生效（job-machine/alarm-machine，对应 4.10 节提交后的库配置）：
grep -E 'CAT server is running' /data/appdatas/cat/cat_20261023.log | tail -3
实测输出：
[10-23 00:06:53.687] [INFO] [ServerConfigManager] CAT server is running with hdfs,false
[10-23 00:06:53.687] [INFO] [ServerConfigManager] CAT server is running with alert,true
[10-23 00:06:53.687] [INFO] [ServerConfigManager] CAT server is running with job,true
⑤ 控制台登录——浏览器打开 http://10.89.66.3:8080/cat/r/，未登录会跳转 /cat/s/login 登录页，账号 admin、密码 q1w2e3r4（即 4.8 节 -DCAT_ADMIN_PWD 所设）。用命令行等价验证：
curl -s -m 8 -c /tmp/cc.txt --data-urlencode 'account=admin' \
--data-urlencode 'password=q1w2e3r4' \
--data-urlencode 'login=1' --data-urlencode 'op=login' \
-o /dev/null -w 'login=%{http_code}\n' http://127.0.0.1:8080/cat/s/login
grep -c 'ct' /tmp/cc.txt
实测输出：
login=200
1
curl -s -m 8 -b /tmp/cc.txt -o /dev/null -w 'report_page=%{http_code}\n' 'http://127.0.0.1:8080/cat/r/t?op=transactions'
实测输出：
report_page=200
💡 说明：登录成功后服务端下发名为
ct的登录凭证 Cookie（源码Token.TOKEN = "ct"），此后访问报表页返回 200 即代表会话有效。若密码未通过-DCAT_ADMIN_PWD定制，则默认账号密码为admin/admin。控制台左侧报表（Transaction/Event/Problem/Heartbeat/Matrix 等）在服务端自监控数据（cat 域）产生后逐步可见。
4.10 服务端配置入库（角色与路由）
① 提交服务端角色配置：浏览器打开控制台「配置管理 → 服务端配置」（URL http://10.89.66.3:8080/cat/s/config?op=serverConfigUpdate），把角色 XML 提交入库（本文实测用接口提交，等价操作）。提交内容（即 4.6 节 server.xml 的角色部分）：
<?xml version="1.0" encoding="utf-8"?>
<server-config>
<server id="default">
<properties>
<property name="local-mode" value="false"/>
<property name="job-machine" value="true"/>
<property name="send-machine" value="true"/>
<property name="alarm-machine" value="true"/>
<property name="hdfs-enabled" value="false"/>
<property name="remote-servers" value="127.0.0.1:8080"/>
</properties>
<storage local-base-dir="/data/appdatas/cat/bucket/" max-hdfs-storage-time="15" local-report-storage-time="2" local-logivew-storage-time="1">
</storage>
<consumer>
<long-config default-url-threshold="1000" default-sql-threshold="100" default-service-threshold="50">
</long-config>
</consumer>
</server>
</server-config>
提交后验证入库（数据库 config 表 server-config 行更新时间与内容）：
mysql -h10.89.66.2 -uroot -pq1w2e3r4 -e "USE cat; SELECT modify_date FROM config WHERE name='server-config';"
实测输出：
modify_date
2026-10-23 00:06:01
⚠️ 官方明确：「当一个机器角色更改后，请重启该机器」。重启后 4.9 节第 ④ 步日志应显示
alert,true / job,true（本文实测已达成）。remote-servers填本集群全部节点的IP:8080（多节点逗号分隔），供告警等远程监听同步。
② 路由配置（routerConfig）：单机部署默认路由已够用（config 表 routerConfig 行初始为 backup-server=127.0.0.1）；多节点集群时在控制台「配置管理 → 全局系统配置 → 客户端路由」按官方模板把各节点 2280 加入 <default-server>/<server-group>。路由数据同样存 MySQL，改一次全集群生效。逐字段含义见《CAT 监控 3.1.0 配置参数详解》。
4.11 重启前数据保护（checkpoint，生产建议）
官方建议重启前调用 checkpoint 接口，把内存中的实时消息落盘，重启后可恢复：
curl -s -o /dev/null -w '%{http_code}\n' 'http://127.0.0.1:8080/cat/r/home?op=checkpoint'
实测输出：
200
⚠️ 官方注意事项：checkpoint 应在每小时的整点后 10-55 分钟之间调用（避开整点小时报表落盘窗口）；生产部署建议把该调用写进 Tomcat 的 stop 脚本。单机验证环境可跳过。
五、方案 B：WAR 包离线部署（构建机与运行机分离）
当目标服务器不能访问外网（无法 git clone / mvn 构建）时，先在有网的构建机完成 4.1-4.4 节，再把构建产物与配置打成离线包转到运行机执行本章步骤。
5.1 构建机上制作离线包
mkdir -p /opt/deploy
cp /opt/cat-src/cat-home/target/cat-home.war /opt/deploy/cat.war
tar -czf /opt/deploy/cat-3.1.0-offline.tar.gz -C /opt/deploy cat.war -C /data/appdatas cat
ls -la /opt/deploy/
实测输出：
total 68
drwxr-xr-x 2 root root 4096 Oct 23 00:12 .
drwxr-xr-x 1 root root 4096 Oct 23 00:12 ..
-rw-r--r-- 1 root root 13653951 Oct 23 00:12 cat-3.1.0-offline.tar.gz
-rw-r--r-- 1 root root 61600678 Oct 23 00:08 cat.war
（离线包含 cat.war + data/appdatas/cat/ 三份配置；数据库账号密码以运行机实际值修改。）
5.2 传输到运行机
用 scp 把离线包拷到运行机（在运行机 cat-server.local 可达的网络内执行，<构建机IP> 按实际替换）：
scp root@<构建机IP>:/opt/deploy/cat-3.1.0-offline.tar.gz /opt/deploy/
传输完成后校验大小与源一致（本文两台实验机互通场景下用同一校验口径）：
ls -la /opt/deploy/cat-3.1.0-offline.tar.gz
md5sum /opt/deploy/cat-3.1.0-offline.tar.gz
💡 校验建议：传输前后各执行一次
md5sum，两机回显一致才算传输完整（61MB 级文件经内网传输偶发截断）。
5.3 运行机上落位
解包并按运行机实际数据库信息修正 datasources.xml，随后按 4.5-4.9 节完成建库、Tomcat 安装（4.7）、setenv.sh（4.8）与启动验证（4.9）——各步骤命令与回显同前文，不再重复：
tar -xzf /opt/deploy/cat-3.1.0-offline.tar.gz -C /
cp /cat.war /opt/tomcat/webapps/cat.war
mkdir -p /data/appdatas/cat /data/applogs/cat
# 修正数据库地址（vi 打开后将 jdbc:mysql:// 行替换为运行机可达的数据库地址）
vi /data/appdatas/cat/datasources.xml
⚠️ 注意：运行机仍需 JDK 8（仅运行不需 Maven）；Tomcat 需提前按 4.7 节装好。数据库建库脚本
CatApplication.sql需随离线包一起携带（也可从源码包script/目录获取）。
六、方案对比与选择建议
| 维度 | 方案 A：源码构建部署 | 方案 B：WAR 离线部署 |
|---|---|---|
| 前置网络 | 构建机需访问 GitHub + Maven 仓库 | 运行机完全离线，仅构建机需外网 |
| 安装方式 | git clone + mvn 构建 + Tomcat | tar 包传输 + Tomcat |
| 版本可控性 | 可审源码、可打补丁 | 锁定构建产物，不可中途改码 |
| 升级方式 | 重新拉 tag 构建 | 重新构建离线包 |
| 适用场景 | 首次安装、需要源码级排障 | 生产内网批量部署 |
选择建议：首次安装与内部验证用方案 A（本文主线）；构建机固定一台、目标服务器多台且隔离时用方案 B 批量铺开。两方案最终运行形态完全一致（同一 cat.war + 同一套 /data/appdatas/cat 配置）。
七、部署后配置说明
- JVM 内存调整位置：
/opt/tomcat/bin/setenv.sh的CATALINA_OPTS行（4.8 节）。改完shutdown.sh && startup.sh重启生效，并用jps -v验证（回显见 4.9 节 ②）。生产按官方建议把堆放大至 10G 级并追加 GC 参数。 - 控制台密码：同在 setenv.sh，改
-DCAT_ADMIN_PWD=<新密码>；账号固定为admin（源码硬编码），官方亦支持CAT_AUTH_TYPE=LDAP接入企业 LDAP（需同时配CAT_LDAP_URL/CAT_LDAP_USER_DN_TPL）。 - 数据库连接：
/data/appdatas/cat/datasources.xml，改完重启 Tomcat。 - 客户端路由：
/data/appdatas/cat/client.xml指向服务端集群地址，可由运维工具统一下发（官方建议 puppet 类工具维护）；路由异常且存在client_cache.xml缓存时，删缓存文件再重启。 - 服务端角色/存储/路由的权威配置：MySQL
config表 + 控制台「配置管理」页（详见《CAT 监控 3.1.0 配置参数详解》）。
八、常见问题（FAQ）
Q1：启动日志报 Error when connecting to JDBC data source(cat) ... Connections could not be acquired from the underlying database!，随后页面 500，怎么办？
这是本文实测遇到的最大坑：CAT 3.1.0 的 WAR 内置驱动为 mysql-connector-java-5.1.20.jar（2012 年版本，实测 ls /opt/tomcat/webapps/cat/WEB-INF/lib/ | grep -i mysql 回显 mysql-connector-java-5.1.20.jar），对 MySQL 8 兼容性不足。本文实测 MySQL 8.0.46 下的完整报错：
[10-22 23:39:05.693] [ERROR] [ServerConfigManager] Error when connecting to JDBC data source(cat) with properties
(driver=com.mysql.jdbc.Driver, url=jdbc:mysql://<db>:3306/cat?useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&socketTimeout=120000, user=root).
Error message=java.sql.SQLException: Connections could not be acquired from the underlying database!
同时伴随反复刷屏的：
[INFO] [JdbcDataSource] Connecting to JDBC data source(cat) with properties(...) ...
（连接永远悬在 Connecting 状态，无成功日志。）
定位→解决：核对数据库版本——mysql -h<db> -uroot -p -e "SELECT VERSION();" 若为 8.0.x，按官方支持矩阵「更高版本 MySQL 都不建议使用」改用 MySQL 5.7（本文实测 5.7.44 + --max-allowed-packet=1G 一次通过，建库导入后启动成功）。若因环境限制必须用 MySQL 8，官方口径为「不清楚兼容性」，需自行评估升级内置驱动（涉及 WEB-INF/lib 换 jar 与 datasources.xml 驱动类名），不在官方支持路径内。
Q2：mvn 构建报找不到类/编译错误？
九成是 JDK 版本不对。确认 java -version 为 1.8.x 且 mvn -version 的 Java version 行同样显示 1.8（JDK 11+ 会触发旧插件不兼容）。切换方法见 4.1 节踩坑实录 1。
Q3：Maven 下载依赖极慢或卡死？
给 Maven 配国内镜像（4.3 节 aliyun settings.xml）。官方文档另提示：v3.0.1 之前的老代码依赖托管在 http://unidal.org/nexus/，构建 3.1.0 无需该仓库。
Q4：启动初期日志狂刷 error when connect cat server config url http://127.0.0.1:8080/cat/s/router 与 Error when try connecting to /127.0.0.1:2280？
启动顺序导致，属预期现象：CAT 服务端自身的「客户端」线程先于 WAR 完全就绪启动，去拉路由、连 2280 时服务端还没监听，报错后由 ChannelManager 周期重连，服务端就绪后自动恢复。实测日志样例：
[10-22 23:38:41.383] [ERROR] [ChannelManager] Error when try connecting to /127.0.0.1:2280
[10-22 23:40:50.410 INFO] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["http-nio-8080"]
（8080 起来后该报错不再出现，页面可访问。）判断标准：netstat -ltn 中 2280/8080 都 LISTEN 且 curl 返回 200 即健康。
Q5：改了 server.xml 但角色（job-machine 等）没生效？
3.x 生效配置在数据库 config 表 server-config 行，server.xml 仅为初始化源。用控制台 http://<ip>:8080/cat/s/config?op=serverConfigUpdate 提交新 XML（或直接更新该行）后重启该节点，用 grep 'CAT server is running' /data/appdatas/cat/cat_<日期>.log 验证（4.9 节 ④ 实测回显）。
Q6：执行 shutdown.sh 后端口仍被占用、再 startup 后请求全部挂起？
旧进程未退干净。用 jps -l 或 ps -ef | grep java 确认残留 Bootstrap 进程 PID，kill -9 <PID> 逐个清理后再启动（避免 pkill -f 带自匹配关键字误杀当前 Shell 的坑，本文实测以 jps 取 PID 更稳）；重启前按 4.11 节调 checkpoint。
Q7：首次启动特别慢（一两分钟）？
正常。实测首次 WAR 解包 + 26 张表 DAL 初始化共约 130 秒（catalina.out 中 Server startup in [133208] milliseconds），后续重启约 10 秒内（实测 Server startup in [4393] milliseconds）。
Q8：报表中文乱码？
三处编码对齐：数据库建库用 utf8mb4/utf8（4.5 节）、datasources.xml 连接串带 characterEncoding=UTF-8（4.6 节 ②）、JVM 加 -Dfile.encoding=UTF-8（4.8 节）。Tomcat 9 的 URI 默认编码已为 UTF-8，无需再改 server.xml；若用 Tomcat 7/8 需按官方文档给 8080 Connector 加 URIEncoding="utf-8"。
九、卸载与清理
按以下顺序完整卸载 CAT 服务端（每步独立执行）：
# 1. 停止 Tomcat
/opt/tomcat/bin/shutdown.sh
# 2. 确认无残留进程（应无输出）
jps -l | grep Bootstrap
# 3. 删除 WAR 与解包目录
rm -f /opt/tomcat/webapps/cat.war
rm -rf /opt/tomcat/webapps/cat
# 4. 删除 CAT 配置与本地数据（含 bucket 消息文件与日志）
rm -rf /data/appdatas/cat /data/applogs/cat
# 5. 删除源码与部署中转目录（如不再构建）
rm -rf /opt/cat-src /opt/deploy
# 6. 数据库侧删除库（谨慎：删除全部监控数据）
mysql -h10.89.66.2 -uroot -pq1w2e3r4 -e "DROP DATABASE IF EXISTS cat;"
# 7.（可选）整包移除 Tomcat 与 Maven 缓存
rm -rf /opt/tomcat /root/.m2/repository
十、参考链接
- 官方仓库与源码（tag 3.1.0）：https://github.com/dianping/Cat
- 官方服务端部署文档（Wiki readme_server，本文版本矩阵与步骤依据）：https://github.com/dianping/cat/wiki/readme_server
- 建库脚本（源码内）：https://github.com/dianping/Cat/blob/master/script/CatApplication.sql
- 官方 docker 配置模板（datasources.xml/client.xml）：https://github.com/dianping/Cat/tree/master/docker
- 部署 FAQ（官方 Wiki）：https://github.com/dianping/cat/wiki/cat_faq
- Apache Tomcat 9 下载：https://dlcdn.apache.org/tomcat/tomcat-9/
- 本专栏姊妹篇：《CAT 监控 3.1.0 介绍与选型指南》、《CAT 监控 3.1.0 配置参数详解》、《CAT 监控 3.1.0 常用 CLI 命令与工具详解》