概述
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版本,再使用自动升级。
控制台自动升级
1. 登录 日志服务控制台。
2. 在左侧导航栏中,选择机器组管理,进入机器组管理页面。
3. 找到需要自动升级的目标机器组,单击
。


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

5. 单击确定,目标机器组的自动升级栏变为
,即表示开启自动升级 LogListener 成功。

说明:
自动升级的时间段可选择任意时间段,系统会在用户指定的时间段每天进行检查。若满足升级条件,则进行自动升级;若不满足升级条件,则不进行操作。
如需对多个机器组进行 LogListener 自动升级,可以勾选多个目标机器组,然后单击更多操作中的 LogListener 自动升级进行批量升级。
控制台一键升级
1. 登录 日志服务控制台。
2. 在左侧导航栏中,选择机器组管理,进入机器组管理页面。
3. 找到需要升级的目标机器组,单击操作栏的更多,在下拉框中找到并单击手动升级 LogListener。

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

系统默认升级至最新版本,当升级状态为已是最新版本时,即表示升级成功。
说明:
当升级状态显示不支持更新时,表示不支持在控制台一键更新 LogListener,需要您自主下载新版本安装包进行相关的手动升级操作,详情请参见 半自动升级。
当升级状态显示心跳异常时,请 检查机器组状态。
半自动升级
1. 下载 loglistener_operator 脚本。
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 属于上述非标部署环境,建议关闭自动升级功能,改为手动升级或半自动升级方式管理版本更新。关闭自动升级操作步骤如下:
1. 登录 日志服务控制台。
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.shchmod +x tencentcloud-cls-k8s.sh
2. 执行以下命令升级
./tencentcloud-cls-k8s.sh upgrade --region ap-xxxxxx --<options>
参数说明:
参数 | 参数说明 |
region | |
upgrade_metrics | 升级时是否安装 metric 采集组件。不指定该参数时,保持升级前的原有状态(原来已安装则保留,未安装则不安装);如需显式开启或关闭,可传入 true 或 false。 |
namespace | 日志采集组件安装的 namespace,默认安装在 kube-system,一般不需要特殊指定。 |
升级 TKE 集群日志采集组件
TKE 集群可通过控制台一键升级,或通过 API Explorer 调用 UpdateAddon 接口升级
tke-log-agent。升级过程中会同步升级配套的 LogListener、Provisioner 和日志相关 CRD。控制台一键升级
通过容器服务控制台一键升级
tke-log-agent。1. 登录 容器服务控制台。
2. 在左侧导航栏中,选择运维中心 > 运维功能管理。
3. 选择目标地域和集群类型。
4. 找到状态为组件可升级的目标集群,单击组件可升级。
5. 在组件列表中找到
tke-log-agent,单击右侧的升级,并根据页面提示确认升级。
通过 API Explorer 升级
当您需要手动升级
tke-log-agent 组件版本时,可通过腾讯云 API Explorer 调用 UpdateAddon 接口完成升级。1. 打开 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 可能重启,日志写入可能出现短暂延迟。建议在业务低峰期升级,并在升级后检查日志写入的连续性。