跳到主要内容
版本：3.9.x

记录 API 流量日志

API7 企业版支持记录包含主机、客户端 IP 地址和请求时间戳等信息的路由访问日志。这些日志可以帮助识别和解决问题。

API7 企业版通过其插件系统集成了许多日志平台。开箱即用的集成包括以下内容：

  • HTTP/TCP/UDP 日志服务器
  • SkyWalking
  • Kafka
  • RocketMQ
  • ClickHouse
  • Syslog
  • 阿里云 SLS
  • Google Cloud Logging Service
  • Splunk HTTP Event Collector (HEC)
  • File logging
  • Elasticsearch
  • 腾讯云 CLS
  • Grafana Loki

本教程将指导你配置 clickhouse-logger 插件，以将 API 流量日志记录到 ClickHouse 数据库中。

前置条件​

  1. 安装 API7 企业版。
  2. 在网关组上运行 API。

启动 ClickHouse 服务器​

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

docker run -d \
  --name quickstart-clickhouse-server \
  --network=api7-ee_api7 \
  -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 中创建一个包含 String 类型的 host、client_ip、route_id 和 @timestamp 字段的表 test，你也可以根据需要进行修改：

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

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

输入 exit 以退出 Docker 容器。

为所有服务配置日志记录​

强烈建议在全局规则中启用日志插件，以确保所有到服务和路由的流量都能被一致地追踪。

  1. 从侧边导航栏中选择网关组的 Plugin Settings（插件设置）。
  2. 选择 Plugin Global Rules（插件全局规则）选项卡，然后点击 Enable Plugin（启用插件）。
  3. 在 Plugins（插件）字段中搜索 clickhouse-logger 插件，然后点击 Enable（启用）。
  4. 在对话框中执行以下操作：

  • 将以下配置应用到 JSON Editor：

    {
      "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"]
    }

  • 点击 Enable（启用）。

验证​

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

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

你应该会看到类似以下的访问日志条目：

   ┌─host──────┬─client_ip─┬─route_id─┬─@timestamp────────────────┐
1. │ 127.0.0.1 │ 127.0.0.1 │ 23654f0  │ 2025-07-31T03:10:57+00:00 │
   └───────────┴───────────┴──────────┴───────────────────────────┘