Zum Inhalt

healthcheck: Healthcheck-Bibliothek für nginx-module-lua zur Validierung des Status von Upstream-Diensten

Installation

Wenn Sie das RPM-Repository-Abonnement noch nicht eingerichtet haben, melden Sie sich an. Dann können Sie mit den folgenden Schritten fortfahren.

CentOS/RHEL 7 oder Amazon Linux 2

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install lua-resty-healthcheck

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install lua5.1-resty-healthcheck

Um diese Lua-Bibliothek mit NGINX zu verwenden, stellen Sie sicher, dass nginx-module-lua installiert ist.

Dieses Dokument beschreibt lua-resty-healthcheck v3.1.2, das am 09. April 2026 veröffentlicht wurde.

neueste Version neueste luarocks Version master branch Lizenz Twitter Follow

Eine Healthcheck-Bibliothek für OpenResty.

Synopsis

http {
    lua_shared_dict test_shm 8m;
    lua_shared_dict my_worker_events 8m;
    init_worker_by_lua_block {

        local we = require "resty.worker.events"
        local ok, err = we.configure({
            shm = "my_worker_events",
            interval = 0.1
        })
        if not ok then
            ngx.log(ngx.ERR, "Fehler bei der Konfiguration der Worker-Events: ", err)
            return
        end

        local healthcheck = require("resty.healthcheck")
        local checker = healthcheck.new({
            name = "testing",
            shm_name = "test_shm",
            checks = {
                active = {
                    type = "https",
                    http_path = "/status",
                    healthy  = {
                        interval = 2,
                        successes = 1,
                    },
                    unhealthy  = {
                        interval = 1,
                        http_failures = 2,
                    }
                },
            }
        })

        local ok, err = checker:add_target("127.0.0.1", 8080, "example.com", false)

        local handler = function(target, eventname, sourcename, pid)
            ngx.log(ngx.DEBUG,"Ereignis von: ", sourcename)
            if eventname == checker.events.remove
                -- ein Ziel wurde entfernt
                ngx.log(ngx.DEBUG,"Ziel entfernt: ",
                    target.ip, ":", target.port, " ", target.hostname)
            elseif eventname == checker.events.healthy
                -- Ziel hat den Status geändert oder wurde hinzugefügt
                ngx.log(ngx.DEBUG,"Ziel auf gesund gewechselt: ",
                    target.ip, ":", target.port, " ", target.hostname)
            elseif eventname ==  checker.events.unhealthy
                -- Ziel hat den Status geändert oder wurde hinzugefügt
                ngx.log(ngx.DEBUG,"Ziel auf ungesund gewechselt: ",
                    target.ip, ":", target.port, " ", target.hostname)
            else
                -- unbekanntes Ereignis
            end
        end
    }
}

Beschreibung

Diese Bibliothek unterstützt die Durchführung aktiver und passiver Healthchecks auf beliebigen Hosts.

Die Steuerung der Bibliothek erfolgt über ihre programmgesteuerte API. Der Empfang ihrer Ereignisse erfolgt über die lua-resty-worker-events Bibliothek.

Ziele werden mit checker:add_target(host, port) hinzugefügt. Änderungen im Status ("gesund" oder "ungesund") werden über Worker-Events verbreitet.

Aktive Checks werden im Hintergrund basierend auf den angegebenen Timer-Intervallen ausgeführt.

Für passive Healthchecks erhält die Bibliothek explizite Benachrichtigungen über ihre programmgesteuerte API mit Funktionen wie checker:report_http_status(host, port, status).

Siehe die online LDoc-Dokumentation für die vollständige API.

Geschichte

Die Versionierung basiert strikt auf Semantic Versioning

Veröffentlichung neuer Versionen:

  • Aktualisieren Sie das Änderungsprotokoll unten (PRs sollten zusammen mit einem Änderungsprotokolleintrag zusammengeführt werden)
  • Bestimmen Sie basierend auf dem Änderungsprotokoll die neue SemVer-Version
  • Erstellen Sie eine neue Rockspec
  • Rendern Sie die Dokumentation mit ldoc (tun Sie dies nicht innerhalb von PRs)
  • Committen Sie als "release x.x.x" (Rockspec-Revision nicht einbeziehen)
  • Taggen Sie den Commit mit "x.x.x" (Rockspec-Revision nicht einbeziehen)
  • Pushen Sie Commit und Tag
  • Laden Sie den Rock zu luarocks hoch: luarocks upload rockspecs/[name] --api-key=abc

3.1.2 (09-Apr-2026)

  • Fix(active-checks): Verwenden Sie HTTP/1.1 für Healthcheck-Proben mit automatischer Versionsverhandlung #176

3.1.1 (19-Nov-2025)

  • Fix: Ändern Sie die Standard-Header in eine leere Tabelle anstelle eines Arrays, um die Abwertungsbenachrichtigung zu entfernen #174

3.1.0 (19-Jun-2024)

  • Feat: Entfernen Sie die Versionsprüfung von resty.events #162

3.0.2 (16-May-2024)

  • Fix: Vermeiden Sie die Erstellung mehrerer Timer, um denselben aktiven Check auszuführen #157

3.0.1 (22-Dec-2023)

  • Fix: Beheben Sie die Verzögerungsbereinigung, wenn mehrere Healthchecker gestartet wurden #146

3.0.0 (12-Oct-2023)

  • Perf: Optimieren durch Lokalisierung einiger Funktionen #92 (Backport)
  • Fix: Generieren Sie frische Standard-http_statuses innerhalb von new() #83 (Backport)

2.0.0 (22-Sep-2020)

Hinweis: Änderungen in dieser Version wurden von der aktuellen und zukünftigen Entwicklung verworfen. Unten sehen Sie das Änderungsprotokoll, aber beachten Sie, dass diese Änderungen möglicherweise nicht in 3.y.z vorhanden sind, es sei denn, sie sind ausdrücklich in 3.y.z, 1.6.3 oder früheren Versionen angegeben. Lesen Sie mehr unter: release 3.0.0 (#142) und chore(*): Master-Branch auf die 3.0.0-Version ausrichten (#144)

  • BREAKING: Fallback für das abgewertete Top-Level-Feld type wurde jetzt entfernt (abgewertet seit 0.5.0) #56
  • BREAKING: Erhöhen Sie die lua-resty-worker-events-Abhängigkeit auf 2.0.0. Dies macht viele der APIs in dieser Bibliothek asynchron, da die Worker-Events post und post_local nicht mehr automatisch poll auf einem laufenden Worker aufrufen. Für weitere Informationen siehe: https://github.com/Kong/lua-resty-worker-events#200-16-september-2020
  • BREAKING: tcp_failures können bei http(s)-Checks nicht mehr 0 sein (es sei denn, http(s)_failures sind ebenfalls auf 0 gesetzt) #55
  • Feature: Unterstützung für https_sni hinzugefügt #49
  • Fix: Zeilennummern ordnungsgemäß protokollieren, indem Tail-Calls verwendet werden #29
  • Fix: Verwenden Sie IP, wenn kein Hostname angegeben ist #48
  • Fix: Makefile; make install
  • Feature: Hinzufügen eines Statusversionsfeldes #54
  • Feature: Header für die Probeanforderung hinzufügen #54
  • Fix: Frühzeitiger Ausstieg beim Neuladen während einer Probe #47
  • Fix: Verhindern, dass die Ziel-Liste nil ist, aufgrund asynchronen Verhaltens #44
  • Fix: Timer und node-weite Locks durch resty-timer ersetzen, um Intervallüberspringen zu verhindern #59
  • Änderung: Zusätzliche Protokollierung beim Posten von Ereignissen hinzugefügt #25
  • Fix: Während der Initialisierung/Init_Worker nicht ohne Timer auslaufen, wenn eine große Anzahl von Zielen hinzugefügt wird #57
  • Fix: Nicht auf der Modultabelle aufrufen, sondern eine Methode für Locks verwenden. Auch in #57

1.6.3 (06-Sep-2023)

  • Feature: Unterstützung für https_sni hinzugefügt #49 (Backport)
  • Fix: Verwenden Sie die OpenResty-API für mTLS #99 (Backport)

1.6.2 (17-Nov-2022)

  • Fix: Verhindern Sie das Auslösen von Worker-Events für neue Ziele, die zur verzögerten Entfernung markiert wurden, d.h. Ziele, die bereits im Speicher existieren, benötigen nur das Entfernen-Flag, wenn sie wieder hinzugefügt werden. #122

1.6.1 (25-Jul-2022)

  • Fix: Verbesserungen zur Sicherstellung der ordnungsgemäßen Sicherung gemeinsamer Ressourcen, um Wettlaufbedingungen zu vermeiden und Fehlerzustände klar zu melden. #112, #113, #114.
  • Fix: Reduzierung der Häufigkeit der Überprüfung auf ungenutzte Ziele, wodurch die Anzahl der erstellten Locks verringert wird. #116
  • Fix: Akzeptieren Sie jede lua-resty-events 0.1.x-Version. #118

1.6.0 (27-Jun-2022)

  • Feature: Einführung der Unterstützung für das lua-resty-events Modul zusätzlich zur Unterstützung von lua-resty-worker-events. Mit dieser Ergänzung benötigt das lua-resty-healthcheck luarocks-Paket kein spezifisches Event-Sharing-Modul mehr, aber Sie müssen weiterhin entweder lua-resty-worker-events oder lua-resty-events bereitstellen. #105
  • Änderung: Wenn verfügbar, verwendet lua-resty-healthcheck jetzt string.buffer, die neue LuaJIT-Serialisierungs-API. Wenn es nicht verfügbar ist, fällt lua-resty-healthcheck auf cjson zurück. #109

1.5.3 (14-Nov-2022)

  • Fix: Verhindern Sie das Auslösen von Worker-Events für neue Ziele, die zur verzögerten Entfernung markiert wurden, d.h. Ziele, die bereits im Speicher existieren, benötigen nur das Entfernen-Flag, wenn sie wieder hinzugefügt werden. #121

1.5.2 (07-Jul-2022)

  • Bessere Handhabung von resty.lock-Fehlermodi, Hinzufügen weiterer Überprüfungen, um sicherzustellen, dass das Lock vor dem Ausführen kritischer Codes gehalten wird, und Verbesserung der Entscheidung, ob eine Funktion nach einem Timeout beim Versuch, ein Lock zu erwerben, erneut versucht werden sollte. #113
  • Erhöhte Protokollierung für gesperrte Funktionsfehler. #114
  • Die Bereinigungsfrequenz für gelöschte Ziele wurde gesenkt, wodurch die Anzahl der in kurzer Zeit erstellten Locks verringert wurde. #116

1.5.1 (23-Mar-2022)

  • Fix: Verhindern Sie, dass aktive Healthchecks unterbrochen werden, wenn Ziele hinzugefügt oder entfernt werden. #93

1.5.0 (09-Feb-2022)

  • Neue Option checks.active.headers unterstützt eine oder mehrere Listen von Werten, die nach Headernamen indiziert sind. #87
  • Einführung der Funktion dealyed_clear(), die verwendet wird, um Adressen nach einem Zeitintervall zu entfernen. Diese Funktion kann verwendet werden, wenn eine Adresse entfernt wird, aber möglicherweise vor Ablauf des Intervalls erneut hinzugefügt wird, um ihren Gesundheitsstatus beizubehalten. #88

1.4.3 (31-Mar-2022)

  • Fix: Verhindern Sie, dass aktive Healthchecks unterbrochen werden, wenn Ziele hinzugefügt oder entfernt werden. #100

1.4.2 (29-Jun-2021)

  • Fix: Verhindern Sie, dass neue aktive Checks geplant werden, während ein Healthcheck läuft. #72
  • Fix: Entfernen Sie den Ereignisbeobachter, wenn ein aktiver Healthcheck gestoppt wird. #74; behebt Kong-Problem #7406

1.4.1 (17-Feb-2021)

  • Fix: Stellen Sie sicher, dass ein einzelner Worker aktiv die Status von Hosts überprüft. #67

1.4.0 (07-Jan-2021)

  • Verwenden Sie einen einzelnen Timer, um aktiv die Ziele zu überprüfen. Dies reduziert die Anzahl der von Healthcheckern verwendeten Timer, da sie zuvor zwei Timer für jedes Ziel verwendeten. #62

1.3.0 (17-Jun-2020)

  • Fügt Unterstützung für mTLS zu aktiven Healthchecks hinzu. Dieses Feature kann verwendet werden, indem die Felder ssl_cert und ssl_key mit Zertifikat und Schlüssel beim Erstellen eines neuen Healthcheck-Objekts hinzugefügt werden. #41

1.2.0 (13-Feb-2020)

  • Fügt set_all_target_statuses_for_hostname hinzu, das die Ziele für alle Einträge mit einem bestimmten Hostnamen auf einmal festlegt.

1.1.2 (19-Dec-2019)

  • Fix: Wenn die ngx.sleep-API nicht verfügbar ist (z.B. in der Protokollphase), ist es nicht möglich, mit lua-resty-lock zu sperren, und jede Funktion, die exklusiven Zugriff benötigt, würde fehlschlagen. Dieser Fix fügt eine Wiederholungsmethode hinzu, die einen neuen leichten Thread startet, der Zugriff auf ngx.sleep hat, um den kritischen Pfad zu sperren. #37;

1.1.1 (14-Nov-2019)

  • Fix: Fehler, wenn kein exklusiver Zugriff auf die Liste der Ziele möglich ist. Dieser Fix verhindert, dass Worker in einen inkonsistenten Zustand gelangen. #34;

1.1.0 (30-Sep-2019)

  • Fügen Sie Unterstützung für das Setzen des benutzerdefinierten Host-Headers hinzu, der für aktive Checks verwendet werden soll.
  • Fix: Protokollfehler bei SSL-Handshake-Fehlern #28;

1.0.0 (05-Jul-2019)

  • BREAKING: Alle API-Funktionen, die sich auf Hosts beziehen, erfordern jetzt ein hostname-Argument. Auf diese Weise haben unterschiedliche Hostnamen, die auf derselben IP- und Portkombination lauschen, keinen Einfluss aufeinander.
  • Fix: Beheben Sie die Berichterstattung über aktive TCP-Probeerfolge #20; behebt das Problem #19

0.6.1 (04-Apr-2019)

  • Fix: Richten Sie den Ereignis-Callback erst ein, nachdem die Ziel-Liste geladen ist #18; behebt Kong-Problem #4453

0.6.0 (26-Sep-2018)

  • Einführung des Feldes checks.active.https_verify_certificate. Es ist standardmäßig true; das Setzen auf false deaktiviert die Zertifikatsüberprüfung bei aktiven Healthchecks über HTTPS.

0.5.0 (25-Jul-2018)

  • Fügen Sie Unterstützung für https hinzu – danke @gaetanfl für den PR!
  • Einführung separater Felder checks.active.type und checks.passive.type; das Top-Level-Feld type wird weiterhin als Fallback unterstützt, ist jedoch jetzt abgewertet.

0.4.2 (23-May-2018)

  • Fix: Host-Header in aktiven Healthchecks

0.4.1 (21-May-2018)

  • Fix: Interne Verwaltung der Healthcheck-Zähler

0.4.0 (20-Mar-2018)

  • Korrekte Festlegung der Standardwerte in http_statuses
  • Typ- und Bereichsprüfung für die checks-Tabelle

0.3.0 (18-Dec-2017)

  • Deaktivieren Sie einzelne Checks, indem Sie deren Zähler auf 0 setzen

0.2.0 (30-Nov-2017)

  • Fügt set_target_status hinzu

0.1.0 (27-Nov-2017) Erste Veröffentlichung

  • Erste Hochladung

GitHub

Sie finden möglicherweise zusätzliche Konfigurationstipps und Dokumentationen für dieses Modul im GitHub-Repository für nginx-module-healthcheck.