# 使用 ClickHouse 记录日志

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

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

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

## 前置条件[​](#前置条件 "前置条件的直接链接")

* 安装 [Docker](https://docs.docker.com/get-docker/)。
* 安装 [cURL](https://curl.se/) 以向服务发送请求进行验证。
* 按照 [快速入门教程](https://docs.apiseven.com/apisix/getting-started.md) 使用 Docker 启动 APISIX。
* 如需使用 ADC 配置 APISIX，请安装 [ADC](https://docs.apiseven.com/apisix/reference/adc.md)。
* 如果使用 Admin API 示例且启用了身份验证，请将管理员角色的密钥导出为 `ADMIN_API_KEY`。请在 `deployment.admin.admin_key` 下配置该密钥。Docker 快速入门为了便于本地评估而禁用了身份验证；生产环境中请保持启用。

## 配置 ClickHouse[​](#配置-clickhouse "配置 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
```

等待常规服务器监听器就绪，而不要连接到临时的回环初始化服务器：

```
for attempt in $(seq 1 60); do

  if docker exec quickstart-clickhouse-server clickhouse-client \

    --host quickstart-clickhouse-server --user quickstart-user \

    --password quickstart-pass --query "SELECT 1" >/dev/null 2>&1; then

    break

  fi

  sleep 1

done

docker exec quickstart-clickhouse-server clickhouse-client \

  --host quickstart-clickhouse-server --user quickstart-user \

  --password quickstart-pass --query "SELECT 1"
```

服务器响应后，使用 `clickhouse-client` 连接：

```
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-插件的直接链接")

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

* Admin API
* ADC

全局启用 `clickhouse-logger` 插件：

```
curl -i "http://127.0.0.1:9180/apisix/admin/global_rules/clickhouse" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -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 "X-API-KEY: ${ADMIN_API_KEY}" \

  -H "Content-Type: application/json" \

  -d '{

    "uri": "/ip",

    "upstream": {

      "type": "roundrobin",

      "nodes": {

        "httpbin.org:80": 1

      }

    }

}'
```

全局规则无法通过标签选择器相互隔离。添加本规则前，请导出完整的全局规则集合：

```
adc dump -o adc-global-rule.yaml --with-id \

  --include-resource-type global_rule
```

保留导出文件中的其他所有全局规则，并添加 `clickhouse-logger` 条目：

adc-global-rule.yaml (global\_rules excerpt)

```
global_rules:

  # Keep all other global rules from the exported file.

  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"
```

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

❷ ClickHouse 服务器信息。

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

adc-route.yaml

```
services:

  - name: clickhouse-howto

    routes:

      - uris:

          - /ip

        name: getting-started-ip

    upstream:

      type: roundrobin

      nodes:

        - host: httpbin.org

          port: 80

          weight: 1
```

预览完整的全局规则集合，并确认差异中不包含意外的更新或删除：

```
adc diff -f adc-global-rule.yaml \

  --include-resource-type global_rule
```

同步已审查的全局规则：

```
adc sync -f adc-global-rule.yaml \

  --include-resource-type global_rule
```

预览服务范围内的路由变更：

```
adc diff -f adc-route.yaml \

  --include-resource-type service \

  --label-selector docs-example=clickhouse-howto
```

同步已审查的服务配置：

```
adc sync -f adc-route.yaml \

  --include-resource-type service \

  --label-selector docs-example=clickhouse-howto
```

## 批量提交日志[​](#批量提交日志 "批量提交日志的直接链接")

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

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

* Admin API
* ADC

```
curl -i "http://127.0.0.1:9180/apisix/admin/global_rules/clickhouse" -X PATCH \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -H "Content-Type: application/json" \

  -d '{

    "plugins": {

      "clickhouse-logger": {

        "batch_max_size": 2000,

        "inactive_timeout": 10

      }

    }

}'
```

更新完整的全局规则配置，将 `inactive_timeout` 设置为 10 秒，将 `batch_max_size` 设置为 2,000 个条目：

adc-global-rule.yaml

```
global_rules:

  # Keep all other global rules from the exported file.

  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"

    batch_max_size: 2000

    inactive_timeout: 10
```

预览完整的全局规则集合，并确认其中不包含无关规则的变更：

```
adc diff -f adc-global-rule.yaml \

  --include-resource-type global_rule
```

同步已审查的全局规则：

```
adc sync -f adc-global-rule.yaml \

  --include-resource-type global_rule
```

## 验证日志记录[​](#验证日志记录 "验证日志记录的直接链接")

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

```
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`](https://docs.apiseven.com/hub/clickhouse-logger.md) 插件文档以了解更多有关插件配置选项的信息。
