Zum Inhalt

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

Installation

Wenn Sie noch kein RPM-Repository-Abonnement eingerichtet haben, melden Sie sich an. Danach 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.1, das am 19. November 2025 veröffentlicht wurde.

neueste Version neueste luarocks-Version Master-Branch Lizenz Twitter folgen

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 von aktiven und passiven 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 gesendet.

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 Changelog unten (PRs sollten zusammen mit einem Changelog-Eintrag zusammengeführt werden)
  • Bestimmen Sie basierend auf dem Changelog die neue SemVer-Version
  • Erstellen Sie eine neue Rockspec
  • Rendern Sie die Dokumente 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.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 der Versionsprüfung von resty.events #162

3.0.2 (16-Mai-2024)

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

3.0.1 (22-Dez-2023)

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

3.0.0 (12-Okt-2023)

  • Perf: Optimierung 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 Changelog, 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 Veröffentlichung 3.0.0 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 Abhängigkeit lua-resty-worker-events 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 korrekt protokollieren, indem Tail-Calls verwendet werden #29
  • Fix: Verwenden Sie die IP, wenn kein Hostname angegeben ist #48
  • Fix: Makefile; make install
  • Feature: Ein Statusversionsfeld hinzugefügt #54
  • Feature: Header für die Probeanforderung hinzugefügt #54
  • Fix: Frühzeitig beenden, wenn während einer Probe neu geladen wird #47
  • Fix: Verhindern, dass die Ziel-Liste nil ist, aufgrund asynchronen Verhaltens #44
  • Fix: Ersetzen Sie Timer und node-weite Locks durch resty-timer, um Intervallüberspringen zu verhindern #59
  • Änderung: Zusätzliche Protokollierung beim Posten von Ereignissen hinzugefügt #25
  • Fix: Während der Initialisierung/Init_Worker keine Timer ausführen, 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: Vermeiden 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 beim Hinzufügen zurück. #122

1.6.1 (25-Jul-2022)

  • Fix: Verbesserungen zur Sicherstellung der ordnungsgemäßen Sicherung von gemeinsam genutzten Ressourcen, um Rennbedingungen 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: Akzeptiere jede lua-resty-events 0.1.x Veröffentlichung. #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's 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: Vermeiden 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 beim Hinzufügen zurück. #121

1.5.2 (07-Jul-2022)

  • Bessere Handhabung von resty.lock-Fehlermodi, Hinzufügen weiterer Überprüfungen, um sicherzustellen, dass das Lock gehalten wird, bevor kritischer Code ausgeführt 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 Fehler bei gesperrten Funktionen. #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: Vermeiden 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, wobei ihr Gesundheitsstatus beibehalten wird. #88

1.4.3 (31-Mar-2022)

  • Fix: Vermeiden 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 das Kong-Problem #7406

1.4.1 (17-Feb-2021)

  • Fix: Stellen Sie sicher, dass ein einzelner Worker aktiv die Status der 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 entsprechend 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-Dez-2019)

  • Fix: Wenn die ngx.sleep-API nicht verfügbar ist (z.B. in der Log-Phase), 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 Retry-Methode 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 es nicht möglich ist, exklusiven Zugriff auf die Liste der Ziele zu erhalten. 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: Protokollieren Sie Fehler beim SSL-Handshake #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-Probe-Erfolge #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 das 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-Mai-2018)

  • Fix: Host-Header in aktiven Healthchecks

0.4.1 (21-Mai-2018)

  • Fix: Interne Verwaltung der Healthcheck-Zähler

0.4.0 (20-Mar-2018)

  • Korrekte Festlegung der Standardwerte in http_statuses
  • Typ- und Grenzüberprüfung der checks-Tabelle

0.3.0 (18-Dez-2017)

  • Deaktivieren Sie einzelne Checks, indem Sie ihre 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.