plugin-cluster-manager 1.1.15 → 1.1.17

package/src/client/ContainerOrchestrator.tsx

@@ -38,6 +38,12 @@ import {
 } from '@ant-design/icons';
 import { useApp } from '@nocobase/client-v2';
 import { useT } from './utils';
+import {
+  getCommonWorkerProcesses,
+  normalizeWorkerMode,
+  resolveWorkerProcessName,
+  workerModeTokens,
+} from '../shared/worker-processes';
 
 const { Text, Title } = Typography;
 
@@ -58,6 +64,7 @@ interface StackInfo {
   image: string;
   command?: string;
   envVars?: Record<string, string>;
+  workerMode?: string;
   resourceLimits?: Record<string, string>;
   replicas: number;
   desiredReplicas: number;
@@ -73,6 +80,15 @@ interface StackInfo {
   k8sVolumes?: Record<string, any>[];
 }
 
+interface DiscoveredQueue {
+  name: string;
+  label: string;
+  description: string;
+  type: 'event-queue' | 'redis-list';
+  pending: number | null;
+  workerProcessName?: string;
+}
+
 const DEFAULT_WORKER_COMMAND = `export NOCOBASE_RUNNING_IN_DOCKER=true
 if ! command -v git >/dev/null; then echo "Installing git..."; if command -v apt-get >/dev/null; then apt-get update && apt-get install -y git; elif command -v apk >/dev/null; then apk add git; fi; fi
 if [ ! -d /app/nocobase ]; then mkdir -p /app/nocobase; fi
@@ -98,9 +114,14 @@ while [ $WAITED -lt $MAX_WAIT ]; do
 done
 exec yarn --cwd /app/nocobase start`;
 
+const DEFAULT_WORKER_MODE = 'workflow:process,async-task:process';
+
+const COMMON_WORKER_MODES = getCommonWorkerProcesses();
+const ALL_WORKER_MODE = { name: '*', label: 'All processes', description: 'Consume every worker process' };
+
 const DEFAULT_WORKER_ENV = {
   APP_ROLE: 'worker',
-  WORKER_MODE: '*',
+  WORKER_MODE: DEFAULT_WORKER_MODE,
   APP_PORT: '13000',
   SKILL_HUB_SANDBOX: 'false',
 };
@@ -161,6 +182,21 @@ function parseJsonText(value: string | undefined, fallback: any, label: string)
   }
 }
 
+function splitWorkerMode(value?: string): string[] {
+  return workerModeTokens(value);
+}
+
+function getStackWorkerMode(stack?: StackInfo | null, fallback = '*'): string {
+  return normalizeWorkerMode(stack?.workerMode || stack?.envVars?.WORKER_MODE || fallback) || '';
+}
+
+function shortWorkerMode(workerMode: string): string {
+  if (workerMode.length <= 46) {
+    return workerMode;
+  }
+  return `${workerMode.slice(0, 43)}...`;
+}
+
 function stackToFormValues(stack?: StackInfo | null) {
   if (!stack) {
     return {
@@ -168,6 +204,7 @@ function stackToFormValues(stack?: StackInfo | null) {
       adapter: 'kubernetes',
       image: 'nocobase/nocobase:2.1.6-full',
       command: DEFAULT_WORKER_COMMAND,
+      workerMode: splitWorkerMode(DEFAULT_WORKER_MODE),
       envVars: jsonText(DEFAULT_WORKER_ENV, {}),
       resourceLimits: jsonText({ memory: '1536Mi' }, {}),
       desiredReplicas: 1,
@@ -187,6 +224,7 @@ function stackToFormValues(stack?: StackInfo | null) {
 
   return {
     ...stack,
+    workerMode: splitWorkerMode(getStackWorkerMode(stack)),
     envVars: jsonText(stack.envVars, {}),
     resourceLimits: jsonText(stack.resourceLimits, {}),
     k8sEnv: jsonText(stack.k8sEnv, []),
@@ -197,9 +235,25 @@ function stackToFormValues(stack?: StackInfo | null) {
 }
 
 function formValuesToStack(values: any) {
+  const workerMode = normalizeWorkerMode(values.workerMode);
+  if (!workerMode) {
+    throw new Error('Select at least one process or queue');
+  }
+  if (workerMode.split(',').includes('!')) {
+    throw new Error('Container worker stacks cannot include app process "!"');
+  }
+
+  const envVars = parseJsonText(values.envVars, {}, 'Environment variables');
+  envVars.APP_ROLE = envVars.APP_ROLE || 'worker';
+  envVars.WORKER_MODE = workerMode;
+  if (envVars.SKILL_HUB_SANDBOX === undefined) {
+    envVars.SKILL_HUB_SANDBOX = 'false';
+  }
+
   return {
     ...values,
-    envVars: parseJsonText(values.envVars, {}, 'Environment variables'),
+    workerMode,
+    envVars,
     resourceLimits: parseJsonText(values.resourceLimits, {}, 'Resource limits'),
     k8sEnv: parseJsonText(values.k8sEnv, [], 'Kubernetes env'),
     k8sEnvFrom: parseJsonText(values.k8sEnvFrom, [], 'Kubernetes envFrom'),
@@ -237,6 +291,21 @@ export function ContainerOrchestrator() {
   const [settingsForm] = Form.useForm();
   const [stackForm] = Form.useForm();
   const [dockerNetworks, setDockerNetworks] = useState<{ id: string; name: string }[]>([]);
+  const [queueOptions, setQueueOptions] = useState<DiscoveredQueue[]>([]);
+  const [queuesLoading, setQueuesLoading] = useState(false);
+
+  const fetchQueues = useCallback(async () => {
+    setQueuesLoading(true);
+    try {
+      const res = await api.request({ url: '/workerQueueMappings:scanQueues' });
+      const data = res.data?.data || res.data;
+      setQueueOptions(Array.isArray(data?.discovered) ? data.discovered : []);
+    } catch {
+      setQueueOptions([]);
+    } finally {
+      setQueuesLoading(false);
+    }
+  }, [api]);
 
   // Fetch Docker networks
   const fetchNetworks = useCallback(async () => {
@@ -329,6 +398,7 @@ export function ContainerOrchestrator() {
     setStackModal({ visible: true, stack: stack || null });
     stackForm.setFieldsValue(stackToFormValues(stack));
     fetchNetworks();
+    fetchQueues();
   };
 
   const closeStackModal = () => {
@@ -370,7 +440,8 @@ export function ContainerOrchestrator() {
     fetchPing();
     fetchStacks();
     fetchSettings();
-  }, [fetchPing, fetchStacks, fetchSettings]);
+    fetchQueues();
+  }, [fetchPing, fetchStacks, fetchSettings, fetchQueues]);
 
   // Load containers for each stack and poll every 10s
   useEffect(() => {
@@ -517,6 +588,8 @@ export function ContainerOrchestrator() {
       width: 160,
       render: (_: any, record: ContainerInfo & { _stackId?: number }) => {
         const isK8s = pingResult?.adapter === 'kubernetes';
+        const stackId = record._stackId;
+        if (!stackId) return null;
         return (
           <Space size="small">
             {!isK8s &&
@@ -526,7 +599,7 @@ export function ContainerOrchestrator() {
                     size="small"
                     type="text"
                     icon={<PauseCircleOutlined />}
-                    onClick={() => handleAction('stop', record.id, record._stackId!)}
+                    onClick={() => handleAction('stop', record.id, stackId)}
                   />
                 </Tooltip>
               ) : (
@@ -535,7 +608,7 @@ export function ContainerOrchestrator() {
                     size="small"
                     type="text"
                     icon={<PlayCircleOutlined style={{ color: '#52c41a' }} />}
-                    onClick={() => handleAction('start', record.id, record._stackId!)}
+                    onClick={() => handleAction('start', record.id, stackId)}
                   />
                 </Tooltip>
               ))}
@@ -544,12 +617,12 @@ export function ContainerOrchestrator() {
                 size="small"
                 type="text"
                 icon={<FileTextOutlined />}
-                onClick={() => handleViewLogs(record.id, record._stackId!)}
+                onClick={() => handleViewLogs(record.id, stackId)}
               />
             </Tooltip>
             <Popconfirm
               title={t('Remove this container?')}
-              onConfirm={() => handleAction('remove', record.id, record._stackId!)}
+              onConfirm={() => handleAction('remove', record.id, stackId)}
             >
               <Tooltip title={t('Remove')}>
                 <Button size="small" type="text" danger icon={<DeleteOutlined />} />
@@ -561,6 +634,23 @@ export function ContainerOrchestrator() {
     },
   ];
 
+  const workerModeSelectOptions = Array.from(
+    new Map(
+      [ALL_WORKER_MODE, ...COMMON_WORKER_MODES, ...queueOptions].map((queue) => {
+        const workerProcessName = 'workerProcessName' in queue ? queue.workerProcessName : undefined;
+        const processName = workerProcessName || resolveWorkerProcessName(queue.name);
+        return [
+          processName,
+          {
+            value: processName,
+            label: `${queue.label} (${processName})`,
+            title: queue.name === processName ? queue.description : `${queue.description} - alias: ${queue.name}`,
+          },
+        ];
+      }),
+    ).values(),
+  );
+
   if (!pingResult) {
     return (
       <Spin
@@ -646,6 +736,7 @@ export function ContainerOrchestrator() {
           {stacks.map((stack) => {
             const stackContainers = (containers[stack.id] || []).map((c) => ({ ...c, _stackId: stack.id }));
             const meta = containerMeta[stack.id] || {};
+            const workerMode = getStackWorkerMode(stack);
 
             return (
               <Card
@@ -655,6 +746,9 @@ export function ContainerOrchestrator() {
                     <CloudServerOutlined />
                     <span>{stack.name}</span>
                     <Tag>{stack.adapter}</Tag>
+                    <Tooltip title={workerMode}>
+                      <Tag color={workerMode === '*' ? 'orange' : 'geekblue'}>{shortWorkerMode(workerMode)}</Tag>
+                    </Tooltip>
                   </Space>
                 }
                 extra={
@@ -830,6 +924,46 @@ export function ContainerOrchestrator() {
             </Col>
           </Row>
 
+          <Form.Item
+            name="workerMode"
+            label={t('Processes / queues')}
+            extra={t('Saved as WORKER_MODE. Use tags for custom process keys that are not discovered yet.')}
+            rules={[
+              {
+                validator: (_: unknown, value: string[] | string | undefined) =>
+                  normalizeWorkerMode(value)
+                    ? Promise.resolve()
+                    : Promise.reject(new Error(t('Select at least one process or queue'))),
+              },
+            ]}
+          >
+            <Select
+              mode="tags"
+              loading={queuesLoading}
+              options={workerModeSelectOptions}
+              placeholder={DEFAULT_WORKER_MODE}
+              tokenSeparators={[',']}
+              showSearch
+            />
+          </Form.Item>
+
+          <Form.Item noStyle shouldUpdate={(prev, curr) => prev.workerMode !== curr.workerMode}>
+            {() => {
+              const workerMode = normalizeWorkerMode(stackForm.getFieldValue('workerMode')) || '';
+              if (!workerMode.includes('*')) {
+                return null;
+              }
+              return (
+                <Alert
+                  type="warning"
+                  showIcon
+                  style={{ marginBottom: 16 }}
+                  message={t('WORKER_MODE=* makes this stack consume every queue. Prefer explicit queues in HA.')}
+                />
+              );
+            }}
+          </Form.Item>
+
           {/* Row 3: Deployment name | Service account | Image pull policy */}
           <Row gutter={12}>
             <Col span={8}>
@@ -899,7 +1033,11 @@ export function ContainerOrchestrator() {
 
           <Row gutter={12}>
             <Col span={12}>
-              <Form.Item name="envVars" label={t('Environment variables JSON')}>
+              <Form.Item
+                name="envVars"
+                label={t('Environment variables JSON')}
+                extra={t('WORKER_MODE is managed by Processes / queues above.')}
+              >
                 <Input.TextArea rows={8} />
               </Form.Item>
             </Col>

package/src/client/QueueAssignment.tsx

@@ -35,6 +35,7 @@ interface DiscoveredQueue {
   description: string;
   type: 'event-queue' | 'redis-list';
   pending: number | null;
+  workerProcessName?: string;
 }
 
 interface RegisteredMapping {
@@ -208,7 +209,12 @@ export function QueueAssignment() {
           ) : (
             <MinusCircleOutlined style={{ color: '#52c41a' }} />
           )}
-          <Text code>{name}</Text>
+          <Space direction="vertical" size={0}>
+            <Text code>{name}</Text>
+            {record.workerProcessName && record.workerProcessName !== name ? (
+              <Text type="secondary">{record.workerProcessName}</Text>
+            ) : null}
+          </Space>
         </Space>
       ),
     },
@@ -306,7 +312,9 @@ export function QueueAssignment() {
           <Col>
             <Space>
               <Text strong>{t('Queue Assignment')}</Text>
-              <Text type="secondary">{t('Map queues to worker stacks. Unassigned queues run on all workers.')}</Text>
+              <Text type="secondary">
+                {t('Fallback mapping for legacy stacks without explicit Processes / queues.')}
+              </Text>
             </Space>
           </Col>
           <Col>

package/src/locale/en-US.json

@@ -188,10 +188,16 @@
   "Package": "Package",
   "DB Version": "DB Version",
   "Runtime Versions": "Runtime Versions",
-  "Queue Assignment": "Queue Assignment",
-  "Queue Name": "Queue Name",
-  "Map queues to worker stacks. Unassigned queues run on all workers.": "Map queues to worker stacks. Unassigned queues run on all workers.",
-  "Scan Queues": "Scan Queues",
+  "Queue Assignment": "Queue Assignment",
+  "Queue Name": "Queue Name",
+  "Map queues to worker stacks. Unassigned queues run on all workers.": "Map queues to worker stacks. Unassigned queues run on all workers.",
+  "Fallback mapping for legacy stacks without explicit Processes / queues.": "Fallback mapping for legacy stacks without explicit Processes / queues.",
+  "Processes / queues": "Processes / queues",
+  "Saved as WORKER_MODE. Use tags for custom process keys that are not discovered yet.": "Saved as WORKER_MODE. Use tags for custom process keys that are not discovered yet.",
+  "Select at least one process or queue": "Select at least one process or queue",
+  "WORKER_MODE=* makes this stack consume every queue. Prefer explicit queues in HA.": "WORKER_MODE=* makes this stack consume every queue. Prefer explicit queues in HA.",
+  "WORKER_MODE is managed by Processes / queues above.": "WORKER_MODE is managed by Processes / queues above.",
+  "Scan Queues": "Scan Queues",
   "Auto-map ({count})": "Auto-map ({count})",
   "Register": "Register",
   "Unregister": "Unregister",
@@ -201,5 +207,9 @@
   "No queues discovered. Click \"Scan Queues\" to detect registered queues.": "No queues discovered. Click \"Scan Queues\" to detect registered queues.",
   "Auto-mapped {count} queue(s)": "Auto-mapped {count} queue(s)",
   "Queue Assignment updated": "Queue Assignment updated",
-  "Unassigned (worker runs all queues)": "Unassigned (worker runs all queues)"
-}
+  "Unassigned (worker runs all queues)": "Unassigned (worker runs all queues)",
+  "Cluster registry has no worker heartbeats": "Cluster registry has no worker heartbeats",
+  "Cluster registry Redis is not configured": "Cluster registry Redis is not configured",
+  "Cluster Nodes reads Redis heartbeats, not the container runtime. Check worker boot, plugin-cluster-manager, and shared Redis configuration.": "Cluster Nodes reads Redis heartbeats, not the container runtime. Check worker boot, plugin-cluster-manager, and shared Redis configuration.",
+  "Set REDIS_URL or CLUSTER_MANAGER_REDIS_URL on every app and worker to enable cluster node discovery.": "Set REDIS_URL or CLUSTER_MANAGER_REDIS_URL on every app and worker to enable cluster node discovery."
+}

package/src/locale/vi-VN.json

@@ -157,10 +157,16 @@
   "Deprecated multi-app share collection is active. Avoid schema/table sharing for new cluster deployments.": "Deprecated multi-app share collection is active. Avoid schema/table sharing for new cluster deployments.",
   "{count} legacy application record(s) were found in the applications collection.": "{count} legacy application record(s) were found in the applications collection.",
   "App Supervisor is not enabled. Use it for new multi-application management instead of deprecated multi-app plugins.": "App Supervisor is not enabled. Use it for new multi-application management instead of deprecated multi-app plugins.",
-  "Queue Assignment": "Gán hàng đợi",
-  "Queue Name": "Tên hàng đợi",
-  "Map queues to worker stacks. Unassigned queues run on all workers.": "Gán hàng đợi vào worker stack. Hàng đợi chưa gán sẽ chạy trên tất cả worker.",
-  "Scan Queues": "Quét hàng đợi",
+  "Queue Assignment": "Gán hàng đợi",
+  "Queue Name": "Tên hàng đợi",
+  "Map queues to worker stacks. Unassigned queues run on all workers.": "Gán hàng đợi vào worker stack. Hàng đợi chưa gán sẽ chạy trên tất cả worker.",
+  "Fallback mapping for legacy stacks without explicit Processes / queues.": "Mapping dự phòng cho các stack cũ chưa cấu hình Processes / queues rõ ràng.",
+  "Processes / queues": "Processes / queues",
+  "Saved as WORKER_MODE. Use tags for custom process keys that are not discovered yet.": "Được lưu thành WORKER_MODE. Có thể nhập tag cho process key tùy chỉnh chưa được phát hiện.",
+  "Select at least one process or queue": "Chọn ít nhất một process hoặc queue",
+  "WORKER_MODE=* makes this stack consume every queue. Prefer explicit queues in HA.": "WORKER_MODE=* khiến stack này tiêu thụ mọi queue. Nên chọn queue rõ ràng trong HA.",
+  "WORKER_MODE is managed by Processes / queues above.": "WORKER_MODE được quản lý bởi Processes / queues ở trên.",
+  "Scan Queues": "Quét hàng đợi",
   "Auto-map ({count})": "Tự động gán ({count})",
   "Register": "Đăng ký",
   "Unregister": "Hủy đăng ký",
@@ -202,5 +208,9 @@
   "Log Files": "Log Files",
   "Package": "Package",
   "DB Version": "DB Version",
-  "Runtime Versions": "Runtime Versions"
-}
+  "Runtime Versions": "Runtime Versions",
+  "Cluster registry has no worker heartbeats": "Registry cụm chưa có heartbeat từ worker",
+  "Cluster registry Redis is not configured": "Chưa cấu hình Redis cho registry cụm",
+  "Cluster Nodes reads Redis heartbeats, not the container runtime. Check worker boot, plugin-cluster-manager, and shared Redis configuration.": "Cluster Nodes đọc heartbeat trong Redis, không đọc trực tiếp container runtime. Hãy kiểm tra worker đã boot, plugin-cluster-manager đã load, và cấu hình Redis dùng chung.",
+  "Set REDIS_URL or CLUSTER_MANAGER_REDIS_URL on every app and worker to enable cluster node discovery.": "Thiết lập REDIS_URL hoặc CLUSTER_MANAGER_REDIS_URL trên mọi app và worker để bật khám phá node trong cụm."
+}

package/src/locale/zh-CN.json

@@ -190,10 +190,16 @@
   "Package": "Package",
   "DB Version": "DB Version",
   "Runtime Versions": "Runtime Versions",
-  "Queue Assignment": "队列分配",
-  "Queue Name": "队列名称",
-  "Map queues to worker stacks. Unassigned queues run on all workers.": "将队列映射到工作节点栈。未分配的队列将在所有工作节点上运行。",
-  "Scan Queues": "扫描队列",
+  "Queue Assignment": "队列分配",
+  "Queue Name": "队列名称",
+  "Map queues to worker stacks. Unassigned queues run on all workers.": "将队列映射到工作节点栈。未分配的队列将在所有工作节点上运行。",
+  "Fallback mapping for legacy stacks without explicit Processes / queues.": "用于没有显式进程/队列配置的旧工作栈的兜底映射。",
+  "Processes / queues": "进程 / 队列",
+  "Saved as WORKER_MODE. Use tags for custom process keys that are not discovered yet.": "保存为 WORKER_MODE。可用标签输入尚未发现的自定义进程键。",
+  "Select at least one process or queue": "请至少选择一个进程或队列",
+  "WORKER_MODE=* makes this stack consume every queue. Prefer explicit queues in HA.": "WORKER_MODE=* 会让此工作栈消费所有队列。HA 环境建议显式选择队列。",
+  "WORKER_MODE is managed by Processes / queues above.": "WORKER_MODE 由上方的进程 / 队列配置管理。",
+  "Scan Queues": "扫描队列",
   "Auto-map ({count})": "自动映射 ({count})",
   "Register": "注册",
   "Unregister": "注销",
@@ -203,5 +209,9 @@
   "No queues discovered. Click \"Scan Queues\" to detect registered queues.": "未发现队列。点击\"扫描队列\"以检测已注册的队列。",
   "Auto-mapped {count} queue(s)": "已自动映射 {count} 个队列",
   "Queue Assignment updated": "队列分配已更新",
-  "Unassigned (worker runs all queues)": "未分配（工作节点运行所有队列）"
-}
+  "Unassigned (worker runs all queues)": "未分配（工作节点运行所有队列）",
+  "Cluster registry has no worker heartbeats": "集群注册表没有 worker 心跳",
+  "Cluster registry Redis is not configured": "未配置集群注册表 Redis",
+  "Cluster Nodes reads Redis heartbeats, not the container runtime. Check worker boot, plugin-cluster-manager, and shared Redis configuration.": "Cluster Nodes 读取 Redis 心跳，而不是直接读取容器运行时。请检查 worker 启动、plugin-cluster-manager 加载以及共享 Redis 配置。",
+  "Set REDIS_URL or CLUSTER_MANAGER_REDIS_URL on every app and worker to enable cluster node discovery.": "请在每个 app 和 worker 上设置 REDIS_URL 或 CLUSTER_MANAGER_REDIS_URL，以启用集群节点发现。"
+}

package/src/server/__tests__/worker-processes.test.ts

@@ -0,0 +1,42 @@
+import {
+  isWorkerOnlyMode,
+  normalizeWorkerMode,
+  resolveWorkerProcessName,
+  workerModeServesProcess,
+} from '../../shared/worker-processes';
+import { getNodeRoleFrom } from '../utils/node';
+
+describe('worker process resolver', () => {
+  it('normalizes process keys and queue aliases', () => {
+    expect(normalizeWorkerMode('workflow.pendingExecution, plugin-git-manager.review')).toBe(
+      'workflow:process,git-review:process',
+    );
+    expect(normalizeWorkerMode('main:plugin-build-guide-block:build:queue')).toBe('build-guide:process');
+    expect(normalizeWorkerMode('file-preview-auth.ocr.queue')).toBe('file-preview-auth:ocr');
+  });
+
+  it('lets wildcard win when mixed with explicit processes', () => {
+    expect(normalizeWorkerMode('workflow:process,*,git-review:process')).toBe('*');
+    expect(workerModeServesProcess('*,workflow:process', 'notification-manager.send')).toBe(true);
+  });
+
+  it('routes app and worker modes using NocoBase worker semantics', () => {
+    expect(isWorkerOnlyMode('!')).toBe(false);
+    expect(isWorkerOnlyMode('workflow:process')).toBe(true);
+    expect(isWorkerOnlyMode('workflow.pendingExecution')).toBe(true);
+    expect(workerModeServesProcess('workflow.pendingExecution', 'workflow:process')).toBe(true);
+    expect(workerModeServesProcess('workflow:process', 'plugin-git-manager.review')).toBe(false);
+    expect(workerModeServesProcess('file-preview-auth.ocr.queue', 'file-preview-auth:ocr')).toBe(true);
+  });
+
+  it('keeps unknown custom process keys stable', () => {
+    expect(resolveWorkerProcessName('custom-plugin:process')).toBe('custom-plugin:process');
+    expect(workerModeServesProcess('custom-plugin:process', 'custom-plugin:process')).toBe(true);
+  });
+
+  it('lets explicit APP_ROLE override worker mode for local node classification', () => {
+    expect(getNodeRoleFrom({ appRole: 'app', workerMode: '*' })).toBe('app');
+    expect(getNodeRoleFrom({ appRole: 'worker', workerMode: '!' })).toBe('worker');
+    expect(getNodeRoleFrom({ appRole: 'sandbox', workerMode: '!' })).toBe('sandbox');
+  });
+});

package/src/server/actions/cluster-nodes.ts

@@ -181,10 +181,13 @@ function getReferenceVersion(nodes: ClusterNodeRecord[]) {
   return [...counts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] || null;
 }
 
-async function getClusterNodes(ctx: Context): Promise<ClusterNodeRecord[]> {
+function getClusterRegistry(ctx: Context): RedisNodeRegistry {
   const plugin = (ctx.app as any).pm?.get?.('plugin-cluster-manager') as any;
-  const registry = plugin?.nodeRegistry ?? new RedisNodeRegistry(ctx.app);
-  return registry.getNodes();
+  return plugin?.nodeRegistry ?? new RedisNodeRegistry(ctx.app);
+}
+
+async function getClusterNodes(ctx: Context): Promise<ClusterNodeRecord[]> {
+  return getClusterRegistry(ctx).getNodes();
 }
 
 async function getExpectedPackages(ctx: Context): Promise<NormalizedPackages> {
@@ -267,6 +270,8 @@ export async function readLocalLogs(app: any, maxLines: number) {
     hostname: os.hostname(),
     pid: process.pid,
     workerMode: process.env.WORKER_MODE || 'main',
+    appRole: process.env.APP_ROLE || '',
+    isSandbox: process.env.SKILL_HUB_SANDBOX === 'true',
   };
 
   if (logFiles.length === 0) {
@@ -301,7 +306,12 @@ export const clusterActions = {
    */
   async current(ctx: Context, next: () => Promise<void>) {
     const currentMode = process.env.WORKER_MODE || 'main';
-    const isApp = !isWorkerMode(process.env.WORKER_MODE);
+    const isApp =
+      getNodeRoleFrom({
+        workerMode: process.env.WORKER_MODE,
+        appRole: process.env.APP_ROLE,
+        isSandbox: process.env.SKILL_HUB_SANDBOX === 'true',
+      }) === 'app';
 
     if (isApp) {
       // This process IS the APP node — return local data directly
@@ -315,6 +325,8 @@ export const clusterActions = {
           arch: process.arch,
           uptime: process.uptime(),
           workerMode: currentMode,
+          appRole: process.env.APP_ROLE || '',
+          isSandbox: process.env.SKILL_HUB_SANDBOX === 'true',
           appPort: process.env.APP_PORT || '',
           clusterMode: process.env.CLUSTER_MODE || '',
         },
@@ -337,7 +349,9 @@ export const clusterActions = {
       const plugin = (ctx.app as any).pm?.get?.('plugin-cluster-manager') as any;
       const registry = plugin?.nodeRegistry ?? new RedisNodeRegistry(ctx.app);
       const nodes = await registry.getNodes();
-      const appNode = nodes.find((n: any) => n.workerMode === 'main' || n.workerMode === '' || n.workerMode === 'app');
+      const appNode = nodes.find(
+        (n: any) => getNodeRoleFrom({ workerMode: n.workerMode, appRole: n.appRole, isSandbox: n.isSandbox }) === 'app',
+      );
 
       if (appNode?.nodeDetails) {
         ctx.body = appNode.nodeDetails;
@@ -353,6 +367,8 @@ export const clusterActions = {
             arch: process.arch,
             uptime: process.uptime(),
             workerMode: currentMode,
+            appRole: process.env.APP_ROLE || '',
+            isSandbox: process.env.SKILL_HUB_SANDBOX === 'true',
             appPort: process.env.APP_PORT || '',
             clusterMode: process.env.CLUSTER_MODE || '',
           },
@@ -385,7 +401,10 @@ export const clusterActions = {
   async list(ctx: Context, next: () => Promise<void>) {
     const environments: any[] = [];
 
-    const nodes = await getClusterNodes(ctx);
+    const registry = getClusterRegistry(ctx);
+    const nodes = await registry.getNodes();
+    const registryStatus = registry.getStatus();
+    let fallback = false;
 
     if (nodes && nodes.length > 0) {
       for (const env of nodes) {
@@ -399,6 +418,7 @@ export const clusterActions = {
           lastHeartbeatAt: env.lastHeartbeatAt ? new Date(env.lastHeartbeatAt).toISOString() : null,
           status: env.status || 'online',
           workerMode: env.workerMode,
+          appRole: env.appRole,
           isSandbox: env.isSandbox,
           pid: env.pid,
         });
@@ -407,18 +427,33 @@ export const clusterActions = {
 
     // If no discovery adapter or empty, at least return current node
     if (environments.length === 0) {
+      fallback = true;
+      const currentMode = process.env.WORKER_MODE || 'main';
+      const appName = process.env.APP_NAME || (ctx.app as any).name || 'main';
       environments.push({
-        name: os.hostname(),
+        id: getLocalNodeId(ctx.app),
+        name: `${appName} (${os.hostname()})`,
         hostname: os.hostname(),
         url: null,
         available: true,
         appVersion: null,
         lastHeartbeatAt: new Date().toISOString(),
         status: 'online',
+        workerMode: currentMode,
+        appRole: process.env.APP_ROLE || '',
+        isSandbox: process.env.SKILL_HUB_SANDBOX === 'true',
+        pid: process.pid,
       });
     }
 
-    ctx.body = { data: environments, meta: { count: environments.length } };
+    ctx.body = {
+      data: environments,
+      meta: {
+        count: environments.length,
+        fallback,
+        registry: registryStatus,
+      },
+    };
     await next();
   },