tutorial

SiYuan Notes Monitoring with Vigilmon

"Learn how to monitor SiYuan Notes, the self-hosted privacy-first personal knowledge management system, with Vigilmon — covering kernel server availability, WebSocket synchronization health, data repository integrity checks, cloud sync endpoint connectivity, plugin loading service, and export/import pipeline monitoring."

SiYuan Notes Monitoring with Vigilmon

SiYuan Notes is a self-hosted, privacy-first personal knowledge management (PKM) and note-taking system written in Go. It runs a local kernel server on port 6806 that serves a web-based editor, handles block-level storage in a local repository, syncs to cloud backends via S3-compatible APIs, manages plugins via a marketplace, and provides data export/import pipelines for Markdown, Word, and PDF. Teams and individuals self-host SiYuan to keep their notes fully offline while retaining optional cloud sync.

Because SiYuan is the single point of access for all stored knowledge, an undetected outage means notes are inaccessible, edits are lost during sync failures, and plugins that automate workflows silently stop running. Without monitoring, kernel panics, corrupt data repositories, and stalled cloud sync sessions accumulate invisibly.

This guide covers how to monitor SiYuan Notes with Vigilmon.

Why SiYuan Notes Needs Monitoring

SiYuan failures affect the accessibility and integrity of stored knowledge:

  • Kernel server crash — the Go HTTP server on port 6806 stops responding; the web UI cannot load, and all note access, editing, and search is blocked until the process is restarted
  • WebSocket synchronization failure — the real-time editing WebSocket disconnects; collaborative or multi-window edits do not sync, and unsaved changes accumulate in memory without being flushed to disk
  • Data repository corruption — the local block storage repository becomes inconsistent; notes open with missing content, broken references, or silent data loss on subsequent writes
  • Cloud sync endpoint failure — the S3-compatible sync backend becomes unreachable; local changes are not pushed and remote changes are not pulled, causing divergence between devices
  • Plugin loading failure — the plugin service cannot load or initialize plugins; automations, custom renderers, and workflow integrations stop functioning without alerting the user
  • Export/import pipeline stall — batch export jobs stop completing; long-running Markdown, PDF, or Word exports silently time out and leave partial files on disk

Vigilmon monitors all of these failure modes so issues are caught before knowledge work is disrupted.

SiYuan Notes Architecture Overview

| Component | Default Port | Role | Monitoring Priority | |-----------|-------------|------|---------------------| | SiYuan kernel HTTP server | 6806 | Web UI, API, and note access | Critical | | WebSocket endpoint | 6806 (ws://) | Real-time sync and editor updates | Critical | | Cloud sync endpoint | External (S3/WebDAV) | Cross-device note synchronization | High | | Plugin service | 6806 (same server) | Plugin loading and execution | Medium | | Export/import pipeline | 6806 (same server) | Batch data export and import | Medium |

Monitor 1: SiYuan Kernel Server Availability

Monitor the SiYuan kernel home page to confirm the Go HTTP server is responding:

  1. Log in to Vigilmon → Monitors → New Monitor
  2. Type: HTTP
  3. Name: SiYuan Notes - Kernel Server
  4. URL: http://your-siyuan-host:6806/
  5. Method: GET
  6. Expected status: 200
  7. Keyword check: SiYuan
  8. Interval: 1 minute

Test your endpoint:

curl -s http://your-siyuan-host:6806/ | grep -i "siyuan"
# Expected: HTML containing "SiYuan"

Monitor 2: SiYuan API Health Check

The SiYuan kernel exposes a /api/system/version endpoint that returns version information without authentication. A 200 response confirms the API layer is healthy:

  1. Type: HTTP
  2. Name: SiYuan Notes - API Health
  3. URL: http://your-siyuan-host:6806/api/system/version
  4. Method: POST
  5. Request body: {}
  6. Expected status: 200
  7. Keyword check: kernelVersion
  8. Interval: 2 minutes
curl -s -X POST http://your-siyuan-host:6806/api/system/version \
  -H "Content-Type: application/json" \
  -d '{}'
# Expected: {"code":0,"msg":"","data":{"kernelVersion":"..."}}

Monitor 3: WebSocket Synchronization Endpoint

SiYuan uses WebSocket connections for real-time editor updates. A successful WebSocket upgrade response from the kernel confirms the sync service is listening:

  1. Type: HTTP
  2. Name: SiYuan Notes - WebSocket Endpoint
  3. URL: http://your-siyuan-host:6806/ws
  4. Method: GET
  5. Expected status: 101 (or 400 — both confirm the WebSocket handler is active)
  6. Interval: 2 minutes
# A plain HTTP GET to the WebSocket path returns a protocol upgrade error,
# confirming the endpoint exists and the handler is running
curl -s -o /dev/null -w "%{http_code}" http://your-siyuan-host:6806/ws
# Expected: 400 (WebSocket upgrade required — handler is active)
# Error: 502 or 000 (server down or proxy failure)

Monitor 4: Cloud Sync Endpoint Connectivity

If SiYuan is configured to sync to an S3-compatible or WebDAV backend, monitor the sync endpoint to catch network or credential failures before data diverges across devices:

  1. Type: HTTP
  2. Name: SiYuan Notes - Cloud Sync Endpoint
  3. URL: https://your-s3-or-webdav-endpoint/
  4. Method: GET
  5. Expected status: 200 or 403 (both confirm the endpoint is reachable)
  6. Interval: 5 minutes
curl -s -o /dev/null -w "%{http_code}" https://your-s3-endpoint/
# Expected: 200 or 403 (reachable)
# Error: 000 or 503 (network failure)

For MinIO self-hosted sync: monitor http://your-minio-host:9000/minio/health/live with expected status 200.

Monitor 5: SSL Certificate Alert

If SiYuan is exposed via a reverse proxy with HTTPS:

  1. Type: HTTP
  2. Name: SiYuan Notes - SSL Certificate
  3. URL: https://notes.your-domain.com/
  4. SSL certificate expiry alert: 21 days before expiry
  5. Interval: 1 hour
curl -vI https://notes.your-domain.com/ 2>&1 | grep "expire date"
# Expected: a future expiry date with at least 21 days remaining

Monitor 6: SiYuan Kernel Heartbeat

An hourly heartbeat verifies that the kernel can read a workspace and that the note API is functional end-to-end:

Heartbeat Script

#!/bin/bash
# siyuan-heartbeat.sh — run hourly via cron
set -euo pipefail

SIYUAN_URL="http://your-siyuan-host:6806"
SIYUAN_TOKEN="${SIYUAN_API_TOKEN}"  # set in SiYuan Settings → About
VIGILMON_HEARTBEAT="YOUR_HEARTBEAT_ID"

# Step 1: Check kernel version (no auth required)
VERSION_RESPONSE=$(curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{}' \
  "${SIYUAN_URL}/api/system/version")

VERSION=$(echo "$VERSION_RESPONSE" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('data',{}).get('kernelVersion',''))" 2>/dev/null)

if [ -z "$VERSION" ]; then
  echo "[siyuan-hb] Kernel version check failed"
  exit 1
fi

# Step 2: List notebooks (verifies repository access)
NOTEBOOKS=$(curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Token ${SIYUAN_TOKEN}" \
  -d '{}' \
  "${SIYUAN_URL}/api/notebook/lsNotebooks")

NB_CODE=$(echo "$NOTEBOOKS" | python3 -c "import sys,json; print(json.load(sys.stdin).get('code',-1))" 2>/dev/null)

if [ "$NB_CODE" -ne 0 ]; then
  echo "[siyuan-hb] Notebook list returned code $NB_CODE (repository may be corrupt or token invalid)"
  exit 1
fi

echo "[siyuan-hb] Kernel v${VERSION} healthy; repository accessible"

# Step 3: Signal Vigilmon
curl -s "https://heartbeat.vigilmon.online/$VIGILMON_HEARTBEAT"

Add to cron:

# /etc/cron.d/siyuan-heartbeat
0 * * * * root /opt/siyuan/siyuan-heartbeat.sh >> /var/log/siyuan-heartbeat.log 2>&1

In Vigilmon:

  • Type: Heartbeat
  • Name: SiYuan Notes - Kernel and Repository Pipeline
  • Expected interval: 1 hour
  • Grace period: 10 minutes

Alert Configuration

| Monitor | Type | Interval | Alert Channel | |---------|------|----------|---------------| | Kernel server | HTTP | 1 min | Slack + Email | | API health | HTTP | 2 min | Slack | | WebSocket endpoint | HTTP | 2 min | Slack | | Cloud sync endpoint | HTTP | 5 min | Email | | SSL certificate | HTTP | 1 hour | Email (21-day lead) | | Kernel and repository pipeline | Heartbeat | 1 hour | PagerDuty + Email |

Use immediate alerts for the kernel server monitor. A down kernel means all notes are inaccessible — users will notice instantly and file support requests.

Status Page

  1. Status Pages → New Page → name it "SiYuan Notes"
  2. Add all monitors above
  3. Share with team members or household users who rely on the shared SiYuan instance

When a user reports that the editor is not saving or cloud sync appears stalled, they can check this page before escalating.

Summary

SiYuan Notes is the sole access point for your stored knowledge base. Vigilmon keeps it healthy:

  • HTTP monitors for kernel availability, API health, and WebSocket endpoint reachability
  • Cloud sync monitoring to catch S3/WebDAV connectivity failures before note divergence accumulates
  • SSL certificate monitoring with a 21-day lead time for reverse-proxied deployments
  • Hourly heartbeat that verifies kernel version and notebook repository access end-to-end

Get started at vigilmon.online.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles