@nocobase/cli-v1 2.3.0-beta.9 → 2.4.0-alpha.10

package/nocobase.conf.tpl

@@ -154,6 +154,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;
@@ -212,6 +240,68 @@ server {
 
 
 
+    location = {{publicPath}}{{portalClientPrefix}} {
+        absolute_redirect off;
+        return 302 {{v2PublicPath}}$is_args$args;
+    }
+
+    location = {{publicPath}}{{portalClientPrefix}}/ {
+        absolute_redirect off;
+        return 302 {{v2PublicPath}}$is_args$args;
+    }
+
+    location ^~ {{publicPath}}{{portalClientPrefix}}/apps/ {
+        absolute_redirect off;
+
+        if ($uri ~ ^{{publicPath}}{{portalClientPrefix}}/apps/(?<subapp>[A-Za-z0-9_-]+)/?$) {
+            return 302 {{v2PublicPath}}apps/$subapp/$is_args$args;
+        }
+
+        if ($uri ~ ^{{publicPath}}{{portalClientPrefix}}/apps/(?<subapp>[A-Za-z0-9_-]+)/(?<portal>[A-Za-z0-9_-]+)$) {
+            return 308 {{publicPath}}{{portalClientPrefix}}/apps/$subapp/$portal/$is_args$args;
+        }
+
+        if ($uri !~ ^{{publicPath}}{{portalClientPrefix}}/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}}{{portalClientPrefix}}/ {
+        absolute_redirect off;
+
+        if ($uri ~ ^{{publicPath}}{{portalClientPrefix}}/(?<portal>[A-Za-z0-9_-]+)$) {
+            return 308 {{publicPath}}{{portalClientPrefix}}/$portal/$is_args$args;
+        }
+
+        if ($uri !~ ^{{publicPath}}{{portalClientPrefix}}/(?<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/;
         try_files $uri $uri/ /index.html;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/cli-v1",
-  "version": "2.3.0-beta.9",
+  "version": "2.4.0-alpha.10",
   "description": "",
   "license": "Apache-2.0",
   "main": "./src/index.js",
@@ -9,9 +9,9 @@
     "nocobase-v1": "./bin/index.js"
   },
   "dependencies": {
-    "@nocobase/cli": "2.3.0-beta.9",
+    "@nocobase/cli": "2.4.0-alpha.10",
     "@nocobase/license-kit": "^0.3.8",
-    "@nocobase/utils": "2.3.0-beta.9",
+    "@nocobase/utils": "2.4.0-alpha.10",
     "chalk": "^4.1.1",
     "commander": "^9.2.0",
     "deepmerge": "^4.3.1",
@@ -20,7 +20,7 @@
     "fast-glob": "^3.3.1",
     "fs-extra": "^11.1.1",
     "p-all": "3.0.0",
-    "pm2": "^6.0.5",
+    "pm2": "^7.0.0",
     "portfinder": "^1.0.28",
     "tar": "^7.4.3",
     "tree-kill": "^1.2.2"
@@ -33,5 +33,5 @@
     "url": "git+https://github.com/nocobase/nocobase.git",
     "directory": "packages/core/cli"
   },
-  "gitHead": "c215e60ed704afe6c086bd96304f4b0d3b46d02e"
+  "gitHead": "c869865c0413fbe4ef85b26be1f2b8d7078c38df"
 }

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

@@ -87,6 +87,20 @@ describe('cli-v1 buildIndexHtml', () => {
     fs.removeSync(appRoot);
   });
 
+  test('injects settings-default as a valid client entry mode', () => {
+    const appRoot = createAppPackageRoot();
+    process.argv = ['node', 'nocobase-v1', 'start'];
+    process.env.APP_PACKAGE_ROOT = appRoot;
+    process.env.APP_PUBLIC_PATH = '/';
+    process.env.APP_CLIENT_ENTRY_MODE = 'settings-default';
+
+    buildIndexHtml();
+
+    const html = fs.readFileSync(path.join(appRoot, 'dist/client/index.html'), 'utf-8');
+    expect(html).toContain("window['__nocobase_app_client_entry_mode__'] = 'settings-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');

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__/client-upload.test.js

@@ -0,0 +1,60 @@
+/**
+ * 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 */
+/* global vi */
+
+const { putWithRetry, OSS_TIMEOUT, OSS_MAX_ATTEMPTS } = require('../commands/client')._test;
+
+describe('cli-v1 client:upload', () => {
+  let warn;
+
+  beforeEach(() => {
+    warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warn.mockRestore();
+  });
+
+  it('should raise the ali-oss response timeout above its 60s default', () => {
+    expect(OSS_TIMEOUT).toBeGreaterThan(60000);
+  });
+
+  it('should return the result without retrying when the upload succeeds', async () => {
+    const put = vi.fn().mockResolvedValue({ name: 'a.js' });
+
+    await expect(putWithRetry({ put }, 'a.js', '/tmp/a.js')).resolves.toEqual({ name: 'a.js' });
+
+    expect(put).toHaveBeenCalledTimes(1);
+    expect(put).toHaveBeenCalledWith('a.js', '/tmp/a.js');
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it('should retry a transient timeout and resolve', async () => {
+    const put = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('Response timeout for 60000ms'))
+      .mockResolvedValue({ name: 'a.js' });
+
+    await expect(putWithRetry({ put }, 'a.js', '/tmp/a.js')).resolves.toEqual({ name: 'a.js' });
+
+    expect(put).toHaveBeenCalledTimes(2);
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should give up and rethrow after the attempt limit', async () => {
+    const error = new Error('Response timeout for 60000ms');
+    const put = vi.fn().mockRejectedValue(error);
+
+    await expect(putWithRetry({ put }, 'a.js', '/tmp/a.js')).rejects.toThrow(error);
+
+    expect(put).toHaveBeenCalledTimes(OSS_MAX_ATTEMPTS);
+  });
+});

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

@@ -0,0 +1,87 @@
+/**
+ * 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 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;');
+    },
+  );
+
+  test.each([
+    ['root mount', '/', '/x', '/v/'],
+    ['custom public path', '/nocobase/', '/nocobase/x', '/nocobase/v/'],
+  ])('redirects Portal roots to the Modern Client for %s', async (_label, publicPath, portalRoot, modernRoot) => {
+    const config = await renderConfig(publicPath);
+
+    expect(config).toContain(`location = ${portalRoot} {
+        absolute_redirect off;
+        return 302 ${modernRoot}$is_args$args;
+    }`);
+    expect(config).toContain(`location = ${portalRoot}/ {
+        absolute_redirect off;
+        return 302 ${modernRoot}$is_args$args;
+    }`);
+    expect(config).toContain(`return 302 ${modernRoot}$is_args$args;`);
+    expect(config).toContain(`if ($uri ~ ^${portalRoot}/apps/(?<subapp>[A-Za-z0-9_-]+)/?$) {`);
+    expect(config).toContain(`return 302 ${modernRoot}apps/$subapp/$is_args$args;`);
+  });
+});

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

@@ -9,13 +9,28 @@
 
 /* eslint-env jest */
 
-const { buildAppDevForwardArgs, forwardDevToAppDev, resolveDevRuntimeMode } = 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 () => {
@@ -37,6 +52,7 @@ describe('cli-v1 dev command', () => {
       useModernOnlyEntryMode: false,
       shouldRunClient: true,
       shouldRunClientV2: true,
+      shouldRunSettings: true,
       shouldRunServer: true,
     });
   });
@@ -46,6 +62,17 @@ describe('cli-v1 dev command', () => {
       useModernOnlyEntryMode: true,
       shouldRunClient: false,
       shouldRunClientV2: true,
+      shouldRunSettings: true,
+      shouldRunServer: true,
+    });
+  });
+
+  test('resolveDevRuntimeMode keeps all clients in settings-default', () => {
+    expect(resolveDevRuntimeMode({ appClientEntryMode: 'settings-default' })).toMatchObject({
+      useModernOnlyEntryMode: false,
+      shouldRunClient: true,
+      shouldRunClientV2: true,
+      shouldRunSettings: true,
       shouldRunServer: true,
     });
   });
@@ -55,7 +82,37 @@ describe('cli-v1 dev command', () => {
       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;
+}
 
 /**
  * 复制主应用客户端文件
@@ -63,6 +156,31 @@ async function writeActiveVersion(version) {
   return activeVersionFile;
 }
 
+// 客户端资源里有体积较大的 bundle，ali-oss 默认的 60s 响应超时在 CI 上不够用。
+const OSS_TIMEOUT = 300000;
+// 单个文件偶发超时不应该让整次上传前功尽弃，做有限重试。
+const OSS_MAX_ATTEMPTS = 3;
+
+/**
+ * 上传单个文件，对偶发失败重试
+ * @param {Client} client - OSS 客户端实例
+ * @param {string} ossKey - OSS 对象名
+ * @param {string} filePath - 本地文件路径
+ */
+async function putWithRetry(client, ossKey, filePath) {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return await client.put(ossKey, filePath);
+    } catch (error) {
+      if (attempt >= OSS_MAX_ATTEMPTS) {
+        throw error;
+      }
+      console.warn(chalk.yellow(`Retrying ${ossKey} (${attempt}/${OSS_MAX_ATTEMPTS - 1}): ${error.message}`));
+      await new Promise((_resolve) => setTimeout(_resolve, attempt * 2000));
+    }
+  }
+}
+
 /**
  * 递归上传目录到 OSS
  * @param {Client} client - OSS 客户端实例
@@ -96,7 +214,7 @@ async function uploadDirectoryToOSS(client, localDir, ossPrefix = '') {
       // 上传文件
       const ossKey = ossPrefix ? `${ossPrefix}/${file}` : file;
       try {
-        await client.put(ossKey, filePath);
+        await putWithRetry(client, ossKey, filePath);
         // console.log(chalk.green(`Uploaded: ${ossKey}`));
         uploadedCount++;
       } catch (error) {
@@ -127,6 +245,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 +264,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}).`,
         ),
       );
     });
@@ -179,6 +298,7 @@ module.exports = (cli) => {
         accessKeySecret: process.env.CDN_ALI_OSS_ACCESS_KEY_SECRET,
         bucket: process.env.CDN_ALI_OSS_BUCKET,
         region: process.env.CDN_ALI_OSS_REGION,
+        timeout: OSS_TIMEOUT,
       });
 
       if (!(await fs.exists(target))) {
@@ -198,3 +318,11 @@ module.exports = (cli) => {
       }
     });
 };
+
+module.exports.renderExtractedClientIndexHtml = renderExtractedClientIndexHtml;
+
+module.exports._test = {
+  putWithRetry,
+  OSS_TIMEOUT,
+  OSS_MAX_ATTEMPTS,
+};

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

@@ -11,6 +11,12 @@ const { resolve, posix } = require('path');
 const { storagePathJoin, resolvePublicPath, resolveV2PublicPath, normalizeModernClientPrefix } = require('../util');
 const { readFileSync, writeFileSync } = require('fs');
 
+const PORTAL_CLIENT_PREFIX = 'x';
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
 /**
  *
  * @param {Command} cli
@@ -24,6 +30,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 = '';
@@ -64,6 +72,9 @@ module.exports = (cli) => {
       .replace(/\{\{distPath\}\}/g, distPath)
       .replace(/\{\{v2PublicPath\}\}/g, v2PublicPath)
       .replace(/\{\{v2PublicPathNoTrailingSlash\}\}/g, v2PublicPathWithoutTrailingSlash)
+      .replace(/\{\{portalClientPrefix\}\}/g, PORTAL_CLIENT_PREFIX)
+      .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

@@ -48,6 +48,48 @@ 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';
@@ -57,6 +99,7 @@ function resolveDevRuntimeMode(opts = {}) {
   const shouldRunClientV2 = clientV2Only || useModernOnlyEntryMode || forceClient || !forceServer;
   const shouldRunClient = !clientV2Only && !useModernOnlyEntryMode && (forceClient || !forceServer);
   const shouldRunServer = !clientV2Only && (forceServer || !forceClient || useModernOnlyEntryMode);
+  const shouldRunSettings = shouldRunClientV2;
 
   return {
     appClientEntryMode,
@@ -64,6 +107,7 @@ function resolveDevRuntimeMode(opts = {}) {
     shouldRunClientV2,
     shouldRunClient,
     shouldRunServer,
+    shouldRunSettings,
   };
 }
 
@@ -83,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]')
@@ -123,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 { useModernOnlyEntryMode, shouldRunClientV2, shouldRunClient, shouldRunServer } = resolveDevRuntimeMode(
-        opts,
-      );
+      const {
+        useModernOnlyEntryMode,
+        shouldRunClientV2,
+        shouldRunClient,
+        shouldRunServer,
+        shouldRunSettings,
+      } = resolveDevRuntimeMode(opts);
       const shouldRunClientWithRsbuild = shouldRunClient && !!rsbuild;
 
       if (shouldRunServer && server) {
@@ -150,8 +200,15 @@ module.exports = (cli) => {
         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);
@@ -164,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,
@@ -181,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;
       }
 
@@ -203,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,
@@ -255,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);
 
@@ -324,11 +412,17 @@ module.exports = (cli) => {
       if (shouldRunClientV2) {
         runDevClientV2();
       }
+
+      if (shouldRunSettings) {
+        runDevSettings();
+      }
     });
 };
 
 module.exports._test = {
   buildAppDevForwardArgs,
+  createSettingsDevProcessOptions,
   forwardDevToAppDev,
   resolveDevRuntimeMode,
+  resolveSettingsDevPort,
 };

package/src/commands/docs.js

@@ -57,6 +57,8 @@ function createCdnClient() {
  * @param {string} timestampDir
  */
 const REWRITE_RULES = [
+  // AI API 请求保持原路径，避免被后续规则补上文档版本的时间戳前缀
+  { sourceUrl: '^/api/ai/(.*)$', targetTemplate: () => '/api/ai/$1', flag: 'break' },
   // /en/ 下无后缀的页面路由，去掉 /en/ 前缀并改写到目录式 index.html
   { sourceUrl: '^/en/([^.]*[^/.])$', targetTemplate: (ts) => `/${ts}/$1/index.html`, flag: 'break' },
   // 其他语言和默认语言的无后缀页面路由，统一改写到目录式 index.html
@@ -147,7 +149,11 @@ async function waitForRewriteRule(cdnClient, domain, timestampDir) {
           if (!config) return false;
           const args = config.functionArgs?.functionArg || [];
           const targetArg = args.find((a) => a.argName === 'target_url');
-          return config.status === 'success' && (targetArg?.argValue || '').startsWith(expectedPrefix);
+          const expectedTarget = rule.targetTemplate(timestampDir);
+          const targetMatches = expectedTarget.startsWith(expectedPrefix)
+            ? (targetArg?.argValue || '').startsWith(expectedPrefix)
+            : targetArg?.argValue === expectedTarget;
+          return config.status === 'success' && targetMatches;
         });
 
         if (allEffective) {

package/src/util.js

@@ -433,7 +433,7 @@ 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']);
+const APP_CLIENT_ENTRY_MODES = new Set(['legacy-default', 'modern-default', 'modern-only', 'settings-default']);
 
 exports.DEFAULT_APP_CLIENT_ENTRY_MODE = DEFAULT_APP_CLIENT_ENTRY_MODE;
 
@@ -462,7 +462,11 @@ 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;