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

+21 -1
View File
@@ -42,6 +42,8 @@ export interface MaintenanceWindow {
startedAt: string;
endsAt: string;
createdBy: string | null;
/** Set on windows mirrored from Uptime Kuma's schedule ("kuma:<integration>:<maintenance>"); null for ones started by hand. */
source: string | null;
}
export interface MaintenanceTargets {
@@ -773,6 +775,22 @@ export interface UptimeKumaMonitorsResponse {
summary: { total: number; up: number; down: number; pending: number; maintenance: number; unknown: number };
}
export interface UptimeKumaSyncResult {
maintenances: {
id: number;
title: string;
strategy: string;
status: string;
servers: string[];
unmatched: string[];
/** Why it produced no window, when it did not. */
note: string | null;
}[];
started: number;
updated: number;
removed: number;
}
export interface UptimeKumaImportResult {
imported: { serverId: number; serverName: string; monitorName: string; extended: boolean }[];
unmatched: string[];
@@ -1043,10 +1061,12 @@ export const api = {
}),
},
maintenance: {
list: () => request<{ windows: MaintenanceWindow[]; targets: MaintenanceTargets }>("/api/maintenance"),
list: () => request<{ windows: MaintenanceWindow[]; upcoming: MaintenanceWindow[]; targets: MaintenanceTargets }>("/api/maintenance"),
start: (data: { targetType: MaintenanceTargetType; targetId: number; minutes: number; reason?: string }) =>
request<{ window: MaintenanceWindow }>("/api/maintenance", { method: "POST", body: JSON.stringify(data) }),
end: (id: number) => request<void>(`/api/maintenance/${id}`, { method: "DELETE" }),
syncUptimeKuma: (data: { integrationId: number }) =>
request<UptimeKumaSyncResult>("/api/maintenance/sync/uptimekuma", { method: "POST", body: JSON.stringify(data) }),
importUptimeKuma: (data: { integrationId: number; minutes: number }) =>
request<UptimeKumaImportResult>("/api/maintenance/import/uptimekuma", { method: "POST", body: JSON.stringify(data) }),
},
+112 -5
View File
@@ -7,6 +7,7 @@ import {
type MaintenanceTargetType,
type MaintenanceWindow,
type UptimeKumaImportResult,
type UptimeKumaSyncResult,
} from "../api/client";
import { formatDateTime } from "../utils/date";
import { formatRemaining } from "../utils/duration";
@@ -30,6 +31,7 @@ function announceChange() {
export default function Maintenance({ user }: { user: CurrentUser }) {
const canEdit = user.role === "admin" || user.role === "operator";
const [windows, setWindows] = useState<MaintenanceWindow[] | null>(null);
const [upcoming, setUpcoming] = useState<MaintenanceWindow[]>([]);
const [targets, setTargets] = useState<MaintenanceTargets | null>(null);
const [error, setError] = useState<string | null>(null);
const [now, setNow] = useState(() => Date.now());
@@ -45,6 +47,9 @@ export default function Maintenance({ user }: { user: CurrentUser }) {
const [kumaBusy, setKumaBusy] = useState(false);
const [kumaError, setKumaError] = useState<string | null>(null);
const [kumaResult, setKumaResult] = useState<UptimeKumaImportResult | null>(null);
const [syncBusy, setSyncBusy] = useState(false);
const [syncError, setSyncError] = useState<string | null>(null);
const [syncResult, setSyncResult] = useState<UptimeKumaSyncResult | null>(null);
useEffect(() => {
api.integrations
@@ -63,6 +68,7 @@ export default function Maintenance({ user }: { user: CurrentUser }) {
.list()
.then((res) => {
setWindows(res.windows);
setUpcoming(res.upcoming ?? []);
setTargets(res.targets);
})
.catch((err) => setError(readableError(err)));
@@ -109,6 +115,23 @@ export default function Maintenance({ user }: { user: CurrentUser }) {
}
}
async function syncFromUptimeKuma() {
if (kumaIntegrationId === "") return;
setSyncError(null);
setSyncResult(null);
setSyncBusy(true);
try {
const result = await api.maintenance.syncUptimeKuma({ integrationId: kumaIntegrationId });
setSyncResult(result);
load();
announceChange();
} catch (err) {
setSyncError(readableError(err));
} finally {
setSyncBusy(false);
}
}
async function importFromUptimeKuma(e: React.FormEvent) {
e.preventDefault();
if (kumaIntegrationId === "") return;
@@ -216,9 +239,16 @@ export default function Maintenance({ user }: { user: CurrentUser }) {
<form onSubmit={importFromUptimeKuma}>
<div className="card-body row g-3">
<div className="text-secondary">
Uptime Kuma only ever tells us what's in maintenance <em>right now</em>, not for how long, so pick a
duration below — it doesn't have to match Uptime Kuma's own schedule exactly, and importing again
later just extends the window instead of stacking a second one.
<strong>Sync schedule</strong> copies Uptime Kuma's maintenance windows — the one running now and the
next one of each daily, weekly or one-off window — onto the servers their monitors belong to, so they
show up under Scheduled below and silence alerts when they start. It needs the login username and
password filled in on the integration, and runs by itself every 15 minutes when{" "}
<em>Keep maintenance windows in step</em> is ticked there.
</div>
<div className="text-secondary">
<strong>Import now</strong> only looks at what is in maintenance <em>this moment</em>: pick a duration
— it doesn't have to match Uptime Kuma's own schedule exactly, and importing again later just extends
the window instead of stacking a second one.
</div>
{kumaIntegrations.length > 1 && (
<div className="col-md-5">
@@ -248,6 +278,32 @@ export default function Maintenance({ user }: { user: CurrentUser }) {
</select>
</div>
</div>
{syncError && (
<div className="card-body pt-0">
<div className="alert alert-danger mb-0">{syncError}</div>
</div>
)}
{syncResult && (
<div className="card-body pt-0">
<div className={`alert ${syncResult.started + syncResult.updated + syncResult.removed > 0 ? "alert-success" : "alert-info"} mb-0`}>
{syncResult.maintenances.length === 0
? "Uptime Kuma has no maintenance windows."
: `Read ${syncResult.maintenances.length} maintenance window${syncResult.maintenances.length === 1 ? "" : "s"} from Uptime Kuma: ${syncResult.started} added, ${syncResult.updated} changed, ${syncResult.removed} removed here.`}
<ul className="mb-0 mt-2">
{syncResult.maintenances.map((m) => (
<li key={m.id}>
<strong>{m.title}</strong>{" "}
<span className="text-secondary">
({m.strategy}, {m.status})
</span>
{m.servers.length > 0 ? ` → ${m.servers.join(", ")}` : m.note ? ` — nothing to schedule: ${m.note}` : ""}
{m.unmatched.length > 0 && <span className="text-secondary"> · no server for {m.unmatched.join(", ")}</span>}
</li>
))}
</ul>
</div>
</div>
)}
{kumaError && (
<div className="card-body pt-0">
<div className="alert alert-danger mb-0">{kumaError}</div>
@@ -289,8 +345,11 @@ export default function Maintenance({ user }: { user: CurrentUser }) {
</div>
)}
<div className="card-footer d-flex align-items-center gap-3">
<button type="submit" className="btn btn-primary" disabled={kumaBusy || kumaIntegrationId === ""}>
{kumaBusy ? "Importing…" : "Import"}
<button type="button" className="btn btn-primary" onClick={syncFromUptimeKuma} disabled={syncBusy || kumaIntegrationId === ""}>
{syncBusy ? "Syncing…" : "Sync schedule"}
</button>
<button type="submit" className="btn" disabled={kumaBusy || kumaIntegrationId === ""}>
{kumaBusy ? "Importing…" : "Import now"}
</button>
{kumaIntegrationId === "" && (
<span className="text-secondary">Every Uptime Kuma integration is disabled — enable one under Integrations.</span>
@@ -300,6 +359,53 @@ export default function Maintenance({ user }: { user: CurrentUser }) {
</div>
)}
{upcoming.length > 0 && (
<div className="card mb-3">
<div className="card-header">
<h3 className="card-title">Scheduled</h3>
</div>
<div className="table-responsive">
<table className="table table-vcenter card-table">
<thead>
<tr>
<th>Target</th>
<th>Reason</th>
<th>Starts</th>
<th>Ends</th>
{canEdit && <th className="w-1">Actions</th>}
</tr>
</thead>
<tbody>
{upcoming.map((w) => (
<tr key={w.id}>
<td>
{w.targetName} <span className="text-secondary">· {w.targetKind}</span>
</td>
<td className="text-secondary">{w.reason ?? "—"}</td>
<td>
<span className="badge bg-blue-lt text-blue me-2">in {formatRemaining(w.startedAt, now)}</span>
<span className="text-secondary small">{formatDateTime(new Date(w.startedAt))}</span>
</td>
<td className="text-secondary small">{formatDateTime(new Date(w.endsAt))}</td>
{canEdit && (
<td>
<button className="btn btn-sm btn-outline-secondary" onClick={() => end(w)}>
Cancel
</button>
</td>
)}
</tr>
))}
</tbody>
</table>
</div>
<div className="card-footer text-secondary small">
Not silencing anything yet. These start by themselves; the schedule comes from Uptime Kuma and is refreshed
every 15 minutes, so a cancelled one stays cancelled but a change in Uptime Kuma is followed.
</div>
</div>
)}
<div className="card mb-3">
<div className="card-header">
<h3 className="card-title">Active</h3>
@@ -320,6 +426,7 @@ export default function Maintenance({ user }: { user: CurrentUser }) {
<tr key={w.id}>
<td>
{w.targetName} <span className="text-secondary">· {w.targetKind}</span>
{w.source?.startsWith("kuma:") && <span className="badge bg-cyan-lt ms-2">Uptime Kuma</span>}
</td>
<td className="text-secondary">{w.reason ?? "—"}</td>
<td>