Categraf 企业版升级说明

适用范围

本文说明 Categraf 企业版的升级和降级方式，重点说明通过 Web 控制台触发 Categraf 版本切换的限制和注意事项。

Web 版本切换依赖 Categraf 的 heartbeat 机制：Agent 周期性向服务端上报心跳，服务端在心跳响应中下发目标版本和下载地址，Agent 收到后自行下载、替换二进制并重启服务。

注意：Web 版本切换只适用于由 systemd 托管的 Linux Categraf 服务。Docker 容器、Kubernetes Pod、手工前台运行、nohup、supervisord，以及未注册为 systemd 服务的环境，不支持 Web 升级或降级。容器化环境请更新镜像，并通过 Docker Compose、Deployment、StatefulSet 等方式重新发布。

Web 版本切换原理

Web 控制台发起版本切换后，服务端会在目标机器下一次 heartbeat 响应中返回：

• new_version：目标版本。
• download_url：目标版本升级包下载地址。

Agent 判断 new_version 和当前上报版本不同后，会执行本机升级命令：

categraf -update -update_url <download_url>

随后 Agent 下载升级包，解压出新的 categraf 二进制，替换当前二进制并重启服务。重启后的 Agent 会在后续 heartbeat 中上报实际运行版本，Web 控制台据此展示结果。

heartbeat 会上传序列化后的主配置，配置中可能包含鉴权字段。生产环境请使用 HTTPS heartbeat 地址，并只连接可信服务端。

升级前检查

升级前请先确认以下条件：

heartbeat 配置示例：

[heartbeat]
enable = true
url = "https://n9e.example.com/v1/n9e-plus/heartbeat"
interval = 10
timeout = 5000
dial_timeout = 2500
max_idle_conns_per_host = 100

如果未显式配置 heartbeat.url，但配置了 global.n9e_server.address，Agent 会使用默认路径：

/v1/n9e-plus/heartbeat

Web 操作流程

1. 在 Web 控制台确认目标机器在线。
2. 确认目标 Agent 由 systemd 托管。Docker、Kubernetes、nohup、supervisord 等环境不要纳入 Web 升级批次。
3. 确认操作系统、Linux 内核版本、CPU 架构满足要求。
4. 确认当前 Agent 版本和目标版本满足下面的“当前版本兼容矩阵”和“版本变体选择规则”。
5. 准备正确平台的升级包，例如 linux-amd64、linux-arm64。
6. 确认 download_url 使用 HTTPS，并来自可信下载源。
7. 升级前在目标机器保留当前二进制备份。
8. 选择需要升级或降级的主机或主机分组。
9. 发起版本切换任务。
10. 等待 Agent 下一次 heartbeat 拉取指令。默认配置下通常 10 秒左右触发一次 heartbeat，实际时间以现场配置为准。
11. 在 Web 控制台查看版本切换结果，也可以登录机器查看服务日志和版本。

升级包要求

Linux 升级包应满足：

1. 生产环境必须使用 HTTPS 下载地址，并确认下载源可信。
2. HTTP 和省略 scheme 后自动按 http:// 处理仅属于兼容行为，不建议生产环境使用。当前升级流程不做包签名或摘要校验，HTTP 下载包被篡改后可能以 Categraf 服务权限执行。
3. 下载器不继承 heartbeat 的自定义 CA、客户端证书、Headers、Basic Auth 或代理配置。HTTPS 证书必须被系统 CA 信任；代理通常需要通过进程环境变量配置；下载鉴权建议使用带有效期的签名 URL。
4. 包格式为 tar.gz。
5. 包内必须包含名为 categraf 的目标二进制文件。
6. 包内只能有一个目标 categraf 二进制文件。
7. 包内二进制必须是当前机器可运行的平台，例如 Linux amd64 机器只能使用 Linux amd64 包。
8. Web 登记的 new_version 必须与包内二进制实际运行后上报的版本一致。Agent 只根据 heartbeat 响应中的 new_version 和当前上报版本判断是否替换，不会在替换前读取并校验包内版本。

当前版本兼容矩阵

v0.5.33 及以上 Agent 会在替换旧二进制之前做平台校验：

• 如果 URL 文件名明确包含错误平台，例如当前机器是 linux/amd64，但 URL 文件名包含 linux-arm64，会直接拒绝升级。
• 如果 URL 文件名没有平台信息，Agent 仍会下载升级包，并校验包内真实二进制的平台。
• 如果包内二进制平台与当前机器不一致，Agent 会中止升级，不覆盖当前二进制，不重启服务。

v0.5.33 以下 Agent 执行升级时不具备这些客户端侧保护能力。即使目标版本是 v0.5.34 或更高版本，本次下载、解压和替换动作仍由旧 Agent 执行，因此选错平台包可能直接覆盖当前二进制。

版本变体选择规则

Categraf 企业版发布包可能包含标准版本和特定能力变体版本，例如 servicemap、jetson、cgo 等。Web 版本切换时不要混用不明确的版本变体，否则可能因为二进制依赖、运行环境或启动参数差异导致服务启动失败。

请按以下规则选择升级包：

1. 普通标准包 Web 版本切换建议目标版本至少为 v0.5.34。
2. 变体版本 Web 版本切换建议目标版本至少为 v0.5.35。
3. v0.5.34 以下版本不支持通过 Web 切换到带 servicemap、jetson 等后缀的小版本或变体版本。
4. v0.5.32 升级到 v0.5.32-servicemap 是已知高风险场景，可能导致 Categraf 不停重启，最终达到 systemd 重启次数限制并造成 Categraf 失联。
5. v0.5.34-servicemap 仍可能被上报成基础版本，导致服务端重复下发升级指令、Agent 循环升级重启，因此不要作为 Web 变体升级目标。
6. v0.5.35 及以上版本，仅建议从标准 Linux 包升级到同架构的 servicemap Linux 包，例如从 linux-amd64 升级到 servicemap-linux-amd64，或从 linux-arm64 升级到 servicemap-linux-arm64。
7. v0.5.35 及以上版本也不要混用 jetson、cgo 等变体升级，避免因为 glibc 或其他系统库依赖差异导致升级后启动失败。
8. 如需使用 jetson、cgo 等特殊变体版本，建议按对应环境准备并执行手动升级，升级前先在同类机器上验证依赖和启动结果。

特殊系统限制

CentOS 6、Red Hat 6

Linux 内核版本低于 3.10 的系统不要通过 Web 升级，例如 CentOS 6、Red Hat Enterprise Linux 6。这类老系统最高建议使用 Categraf 企业版 v0.3.97。

下载地址：https://flashcat.cloud/download/categraf_ent/?version=v0.3.97

部分老版本 Agent 可能本身不支持 Web 升级，需要手动升级。

Windows

Windows 版本不支持从 Web 升级，只能手动升级。

• Windows 10 以下版本不支持运行 Categraf。
• Windows Server 2008 R2 以下版本不支持运行 Categraf。
• Windows Server 2008 R2 最高可运行版本为 Categraf 企业版 v0.3.97。

下载地址：https://flashcat.cloud/download/categraf_ent/?version=v0.3.97

HANA 插件

从 Categraf 企业版 v0.5.37 开始，HANA 采集插件已集成到通用版本中。运行 v0.5.37 及以上版本时，HANA 采集机器可以使用与其他插件相同的通用版本升级流程，无需再单独升级 HANA 插件。

v0.5.37 以前的 HANA 采集版本仍按独立版本管理。涉及这些旧版本的机器，升级前需要单独确认当前 HANA 版本和升级路径；升级到 v0.5.37 及以上通用版本后，后续可以按本文说明进行统一升级。

备份和恢复

Web 升级没有自动回滚。当前二进制被替换后，如果新版本重启失败，需要登录主机人工恢复旧二进制并重启服务。

升级前建议备份当前二进制。默认服务名是 categraf；如果安装时使用了 -service-name，请把下面命令中的 SERVICE_NAME 替换为实际服务名。如果 Categraf 安装路径不是 /opt/categraf/categraf，请把 CATEGRAF_BIN 替换为实际二进制路径。

SERVICE_NAME=categraf
CATEGRAF_BIN=/opt/categraf/categraf
sudo cp -a "$CATEGRAF_BIN" "$CATEGRAF_BIN.bak.$(date +%Y%m%d%H%M%S)"

如果升级后服务启动失败，必须先在 Web 侧撤销版本切换任务，或将该机器移出升级批次，再使用备份文件人工恢复并启动服务。否则恢复后的 Agent 可能在下一次 heartbeat 立即再次收到同一升级指令并重复替换。

如果暂时无法操作 Web 控制台，必须保持服务停止，或保持 heartbeat/下载链路被阻断，直到 Web 侧任务已撤销或该机器已移出升级批次。不要在升级任务仍会下发时恢复连接并启动服务。

系统级 systemd 服务恢复命令。执行 start 前必须确认 Web 侧任务已清理；如果还不能确认，只执行到 reset-failed，保持服务停止。

SERVICE_NAME=categraf
CATEGRAF_BIN=/opt/categraf/categraf
BACKUP_BIN=/opt/categraf/categraf.bak.20260101120000

sudo systemctl stop "$SERVICE_NAME"
sudo cp -a "$BACKUP_BIN" "$CATEGRAF_BIN"
sudo chmod +x "$CATEGRAF_BIN"
sudo systemctl reset-failed "$SERVICE_NAME"
sudo systemctl start "$SERVICE_NAME"
sudo systemctl status "$SERVICE_NAME"

用户级 systemd 服务恢复命令。执行 start 前必须确认 Web 侧任务已清理；如果还不能确认，只执行到 reset-failed，保持服务停止。

SERVICE_NAME=categraf
CATEGRAF_BIN=/opt/categraf/categraf
BACKUP_BIN=/opt/categraf/categraf.bak.20260101120000

systemctl --user stop "$SERVICE_NAME"
cp -a "$BACKUP_BIN" "$CATEGRAF_BIN"
chmod +x "$CATEGRAF_BIN"
systemctl --user reset-failed "$SERVICE_NAME"
systemctl --user start "$SERVICE_NAME"
systemctl --user status "$SERVICE_NAME"

升级验证

登录目标机器后，可执行：

categraf -version

如果 Categraf 安装路径没有加入 PATH，请使用实际安装路径执行，例如：

/opt/categraf/categraf -version

查看系统级 systemd 服务状态：

systemctl status categraf
journalctl -u categraf -n 200 --no-pager

如果是用户级 systemd 服务，使用：

systemctl --user status categraf
journalctl --user -u categraf -n 200 --no-pager

成功时日志中通常会出现类似信息：

update categraf(<old_version>) from <download_url> success, new version: <new_version>

常见问题

Web 发起后长时间无变化

检查 heartbeat 是否开启，Agent 是否能访问 heartbeat 地址，服务端鉴权是否正确。

Agent 在线但不执行版本切换

检查 Web 侧登记的 new_version 是否与 Agent 当前上报版本一致。目标版本与当前版本一致时，Agent 不会替换二进制。

Agent 反复替换并重启

常见原因是 Web 登记的 new_version 与目标二进制重启后实际上报版本不一致，或者旧版本丢失了变体标识。处理时先停止 Web 侧任务或移出升级批次，再人工恢复。

日志提示 exec ... timeout

heartbeat 拉起的本机升级命令有 300 秒超时限制。下载、解压、替换、服务重启在 300 秒内未完成会被判定为超时。慢速网络或大包场景下，后续 heartbeat 可能再次触发同一版本切换。

下载失败或 HTTP 状态码异常

在 Agent 主机上用 curl 测试 download_url，检查网络、防火墙、对象存储权限、签名 URL 是否过期，并确认下载源可信。升级下载器不继承 heartbeat 的 Headers、Basic Auth、自定义 CA、客户端证书或代理配置。

日志提示 linux support only

说明非 Linux 系统收到了 Web 升级指令。当前 Web 版本切换路径不支持该系统，请使用手动升级或其他发布方式。

日志提示 update only support mode that running in service mode

说明 Categraf 未以服务方式安装或运行。请先将 Categraf 安装为 systemd 服务，再使用 Web 版本切换。

日志提示 target binary categraf not found

升级包内没有名为 categraf 的二进制。请重新制作升级包，确保包内包含正确文件。

日志提示 multiple categraf binaries found

升级包内有多个 categraf 文件。请精简升级包，保留唯一目标二进制。

日志提示 update_url platform mismatch 或 target platform mismatch

升级包平台与当前机器不一致。请选择与目标机器 OS、CPU 架构匹配的升级包。

建议升级策略

1. 先选择少量测试机器升级，确认采集、日志、服务状态正常。
2. 按操作系统、CPU 架构和 Linux 内核版本拆分升级批次，避免混用升级包。
3. 排除 CentOS 6、Red Hat Enterprise Linux 6、Windows、容器化 Agent 和其他不满足 Web 升级条件的机器。
4. Web 版本切换既支持升级也支持降级，操作前必须确认 Web 登记版本与目标二进制实际上报版本一致。
5. 普通标准包 Web 升级目标版本建议至少选择 v0.5.34；变体升级目标版本建议至少选择 v0.5.35。
6. v0.5.35 及以上如需升级 servicemap，仅建议从标准 Linux 包升级到同架构 servicemap Linux 包，不要混用 jetson、cgo 等特殊变体。
7. 当前 Agent 低于 v0.5.33 时，不要依赖客户端侧平台校验，升级前必须人工确认升级包和备份。
8. 慢速网络或跨地域下载场景先验证下载耗时，避免本机升级命令超过 300 秒后被重复触发。
9. HANA 采集机器升级到 v0.5.37 及以上通用版本后，可以纳入统一升级；更早的独立 HANA 版本仍需单独确认升级路径。