@nocobase/cli-v1 2.2.0-beta.9 → 3.0.0-alpha.1

package/nocobase.conf.tpl

@@ -36,10 +36,11 @@ server {
     gzip on;
     gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
 
-    location ~* ^{{publicPath}}storage/uploads/(.*\.(?:htm|html|svg|svgz|xhtml))$ {
+    location ~* ^{{publicPath}}storage/uploads/(.*\.(?:htm|html|pdf|svg|svgz|xht|xhtml|xml|xsl|xslt))$ {
         alias {{cwd}}/storage/uploads/$1;
         add_header Cache-Control "public";
         add_header Content-Disposition "attachment" always;
+        add_header Content-Security-Policy "sandbox" always;
         add_header X-Content-Type-Options "nosniff" always;
         access_log off;
         autoindex off;
@@ -48,6 +49,7 @@ server {
     location {{publicPath}}storage/uploads/ {
         alias {{cwd}}/storage/uploads/;
         add_header Cache-Control "public";
+        add_header Content-Security-Policy "sandbox" always;
         add_header X-Content-Type-Options "nosniff" always;
         access_log off;
         autoindex off;
@@ -55,6 +57,8 @@ server {
         location ~* \.md$ {
             default_type text/markdown;
             add_header Content-Disposition "inline";
+            add_header Content-Security-Policy "sandbox" always;
+            add_header X-Content-Type-Options "nosniff" always;
         }
     }
 
@@ -124,6 +128,34 @@ server {
         send_timeout 600;
     }
 
+    location ^~ {{settingsAssetsPath}} {
+        alias {{cwd}}/node_modules/@nocobase/app/dist/client/settings/assets/;
+        expires 365d;
+        add_header Cache-Control "public";
+        access_log off;
+        autoindex off;
+    }
+
+    # The standalone Settings SPA is a Client V2 surface. Keep this matcher
+    # narrow so legacy /admin/settings routes continue to use the v1 HTML.
+    location ~ {{settingsDocumentPattern}} {
+        proxy_pass http://127.0.0.1:{{apiPort}};
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $upstream_x_forwarded_proto;
+        proxy_set_header Host $final_host;
+        proxy_set_header Referer $http_referer;
+        proxy_set_header User-Agent $http_user_agent;
+        add_header Cache-Control 'no-cache, no-store';
+        proxy_cache_bypass $http_upgrade;
+        proxy_connect_timeout 600;
+        proxy_send_timeout 600;
+        proxy_read_timeout 600;
+        send_timeout 600;
+    }
+
     # RFC 8414 root-mounted discovery compatibility for path-based issuers/resources.
     location ~ ^/\.well-known/oauth-authorization-server/(.+)$ {
         rewrite ^/\.well-known/oauth-authorization-server/(.+)$ /$1/.well-known/oauth-authorization-server break;
@@ -163,7 +195,72 @@ server {
         send_timeout 600;
     }
 
+    # File access URLs are application routes. Keep them above the SPA
+    # locations so Nginx forwards them to the NocoBase gateway.
+    location ^~ {{publicPath}}files/ {
+        proxy_pass http://127.0.0.1:{{apiPort}};
+        proxy_http_version 1.1;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $upstream_x_forwarded_proto;
+        proxy_set_header Host $final_host;
+        proxy_set_header Referer $http_referer;
+        proxy_set_header User-Agent $http_user_agent;
+        add_header Cache-Control 'no-cache, no-store';
+        proxy_connect_timeout 600;
+        proxy_send_timeout 600;
+        proxy_read_timeout 600;
+        send_timeout 600;
+    }
+
+
+
+    location ^~ {{publicPath}}x/apps/ {
+        absolute_redirect off;
+
+        if ($uri ~ ^{{publicPath}}x/apps/(?<subapp>[A-Za-z0-9_-]+)/(?<portal>[A-Za-z0-9_-]+)$) {
+            return 308 {{publicPath}}x/apps/$subapp/$portal/$is_args$args;
+        }
+
+        if ($uri !~ ^{{publicPath}}x/apps/(?<subapp>[A-Za-z0-9_-]+)/(?<portal>[A-Za-z0-9_-]+)/(?<portal_path>.*)$) {
+            return 404;
+        }
 
+        root {{cwd}}/storage;
+
+        if ($portal_path = "") {
+            rewrite ^ /portals/$subapp/$portal/dist/index.html break;
+        }
+
+        try_files
+            /portals/$subapp/$portal/dist/$portal_path
+            /portals/$subapp/$portal/dist/$portal_path/
+            /portals/$subapp/$portal/dist/index.html
+            =404;
+    }
+
+    location ^~ {{publicPath}}x/ {
+        absolute_redirect off;
+
+        if ($uri ~ ^{{publicPath}}x/(?<portal>[A-Za-z0-9_-]+)$) {
+            return 308 {{publicPath}}x/$portal/$is_args$args;
+        }
+
+        if ($uri !~ ^{{publicPath}}x/(?<portal>[A-Za-z0-9_-]+)/(?<portal_path>.*)$) {
+            return 404;
+        }
+
+        root {{cwd}}/storage;
+
+        if ($portal_path = "") {
+            rewrite ^ /portals/main/$portal/dist/index.html break;
+        }
+
+        try_files
+            /portals/main/$portal/dist/$portal_path
+            /portals/main/$portal/dist/$portal_path/
+            /portals/main/$portal/dist/index.html
+            =404;
+    }
 
     location {{publicPath}} {
         alias {{cwd}}/node_modules/@nocobase/app/dist/client/;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/cli-v1",
-  "version": "2.2.0-beta.9",
+  "version": "3.0.0-alpha.1",
   "description": "",
   "license": "Apache-2.0",
   "main": "./src/index.js",
@@ -9,9 +9,9 @@
     "nocobase-v1": "./bin/index.js"
   },
   "dependencies": {
-    "@nocobase/cli": "2.2.0-beta.9",
+    "@nocobase/cli": "3.0.0-alpha.1",
     "@nocobase/license-kit": "^0.3.8",
-    "@nocobase/utils": "2.2.0-beta.9",
+    "@nocobase/utils": "3.0.0-alpha.1",
     "chalk": "^4.1.1",
     "commander": "^9.2.0",
     "deepmerge": "^4.3.1",
@@ -33,5 +33,5 @@
     "url": "git+https://github.com/nocobase/nocobase.git",
     "directory": "packages/core/cli"
   },
-  "gitHead": "60e3d7abbaa0c7cead76f71a4f3d5eedb6b8acdb"
+  "gitHead": "22d8be8ece179cfa5c8a4ebb2c896c92bd418e03"
 }

package/src/__tests__/build-index-html.test.js

@@ -24,6 +24,8 @@ function createAppPackageRoot() {
     [
       "window['__nocobase_app_dev__'] = {{env.NOCOBASE_APP_DEV}};",
       "window['__nocobase_public_path__'] = '{{env.APP_PUBLIC_PATH}}';",
+      "window['__nocobase_modern_client_prefix__'] = '{{env.APP_MODERN_CLIENT_PREFIX}}';",
+      "window['__nocobase_app_client_entry_mode__'] = '{{env.APP_CLIENT_ENTRY_MODE}}';",
     ].join('\n'),
     'utf-8',
   );
@@ -73,11 +75,43 @@ describe('cli-v1 buildIndexHtml', () => {
     process.env.APP_PACKAGE_ROOT = appRoot;
     process.env.APP_PUBLIC_PATH = '/';
     process.env.NOCOBASE_APP_DEV = '';
+    process.env.APP_MODERN_CLIENT_PREFIX = 'console';
+    process.env.APP_CLIENT_ENTRY_MODE = 'modern-default';
 
     buildIndexHtml();
 
     const html = fs.readFileSync(path.join(appRoot, 'dist/client/index.html'), 'utf-8');
     expect(html).toContain("window['__nocobase_app_dev__'] = false;");
+    expect(html).toContain("window['__nocobase_modern_client_prefix__'] = 'console';");
+    expect(html).toContain("window['__nocobase_app_client_entry_mode__'] = 'modern-default';");
+    fs.removeSync(appRoot);
+  });
+
+  test('refreshes cached tpl when new runtime placeholders are missing', () => {
+    const appRoot = createAppPackageRoot();
+    const tplPath = path.join(appRoot, 'dist/client/index.html.tpl');
+    const indexPath = path.join(appRoot, 'dist/client/index.html');
+    fs.writeFileSync(tplPath, "window['__nocobase_public_path__'] = '{{env.APP_PUBLIC_PATH}}';", 'utf-8');
+    fs.writeFileSync(
+      indexPath,
+      [
+        "window['__nocobase_public_path__'] = '{{env.APP_PUBLIC_PATH}}';",
+        "window['__nocobase_modern_client_prefix__'] = '{{env.APP_MODERN_CLIENT_PREFIX}}';",
+        "window['__nocobase_app_client_entry_mode__'] = '{{env.APP_CLIENT_ENTRY_MODE}}';",
+      ].join('\n'),
+      'utf-8',
+    );
+    process.argv = ['node', 'nocobase-v1', 'start'];
+    process.env.APP_PACKAGE_ROOT = appRoot;
+    process.env.APP_PUBLIC_PATH = '/';
+    process.env.APP_MODERN_CLIENT_PREFIX = 'v';
+    process.env.APP_CLIENT_ENTRY_MODE = 'modern-only';
+
+    buildIndexHtml();
+
+    const tpl = fs.readFileSync(tplPath, 'utf-8');
+    expect(tpl).toContain('__nocobase_modern_client_prefix__');
+    expect(tpl).toContain('__nocobase_app_client_entry_mode__');
     fs.removeSync(appRoot);
   });
 });

package/src/__tests__/client-extract.test.js

@@ -0,0 +1,55 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+/* eslint-env jest */
+
+const fs = require('fs-extra');
+const os = require('os');
+const path = require('path');
+const { renderExtractedClientIndexHtml } = require('../commands/client');
+
+describe('cli-v1 client:extract', () => {
+  const originalEnv = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  test('renders extracted root index with the current client entry mode', () => {
+    const target = fs.mkdtempSync(path.join(os.tmpdir(), 'nocobase-client-extract-'));
+    fs.writeFileSync(
+      path.join(target, 'index.html.tpl'),
+      [
+        '<html><head>',
+        "<script>window['__webpack_public_path__'] = '{{env.CDN_BASE_URL}}';",
+        "window['__nocobase_public_path__'] = '{{env.APP_PUBLIC_PATH}}';",
+        "window['__nocobase_modern_client_prefix__'] = '{{env.APP_MODERN_CLIENT_PREFIX}}';",
+        "window['__nocobase_app_client_entry_mode__'] = '{{env.APP_CLIENT_ENTRY_MODE}}';</script>",
+        '<script src="{{env.APP_PUBLIC_PATH}}browser-checker.js?v=1"></script>',
+        '<script type="module" src="assets/runtime.js"></script>',
+        '</head><body></body></html>',
+      ].join(''),
+      'utf-8',
+    );
+
+    process.env.APP_PUBLIC_PATH = '/';
+    process.env.APP_MODERN_CLIENT_PREFIX = 'v';
+    process.env.APP_CLIENT_ENTRY_MODE = 'modern-only';
+    delete process.env.CDN_BASE_URL;
+
+    expect(renderExtractedClientIndexHtml(target, '2.2.0-beta.15')).toBe(true);
+
+    const html = fs.readFileSync(path.join(target, 'index.html'), 'utf-8');
+    expect(html).toContain("window['__nocobase_app_client_entry_mode__'] = 'modern-only';");
+    expect(html).toContain("window['__webpack_public_path__'] = '/dist/2.2.0-beta.15/';");
+    expect(html).toContain('src="/dist/2.2.0-beta.15/browser-checker.js?v=1"');
+    expect(html).toContain('src="/dist/2.2.0-beta.15/assets/runtime.js"');
+    fs.removeSync(target);
+  });
+});

package/src/__tests__/create-nginx-conf.test.js

@@ -0,0 +1,68 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+/* eslint-env jest */
+
+const fs = require('fs-extra');
+const os = require('os');
+const path = require('path');
+
+const registerCreateNginxConf = require('../commands/create-nginx-conf');
+
+describe('create-nginx-conf Settings SPA routing', () => {
+  const originalEnv = { ...process.env };
+  let storagePath;
+
+  afterEach(async () => {
+    process.env = { ...originalEnv };
+    if (storagePath) {
+      await fs.remove(storagePath);
+      storagePath = undefined;
+    }
+  });
+
+  async function renderConfig(appPublicPath) {
+    storagePath = await fs.mkdtemp(path.join(os.tmpdir(), 'nocobase-nginx-settings-'));
+    process.env.APP_PUBLIC_PATH = appPublicPath;
+    process.env.APP_MODERN_CLIENT_PREFIX = 'v';
+    process.env.APP_PORT = '13000';
+    process.env.STORAGE_PATH = storagePath;
+
+    let action;
+    registerCreateNginxConf({
+      command() {
+        return {
+          action(callback) {
+            action = callback;
+          },
+        };
+      },
+    });
+    await action();
+    return await fs.readFile(path.join(storagePath, 'nocobase.conf'), 'utf8');
+  }
+
+  test.each([
+    ['root mount', '/', '/settings/assets/', '^/settings(?:/|$)'],
+    ['custom public path', '/nocobase/', '/nocobase/settings/assets/', '^/nocobase/settings(?:/|$)'],
+  ])(
+    'proxies Settings documents and caches Settings assets for %s',
+    async (_label, publicPath, assetsPath, routePattern) => {
+      const config = await renderConfig(publicPath);
+
+      expect(config).toContain(`location ^~ ${assetsPath} {`);
+      expect(config).toContain('dist/client/settings/assets/;');
+      expect(config).toContain('expires 365d;');
+      expect(config).toContain(`location ~ ${routePattern} {`);
+      expect(config).toContain('proxy_pass http://127.0.0.1:13000;');
+      expect(config).not.toContain('location ~ ^/admin/settings');
+      expect(config).toContain('try_files $uri $uri/ /index.html;');
+    },
+  );
+});

package/src/__tests__/dev-command.test.js

@@ -9,13 +9,28 @@
 
 /* eslint-env jest */
 
-const { buildAppDevForwardArgs, forwardDevToAppDev } = require('../commands/dev')._test;
+const {
+  buildAppDevForwardArgs,
+  createSettingsDevProcessOptions,
+  forwardDevToAppDev,
+  resolveDevRuntimeMode,
+  resolveSettingsDevPort,
+} = require('../commands/dev')._test;
 
 describe('cli-v1 dev command', () => {
   test('buildAppDevForwardArgs rewrites dev argv to app-dev while preserving extra args', () => {
     expect(
-      buildAppDevForwardArgs(['node', 'nocobase-v1', 'dev', '--rsbuild', '--port', '13000', '--inspect=9229']),
-    ).toEqual(['app-dev', '--rsbuild', '--port', '13000', '--inspect=9229']);
+      buildAppDevForwardArgs([
+        'node',
+        'nocobase-v1',
+        'dev',
+        '--rsbuild',
+        '--quickstart',
+        '--port',
+        '13000',
+        '--inspect=9229',
+      ]),
+    ).toEqual(['app-dev', '--rsbuild', '--quickstart', '--port', '13000', '--inspect=9229']);
   });
 
   test('forwardDevToAppDev delegates to nocobase-v1 app-dev for create-app projects', async () => {
@@ -31,4 +46,63 @@ describe('cli-v1 dev command', () => {
 
     expect(calls).toEqual([['nocobase-v1', ['app-dev', '--port', '13000', '--db-sync']]]);
   });
+
+  test('resolveDevRuntimeMode keeps both clients in legacy-default', () => {
+    expect(resolveDevRuntimeMode({ appClientEntryMode: 'legacy-default' })).toMatchObject({
+      useModernOnlyEntryMode: false,
+      shouldRunClient: true,
+      shouldRunClientV2: true,
+      shouldRunSettings: true,
+      shouldRunServer: true,
+    });
+  });
+
+  test('resolveDevRuntimeMode only runs v2 client and server in modern-only', () => {
+    expect(resolveDevRuntimeMode({ appClientEntryMode: 'modern-only' })).toMatchObject({
+      useModernOnlyEntryMode: true,
+      shouldRunClient: false,
+      shouldRunClientV2: true,
+      shouldRunSettings: true,
+      shouldRunServer: true,
+    });
+  });
+
+  test('resolveDevRuntimeMode preserves explicit client-v2-only flag behavior', () => {
+    expect(resolveDevRuntimeMode({ clientV2Only: true, appClientEntryMode: 'legacy-default' })).toMatchObject({
+      useModernOnlyEntryMode: false,
+      shouldRunClient: false,
+      shouldRunClientV2: true,
+      shouldRunSettings: true,
+      shouldRunServer: false,
+    });
+  });
+
+  test('resolveSettingsDevPort reserves APP_PORT + 3 by default', () => {
+    expect(resolveSettingsDevPort(13001)).toBe(13004);
+  });
+
+  test('createSettingsDevProcessOptions uses the standalone config and settings HMR path', () => {
+    expect(
+      createSettingsDevProcessOptions({
+        appPackageRoot: '/repo/packages/core/app',
+        appPort: 13001,
+        settingsPort: 13004,
+        browserPort: 13001,
+        appPublicPath: '/nocobase/',
+        processEnv: { API_BASE_URL: '/api/' },
+      }),
+    ).toMatchObject({
+      command: 'rsbuild',
+      args: ['dev', '--config', '/repo/packages/core/app/client-settings/rsbuild.config.ts'],
+      runOptions: {
+        prefix: 'client-settings',
+        env: {
+          APP_PORT: '13001',
+          APP_SETTINGS_PORT: '13004',
+          RSPACK_HMR_CLIENT_PORT: '13001',
+          RSPACK_HMR_PATH: '/nocobase/settings/__rspack_hmr',
+        },
+      },
+    });
+  });
 });

package/src/__tests__/util.test.js

@@ -9,9 +9,14 @@
 
 /* eslint-env jest */
 
+const { normalizeModernClientPrefix } = require('../util');
 const { colorizedDevLogEnv, createRunWithPrefixLabel } = require('../util')._test;
 
 describe('cli-v1 util helpers', () => {
+  test('normalizeModernClientPrefix reserves the Settings SPA path', () => {
+    expect(() => normalizeModernClientPrefix('/settings/')).toThrow('APP_MODERN_CLIENT_PREFIX "settings" is reserved');
+  });
+
   test('colorizedDevLogEnv enables color for dev child output by default', () => {
     expect(colorizedDevLogEnv({})).toEqual({ FORCE_COLOR: '1' });
   });

package/src/commands/client.js

@@ -11,7 +11,100 @@ const chalk = require('chalk');
 const fs = require('fs-extra');
 const { resolve } = require('path');
 const { discoverPluginPackages } = require('@nocobase/utils/plugin-package');
-const { storagePathJoin } = require('../util');
+const {
+  normalizeModernClientPrefix,
+  resolveAppClientEntryMode,
+  resolvePublicPath,
+  storagePathJoin,
+} = require('../util');
+
+function replaceRuntimeEnvPlaceholders(data, values) {
+  return data
+    .replace(/\{\{env.CDN_BASE_URL\}\}/g, values.CDN_BASE_URL)
+    .replace(/\{\{env.APP_PUBLIC_PATH\}\}/g, values.APP_PUBLIC_PATH)
+    .replace(/\{\{env.APP_MODERN_CLIENT_PREFIX\}\}/g, values.APP_MODERN_CLIENT_PREFIX)
+    .replace(/\{\{env.APP_CLIENT_ENTRY_MODE\}\}/g, values.APP_CLIENT_ENTRY_MODE)
+    .replace(/\{\{env.API_CLIENT_SHARE_TOKEN\}\}/g, values.API_CLIENT_SHARE_TOKEN)
+    .replace(/\{\{env.API_CLIENT_STORAGE_TYPE\}\}/g, values.API_CLIENT_STORAGE_TYPE)
+    .replace(/\{\{env.API_CLIENT_STORAGE_PREFIX\}\}/g, values.API_CLIENT_STORAGE_PREFIX)
+    .replace(/\{\{env.API_BASE_URL\}\}/g, values.API_BASE_URL)
+    .replace(/\{\{env.WS_URL\}\}/g, values.WS_URL)
+    .replace(/\{\{env.WS_PATH\}\}/g, values.WS_PATH)
+    .replace(/\{\{env.NOCOBASE_APP_DEV\}\}/g, values.NOCOBASE_APP_DEV)
+    .replace(/\{\{env.ESM_CDN_BASE_URL\}\}/g, values.ESM_CDN_BASE_URL)
+    .replace(/\{\{env.ESM_CDN_SUFFIX\}\}/g, values.ESM_CDN_SUFFIX);
+}
+
+function replaceRuntimeAssignment(data, key, value) {
+  const literal =
+    typeof value === 'boolean' ? String(value) : `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+  const assignment = `window['${key}'] = ${literal};`;
+  const pattern = new RegExp(`window\\['${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}'\\]\\s*=\\s*[^;]*;`);
+
+  return pattern.test(data) ? data.replace(pattern, assignment) : data;
+}
+
+function renderExtractedClientIndexHtml(target, version) {
+  const indexPath = resolve(target, 'index.html');
+  const tplPath = resolve(target, 'index.html.tpl');
+  if (!fs.existsSync(indexPath) && !fs.existsSync(tplPath)) {
+    return false;
+  }
+
+  const appPublicPath = resolvePublicPath(process.env.APP_PUBLIC_PATH || '/');
+  const cdnBaseUrl =
+    process.env.CDN_BASE_URL || `${appPublicPath.replace(/\/$/, '')}/dist/${version}/`.replace(/^\/\//, '/');
+  const values = {
+    CDN_BASE_URL: cdnBaseUrl,
+    APP_PUBLIC_PATH: appPublicPath,
+    APP_MODERN_CLIENT_PREFIX: normalizeModernClientPrefix(process.env.APP_MODERN_CLIENT_PREFIX),
+    APP_CLIENT_ENTRY_MODE: resolveAppClientEntryMode(),
+    API_CLIENT_SHARE_TOKEN: process.env.API_CLIENT_SHARE_TOKEN || 'false',
+    API_CLIENT_STORAGE_TYPE: process.env.API_CLIENT_STORAGE_TYPE || 'localStorage',
+    API_CLIENT_STORAGE_PREFIX: process.env.API_CLIENT_STORAGE_PREFIX || 'NOCOBASE_',
+    API_BASE_URL: process.env.API_BASE_URL || process.env.API_BASE_PATH || '/api/',
+    WS_URL: process.env.WEBSOCKET_URL || '',
+    WS_PATH: process.env.WS_PATH || '/ws',
+    NOCOBASE_APP_DEV: 'false',
+    ESM_CDN_BASE_URL: process.env.ESM_CDN_BASE_URL || 'https://esm.sh',
+    ESM_CDN_SUFFIX: process.env.ESM_CDN_SUFFIX || '',
+  };
+  const sourcePath = fs.existsSync(tplPath) ? tplPath : indexPath;
+  let data = replaceRuntimeEnvPlaceholders(fs.readFileSync(sourcePath, 'utf-8'), values)
+    .replace(/((?:src|href)=")(?:\.\/)?assets\//g, `$1${values.APP_PUBLIC_PATH}assets/`)
+    .replace(/((?:src|href)=")\/assets\//g, `$1${values.APP_PUBLIC_PATH}assets/`)
+    .replace('src="/umi.', `src="${values.APP_PUBLIC_PATH}umi.`)
+    .replace(/((?:src|href)="[^"]*?)\/{2,}(assets\/)/g, '$1/$2');
+
+  if (values.CDN_BASE_URL) {
+    const appBaseUrl = values.CDN_BASE_URL.replace(/\/+$/, '');
+    const publicPath = values.APP_PUBLIC_PATH.replace(/\/+$/, '');
+    data = data
+      .replace(new RegExp(`src="${publicPath}/`, 'g'), `src="${appBaseUrl}/`)
+      .replace(new RegExp(`href="${publicPath}/`, 'g'), `href="${appBaseUrl}/`);
+  }
+
+  data = replaceRuntimeAssignment(data, '__webpack_public_path__', values.CDN_BASE_URL);
+  data = replaceRuntimeAssignment(data, '__nocobase_public_path__', values.APP_PUBLIC_PATH);
+  data = replaceRuntimeAssignment(data, '__nocobase_modern_client_prefix__', values.APP_MODERN_CLIENT_PREFIX);
+  data = replaceRuntimeAssignment(data, '__nocobase_app_client_entry_mode__', values.APP_CLIENT_ENTRY_MODE);
+  data = replaceRuntimeAssignment(data, '__nocobase_api_base_url__', values.API_BASE_URL);
+  data = replaceRuntimeAssignment(data, '__nocobase_api_client_storage_prefix__', values.API_CLIENT_STORAGE_PREFIX);
+  data = replaceRuntimeAssignment(data, '__nocobase_api_client_storage_type__', values.API_CLIENT_STORAGE_TYPE);
+  data = replaceRuntimeAssignment(
+    data,
+    '__nocobase_api_client_share_token__',
+    /^true$/i.test(values.API_CLIENT_SHARE_TOKEN),
+  );
+  data = replaceRuntimeAssignment(data, '__nocobase_ws_url__', values.WS_URL);
+  data = replaceRuntimeAssignment(data, '__nocobase_ws_path__', values.WS_PATH);
+  data = replaceRuntimeAssignment(data, '__nocobase_app_dev__', false);
+  data = replaceRuntimeAssignment(data, '__esm_cdn_base_url__', values.ESM_CDN_BASE_URL);
+  data = replaceRuntimeAssignment(data, '__esm_cdn_suffix__', values.ESM_CDN_SUFFIX);
+
+  fs.writeFileSync(indexPath, data, 'utf-8');
+  return true;
+}
 
 /**
  * 复制主应用客户端文件
@@ -127,6 +220,7 @@ module.exports = (cli) => {
         nodeModulesPath: resolve(process.cwd(), 'node_modules'),
       });
       const copiedMainClient = await copyMainClient(mainClientSource, target);
+      const renderedMainIndex = copiedMainClient ? renderExtractedClientIndexHtml(target, version) : false;
       const copiedPluginBundles = await copyPluginClients(plugins, target);
       const activeVersionFile = await writeActiveVersion(version);
 
@@ -145,7 +239,7 @@ module.exports = (cli) => {
         chalk.green(
           `Extracted client assets ${version} to ${target} (main client: ${
             copiedMainClient ? 'yes' : 'no'
-          }, plugin bundles: ${copiedPluginBundles}).`,
+          }, rendered index: ${renderedMainIndex ? 'yes' : 'no'}, plugin bundles: ${copiedPluginBundles}).`,
         ),
       );
     });
@@ -198,3 +292,5 @@ module.exports = (cli) => {
       }
     });
 };
+
+module.exports.renderExtractedClientIndexHtml = renderExtractedClientIndexHtml;

package/src/commands/create-nginx-conf.js

@@ -11,6 +11,10 @@ const { resolve, posix } = require('path');
 const { storagePathJoin, resolvePublicPath, resolveV2PublicPath, normalizeModernClientPrefix } = require('../util');
 const { readFileSync, writeFileSync } = require('fs');
 
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
 /**
  *
  * @param {Command} cli
@@ -24,6 +28,8 @@ module.exports = (cli) => {
     const modernClientPrefix = normalizeModernClientPrefix(process.env.APP_MODERN_CLIENT_PREFIX);
     const appPublicPathWithoutTrailingSlash = appPublicPath.replace(/\/$/, '');
     const v2PublicPathWithoutTrailingSlash = v2PublicPath.replace(/\/$/, '');
+    const settingsAssetsPath = `${appPublicPath}settings/assets/`;
+    const settingsDocumentPattern = `^${escapeRegExp(appPublicPath)}settings(?:/|$)`;
     const file = resolve(__dirname, '../../nocobase.conf.tpl');
     const data = readFileSync(file, 'utf-8');
     let otherLocation = '';
@@ -38,6 +44,21 @@ module.exports = (cli) => {
         return 302 ${appPublicPathWithoutTrailingSlash}$uri$is_args$args;
     }
 
+    location ^~ /files/ {
+        proxy_pass http://127.0.0.1:${process.env.APP_PORT};
+        proxy_http_version 1.1;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $upstream_x_forwarded_proto;
+        proxy_set_header Host $final_host;
+        proxy_set_header Referer $http_referer;
+        proxy_set_header User-Agent $http_user_agent;
+        add_header Cache-Control 'no-cache, no-store';
+        proxy_connect_timeout 600;
+        proxy_send_timeout 600;
+        proxy_read_timeout 600;
+        send_timeout 600;
+    }
+
     location / {
         alias ${posix.resolve(process.cwd())}/node_modules/@nocobase/app/dist/client/;
         try_files $uri $uri/ /index.html;
@@ -49,6 +70,8 @@ module.exports = (cli) => {
       .replace(/\{\{distPath\}\}/g, distPath)
       .replace(/\{\{v2PublicPath\}\}/g, v2PublicPath)
       .replace(/\{\{v2PublicPathNoTrailingSlash\}\}/g, v2PublicPathWithoutTrailingSlash)
+      .replace(/\{\{settingsAssetsPath\}\}/g, settingsAssetsPath)
+      .replace(/\{\{settingsDocumentPattern\}\}/g, settingsDocumentPattern)
       .replace(/\{\{apiPort\}\}/g, process.env.APP_PORT)
       .replace(/\{\{otherLocation\}\}/g, otherLocation);
     const targetFile = storagePathJoin('nocobase.conf');

package/src/commands/dev.js

@@ -20,6 +20,7 @@ const {
   isPortReachable,
   buildWSURL,
   checkDBDialect,
+  resolveAppClientEntryMode,
 } = require('../util');
 const { getPortPromise } = require('portfinder');
 const chokidar = require('chokidar');
@@ -47,6 +48,69 @@ function buildAppDevForwardArgs(argv = process.argv) {
   return ['app-dev', ...argv.slice(3)];
 }
 
+function resolveSettingsDevPort(appPort) {
+  return Number(appPort) + 3;
+}
+
+function normalizePublicPath(value) {
+  let normalized = value || '/';
+  if (!normalized.startsWith('/')) {
+    normalized = `/${normalized}`;
+  }
+  if (!normalized.endsWith('/')) {
+    normalized = `${normalized}/`;
+  }
+  return normalized.replace(/\/{2,}/g, '/');
+}
+
+function createSettingsDevProcessOptions({
+  appPackageRoot,
+  appPort,
+  settingsPort,
+  browserPort,
+  appPublicPath,
+  processEnv = process.env,
+}) {
+  const settingsHmrPath = `${normalizePublicPath(appPublicPath)}settings/__rspack_hmr`;
+  return {
+    command: 'rsbuild',
+    args: ['dev', '--config', `${appPackageRoot}/client-settings/rsbuild.config.ts`],
+    runOptions: {
+      prefix: 'client-settings',
+      color: 'yellow',
+      env: {
+        ...processEnv,
+        APP_PORT: `${appPort}`,
+        APP_SETTINGS_PORT: `${settingsPort}`,
+        NODE_ENV: 'development',
+        RSPACK_HMR_CLIENT_PORT: `${browserPort}`,
+        RSPACK_HMR_PATH: settingsHmrPath,
+      },
+    },
+  };
+}
+
+function resolveDevRuntimeMode(opts = {}) {
+  const appClientEntryMode = opts.appClientEntryMode || resolveAppClientEntryMode();
+  const useModernOnlyEntryMode = appClientEntryMode === 'modern-only';
+  const clientV2Only = !!opts.clientV2Only;
+  const forceClient = !!opts.client;
+  const forceServer = !!opts.server;
+  const shouldRunClientV2 = clientV2Only || useModernOnlyEntryMode || forceClient || !forceServer;
+  const shouldRunClient = !clientV2Only && !useModernOnlyEntryMode && (forceClient || !forceServer);
+  const shouldRunServer = !clientV2Only && (forceServer || !forceClient || useModernOnlyEntryMode);
+  const shouldRunSettings = shouldRunClientV2;
+
+  return {
+    appClientEntryMode,
+    useModernOnlyEntryMode,
+    shouldRunClientV2,
+    shouldRunClient,
+    shouldRunServer,
+    shouldRunSettings,
+  };
+}
+
 async function forwardDevToAppDev({ argv = process.argv, runCommand = run } = {}) {
   await runCommand('nocobase-v1', buildAppDevForwardArgs(argv));
 }
@@ -63,6 +127,7 @@ module.exports = (cli) => {
     .option('-c, --client')
     .option('-s, --server')
     .option('--db-sync')
+    .option('--quickstart')
     .option('--rsbuild')
     .option('--client-v2-only')
     .option('-i, --inspect [port]')
@@ -103,13 +168,18 @@ module.exports = (cli) => {
       let clientPort = APP_PORT;
       let serverPort;
       let clientV2Port = APP_PORT;
+      let settingsPort = resolveSettingsDevPort(APP_PORT);
 
       nodeCheck();
       await postCheck(opts);
 
-      const shouldRunClientV2 = clientV2Only || client || !server;
-      const shouldRunClient = !clientV2Only && (client || !server);
-      const shouldRunServer = !clientV2Only && (server || !client);
+      const {
+        useModernOnlyEntryMode,
+        shouldRunClientV2,
+        shouldRunClient,
+        shouldRunServer,
+        shouldRunSettings,
+      } = resolveDevRuntimeMode(opts);
       const shouldRunClientWithRsbuild = shouldRunClient && !!rsbuild;
 
       if (shouldRunServer && server) {
@@ -120,14 +190,25 @@ module.exports = (cli) => {
         });
       }
 
-      if (shouldRunClientV2 && !clientV2Only) {
+      if (shouldRunClientV2 && !clientV2Only && !useModernOnlyEntryMode) {
         clientV2Port = await getPortPromise({
           port: 1 * clientPort + 2,
         });
       }
 
+      if (useModernOnlyEntryMode) {
+        clientV2Port = APP_PORT;
+      }
+
+      if (shouldRunSettings) {
+        settingsPort = await getPortPromise({
+          port: resolveSettingsDevPort(APP_PORT),
+        });
+      }
+
       let subprocessClient;
       let subprocessClientV2;
+      let subprocessSettings;
 
       const runDevClientV2 = () => {
         console.log('starting client-v2', 1 * clientV2Port);
@@ -140,6 +221,7 @@ module.exports = (cli) => {
             env: {
               ...process.env,
               APP_V2_PORT: `${clientV2Port}`,
+              APP_SETTINGS_PORT: `${settingsPort}`,
               NODE_ENV: 'development',
               RSPACK_HMR_CLIENT_PORT: `${clientV2Only ? clientV2Port : clientPort}`,
               API_BASE_URL: process.env.API_BASE_URL || process.env.API_BASE_PATH,
@@ -157,8 +239,34 @@ module.exports = (cli) => {
         );
       };
 
+      const runDevSettings = () => {
+        console.log('starting client-settings', 1 * settingsPort);
+        const { command, args, runOptions } = createSettingsDevProcessOptions({
+          appPackageRoot: APP_PACKAGE_ROOT,
+          appPort: APP_PORT,
+          settingsPort,
+          browserPort: clientV2Only ? clientV2Port : clientPort,
+          appPublicPath: process.env.APP_PUBLIC_PATH,
+          processEnv: {
+            ...process.env,
+            API_BASE_URL: process.env.API_BASE_URL || process.env.API_BASE_PATH,
+            API_CLIENT_STORAGE_PREFIX: process.env.API_CLIENT_STORAGE_PREFIX,
+            API_CLIENT_STORAGE_TYPE: process.env.API_CLIENT_STORAGE_TYPE,
+            API_CLIENT_SHARE_TOKEN: process.env.API_CLIENT_SHARE_TOKEN || 'false',
+            WEBSOCKET_URL: process.env.WEBSOCKET_URL || buildWSURL(process.env.API_BASE_URL, serverPort),
+            WS_PATH: process.env.WS_PATH,
+            ESM_CDN_BASE_URL: process.env.ESM_CDN_BASE_URL || 'https://esm.sh',
+            ESM_CDN_SUFFIX: process.env.ESM_CDN_SUFFIX || '',
+            PROXY_TARGET_URL:
+              process.env.PROXY_TARGET_URL || (serverPort ? `http://127.0.0.1:${serverPort}` : undefined),
+          },
+        });
+        subprocessSettings = runWithPrefix(command, args, runOptions);
+      };
+
       if (clientV2Only) {
         runDevClientV2();
+        runDevSettings();
         return;
       }
 
@@ -179,6 +287,7 @@ module.exports = (cli) => {
             APP_PORT: `${clientPort}`,
             APP_ROOT: `${APP_PACKAGE_ROOT}/client`,
             APP_V2_PORT: `${clientV2Port}`,
+            APP_SETTINGS_PORT: `${settingsPort}`,
             NODE_ENV: 'development',
             RSPACK_HMR_CLIENT_PORT: `${clientPort}`,
             API_BASE_URL: process.env.API_BASE_URL || process.env.API_BASE_PATH,
@@ -231,6 +340,9 @@ module.exports = (cli) => {
           if (shouldRunClientV2) {
             await restartSubprocess(subprocessClientV2, clientV2Port, runDevClientV2);
           }
+          if (shouldRunSettings) {
+            await restartSubprocess(subprocessSettings, settingsPort, runDevSettings);
+          }
           await fs.promises.writeFile(process.env.WATCH_FILE, `export const watchId = '${uid()}';`, 'utf-8');
         }, 500);
 
@@ -300,10 +412,17 @@ module.exports = (cli) => {
       if (shouldRunClientV2) {
         runDevClientV2();
       }
+
+      if (shouldRunSettings) {
+        runDevSettings();
+      }
     });
 };
 
 module.exports._test = {
   buildAppDevForwardArgs,
+  createSettingsDevProcessOptions,
   forwardDevToAppDev,
+  resolveDevRuntimeMode,
+  resolveSettingsDevPort,
 };

package/src/util.js

@@ -432,13 +432,41 @@ const DEFAULT_MODERN_CLIENT_PREFIX = 'v';
 
 exports.DEFAULT_MODERN_CLIENT_PREFIX = DEFAULT_MODERN_CLIENT_PREFIX;
 
+const DEFAULT_APP_CLIENT_ENTRY_MODE = 'legacy-default';
+const APP_CLIENT_ENTRY_MODES = new Set(['legacy-default', 'modern-default', 'modern-only']);
+
+exports.DEFAULT_APP_CLIENT_ENTRY_MODE = DEFAULT_APP_CLIENT_ENTRY_MODE;
+
+function isAppClientEntryMode(value) {
+  return APP_CLIENT_ENTRY_MODES.has(String(value || '').trim());
+}
+
+exports.isAppClientEntryMode = isAppClientEntryMode;
+
+function normalizeAppClientEntryMode(value) {
+  const normalized = String(value || '').trim();
+  return isAppClientEntryMode(normalized) ? normalized : DEFAULT_APP_CLIENT_ENTRY_MODE;
+}
+
+exports.normalizeAppClientEntryMode = normalizeAppClientEntryMode;
+
+function resolveAppClientEntryMode() {
+  return normalizeAppClientEntryMode(process.env.APP_CLIENT_ENTRY_MODE);
+}
+
+exports.resolveAppClientEntryMode = resolveAppClientEntryMode;
+
 // Normalize APP_MODERN_CLIENT_PREFIX (accepts `v`, `/v`, `/v/`)
 // down to a bare segment like `v`.
 function normalizeModernClientPrefix(value) {
   const segment = String(value || '')
     .trim()
     .replace(/^\/+|\/+$/g, '');
-  return segment || DEFAULT_MODERN_CLIENT_PREFIX;
+  const normalized = segment || DEFAULT_MODERN_CLIENT_PREFIX;
+  if (normalized === 'settings') {
+    throw new Error('APP_MODERN_CLIENT_PREFIX "settings" is reserved for the standalone Settings application.');
+  }
+  return normalized;
 }
 
 exports.normalizeModernClientPrefix = normalizeModernClientPrefix;
@@ -455,6 +483,13 @@ function isAppDevHtml() {
   return process.argv[2] === 'app-dev' || process.env.NOCOBASE_APP_DEV === 'true';
 }
 
+function shouldRefreshLegacyIndexTemplate(data = '') {
+  return (
+    !data.includes("window['__nocobase_modern_client_prefix__']") ||
+    !data.includes("window['__nocobase_app_client_entry_mode__']")
+  );
+}
+
 function buildIndexHtml(force = false) {
   if (process.env.NOCOBASE_EXTRACT_CLIENT_ASSETS === 'true') {
     return;
@@ -469,11 +504,15 @@ function buildIndexHtml(force = false) {
   }
   if (!fs.existsSync(tpl)) {
     fs.copyFileSync(file, tpl);
+  } else if (shouldRefreshLegacyIndexTemplate(fs.readFileSync(tpl, 'utf-8'))) {
+    fs.copyFileSync(file, tpl);
   }
   const data = fs.readFileSync(tpl, 'utf-8');
   let replacedData = data
     .replace(/\{\{env.CDN_BASE_URL\}\}/g, process.env.CDN_BASE_URL)
     .replace(/\{\{env.APP_PUBLIC_PATH\}\}/g, process.env.APP_PUBLIC_PATH)
+    .replace(/\{\{env.APP_MODERN_CLIENT_PREFIX\}\}/g, normalizeModernClientPrefix(process.env.APP_MODERN_CLIENT_PREFIX))
+    .replace(/\{\{env.APP_CLIENT_ENTRY_MODE\}\}/g, resolveAppClientEntryMode())
     .replace(/\{\{env.API_CLIENT_SHARE_TOKEN\}\}/g, process.env.API_CLIENT_SHARE_TOKEN || 'false')
     .replace(/\{\{env.API_CLIENT_STORAGE_TYPE\}\}/g, process.env.API_CLIENT_STORAGE_TYPE)
     .replace(/\{\{env.API_CLIENT_STORAGE_PREFIX\}\}/g, process.env.API_CLIENT_STORAGE_PREFIX)
@@ -614,6 +653,7 @@ exports.initEnv = function initEnv() {
     CDN_BASE_URL: '',
     APP_PUBLIC_PATH: '/',
     APP_MODERN_CLIENT_PREFIX: DEFAULT_MODERN_CLIENT_PREFIX,
+    APP_CLIENT_ENTRY_MODE: DEFAULT_APP_CLIENT_ENTRY_MODE,
     ESM_CDN_BASE_URL: 'https://esm.sh',
     ESM_CDN_SUFFIX: '',
   };
@@ -665,6 +705,14 @@ exports.initEnv = function initEnv() {
     }
   }
 
+  const rawAppClientEntryMode = String(process.env.APP_CLIENT_ENTRY_MODE || '').trim();
+  if (rawAppClientEntryMode && !isAppClientEntryMode(rawAppClientEntryMode)) {
+    console.warn(
+      `Unknown APP_CLIENT_ENTRY_MODE "${rawAppClientEntryMode}", falling back to ${DEFAULT_APP_CLIENT_ENTRY_MODE}.`,
+    );
+  }
+  process.env.APP_CLIENT_ENTRY_MODE = normalizeAppClientEntryMode(rawAppClientEntryMode);
+
   if (!process.env.__env_modified__ && process.env.APP_PUBLIC_PATH) {
     const publicPath = process.env.APP_PUBLIC_PATH.replace(/\/$/g, '');
     const keys = ['API_BASE_PATH', 'WS_PATH', 'PLUGIN_STATICS_PATH'];