跳到主要内容

使用 ClickHouse 记录日志

APISIX 支持收集路由访问信息并将其记录为日志，例如主机、客户端 IP 和请求时间戳。这些关键信息将对解决相关问题大有帮助。

ClickHouse 是一个开源的面向列的数据库管理系统 (DBMS)，用于在线分析处理 (OLAP)。它允许用户使用 SQL 查询实时生成分析报告，例如日志分析。

本指南将向你展示如何启用 clickhouse-logger 插件将 APISIX 日志记录到 ClickHouse 数据库中。

前置条件​

  • 安装 Docker。
  • 安装 cURL 以向服务发送请求进行验证。
  • 按照 快速入门教程 在 Docker 或 Kubernetes 中启动一个新的 APISIX 实例。

配置 ClickHouse​

启动一个名为 quickstart-clickhouse-server 的 ClickHouse 实例，默认数据库为 quickstart_db，默认用户为 quickstart-user，密码为 quickstart-pass：

docker run -d \
  --name quickstart-clickhouse-server \
  --network=apisix-quickstart-net \
  -e CLICKHOUSE_DB=quickstart_db \
  -e CLICKHOUSE_USER=quickstart-user \
  -e CLICKHOUSE_PASSWORD=quickstart-pass \
  -e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 \
  --ulimit nofile=262144:262144 \
  clickhouse/clickhouse-server

在 Docker 中使用命令行工具 clickhouse-client 连接到 ClickHouse 实例：

docker exec -it quickstart-clickhouse-server clickhouse-client

在数据库 quickstart_db 中创建表 test，包含 String 类型的字段 host、client_ip、route_id、@timestamp，或根据你的需要相应调整命令：

CREATE TABLE quickstart_db.test (
  `host` String,
  `client_ip` String,
  `route_id` String,
  `@timestamp` String,
   PRIMARY KEY(`@timestamp`)
) ENGINE = MergeTree()

如果成功，你应该在输出中看到 Ok。

输入 exit 退出 Docker 中的命令行界面。

启用 clickhouse-logger 插件​

全局启用 clickhouse-logger 插件。或者，你可以在路由上启用该插件。

全局启用 clickhouse-logger 插件：

curl -i "http://127.0.0.1:9180/apisix/admin/global_rules" -X PUT -d '
{
  "id": "clickhouse",
  "plugins": {
    "clickhouse-logger": {
// Annotate 1
      "log_format": {
        "host": "$host",
        "@timestamp": "$time_iso8601",
        "client_ip": "$remote_addr"
      },
// Annotate 2
      "user": "quickstart-user",
      "password": "quickstart-pass",
      "database": "quickstart_db",
      "logtable": "test",
      "endpoint_addrs": ["http://quickstart-clickhouse-server:8123"]
    }
  }
}'

➊ 指定日志格式中对应 ClickHouse 表的字段

➋ ClickHouse 服务器信息

创建一个你将收集日志的示例路由：

curl -i "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
{
  "id": "getting-started-ip",
  "uri": "/ip",
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'

批量提交日志​

clickhouse-logger 插件支持使用批处理器聚合和处理日志。这避免了频繁向 ClickHouse 提交日志条目，这会降低操作速度。

默认情况下，批处理器每 5 秒或当批处理中的数据大小达到 1000 KB 时提交数据。你可以调整插件的提交时间间隔 inactive_timeout 和最大批处理大小 batch_max_size。例如，这是将 inactive_timeout 设置为 10 秒并将 batch_max_size 设置为 2000 KB 的方法：

curl -i "http://127.0.0.1:9180/apisix/admin/global_rules/clickhouse" -X PATCH -d '
{
  "plugins": {
    "clickhouse-logger": {
      "batch_max_size": 2000,
      "inactive_timeout": 10
    }
  }
}'

验证日志记录​

向路由发送请求以生成访问日志条目：

curl -i "http://127.0.0.1:9080/ip"

在 Docker 中使用命令行工具 clickhouse-client 连接到 ClickHouse 实例：

docker exec -it quickstart-clickhouse-server clickhouse-client

查询表 quickstart_db.test 中的所有记录：

SELECT * from quickstart_db.test

你应该看到类似以下的访问记录，这验证了 clickhouse-logger 插件按预期工作。

   ┌─host──────┬─client_ip─┬─route_id─┬─@timestamp────────────────┐
1. │ 127.0.0.1 │ 127.0.0.1 │ 5e835ead │ 2025-08-12T09:17:04+00:00 │
   └───────────┴───────────┴──────────┴───────────────────────────┘

下一步​

参阅 clickhouse-logger 插件文档以了解更多有关插件配置选项的信息。