使用 Vector 和 ClickHouse 採集 OpenResty Edge 日誌

本文介紹如何使用 Vector 採集 OpenResty Edge Node 的日誌， 並將日誌集中寫入 ClickHouse。ClickHouse 透過 Docker Compose 部署在獨立的 資料庫伺服器上，Vector 以 systemd 服務的形式部署在每臺 Edge Node 上。

Edge Node 日誌檔案 -> 本機 Vector -> HTTPS -> ClickHouse

# 採集範圍

部署完成後，Vector 將日誌寫入 app 資料庫中的三個表：

HTTP 和 Stream 訪問日誌必須使用部署包提供的 JSON 格式。Vector 會解析預設格式的 NGINX 錯誤日誌。解析失敗的日誌不會被丟棄，其 parsed_ok 欄位為 0，原始內容儲存在 raw_message 欄位中。

錯誤日誌採集是可選的。如果不需要將錯誤日誌寫入 ClickHouse，請在部署 Vector 前從 edge-vector-deployment/vector.yaml 中刪除以下三個完整配置塊：

• sources.nginx_error。
• transforms.normalize_error。
• sinks.clickhouse_error。

刪除 Vector 中的採集配置即可，不要刪除 Edge Node 上的原始錯誤日誌檔案。 ClickHouse 中未使用的 nginx_error_logs 空表可以保留，不會寫入錯誤日誌資料。

# 部署準備

準備一臺 ClickHouse 伺服器以及至少一臺已加入 Edge Admin 的 Edge Node。

本文使用以下示例值，請按實際環境替換：

交付檔案包含兩個版本配套的壓縮包。以下以 1.0.0 版本為例：

# 在 ClickHouse 伺服器上解壓

將 edge-clickhouse-deployment-1.0.0.tar.gz 下載到 ClickHouse 伺服器的 /opt 目錄並 解壓：

cd /opt
sudo curl -O https://openresty.com/client/oredge/edge-clickhouse-deployment-1.0.0.tar.gz
sudo tar -xzf edge-clickhouse-deployment-1.0.0.tar.gz

解壓後的目錄結構如下：

/opt/
└── edge-clickhouse-deployment/
    ├── .env.example
    ├── auto-deploy.sh
    ├── certs/
    ├── config.d/
    ├── docker-compose.yml
    ├── initdb/
    └── users.d/

# 在 Edge Node 上解壓

將 edge-vector-deployment-1.0.0.tar.gz 下載到每臺 Edge Node 的 /opt 目錄並解壓：

cd /opt
sudo curl -O https://openresty.com/client/oredge/edge-vector-deployment-1.0.0.tar.gz
sudo tar -xzf edge-vector-deployment-1.0.0.tar.gz

解壓後的目錄結構如下：

/opt/
└── edge-vector-deployment/
    ├── auto-deploy.sh
    ├── systemd/
    ├── vector.env.example
    └── vector.yaml

解壓後的部署目錄不帶版本號，始終使用 /opt/edge-clickhouse-deployment 和 /opt/edge-vector-deployment。兩個壓縮包的版本必須一致；固定目錄名可以避免版本 變化影響部署和升級指令碼中的路徑。

確認各主機的時間和時區配置正確。ClickHouse 表以 UTC 儲存時間；查詢客戶端可以按需 轉換顯示時區。為 clickhouse.example.com 準備由客戶端信任的 CA 簽發的伺服器 證書，證書的 Subject Alternative Name 必須包含該域名。公網服務建議使用受公共信任 的 CA；使用組織內部 CA 時，需要將 CA 證書部署到每臺 Edge Node。

# 配置 Edge 訪問日誌

# 配置 HTTP 訪問日誌格式

1. 登入 Edge Admin，進入 全域性配置 > 通用 > 日誌。

2. 使用以下任一方式配置 HTTP 訪問日誌格式：

   • 修改預設的 main 格式。
   • 新增一個名為 vector-json 的格式，並將其設定為預設訪問日誌格式。

3. 將所選格式的內容替換為：

   {
   "app_id": $app_id,
   "timestamp":"$time_iso8601",
   "remote_addr":"$remote_addr",
   "remote_user":"$remote_user",
   "http_host":"$http_host",
   "request":"$request",
   "status":$status,
   "body_bytes_sent":$body_bytes_sent,
   "request_time":$request_time,
   "http_referer":"$http_referer",
   "http_user_agent":"$http_user_agent",
   "upstream_addr":"$upstream_addr",
   "upstream_status":"$upstream_status",
   "upstream_connect_time":"$upstream_connect_time",
   "upstream_header_time":"$upstream_header_time",
   "upstream_response_time":"$upstream_response_time",
   "upstream_cache_status":"$upstream_cache_status",
   "pid":$pid,
   "req_id":"$req_id",
   "request_length":$request_length,
   "invalid_referer":"$invalid_referer",
   "internal_request":"$internal_request"
   }
   

4. 將 Escape（轉義） 設定為 json。

5. 檢查需要採集日誌的 HTTP 應用。使用預設格式的應用會自動採用上述配置；如果應用 顯式選擇了其他格式，請改為 main 或 vector-json。

6. 儲存併發布配置。

該格式包含應用 ID、請求、狀態碼、請求耗時和上游耗時等欄位。有關可用變數的說明， 請參見OpenResty Edge 的訪問日誌變數。

Edge Admin 釋出配置時會自動刪除日誌格式中的換行符。雖然上述 JSON 為方便閱讀採用 多行展示，Edge Node 實際寫入時每條日誌只佔一行，檔案格式為 JSON Lines（JSONL）。

# 配置 Stream 訪問日誌格式

1. 在 全域性配置 > 通用 > 日誌 中找到 Stream 訪問日誌格式。

2. 將原有的空格分隔格式替換為：

   {
   "timestamp":"$time_iso8601",
   "remote_addr":"$remote_addr",
   "protocol":"$protocol",
   "status":$status,
   "bytes_sent":$bytes_sent,
   "bytes_received":$bytes_received,
   "session_time":$session_time,
   "upstream_addr":"$upstream_addr",
   "upstream_bytes_sent":"$upstream_bytes_sent",
   "upstream_bytes_received":"$upstream_bytes_received",
   "upstream_connect_time":"$upstream_connect_time",
   "server_addr":"$server_addr",
   "server_port":$server_port
   }
   

3. 將 Escape（轉義） 設定為 json，儲存併發布配置。

JSON 格式使用 $time_iso8601 生成 timestamp，Vector 會將其寫入 ClickHouse 的 event_time 欄位。其他欄位與原有 Stream 訪問日誌中的連線狀態、流量和上游資訊 一一對應。Edge Admin 同樣會刪除該格式中的換行符，因此 Stream 訪問日誌也是每條 記錄佔一行的 JSONL。

如果不需要採集 Stream 日誌，可以跳過本步驟，並保留 Vector 中相應的採集配置。 在沒有匹配檔案時，Vector 不會產生 Stream 日誌資料。

# 保持日誌格式一致

訪問日誌格式必須與同一版本 ClickHouse 部署包中的表結構保持一致。兩個交付包中的 以下配置是配套的：

• 本文給出的 HTTP 和 Stream JSON 格式定義 Edge 輸出的欄位。
• edge-vector-deployment/vector.yaml 中的 normalize_http_access 和 normalize_stream_access 定義欄位解析與轉換規則。
• edge-clickhouse-deployment/initdb/001-nginx-logs.sql 定義 ClickHouse 表的列名和 型別。

不要只在 Edge Admin 中增加、刪除欄位或修改欄位型別。如果需要自定義日誌格式，必須 同步修改 Vector 轉換規則和 ClickHouse 表結構，並在釋出前驗證三處配置一致。

# 對齊 Edge 日誌檔名

OpenResty Edge 預設使用 stream_access.log，並將輪轉檔案命名為 access.log_YYYYMMDD.HHMMSS 這類下劃線字尾。部署 Vector 前，編輯 edge-vector-deployment/vector.yaml，確認三個 file source 的 include 覆蓋當前 日誌和未壓縮的輪轉日誌：

sources:
  nginx_http_access:
    include:
      - ${NGINX_LOG_DIR}/access.log
      - ${NGINX_LOG_DIR}/access.log_*

  nginx_stream_access:
    include:
      - ${NGINX_LOG_DIR}/stream_access.log
      - ${NGINX_LOG_DIR}/stream_access.log_*

  nginx_error:
    include:
      - ${NGINX_LOG_DIR}/*error*.log
      - ${NGINX_LOG_DIR}/*error*.log_*
      - ${NGINX_LOG_DIR}/**/*error*.log
      - ${NGINX_LOG_DIR}/**/*error*.log_*

生產環境建議保留輪轉日誌的匹配規則。Vector 持續執行時會繼續讀取已經開啟的輪轉 檔案；如果 Vector 停機或重啟跨過了輪轉時間，access.log_* 等規則可以讓它根據 檢查點補採未壓縮的舊檔案。只匹配當前 access.log 適用於允許少量日誌丟失的即時 採集場景，不建議用於完整日誌留存。

保留各 source 中排除 *.gz 檔案的配置，並確保被採集的日誌沒有啟用 Gzip 壓縮， 以便 Vector 在故障恢復後補採輪轉檔案。有關預設路徑和輪轉方式，請參見 日誌檔案的路徑和 日誌輪轉。

在 Edge Node 上產生測試流量後，確認 HTTP 訪問日誌是單行 JSON：

sudo tail -n 1 /usr/local/oredge-node/logs/access.log

# 部署 ClickHouse

# 準備伺服器證書

在 ClickHouse 伺服器的部署目錄中建立 certs，並放入證書鏈和私鑰：

edge-clickhouse-deployment/
└── certs/
    ├── server.crt
    └── server.key

server.crt 應包含完整證書鏈，server.key 不得加密，以便 ClickHouse 無人值守啟動。 限制私鑰的讀取許可權，同時確保容器內的 ClickHouse 程序能夠讀取它。不要將證書私鑰 提交到版本控制系統。

# 啟用 ClickHouse HTTPS

部署包中的 edge-clickhouse-deployment/config.d/custom.xml 已預設配置為：

<clickhouse>
    <timezone>UTC</timezone>
    <max_connections>4096</max_connections>
    <listen_host>0.0.0.0</listen_host>
    <http_port>8123</http_port>
    <https_port>443</https_port>
    <tcp_port>9000</tcp_port>
    <openSSL>
        <server>
            <certificateFile>/etc/clickhouse-server/certs/server.crt</certificateFile>
            <privateKeyFile>/etc/clickhouse-server/certs/server.key</privateKeyFile>
            <loadDefaultCAFile>true</loadDefaultCAFile>
            <cacheSessions>true</cacheSessions>
            <disableProtocols>sslv2,sslv3,tlsv1,tlsv1_1</disableProtocols>
            <preferServerCiphers>true</preferServerCiphers>
        </server>
    </openSSL>
</clickhouse>

部署包中的 edge-clickhouse-deployment/docker-compose.yml 預設掛載證書，但不向 宿主機發布埠。auto-deploy.sh 會根據使用者指定的埠生成 docker-compose.ports.yml。例如，使用 --https-port 443 時，生成的埠配置等效於：

services:
  clickhouse:
    ports:
      - "${CLICKHOUSE_BIND_ADDRESS:-0.0.0.0}:443:443"

埠對映左側是使用者指定的宿主機埠，右側是固定的容器埠。ClickHouse 在容器內 始終監聽 HTTPS 443；使用上述引數時，宿主機和容器的埠對映為 443:443。

不要刪除 Compose 檔案中的 healthcheck；它透過容器內部的 HTTP 8123 介面檢查 服務。clickhouse-init 同樣透過 Compose 內部的 Native TCP 9000 介面完成初始化。 只有顯式指定對應的部署引數時，這些端口才會發布到宿主機。

# 配置環境變數

在 ClickHouse 伺服器上執行：

cd /opt/edge-clickhouse-deployment
sudo cp .env.example .env
sudo chmod 600 .env

使用 sudoedit .env 編輯檔案，至少修改以下配置：

CLICKHOUSE_TAG=26.3.17.56
CLICKHOUSE_DB=app
CLICKHOUSE_USER=app
CLICKHOUSE_PASSWORD=請替換為強管理密碼
CLICKHOUSE_VECTOR_PASSWORD=請替換為強寫入密碼
CLICKHOUSE_OREDGE_READER_PASSWORD=請替換為強只讀密碼
CLICKHOUSE_RETENTION_DAYS=365
CLICKHOUSE_BIND_ADDRESS=0.0.0.0

三個賬號應使用不同的強密碼，可以使用 openssl rand -hex 32 分別生成。.env 包含明文憑據，只允許管理員讀取，不要將其提交到版本控制系統。對外埠不再透過 .env 設定，而是在首次執行 auto-deploy.sh 時透過命令列引數指定。

# 執行自動部署指令碼

檢視指令碼支援的部署引數：

cd /opt/edge-clickhouse-deployment
sudo ./auto-deploy.sh --help

可用的埠引數如下：

如果不指定任何埠引數，指令碼不會向宿主機發布埠。本文只需要 HTTPS 介面，建議將 宿主機標準 HTTPS 443 埠對映到容器的 443 埠。

使用 Docker 部署：

cd /opt/edge-clickhouse-deployment
sudo ./auto-deploy.sh --https-port 443

使用 Podman 部署：

cd /opt/edge-clickhouse-deployment
sudo ./auto-deploy.sh --runtime podman --https-port 443

下文以 Docker 命令為例。使用 Podman 時，請將 docker 替換為 podman。

埠引數必須在首次部署時指定。如果 ClickHouse 容器已經存在，指令碼會直接退出，不會 修改現有容器或 docker-compose.ports.yml。

指令碼會建立 clickhouse_data 和 clickhouse_logs 兩個外部卷，啟動 ClickHouse， 並透過一次性的 clickhouse-init 容器完成以下初始化：

• 建立三個日誌表並配置資料保留時間。
• 建立僅能寫入日誌表的 vector 賬號。
• 建立僅能查詢日誌表的 oredge-reader 賬號。

檢查容器狀態：

sudo docker compose \
    --project-name clickhouse-deployment \
    --file docker-compose.yml \
    --file docker-compose.ports.yml \
    ps --all

clickhouse-init 顯示 Exited (0) 是正常現象。ClickHouse 服務應處於執行且健康的 狀態。如果初始化失敗，請檢查其日誌：

sudo docker compose \
    --project-name clickhouse-deployment \
    --file docker-compose.yml \
    --file docker-compose.ports.yml \
    logs clickhouse-init

# 配置網路訪問

在防火牆或安全組中開放 --https-port 指定的 TCP 埠。本文使用 443。不要向公網 開放 ClickHouse 的明文 HTTP 和 Native TCP 埠。如果 Edge Node 有固定出口地址， 仍建議限制允許訪問 HTTPS 埠的來源範圍；不能限制來源時，應使用隨機強密碼，並在 伺服器入口配置連線限速和異常訪問監控。

確認 clickhouse.example.com 已解析到 ClickHouse 伺服器，然後在每臺 Edge Node 上測試 HTTPS 連通性。命令會互動式提示輸入 vector 賬號的密碼：

curl --user vector --data-binary 'SELECT 1' \
    https://clickhouse.example.com/

返回 1 表示 DNS、TLS 證書、埠和憑據均可用。使用組織內部 CA 時，透過 --cacert /path/to/organization-ca.crt 指定 CA 證書。不要使用 --insecure 或 -k 跳過證書校驗。如果 --https-port 使用的不是 443，URL 中也必須顯式指定 相同埠，例如 https://clickhouse.example.com:8443/。

# 在 Edge Node 上部署 Vector

以下步驟需要在每臺要採集日誌的 Edge Node 上執行。

# 配置 Vector HTTPS

部署包中的 edge-vector-deployment/vector.yaml 已在三個 ClickHouse sink 中啟用 證書和主機名校驗：

tls:
  verify_certificate: true
  verify_hostname: true

執行自動部署指令碼，並傳入伺服器證書所覆蓋的域名：

cd /opt/edge-vector-deployment
sudo ./auto-deploy.sh --host clickhouse.example.com

指令碼預設使用 HTTPS 443 埠，安全地提示輸入 vector 賬號密碼，並自動完成以下 操作：

• 安裝 openresty-vector 軟體包（尚未安裝時）。
• 建立非特權的 vector 系統賬號。
• 安裝 Vector 配置、環境變數和 vector-edge.service。
• 驗證配置並啟動服務。

如需非互動式部署，可將密碼第一行寫入僅允許 root 讀取的檔案：

sudo ./auto-deploy.sh --host clickhouse.example.com \
    --password-file /root/vector-password

需要覆蓋已有的 Vector 託管配置時增加 --force：

sudo ./auto-deploy.sh --force --host clickhouse.example.com

如果 ClickHouse 部署時透過 --https-port 指定了非 443 埠，部署 Vector 時必須 透過 --port 指定相同埠。例如，ClickHouse 使用 --https-port 8443 時執行：

sudo ./auto-deploy.sh --host clickhouse.example.com --port 8443

使用本文推薦配置時，Vector 會連線 https://clickhouse.example.com:443。不要將 --host 設定為 IP，除非伺服器證書的 Subject Alternative Name 中也包含該 IP。 使用組織內部 CA 時，應先將 CA 證書加入 Edge Node 的系統信任庫；不要使用關閉證書 校驗的方式繞過 TLS 錯誤。

主要檔案和資料目錄如下：

# 授予日誌讀取許可權

部署完成後，優先使用 Edge 日誌所屬使用者組或 ACL 授權，不要讓 Vector 以 root 使用者 執行。以下 ACL 示例授予現有日誌讀取許可權，並讓輪轉後新建的檔案繼承相同許可權：

sudo setfacl -m u:vector:x /usr/local/oredge-node
sudo setfacl -R -m u:vector:rX /usr/local/oredge-node/logs
sudo setfacl -d -m u:vector:rX /usr/local/oredge-node/logs

如果系統沒有 setfacl，請先安裝 ACL 工具，或透過 Edge 日誌所屬使用者組授予等效的 讀取和目錄遍歷許可權。

# 檢查 Vector 狀態

載入 systemd 配置並啟動服務：

sudo systemctl daemon-reload
sudo systemctl enable --now vector-edge.service

Vector 首次啟動時從所有匹配且未壓縮的檔案開頭讀取，後續從檢查點繼續。如果節點上 已有大量歷史日誌，請先評估首次匯入量，或臨時縮小 include 範圍。HTTP 日誌 sink 的磁碟緩衝區上限為 4 GiB，Stream 和錯誤日誌 sink 各為 512 MiB。請為 /var/lib/vector-edge 預留足夠空間，並在重啟或升級時保留該目錄。

檢查服務狀態和即時日誌：

sudo systemctl status vector-edge.service
sudo journalctl -u vector-edge.service -f

修改配置後，重新安裝配置檔案並重啟服務。不要刪除現有資料目錄：

cd /opt/edge-vector-deployment
sudo install -o root -g root -m 0644 vector.yaml \
    /etc/vector-edge/vector-edge.yaml
sudo systemctl restart vector-edge.service

# 檢查 Vector 上報是否異常

vector-edge.service 處於 active 狀態只表示程序正在執行，不代表日誌一定已經成功寫入 ClickHouse。首先檢視最近 10 分鐘的服務日誌：

sudo journalctl -u vector-edge.service --since "10 minutes ago" --no-pager

也可以篩選常見的上報異常關鍵詞：

sudo journalctl -u vector-edge.service --since "10 minutes ago" --no-pager \
    | grep -Ei 'error|warn|failed|timeout|refused|tls|certificate|401|403|429|5[0-9]{2}|buffer'

重點關注以下資訊：

部署包已在 127.0.0.1:8686 啟用僅本機可訪問的 Vector API。可以透過 vector top 觀察三個 ClickHouse sink 的吞吐量和錯誤計數：

sudo /usr/local/openresty-vector/bin/vector top \
    --components 'clickhouse_*'

產生測試流量後，如果 ClickHouse sink 的錯誤數持續增加，或者輸入事件持續增加但傳送 事件不再增加，說明上報存在異常。短暫的重試不一定會丟失日誌；只要磁碟緩衝區未滿， Vector 會在 ClickHouse 恢復後繼續傳送。按 Ctrl+C 退出 vector top。

最後應結合下一節的 ClickHouse 查詢確認 last_ingested_at 持續更新。只有同時滿足 Vector sink 沒有持續錯誤、傳送計數持續增加且 ClickHouse 最新寫入時間正常，才能確認 上報鏈路正常。

# 驗證日誌採集

先透過已配置的 HTTP 或 Stream 應用產生幾條測試流量，然後在 ClickHouse 伺服器上 進入只讀客戶端：

cd /opt/edge-clickhouse-deployment
sudo docker compose \
    --project-name clickhouse-deployment \
    --file docker-compose.yml \
    --file docker-compose.ports.yml \
    exec clickhouse clickhouse-client \
    --user oredge-reader --password --database app

輸入 .env 中的 CLICKHOUSE_OREDGE_READER_PASSWORD，再執行以下查詢。

檢視各類日誌數量和最後寫入時間：

SELECT 'http' AS type, count() AS rows, max(ingested_at) AS last_ingested_at
FROM nginx_http_access_logs
UNION ALL
SELECT 'stream', count(), max(ingested_at)
FROM nginx_stream_access_logs
UNION ALL
SELECT 'error', count(), max(ingested_at)
FROM nginx_error_logs;

檢視最近的 HTTP 請求：

SELECT
    event_time,
    app_id,
    nginx_host,
    remote_addr,
    http_host,
    request,
    status,
    request_time,
    upstream_addr,
    upstream_status
FROM nginx_http_access_logs
ORDER BY event_time DESC
LIMIT 20;

檢查日誌解析質量：

SELECT
    nginx_host,
    parsed_ok,
    count() AS rows,
    max(ingested_at) AS last_ingested_at
FROM nginx_http_access_logs
GROUP BY nginx_host, parsed_ok
ORDER BY nginx_host, parsed_ok;

如果存在 parsed_ok = 0 的記錄，檢查無法解析的原始日誌：

SELECT ingested_at, source_file, raw_message
FROM nginx_http_access_logs
WHERE parsed_ok = 0
ORDER BY ingested_at DESC
LIMIT 20;

# 容量規劃

日誌長度、欄位內容和重複度都會影響 ClickHouse 的壓縮效果。例如，較長的 URL、 User-Agent、上游地址和錯誤資訊會增加單條日誌的空間佔用。因此，應以實際業務日誌的 壓縮後資料為準，不要只根據原始日誌檔案大小估算。

# 容量計算公式

分別計算 HTTP、Stream 和可選錯誤日誌，再將結果相加：

基礎資料容量 = 每天日誌條數 × 保留天數 × 壓縮後平均每條位元組數
規劃資料盤容量 = 基礎資料容量 × 2 × (1 + 預計業務增長率)

這裡建議使用 2 作為執行安全係數，用於預留後臺合併、TTL 刪除延遲、資料波動和 至少 30% 的可用空間。該係數不包括備份和副本：

• 在同一伺服器保留一份完整備份時，至少再增加一份基礎資料容量；建議將備份存放到 獨立磁碟或物件儲存。
• 部署多個 ClickHouse 副本時，叢集的總儲存量還要乘以副本數。
• 如果預計一年內流量增長 30%，公式中的預計業務增長率填寫 0.3。

# 一百萬條日誌的容量示例

在沒有實測資料時，可以暫時按壓縮後平均每條 500 位元組估算。100 萬條日誌的 ClickHouse 活躍資料大約佔用 0.5 GB，乘以執行安全係數後，應為這批日誌規劃約 1 GB 資料盤空間。

不同日誌內容下的估算如下。表中使用十進位制單位，1 GB = 1,000,000,000 位元組：

這些數值只表示新增日誌資料所需的空間，不是 ClickHouse 伺服器的最小磁碟配置。 伺服器還需要為作業系統、容器映象、ClickHouse 執行日誌和其他運維檔案預留空間。

# 儲存一年的容量示例

以下示例假設每天的日誌總量已經包含 HTTP、Stream 和可選錯誤日誌，壓縮後平均每條 500 位元組，保留 365 天，執行安全係數為 2，且暫不計算額外的業務增長、備份和 副本：

例如，客戶每天產生 100 萬條日誌並儲存一年，可以先按 365 GB 資料盤規劃。如果預計 一年內日誌量增長 30%，則應調整為：

365 GB × 1.3 = 474.5 GB

實際採購時還應向上取整，並選擇能夠滿足持續寫入、後臺合併和查詢負載的 SSD。

# 測量實際每條日誌大小

建議先匯入至少 100 萬條有代表性的業務日誌，等待 ClickHouse 完成主要後臺合併， 然後查詢 system.parts。bytes_on_disk 包含活動資料 part 的壓縮列、索引和元資料， 適合用來估算實際磁碟佔用：

SELECT
    table,
    sum(rows) AS rows,
    formatReadableSize(sum(bytes_on_disk)) AS size_on_disk,
    round(sum(bytes_on_disk) / nullIf(sum(rows), 0), 2) AS bytes_per_row
FROM system.parts
WHERE database = 'app'
  AND active
  AND table IN (
      'nginx_http_access_logs',
      'nginx_stream_access_logs',
      'nginx_error_logs'
  )
GROUP BY table
ORDER BY table;

使用各表的 bytes_per_row 分別計算會更準確。例如不採集錯誤日誌時，不需要把 nginx_error_logs 計入容量。

統計最近 24 小時各類日誌條數：

SELECT 'http' AS type, count() AS rows
FROM nginx_http_access_logs
WHERE ingested_at >= now() - INTERVAL 1 DAY
UNION ALL
SELECT 'stream', count()
FROM nginx_stream_access_logs
WHERE ingested_at >= now() - INTERVAL 1 DAY
UNION ALL
SELECT 'error', count()
FROM nginx_error_logs
WHERE ingested_at >= now() - INTERVAL 1 DAY;

不要只選擇流量較低的日期。應統計業務高峰日，並結合促銷、攻擊流量和未來業務增長 確定每天日誌條數。執行一段時間後，定期重新測量並修正容量預測。

# 檢查磁碟空間

使用以下查詢檢視 ClickHouse 當前磁碟總量和剩餘空間：

SELECT
    name,
    path,
    formatReadableSize(total_space) AS total_space,
    formatReadableSize(free_space) AS free_space,
    round(free_space / total_space * 100, 2) AS free_percent
FROM system.disks;

建議在可用空間低於 30% 前告警並擴容，避免後臺合併或 TTL 清理因為空間不足而失敗。 clickhouse_logs 卷和備份空間需要單獨監控，不包含在 system.parts.bytes_on_disk 的 資料表容量中。

每臺 Edge Node 還需要為 Vector 磁碟緩衝區預留空間。採集全部三類日誌時，當前配置的 緩衝區上限合計為 5 GiB；建議為 /var/lib/vector-edge 至少預留 6 GiB。關閉錯誤 日誌採集後，可以扣除對應的 512 MiB 緩衝區，但仍應考慮 ClickHouse 暫時不可用時的 日誌積壓時間。

# 調整日誌保留時間

CLICKHOUSE_RETENTION_DAYS 必須是正整數。修改 ClickHouse 伺服器上的 .env 後， 重新執行一次初始化服務：

cd /opt/edge-clickhouse-deployment
sudo docker compose \
    --project-name clickhouse-deployment \
    --file docker-compose.yml \
    --file docker-compose.ports.yml \
    run --rm clickhouse-init

該操作會更新新表和現有日誌表的 TTL。ClickHouse 通過後臺合併刪除過期資料，因此 修改後不會立即釋放全部空間。

# 常見問題

# Vector 服務無法啟動

使用以下命令檢視最近的錯誤：

sudo journalctl -u vector-edge.service -n 100 --no-pager

重點檢查 ClickHouse 域名、HTTPS 埠、證書鏈、vector 密碼、系統時間以及 /etc/vector-edge/vector-edge.env 的許可權。該環境變數檔案應由 root 所有，許可權 為 0600。

如果日誌包含 certificate verify failed 或 unknown issuer，確認伺服器傳送的是 完整證書鏈，並檢查 Edge Node 是否信任簽發證書的 CA。不要關閉 verify_certificate 或 verify_hostname。

# Vector 報告 Permission denied

確認 vector 使用者對 /usr/local/oredge-node 有目錄遍歷許可權，對日誌目錄和現有日誌 有讀取許可權，並且目錄的預設 ACL 會覆蓋輪轉後新建的檔案。

# ClickHouse 中沒有訪問日誌

依次確認：

1. Edge 應用已使用配置後的 main 或預設的 vector-json 格式，並已釋出配置。
2. Edge Node 的當前日誌檔案有新內容，且每條記錄都是單行 JSON。
3. edge-vector-deployment/vector.yaml 中的檔名與 Edge Node 實際檔名一致。
4. Vector 日誌中沒有連線、認證、解析或緩衝區錯誤。
5. Edge Node 能夠透過 HTTPS 訪問 ClickHouse 域名和埠，且證書校驗成功。

# 只有當前日誌，沒有輪轉日誌

確認 Vector 的 include 同時包含當前日誌和下劃線字尾的輪轉日誌，並且輪轉檔案沒有 經過 Gzip 壓縮。Vector 會根據 /var/lib/vector-edge 中的檢查點避免在正常重啟後 重複讀取相同內容。

# 重新部署後出現重複記錄

不要刪除 /var/lib/vector-edge，否則 Vector 會丟失讀取檢查點並可能重新匯入歷史 日誌。ClickHouse 表使用 ReplacingMergeTree，相同排序鍵的記錄只能在後臺合併後 去重，不應以此代替 Vector 檢查點。

# 後續使用建議

• 日常查詢使用 oredge-reader 或為每個分析工具建立獨立的只讀賬號，不要使用 vector 寫入賬號。
• 日常運維可以使用容器內建的 clickhouse-client 查詢；需要圖形化瀏覽時，可使用 DBeaver；需要持續監控和告警時，可接入 Grafana 的 ClickHouse 資料來源。
• 查詢歷史日誌時新增時間範圍，避免無意掃描全部分割槽。
• 更改 ClickHouse 映象版本前先備份資料，並保留 clickhouse_data 外部卷。
• 監控伺服器證書的有效期。續期並替換證書檔案後，重啟 ClickHouse 容器並再次執行 HTTPS 連通性測試。

更多 TLS 配置項請參考 ClickHouse TLS 配置 和 Vector ClickHouse sink 配置。