Mirror Uptime Kuma's maintenance schedule as maintenance windows

Uptime Kuma shares its maintenance windows only over its dashboard Socket.IO
connection, which takes a login. With a login username and password on the
integration, "Sync schedule" on the Maintenance page (and a 15-minute
background pass when switched on) reads each window's running and next time
slot and the monitors it covers, and makes a maintenance window on every
server those monitors match. Windows that haven't started are listed as
Scheduled and silence nothing until they begin; ones ended or cancelled by
hand stay ended, and ones removed in Kuma are removed here.

maintenance_windows gets a source column (migration 0017) and active windows
now require their start to have passed. Adds socket.io-client, and tests
against a stand-in Uptime Kuma speaking the same protocol.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-11 23:43:47 +02:00
1 parent 5e416b0273
commit 9e483f2163
21 files changed
+3259 -31

No files matched your search

+27 -4
View File
@@ -74,10 +74,33 @@ the dashboard views themselves load fine.
with no single network target (groups, push monitors, keyword checks with a complex URL) are shown
unmatched rather than guessed at. Uptime Kuma's tags aren't read, since the metrics endpoint doesn't
reliably distinguish a tag from any other label.
- **Maintenance import:** the Maintenance page can read which monitors are currently in maintenance in Uptime
Kuma and start (or extend) a maintenance window here for the matching server, for a duration you pick — the
metrics endpoint only exposes current status, not a monitor's scheduled start/end time, so this reflects
what's in maintenance right now rather than mirroring Uptime Kuma's own schedule.
- **Maintenance import ("Import now"):** the Maintenance page can read which monitors are currently in
maintenance in Uptime Kuma and start (or extend) a maintenance window here for the matching server, for a
duration you pick — the metrics endpoint only exposes current status, not a window's schedule.
- **Maintenance schedule ("Sync schedule"):** Uptime Kuma shares its maintenance windows only over the live
Socket.IO connection its own dashboard uses, and that connection takes a **login username and password** —
an API key is not accepted there. Fill in the optional *Login username* and *Login password* on the
integration to use it. Be aware that a Uptime Kuma login can change anything in Uptime Kuma (it has no
read-only accounts), so create a **dedicated account** for this. An account with two-factor authentication
cannot be used. The password is stored encrypted like every other credential here, and is used for nothing
but this. The login is sent as Uptime Kuma's own `login` event over `ws://` or `wss://` to the same address
as the integration, so use an `https://` address if it crosses anything but a trusted network.
- For each window Uptime Kuma reports (its running time slot and the next one), the app finds the
monitors it covers, matches their targets to servers the same way the Uptime Kuma page does, and makes a
maintenance window on each matched server. A window that hasn't started shows as *Scheduled* and silences
nothing yet.
- Tick *Keep maintenance windows in step with Uptime Kuma's schedule* to run this automatically every
15 minutes. Without it, the *Sync schedule* button does the same once.
- Windows are capped at 31 days, and only slots starting within two weeks are mirrored. A window Uptime
Kuma holds in maintenance "until switched off" (the manual kind) is mirrored 45 minutes at a time and
renewed on each pass, so it lapses by itself if Uptime Kuma becomes unreachable.
- A window you end or cancel here is not brought back by a later sync. One that is removed or switched
off in Uptime Kuma is removed here (a running one is ended at once).
- Monitors that match no server (groups, push monitors, hosts the app doesn't know) are listed as
unmatched in the result and silence nothing. A window on a *group* monitor does not extend to its
children here.
- Verified against the Uptime Kuma 1.23 and 2.0 source and against a stand-in server speaking the same
protocol; not yet run against a live Uptime Kuma.
### Proxmox Backup Server