Server Connections

Managing Server Connections

The eKuiper Manager allows you to monitor and control multiple eKuiper server instances from a single centralized interface. By providing a flexible connection management system, you can switch between edge nodes, production clusters, and local development environments seamlessly.

Connection Configuration

To add a new server, you must provide the connection details for the eKuiper REST API (default port is usually 9081).

Persistence Modes

The manager supports two primary ways to store your server configurations, depending on your deployment requirements:

1. Browser-based Persistence (Default)

In this mode, server connections are stored in your browser's local storage.

Pros: Zero-configuration required; data remains private to your browser.
Cons: Connections are lost if you clear browser data or switch to a different machine/browser.

2. SQLite / Server-side Persistence (Experimental)

For multi-user environments or persistent management stations, you can enable server-side storage. Configurations are saved in a local database file (defaults to .data/connections.json).

Pros: Persistent across different browsers and devices; shared state.
Cons: Requires write permissions on the host filesystem.

Health Monitoring

The manager performs periodic health checks against all configured connections. Each server card in the dashboard displays a real-time status indicator:

Online: The REST API is reachable and responding to system info requests.
Offline: The server is unreachable or the REST service is stopped.
Unauthorized/Error: The server responded, but the request failed (e.g., due to networking or firewall rules).

Connection Proxying

To circumvent CORS (Cross-Origin Resource Sharing) limitations and provide a unified API interface, eKuiper Manager uses an internal proxy. This allows the frontend to communicate with edge servers via the manager's backend.

The internal API structure follows this pattern: POST/GET /api/connections/[connectionId]/ekuiper/[...path]

Example Proxy Request:

// Accessing rules on a specific connection via the proxy
const response = await fetch('/api/connections/my-server-id/ekuiper/rules', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});

const rules = await response.json();

Testing Connections Programmatically

If you are extending the manager or writing custom scripts, you can utilize the EKuiperClient to verify connections.

import { EKuiperClient } from "@/lib/ekuiper/client";

// Initialize client in direct mode (for server-side/script usage)
const client = new EKuiperClient("http://localhost:9081", undefined, 5000, true);

async function checkHealth() {
    try {
        const info = await client.getInfo();
        console.log(`Connected to eKuiper version: ${info.version}`);
    } catch (error) {
        console.error("Connection failed", error);
    }
}

Troubleshooting

CORS Issues: If connecting directly from a browser to a remote eKuiper instance without using the manager proxy, ensure the eKuiper server is configured to allow your manager's origin.
Connection Refused: Verify that the eKuiper REST service is listening on the expected IP/Port and that no firewall is blocking traffic to 9081.