Platform Health Diagnostics
Open Settings → Platform Health to see the platform gather scattered runtime facts — caches, cluster sync, License, database pool, reverse proxy — into a single-screen snapshot: when something is wrong, it states the cause and offers a one-click fix, without digging through logs or config files.
Aimed at Kuboard administrators for troubleshooting: after an upgrade, when menu or permission changes do not take effect, when list data looks stale, or when the terminal will not open — start here.
Opening the Page
- Sign in and go to Settings → Platform Health;
- The page requires list permission on
health.kuboard.cn / diagnostics(administrators have it by default); - The menu item can be disabled in Settings → System Settings → Menu Settings (it then disappears from the left menu).
The page runs top to bottom: Detected Issues → Platform → Reverse Proxy → Clusters → Cache Resources → Common Issues.

Detected Issues
The platform detects problems across the following dimensions automatically and sorts them by severity (Critical > Warning > Info):
| Dimension | Example of a detected issue |
|---|---|
| Menu cache | Menu definition changed but the cache was not refreshed; menu cache too old (more than 24 hours) |
| Authority cache | Roles / user groups changed but the authority cache was not invalidated ("permissions changed but no effect") |
| Cluster cache & sync | Unhealthy cluster cache, failed sync task, incremental sync (watch) possibly interrupted, slow full sync |
| License | Expired, expiring soon (within 30 days), or not enough cluster capacity (per-site License count + 3 free per site) |
| Database pool | Active connections near the limit, waiting threads piling up |
| Reverse proxy | WebSocket upgrade headers lost, handshake rejected, missing X-Forwarded-Proto, rewritten Host, failed browser probe |
| Redis cache namespace | A shared Redis is in use but no deployment-level key prefix is set (informational, does not affect the health score) |
When everything is fine, the page shows "No known issue detected".
Each issue entry shows: severity, title, evidence (time / cluster / resource involved, etc.) and a fix button. Clicking the fix button applies it immediately — no backend restart needed.
Informational issues do not affect the score
"Redis keys have no deployment prefix" is an informational (info) issue: not configuring a prefix is perfectly normal for a single deployment (empty by default, so an upgrade never clears the caches), therefore it only shows up in the issue list and does not deduct from the health score. It only needs to be addressed when another Kuboard deployment runs on the same Redis database — the entry has no one-click fix, so set the environment variable and restart, see Environment Variable Reference.
One-Click Fixes
| Action | Effect |
|---|---|
| Clear cache | Clears the menu cache or the authority cache; "Clear all caches" also clears system config, resource-type mapping and other caches |
| Restart full sync | Rebuilds the sync tasks for all cached objects of that cluster |
| Check connectivity | Verifies reachability of that cluster's apiserver (whether import parameters are correct and the network is reachable) |
Multi-instance deployments
Caches live in the single-instance local store by default, so clearing affects only the current instance; with KUBOARD_CACHE_PROVIDER=redis the cache is shared and clearing applies to all instances.
Platform
| Metric | Description |
|---|---|
| Backend version / uptime | Version number, how long since startup |
| Cache provider / scheduler leader | Cache implementation (local / redis), whether this instance is the scheduler leader |
| JVM heap / threads | Heap used and max, thread count and processor count |
| SSE / WebSocket connections | Connection counts of this instance |
| Audit writes | Total written / written in the last minute |
| Database pool | Active / idle / max / waiting |
| Snapshot time | When this snapshot was generated |
About connection counts
SSE and WebSocket connections are held by the process, so in a multi-replica deployment this page shows the numbers of the current instance; check each instance separately.
Reverse Proxy
Terminal and log streaming rely on WebSocket, and a misconfigured reverse proxy is the most common fault source. This section answers "which link of the chain is broken":
Browser probe: click Run Probe to start from your current browser and check the "browser → reverse proxy → Kuboard" chain in three steps:
| Step | What it checks |
|---|---|
| 1. Reachability | Whether the request reaches the Kuboard backend |
| 2. Upgrade forwarding | Whether the WebSocket upgrade headers (Upgrade / Connection) are forwarded |
| 3. Auth forwarding | Whether the credential (access_token) reaches the backend |
Probe conclusions: OK, Upgrade headers not forwarded, Path not routed, Auth not forwarded, or Idle timeout too short — each with the matching cause and fix hint.
Server-side observation: the backend counts occurrences and last-seen times of "upgrade headers lost" and "handshake rejected" (per instance), useful for cross-checking against proxy logs and packet captures.
See the "How to fix" section in this panel for Nginx / Ingress configuration samples.
Scope of the probe
The probe reflects the single "current browser → current proxy → Kuboard" chain; validate each entry / proxy separately in multi-ingress deployments.
Clusters
One row per cluster, showing K8s version, cache health, import status, sync issues, cached object count, last full sync and the apiserver address; the action column provides "Restart Full Sync" and "Check Connectivity".
Cache Resources
Lists each resource type's sync mode (Watch / Polling / No cache), polling interval, full/incremental sync status and watch heartbeat. Resources without cache are not auto-synced and their list data is read directly from the cluster (see Resource List Pages, "Cached vs Direct Data").
Common Issues
| Symptom | Fix |
|---|---|
| A newly installed CRD is missing under "Custom Resources" on the left | Check "Detected Issues" for an unhealthy cluster cache or sync failure, click "Restart Full Sync", then refresh |
| Role permission changes have no effect for users | Click "Clear cache" (authority) here — the current user's menu and permissions are rebuilt immediately |
| List data has not changed for a long time | "Restart Full Sync" for that cluster; run "Check Connectivity" first if the apiserver is unreachable |
| The whole platform responds slowly | Look at the pool numbers under "Platform"; when saturated, restarting full sync usually relieves it right away |
| Two Kuboard deployments share one Redis and one of them stops syncing, or permissions leak between them | Set KUBOARD_CACHE_REDIS_KEY_PREFIX (one value per deployment) and restart, see Environment Variable Reference |
| Pod terminal will not open, logs invisible | Click "Run Probe" under "Reverse Proxy" to find the broken link, then fix the proxy configuration |
The interfaces involved in this section (health.kuboard.cn) are not listed among the existing Swagger UI groups; see the API documentation overview for access.
