feat: allocate linux dev port ranges

scripts/dev-stack-port-utils.test.ts

@@ -1,7 +1,13 @@
 import {createServer} from 'node:net';
+import {mkdtempSync, readFileSync, rmSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
 import {describe, expect, it} from 'vitest';
 import {
   findAvailablePort,
+  mapDevPortsToPortRange,
+  parsePortRangeSpec,
+  reserveLinuxDevPortRange,
   resolveDevStackPorts,
 } from './dev-stack-port-utils.mjs';
 
@@ -18,6 +24,20 @@ function reservePort(port) {
 }
 
 describe('dev stack port utils', () => {
+  it('解析端口段并映射到四个 dev 端口', () => {
+    expect(parsePortRangeSpec('10000-10099')).toEqual({
+      start: 10000,
+      end: 10099,
+      label: '10000-10099',
+    });
+    expect(mapDevPortsToPortRange('10000-10099')).toMatchObject({
+      webPort: 10000,
+      apiPort: 10001,
+      spacetimePort: 10002,
+      adminWebPort: 10003,
+    });
+  });
+
   it('使用端口可用性检查为被占用端口寻找后续可用端口', async () => {
     const firstServer = await reservePort(0);
     const firstPort = firstServer.address().port;
@@ -38,6 +58,16 @@ describe('dev stack port utils', () => {
     }
   });
 
+  it('端口查找不会越过 Linux 用户端口段', async () => {
+    await expect(
+      findAvailablePort({
+        host: '127.0.0.1',
+        preferredPort: 9999,
+        portRange: {start: 10000, end: 10099, label: '10000-10099'},
+      }),
+    ).rejects.toThrow('不在允许端口段');
+  });
+
   it('为 npm run dev 的所有后续流程解析互不冲突的端口', async () => {
     const resolvedPorts = await resolveDevStackPorts({
       spacetime: {host: '127.0.0.1', preferredPort: 0},
@@ -48,4 +78,191 @@ describe('dev stack port utils', () => {
 
     expect(new Set(Object.values(resolvedPorts)).size).toBe(4);
   });
+
+  it('端口段内会一直漂移到段尾，不会被默认 200 次尝试截断', async () => {
+    const rangeStart = 10000;
+    const rangeEnd = 10300;
+    const reservedPorts = new Set(
+      Array.from({length: 201}, (_, index) => rangeStart + index),
+    );
+
+    const availablePort = await findAvailablePort({
+      host: '127.0.0.1',
+      preferredPort: rangeStart,
+      reservedPorts,
+      portRange: {start: rangeStart, end: rangeEnd, label: `${rangeStart}-${rangeEnd}`},
+    });
+
+    expect(availablePort).toBeGreaterThan(rangeStart + 200);
+    expect(availablePort).toBeLessThanOrEqual(rangeEnd);
+  });
+
+  const linuxIt = process.platform === 'linux' ? it : it.skip;
+
+  linuxIt('Linux 未手动指定端口段时从 10000 开始按 100 端口块自动分配', async () => {
+    const tempRoot = mkdtempSync(join(tmpdir(), 'genarrative-port-range-'));
+    const registryPath = join(tempRoot, 'registry.json');
+    const lockPath = join(tempRoot, 'registry.lock');
+
+    try {
+      const aliceAllocation = await reserveLinuxDevPortRange({
+        env: {
+          USER: 'alice',
+          LOGNAME: 'alice',
+          GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR: tempRoot,
+        },
+        username: 'alice',
+        requestedRange: null,
+        registryPath,
+        lockPath,
+      });
+      const bobAllocation = await reserveLinuxDevPortRange({
+        env: {
+          USER: 'bob',
+          LOGNAME: 'bob',
+          GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR: tempRoot,
+        },
+        username: 'bob',
+        requestedRange: null,
+        registryPath,
+        lockPath,
+      });
+
+      expect(aliceAllocation.range.label).toBe('10000-10099');
+      expect(aliceAllocation.source).toBe('auto');
+      expect(bobAllocation.range.label).toBe('10100-10199');
+      expect(bobAllocation.source).toBe('auto');
+    } finally {
+      rmSync(tempRoot, {recursive: true, force: true});
+    }
+  });
+
+  linuxIt('Linux 系统级端口段记录会阻止两个用户拿到同一段', async () => {
+    const tempRoot = mkdtempSync(join(tmpdir(), 'genarrative-port-range-'));
+    const registryPath = join(tempRoot, 'registry.json');
+    const lockPath = join(tempRoot, 'registry.lock');
+
+    try {
+      const baseEnv = {
+        USER: 'alice',
+        LOGNAME: 'alice',
+        GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR: tempRoot,
+        GENARRATIVE_DEV_PORT_RANGE: '10000-10099',
+      };
+
+      const aliceAllocation = await reserveLinuxDevPortRange({
+        env: baseEnv,
+        username: 'alice',
+        registryPath,
+        lockPath,
+      });
+
+      expect(aliceAllocation.range.label).toBe('10000-10099');
+
+      const registryAfterAlice = JSON.parse(readFileSync(registryPath, 'utf8'));
+      expect(registryAfterAlice.allocations.alice.range.label).toBe('10000-10099');
+
+      await expect(
+        reserveLinuxDevPortRange({
+          env: {
+            ...baseEnv,
+            USER: 'bob',
+            LOGNAME: 'bob',
+          },
+          username: 'bob',
+          requestedRange: '10000-10099',
+          registryPath,
+          lockPath,
+        }),
+      ).rejects.toThrow('已被用户 alice 占用');
+
+      const aliceReuse = await reserveLinuxDevPortRange({
+        env: {
+          ...baseEnv,
+          USER: 'alice',
+          LOGNAME: 'alice',
+        },
+        username: 'alice',
+        registryPath,
+        lockPath,
+      });
+
+      expect(aliceReuse.range.label).toBe('10000-10099');
+      expect(aliceReuse.source).toBe('manual');
+      expect(
+        (
+          await reserveLinuxDevPortRange({
+            env: {
+              ...baseEnv,
+              USER: 'alice',
+              LOGNAME: 'alice',
+              GENARRATIVE_DEV_PORT_RANGE: '10100-10199',
+            },
+            username: 'alice',
+            requestedRange: '10100-10199',
+            registryPath,
+            lockPath,
+          })
+        ).range.label,
+      ).toBe('10000-10099');
+
+      const registryAfterReuse = JSON.parse(readFileSync(registryPath, 'utf8'));
+      expect(registryAfterReuse.allocations.alice.range.label).toBe('10000-10099');
+
+      const bobAllocation = await reserveLinuxDevPortRange({
+        env: {
+          ...baseEnv,
+          USER: 'bob',
+          LOGNAME: 'bob',
+          GENARRATIVE_DEV_PORT_RANGE: '10100-10199',
+        },
+        username: 'bob',
+        requestedRange: '10100-10199',
+        registryPath,
+        lockPath,
+      });
+
+      expect(bobAllocation.range.label).toBe('10100-10199');
+    } finally {
+      rmSync(tempRoot, {recursive: true, force: true});
+    }
+  });
+
+  linuxIt('Linux 同一用户第二个 dev 会话会复用同一用户段并继续在段内漂移', async () => {
+    const tempRoot = mkdtempSync(join(tmpdir(), 'genarrative-port-range-'));
+    const registryPath = join(tempRoot, 'registry.json');
+    const lockPath = join(tempRoot, 'registry.lock');
+
+    try {
+      const baseEnv = {
+        USER: 'alice',
+        LOGNAME: 'alice',
+        GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR: tempRoot,
+        GENARRATIVE_DEV_PORT_RANGE: '10000-10099',
+      };
+
+      const first = await reserveLinuxDevPortRange({
+        env: baseEnv,
+        username: 'alice',
+        registryPath,
+        lockPath,
+      });
+
+      const second = await reserveLinuxDevPortRange({
+        env: baseEnv,
+        username: 'alice',
+        registryPath,
+        lockPath,
+      });
+
+      expect(first.range.label).toBe('10000-10099');
+      expect(second.range.label).toBe('10000-10099');
+      expect(second.username).toBe('alice');
+      expect(JSON.parse(readFileSync(registryPath, 'utf8')).allocations.alice.range.label).toBe(
+        '10000-10099',
+      );
+    } finally {
+      rmSync(tempRoot, {recursive: true, force: true});
+    }
+  });
 });

scripts/dev.mjs

@@ -15,7 +15,11 @@ import {fileURLToPath} from 'node:url';
 
 import {
   formatPortDecision,
+  getLinuxDevPortRangeRegistryPaths,
+  getLinuxDevPortRangeUsername,
+  mapDevPortsToPortRange,
   normalizePort,
+  reserveLinuxDevPortRange,
   resolveDevStackPorts,
 } from './dev-stack-port-utils.mjs';
 import {
@@ -59,6 +63,7 @@ function usage() {
   --spacetime-port <port>           SpacetimeDB 端口
   --spacetime-data-dir <path>       SpacetimeDB 本地数据目录
   --database <name>                 SpacetimeDB 数据库名
+  --port-range <start-end>          Linux 用户端口段，手动指定示例 10000-10099；默认自动从 10000-10099 起分配
   --watch                           文件改动后刷新/重启对应模块
   --no-interactive                  关闭交互式手动命令
 
@@ -109,6 +114,7 @@ function parseArgs(argv, baseEnv) {
     spacetimePort: normalizePort(env.SPACETIME_PORT, 3101),
     spacetimeDataDir: resolve(serverRsDir, '.spacetimedb/local/data'),
     spacetimeServerUrl: String(env.GENARRATIVE_SPACETIME_SERVER_URL ?? '').trim(),
+    portRangeSpec: String(env.GENARRATIVE_DEV_PORT_RANGE ?? '').trim(),
     database:
       readLocalSpacetimeDatabase() ||
       String(env.GENARRATIVE_SPACETIME_DATABASE ?? '').trim() ||
@@ -184,6 +190,10 @@ function parseArgs(argv, baseEnv) {
         options.database = readValue();
         explicitOptions.add('database');
         break;
+      case '--port-range':
+        options.portRangeSpec = readValue();
+        explicitOptions.add('portRangeSpec');
+        break;
       case '--log':
         options.apiLog = readValue();
         break;
@@ -549,6 +559,8 @@ class DevRunner {
       adminWebTargetHost: resolveClientHost(options.adminWebHost),
       spacetimeServer: initialSpacetimeServer,
       apiTarget: `http://${resolveClientHost(options.apiHost)}:${options.apiPort}`,
+      portRange: null,
+      portRangeReservation: null,
     };
     this.services = new Map();
     this.watchers = [];
@@ -572,12 +584,57 @@ class DevRunner {
       ensureSpacetimeToolVersionMatchesWorkspace();
     }
 
+    await this.prepareLinuxPortRange(command);
     await this.tryReuseExistingSpacetime(command);
     await this.resolvePorts(command);
     this.registerServices();
     this.printSummary(command);
   }
 
+  async prepareLinuxPortRange(command) {
+    if (process.platform !== 'linux') {
+      return;
+    }
+
+    const requestedRange = String(this.options.portRangeSpec ?? '').trim();
+    const allocation = await reserveLinuxDevPortRange({
+      env: {
+        ...this.baseEnv,
+        GENARRATIVE_DEV_PORT_RANGE: requestedRange,
+      },
+      username: getLinuxDevPortRangeUsername(this.baseEnv),
+    });
+
+    if (!allocation) {
+      return;
+    }
+
+    this.state.portRangeReservation = allocation;
+    this.state.portRange = allocation.range;
+    this.baseEnv.GENARRATIVE_DEV_PORT_RANGE = allocation.range.label;
+
+    const mappedPorts = mapDevPortsToPortRange(allocation.range);
+    if (!mappedPorts) {
+      return;
+    }
+
+    if (!this.explicitOptions.has('webPort')) {
+      this.options.webPort = mappedPorts.webPort;
+    }
+    if (!this.explicitOptions.has('apiPort')) {
+      this.options.apiPort = mappedPorts.apiPort;
+    }
+    if (!this.explicitOptions.has('spacetimePort')) {
+      this.options.spacetimePort = mappedPorts.spacetimePort;
+    }
+    if (!this.explicitOptions.has('adminWebPort')) {
+      this.options.adminWebPort = mappedPorts.adminWebPort;
+    }
+
+    this.state.spacetimeServer = `http://${this.options.spacetimeHost}:${this.options.spacetimePort}`;
+    this.state.apiTarget = `http://${this.state.apiTargetHost}:${this.options.apiPort}`;
+  }
+
   shouldValidateSpacetimeToolVersion(command) {
     if (command === 'spacetime') {
       return true;
@@ -626,6 +683,10 @@ class DevRunner {
     ]);
 
     for (const candidate of candidates) {
+      if (!this.isCandidateSpacetimeWithinAssignedRange(candidate)) {
+        continue;
+      }
+
       const pingUrl = buildUrl(candidate, '/v1/ping');
       if (!pingUrl || !(await isHttpReady(pingUrl))) {
         continue;
@@ -653,6 +714,21 @@ class DevRunner {
     );
   }
 
+  isCandidateSpacetimeWithinAssignedRange(candidateUrl) {
+    const range = this.state.portRange;
+    if (!range) {
+      return true;
+    }
+
+    try {
+      const url = new URL(candidateUrl);
+      const port = Number(url.port);
+      return Number.isInteger(port) && port >= range.start && port <= range.end;
+    } catch {
+      return false;
+    }
+  }
+
   async resolvePorts(command) {
     const {options} = this;
     const portConfig = {};
@@ -662,6 +738,7 @@ class DevRunner {
         portConfig.spacetime = {
           host: options.spacetimeHost,
           preferredPort: options.spacetimePort,
+          portRange: this.state.portRange,
         };
       }
     }
@@ -670,6 +747,7 @@ class DevRunner {
       portConfig.api = {
         host: options.apiHost,
         preferredPort: options.apiPort,
+        portRange: this.state.portRange,
       };
     }
 
@@ -677,6 +755,7 @@ class DevRunner {
       portConfig.web = {
         host: options.webHost,
         preferredPort: options.webPort,
+        portRange: this.state.portRange,
       };
     }
 
@@ -684,6 +763,7 @@ class DevRunner {
       portConfig.adminWeb = {
         host: options.adminWebHost,
         preferredPort: options.adminWebPort,
+        portRange: this.state.portRange,
       };
     }
 
@@ -747,6 +827,15 @@ class DevRunner {
     console.log(`[dev] repo: ${repoRoot}`);
     console.log(`[dev] command: ${command}`);
     console.log(`[dev] watch: ${options.watch ? 'on' : 'off'}`);
+    if (state.portRange) {
+      const owner =
+        state.portRangeReservation?.username ||
+        getLinuxDevPortRangeUsername(this.baseEnv);
+      console.log(`[dev] port-range: ${state.portRange.label} (${owner})`);
+      console.log(
+        `[dev] port-range-registry: ${getLinuxDevPortRangeRegistryPaths(this.baseEnv).registryPath}`,
+      );
+    }
     console.log(`[dev] web: http://127.0.0.1:${options.webPort}`);
     console.log(`[dev] admin web: http://${state.adminWebTargetHost}:${options.adminWebPort}/admin/`);
     console.log(`[dev] api-server: ${state.apiTarget}`);

scripts/dev.test.ts

@@ -35,6 +35,8 @@ function workspaceSpacetimeVersionForTest() {
 }
 
 describe('dev scheduler argument routing', () => {
+  const linuxTest = process.platform === 'linux' ? test : test.skip;
+
   test('完整 dev 栈覆盖前端代理到本次解析出的 api-server 地址', () => {
     const {command, explicitOptions, options} = parseArgs([], {
       GENARRATIVE_API_PORT: '8090',
@@ -88,6 +90,67 @@ describe('dev scheduler argument routing', () => {
       'http://127.0.0.1:3100',
     );
   });
+
+  linuxTest('Linux 启动时按系统级端口段映射四个 dev 端口', async () => {
+    const tempDir = mkdtempSync(join(tmpdir(), 'genarrative-dev-port-range-'));
+    try {
+      const {command, explicitOptions, options} = parseArgs([], {
+        USER: 'alice',
+        LOGNAME: 'alice',
+        GENARRATIVE_DEV_PORT_RANGE: '22000-22099',
+        GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR: tempDir,
+      });
+      const runner = new DevRunner(options, {
+        USER: 'alice',
+        LOGNAME: 'alice',
+        GENARRATIVE_DEV_PORT_RANGE: '22000-22099',
+        GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR: tempDir,
+      }, explicitOptions);
+
+      await runner.prepareLinuxPortRange(command);
+
+      expect(runner.state.portRange.label).toBe('22000-22099');
+      expect(runner.options.webPort).toBe(22000);
+      expect(runner.options.apiPort).toBe(22001);
+      expect(runner.options.spacetimePort).toBe(22002);
+      expect(runner.options.adminWebPort).toBe(22003);
+      expect(runner.state.apiTarget).toBe('http://127.0.0.1:22001');
+      expect(runner.state.spacetimeServer).toBe('http://127.0.0.1:22002');
+    } finally {
+      rmSync(tempDir, {recursive: true, force: true});
+    }
+  });
+
+  test('Windows 仍沿用原有端口解析，不启用 Linux 端口段登记', async () => {
+    const originalPlatform = Object.getOwnPropertyDescriptor(process, 'platform');
+    Object.defineProperty(process, 'platform', {
+      configurable: true,
+      value: 'win32',
+    });
+
+    try {
+      const {command, explicitOptions, options} = parseArgs([], {
+        USER: 'alice',
+        GENARRATIVE_DEV_PORT_RANGE: '22000-22099',
+      });
+      const runner = new DevRunner(options, {
+        USER: 'alice',
+        GENARRATIVE_DEV_PORT_RANGE: '22000-22099',
+      }, explicitOptions);
+
+      await runner.prepareLinuxPortRange(command);
+
+      expect(runner.state.portRange).toBeNull();
+      expect(runner.options.webPort).toBe(3000);
+      expect(runner.options.apiPort).toBe(8082);
+      expect(runner.options.spacetimePort).toBe(3101);
+      expect(runner.options.adminWebPort).toBe(3102);
+    } finally {
+      if (originalPlatform) {
+        Object.defineProperty(process, 'platform', originalPlatform);
+      }
+    }
+  });
 });
 
 describe('dev scheduler api-server env', () => {