- 快猫星云Flashcat

夜鶯（Nightingale）設定檔的詳細說明

中心端 n9e 的設定檔是 etc/config.toml，邊緣告警引擎 n9e-edge 的設定檔是 etc/edge/edge.toml。這裡我們先分塊講解 n9e 的設定檔。

Global

[Global]
RunMode = "release"

這是夜鶯研發人員用的設定項，普通使用者不需要關心，永遠保持 release 即可。

Log

[Log]
# stdout, stderr, file
Output = "stdout"
# log write dir
Dir = "logs"
# log level: DEBUG INFO WARNING ERROR
Level = "DEBUG"
# # rotate by time
# KeepHours = 4
# # rotate by size
# RotateNum = 3
# # unit: MB
# RotateSize = 256

Output：日誌輸出方式，支援 stdout、stderr、file，只有在 file 模式下才會把日誌輸出到檔案，才會用到下面的其他設定項
Dir：日誌檔案的存放目錄
Level：日誌等級，支援 DEBUG、INFO、WARNING、ERROR
KeepHours：日誌檔案保留時間，單位小時。日誌既可以按照時間切分，也可以按照大小切分，如果按照時間切分，就用這個設定項，每小時一個日誌檔案，如果按照大小切分，就用下面兩個設定項
RotateNum：日誌檔案保留數量
RotateSize：日誌檔案大小，單位 MB

HTTP

[HTTP]
# http listening address
Host = "0.0.0.0"
# http listening port
Port = 17000
# https cert file path
CertFile = ""
# https key file path
KeyFile = ""
# whether print access log
PrintAccessLog = false
# whether enable pprof
PProf = true
# expose prometheus /metrics?
ExposeMetrics = true
# http graceful shutdown timeout, unit: s
ShutdownTimeout = 30
# max content length: 64M
MaxContentLength = 67108864
# http server read timeout, unit: s
ReadTimeout = 20
# http server write timeout, unit: s
WriteTimeout = 40
# http server idle timeout, unit: s
IdleTimeout = 120

Host：HTTP 服務監聽位址，一般都是 0.0.0.0，表示監聽所有網路卡
Port：HTTP 服務監聽連接埠
CertFile：HTTPS cert 檔案路徑
KeyFile：HTTPS key 檔案路徑
PrintAccessLog：是否列印存取日誌
PProf：是否開啟 pprof，如果開啟的話，在 /api/debug/pprof/ 下可以看到 pprof 的資訊
ExposeMetrics：是否暴露 Prometheus 的 /metrics 介面，用於暴露夜鶯自身的監控指標
ShutdownTimeout：HTTP 服務優雅關閉逾時時間，單位秒
MaxContentLength：HTTP 請求最大長度，單位位元組
ReadTimeout：HTTP 讀取逾時時間，單位秒
WriteTimeout：HTTP 寫入逾時時間，單位秒
IdleTimeout：HTTP 閒置逾時時間，單位秒

HTTP.ShowCaptcha

[HTTP.ShowCaptcha]
Enable = false

Enable：是否開啟驗證碼功能

HTTP.APIForAgent

[HTTP.APIForAgent]
Enable = true
# [HTTP.APIForAgent.BasicAuth]
# user001 = "ccc26da7b9aba533cbb263a36c07dcc5"

Enable：是否開啟 Agent 的 API 介面，正常來講必然是要開啟的，所以這個設定項一般都是 true
BasicAuth：Agent 的 API 介面支援 BasicAuth，這裡設定 BasicAuth 使用者名稱和密碼，一般內網通訊的話，不需要設定 BasicAuth，如果是公網通訊的話，建議設定 BasicAuth，而且，密碼一定不要使用預設的，容易被攻擊
上例中 user001 是 BasicAuth 的使用者名稱，ccc26da7b9aba533cbb263a36c07dcc5 BasicAuth 的密碼，如果想要設定多個使用者，可以繼續新增，比如：

[HTTP.APIForAgent.BasicAuth]
user001 = "ccc26da7b9aba533cbb263a36c07dcc5"
user002 = "d4f5e6a7b8c9d0e1f2g3h4i5j6k7l8m9"

注意：如果你設定了 BasicAuth，那麼 Agent 端的 n9e 設定檔中也需要設定相應的使用者名稱和密碼，否則 Agent 端無法連線到中心 n9e。

預設設定裡 Enable 設定為 true，HTTP.APIForAgent.BasicAuth 為空，表示啟用面向 Agent 的那些 API 介面，同時不啟用 BasicAuth。

HTTP.APIForService

[HTTP.APIForService]
Enable = false
[HTTP.APIForService.BasicAuth]
user001 = "ccc26da7b9aba533cbb263a36c07dcc5"

Enable：是否開啟 Service 的 API 介面，邊緣告警引擎 n9e-edge 和中心 n9e 通訊就相依中心端的這部分介面，所以如果你用到了 n9e-edge，就需要啟用，即設定為 true
BasicAuth：Service 的 API 介面支援 BasicAuth，這裡設定 BasicAuth 使用者名稱和密碼，一般內網通訊的話，不需要設定 BasicAuth，如果是公網通訊的話，建議設定 BasicAuth，而且，密碼一定一定不要使用預設的，容易被攻擊
上例中 user001 是 BasicAuth 的使用者名稱，ccc26da7b9aba533cbb263a36c07dcc5 BasicAuth 的密碼，如果想要設定多個使用者，可以繼續新增，比如：

[HTTP.APIForService.BasicAuth]
user001 = "ccc26da7b9aba533cbb263a36c07dcc5"
user002 = "d4f5e6a7b8c9d0e1f2g3h4i5j6k7l8m9"

注意：如果你設定了 BasicAuth，那麼邊緣告警引擎 n9e-edge 的設定檔中也需要設定相應的使用者名稱和密碼，否則 n9e-edge 無法連線到中心 n9e。預設設定裡 Enable 設定為 false，表示不啟用面向其他 Service 的那些 API 介面，此時 n9e-edge 也無法連線到中心 n9e。

HTTP.JWTAuth

[HTTP.JWTAuth]
# unit: min
AccessExpired = 1500
# unit: min
RefreshExpired = 10080
RedisKeyPrefix = "/jwt/"

夜鶯的認證使用 jwt 的方式，這裡設定 jwt 的過期時間，單位分鐘，AccessExpired 是 access token 的過期時間，RefreshExpired 是 refresh token 的過期時間。jwt 機制下這兩個 token 的作用可以問一下 GPT，這裡不再贅述。夜鶯會把部分 jwt 相關的資訊存到 redis 中，RedisKeyPrefix 是 redis 的 key 字首，一般不用改。

HTTP.ProxyAuth

[HTTP.ProxyAuth]
# if proxy auth enabled, jwt auth is disabled
Enable = false
# username key in http proxy header
HeaderUserNameKey = "X-User-Name"
DefaultRoles = ["Standard"]

如果你想把夜鶯嵌入到你自己的系統中，可以考慮使用 ProxyAuth 方式，類似 Grafana 的 ProxyAuth。相當於使用者在你自己的系統中登入，你可以拿到使用者名稱，然後把使用者名稱放到 X-User-Name 這個 Header 中傳給夜鶯，夜鶯就會認為這個使用者已經登入了。DefaultRoles 是預設角色，如果你不傳角色，夜鶯就會把這個使用者當做 Standard 角色處理。

實際上據我觀察，目前並沒有社群使用者使用這個功能，所以請慎重使用。

HTTP.RSA

[HTTP.RSA]
OpenRSA = false

夜鶯在登入的時候，使用者密碼是明文傳輸的，如果夜鶯站點是 HTTPS 的倒是還好，如果是 HTTP 的，就建議開啟 RSA 加密，這樣使用者密碼就不會明文傳輸了。

DB

[DB]
# mysql postgres sqlite
DBType = "sqlite"
# postgres: host=%s port=%s user=%s dbname=%s password=%s sslmode=%s
# postgres: DSN="host=127.0.0.1 port=5432 user=root dbname=n9e_v6 password=1234 sslmode=disable"
# mysql: DSN="root:1234@tcp(localhost:3306)/n9e_v6?charset=utf8mb4&parseTime=True&loc=Local"
DSN = "n9e.db"
# enable debug mode or not
Debug = false
# unit: s
MaxLifetime = 7200
# max open connections
MaxOpenConns = 32
# max idle connections
MaxIdleConns = 8

DBType 和 DSN 是最為關鍵的，兩個設定聯動。DBType 支援 mysql、postgres、sqlite 三種資料庫，DSN 是資料庫連線資訊，如果是 sqlite，就是資料庫檔案路徑，如果是 mysql 或 postgres，就是資料庫連線資訊。

夜鶯從 v8 版本開始，預設 DBType 設定的是 sqlite，這樣方便使用者快速體驗，不需要安裝資料庫。但是，生產環境中，還請使用 mysql 或 postgres。

Postgres 和 MySQL 的 DSN 設定可以參考註解中的範例。其他設定是資料庫連線相關的設定，根據自己的環境來修改即可。一般中小型環境，MaxOpenConns 設定為 32，MaxIdleConns 設定為 8 就可以了。

Redis

[Redis]
# standalone cluster sentinel miniredis
RedisType = "miniredis"
# address, ip:port or ip1:port,ip2:port for cluster and sentinel(SentinelAddrs)
Address = "127.0.0.1:6379"
# Username = ""
# Password = ""
# DB = 0
# UseTLS = false
# TLSMinVersion = "1.2"
# Mastername for sentinel type
# MasterName = "mymaster"
# SentinelUsername = ""
# SentinelPassword = ""

Redis 除了用於儲存 jwt 相關的登入認證資訊，還用於存放機器的心跳上報的 metadata。夜鶯中支援的機器失聯告警規則，就是根據 Redis 中機器的心跳時間來判斷的，如果很長時間沒有心跳了，就認為機器失聯了。

如果 Redis 回應較慢，可能會導致失聯告警的誤判。即機器明明是存活的，但是 Redis 中的心跳資訊沒有及時更新，最終導致夜鶯誤判機器失聯了。V8.beta11 版本開始，增加了 Redis 操作相關的監控指標，需要關注這些指標，及時發現 Redis 回應慢的問題。

RedisType 支援 standalone、cluster、sentinel、miniredis 四種，從夜鶯 v8 版本開始，夜鶯預設使用 miniredis，這樣方便使用者快速體驗，不需要安裝 Redis。但是，生產環境中，還請使用其他模式。

Address 是 Redis 的連線位址，根據 RedisType 的不同，設定方式也不同：

standalone：RedisType 是 standalone 時，Address 就是 Redis 實例的位址，格式是 ip:port
cluster：RedisType 是 cluster 時，Address 就是 Redis 叢集的位址，格式是 ip1:port,ip2:port
sentinel：RedisType 是 sentinel 時，Address 就是 Redis Sentinel 的位址，格式是 ip1:port,ip2:port，哨兵模式下，還需要設定 MasterName、SentinelUsername、SentinelPassword
UseTLS：是否使用 TLS
TLSMinVersion：TLS 最低版本，只有在 UseTLS 為 true 時才生效

Alert

夜鶯從某個版本開始，為了降低部署複雜度，把 webapi 和告警引擎模組合並在一起了，Alert 這裡的設定項是告警引擎的設定項。

Alert.Heartbeat

[Alert.Heartbeat]
# auto detect if blank
IP = ""
# unit ms
Interval = 1000
EngineName = "default"

IP：告警引擎的 IP 位址，如果是空的話，夜鶯會自動探測。每個告警引擎都會寫心跳資訊到 MySQL，這樣一來，每個告警引擎都知道所有活著的告警引擎列表，進而就可以做告警規則的分片處理了。比如有 100 條告警規則，有兩個 n9e 組成叢集，那麼每個 n9e 大概會處理 50 條告警規則，當其中一個告警引擎掛掉的時候，另一個告警引擎就會接管這 100 條告警規則。
Interval：心跳間隔，單位毫秒
EngineName：告警引擎的名稱，一般中心端就維持 default 即可，邊緣告警引擎 n9e-edge 的話，可以自訂 EngineName，比如 edge1、edge2 等。相同 EngineName 的告警引擎會被認為是一個叢集。

Center

中心端 n9e 的特有設定，邊緣告警引擎 n9e-edge 沒有這些設定項。即老版本的 n9e-webapi 相關的特有的設定。

[Center]
MetricsYamlFile = "./etc/metrics.yaml"
I18NHeaderKey = "X-Language"

[Center.AnonymousAccess]
PromQuerier = true
AlertDetail = true

MetricsYamlFile：指標設定檔路徑，你在快捷檢視裡看到的指標的解釋說明就是來自這個設定檔。後來上線了指標檢視，這個設定檔就不那麼重要了，甚至後面計劃下掉快捷檢視的功能。
I18NHeader：這是一個研發人員用的設定項，普通使用者不需要關心。
Center.AnonymousAccess：匿名存取相關的設定項。PromQuerier 是指是否允許匿名查詢各資料來源的介面，AlertDetail 是指是否允許匿名檢視告警詳情。內網環境可以開啟，公網環境一定要關閉。

儀表板有個公開存取的功能，甚至可以設定為不需要登入就可以存取，但是這個前提是 PromQuerier 需要設定為 true，即如果 PromQuerier = false，那麼即使設定了儀表板為公開存取，也是需要登入的。

Pushgw

夜鶯雖然不直接儲存監控資料，但是提供了多種接收監控資料的介面，比如 Prometheus remote write 協定的介面、OpenTSDB 協定的介面等。接收到資料之後，夜鶯會把監控資料轉發給後端時序庫，所以這裡夜鶯就相當於一個 Pushgateway，跟 Pushgateway 相關的設定項就在 Pushgw 下面了。

[Pushgw]
# use target labels in database instead of in series
LabelRewrite = true
ForceUseServerTS = true

LabelRewrite：夜鶯有個機器管理的選單，可以給機器打標籤，並且這些標籤會附加到機器相關的時序資料裡。但是，如果上報的資料中有個標籤和機器管理裡的標籤衝突了，以哪個為準呢？如果 LabelRewrite 為 true，就以機器管理裡的標籤為準，否則以上報的標籤為準。
ForceUseServerTS：是否強制使用伺服器端的時間戳記，來覆蓋接收到的監控資料的時間戳記。之前沒有這個設定項，由於很多公司的機器時間沒有校準導致各種困惑，所以夜鶯提供了這個設定，建議開啟，統一使用伺服器端的時間戳記得了。

Pushgw.DebugSample

[Pushgw.DebugSample]
ident = "xx"
__name__ = "cpu_usage_active"

這個設定是為了除錯、排查問題用的。這個設定其實是一個監控指標的篩選條件，如果上報給夜鶯的指標符合這個篩選條件，就會列印到日誌中。一般不需要設定，註解掉即可。

Pushgw.WriterOpt

[Pushgw.WriterOpt]
QueueMaxSize = 1000000
QueuePopSize = 1000
QueueNumber = 0

這部分設定預設是註解的，因為正常來講，使用者是不需要關注的，如果夜鶯接收到太多資料，在記憶體裡擁塞了，最終丟了指標，此時需要考慮調整這裡的設定。

夜鶯會在記憶體裡建立 QueueNumber 個佇列，收到監控資料之後，就會把資料放到這些佇列中，QueueNumber 的預設設定是 0，表示不指定具體數量，按照 CPU 核心數來建立佇列。每個佇列的最大容量是 QueueMaxSize，預設是 1000000，表示每個佇列最多可以儲存 100 萬條資料。

然後每個佇列對應一個 goroutine，這個 goroutine 每次從佇列中取出指標的數量是 QueuePopSize，預設是 1000，表示每次從佇列中取出 1000 條資料，作為一個批次寫入到後端時序庫。這樣做的好處是可以充分利用多核 CPU 的效能。所以，QueueNumber 的數量，本質就等於並行寫入後端時序庫的並行量。

Pushgw.Writers

這裡是設定後端時序庫的 remote write 寫入位址，所有支援 remote write 協定的時序庫都可以設定在這裡。一般來講，只需要設定一個即可，如果你想同時寫入多個時序庫，可以設定多個。

[[Pushgw.Writers]]
Url = "http://127.0.0.1:9090/api/v1/write"
BasicAuthUser = "xx"
BasicAuthPass = "xx"

[[Pushgw.Writers]]
Url = "http://127.0.0.1:8482/api/v1/write"
BasicAuthUser = "xx"
BasicAuthPass = "xx"

Url：時序庫的 remote write 寫入位址
BasicAuth：如果時序庫需要 BasicAuth 認證，可以設定 BasicAuth 的使用者名稱和密碼
Headers：如果時序庫需要額外的 Header，可以設定在這裡
Timeout：寫入逾時時間，單位是毫秒
DialTimeout：連線逾時時間，單位是毫秒

Pushgw.Writers.WriteRelabels

寫往時序庫的資料，在寫入之前可以做 relabel 的操作，這個設定項就是 relabel 的設定項。和 Prometheus 的 relabel 設定項類似，只不過 Prometheus 用的 yaml 格式，夜鶯用的 toml 格式。

Ibex

故障自愈引擎 Ibex 的設定項。即遠端執行指令碼的那個功能。原本這個功能是單獨拆開的一個模組叫 ibex，後來合併到 n9e 裡了，所以這個設定項也在 n9e 裡。

[Ibex]
Enable = true
RPCListen = "0.0.0.0:20090"

Enable：是否開啟 Ibex 伺服器端功能
RPCListen：Ibex 的 RPC 服務監聽位址

n9e-edge 的設定

邊緣告警引擎 n9e-edge 的設定檔是 etc/edge/edge.toml，大部分設定和中心 n9e 的設定相同。更多資訊可以參考這篇文章：《夜鶯架構中的邊緣模式說明》。