文件 v1.0.0
首頁 GitHub

API 參考

本頁列出套件 golangIPSentry 所有匯出的函式、方法與型別，並標明哪些型別只供內部使用。

建立與釋放

函式 簽章 說明
New func New(c Config) (*IPGuardian, error) 套用 Log／Redis 預設、建立 Logger、連線並 PING Redis、建立三個名單管理器並載入名單檔、開啟 GeoLite2
IPGuardian.Close func (i *IPGuardian) Close() error 關閉 Redis、GeoLite2 與 Logger；Redis 關閉失敗時直接回傳錯誤，不再關閉其他資源

New 失敗情境：Logger 初始化失敗、Redis PING 失敗。名單檔與 GeoLite2 失敗只記錄，不會讓 New 失敗。

檢查與整合

方法 簽章 說明
IPGuardian.Check func (i *IPGuardian) Check(r *http.Request, w http.ResponseWriter) IPGuardianResult 完整判定流程，見 請求流程
IPGuardian.HTTPMiddleware func (i *IPGuardian) HTTPMiddleware(next http.Handler) http.Handler net/http 中介層
IPGuardian.GinMiddleware func (i *IPGuardian) GinMiddleware() gin.HandlerFunc Gin 中介層
IPGuardian.LoginFailure func (i *IPGuardian) LoginFailure(w http.ResponseWriter, r *http.Request) error 當前 Session 登入失敗數加 1
IPGuardian.NotFound404 func (i *IPGuardian) NotFound404(w http.ResponseWriter, r *http.Request) error 當前 Session 404 數加 1

名單管理

透過 IPGuardian.Manager（型別 Manager，欄位 Allow、Block、Deny）存取：

方法 簽章 說明
AllowIPManager.Add func (m *AllowIPManager) Add(ip string, tag string) error 寫入記憶體、Redis（無過期）、名單檔
AllowIPManager.Check func (m *AllowIPManager) Check(ip string) bool 先查 Redis，失敗或不存在再查記憶體
DenyIPManager.Add func (m *DenyIPManager) Add(ip, reason string) error 同 Allow，另外非同步寄送 Email
DenyIPManager.Check func (m *DenyIPManager) Check(ip string) bool 同 Allow
BlockIPManager.Add func (m *BlockIPManager) Add(ip string, reason string) error 暫時封鎖，重複呼叫時長倍增
BlockIPManager.IsBlock func (m *BlockIPManager) IsBlock(ip string) bool 是否處於封鎖期；Redis 錯誤回 false

AllowIPManager 與 DenyIPManager 的匯出欄位為 Logger、Config、Redis、Context、Mutex、Cache（map[string]*IPItem）；BlockIPManager 為 Logger、Config、Redis、Context。直接操作 Cache 須持有 Mutex。

主要型別

type IPGuardian struct {
    Context  context.Context
    Config   *Config
    Redis    *redis.Client
    Logger   *Logger
    GeoLite2 *GeoLite2
    Manager  *Manager
}

type IPGuardianResult struct {
    Success    bool   `json:"success"`
    StatusCode int    `json:"status_code"`
    Error      string `json:"error"`
}

type IPItem struct {
    IP      string `json:"ip"`
    Reason  string `json:"reason"`
    AddedAt int64  `json:"added_at"`
    Count   int    `json:"count,omitempty"`
    Last    int64  `json:"last,omitempty"`
}
型別 說明
Config、Redis、Filepath、EmailConfig 設定，見 設定
Parameter 門檻與分數，見 參數
Log goLogger.Log 的別名
Logger goLogger.Logger 的別名，IPGuardian.Logger 可直接用來寫日誌
IPItem 名單檔與 Redis 中每筆名單的格式；Count／Last 只在 Block 使用

內部使用的匯出型別

下列型別匯出但沒有任何公開函式回傳或接收，屬實作細節，版本間可能變動：

型別 用途
Device、IS、IP getDevice 解析出的裝置、名單狀態與 IP 資訊
ScoreItem 單次評分結果（IsBlock、IsSuspicious、IsDangerous、Flag、Score、Detail）
RiskScore 各維度累積的 Base 分數與 Detail
BasicItem calcBasic 的關聯集合設定（欄位皆未匯出）
ScoreTask、ScoreResult 目前未使用
GeoLite2 GeoLite2 讀取器與快取（IPGuardian.GeoLite2，停用時為 nil）
GeoLite2Config 目前未使用；路徑改由 Filepath 設定
Location GeoLite2 查詢結果（國家、城市、時區、經緯度、精度半徑）
EN