Kibana 是一款开源的数据分析和可视化平台，可以对 Elasticsearch 中的数据进行查询、分析和可视化。通过日志服务提供的日志服务兼容 Elasticsearch 接口，可以实现在 Kibana 中查询和分析日志服务中的数据。

本章节介绍如何使用 KProxy 作为代理访问日志服务数据，使用 Kibana 检索日志。

功能介绍

KProxy 是一个高性能的兼容性代理网关，日志服务支持通过 KProxy 代理，使用标准的 Elasticsearch 7.10 协议和工具（如 Kibana、Elasticsearch SDK）直接访问日志服务中的日志数据，同时屏蔽了后端复杂的 ProjectID 和 TopicID 概念，提供了友好的命名空间管理。

日志服务 KProxy	说明
兼容 Elasticsearch 7.10 协议	支持 _search、 _msearch、 _resolve/index 等核心查询接口。
透明的资源映射	前端：使用易读的 Alias.TopicName（例如 my-app.access-log）。后端：自动转换为 TLS 要求的 ProjectID.TopicID（例如 pid-xxx.tid-yyy）。
零配置集成	内置后台进程，自动发现 TLS Topic 并在 Kibana 中创建对应的 Index Patterns。
多项目支持	单实例可代理多个 TLS Project，支持跨 Project 的统一视图。
高性能架构	基于 OpenResty (Nginx + Lua) 构建，支持高并发转发与 Lua 级缓存。
安全鉴权	代理 AWS v4 签名，支持 AK/SK 自动注入，前端可使用 Basic Auth 或无认证。

工作原理如下：

说明如下：

服务	说明
Kibana	用于查询、分析和可视化展示日志服务数据。
KProxy	用于对 Kibana 的 API 请求进行路由。区分 Kibana 对 Meta 数据和日志服务 Elasticsearch 兼容接口的 API 请求。
Elasticsearch	用于存储 Kibana 的 Meta 数据。日志服务不支持更新 Kibana 的 Meta 信息，但 Meta 信息会经常更新，所以需要部署一个 Elasticsearch 专门用于存储 Kibana 的 Meta 数据。
Elasticsearch 兼容接口	火山引擎日志服务 TLS 提供的兼容 Elasticsearch API，用于实现与标准 Elasticsearch 查询协议的兼容，详情可参考日志服务兼容 Elasticsearch 接口。
TLS	火山引擎日志服务 TLS 是日志和 Trace 类数据的一站式服务平台，提供数据采集、存储、检索分析、加工、消费、投递、监控告警、可视化等功能，适用于业务运维监控、数据统计分析等场景。

前提条件

已准备好用于环境部署的云服务器 ECS，详情可参考快速购买实例。

已配置云服务器 ECS 安全组的入方向规则 5601 端口（并确保放通全网段0.0.0.0/0），详情可参考查看/修改安全组访问规则。

已创建日志项目和日志主题。

检索日志之前，必须先开启索引，详情可参考配置索引。

已创建 IAM 角色，获取 Access Key ID、Secret Access Key。并为用户授予日志主题查询权限，详情可参考IAM 概述。

Kibana 需为 7.10 及以后版本。

Docker 需为1.18 及以后版本。

建议服务器的内存为 8GB 及以上。

1 部署环境

镜像地址

日志服务提供两个版本的 KProxy 镜像，可根据需求选择：

镜像	说明	镜像地址
Alpine 版（推荐）	体积小，不超过 100MB，启动快，适合生产环境。	tls-image-cn-shanghai.cr.volces.com/public/kproxy:1.0.17-alpine
Rocky Linux 版	包含完整调试工具，适合开发调试。	tls-image-cn-shanghai.cr.volces.com/public/kproxy:1.0.17

典型 Docker 配置示例

该示例提供最简启动命令，在后台启动一个名为 kproxy 的 Docker 容器，运行日志服务的 kproxy 代理程序，并通过环境变量配置了该代理连接 Elasticsearch 和日志服务，同时映射了 9201 端口供外部访问。

启动命令示例：

其中如下参数必填：

参数	示例	说明
ES_ENDPOINT	Elasticsearch 所在机器的 endpoint	Elasticsearch 所在机器的 endpoint。用于存储 Kibana 的元数据（仪表盘、索引模式等）。
TLS_ENDPOINT	http://tls-cn-beijing.ivolces.com/es/	日志服务所在机器的 endpoint（需以 /es/ 结尾）。
TLS_PROJECT_ID	2f687611-6e9a-4918-9720-68****	日志服务的项目 ID。
TLS_ACCESS_KEY_ID	AKTPODg0MzV2ZDcDemo****	火山引擎账号或 IAM 用户的 AccessKey ID。推荐使用 IAM 用户密钥，请确认该用户具备相关的操作权限。可以在火山引擎控制台密钥管理页面获取。
TLS_ACCESS_KEY_SECRET	TVRNNVlqRmxPR1mRoTkdW****	火山引擎账号或 IAM 用户的 AccessKey Secret。推荐使用 IAM 用户密钥，请确认该用户具备相关的操作权限。可以在火山引擎控制台密钥管理页面获取。
TLS_PROJECT_ALIAS	my-prod-env	【可选】前端展示用的项目别名。未设置时自动获取 Project Name。
TLS_TOPICNAME_FILTERS	access,error,app-*-log	【可选】Topic 过滤白名单（只自动创建匹配的 Topic）。支持通配符，多个规则用逗号分隔。默认为（匹配所有）。例如：app-,sys- 表示只创建以app-或sys-开头的 Topic。
KIBANA_SPACE	dev-space	【可选】指定 Index Pattern 创建的 Kibana Space。未设置时自动创建，默认为 default。

部署步骤

Docker Compose 完整部署

Docker Run 部署

推荐通过 docker-compose.yml 配置文件，定义和管理日志服务、Elasticsearch、kibana 等依赖，包含数据持久化、密码保护和环境变量隔离等。

目录结构如下：

创建 .env 文件。

在tls-kibana/目录下创建.env文件，配置如下信息，必填标记的参数需修改为实际值。

# ==========================================
# Elasticsearch & Kibana 基础配置
# ==========================================
# [必填] 设置 ES 和 Kibana 的超级管理员密码 (elastic 用户)
ES_PASSWORD=changeme

# ==========================================
# TLS Project 1 (主项目) 配置
# ==========================================
# [必填] TLS 的 ES 兼容接口地址 (需带 /es/)
# 来源: TLS 控制台 -> 项目概览 -> 访问入口 (外网或内网地址)
TLS_ENDPOINT=http://tls-cn-beijing.ivolces.com/es/

# [必填] TLS 项目 ID
# 来源: TLS 控制台 -> 项目概览 -> 项目ID
TLS_PROJECT_ID=pid-prod-xxx

# [可选] 前端展示用的项目别名 (默认使用 TLS 项目名称)
# TLS_PROJECT_ALIAS=prod

# [必填] 火山引擎访问密钥 AK
# 来源: 火山引擎控制台 -> 访问控制 -> 密钥管理
TLS_ACCESS_KEY_ID=AKLT...

# [必填] 火山引擎访问密钥 SK
TLS_ACCESS_KEY_SECRET=TkR...

# [可选] 过滤自动创建 Index Pattern 的 Topic (白名单，支持通配符)
# TLS_TOPICNAME_FILTERS="access*,error*"

# [可选] 指定 Kibana Space (默认 default)
# KIBANA_SPACE=default

# ==========================================
# TLS Project 2 (可选：第二个项目)
# ==========================================
# 如需配置更多项目，请取消注释并填写，注意变量名后缀 "2"
# TLS_ENDPOINT2=http://tls-cn-beijing.ivolces.com/es/ # 不填默认使用 TLS_ENDPOINT
# TLS_PROJECT_ID2=pid-test-xxx
# TLS_ACCESS_KEY_ID2=... # 不填默认使用 TLS_ACCESS_KEY_ID
# TLS_ACCESS_KEY_SECRET2=... # 不填默认使用 TLS_ACCESS_KEY_SECRET
# TLS_PROJECT_ALIAS2=test
# TLS_TOPICNAME_FILTERS2="*"
# KIBANA_SPACE2=test-space

创建 docker-compose.yml 文件。

在tls-kibana/目录下创建docker-compose.yml文件，配置如下信息。

version: '3'
services:
# 1. 元数据存储 (单节点 ES)
elasticsearch:
image: docker.elastic.co/elasticsearch/elasticsearch:7.17.26
container_name: elasticsearch
restart: always
environment:
- "discovery.type=single-node"
- "ES_JAVA_OPTS=-Xms512m -Xmx512m"
- ELASTIC_PASSWORD=${ES_PASSWORD}
- xpack.security.enabled=true
volumes:
# 数据持久化挂载
- ./data:/usr/share/elasticsearch/data

# 2. Kibana 可视化
kibana:
image: docker.elastic.co/kibana/kibana:7.17.26
container_name: kibana
restart: always
ports:
- "5601:5601"
environment:
- ELASTICSEARCH_HOSTS=http://kproxy:9201
- ELASTICSEARCH_USERNAME=elastic
- ELASTICSEARCH_PASSWORD=${ES_PASSWORD}
# 可选：设置为中文界面
# - I18N_LOCALE=zh-CN
depends_on:
- kproxy

# 3. 代理网关
kproxy:
image: tls-image-cn-shanghai.cr.volces.com/public/kproxy:1.0.17-alpine
container_name: kproxy
restart: always
ports:
- "9201:9201"
environment:
# --- 路由配置 ---
- ES_ENDPOINT=http://elasticsearch:9200
- TLS_ENDPOINT=${TLS_ENDPOINT}

# --- Project 1 (主项目) ---
- TLS_PROJECT_ID=${TLS_PROJECT_ID}
- TLS_ACCESS_KEY_ID=${TLS_ACCESS_KEY_ID}
- TLS_ACCESS_KEY_SECRET=${TLS_ACCESS_KEY_SECRET}
# 可选参数 (在 .env 中取消注释后生效)
- TLS_PROJECT_ALIAS=${TLS_PROJECT_ALIAS:-}
- TLS_TOPICNAME_FILTERS=${TLS_TOPICNAME_FILTERS:-}
- KIBANA_SPACE=${KIBANA_SPACE:-}

# --- Project 2 (可选) ---
# 如果在 .env 中配置了第二项目，这里会自动读取
# - TLS_ENDPOINT2=${TLS_ENDPOINT2:-}
# - TLS_PROJECT_ID2=${TLS_PROJECT_ID2:-}
# - TLS_ACCESS_KEY_ID2=${TLS_ACCESS_KEY_ID2:-}
# - TLS_ACCESS_KEY_SECRET2=${TLS_ACCESS_KEY_SECRET2:-}
# - TLS_PROJECT_ALIAS2=${TLS_PROJECT_ALIAS2:-}
# - TLS_TOPICNAME_FILTERS2=${TLS_TOPICNAME_FILTERS2:-}
# - KIBANA_SPACE2=${KIBANA_SPACE2:-}

# --- Kibana 集成 ---
- KIBANA_ENDPOINT=http://kibana:5601
- KIBANA_USER=elastic
- KIBANA_PASSWORD=${ES_PASSWORD}

depends_on:
- elasticsearch

在服务器中执行如下命令启动服务。

# 1. 创建数据目录并赋权
mkdir data && chmod 777 data

# 2. 启动服务
docker-compose up -d

如果只想快速启动一个容器做临时测试，可使用 Docker Run 部署，通过以下命令手动启动各个组件，必填标记的参数需修改为实际值。

2 访问Kibana

在左侧导航栏中，选择 Management > Stack Management。

在左侧导航栏中，选择 Kibana > Index Patterns。

QueryString 案例。

使用精准匹配

查询更友好，更精准。

使用*通配符

会触发全文扫描，数据量大时会增加响应时间。

配置介绍

多项目配置 (Multi-Project)

KProxy 支持同时代理多个日志项目。从第二个项目开始，环境变量需追加数字后缀{n} (n=2,3,...)。

例如：同时代理生产环境和测试环境。

Kibana 自动集成 (推荐)

配置以下变量后，KProxy 会启动守护进程：

自动将 TLS Topic 同步为 Kibana Index Patterns。名称格式为 Alias.TopicName，例如 prod.nginx-log。

自动清理 Kibana 中已不存在于 TLS 的旧 Pattern (仅删除 ID 以tls- 开头的 Pattern)。

环境变量	说明
KIBANA_ENDPOINT	Kibana 地址，例如 http://kibana:5601。
KIBANA_USER	Kibana 用户名。注意如果开启了 Elasticsearch 的 X-Pack 安全认证。KProxy 会自动检测 Elasticsearch 的 401 状态，并开启鉴权透传模式，Kibana 用户需使用在 Elasticsearch 中创建的账号，如 elastic。
KIBANA_PASSWORD	Kibana 密码。
PATTERN_REFRESH_INTERVAL	自动同步周期，单位秒，默认 180。

KProxy 映射刷新策略

KProxy 维护的 Alias.TopicName > TopicID 的映射表，支持以下刷新模式，默认配置已覆盖大多数场景：

映射刷新策略	说明
按需加载（On-Demand）	收到请求后，缓存未命中时，实时调用 TLS SDK 获取 TopicID 并缓存。支持新创建的 Topic 立即访问，无需等待周期刷新。默认开启，可设置ENABLE_TOPIC_MAP_ON_DEMAND=false关闭该策略。
启动时预加载（Bootstrap）	容器启动时立即执行一次全量拉取 Topic 列表，加速启动后首批请求的响应。默认开启，可设置ENABLE_TOPIC_MAP_BOOTSTRAP=false关闭该策略。
周期预加载（Periodic）	后台进程定期全量拉取 Topic 列表并更新到内存。适用于 Topic 变动不频繁，且希望极致降低首个请求延迟（避免按需加载的 SDK 调用开销）。默认关闭，可设置ENABLE_TOPIC_MAP_FETCH=true开启该策略。

其他配置

参数	说明
KPROXY_PORT	服务监听端口，默认 9201。
VOLCENGINE_REGION	手动指定区域（如 cn-beijing），通常可自动推断，无需手动指定。

常见问题与排查

1. 如何查看当前映射状态

进入容器查看生成的配置文件：

2. 如何处理报错 503 Service Unavailable

通常是因为 Topic 映射未找到。

检查 TLS_PROJECT_ID 是否正确，检查该 Project 下是否存在对应 TopicName。

或查看容器日志docker logs kproxy。

3. 如何处理加载 Discover 时报错 Could not locate that index-pattern

Kibana 的 Discover 依赖具体的 index-pattern ID，如果修改 Alias 或删除旧 Pattern，会导致该 index-pattern ID 失效。

此时需重新在 Kibana Index Patterns 中选择一个现存的 Pattern 作为默认 Pattern 即可。

4. 未找到 Kibana 的 Index Pattern

检查 KIBANA_ENDPOINT 是否可达。

检查 KProxy 日志 /var/log/tls_pattern.log。

确认 Kibana 版本（支持 7.10 及 OpenSearch Dashboards）。

5. 如何调优性能

对于极大规模 Topic 场景（数千个），建议开启ENABLE_TOPIC_MAP_FETCH=true，并调大 PATTERN_REFRESH_INTERVAL，减少 SDK 调用频率。

建议使用 Alpine 版的 KProxy 镜像。

API 参考

Search API

curl -u user:pass "http://localhost:9201/{Alias}.{TopicName}/_search?pretty" -d '{"query":{"match_all":{}}}'

MSearch API (Grafana 常用)

支持 NDJSON 格式，Header 中的 index 字段会自动被重写。

curl -XPOST "http://localhost:9201/_msearch" -H 'Content-Type: application/x-ndjson' --data-binary @- <<EOF
{"index": "prod.nginx-log"}
{"query": {"match_all": {}}}
EOF

Resolve API

curl "http://localhost:9201/_resolve/index/prod.nginx-log"