腾讯云日志服务CLS实战指南：从零搭建网站运行日志采集体系

apphuang2026年07月04日 21:10:503

引言：为什么网站需要统一的日志采集平台

网站运行过程中会产生大量日志，包括Web服务器访问日志、应用运行日志、数据库日志、安全审计日志等。这些日志分散在不同的服务器和容器中，格式各异，量级庞大。传统的手动登录服务器查看日志方式，在面对分布式系统和微服务架构时显得力不从心。腾讯云日志服务（Cloud Log Service，CLS，原称SLS）提供了一站式的日志采集、存储、检索分析和监控告警能力，能够帮助运维和开发人员高效地管理网站日志。本文将从零开始，详细讲解如何使用CLS采集网站运行日志，涵盖从服务开通到最终实现日志监控告警的完整流程。

一、腾讯云日志服务CLS概述

1.1 什么是CLS

日志服务（Cloud Log Service，CLS）是腾讯云提供的一站式日志数据解决方案，支持日志（Log）、指标（Metric）数据的采集、ETL、检索分析、可视化及告警等功能。CLS提供了从日志采集、日志存储到日志检索分析、实时消费、日志投递等多项服务，协助用户通过日志来解决业务运营、安全监控等问题。用户无需关注资源扩容问题，五分钟内即可便捷接入，享受稳定可靠的日志服务。

1.2 CLS的核心功能

CLS主要包含以下几大核心功能模块：

日志采集：通过LogListener采集客户端、API和SDK三种方式，支持从多种数据源场景采集日志并导入到日志服务。
日志存储：提供标准存储和低频存储两种存储类型，支持1至3600天的数据保存周期，也可选择永久保存。
索引与检索：支持全文索引和键值索引，提供关键词检索、模糊检索、上下文检索、范围检索以及SQL聚合分析等查询手段。
监控告警：支持为日志主题设置告警策略，当查询分析结果满足触发条件时发送告警通知。
日志投递：支持将日志数据投递至对象存储COS、Kafka等下游服务，便于长期归档和二次处理。

1.3 CLS的采集方式

CLS提供了三种主要的日志采集方式：

LogListener采集客户端：这是最常用的采集方式，通过在服务器上安装专用的日志采集器LogListener，实现无侵入式的日志采集。LogListener类似于开源组件Beats，负责采集日志数据并上报至CLS。
API采集：通过调用CLS的API接口，将应用程序日志直接写入CLS，适用于需要精确控制上传逻辑的场景。
SDK采集：CLS提供了多种编程语言的SDK（如Python、Java、Go等），方便开发者在应用程序中集成日志上传功能。

对于网站运行日志的采集，最典型的方案是使用LogListener采集服务器上的Web日志文件（如Nginx访问日志、错误日志），同时结合SDK采集应用程序内部的结构化日志。

二、CLS采集网站日志的前置准备

在开始采集日志之前，需要完成以下准备工作。

需要先登录腾讯云控制台，点击：腾讯云控制台，还没有账号，点击：注册后再关联，已有账号点击：登录后再关联

2.1 开通CLS服务

首先需要在腾讯云官网申请开通日志服务。登录腾讯云控制台后，在产品列表中找到"日志服务"（CLS），按照指引完成服务开通。CLS采用按量计费模式，根据存储容量、请求次数、流量等计量项的实际用量进行计费，每日进行结算和扣费。同时，CLS也提供了资源包套餐，可以抵扣各计费项的费用。

2.2 获取API密钥

安装LogListener或使用SDK上传日志时，需要提供API密钥（SecretId和SecretKey）进行身份认证。登录访问管理控制台，查看或创建密钥对，并确认密钥状态为启用。建议使用子账号密钥并授予最小权限，避免主账号密钥泄露的风险。具体权限配置可参考LogListener日志采集权限文档。

2.3 规划网络与地域

CLS服务区分地域，为了降低网络延迟，应尽可能选择与服务邻近的地域创建日志资源。如果日志源机器是腾讯云CVM且与CLS服务在同一地域，LogListener可以通过内网访问CLS，无需消耗外网流量，有效降低费用。如果服务器与CLS在不同地域，则需要使用外网方式访问。

三、安装LogListener采集客户端

LogListener是CLS的专用日志采集器，安装部署到服务器上后即可快速采集日志到CLS。下面分别介绍Linux和Windows环境下的安装方法。

3.1 Linux环境安装LogListener

LogListener支持x64和ARM两种处理器架构，兼容TencentOS、CentOS、Ubuntu、Debian、openSUSE等多种Linux发行版。以安装路径/usr/local/为例，安装步骤如下：

外网环境下载安装：

wget http://mirrors.tencent.com/install/cls/loglistener-linux-x64.tar.gz && \
tar zxvf loglistener-linux-x64.tar.gz -C /usr/local/ && \
cd /usr/local/loglistener/tools && \
./loglistener.sh install

内网环境下载安装（适用于腾讯云CVM）：

wget http://mirrors.tencentyun.com/install/cls/loglistener-linux-x64.tar.gz && \
tar zxvf loglistener-linux-x64.tar.gz -C /usr/local/ && \
cd /usr/local/loglistener/tools && \
./loglistener.sh install

如果需要安装特定版本，可以将安装包名称中的loglistener-linux-x64替换为loglistener-linux-x64-2.8.0，即可指定安装2.8.0版本。安装完成后，LogListener会以守护进程方式运行，自动采集配置的日志文件。

3.2 Windows环境安装LogListener

LogListener支持64位Windows Server操作系统，包括Windows Server 2012R2、2016、2019、2022等版本。安装步骤如下：

下载LogListener安装包并解压缩。
以管理员身份运行Windows PowerShell，在解压路径下执行安装命令：

.\loglistener_installer.exe install \
--secret_id AKID******************************** \
--secret_key whHwQfjdLnzzCE1jIf09xxxxxxxxxxxx \
--region ap-xxxxxx

其中--secret_id、--secret_key、--region为必填参数。--region指定的是日志服务所在地域，而非业务机器所在地域。执行安装指令后，LogListener默认安装在C:\Program Files (x86)\Tencent\LogListener目录下。

3.3 验证LogListener安装

安装完成后，可以通过以下方式验证LogListener是否正常运行：

Linux环境下，执行ps aux | grep loglistener查看进程是否存在。
检查LogListener的日志文件（通常位于/usr/local/loglistener/log/目录下），确认是否有错误信息。
在CLS控制台的机器组管理中，查看对应机器的状态是否显示为"正常"。

四、创建日志主题与机器组

4.1 创建日志主题

日志主题是CLS中日志数据的基本组织单元。一个日志集表示一个项目，一个日志主题表示一类服务，单个日志集可以包含多个日志主题。创建日志主题的步骤如下：

登录日志服务控制台，在左侧导航栏中单击"日志主题"。
选择日志主题的地域，单击"创建日志主题"。
在弹出的窗口中填写相关信息：
- 日志主题名称：例如nginx-access-log，支持1-255个字符。
- 存储时间：支持有限保存（1-3600天）或永久保存。
- 日志集操作：可以选择现有日志集或创建新的日志集。
单击确定完成创建。

4.2 创建机器组

机器组是一组需要采集日志的机器列表，CLS通过机器组来管理所有需要通过LogListener采集日志的机器。一个机器组可以与一个日志主题关联，也可以与多个日志主题关联。创建机器组的步骤如下：

在日志服务控制台左侧导航栏单击"机器组管理"。
在页面顶部选择合适的地域，单击"新建机器组"。
填写机器组名称，并添加机器IP地址（每行一个IP地址）。
- 如果是腾讯云CVM，直接填写内网IP地址即可。
- 也可以使用机器标识（自定义标识）方式，在LogListener配置中填入机器标识，CLS即可自动识别并添加机器。
单击确定完成创建。

创建机器组后，需要将机器组与日志主题进行绑定。在日志主题的采集配置页面，选择对应的机器组即可完成绑定。

五、配置日志采集规则

完成日志主题和机器组的创建后，接下来需要配置具体的采集规则，包括日志文件路径、解析模式等。

5.1 配置采集路径

在日志主题管理页面，单击目标日志主题名称进入管理页面，选择"采集配置"页签，在LogListener采集配置中单击新增。在采集配置页面，需要指定日志文件的采集路径：

Linux系统：日志路径必须以"/"开头，例如/var/log/nginx/access.log。
Windows系统：文件路径必须以盘符开头，例如C:\inetpub\logs\LogFiles\W3SVC1\*.log。

采集路径支持通配符，例如/var/log/nginx/*.log可以匹配该目录下所有以.log结尾的文件。

5.2 选择解析模式

CLS支持多种日志解析模式，用于将原始日志文本提取为结构化的字段，便于后续的检索和分析。

单行全文：将每行日志作为一个整体，不进行字段提取。适用于日志格式不固定或不需要字段级检索的场景。
多行全文：将多行日志合并为一条日志，适用于Java堆栈跟踪等多行日志场景。
JSON：当日志为JSON格式时，自动解析为键值对字段。
分隔符：根据指定的分隔符（如空格、逗号、竖线等）将日志切分为多个字段。
正则表达式：使用正则表达式提取日志中的特定字段。

对于Nginx访问日志，建议使用正则表达式或分隔符模式进行解析。Nginx访问日志的默认格式如下：

log_format main '$remote_addr - $remote_user [$time_local] ' '"$request" $status $body_bytes_sent ' '"$http_referer" "$http_user_agent"';

对应的字段包括：客户端IP（remote_addr）、客户端名称（remote_user）、本地时间（time_local）、请求方法和URL（request）、状态码（status）、发送字节数（body_bytes_sent）、来源页面（http_referer）、客户端浏览器信息（http_user_agent）。

5.3 配置结构化提取

在采集配置中，可以选择"结构化提取"模式，通过正则表达式或JSON解析等方式将日志字段提取出来。例如，对于Nginx日志，可以配置如下正则表达式来提取字段：

ext_regex('(?P<remote_addr>\S+) - (?P<remote_user>\S+) \[(?P<time_local>[^\]]+)\] "(?P<request>[^"]*)" (?P<status>\d+) (?P<body_bytes_sent>\d+) "(?P<http_referer>[^"]*)" "(?P<http_user_agent>[^"]*)"')

提取后的字段将作为键值对存储，用户可以在检索时直接使用字段名进行精确查询，例如status:500检索所有状态码为500的请求。

六、配置索引以实现日志检索

索引配置是使用CLS进行检索分析的必要条件，只有开启索引才能对日志进行检索分析。CLS包含两类索引：

全文索引：将日志全文整体切分为多个分词进行索引构建，检索时通过关键词进行检索，例如使用error检索所有出现过error的日志。
键值索引：将原始日志按字段分别切分为多个分词进行索引构建，检索时基于键值方式进行检索，例如使用level:error AND timeCost:>1000检索日志级别为error且耗时大于1000ms的日志。

6.1 配置全文索引

全文索引的配置项包括：

全文分词符：对原始日志进行分词的字符集合，默认为@&?|#()='",;:<>[]{}/ \n\t\r\\。
大小写敏感：检索时是否对大小写敏感。
是否包含中文：日志中包含中文且需要对中文进行检索时可开启此功能。

6.2 配置键值索引

键值索引需要为每个需要检索的字段单独配置。在索引配置页面，开启"键值索引"后，可以手动添加字段，也可以开启"自动配置"功能，CLS将自动识别日志中的字段并添加到键值索引中。对于需要做统计分析（如使用SQL进行聚合查询）的字段，还需要开启"统计"功能。

6.3 索引配置的注意事项

索引关闭时采集的日志数据无法被检索。
从开启索引到支持日志检索分析存在约一分钟的延迟。
索引规则编辑后仅对新写入的日志生效，已有数据不会更新。
低频存储仅支持全文索引，不支持键值索引。

七、使用SDK上传结构化日志

除了通过LogListener采集文件日志外，CLS还支持通过SDK直接上传结构化日志。这种方式适用于应用程序需要实时上报结构化日志的场景，例如业务操作日志、API调用日志等。

7.1 安装Python SDK

在命令行中执行以下命令安装CLS的Python SDK：

pip install tencentcloud-cls-sdk-python

验证安装是否成功：

pip show tencentcloud-cls-sdk-python

7.2 Python SDK上传日志示例

以下代码演示了如何使用Python SDK将结构化日志上传到CLS：

# 导入所需的库
import time
from tencentcloud.log.logclient import LogClient
from tencentcloud.log.logexception import LogException
from tencentcloud.log.cls_pb2 import Log, LogGroup, LogGroupList

# 配置参数
endpoint = "ap-guangzhou.cls.tencentyun.com"  # CLS服务域名
topic_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"  # 日志主题ID
access_key_id = "AKID********************************"  # 请通过环境变量获取
access_key = "********************************"  # 请通过环境变量获取

# 创建客户端
client = LogClient(endpoint, access_key_id, access_key)

# 构造日志数据
log_group_list = LogGroupList()
log_group = log_group_list.logGroupList.add()
log_group.filename = "/var/log/myapp/app.log"
log_group.source = "192.168.1.100"

# 添加日志条目
log = Log()
log.time = int(time.time())
content = log.contents.add()
content.key = "level"
content.value = "INFO"
content = log.contents.add()
content.key = "message"
content.value = "User login success"
content = log.contents.add()
content.key = "user_id"
content.value = "12345"
log_group.logs.append(log)

# 上传日志
try:
    response = client.put_logs(topic_id, log_group_list)
    print("Upload success")
except LogException as e:
    print("Upload failed: {0}".format(e))

需要注意的是，不建议将云API密钥信息明文存储至工程代码中，应通过环境变量动态获取。

八、日志检索与SQL分析

日志采集到CLS后，可以通过控制台的检索分析功能进行查询和分析。

8.1 基础检索

在日志主题的检索分析页面，可以输入检索语句进行日志查询：

关键词检索：直接输入关键词，如error，检索所有包含error的日志。
字段检索：使用字段名:值格式，如status:500，检索状态码为500的日志。
组合检索：使用AND、OR、NOT等逻辑运算符，如status:500 AND remote_addr:192.168.1.*。
范围检索：使用比较运算符，如body_bytes_sent:>1024。

8.2 SQL统计分析

CLS支持使用SQL语句对日志进行统计分析。以下是一些常用的分析示例：

统计PV（页面访问量）：SELECT COUNT(*) AS pv
统计UV（独立访客数）：SELECT COUNT(DISTINCT remote_addr) AS uv
按状态码分组统计：SELECT status, COUNT(*) AS count GROUP BY status ORDER BY count DESC
统计每秒请求数（QPS）：SELECT DATE_FORMAT(__TIMESTAMP__, '%Y-%m-%d %H:%i:%s') AS time, COUNT(*) AS qps GROUP BY time ORDER BY time
统计平均响应时间：SELECT AVG(request_time) AS avg_response_time

这些分析结果可以帮助运维人员了解网站的访问趋势、性能状况和异常情况。

九、配置日志告警

CLS支持基于日志内容设置告警策略，当满足特定条件时自动发送告警通知。

9.1 创建告警策略

告警策略的配置步骤如下：

登录CLS控制台，选择目标日志主题。
点击"告警策略" → "新建策略"。
配置告警规则：
- 触发条件：支持字段过滤（如status_code == 500）和统计聚合（如COUNT(*) > 100）。
- 监控周期：设置告警检查的频率。
- 告警频率：设置告警通知的发送频率。
配置通知模板，指定告警接收人（短信、邮件、微信等）。
单击完成创建。

9.2 常见告警场景

错误率过高：当状态码为5xx的请求占比超过阈值时告警。
访问量异常：当QPS突然下降或飙升时告警。
特定错误码频繁出现：当特定错误码（如404、500）在短时间内出现次数过多时告警。
LogListener心跳异常：当LogListener与CLS的心跳连接中断时告警。

十、安全与权限管理

10.1 最小权限原则

在配置CLS时，应遵循最小权限原则：

使用子账号而非主账号进行日常操作。
为不同的角色授予不同的权限：
- 运维人员：日志检索、告警配置权限。
- 开发人员：日志上传（SDK/API）权限。
- 管理员：日志主题管理、机器组管理、索引配置权限。
定期轮换API密钥，避免密钥泄露。

10.2 日志数据安全

敏感信息（如用户密码、Token）在日志中应进行脱敏处理。
CLS支持日志数据的传输加密和存储加密。
可以通过日志投递功能将日志备份到COS，实现数据冗余。

十一、成本优化建议

CLS采用按量计费模式，主要计费项包括存储费用、索引流量费用、读写流量费用和请求费用。以下是一些成本优化的建议：

11.1 合理设置存储周期

根据业务需求设置日志的存储周期。热数据（如最近7天的日志）保存在标准存储中以便快速检索，历史数据可以自动沉降到低频存储或删除。CLS支持日志沉降功能，可以将部分历史日志自动沉降到低频存储以节约费用。

11.2 利用内网免流量

如果日志源机器是腾讯云CVM且与CLS服务在同一地域，LogListener可以通过内网访问CLS，无需消耗外网流量。这可以显著降低流量费用。

11.3 合理配置索引

索引会占用存储空间并产生索引流量费用。只为需要检索和统计的字段开启键值索引和统计功能，避免为所有字段开启索引造成不必要的费用。

11.4 使用资源包

CLS提供了资源包套餐，可以抵扣各计费项的费用。对于日志量较大的场景，购买资源包通常比按量计费更经济。

十二、容器环境日志采集

对于运行在容器环境（如TKE、EKS）中的网站应用，CLS也提供了完善的日志采集方案。

12.1 TKE容器日志采集

腾讯云容器服务TKE与CLS深度集成，可以通过控制台直接配置日志采集：

登录容器服务控制台，在左侧导航栏中选择集群。
在集群列表中单击目标集群ID，进入集群详情页。
选择左侧导航栏中的"日志"，在日志采集页签中单击"新增采集配置"。

采集配置支持两种采集源：

容器标准输出：可选择所有容器、指定工作负载或指定Pod Labels内的容器。
容器文件路径：可指定工作负载或Pod Labels内容器的文件路径日志作为采集源。

12.2 自建Kubernetes集群日志采集

对于自建的Kubernetes集群，CLS支持通过LogConfig CRD方式配置日志采集：

LogConfig：日志采集配置CRD，定义了日志采集源、解析方式和目标日志主题。
Log-Agent：监听LogConfig和节点上容器的变化，动态计算容器日志文件在宿主机上的实际位置。
LogListener：负责实际的日志采集和上报。

通过在Kubernetes集群中部署Log-Agent和LogListener，并定义LogConfig CRD，即可将自建K8s集群的容器日志采集到CLS。

十三、实战案例：Nginx访问日志完整采集流程

下面以一个完整的Nginx访问日志采集案例，串联上述所有步骤。

13.1 步骤一：开通CLS并准备环境

在腾讯云控制台开通CLS服务。
获取API密钥（SecretId和SecretKey）。
确认Nginx服务器与CLS服务的地域关系，规划网络访问方式。

13.2 步骤二：安装LogListener

在Nginx服务器上安装LogListener（以Linux为例）：

wget http://mirrors.tencentyun.com/install/cls/loglistener-linux-x64.tar.gz && \
tar zxvf loglistener-linux-x64.tar.gz -C /usr/local/ && \
cd /usr/local/loglistener/tools && \
./loglistener.sh install

13.3 步骤三：创建日志主题和机器组

在CLS控制台创建日志主题，命名为"nginx-access-log"，设置合理的存储周期。
创建机器组，将Nginx服务器的内网IP添加到机器组中。
将机器组与日志主题进行绑定。

13.4 步骤四：配置采集规则

在日志主题的采集配置页面：

采集路径：/var/log/nginx/access.log。
解析模式：选择正则表达式或分隔符模式，配置字段提取规则。
配置Nginx日志格式对应的正则表达式，提取remote_addr、time_local、request、status等字段。

13.5 步骤五：配置索引

开启全文索引，设置合适的分词符。
为status、remote_addr、request等常用检索字段开启键值索引和统计功能。

13.6 步骤六：验证与查询

等待1-2分钟后，在检索分析页面查询日志。
执行检索语句如status:500验证是否能正常检索。
执行SQL分析如SELECT status, COUNT(*) AS count GROUP BY status验证统计功能。

13.7 步骤七：配置告警

创建告警策略，设置触发条件如status:500 | SELECT COUNT(*) > 10。
配置通知方式，指定告警接收人。

通过以上七个步骤，即可完成Nginx访问日志从采集到分析告警的完整链路。

结语

腾讯云日志服务CLS为网站运行日志的采集、存储、分析和告警提供了一站式的解决方案。通过LogListener采集客户端，可以无侵入式地采集服务器上的各类日志文件；通过SDK和API，可以灵活地上传应用程序的结构化日志；通过强大的索引和SQL分析能力，可以快速从海量日志中提取有价值的信息；通过告警策略，可以实现日志驱动的智能运维。无论是传统的物理机/虚拟机部署，还是现代的容器化/Kubernetes环境，CLS都能提供完善的日志采集方案。希望本文能帮助读者快速掌握CLS的使用方法，建立一套高效、可靠的网站日志管理体系。

常见问题解答

问1：LogListener采集日志时，采集路径支持通配符吗？

支持。采集路径可以使用通配符匹配多个文件，例如/var/log/nginx/*.log可以匹配该目录下所有以.log结尾的文件。Linux系统的日志路径必须以"/"开头，Windows系统的文件路径必须以盘符开头。

问2：采集到CLS的日志为什么检索不到？

检索不到日志通常有以下几个原因：索引未开启或配置不正确，索引从开启到生效有约一分钟的延迟；索引规则修改后仅对新写入的日志生效，已有数据不会被重新索引；检索语句的语法有误，或分词符设置导致关键词无法匹配。建议先检查索引配置状态，再确认检索语句是否正确。

问3：CLS支持采集哪些类型的网站日志？

CLS支持采集多种类型的网站日志，包括但不限于：Nginx访问日志和错误日志、Apache访问日志、IIS日志、Tomcat应用日志、容器标准输出和文件日志、以及通过SDK上传的自定义结构化日志。

问4：CLS的日志存储周期可以设置多长？

CLS支持1至3600天的数据保存周期，也可以选择永久保存。同时支持日志沉降功能，可以将部分历史日志自动从标准存储沉降到低频存储，以节约存储费用。

问5：如何降低CLS的使用成本？

降低CLS成本可以从以下几个方面入手：利用同地域CVM内网访问免流量；合理设置存储周期，将历史数据沉降到低频存储；只为需要检索和统计的字段开启索引；对于日志量大的场景，购买资源包通常比按量计费更经济。

问6：自建Kubernetes集群如何采集容器日志到CLS？

自建Kubernetes集群可以通过部署Log-Agent和LogListener组件，并定义LogConfig CRD来实现日志采集。LogConfig定义了日志采集源、解析方式和目标日志主题，Log-Agent负责监听配置变化并计算日志文件位置，LogListener负责实际的日志采集和上报。