企业官网建设流程全解析

• 可观测性
• 指标监控
• 告警
• APM
• 后端
• 链路追踪

CAT（Central Application Tracking）是由美团点评开源的分布式监控系统，其各语言客户端（Java、C/C++、Node.js、Python、Go 等）在启动并上报埋点数据之前，都需要在本地完成一套统一的"落地准备"：创建两个约定目录、放置一份服务端地址配置文件。这篇指南以仓库中的 preparations.zh-CN.md 为骨架，结合多语言客户端源码与 Docker/Helm 部署脚本，完整讲解 CAT 客户端初始化前必须完成的准备工作，以及这些路径约定背后的实现原理。读完本文，你将能独立为任意一台业务机器完成 CAT 客户端的前置环境配置，并理解 CAT_HOME、client.xml、client_cache.xml 等关键机制的工作方式。

准备工作总览：三步完成 CAT 客户端本地初始化

CAT 客户端在初始化时会读取本地磁盘上的目录与配置文件，作为连接服务端的唯一依据。按照官方文档，初始化前需要完成三个步骤：

1. 创建/data/appdatas/cat目录，并确保具备读写权限；
2. 创建/data/applogs/cat目录（可选，但强烈建议），用于存放运行时日志；
3. 在/data/appdatas/cat下创建client.xml，填入 CAT 服务端地址。

这三步看似简单，却直接决定客户端能否找到服务端、能否持久化路由信息、能否输出可诊断的日志。下面逐项展开。

第一步：创建 /data/appdatas/cat 目录

CAT 将/data/appdatas/cat约定为客户端配置与数据的主目录，所有关键文件都存放于此。创建命令如下：

mkdir -p /data/appdatas/cat

创建后务必确认读写权限，CAT 客户端进程需要在该目录下读取配置、写入路由缓存文件：

ls -ld /data/appdatas/cat

官方英文文档（preparations.md）特别强调，该目录需要具备读写权限（≥ 0644）。权限不足时，客户端在读取client.xml或写入路由缓存时会出现异常，导致无法正常连接服务端。

CAT_HOME：为什么默认值是 /data/appdatas/cat

/data/appdatas/cat并非硬编码在每一个调用点，而是通过CAT_HOME环境变量统一管理的。在 Java 客户端中，Cat.getCatHome() 的定义为：

public static String getCatHome() { return Properties.forString().fromEnv().fromSystem().getProperty("CAT_HOME", "/data/appdatas/cat/"); }

也就是说，配置查找顺序为环境变量 → 系统属性 → 默认值：当环境变量或 JVM 系统属性（-DCAT_HOME=...）未设置时，客户端一律回落到/data/appdatas/cat/。这意味着：

• 默认部署下，只需严格按文档创建/data/appdatas/cat即可；
• 若出于目录规划需要，可通过CAT_HOME整体迁移配置目录，例如将 CAT_HOME 指向/opt/cat，则client.xml的查找路径会同步变为/opt/cat/client.xml；
• 对标准多机部署，建议所有机器保持一致的 CAT_HOME，避免配置管理混乱。

C 客户端同样遵守这一约定。lib/c/src/ccat/client_config.h 中可以看到：

// #define DEFAULT_XML_FILE "/data/appdatas/cat/client.xml" // 通过指定环境变量CAT_HOME来修改此路径 #define DEFAULT_CAT_HOME "/data/appdatas/cat/" // #define DEFAULT_DATA_DIR "/data/appdatas/cat/"

由此可以推断，C/C++ 客户端的默认配置路径同样是CAT_HOME环境变量 +/data/appdatas/cat/默认值，多语言客户端在此处保持了完全一致的约定。

第二步：创建 /data/appdatas/cat 的兄弟目录 /data/applogs/cat（强烈建议）

/data/applogs/cat是 CAT 客户端运行时日志的存放目录，官方文档将其标注为可选，但明确说明"这对调试将提供很大帮助"。

mkdir -p /data/applogs/cat

同样需要读写权限，因为客户端会在该目录下追加写入日志文件。

日志文件长什么样：cat_client_yyyyMMdd.log

从 Java 客户端源码 CatLogger.java 可以确认日志的实际落盘细节：

private static final String DEFAULT_BASE_DIR = "/data/applogs/cat"; ... private File getFilePath(String path) throws IOException { File file = new File(path); String baseDir = Properties.forString().fromSystem().fromEnv().getProperty("CAT_HOME", DEFAULT_BASE_DIR); if (baseDir != null) { file = new File(baseDir, path); } return file.getCanonicalFile(); }

日志文件按天滚动，命名格式为cat_client_yyyyMMdd.log，例如cat_client_20260920.log。当连接异常、配置解析失败、上报失败时，错误信息都会写入该日志，是排查 CAT 客户端问题的一手资料。

需要留意的一个细节：日志目录的默认值同样取自CAT_HOME属性（环境变量CAT_HOME或系统属性），缺省时才回落为/data/applogs/cat。如果第一步中自定义了 CAT_HOME，日志路径也会随之改变——因此在自定义 CAT_HOME 时，应同时确保日志目录有对应权限。

第三步：创建 client.xml 并填写服务端地址

这是准备工作的核心。在/data/appdatas/cat下创建client.xml，内容如下：

<?xml version="1.0" encoding="utf-8"?> <config xmlns:xsi="http://www.w3.org/2001/XMLSchema" xsi:noNamespaceSchemaLocation="config.xsd"> <servers> <server ip="<cat server ip address>" port="2280" http-port="8080" /> </servers> </config>

不要忘记把<cat server IP address>替换成你自己的服务器地址！

字段语义与端口约定

client.xml 是客户端连接服务端的唯一地址来源，其核心字段含义如下：

多台服务端的配置示例如下（摘自 lib/java/README.zh-CN.md）：

<?xml version="1.0" encoding="utf-8"?> <config mode="client"> <servers> <server ip="10.1.1.1" port="2280" http-port="8080"/> <server ip="10.1.1.2" port="2280" http-port="8080"/> <server ip="10.1.1.3" port="2280" http-port="8080"/> </servers> </config>

官方对端口的约束非常明确："2280 是默认的 CAT 服务端接受数据的端口，不允许修改，http-port 是 Tomcat 启动的端口，默认是 8080，建议使用默认端口"。

源码层面同样印证了这一默认值。在 Server.java 中：

private int port = 2280; private int httpPort = 8080;

服务端 Docker 部署也将 2280 作为对外暴露的接收端口，见 docker-compose.yml 中的"2280:2280"映射。

client.xml 在启动流程中的实际作用

从源码调用链看，client.xml 并不是一个"装饰性"文件，而是客户端初始化的输入源头。ApplicationEnvironment.loadClientConfig 的加载顺序为：

1. 若client_cache.xml（路由缓存）存在且未开启 devMode，优先读取缓存；
2. 否则读取client.xml；
3. 两者都不存在时，回退到远程拉取（loadRemoteClientConfig，请求http://{CAT_HOST}/cat/s/launch）。

其中CLIENT_FILE = "client.xml"、CACHE_FILE = "client_cache.xml"、配置目录通过Cat.getCatHome()取得（见 ApplicationEnvironment.java）。加载到的ClientConfig会设置上业务 domain（应用标识），供后续消息树打点使用。

也就是说，一份正确的 client.xml 是客户端稳定连上服务端的"第一块基石"；而 client_cache.xml 是客户端在运行时根据服务端下发结果写入的路由缓存文件——若路由出现错误，删除 client_cache.xml 后重启服务即可重新拉取（见 lib/java/README.zh-CN.md）。

权限与常见错误

• 确认/data/appdatas/cat/client.xml可读，且进程用户具备写入目录权限（用于写 client_cache.xml）；
• 若client.xml缺失，客户端会尝试远程拉取路由配置，在无法访问服务端的情况下将抛出异常并提示"contact cat support team for help"（见 ApplicationEnvironment.java 对应的源码逻辑）；
• 若日志目录不存在，运行时诊断信息无处落盘，排查问题会非常困难，因此强烈建议创建/data/applogs/cat。

完整的初始化检查清单

完成以上三步后，可以用下面的清单做一次自检：

# 1. 配置目录存在且可写 ls -ld /data/appdatas/cat # 2. 日志目录存在且可写（建议） ls -ld /data/applogs/cat # 3. 配置文件存在且 IP 已替换 cat /data/appdatas/cat/client.xml # 4.（可选）确认 CAT_HOME 未做非常规覆盖 echo $CAT_HOME

各项就绪后即可进入客户端初始化与打点阶段：Java 客户端需在src/main/resources/META-INF/app.properties中配置app.name={appkey}（appkey 仅允许英文字母、数字、下划线与中划线），Java 版 cat client 现在会自动懒加载，无需手动初始化（详见 lib/java/README.zh-CN.md）。

容器化部署中的目录映射

在 Docker/Kubernetes 部署场景下，同样的目录约定通过挂载或持久卷实现：

• Docker 方式：将宿主机的 client.xml 挂载到容器内/data/appdatas/cat/client.xml，并暴露 2280 端口，参见 docker-compose.yml；
• Kubernetes 方式：通过 ConfigMap 生成 client.xml 并挂载至/data/appdatas/cat/client.xml，见 Helm 模板 configmap-cat-client-xml.yaml 与 values.yaml。

无论以何种方式部署，容器内 CAT 客户端读取的仍然是/data/appdatas/cat/client.xml这一约定路径，目录准备逻辑与裸机部署完全一致。

总结

CAT 客户端的初始化准备只有三步：创建/data/appdatas/cat、创建/data/applogs/cat（强烈建议）、配置client.xml。背后是 CAT_HOME 统一管理的路径约定（默认/data/appdatas/cat/，日志默认/data/applogs/cat）、2280/8080 双端口约定，以及 client.xml → client_cache.xml → 远程拉取的配置加载链。理解这套约定，无论使用 Java、C/C++ 还是其他语言客户端，无论裸机部署还是容器化部署，都能快速完成客户端上线，并在出现问题时从运行日志与路由缓存入手高效定位。

• 可观测性
• 指标监控
• 告警
• APM
• 后端
• 链路追踪