Categraf 是监控链路的入口。升级它不像升级一个普通后台服务：如果升级失败，影响的不只是一个业务接口，而是主机、数据库、中间件、探测、日志或 Prometheus Agent 的数据入口。更麻烦的是，很多问题不会立刻表现为进程退出，而是某个插件少了一组指标、某些标签变了、Dashboard 变量为空、告警规则没有触发。
因此，Categraf 升级不能只做“替换二进制 + 重启”。一次可靠升级至少要包括：当前版本盘点、二进制和配置备份、新旧配置差异审查、灰度节点验证、后端指标验收，以及明确可执行的回滚命令。
本文给出一套偏生产实操的升级和回滚流程，适用于 systemd 裸机部署，也可以迁移到容器、配置管理或批量发布系统中。
核心要点
- 升级前必须同时备份二进制和配置目录；只备份
categraf不够，很多问题来自配置和 Dashboard 依赖变化。 - 先盘点当前启用的 Agent：Metrics、Logs、Prometheus、Ibex。不同 Agent 的配置、状态目录和发送链路不同。
- 不要直接用新版
conf覆盖生产配置；应先做差异审查，把新增默认项、废弃字段、插件配置变更逐项合并。 - 灰度节点要覆盖真实插件组合，至少包含 Linux 基础指标、一个数据库/中间件插件、一个 writer 链路和对应 Dashboard 查询。
--test只能验证采集和标签处理，不验证 remote write；升级验收还要看正式模式写入后的后端裸指标。- 二进制升级、主配置、writer、Logs Agent、Prometheus Agent 和环境变量变化，建议使用受控重启，不依赖 HUP。
- 回滚方案要在升级前写好，并验证旧二进制、旧配置、旧 unit 路径和旧环境文件都还可用。
- 生产升级不是单人手工动作，要把提前通报、完备步骤、分级发布、避开高峰和变更后检查纳入流程。
1. 升级前先做资产盘点
先确认这台机器到底运行了什么：
cd /opt/categraf
./categraf --version
sudo ./categraf --status
systemctl show categraf \
-p ExecStart \
-p WorkingDirectory \
-p User \
-p EnvironmentFiles
find /opt/categraf/conf -maxdepth 2 -type f | sort
同时记录主配置中的关键开关：
sed -n '1,220p' /opt/categraf/conf/config.toml
sed -n '1,180p' /opt/categraf/conf/logs.toml
重点看：
[global].providers是否只使用 local；[[writers]]写到哪个后端、哪个租户；[heartbeat]是否启用；[prometheus]是否启用，WAL 目录在哪里；[ibex]是否启用；logs.toml是否启用日志采集；- 哪些
input.*目录实际存在； - systemd 是否使用自定义用户和 EnvironmentFile。
不要只看进程名。Categraf 进程里可能同时运行 Metrics、Logs、Prometheus、Ibex 四类 Agent，升级影响面要按启用模块评估。
2. 备份二进制、配置和运行状态
建议每次升级使用带时间戳的备份目录：
ts=$(date +%Y%m%d%H%M%S)
sudo install -d -m 750 /opt/categraf-backup/$ts
sudo cp -a /opt/categraf/categraf /opt/categraf-backup/$ts/categraf
sudo cp -a /opt/categraf/conf /opt/categraf-backup/$ts/conf
if [ -f /etc/sysconfig/categraf ]; then
sudo cp -a /etc/sysconfig/categraf /opt/categraf-backup/$ts/categraf.sysconfig
fi
systemctl cat categraf | sudo tee /opt/categraf-backup/$ts/categraf.service.txt >/dev/null
/opt/categraf/categraf --version | sudo tee /opt/categraf-backup/$ts/version.txt >/dev/null
如果启用了 Prometheus Agent，还要确认 WAL 目录：
[prometheus]
enable = true
# wal_storage_path = "/path/to/storage"
WAL 是否备份取决于运维策略。通常不建议在升级窗口里复制大体量 WAL；更重要的是保证回滚后路径、权限和剩余磁盘空间都正确。Logs Agent 的读取状态目录、Ibex 的 meta_dir 也要纳入权限检查。
最少要能回答：
旧二进制在哪里
旧配置在哪里
旧 EnvironmentFile 在哪里
旧 systemd unit 长什么样
旧版本号是多少
回滚后如何确认数据恢复
3. 不要直接覆盖生产 conf
新版发布包通常会带一份默认 conf。这份配置适合参考，不适合直接覆盖生产目录。正确做法是把新版解压到临时目录：
mkdir -p /tmp/categraf-new
tar -xf categraf-new.tar.gz -C /tmp/categraf-new --strip-components=1
/tmp/categraf-new/categraf --version
find /tmp/categraf-new/conf -maxdepth 2 -type f | sort
对比主配置：
diff -u /opt/categraf/conf/config.toml /tmp/categraf-new/conf/config.toml || true
diff -u /opt/categraf/conf/logs.toml /tmp/categraf-new/conf/logs.toml || true
对比目标插件配置：
diff -u /opt/categraf/conf/input.redis/redis.toml \
/tmp/categraf-new/conf/input.redis/redis.toml || true
diff -u /opt/categraf/conf/input.postgresql/postgresql.toml \
/tmp/categraf-new/conf/input.postgresql/postgresql.toml || true
需要重点关注：
- 新增配置项是否有默认值变化；
- 字段名是否调整；
- input 目录名是否变化；
- Dashboard 依赖的标签是否变化；
- writer、heartbeat、logs、prometheus 是否新增安全或性能参数；
- 插件 README 是否提示权限、指标名或采集范围变化；
- 是否新增高基数字段，需要用过滤或限制参数控制。
配置合并建议通过配置管理或人工审查完成，不要用一条 cp -r new/conf /opt/categraf/conf 结束。
4. 先在测试或灰度节点验证
灰度节点应尽量覆盖真实使用场景。比如生产启用了：
- Linux 主机指标；
- Redis；
- PostgreSQL；
- HTTP 探测；
- remote write 到夜莺或 VictoriaMetrics；
- Dashboard 和告警。
灰度就至少验证这些路径中的代表项：
cd /opt/categraf
./categraf --test --inputs cpu:mem:system
./categraf --test --inputs redis
./categraf --test --inputs postgresql
./categraf --test --inputs http_response
--test 通过后，还要验证正式写入。可以在灰度节点短时间重启正式服务：
sudo ./categraf --stop
sudo ./categraf --start
sudo ./categraf --status
journalctl -u categraf -n 200 --no-pager
后端查询：
system_load1
redis_up
postgresql_up
http_response_result_code
再看关键标签：
count by (agent_hostname) (system_load1)
count by (instance, agent_hostname) (redis_up)
count by (server, instance, agent_hostname) (postgresql_up)
count by (target, service, agent_hostname) (http_response_result_code)
如果 Dashboard 变量依赖 instance、server、target 或 ident，必须确认这些标签仍然存在且取值没有意外变化。
5. 升级前冻结变更窗口
升级窗口内不要同时做这些事：
- 批量新增插件；
- 大规模调整标签规范；
- 替换 writer 后端；
- 切换夜莺或 VictoriaMetrics 租户；
- 修改 Dashboard JSON；
- 改 systemd 运行用户；
- 调整 Prometheus Agent WAL 路径；
- 修改日志采集范围。
这些变更本身都可能造成数据变化。把它们和版本升级混在一起，会让回滚判断变得困难。稳妥做法是：
先升级二进制和必要兼容配置
-> 验证数据链路稳定
-> 再单独发布标签、Dashboard 或插件范围调整
很多运维团队会把线上变更纪律总结成类似“五条军规”的形式。放到 Categraf 升级里，可以对应成下面这张检查表：
| 变更纪律 | 在 Categraf 升级中的落点 |
|---|---|
| 提前通报 | 升级前在团队、值班群或相关频道公告，说明影响节点、窗口、验证方式和回滚责任人 |
| 步骤完备 | 操作方案必须包含备份、替换、重启、验证、回滚命令和失败判断标准 |
| 分级发布 | 先测试或灰度节点，再按批次扩大范围，不直接全量替换所有采集器 |
| 避开高峰 | 高风险升级避开业务流量高峰、发布高峰和重大活动保障窗口 |
| 服务检查 | 升级后检查 Categraf 服务状态、日志、后端裸指标、Dashboard 变量和关键告警 |
这五条不是额外的形式主义，而是为了降低监控入口自身变更带来的盲区。尤其是 Categraf 这种采集器，升级失败可能不会立刻影响业务请求，但会影响故障发现能力，因此变更通知和变更后检查要和技术命令放在同一张执行单里。
6. systemd 裸机升级步骤
假设新二进制已经放在：
/tmp/categraf-new/categraf
并且配置差异已经合并到：
/opt/categraf/conf
升级步骤：
cd /opt/categraf
sudo ./categraf --status
sudo ./categraf --stop
sudo install -m 755 /tmp/categraf-new/categraf /opt/categraf/categraf
/opt/categraf/categraf --version
./categraf --test --inputs cpu
sudo ./categraf --start
sudo ./categraf --status
journalctl -u categraf -n 200 --no-pager
如果升级同时改了 unit 路径或从临时目录重新安装，必须检查：
systemctl show categraf -p ExecStart -p WorkingDirectory
通常不需要重新 --install。只有 unit 指向错误路径、需要重建 service，或者从非标准目录迁移到 /opt/categraf 时，才执行：
sudo ./categraf --remove
sudo ./categraf --install
sudo ./categraf --start
执行前要确认自定义 unit 内容已经备份，否则可能覆盖或丢失安全加固配置。
7. 容器升级步骤
容器部署的关键是镜像版本和 volume。不要用漂移的 latest 作为生产唯一记录，建议使用明确 tag 或镜像 digest。
升级前记录：
docker inspect categraf --format '{{.Config.Image}}'
docker inspect categraf --format '{{json .Mounts}}'
docker logs --tail=100 categraf
Compose 场景：
docker compose pull categraf
docker compose up -d categraf
docker compose ps
docker compose logs --tail=100 categraf
如果使用普通 Docker：
docker stop categraf
docker rename categraf categraf-before-upgrade
docker run -d \
--name categraf \
--restart unless-stopped \
-v /opt/categraf/conf:/etc/categraf/conf:ro \
-v /opt/categraf/run:/opt/categraf/run \
-v /opt/categraf/data-agent:/opt/categraf/data-agent \
-v /opt/categraf/meta:/opt/categraf/meta \
flashcatcloud/categraf:<NEW_VERSION> \
/usr/bin/categraf -configs=/etc/categraf/conf
不要删除旧容器，直到新容器完成验收。回滚时可以停止新容器，恢复旧容器：
docker stop categraf
docker rm categraf
docker rename categraf-before-upgrade categraf
docker start categraf
前提是旧容器仍然引用旧镜像、旧配置 volume 也没有被破坏。因此容器升级同样要先备份宿主机上的 conf。
8. 升级后的验收清单
服务层：
sudo ./categraf --status
systemctl show categraf -p ExecStart -p WorkingDirectory -p User
journalctl -u categraf -n 200 --no-pager
进程层：
/opt/categraf/categraf --version
pgrep -af categraf
采集层：
./categraf --test --inputs redis
./categraf --test --inputs postgresql
写入层：
redis_up
postgresql_up
标签层：
count by (instance, agent_hostname) (redis_up)
count by (server, instance, agent_hostname) (postgresql_up)
Dashboard 层：
- 变量能列出实例；
- 核心面板不是 No data；
- 最近 15 分钟有新样本；
- 告警规则引用的指标仍然存在；
- 告警模板中的标签仍然有值。
self metrics 层，如果启用了：
categraf_metrics_queue_size
categraf_metrics_enqueue_failed_total
不要只验收 system_load1。Linux 基础指标正常，不代表数据库、探测、日志或 Prometheus Agent 也正常。
9. 什么时候应该回滚
以下情况建议优先回滚，而不是在线继续试错：
- Categraf 服务无法稳定启动；
- remote write 持续失败，后端没有新样本；
- 核心插件
--test报错且无法快速修复； - 关键 Dashboard 大面积 No data；
- 标签主维度变化导致告警无法匹配；
- Prometheus Agent WAL 或 Logs Agent 状态目录权限异常；
- CPU、内存或采集耗时明显异常；
- 新版本引入的配置差异无法在窗口内确认。
可以现场修复的小问题：
- 某个非核心插件配置缺失；
- 单个测试目标认证失败；
- Dashboard 某个非关键变量需要更新；
- 日志级别或轮转参数需要微调。
判断标准很简单：如果影响监控主链路，先恢复数据入口；如果只是局部增强项，可以记录并后续修复。
10. systemd 回滚步骤
假设备份目录为：
backup=/opt/categraf-backup/20260721103000
回滚：
cd /opt/categraf
sudo ./categraf --stop
sudo cp -a "$backup/categraf" /opt/categraf/categraf
sudo rm -rf /opt/categraf/conf
sudo cp -a "$backup/conf" /opt/categraf/conf
if [ -f "$backup/categraf.sysconfig" ]; then
sudo cp -a "$backup/categraf.sysconfig" /etc/sysconfig/categraf
fi
/opt/categraf/categraf --version
./categraf --test --inputs cpu
sudo ./categraf --start
sudo ./categraf --status
journalctl -u categraf -n 200 --no-pager
然后验证后端：
system_load1
redis_up
postgresql_up
如果升级过程中重建过 unit，还要对照备份的 categraf.service.txt 检查：
systemctl cat categraf
systemctl show categraf -p ExecStart -p WorkingDirectory -p User -p EnvironmentFiles
必要时重新执行旧目录下的 --remove / --install，但不要在未理解当前 unit 的情况下直接删除服务文件。
11. 回滚后也要复盘配置差异
回滚完成不等于问题结束。至少记录：
- 新旧版本号；
- 失败发生在哪个阶段：启动、采集、写入、Dashboard、告警；
- 第一条错误日志；
- 受影响插件；
- 受影响标签或指标；
- 是否影响告警；
- 回滚耗时；
- 是否需要补测试用例、Dashboard 或文档。
建议保留升级前后的核心查询结果：
count by (__name__) ({__name__=~"redis_.*"})
count by (instance, agent_hostname) (redis_up)
count by (server, instance, agent_hostname) (postgresql_up)
这些结果能帮助判断是指标消失、标签变化，还是 Dashboard 查询条件不兼容。
12. 版本兼容重点看什么
每次升级至少检查这些兼容点：
| 类别 | 检查点 |
|---|---|
| 主配置 | 新增字段、默认值、writer、heartbeat、http、provider |
| input 配置 | 字段名、默认采集范围、认证、TLS、过滤参数 |
| 指标名 | 是否新增、改名、废弃或补兼容指标 |
| 标签 | 主维度是否变化，是否新增高基数标签 |
| Dashboard | 变量基准指标和标签是否仍存在 |
| 告警 | PromQL、for 时长、标签模板是否仍匹配 |
| Logs Agent | logs.toml、run 状态、send_to |
| Prometheus Agent | YAML、remote_write、WAL 路径和权限 |
| systemd | unit 路径、环境文件、运行用户 |
| 容器 | 镜像 tag、volume、网络、UID/GID |
插件实战文章里常见的 instance、server、target、ident 是 Dashboard 和告警最敏感的标签。升级后只要这些标签变化，即使指标还在，也可能造成展示和告警异常。
13. 常见问题
升级前只备份二进制可以吗？
不够。配置、EnvironmentFile、unit 和部分状态目录同样会影响运行结果。至少备份二进制、conf、EnvironmentFile 和 unit 内容。
可以直接用新版默认配置覆盖旧配置吗？
不建议。新版默认配置可能缺少你的 writer、认证、标签、插件开关和过滤规则。应使用 diff 合并必要变化。
--test 通过就能发布吗？
不能。--test 不写入后端，只能证明采集侧。还要让正式模式运行，并在后端查询最新裸指标。
升级时要不要重新 --install？
通常不需要。原 unit 指向 /opt/categraf/categraf，替换二进制后重启即可。只有 unit 路径错误、迁移目录或需要调整 service 配置时才重建。
回滚后 Dashboard 仍然空怎么办？
先查后端裸指标和真实标签。如果裸指标恢复但 Dashboard 空，可能是升级期间改过 Dashboard、变量或标签规范，需要回滚对应 JSON 或变量配置。
14. 生产建议
- 每次升级前生成带时间戳的备份目录；
- 记录旧版本、旧 unit、旧配置和旧环境文件；
- 新版默认配置只作为参考，不直接覆盖生产配置；
- 灰度节点覆盖真实插件组合和 writer 链路；
- 验收同时看服务、日志、采集、写入、标签、Dashboard 和告警；
- 标签变化视为高风险变更，单独评审；
- 主配置和二进制变化使用受控重启；
- 容器镜像使用明确版本，不把
latest当成审计依据； - 回滚命令提前写好，升级窗口中只替换变量；
- 升级前提前通报相关团队，升级后按服务、指标、Dashboard、告警顺序完成检查；
- 升级完成后把计划、文章、Dashboard 和运维记录同步更新。
最小升级验收标准：
旧版本和配置已备份
+ 新旧配置差异已审查
+ 灰度节点 --test 通过
+ 正式模式写入后端
+ 核心裸指标有新样本
+ 主标签没有意外变化
+ Dashboard 和告警可用
+ 回滚路径已验证
15. 小结
Categraf 升级的关键不是“能不能把新二进制跑起来”，而是“监控数据入口是否持续可信”。所以升级流程要围绕数据闭环设计：
备份
-> diff
-> 灰度
-> test
-> 正式写入
-> 后端查询
-> Dashboard/告警验收
-> 可回滚
只要这条链路完整，升级失败也能快速恢复；如果跳过备份和标签验收，问题往往会在 Dashboard 空白或告警漏报时才暴露。
完成多实例标签、systemd/容器部署和升级回滚之后，新手与排障补充系列已经覆盖“会配置、能启动、能采集、能写入、能展示、可维护”的主要路径。后续可以继续进入 Kafka、Elasticsearch、RabbitMQ、Kubernetes 等中间件与云原生场景。
内容更新时间：2026-07-21
证据边界：服务管理参数、配置目录、HUP reload、writer 与 test/debug 边界来自当前 Categraf 仓库源码和默认配置；具体版本差异、镜像 tag、发布包结构、后端接收路径和 Dashboard schema 应以实际发布版本与部署环境为准。
