跳到主要内容
版本：3.18.0

使用 ClickHouse 记录日志

APISIX 可以将结构化的请求和响应日志发送到 ClickHouse，以便查询、分析和故障排查。clickhouse-logger 插件会批量处理日志条目，并将它们写入列与所配置日志格式匹配的表中。

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

本指南将启动一个本地 ClickHouse 实例，配置 APISIX 发送自定义访问日志格式，并验证已存储的记录。

前置条件​

  • 安装 Docker。
  • 安装 cURL 以向服务发送请求进行验证。
  • 按照 快速入门教程 使用 Docker 启动 APISIX。
  • 如需使用 ADC 配置 APISIX，请安装 ADC。

配置 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:26.8.5.13

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

docker exec -it quickstart-clickhouse-server \
  clickhouse-client \
  --user quickstart-user \
  --password quickstart-pass

在数据库 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()

如果成功，ClickHouse 会返回 Ok。

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

启用 clickhouse-logger 插件​

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

全局启用 clickhouse-logger 插件：

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

➊ log_format：与 ClickHouse 表中各列对应的字段。

➋ user、password、database、logtable 和 endpoint_addrs：本地 ClickHouse 实例的连接和目标表设置。

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

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

批量提交日志​

clickhouse-logger 插件使用批处理器，以减少发送到 ClickHouse 的请求数。

默认情况下，批处理器会在五秒内没有新条目，或一个批次达到 1,000 个条目时提交数据。你可以使用 inactive_timeout 调整空闲时间间隔，使用 batch_max_size 调整最大条目数。以下配置使用十秒空闲时间间隔，并允许每批最多 2,000 个条目：

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

验证日志记录​

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

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

使用 clickhouse-client 查询最新记录：

docker exec quickstart-clickhouse-server \
  clickhouse-client \
  --user quickstart-user \
  --password quickstart-pass \
  --query 'SELECT * FROM quickstart_db.test ORDER BY `@timestamp` DESC LIMIT 1 FORMAT PrettyCompactMonoBlock'

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

   ┌─host──────┬─client_ip─────┬─route_id────────────┬─@timestamp────────────────┐
1. │ 127.0.0.1 │ 192.168.155.1 │ getting-started-ip │ 2026-09-16T12:30:37+00:00 │
   └───────────┴───────────────┴─────────────────────┴───────────────────────────┘

下一步​

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