plugin-cluster-manager 1.1.7 → 1.1.10

package/dist/server/collections/orchestrator-settings.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Plugin settings stored in DB — configurable via NocoBase admin UI.
+ * Replaces env-var-only configuration for orchestrator adapter selection.
+ */
+declare const _default: {
+    name: string;
+    autoGenId: boolean;
+    createdAt: boolean;
+    updatedAt: boolean;
+    fields: ({
+        name: string;
+        type: string;
+        defaultValue: string;
+        interface: string;
+        uiSchema: {
+            title: string;
+            'x-component': string;
+            enum: {
+                value: string;
+                label: string;
+            }[];
+            description?: undefined;
+        };
+    } | {
+        name: string;
+        type: string;
+        defaultValue: string;
+        interface: string;
+        uiSchema: {
+            title: string;
+            'x-component': string;
+            enum?: undefined;
+            description?: undefined;
+        };
+    } | {
+        name: string;
+        type: string;
+        interface: string;
+        uiSchema: {
+            title: string;
+            description: string;
+            'x-component': string;
+            enum?: undefined;
+        };
+        defaultValue?: undefined;
+    } | {
+        name: string;
+        type: string;
+        defaultValue: string;
+        interface: string;
+        uiSchema: {
+            title: string;
+            description: string;
+            'x-component': string;
+            enum?: undefined;
+        };
+    })[];
+};
+export default _default;

package/dist/server/collections/orchestrator-stacks.d.ts

@@ -0,0 +1,102 @@
+declare const _default: {
+    name: string;
+    autoGenId: boolean;
+    createdAt: boolean;
+    updatedAt: boolean;
+    fields: ({
+        name: string;
+        type: string;
+        unique: boolean;
+        interface: string;
+        uiSchema: {
+            title: string;
+            'x-component': string;
+            enum?: undefined;
+        };
+        defaultValue?: undefined;
+    } | {
+        name: string;
+        type: string;
+        defaultValue: string;
+        interface: string;
+        uiSchema: {
+            title: string;
+            'x-component': string;
+            enum: {
+                value: string;
+                label: string;
+            }[];
+        };
+        unique?: undefined;
+    } | {
+        name: string;
+        type: string;
+        interface: string;
+        uiSchema: {
+            title: string;
+            'x-component': string;
+            enum?: undefined;
+        };
+        unique?: undefined;
+        defaultValue?: undefined;
+    } | {
+        name: string;
+        type: string;
+        defaultValue: {};
+        interface: string;
+        uiSchema: {
+            title: string;
+            'x-component'?: undefined;
+            enum?: undefined;
+        };
+        unique?: undefined;
+    } | {
+        name: string;
+        type: string;
+        defaultValue: any[];
+        interface: string;
+        uiSchema: {
+            title: string;
+            'x-component'?: undefined;
+            enum?: undefined;
+        };
+        unique?: undefined;
+    } | {
+        name: string;
+        type: string;
+        defaultValue: number;
+        interface: string;
+        uiSchema: {
+            title: string;
+            'x-component'?: undefined;
+            enum?: undefined;
+        };
+        unique?: undefined;
+    } | {
+        name: string;
+        type: string;
+        defaultValue: boolean;
+        interface: string;
+        uiSchema: {
+            title: string;
+            'x-component'?: undefined;
+            enum?: undefined;
+        };
+        unique?: undefined;
+    } | {
+        name: string;
+        type: string;
+        defaultValue: string;
+        unique?: undefined;
+        interface?: undefined;
+        uiSchema?: undefined;
+    } | {
+        name: string;
+        type: string;
+        unique?: undefined;
+        interface?: undefined;
+        uiSchema?: undefined;
+        defaultValue?: undefined;
+    })[];
+};
+export default _default;

package/dist/server/collections/worker-orchestrator.d.ts

@@ -0,0 +1,22 @@
+/**
+ * DUMMY COLLECTION
+ * This collection is created to prevent NocoBase workflow/ACL from throwing the error:
+ * '[Workflow pre-action]: collection "workerOrchestrator" not found'
+ *
+ * Since 'workerOrchestrator' is registered as a resourcer in plugin.ts, NocoBase
+ * implicitly looks for a collection with the same name.
+ * We set dumpRules: 'skip' and avoid timestamps to ensure this collection
+ * is completely ignored during backups/migrations and doesn't pollute the actual DB.
+ */
+declare const _default: {
+    name: string;
+    dumpRules: string;
+    autoGenId: boolean;
+    createdAt: boolean;
+    updatedAt: boolean;
+    fields: {
+        name: string;
+        type: string;
+    }[];
+};
+export default _default;

package/dist/server/collections/worker-packages-configs.d.ts

@@ -0,0 +1,3 @@
+import { CollectionOptions } from '@nocobase/database';
+declare const _default: CollectionOptions;
+export default _default;

package/dist/server/collections/worker-packages.d.ts

@@ -0,0 +1,22 @@
+/**
+ * DUMMY COLLECTION
+ * This collection is created to prevent NocoBase workflow/ACL from throwing the error:
+ * '[Workflow pre-action]: collection "workerPackages" not found'
+ *
+ * Since 'workerPackages' is registered as a resourcer in plugin.ts, NocoBase
+ * implicitly looks for a collection with the same name.
+ * We set dumpRules: 'skip' and avoid timestamps to ensure this collection
+ * is completely ignored during backups/migrations and doesn't pollute the actual DB.
+ */
+declare const _default: {
+    name: string;
+    dumpRules: string;
+    autoGenId: boolean;
+    createdAt: boolean;
+    updatedAt: boolean;
+    fields: {
+        name: string;
+        type: string;
+    }[];
+};
+export default _default;

package/dist/server/index.d.ts

@@ -0,0 +1 @@
+export { default } from './plugin';

package/dist/server/orchestrator/PackageManager.d.ts

@@ -0,0 +1,39 @@
+import Application from '@nocobase/server';
+type TargetRole = 'app' | 'worker' | 'sandbox' | 'all';
+interface InstallPayload {
+    targetRole: TargetRole;
+    packages: {
+        apt?: string[];
+        npm?: string[];
+        python?: string[];
+    };
+    registryConfig?: {
+        aptMirrorUrl?: string;
+        npmRegistryUrl?: string;
+        pypiIndexUrl?: string;
+        pypiTrustedHost?: string;
+    };
+}
+export declare class PackageManager {
+    private app;
+    constructor(app: Application);
+    /**
+     * Called from REST action when admin clicks "Install Packages".
+     * Publishes task to all nodes via PubSub. Nodes will filter by targetRole.
+     */
+    dispatchInstall(payload: InstallPayload): Promise<string>;
+    executeInstall(payload: InstallPayload): Promise<void>;
+    /**
+     * Run a command without a shell so registry URLs and package names are not re-parsed as shell syntax.
+     */
+    private runCommand;
+    private getMissingPackages;
+    private isPackageInstalled;
+    private runStatus;
+    private getAptOsInfo;
+    private buildAptSources;
+    private configureAptMirror;
+    private moveIfExists;
+    private updateInstallStatus;
+}
+export {};

package/dist/server/orchestrator/PackageManager.js

@@ -43,7 +43,7 @@ var import_child_process = require("child_process");
 var import_redis = require("../utils/redis");
 var import_fs = require("fs");
 var import_path = __toESM(require("path"));
-const SAFE_PKG_RE = /^[a-zA-Z0-9_\-\.@\/\[\]]+$/;
+const SAFE_PKG_RE = /^(?:[a-zA-Z0-9_.@/-]|\[|\])+$/;
 const INSTALL_CHANNEL = "cluster-manager.install-packages";
 function sanitizePkg(name) {
   if (typeof name !== "string") {
@@ -99,6 +99,35 @@ function formatCommand(command, args) {
     return /^[a-zA-Z0-9_./:@=-]+$/.test(value) ? value : JSON.stringify(value);
   }).join(" ");
 }
+function parseOsRelease(content) {
+  const values = {};
+  for (const line of content.split("\n")) {
+    const match = line.match(/^([A-Z0-9_]+)=(.*)$/);
+    if (!match) continue;
+    values[match[1]] = match[2].replace(/^"|"$/g, "");
+  }
+  return values;
+}
+function normalizeMirrorUrl(value) {
+  return value.endsWith("/") ? value : `${value}/`;
+}
+function isInternalCacheMirror(url) {
+  return url.hostname === "nginx-cache-registry";
+}
+function resolveAptMirrorForOs(aptMirrorUrl, osInfo, logs) {
+  const url = new URL(normalizeMirrorUrl(aptMirrorUrl));
+  const original = url.toString();
+  if (isInternalCacheMirror(url) && osInfo.id === "debian" && url.pathname === "/ubuntu/") {
+    url.pathname = "/debian/";
+  } else if (isInternalCacheMirror(url) && osInfo.id === "ubuntu" && url.pathname === "/debian/") {
+    url.pathname = "/ubuntu/";
+  }
+  const resolved = url.toString();
+  if (resolved !== original) {
+    logs.push(`Adjusted APT mirror for ${osInfo.id}: ${redactUrl(resolved)}`);
+  }
+  return resolved;
+}
 class PackageManager {
   constructor(app) {
     this.app = app;
@@ -143,7 +172,7 @@ class PackageManager {
         if (registryConfig.aptMirrorUrl) {
           const aptMirrorUrl = sanitizeHttpUrl(registryConfig.aptMirrorUrl, "APT mirror URL");
           logs.push(`Applying APT mirror: ${redactUrl(aptMirrorUrl)}`);
-          await this.configureAptMirror(aptMirrorUrl);
+          await this.configureAptMirror(aptMirrorUrl, logs);
         }
         await this.updateInstallStatus("running", 20, "Installing APT packages...", logs);
         await this.runCommand("apt-get", ["update", "-qq"], "Updating APT package index...", logs, 12e5);
@@ -245,11 +274,11 @@ ${logs.join("\n")}`);
       let stdout = "";
       let stderr = "";
       let settled = false;
-      let timer;
+      const state = {};
       const finish = (error) => {
         if (settled) return;
         settled = true;
-        clearTimeout(timer);
+        if (state.timer) clearTimeout(state.timer);
         if (stdout) logs.push(stdout.slice(0, 500));
         if (stderr) logs.push(`WARN: ${stderr.slice(0, 300)}`);
         if (error) {
@@ -259,7 +288,7 @@ ${logs.join("\n")}`);
           resolve();
         }
       };
-      timer = setTimeout(() => {
+      state.timer = setTimeout(() => {
         child.kill("SIGTERM");
         finish(new Error(`${command} timed out after ${timeoutMs}ms`));
       }, timeoutMs);
@@ -312,14 +341,14 @@ ${logs.join("\n")}`);
       const child = (0, import_child_process.spawn)(command, args, { stdio: ["ignore", "pipe", "ignore"] });
       let stdout = "";
       let settled = false;
-      let timer;
+      const state = {};
       const finish = (ok) => {
         if (settled) return;
         settled = true;
-        clearTimeout(timer);
+        if (state.timer) clearTimeout(state.timer);
         resolve(ok);
       };
-      timer = setTimeout(() => {
+      state.timer = setTimeout(() => {
         child.kill("SIGTERM");
         finish(false);
       }, timeoutMs);
@@ -330,7 +359,31 @@ ${logs.join("\n")}`);
       child.on("close", (code) => finish(code === 0 && (isSuccess ? isSuccess(stdout) : true)));
     });
   }
-  async configureAptMirror(aptMirrorUrl) {
+  async getAptOsInfo() {
+    const values = parseOsRelease(await import_fs.promises.readFile("/etc/os-release", "utf8"));
+    const id = (values.ID || "").toLowerCase();
+    const codename = values.VERSION_CODENAME || values.UBUNTU_CODENAME;
+    if (!id || !codename) {
+      throw new Error("Cannot detect OS ID/version codename from /etc/os-release for APT mirror configuration.");
+    }
+    return { id, codename };
+  }
+  buildAptSources(aptMirrorUrl, osInfo) {
+    const mirror = normalizeMirrorUrl(aptMirrorUrl);
+    if (osInfo.id === "ubuntu") {
+      return `deb ${mirror} ${osInfo.codename} main universe restricted multiverse
+`;
+    }
+    if (osInfo.id === "debian") {
+      return `deb ${mirror} ${osInfo.codename} main contrib non-free non-free-firmware
+`;
+    }
+    return `deb ${mirror} ${osInfo.codename} main
+`;
+  }
+  async configureAptMirror(aptMirrorUrl, logs) {
+    const osInfo = await this.getAptOsInfo();
+    const resolvedMirrorUrl = resolveAptMirrorForOs(aptMirrorUrl, osInfo, logs);
     const backupDir = "/etc/apt/sources.list.d.bak";
     await import_fs.promises.mkdir(backupDir, { recursive: true });
     await this.moveIfExists("/etc/apt/sources.list", import_path.default.join(backupDir, `sources.list.${Date.now()}.bak`));
@@ -342,8 +395,7 @@ ${logs.join("\n")}`);
       }
     } catch {
     }
-    await import_fs.promises.writeFile("/etc/apt/sources.list", `deb ${aptMirrorUrl} bookworm main
-`, "utf8");
+    await import_fs.promises.writeFile("/etc/apt/sources.list", this.buildAptSources(resolvedMirrorUrl, osInfo), "utf8");
   }
   async moveIfExists(from, to) {
     try {

package/dist/server/orchestrator/docker-adapter.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Docker Adapter — MVP implementation
+ *
+ * Uses dockerode to communicate with the Docker daemon via unix socket.
+ * Containers are tagged with label `orchestrator.stack=<stackName>` for identification.
+ *
+ * Security: Docker socket = root on host. Only admin users should access
+ * orchestrator actions (enforced by ACL in plugin.ts).
+ */
+import type { IOrchestratorAdapter, ContainerInfo, ScaleResult, ContainerStats, StackConfig } from './types';
+export declare class DockerAdapter implements IOrchestratorAdapter {
+    readonly name = "docker";
+    private docker;
+    private workerLabels;
+    constructor(options?: {
+        socketPath?: string;
+        host?: string;
+        port?: number;
+        workerLabelSelector?: string;
+    });
+    ping(): Promise<boolean>;
+    listContainers(stack: StackConfig): Promise<ContainerInfo[]>;
+    assertManagedByStack(stack: StackConfig, containerId: string): Promise<void>;
+    scale(stack: StackConfig, replicas: number): Promise<ScaleResult>;
+    startContainer(containerId: string): Promise<void>;
+    stopContainer(containerId: string, timeoutSecs?: number): Promise<void>;
+    removeContainer(containerId: string): Promise<void>;
+    getStats(containerId: string): Promise<ContainerStats>;
+    getLogs(containerId: string, tail?: number): Promise<string>;
+    listNetworks(): Promise<{
+        id: string;
+        name: string;
+    }[]>;
+    private mapState;
+    private buildEnvArray;
+    private buildLabelFilters;
+    private parseLabelSelector;
+    private labelsMatch;
+    private parseMemory;
+    private demuxDockerLogs;
+}

package/dist/server/orchestrator/index.d.ts

@@ -0,0 +1,4 @@
+export { IOrchestratorAdapter, ContainerInfo, ScaleResult, ContainerStats, StackConfig } from './types';
+export { DockerAdapter } from './docker-adapter';
+export { K8sAdapter } from './k8s-adapter';
+export { LeaderElection } from './leader-election';

package/dist/server/orchestrator/k8s-adapter.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Kubernetes Adapter
+ *
+ * Manages worker Deployments/Pods via the K8s API using in-cluster ServiceAccount
+ * or kubeconfig. Only manages resources labeled with `orchestrator.stack=<stackName>`.
+ *
+ * Prerequisites:
+ *   - ServiceAccount with RBAC: get/list/create/patch/update on Deployments and Deployments/scale
+ *   - get/list/delete on Pods and get on Pods/log
+ *   - Or KUBECONFIG env var pointing to a valid kubeconfig file
+ */
+import type { IOrchestratorAdapter, ContainerInfo, ScaleResult, ContainerStats, StackConfig } from './types';
+export declare class K8sAdapter implements IOrchestratorAdapter {
+    readonly name = "kubernetes";
+    private appsApi;
+    private coreApi;
+    private kc;
+    private namespace;
+    private workerLabelSelector;
+    private workerLabels;
+    constructor(options?: {
+        kubeconfig?: string;
+        context?: string;
+        namespace?: string;
+        workerLabelSelector?: string;
+    });
+    ping(): Promise<boolean>;
+    listContainers(stack: StackConfig): Promise<ContainerInfo[]>;
+    scale(stack: StackConfig, replicas: number): Promise<ScaleResult>;
+    startContainer(containerId: string): Promise<void>;
+    stopContainer(containerId: string): Promise<void>;
+    removeContainer(containerId: string): Promise<void>;
+    getStats(containerId: string): Promise<ContainerStats>;
+    getLogs(containerId: string, tail?: number): Promise<string>;
+    assertManagedByStack(stack: StackConfig, containerId: string): Promise<void>;
+    private parsePodRef;
+    private buildDeployment;
+    private buildWorkerLabels;
+    private buildContainerEnv;
+    private buildResources;
+    private cleanArray;
+    private isEmptyValue;
+    private isNotFound;
+    private assertDeploymentManagedByStack;
+    private joinSelectors;
+    private parseLabelSelector;
+    private labelsMatch;
+    private mapPodPhase;
+    private parseK8sMemory;
+}

package/dist/server/orchestrator/leader-election.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Leader Election using native Redis commands
+ *
+ * Ensures only ONE app instance runs orchestrator write operations (scale, start, stop).
+ * Other instances remain read-only followers.
+ *
+ * Flow:
+ *   1. After app starts, tryBecomeLeader() attempts to acquire the Redis lock using SET NX PX.
+ *   2. If acquired → this node is leader; a renewal timer extends the lock periodically using a Lua script.
+ *   3. If not acquired → this node is follower; it retries periodically.
+ *   4. On app stop → release the lock gracefully using a Lua script.
+ *   5. On crash → lock auto-expires after TTL.
+ */
+export declare class LeaderElection {
+    private app;
+    private renewTimer;
+    private retryTimer;
+    private _isLeader;
+    private _leaderId;
+    private standaloneMode;
+    private enabled;
+    private _disabledReason;
+    private redis;
+    constructor(app: any, options?: {
+        standaloneMode?: boolean;
+        enabled?: boolean;
+        disabledReason?: string;
+    });
+    get isLeader(): boolean;
+    get leaderId(): string;
+    get disabledReason(): string;
+    /**
+     * Initialize Redis client. Must be called after Redis is connected.
+     */
+    init(): Promise<boolean>;
+    /**
+     * Attempt to become the orchestrator leader.
+     * If successful, starts a renewal loop.
+     * If not, starts a retry loop.
+     */
+    tryBecomeLeader(): Promise<boolean>;
+    /**
+     * Gracefully release leadership.
+     */
+    release(): Promise<void>;
+    private startRenewal;
+    private startRetry;
+}

package/dist/server/orchestrator/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Orchestrator Adapter Interface
+ *
+ * Abstraction layer for container runtimes (Docker, K8s, Swarm).
+ * Each adapter implements this interface so the plugin logic is runtime-agnostic.
+ */
+export interface ContainerInfo {
+    id: string;
+    name: string;
+    status: 'running' | 'stopped' | 'pending' | 'error' | 'creating' | 'exited';
+    image: string;
+    createdAt: Date;
+    cpu?: number;
+    memory?: number;
+    labels?: Record<string, string>;
+}
+export interface ScaleResult {
+    previousReplicas: number;
+    currentReplicas: number;
+    containersCreated?: string[];
+    containersRemoved?: string[];
+}
+export interface ContainerStats {
+    cpu: number;
+    memory: number;
+    memoryLimit: number;
+    networkRx: number;
+    networkTx: number;
+}
+export interface StackConfig {
+    id?: number;
+    name: string;
+    adapter: 'docker' | 'kubernetes';
+    image: string;
+    command?: string;
+    envVars?: Record<string, string>;
+    volumes?: string[];
+    networks?: string[];
+    resourceLimits?: {
+        memory?: string;
+        cpu?: string;
+    };
+    replicas: number;
+    desiredReplicas: number;
+    enabled: boolean;
+    namespace?: string;
+    deploymentName?: string;
+    serviceAccountName?: string;
+    imagePullPolicy?: string;
+    k8sContainerName?: string;
+    k8sEnv?: Record<string, any>[];
+    k8sEnvFrom?: Record<string, any>[];
+    k8sVolumeMounts?: Record<string, any>[];
+    k8sVolumes?: Record<string, any>[];
+    networkMode?: string;
+    restartPolicy?: string;
+}
+export interface IOrchestratorAdapter {
+    /** Human-readable adapter name */
+    readonly name: string;
+    /** Test connectivity to the runtime */
+    ping(): Promise<boolean>;
+    /** List containers managed by a stack */
+    listContainers(stack: StackConfig): Promise<ContainerInfo[]>;
+    /** Verify that a runtime container/pod belongs to the requested stack */
+    assertManagedByStack(stack: StackConfig, containerId: string): Promise<void>;
+    /** Scale stack to N replicas */
+    scale(stack: StackConfig, replicas: number): Promise<ScaleResult>;
+    /** Start a stopped container */
+    startContainer(containerId: string): Promise<void>;
+    /** Gracefully stop a running container */
+    stopContainer(containerId: string, timeoutSecs?: number): Promise<void>;
+    /** Remove/delete a container (force) */
+    removeContainer(containerId: string): Promise<void>;
+    /** Get real-time resource stats for a container */
+    getStats(containerId: string): Promise<ContainerStats>;
+    /** Get tail logs from a container */
+    getLogs(containerId: string, tail?: number): Promise<string>;
+    /** List available networks (if supported by adapter) */
+    listNetworks?(): Promise<{
+        id: string;
+        name: string;
+    }[]>;
+}

package/dist/server/plugin.d.ts

@@ -0,0 +1,26 @@
+import { Plugin } from '@nocobase/server';
+import { RedisNodeRegistry } from './adapters/redis-node-registry';
+import type { IOrchestratorAdapter } from './orchestrator/types';
+import { LeaderElection } from './orchestrator/leader-election';
+export declare class PluginClusterManagerServer extends Plugin {
+    nodeRegistry: RedisNodeRegistry;
+    orchestrator: IOrchestratorAdapter | null;
+    leaderElection: LeaderElection | null;
+    beforeLoad(): Promise<void>;
+    load(): Promise<void>;
+    private registerPubSubAdapter;
+    /**
+     * Initialize the Container Orchestrator subsystem.
+     * Config is loaded from DB (orchestratorSettings collection) first,
+     * then falls back to ORCHESTRATOR_ADAPTER env var.
+     * This allows manual configuration via the NocoBase admin UI.
+     */
+    private initOrchestrator;
+    /**
+     * Connect (or reconnect) the orchestrator adapter based on settings.
+     * Can be called at startup or when user saves new settings via UI.
+     */
+    connectAdapter(settings: any): Promise<boolean>;
+    private isWorkerOnlyNode;
+}
+export default PluginClusterManagerServer;

package/dist/server/plugin.js

@@ -71,6 +71,15 @@ class PluginClusterManagerServer extends import_server.Plugin {
     await this.db.import({ directory: import_path.default.resolve(__dirname, "collections") });
   }
   async load() {
+    this.db.extendCollection({
+      name: "attachments",
+      fields: [
+        {
+          type: "bigInt",
+          name: "createdById"
+        }
+      ]
+    });
     this.nodeRegistry = new import_redis_node_registry.RedisNodeRegistry(this.app);
     this.app.on("afterStart", () => {
       var _a;

package/dist/server/utils/node.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Generate a universally unique identifier for this specific Node.js process.
+ * Combines app name, worker mode, hostname, port, and PID to ensure uniqueness
+ * even when multiple workers run on the exact same host.
+ */
+export declare function getLocalNodeId(app: any): string;