帮你快速理解、总结文档立即下载

LogListener 升级指南

最近更新时间:2026-11-11 15:31:01
本文档已由 AI 辅助审校
我的收藏

概述

LogListener 的升级方式取决于日志采集环境。本文介绍 CVM 与 Lighthouse 主机、自建 K8s 集群以及 TKE 集群中的日志采集组件升级方法。请根据实际部署环境选择对应的升级方式。

选择升级方式

部署环境
升级对象
升级方式
CVM 或 Lighthouse 主机
LogListener
自建 K8s 集群
日志采集组件
TKE 集群
tke-log-agent 及配套日志组件

升级前准备

升级前,请确认当前部署环境和组件版本,并检查日志采集状态。建议在业务低峰期执行升级,并在升级前记录当前版本和配置。升级期间,采集进程或 Pod 可能重启,请关注日志写入的连续性。

升级 CVM 与 Lighthouse 中的 LogListener

本节适用于通过机器组管理的 CVM 或 Lighthouse 主机。您可以使用控制台自动升级、控制台一键升级或半自动升级。
说明:
LogListener 自动升级功能仅支持 LogListener 2.5.0及以上版本。建议先通过 半自动升级 将 LogListener 升级至2.5.0以上版本。
LogListener 版本低于2.8.3时,脚本半自动升级功能依赖 Python 2.7。请先确认主机已安装 Python 2.7。
自动升级不支持将2.8.3以下版本直接升级至3.x 版本。请先通过 半自动升级 升级至2.8.6版本,再使用自动升级。

控制台自动升级

2. 在左侧导航栏中,选择机器组管理,进入机器组管理页面。
3. 找到需要自动升级的目标机器组,单击

。

4. 在弹出的窗口中,开启 LogListener 自动升级开关,指定升级时间段(默认为当前时间至后两小时,如23:25~01:25)。

5. 单击确定,目标机器组的自动升级栏变为

,即表示开启自动升级 LogListener 成功。
说明:
自动升级的时间段可选择任意时间段,系统会在用户指定的时间段每天进行检查。若满足升级条件,则进行自动升级;若不满足升级条件,则不进行操作。
如需对多个机器组进行 LogListener 自动升级,可以勾选多个目标机器组,然后单击更多操作中的 LogListener 自动升级进行批量升级。

控制台一键升级

2. 在左侧导航栏中,选择机器组管理,进入机器组管理页面。
3. 找到需要升级的目标机器组,单击操作栏的更多,在下拉框中找到并单击手动升级 LogListener。

4. 在弹出的窗口中,勾选升级状态为可升级的目标机器,单击手动升级。

系统默认升级至最新版本,当升级状态为已是最新版本时,即表示升级成功。
说明:
当升级状态显示不支持更新时,表示不支持在控制台一键更新 LogListener,需要您自主下载新版本安装包进行相关的手动升级操作,详情请参见 半自动升级。
当升级状态显示心跳异常时,请 检查机器组状态。

半自动升级

升级到 Loglistener 新架构(3.x 版本号)最新版本
升级到 LogListener 老架构(2.x 版本号)最新版本
2. 执行以下命令即可完成升级。
./loglistener_operator upgrade --root_dir=${loglistener安装目录} --url=${升级包url}
参数描述:
参数
描述
--root_dir
必填,指定新版本 LogListener 的实际安装目录(产品目录),不是安装参数 --base_dir 所表示的父目录。新架构(LogListener ≥3.4.0)默认安装目录为/opt/loglistener(对应 --base_dir 默认值为/opt)。
--url
必填,需要升级到的 LogListener 升级包地址。请根据目标系统架构和版本填写对应的升级包地址。升级包文件名带 -update 后缀,与不带该后缀的全量安装包不是同一类包,请勿混用。
x64 架构升级包的下载地址格式固定,将 URL 中的版本号替换为所需版本即可。地址模板为 https://mirrors.tencent.com/install/cls/packages/loglistener-linux-x64-${版本号}-update.tar.gz。以 3.6.6 版本为例:https://mirrors.tencent.com/install/cls/packages/loglistener-linux-x64-3.6.6-update.tar.gz
注意:
以下流程是升级到2.x 的最新版本,如果需要升级到 LogListener 新架构(版本≥3.5.0),请参考左侧 Tab。
1. 执行如下命令,下载升级脚本。
wget https://mirrors.tencent.com/install/cls/update
2. 执行以下命令,添加权限。
chmod +x update
3. 执行以下命令,执行 LogListener 升级脚本。
./update auto_upgrade --root-dir /usr/local/loglistener --url https://mirrors.tencent.com/install/cls/loglistener-linux-x64-2.8.7.tar.gz
参数描述:
参数
描述
--root-dir
必填,指定 LogListener 的实际安装目录(产品目录)。老架构(LogListener 3.4.0以下)常见安装目录为/usr/local/loglistener。
--url
必填,需要升级的 LogListener 的安装包地址。指定版本升级示例(以2.8.7为例):https://mirrors.tencent.com/install/cls/loglistener-linux-x64-2.8.7.tar.gz
注意:
如果输入的版本不存在,则下载失败;如果输入的版本低于机器上已安装的当前版本,则更新不生效。

非标部署环境自动升级风险说明

注意:
如果您通过自定义镜像打包、自研脚本部署或修改默认安装路径等非标方式部署 LogListener,自动升级功能可能无法正常工作,甚至导致采集环境损坏。请在确认部署方式后,参考本节说明评估风险。

非标部署环境定义

以下任一情况均属于非标部署环境:
场景
说明
自定义镜像打包
将 LogListener 二进制文件或安装目录打包进自定义容器镜像或系统镜像中,未使用官方安装脚本部署
自研脚本管理进程
使用自研的启动/停止/重启脚本管理 LogListener 进程,未通过官方提供的 tools/loglistener.sh 脚本管理
非默认安装路径
安装目录不是对应架构的默认产品目录。新架构(LogListener ≥3.4.0)默认为/opt/loglistener,老架构(LogListener 3.4.0以下)常见为/usr/local/loglistener。仅自定义到上述默认目录之外的路径才属于非默认安装路径,/opt/loglistener 是新架构的默认目录,不属于非标迁移路径。
进程名或路径被修改
修改了 LogListener 的可执行文件名称或符号链接路径,导致实际进程路径与标准部署不一致

自动升级与非标环境的冲突风险

自动升级脚本依赖标准安装路径和进程特征来定位 LogListener 实例。当您的部署方式与标准不一致时,可能出现以下问题:
升级脚本无法定位进程:自动升级通过预设路径查找 LogListener 进程,非标路径会导致进程定位失败,升级脚本可能误判为未安装状态,触发全新安装覆盖现有环境。
文件覆盖冲突:升级脚本按默认路径写入新版本文件,与您自定义路径下的实际运行实例产生冲突,导致配置文件丢失或进程异常。
环境状态不一致:升级完成后,自研管理脚本指向的路径/进程与实际升级后的版本不匹配,造成采集服务无法正常启动或运行。

建议非标环境关闭自动升级

如果您的 LogListener 属于上述非标部署环境,建议关闭自动升级功能,改为手动升级或半自动升级方式管理版本更新。关闭自动升级操作步骤如下:
2. 在左侧导航栏中,选择机器组管理。
3. 找到对应机器组的 LogListener 自动升级,设置为关闭状态。

说明:
关闭自动升级后,您可通过 控制台一键升级 进行版本更新。

升级自建 K8s 集群日志采集组件

自建 K8s 集群通过 Helm Release tencent-cloud-cls-log 管理日志采集组件。升级操作会更新该 Helm Release 管理的组件,例如 tke-log-agent 和 cls-provisioner。本节适用于通过腾讯云官方脚本安装日志采集组件的集群。
1. 升级前需重新拉取最新版本的安装脚本,以获取最新的采集器组件:
wget https://mirrors.tencent.com/install/cls/k8s/addon-charts/tencentcloud-cls-k8s.sh
chmod +x tencentcloud-cls-k8s.sh
2. 执行以下命令升级
./tencentcloud-cls-k8s.sh upgrade --region ap-xxxxxx --<options>
参数说明:
参数
参数说明
region
目标 CLS 服务地域,详见产品支持的 地域列表。
upgrade_metrics
升级时是否安装 metric 采集组件。不指定该参数时,保持升级前的原有状态(原来已安装则保留,未安装则不安装);如需显式开启或关闭,可传入 true 或 false。
namespace
日志采集组件安装的 namespace,默认安装在 kube-system,一般不需要特殊指定。

升级 TKE 集群日志采集组件

TKE 集群可通过控制台一键升级,或通过 API Explorer 调用 UpdateAddon 接口升级 tke-log-agent。升级过程中会同步升级配套的 LogListener、Provisioner 和日志相关 CRD。

控制台一键升级

通过容器服务控制台一键升级 tke-log-agent。
2. 在左侧导航栏中,选择运维中心 > 运维功能管理。
3. 选择目标地域和集群类型。
4. 找到状态为组件可升级的目标集群,单击组件可升级。
5. 在组件列表中找到 tke-log-agent,单击右侧的升级,并根据页面提示确认升级。


通过 API Explorer 升级

当您需要手动升级 tke-log-agent 组件版本时,可通过腾讯云 API Explorer 调用 UpdateAddon 接口完成升级。
2. 填写以下参数:
参数
值
说明
Region
集群所在地域(例如 ap-guangzhou)
根据实际情况选择
ClusterId
待升级的集群 ID(例如 cls-xxxxxxxx)
必填
AddonName
tke-log-agent
固定值
AddonVersion
目标版本号(例如2.0.0)
填写需要升级到的 tke-log-agent 版本号
RawValues
留空
可选
UpdateStrategy
留空
可选
DryRun
留空
可选。设为 true 时可预检而不实际执行升级
3. 单击发送请求。
4. 响应结果中返回 RequestId,即表示升级请求已提交成功。

常见问题

升级是否会中断日志采集?

升级期间,LogListener 进程或日志采集 Pod 可能重启,日志写入可能出现短暂延迟。建议在业务低峰期升级,并在升级后检查日志写入的连续性。

升级后日志未继续写入怎么办?

请先检查 LogListener 或日志采集 Pod 的运行状态和组件日志,然后确认网络、权限、日志主题及采集配置是否正常。如果问题仍未解决,请 提交工单 联系腾讯云技术支持。