@littlelane/prismix
v0.0.2
Published
Prismix - 高并发请求转发代理服务（插件架构 + PM2 进程管理）
Maintainers
littlelaneReadme
Prismix
一束光入，万径分发 — 高并发请求转发代理服务
基于 http-proxy-3 实现，支持插件化架构和 PM2 进程管理。
功能
- 协议支持：HTTP / HTTPS / WebSocket / SSE / CONNECT 隧道
- 插件架构：按功能拆分，可插拔、可扩展
- PM2 进程管理：自动扩缩、零停机重载、进程监控
- 安全防护：URL 白名单/黑名单、防 SSRF（内网 IP 拦截）
- 速率限制：按 IP 滑动窗口限流
- CORS：可配置跨域策略
- 健康检查：
/__health+/__ready端点 - 优雅关闭：等待活跃连接完成后退出
工作原理
读取请求头 x-request-real-url 作为转发目标地址，将请求完整代理到该地址并透传响应。
Client → Proxy Server → Target (由 x-request-real-url 指定)架构图
整体架构
┌─────────────────────────────────────────────────────────────────┐
│ PM2 Cluster │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Worker 0 │ │ Worker 1 │ │ Worker 2 │ │ Worker N │ │
│ │ (index) │ │ (index) │ │ (index) │ │ (index) │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │ │
│ └──────────────┴──────┬───────┴──────────────┘ │
│ │ │
│ ┌───────▼────────┐ │
│ │ ProxyWorker │ │
│ │ (worker.cjs) │ │
│ └───────┬────────┘ │
│ │ │
│ ┌──────────────┼──────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌────────────┐ ┌───────────┐ │
│ │ HTTP Server │ │ http-proxy │ │ Agents │ │
│ │ (Node.js) │ │ -3 实例 │ │ (连接池) │ │
│ └─────────────┘ └────────────┘ └───────────┘ │
└─────────────────────────────────────────────────────────────────┘请求处理管道
┌─────────────┐
│ Client │
└──────┬──────┘
│
x-request-real-url: https://target.com
│
┌──────▼──────┐
│ HTTP Server │
└──────┬──────┘
│
┌───────────────▼───────────────┐
│ Plugin Pipeline │
│ (PluginManager 中间件管道) │
│ │
│ ┌─────────────────────────┐ │
│ │ 1. CORS 跨域处理 │ │
│ ├─────────────────────────┤ │
│ │ 2. Health 健康检查端点 │ │
│ ├─────────────────────────┤ │
│ │ 3. Rate-Limit IP 限流 │ │
│ ├─────────────────────────┤ │
│ │ 4. Access-Log 请求日志 │ │
│ ├─────────────────────────┤ │
│ │ 5. Security 安全校验 │ │
│ │ • URL 解析 │ │
│ │ • 协议白名单 │ │
│ │ • SSRF 防护 │ │
│ │ • 域名黑/白名单 │ │
│ ├─────────────────────────┤ │
│ │ 6. SSE 流式标记 │ │
│ └─────────────────────────┘ │
└───────────────┬───────────────┘
│
┌──────▼──────┐
│ http-proxy │
│ 转发请求 │
└──────┬──────┘
│
┌──────▼──────┐
│ Target │
│ Server │
└─────────────┘协议支持
┌────────────────────────────────────────────────────────┐
│ Prismix Proxy │
├────────────┬────────────┬──────────────┬───────────────┤
│ HTTP │ HTTPS │ WebSocket │ CONNECT │
│ Request │ Request │ Upgrade │ 隧道 │
├────────────┼────────────┼──────────────┼───────────────┤
│ │ │ │ │
│ proxy.web()│ proxy.web()│ proxy.ws() │ net.connect() │
│ │ │ │ TCP pipe │
├────────────┴────────────┴──────────────┴───────────────┤
│ SSE (流式响应) │
│ 检测 Accept: text/event-stream │
│ 禁用缓冲 · 超时设为 0 · 透传 chunk │
└────────────────────────────────────────────────────────┘组件依赖关系
ecosystem.config.cjs ──→ PM2 (cluster mode, N workers)
│
▼
src/index.ts ──→ ProxyWorker
│
▼
src/lib/worker.ts
├──→ config.ts (环境变量 → 统一配置对象)
├──→ logger.ts (结构化日志, 按级别输出)
├──→ agents.ts (HTTP/HTTPS Keep-Alive 连接池)
└──→ plugin-manager.ts
│
├──→ plugins/cors.ts
├──→ plugins/health.ts
├──→ plugins/rate-limit.ts
├──→ plugins/access-log.ts
├──→ plugins/security.ts
└──→ plugins/sse.ts快速开始
# 安装依赖
npm install
# 开发模式（单进程 + debug 日志，tsx 直接运行 TS）
npm run dev
# 构建
npm run build
# 生产模式（PM2 多进程，自动先构建）
npm run pm2:start使用方式
请求示例
# HTTP 转发
curl -H "x-request-real-url: https://api.example.com/users?page=1" \
http://localhost:3000/
# POST 转发
curl -X POST \
-H "x-request-real-url: https://api.example.com/data" \
-H "Content-Type: application/json" \
-d '{"name":"test"}' \
http://localhost:3000/
# SSE 转发
curl -H "x-request-real-url: https://api.example.com/stream" \
-H "Accept: text/event-stream" \
http://localhost:3000/
# WebSocket
wscat -c ws://localhost:3000 -H "x-request-real-url: wss://ws.example.com/socket"健康检查
curl http://localhost:3000/__health
# {"status":"ok","pid":12345,"uptime":3600,"activeConnections":5,"memory":"45MB","rss":"82MB"}
curl http://localhost:3000/__ready
# {"ready":true}PM2 管理
# 启动
npm run pm2:start
# 开发环境启动
npm run pm2:dev
# 扩缩容
pm2 scale prismix +2 # 加 2 个进程
pm2 scale prismix -1 # 减 1 个进程
pm2 scale prismix 4 # 固定 4 个进程
# 零停机重载
npm run pm2:reload
# 监控
npm run pm2:monit # 实时面板
pm2 status # 进程状态
npm run pm2:logs # 查看日志
# 停止
npm run pm2:stop环境变量
| 变量 | 默认值 | 说明 |
|------|--------|------|
| PROXY_PORT | 3000 | 监听端口 |
| PROXY_TIMEOUT | 30000 | 转发超时（ms），SSE 不受限 |
| PROXY_ALLOWED_HOSTS | 空（不限制） | 目标域名白名单（逗号分隔） |
| PROXY_BLOCKED_HOSTS | localhost 等 | 目标域名黑名单（逗号分隔） |
| PROXY_RATE_LIMIT | 0（不限制） | 每 IP 每分钟最大请求数 |
| PROXY_CORS_ORIGIN | * | CORS 允许的 Origin |
| PROXY_LOG_LEVEL | info | 日志级别：debug / info / warn / error |
项目结构
proxy-server/
├── src/
│ ├── index.ts # 服务入口
│ ├── bin.ts # CLI 入口
│ ├── exports.ts # npm 包公开 API
│ ├── lib/
│ │ ├── config.ts # 统一配置
│ │ ├── logger.ts # 结构化日志
│ │ ├── agents.ts # HTTP/HTTPS 连接池
│ │ ├── plugin-manager.ts # 插件管理器（含类型定义）
│ │ └── worker.ts # 代理服务主逻辑
│ └── plugins/
│ ├── cors.ts # CORS 跨域
│ ├── health.ts # 健康检查
│ ├── rate-limit.ts # 速率限制
│ ├── security.ts # 安全验证（防 SSRF）
│ ├── sse.ts # SSE 流式支持
│ └── access-log.ts # 请求日志
├── dist/ # 构建产物（ESM + CJS）
├── ecosystem.config.cjs # PM2 配置
├── tsconfig.json # TypeScript 配置
├── tsconfig.cjs.json # CJS 输出配置
└── package.json插件开发
创建 src/plugins/my-plugin.ts：
import type http from 'node:http';
import type net from 'node:net';
import type { Plugin, PluginContext } from '../lib/plugin-manager.js';
function myPlugin(): Plugin {
return {
name: 'my-plugin',
// 请求进入时（返回 true 中断管道）
onRequest(req: http.IncomingMessage, res: http.ServerResponse, context: PluginContext) {
return false;
},
// WebSocket upgrade 时
onUpgrade(req: http.IncomingMessage, socket: net.Socket, head: Buffer, context: PluginContext) {
return false;
},
// 代理请求发出前
onProxyReq(proxyReq: http.ClientRequest, req: http.IncomingMessage, res: http.ServerResponse) {},
// 代理响应返回时
onProxyRes(proxyRes: http.IncomingMessage, req: http.IncomingMessage, res: http.ServerResponse) {},
// 错误处理（返回 true 表示已处理）
onError(err: Error, req: http.IncomingMessage, res: http.ServerResponse) {
return false;
},
// 优雅关闭时
destroy() {},
};
}
export default myPlugin;在 src/lib/worker.ts 的 initPlugins() 中注册：
import myPlugin from '../plugins/my-plugin.js';
private initPlugins(): void {
this.plugins
.use(corsPlugin)
.use(healthPlugin)
.use(myPlugin) // 新增
.use(rateLimitPlugin)
.use(securityPlugin)
.use(ssePlugin);
}作为 npm 包使用
import { ProxyWorker, CONFIG, logger } from 'prismix';
import type { Plugin, PluginFactory } from 'prismix';
const worker = new ProxyWorker();
worker.start();发布
# 构建并发布
npm publish --access public安全说明
- 防 SSRF：默认禁止转发到
localhost、127.0.0.1、内网 IP 段（10.x / 172.16-31.x / 192.168.x）、云元数据端点 - 协议限制：仅允许
http:/https:协议 - 白名单：生产环境建议配置
PROXY_ALLOWED_HOSTS限定可转发的目标域名 - 自定义 header 清理：
x-request-real-url不会透传给目标服务
License
ISC