dynapm 1.0.12 → 1.0.14

package/CHANGELOG.md

@@ -5,6 +5,47 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [1.0.14] - 2026-03-20
+
+### 🔴 Bug 修复
+- **按需启动 POST 请求体丢失（严重）**: uWS 的 onData 回调中 ArrayBuffer 是借用语义，`Buffer.from(ab)` 底层数据被后续回调覆盖。改用 `Buffer.alloc + copy` 确保数据复制
+- **并发按需启动返回 502**: 多个请求同时到达离线服务时，只有第一个触发启动，其他请求等待启动完成后再代理
+- **transfer-encoding 头冲突**: forwardProxyRequest 中过滤 transfer-encoding 头，避免与 content-length 冲突导致后端 400
+- **后端崩溃自动恢复**: 检测到后端不可达（ECONNREFUSED）时，自动将非 proxyOnly 服务状态重置为 offline
+- **端口路由并发启动**: handlePortBindingRequest 补全 starting/stopping 状态处理，与 hostname 路由保持一致
+
+### 🔒 安全加固
+- 请求体大小限制 10MB，防止 DoS 攻击
+- WebSocket 消息队列限制 1000 条，防止内存泄漏
+- CRLF 注入防护：请求头值中的 `\r\n` 被清理
+- 端口路由 WebSocket close handler 补充后端连接清理
+
+### 🚀 性能优化
+- **去除 undici，恢复原生 http 模块**: 吞吐量从 4,523 提升至 **5,942 req/s（+31%）**，延迟从 10.6ms 降至 **10.3ms**
+- 预编译 CRLF 正则，避免热路径重复创建
+- Set 替代内联条件判断，优化请求头跳过逻辑
+
+### 🧪 测试（81 个用例全部通过）
+- test-proxy-comprehensive.ts: 23 个综合代理测试
+- test-edge-cases.ts: 15 个极端场景测试
+- test-gateway-robustness.ts: 13 个健壮性测试
+- test-admin-api-lifecycle.ts: 12 个管理 API 生命周期测试
+- test-port-route-start.ts: 9 个端口路由按需启动测试
+- test-security-stability.ts: 9 个安全与稳定性深度测试
+
+---
+
+## [1.0.13] - 2026-02-10
+
+### 🚀 性能优化
+- 使用 undici 替代原生 http 模块（已在 v1.0.14 回退，原生 http 性能更优）
+
+### 🔧 改进
+- 清理 RouteMapping 中的冗余字段
+- 代码更简洁，维护性更好
+
+---
+
 ## [1.0.12] - 2026-02-10
 
 ### ✨ 新增

package/CLAUDE.md

@@ -1,21 +1,20 @@
 # DynaPM - Claude Code 项目配置
 
-DynaPM 是一个智能网关，通过按需启动和闲置自动停止的方式，帮助用户在资源受限的服务器上管理数百个低频访问的服务。
+DynaPM 是一个智能网关(类似nginx)/进程管理工具(类似pm2)，通过按需启动(请求到达时通过查找配置判断请求属于哪个程序，然后网关转发请求，当程序还未启动会执行启动命令等待就绪后再实际转发)和闲置自动停止的方式，帮助用户在资源受限的服务器上运行成千上万个低频访问+少量高频访问的服务。
 
 **核心特性：**
-- ⚡ 极速冷启动（开销仅 25ms）
-- 🚀 流式代理（1-2ms 延迟）
+- ⚡ 极速冷启动
+- 🚀 双向流式转发代理实现极低的请求延迟：将请求体流式给代理服务，将代理服务的响应流式给请求者 所以不需要缓冲请求或者响应，唯一的需要缓冲的时机就是请求到达网关，但是需要被网关唤起的程序还没有启动成功的时候
 - 🌐 支持 SSE 和 WebSocket
-- 🎛️ 通用服务管理（可替代PM2、Docker、systemd 等）
-- 🔄 闲置自动回收
+- 🎛️ 基于bash的通用服务管理（可用于管理PM2、Docker、systemd 等任意服务）
+- 🔄 闲置自动回收资源
 
 ## 技术栈
 
 - **运行时**: Node.js 22+
-- **Web 框架**: uWebSockets.js（性能比 Fastify 快 10 倍以上）
-- **日志**: Pino（异步结构化日志）
+- **Web 框架**: uWebSockets.js（最佳性能）
+- **日志**: Pino
 - **配置**: c12（支持 TypeScript）
-- **构建**: rslib
 - **包管理**: pnpm
 - **测试**: tsx + 自定义测试套件
 
@@ -37,8 +36,6 @@ DynaPM/
 │   ├── test-all.ts              # 完整测试套件（12个测试）
 │   ├── server-*.ts              # 测试服务器
 │   └── benchmark.js             # 性能测试
-├── docs/
-│   └── NPM_OIDC_SETUP.md        # npm OIDC 发布配置指南
 ├── .github/workflows/
 │   └── release.yml              # 自动发布到 npm
 ├── CHANGELOG.md                  # 版本更新日志
@@ -49,12 +46,7 @@ DynaPM/
 
 ## 开发指南
 
-### 快速开始
-
 ```bash
-# 安装依赖
-pnpm install
-
 # 运行测试
 pnpm test
 
@@ -67,4 +59,4 @@ pnpm benchmark
 
 ### 发布新版本
 
-流程 ： CHANGELOG → commit → npm version （git tag） → push 
+流程 ： CHANGELOG → commit →更新 npm version （git add tag） →git push （github actions 会通过 oicd 发包 npm ）

package/README.md

@@ -4,9 +4,7 @@
 
 > **Dynamic Process Manager** - A lightweight, universal service management system with serverless-like features.
 
-[![npm version](https://badge.fury.io/js/dynapm.svg)](https://www.npmjs.com/package/dynapm)
-![Tests](https://img.shields.io/badge/tests-12%2F12 passing-green)
-![Performance](https://img.shields.io/badge/overhead-25ms-brightgreen)
+[![npm version](https://badge.fury.io/js/dynapm.svg)](https://www.npmjs.com/package/dynapm) ![Tests](https://img.shields.io/badge/tests-81%2F81%20passing-green) ![Performance](https://img.shields.io/badge/overhead-25ms-brightgreen)
 
 DynaPM is a **lightweight alternative** to complex container orchestration platforms (like Knative, Sablier) for private deployments. It helps you manage hundreds of low-frequency services on resource-constrained servers by starting them on-demand and stopping them when idle.
 
@@ -59,7 +57,7 @@ You have many side projects or internal tools that:
 
 - **DynaPM overhead**: Only **25ms** (startup command: 8ms + port wait: 17ms)
 - **Instant retry**: Zero-delay polling, forward immediately when port is ready
-- **Total cold start**: ~500ms (including service boot time, e.g., ~475ms for Node.js apps)
+- **Total cold start**: ~185ms (including service boot time, e.g., ~160ms for Node.js apps)
 
 ### 🚀 **Stream Proxying**
 
@@ -149,9 +147,9 @@ Configure ANY service using bash commands - no limits:
 ```
 Test Environment: Node.js HTTP Server (autocannon benchmark)
 
-✅ Cold start:       ~48ms (DynaPM: 25ms + service boot: 23ms)
-✅ Stream proxy:     Avg 9.5ms (range: 8-14ms)
-✅ Throughput:       8,383 req/s (multi-service, 60 concurrent)
+✅ Cold start:       ~185ms (DynaPM: 25ms + service boot: 160ms)
+✅ Stream proxy:     Avg 10.3ms (range: 9-12ms)
+✅ Throughput:       5,942 req/s (multi-service, 150 concurrent)
 ✅ Load test:        Low latency even under high concurrency
 ✅ Memory overhead:  ~50MB (Node.js runtime)
 ✅ Bundle size:      21.7KB (minified)
@@ -183,6 +181,13 @@ const config: DynaPMConfig = {
   port: 3000,
   host: '127.0.0.1',
 
+  // Logging configuration (optional, disable for better performance in production)
+  logging: {
+    enableRequestLog: false,      // Enable request/response logging (high frequency, affects performance)
+    enableWebSocketLog: false,    // Enable WebSocket lifecycle logging
+    // Error logging is always enabled
+  },
+
   services: {
     'app.example.com': {
       name: 'my-app',
@@ -240,7 +245,7 @@ pnpm test
 
 ### Test Coverage
 
-The automated tests validate 12 core functionalities:
+The automated tests validate 81 test cases across 6 test suites:
 
 1. ✅ **On-demand start** - Services auto-start when offline
 2. ✅ **Hot start** - Direct proxy when service is running
@@ -254,6 +259,9 @@ The automated tests validate 12 core functionalities:
 10. ✅ **SSE streaming** - Server-Sent Events proxy support
 11. ✅ **WebSocket** - WebSocket bidirectional communication support
 12. ✅ **Long connections** - Active connections prevent premature shutdown
+13. ✅ **Concurrent startup** - Multiple requests to offline service
+14. ✅ **Security hardening** - Body size limits, CRLF injection protection
+15. ✅ **Port routing** - Direct port-based proxy and on-demand start
 
 ### Test Output Example
 
@@ -421,8 +429,8 @@ Test: Total time from offline to first accessible request
 
 Results:
 ├─ DynaPM overhead:   25ms (startup command: 8ms + TCP port wait: 17ms)
-├─ Service boot:      17ms (Node.js application)
-└─ Total cold start:  42ms
+├─ Service boot:      160ms (Node.js application)
+└─ Total cold start:  185ms
 ```
 
 ### Stream Proxy Performance
@@ -431,30 +439,23 @@ Results:
 Test: Single request latency when service is running
 
 Results:
-├─ Average latency:  9.3ms
-├─ Min latency:      8ms
+├─ Average latency:  10.3ms
+├─ Min latency:      9ms
 ├─ Max latency:      12ms
-└─ Latency range:    8-12ms
+└─ Latency range:    9-12ms
 ```
 
 ### Throughput Performance
 
 ```
-Test: Multi-service benchmark (3 services × 20 concurrent, 5 seconds)
+Test: Multi-service benchmark (3 services × 50 concurrent, 5 seconds)
 
 Results:
-├─ Total requests:      42,000 requests
-├─ Average throughput:  8,383 req/s
-├─ Per-service:         2,794 req/s
+├─ Total requests:      29,710 requests
+├─ Average throughput:  5,942 req/s
+├─ Per-service:         ~1,980 req/s
 ├─ Errors:              0
 └─ Test duration:       5 seconds
-
-Test: Single service benchmark (50 concurrent, 5 seconds)
-
-Results:
-├─ Requests/sec:     4,225+ req/s
-├─ Average latency:  ~23ms
-└─ Total requests:   21k requests
 ```
 
 ### Resource Usage

package/README_zh.md

@@ -4,9 +4,7 @@
 
 > **动态进程管理器** - 具有类 serverless 特性的轻量级通用服务管理系统
 
-[![npm version](https://badge.fury.io/js/dynapm.svg)](https://www.npmjs.com/package/dynapm)
-![Tests](https://img.shields.io/badge/tests-12%2F12 passing-green)
-![Performance](https://img.shields.io/badge/overhead-25ms-brightgreen)
+[![npm version](https://badge.fury.io/js/dynapm.svg)](https://www.npmjs.com/package/dynapm) ![Tests](https://img.shields.io/badge/tests-81%2F81%20passing-green) ![Performance](https://img.shields.io/badge/overhead-25ms-brightgreen)
 
 DynaPM 是**复杂容器编排平台（如 Knative、Sablier）的轻量级替代方案**，专为私有化部署设计。它通过按需启动和闲置自动停止的方式，帮助你在资源受限的服务器上管理数百个低频访问的服务。
 
@@ -59,7 +57,7 @@ DynaPM 是**复杂容器编排平台（如 Knative、Sablier）的轻量级替
 
 - **DynaPM 开销**：仅 **25ms**（启动命令 8ms + 端口等待 17ms）
 - **失败立即重试**：无延迟轮询，端口可用即刻转发
-- **总冷启动**：~500ms（包括服务本身启动时间，如 Node.js 应用 ~475ms）
+- **总冷启动**：~185ms（包括服务本身启动时间，如 Node.js 应用 ~160ms）
 
 ### 🚀 **流式代理**
 
@@ -148,9 +146,9 @@ DynaPM 原生支持现代实时通信协议：
 ```
 测试环境：Node.js HTTP 服务器 (autocannon 压测)
 
-✅ 冷启动时间：   ~48ms (DynaPM: 25ms + 服务启动: 23ms)
-✅ 流式代理延迟：  平均 9.5ms (范围: 8-14ms)
-✅ 吞吐量：       8,383 req/s (多服务, 60 并发)
+✅ 冷启动时间：   ~185ms (DynaPM: 25ms + 服务启动: 160ms)
+✅ 流式代理延迟：  平均 10.3ms (范围: 9-12ms)
+✅ 吞吐量：       5,942 req/s (多服务, 150 并发)
 ✅ 压测延迟：     高并发下保持低延迟
 ✅ 内存开销：     ~50MB (Node.js 运行时)
 ✅ 代码体积：     21.7KB (压缩后)
@@ -182,6 +180,13 @@ const config: DynaPMConfig = {
   port: 3000,
   host: '127.0.0.1',
 
+  // 日志配置（可选，生产环境建议关闭以提升性能）
+  logging: {
+    enableRequestLog: false,      // 是否启用请求日志（高频，影响性能）
+    enableWebSocketLog: false,    // 是否启用 WebSocket 生命周期日志
+    // 错误日志始终启用，不受此开关控制
+  },
+
   services: {
     'app.example.com': {
       name: 'my-app',
@@ -239,7 +244,7 @@ pnpm test
 
 ### 测试覆盖场景
 
-自动化测试会验证以下 12 个核心功能：
+自动化测试会验证以下 81 个测试用例（6 个测试套件）：
 
 1. ✅ **按需启动** - 服务离线时自动启动
 2. ✅ **热启动** - 服务运行时直接代理，无需重新启动
@@ -253,6 +258,9 @@ pnpm test
 10. ✅ **SSE 流式传输** - Server-Sent Events 代理支持
 11. ✅ **WebSocket** - WebSocket 双向通信支持
 12. ✅ **长连接代理** - 活跃连接阻止服务被提前关闭
+13. ✅ **并发启动** - 多个请求同时到达离线服务
+14. ✅ **安全加固** - 请求体大小限制、CRLF 注入防护
+15. ✅ **端口路由** - 端口直连代理和按需启动
 
 ### 测试输出示例
 
@@ -419,8 +427,8 @@ npm install -g autocannon
 
 结果：
 ├─ DynaPM 开销：   25ms (启动命令 8ms + TCP 端口等待 17ms)
-├─ 服务启动时间：   17ms (Node.js 应用)
-└─ 总冷启动时间：   42ms
+├─ 服务启动时间：   160ms (Node.js 应用)
+└─ 总冷启动时间：   185ms
 ```
 
 ### 流式代理性能
@@ -429,22 +437,22 @@ npm install -g autocannon
 测试：服务运行时的单次请求延迟
 
 结果：
-├─ 平均延迟：      9.3ms
-├─ 最小延迟：      8ms
+├─ 平均延迟：      10.3ms
+├─ 最小延迟：      9ms
 ├─ 最大延迟：      12ms
-└─ 延迟范围：      8-12ms
+└─ 延迟范围：      9-12ms
 ```
 
 ### 吞吐量性能
 
 ```
-测试：autocannon 压测 (100 并发, 10 秒)
+测试：多服务混合压测 (3 服务 × 50 并发, 5 秒)
 
 结果：
-├─ 请求数/秒：     4,225 req/s
-├─ 平均延迟：      23.16ms
-├─ 总请求数：      42k requests
-└─ 测试时长：      10 秒
+├─ 请求数/秒：     5,942 req/s
+├─ 平均延迟：      ~10ms
+├─ 总请求数：      29,710 requests
+└─ 测试时长：      5 秒
 ```
 
 ### 资源占用

package/TASK.md

@@ -0,0 +1,53 @@
+具有类 serverless 特性的轻量级通用服务管理系统:dynapm
+## dynapm 开发
+
+/loop 先检查 TASK.md 中是否有未完成的任务请逐项完成并在充分test验证再继续下一项，如果没有则请请完善当前项目：测试更多代理场景，确保网关程序没有问题，监测并优化程序性能,修改完毕后需要使用 pilot 进行实际运行测试，请自我完善，不要询问我任何事情，也不要切换其他模式（例如 plan mode）
+作为网关的测试一定要非常严谨，测试各种可能的情况以及极端情况。
+所有文件使用 ts，需要临时运行的使用 node --experimental-strip-types -e xxx.ts 来执行
+
+## TASKS
+
+[x] 充分测试当前的代理功能是否正确
+[x] 创建一个实用的dynam能力演示程序：实现一个运行ts/js的 serveless host（并不属于 dynapm，但是可以被 dynapm 运行，然后请求又可以被这个  serveless host 路由到 对应的 ts文件去执行）：支持用户通过网站访问并编写 ts 上传执行和测试执行
+
+## 已完成的工作
+
+### 2026-03-20
+
+#### 网关 Bug 修复
+- **并发按需启动修复**: 多个请求同时到达离线服务时，只有第一个触发启动，其他请求等待启动完成后再代理（之前返回 502）
+- **后端崩溃自动恢复**: 当 handleDirectProxy 检测到后端不可达（ECONNREFUSED），自动将非 proxyOnly 服务状态重置为 offline，后续请求可重新触发按需启动
+- **端口路由并发启动修复**: handlePortBindingRequest 补全 starting/stopping 状态处理，与 hostname 路由保持一致
+- **echo-server 支持命令行端口参数**: `parseInt(process.argv[2] || '3099')`，允许不同测试配置使用不同端口
+- **按需启动 POST 请求体丢失修复（严重）**: uWS 的 onData 回调中 ArrayBuffer 是借用语义，`Buffer.from(ab)` 底层数据被后续回调覆盖。改用 `Buffer.alloc + copy` 确保数据复制
+- **transfer-encoding 头冲突修复**: forwardProxyRequest 中过滤 transfer-encoding 头，避免与 content-length 冲突导致后端 400
+- **请求体大小限制（10MB）**: collectRequestBody 超过限制时截断，防止 DoS 攻击
+- **WebSocket 消息队列限制（1000）**: 防止后端未连接时消息无限堆积导致内存泄漏
+- **端口路由 WebSocket close 清理**: 端口路由的 close handler 补充后端 WebSocket 关闭逻辑
+
+#### 性能优化
+- **预编译 CRLF 正则**: `GatewayConstants.CRLF_REGEX` 避免热路径中重复创建正则对象
+- **Set 替代内联条件**: `GatewayConstants.SKIP_REQUEST_HEADERS` 使用 Set.has() 替代重复 toLowerCase + 条件判断
+
+#### 测试覆盖（81 个测试全部通过）
+- **test-proxy-comprehensive.ts**: 23 个综合代理测试
+- **test-edge-cases.ts**: 15 个极端场景测试
+- **test-gateway-robustness.ts**: 13 个健壮性测试
+- **test-port-route-start.ts**: 9 个端口路由按需启动测试
+- **test-admin-api-lifecycle.ts**: 12 个管理 API 生命周期测试
+- **test-security-stability.ts**: 9 个安全与稳定性深度测试
+  - 端口路由并发按需启动（10个同时请求）
+  - 端口路由多种 HTTP 方法（GET/POST/PUT/DELETE/OPTIONS/PATCH）
+  - 端口路由查询参数转发（含中文编码）
+  - 端口路由大请求体转发（100KB）
+  - 端口路由流式响应（20 chunks）
+  - 端口路由状态码透传（200/201/400/404/500）
+  - 端口路由 CRLF 注入防护
+  - 端口路由后端崩溃恢复
+  - 端口路由闲置后重新按需启动
+
+#### Serverless Host 演示
+- test/services/serverless-host.ts: 轻量级 TypeScript Serverless 运行时
+  - Web 管理界面编写/上传/执行/删除函数
+  - 使用 Node --experimental-strip-types 直接加载 TS 函数
+  - 已添加到 dynapm.config.ts 作为 serverless-host 服务

package/dist/src/config/types.d.ts

@@ -30,6 +30,15 @@ export interface ServiceCommands {
     /** 环境变量（可选） */
     env?: Record<string, string>;
 }
+/** 路由配置 */
+export interface RouteConfig {
+    /** 路由类型 */
+    type: 'host' | 'port';
+    /** 路由值：网关端的 hostname 或端口号 */
+    value: string | number;
+    /** 目标后端地址：转发到的实际服务地址 */
+    target: string;
+}
 /** 服务配置 */
 export interface ServiceConfig {
     /** 服务标识 */
@@ -46,16 +55,52 @@ export interface ServiceConfig {
     healthCheck?: HealthCheckConfig;
     /** 纯代理模式：只做反向代理，不启动/停止服务 */
     proxyOnly?: boolean;
+    /** Hostname 映射（可选）：配置后可通过此 hostname 访问 */
+    host?: string;
+    /** 专属端口（可选）：配置后网关会监听此端口 */
+    port?: number;
+    /** 路由配置（可选）：配置多个访问地址 */
+    routes?: RouteConfig[];
     /** 运行时状态（内部使用） */
     _state?: ServiceState;
 }
 /** 服务运行状态 */
 export interface ServiceState {
-    status: 'offline' | 'starting' | 'online';
+    status: 'offline' | 'starting' | 'online' | 'stopping';
     lastAccessTime: number;
     /** 当前活动连接数（HTTP/SSE/WebSocket） */
     activeConnections: number;
     pid?: number;
+    /** 服务启动时间戳 */
+    startTime?: number;
+    /** 累计启动次数 */
+    startCount: number;
+    /** 累计运行时长（毫秒） */
+    totalUptime: number;
+}
+/** 管理 API 配置 */
+export interface AdminApiConfig {
+    /** 是否启用管理 API */
+    enabled?: boolean;
+    /** 管理 API 端口（独立监听） */
+    port?: number;
+    /** 管理 API hostname（可选，使用主端口时需配置） */
+    host?: string;
+    /** API 认证令牌（可选） */
+    authToken?: string;
+    /** 允许访问的 IP 白名单 */
+    allowedIps?: string[];
+}
+/** 日志配置 */
+export interface LoggingConfig {
+    /** 是否启用请求日志（每个请求响应记录） */
+    enableRequestLog?: boolean;
+    /** 是否启用 WebSocket 生命周期日志 */
+    enableWebSocketLog?: boolean;
+    /** 是否启用错误日志（始终启用，不受此开关控制） */
+    enableErrorLog?: boolean;
+    /** 是否启用性能分析日志（用于性能优化调试） */
+    enablePerformanceLog?: boolean;
 }
 /** DynaPM全局配置 */
 export interface DynaPMConfig {
@@ -65,4 +110,8 @@ export interface DynaPMConfig {
     host?: string;
     /** 服务映射：hostname -> 服务配置 */
     services: Record<string, ServiceConfig>;
+    /** 管理 API 配置 */
+    adminApi?: AdminApiConfig;
+    /** 日志配置 */
+    logging?: LoggingConfig;
 }

package/dist/src/core/admin-api.d.ts

@@ -0,0 +1,76 @@
+import type { ServiceConfig } from '../config/types.js';
+import type { HttpResponse, HttpRequest } from 'uWebSockets.js';
+import type { Logger } from 'pino';
+import type { ServiceManager } from './service-manager.js';
+/**
+ * 路由映射信息
+ */
+interface RouteMapping {
+    /** 服务配置 */
+    service: ServiceConfig;
+    /** 目标后端地址 */
+    target: string;
+}
+/**
+ * 管理处理器
+ * 处理所有管理 API 请求
+ */
+export declare class AdminApiHandler {
+    private config;
+    private logger;
+    private hostnameRoutes;
+    private portRoutes;
+    private serviceManager;
+    constructor(config: DynaPMConfig, logger: Logger, hostnameRoutes: Map<string, RouteMapping>, portRoutes: Map<number, RouteMapping>, serviceManager: ServiceManager);
+    /**
+     * 检查客户端 IP 是否在允许列表中
+     */
+    private isIpAllowed;
+    /**
+     * 检查认证令牌是否有效
+     */
+    private isAuthenticated;
+    /**
+     * 获取服务运行时长
+     */
+    private getServiceUptime;
+    /**
+     * 在所有路由表中查找服务
+     */
+    private findServiceMapping;
+    /**
+     * 处理管理 API 请求
+     */
+    handleAdminApi(res: HttpResponse, req: HttpRequest): void;
+    /**
+     * 获取服务列表
+     */
+    private getServicesList;
+    /**
+     * 获取服务详情
+     */
+    private getServiceDetail;
+    /**
+     * 停止服务
+     */
+    stopService(res: HttpResponse, serviceName: string): Promise<void>;
+    /**
+     * 启动服务
+     */
+    startService(res: HttpResponse, serviceName: string): Promise<void>;
+    /**
+     * 处理事件流（SSE）
+     */
+    private handleEventStream;
+}
+/**
+ * DynaPM 配置类型导入
+ */
+interface DynaPMConfig {
+    adminApi?: {
+        enabled?: boolean;
+        authToken?: string;
+        allowedIps?: string[];
+    };
+}
+export {};

package/dist/src/core/gateway.d.ts

@@ -7,51 +7,82 @@ import type { Logger } from 'pino';
 export declare class Gateway {
     private config;
     private serviceManager;
-    /** 服务映射：hostname -> 服务配置 */
-    private services;
+    /** 主机名路由：hostname -> 路由映射信息 */
+    private hostnameRoutes;
+    /** 端口路由：端口 -> 路由映射信息 */
+    private portRoutes;
     /** 日志记录器 */
     private logger;
+    /** 日志配置 */
+    private logging;
+    /** 管理 API 处理器 */
+    private adminApi;
+    /** 服务启动 Promise 追踪：serviceName -> 启动完成 Promise */
+    private startingPromises;
     constructor(config: DynaPMConfig, logger: Logger);
     /**
-     * 初始化服务映射
+     * 初始化服务映射和端口绑定
      */
     private initServices;
     /**
      * 初始化闲置检查器
-     * 定期检查并停止闲置的服务
-     *
-     * 注意：
-     * - 纯代理模式（proxyOnly）不会被停止
-     * - 只有当服务没有活动连接且超过闲置时间时才会停止
-     * - 这样可以避免 SSE/WebSocket 长连接被意外断开
      */
     private initIdleChecker;
+    /**
+     * 检查单个服务是否闲置
+     */
+    private checkIdleService;
+    /**
+     * 处理端口绑定请求
+     */
+    private handlePortBindingRequest;
     /**
      * 处理传入的 HTTP 请求
      */
     private handleRequest;
+    /**
+     * 启动服务并代理请求
+     */
+    private startServiceAndProxy;
+    /**
+     * 处理需要等待服务停止完成的场景
+     */
+    private handleServiceWithWait;
+    /**
+     * 处理服务正在启动中的场景
+     * 等待启动 Promise 完成后，如果成功则直接代理，如果失败则返回 503
+     */
+    private handleServiceWithStartPromise;
     /**
      * 处理需要启动服务的场景
      */
     private handleServiceStart;
     /**
      * 处理直接代理场景（服务已在线）
+     * 双向流式转发：请求体边收边发，响应体边收边回
      */
     private handleDirectProxy;
     /**
-     * 发起代理请求并流式转发响应
+     * 发起代理请求并流式转发响应（用于服务启动/等待场景）
      *
-     * @param res - uWS HttpResponse 对象
-     * @param service - 目标服务配置
-     * @param path - 请求路径（包含查询字符串）
-     * @param startTime - 请求开始时间（用于日志）
-     * @param method - HTTP 方法
-     * @param headers - 请求头
-     * @param body - 请求体
+     * 仅在服务需要启动或等待停止时使用，此时请求体已缓冲为 Buffer。
+     * 响应体保持流式转发。
      */
     private forwardProxyRequest;
     /**
      * 启动网关
      */
     start(): Promise<void>;
+    /**
+     * 为管理 API 创建监听器
+     */
+    private createAdminApiListener;
+    /**
+     * 为指定端口创建监听器
+     */
+    private createPortBindingListener;
+    /**
+     * 清理所有正在运行的服务
+     */
+    cleanup(): Promise<void>;
 }