帮你快速理解、总结文档立即下载
文档中心>日志服务>开发者指南>集成或内嵌日志服务(DataSight)

集成或内嵌日志服务(DataSight)

最近更新时间:2026-08-13 16:44:31
我的收藏

应用场景

DataSight 是 CLS 日志服务提供的独立控制台:无需登录腾讯云主账号,即可访问日志检索、仪表盘、告警等能力。以下场景适合通过 DataSight 将日志服务 CLS 集成到您的系统内部:
多人多团队共用 CLS:频繁登录腾讯云主控制台,账号管理成本高、功能访问路径深,希望团队成员打开即用、无需腾讯云账号。
嵌入统一运维平台 / 业务系统:将日志检索、仪表盘作为原生模块嵌入内部平台,员工无需切换到外部系统。
复用企业内部账号体系:对接 LDAP、OAuth 或自研登录系统,实现统一登录。
一键直达日志上下文:从订单、工单等业务详情页,直接跳转到对应的日志检索页面或仪表盘。
统一域名与访问入口:使用公司域名 + 反向代理收敛入口,统一 HTTPS,隐藏真实地址,便于访问控制。
DataSight 集成能力如下表:
集成能力
集成方式
适用场景
对应章节
页面内嵌
iframe
嵌入统一运维平台、业务系统
链接直达
URL 参数拼接
从业务系统一键跳到指定日志检索页 / 仪表盘
统一域名
自定义域名 + 反向代理
隐藏真实域名、统一 HTTPS
登录对接
反向代理 + 第三方认证
复用企业内部账号体系(LDAP / OAuth / 自研)
说明:
DataSight 除了可用于集成至企业内部系统,其自身也是一个完整的独立控制台,使用方式详见 DataSight 独立控制台

前提条件

开始集成前,需要先创建并配置好 DataSight 实例:
1. 创建 DataSight 实例:参考 DataSight 独立控制台操作步骤,完成实例创建并选择访问方式。集成场景(内嵌、登录对接)建议使用内网访问
2. 确认实例域名:在 CLS 控制台 → DataSight 管理实例中查看。
3. 打通网络:使用内网访问时,办公网与腾讯云网络需互联互通(物理专线 / VPN / 云联网)。

集成能力

页面内嵌

DataSight 页面本身就是普通 Web 页面,通过 iframe 引入即可嵌入到内部系统。配合 URL 参数可以:
直达指定日志主题的检索页、指定仪表盘。
通过 hide* 系列参数隐藏导航、菜单、按钮等页面元素,让内嵌页面更简洁。
内嵌示例如下:
// 一个快速查看效果的样例,请根据自身业务进行调整
// 请根据实际情况修改 <domain-appid>(DataSight 域名前缀)部分
function prepareSdkFrame(url) {
var ifrm = document.createElement("iframe");
ifrm.setAttribute("src", url);
ifrm.style.width = "1280px";
ifrm.style.height = "960px";
document.body.appendChild(ifrm);
}
const url = 'https://<domain-appid>.clsconsole.tencentcls.com/cls/search?region=${Region}&topic_id=${TopicId}&query=${Query}&time=now-h,now&hideWidget=true&hideTopNav=true&hideLeftNav=true'

prepareSdkFrame(url)
说明:
URL 及 hide 参数的说明,参见 页面内嵌 URL 参数说明

自定义域名与反向代理

在以下场景下,需使用自定义域名与反向代理:
内嵌到内部系统时,统一用公司域名,避免暴露 DataSight 真实域名。
统一 HTTPS 入口。
接管 DataSight 的登录跳转,配合对接内部登录系统,实现统一登录。
通过反向代理模块的请求日志,审计 DataSight 访问记录。

Nginx 配置示例如下:
# 请根据实际情况,修改此配置示例中<your-domain.com>、<your-domain-cert>、<domain-appid>(DataSight 域名前缀,支持公网/内网域名)部分
# 强烈建议您为自定义域名开启https,并强制http跳转到https,以提升浏览器请求安全性、减少浏览器请求排队等待。
# 示例使用新域名(tencentcls.com),老域名实例请替换为 tencent-cloud.com,并以实际实例域名为准

# 如不希望强制跳转到https协议,可注释此server配置
server {
listen 80;
server_name your-domain.com;
return 301 https://$host$request_uri;
}

server {
# 如希望通过http协议访问,可去掉下行注释
# listen 80;
listen 443 ssl http2;
server_name your-domain.com;
ssl_certificate your-domain-cert.pem;
ssl_certificate_key your-domain-cert.key;

location ~ ^/(.*) {
# 可在此处增加自定义访问控制策略,例如:限制指定referer值才可访问
#set $match "$1::$http_referer";
#if ($match !~* ^(.+)::http[s]*://[www]*[.]*\\1.*$ ) {
# return 403;
#}

proxy_pass https://<domain-appid>.clsconsole.tencentcls.com;
proxy_set_header Host $proxy_host;
proxy_set_header Origin https://$proxy_host;
proxy_set_header Referer "https://$proxy_host/$1";
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Proxy true;
proxy_set_header X-Proxy-Host $host;
proxy_set_header X-Proxy-Real-IP $remote_addr;
proxy_set_header X-Proxy-Forwarded-Proto $scheme;
proxy_redirect ~^(.*)/login\\?s_url=https?%3A%2F%2F[a-z0-9\\-]+(.internal)?.clsconsole.tencentcls.com%2F(.*)$ $1/login?s_url=https%3A%2F%2Fyour-domain.com%2F$3;

# 如需要隐藏或自定义DataSight页面的腾讯云图标(favicon),可通过以下两个header实现
# proxy_set_header X-DATASIGHT-HIDE-FAVICON true;
# proxy_set_header X-DATASIGHT-FAVICON-URL https://github.githubassets.com/favicons/favicon.png;
}
}
说明:
建议使用 cls-datasight-demo 模板。

对接内部登录系统



对接原理

Nginx 等反向代理软件,可支持作为前置登录校验模块部署,对接内部登录系统。
用户完成登录操作后,反向代理才会把请求转发到受保护的后端服务(DataSight)。
DataSight 登录方式选择第三方认证登录后,DataSight 自身不做登录校验,而是信任反向代理传入的参数判断用户身份。登录校验逻辑完全由企业自己掌控,内部登录密码等敏感数据不会传递到 DataSight,且支持按用户、按角色管控与审计。
反向代理发往 DataSight 的请求中,通过 header X-DATASIGHT-USER 指定用户名,X-DATASIGHT-ROLE 指定角色名。如需要一次传入多个角色名,也可通过 X-DATASIGHT-ROLES 传入,支持以下格式,DataSight 将使用其中第一个作为角色名。
英文逗号分隔的字符串:role1,role2
JSON 数组字符串:["role1", "role2"]


前提条件

DataSight 登录方式设置为 第三方认证登录
创建 DataSight 角色(角色名称 + 对应的 CAM 子用户 SecretId / SecretKey)。
配置反向代理。
在 DataSight 配置中登记反向代理的内网 IP 地址或 CIDR。支持填写多个,使用英文逗号分隔。

连通性验证

配置完成后,在反向代理所处环境或类似网络环境执行:
curl -X POST \\
-H "X-DATASIGHT-USER:your_user" \\
-H "X-DATASIGHT-ROLE:your_role" \\
https://<domain-appid>.clsconsole.tencentcls.com/api/user
返回 {"isLoggedIn":true,...,"username":"your_user","role":"your_role","isAuthProxy":true}:表示 DataSight 登录校验代理访问正常,并已自动通过 header 登录信息完成登录。
返回 {"isLoggedIn":false,"domain":""}:表示 DataSight 登录校验代理访问正常,但 X-DATASIGHT-ROLE 对应的角色在 DataSight 中未配置,请检查前提条件的第 2 步。
返回 intranet access denied: xxxx:当前 VPC / IP 不在允许范围,检查前提条件中的 IP 登记。

安全注意事项

DataSight 信任 header 意味着 header 可以被伪造。因此必须保证:
内网隔离:DataSight 仅内网访问(互联网不可达),用户无法绕过反向代理直连 DataSight。
IP 登记:DataSight 只信任登记过的反向代理来源。
防止身份伪装:反向代理必须清除/覆盖入站请求中客户端自带的 X-DATASIGHT-USER / X-DATASIGHT-ROLE / X-DATASIGHT-ROLES header,否则用户经反向代理访问时可伪造 header 冒充他人。

配置示例

LDAP
OAuth

集成案例

案例1:iframe 内嵌 + 免登录(最简,内网直嵌)

适用场景:内网可信环境,所有用户无需账号直接看日志。
配置方式
1.1 DataSight 启用匿名登录(仅内网访问支持),密钥使用只读子用户密钥。
1.2 内部平台页面 iframe 内嵌,详情请参见 页面内嵌
安全注意:匿名登录的访问边界 = 内网边界,日志含敏感信息时慎用。

案例2:对接 LDAP/OAuth/ OIDC 认证

适用场景:企业内部使用 LDAP / AD / OAuth / OIDC 账号体系。
配置方式:DataSight 启用第三方认证登录,然后参考 对接内部登录系统,完成完整配置。

案例3:对接自研登录系统(非标准协议)

适用场景:内部登录协议为自研 cookie / token 体系,不是标准 LDAP / OAuth,无法直接接入。
配置方式:DataSight 启用第三方认证登录,然后参考 对接内部登录系统,完成完整配置,DataSight 本质上并不限制登录协议,只要反向代理能通过 header X-DATASIGHT-USER 指定用户名,X-DATASIGHT-ROLE 指定角色名,即可支持。

案例4:业务系统深链直达

适用场景:从业务系统(如订单、工单详情页)一键跳到对应的日志检索结果或查看仪表盘。
配置方式
1.1 拼接 DataSight URL(如果启用了反向代理,则应填写反向代理的域名)。
1.2 URL 参数说明,参见 页面内嵌 URL 参数说明

常见问题

内嵌后顶部/左侧导航还在,页面不像原生模块?

使用 hide 参数隐藏相关模块,详细说明参见 页面内嵌 URL 参数说明

匿名登录安全吗?

匿名登录的边界 = 内网边界,日志含敏感信息时慎用,建议通过对接内部登录系统实现免登录。

怎么按人 / 按角色控制权限?

用第三方认证登录 + X-DATASIGHT-ROLE(请参见 对接内部登录系统),在 DataSight 配置中为每个 X-DATASIGHT-ROLE 分配 CAM 子用户密钥。

iframe 集成无法满足需求,需要更深入的进行集成,该如何做?

使用 cls-console-sdk 进行二次开发。