@robiki/proxy 1.0.2 → 1.0.3

package/README.zh.md

@@ -1,11 +1,11 @@
 # 🚀 Robiki 代理
 
-> 一个高性能、灵活的 HTTP/2 反向代理，支持 WebSocket、可配置路由、CORS 和请求验证。可作为 npm 包在 Node.js 应用程序中使用，也可作为独立的 Docker 容器使用。仅用作本地开发环境的域名代理。
+> 一个高性能的 HTTP/2 反向代理，支持 WebSocket、可配置路由、CORS 和请求验证。可作为 npm 包或 Docker 容器用于本地开发环境。
 
 [![npm version](https://img.shields.io/npm/v/@robiki/proxy.svg)](https://www.npmjs.com/package/@robiki/proxy)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## 🌍 语言 / Languages / Sprachen / 言語 / Języki / Idiomas / Языки
+## 🌍 语言
 
 [English](README.md) | [Deutsch](README.de.md) | [中文](README.zh.md) | [日本語](README.ja.md) | [Polski](README.pl.md) | [Español](README.es.md) | [Русский](README.ru.md)
 
@@ -23,49 +23,23 @@
 
 ## 📦 安装
 
-### 作为 npm 包
+### npm 包
 
 ```bash
 npm install @robiki/proxy
-```
-
-```bash
+# 或
 yarn add @robiki/proxy
 ```
 
-### 作为 Docker 容器
+### Docker
 
 ```bash
 docker pull robiki/proxy:latest
 ```
 
-### 作为 Docker Compose 服务
-
-```yaml
-services:
-  proxy:
-    image: robiki/proxy:latest
-    container_name: robiki-proxy
-    restart: unless-stopped
-    ports:
-      - '443:443'
-      - '8080:8080'
-      - '9229:9229'
-    volumes:
-      - ./proxy.config.json:/app/proxy.config.json:ro
-      - ./certs:/app/certs:ro
-    networks:
-      - app-network
-```
-
-## 注意事项
-
-- 本地配置的主机应添加到本地 `hosts` 文件中。
-- 如果您使用自定义证书，需要将证书文件添加到 `certs` 目录。
-
 ## 🚀 快速开始
 
-### 作为 npm 包使用
+### npm 包
 
 ```javascript
 import { createProxy } from '@robiki/proxy';
@@ -88,13 +62,11 @@ const proxy = await createProxy({
     },
   },
 });
-
-console.log('代理服务器正在运行！');
 ```
 
-### 使用 Docker
+### Docker
 
-1. 创建 `proxy.config.json` 文件：
+创建 `proxy.config.json`：
 
 ```json
 {
@@ -108,20 +80,14 @@ console.log('代理服务器正在运行！');
     "api.example.com": {
       "target": "backend-service:3000",
       "ssl": true
-    },
-    "example.com": {
-      "target": "frontend-service:8080",
-      "ssl": false
     }
   }
 }
 ```
 
-2. 创建 `docker-compose.yml`：
+创建 `docker-compose.yml`：
 
 ```yaml
-version: '3.8'
-
 services:
   proxy:
     image: robiki/proxy:latest
@@ -133,25 +99,9 @@ services:
       - ./certs:/app/certs:ro
     environment:
       - PROXY_CONFIG=/app/proxy.config.json
-    networks:
-      - app-network
-
-  backend-service:
-    image: your-backend-image
-    networks:
-      - app-network
-
-  frontend-service:
-    image: your-frontend-image
-    networks:
-      - app-network
-
-networks:
-  app-network:
-    driver: bridge
 ```
 
-3. 启动服务：
+启动：
 
 ```bash
 docker-compose up -d
@@ -159,9 +109,9 @@ docker-compose up -d
 
 ## 📖 配置
 
-### 配置文件
+### JSON 配置
 
-创建具有以下结构的 `proxy.config.json` 文件：
+简单的声明式配置：
 
 ```json
 {
@@ -169,24 +119,17 @@ docker-compose up -d
   "ssl": {
     "key": "./certs/key.pem",
     "cert": "./certs/cert.pem",
-    "ca": "./certs/ca.pem",
     "allowHTTP1": true
   },
   "cors": {
     "origin": "*",
-    "methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
-    "allowedHeaders": ["Content-Type", "Authorization"],
-    "credentials": true,
-    "maxAge": 86400
+    "methods": ["GET", "POST", "PUT", "DELETE"],
+    "credentials": true
   },
   "routes": {
     "api.example.com": {
-      "target": "backend-service:3000",
-      "ssl": true,
-      "cors": {
-        "origin": ["https://example.com"],
-        "credentials": true
-      }
+      "target": "backend:3000",
+      "ssl": true
     },
     "*.example.com": {
       "target": "wildcard-service:4000",
@@ -196,78 +139,32 @@ docker-compose up -d
 }
 ```
 
-### 环境变量
-
-您还可以使用环境变量配置代理：
-
-```bash
-# SSL 配置
-SSL_KEY=/app/certs/key.pem
-SSL_CERT=/app/certs/cert.pem
-SSL_CA=/app/certs/ca.pem
-SSL_ALLOW_HTTP1=true
-
-# CORS 配置
-CORS_ORIGIN=*
-CORS_METHODS=GET,POST,PUT,DELETE,OPTIONS
-CORS_HEADERS=Content-Type,Authorization
-CORS_CREDENTIALS=true
-
-# 调试模式
-DEBUG=true  # 启用代理连接和错误的详细日志记录
-```
-
-## 🎯 高级用法
-
-### URL 重映射
-
-在转发到目标服务之前转换 URL：
-
-```javascript
-const config = {
-  routes: {
-    'api.example.com': {
-      target: 'backend:3000',
-      ssl: true,
-      remap: (url) => {
-        // 删除 /api 前缀
-        return url.replace(/^\/api/, '');
-      },
-    },
-  },
-};
-```
-
-### 请求验证
+### JavaScript 配置
 
-为身份验证、速率限制等添加自定义验证逻辑：
+用于高级功能，如 URL 重映射和验证：
 
 ```javascript
-const config = {
-  // 全局验证
-  validate: async (info) => {
-    if (!info.headers.authorization) {
-      return {
-        status: false,
-        code: 401,
-        message: '未授权',
-        headers: { 'www-authenticate': 'Bearer' },
-      };
-    }
-    return { status: true };
+// proxy.config.cjs
+module.exports = {
+  ports: [443, 8080],
+  ssl: {
+    key: './certs/key.pem',
+    cert: './certs/cert.pem',
+    allowHTTP1: true,
   },
   routes: {
     'api.example.com': {
       target: 'backend:3000',
       ssl: true,
-      // 路由特定验证
+      // URL 重映射
+      remap: (url) => url.replace(/^\/api/, ''),
+      // 请求验证
       validate: async (info) => {
-        const rateLimit = await checkRateLimit(info.remoteAddress);
-        if (!rateLimit.allowed) {
+        if (!info.headers.authorization) {
           return {
             status: false,
-            code: 429,
-            message: '请求过多',
+            code: 401,
+            message: 'Unauthorized',
           };
         }
         return { status: true };
@@ -277,93 +174,80 @@ const config = {
 };
 ```
 
-### 自定义 CORS 配置
+### TypeScript 配置
 
-全局或按路由配置 CORS：
+类型安全的配置，完整的 IDE 支持：
 
-```javascript
-const config = {
-  // 全局 CORS
-  cors: {
-    origin: ['https://example.com', 'https://www.example.com'],
-    methods: ['GET', 'POST', 'PUT', 'DELETE'],
-    allowedHeaders: ['Content-Type', 'Authorization'],
-    credentials: true,
-    maxAge: 86400,
+```typescript
+// proxy.config.ts
+import type { ServerConfig, ConnectionInfo } from '@robiki/proxy';
+
+const config: ServerConfig = {
+  ports: [443, 8080],
+  ssl: {
+    key: './certs/key.pem',
+    cert: './certs/cert.pem',
+    allowHTTP1: true,
   },
   routes: {
     'api.example.com': {
       target: 'backend:3000',
       ssl: true,
-      // 路由特定 CORS（覆盖全局）
-      cors: {
-        origin: '*',
-        credentials: false,
+      remap: (url: string) => url.replace(/^\/api/, ''),
+      validate: async (info: ConnectionInfo) => {
+        if (!info.headers['x-api-key']) {
+          return { status: false, code: 401, message: 'API Key Required' };
+        }
+        return { status: true };
       },
     },
   },
 };
-```
 
-### 自定义处理程序
+export default config;
+```
 
-为高级用例创建自定义请求处理程序：
+### 环境变量
 
-```javascript
-import { createCustomProxy } from '@robiki/proxy';
+```bash
+# SSL 配置
+SSL_KEY=/app/certs/key.pem
+SSL_CERT=/app/certs/cert.pem
+SSL_ALLOW_HTTP1=true
 
-const customRestHandler = async (req, res) => {
-  if (req.url === '/health') {
-    res.writeHead(200, { 'content-type': 'application/json' });
-    return res.end(JSON.stringify({ status: 'ok' }));
-  }
-  // 回退到默认代理行为
-  const { restAPIProxyHandler } = await import('@robiki/proxy/connections');
-  return restAPIProxyHandler(req, res);
-};
+# CORS 配置
+CORS_ORIGIN=*
+CORS_METHODS=GET,POST,PUT,DELETE
+CORS_CREDENTIALS=true
 
-const proxy = await createCustomProxy(config, {
-  rest: customRestHandler,
-  websocket: customWebSocketHandler,
-  stream: customStreamHandler,
-});
+# 调试模式
+DEBUG=true
 ```
 
 ## 🔧 API 参考
 
-### `createProxy(config: ServerConfig): Promise<ProxyServer>`
-
-使用给定配置创建并启动代理服务器。
-
-**参数：**
-
-- `config`：服务器配置对象
-
-**返回：** 解析为 `ProxyServer` 实例的 Promise
+### `createProxy(config: ServerConfig)`
 
-### `ProxyServer`
+创建并启动代理服务器。
 
-**方法：**
-
-- `start()`：启动代理服务器
-- `stop()`：停止代理服务器
-- `getConfig()`：获取当前配置
-
-### 配置类型
-
-#### `ServerConfig`
+**ServerConfig:**
 
 ```typescript
 interface ServerConfig {
   ports?: number[];
-  ssl?: CertificateConfig;
+  ssl?: {
+    key: string;
+    cert: string;
+    ca?: string;
+    allowHTTP1?: boolean;
+  };
   routes: Record<string, RouteConfig>;
   cors?: CorsConfig;
   validate?: (info: ConnectionInfo) => Promise<ForwardValidationResult>;
 }
 ```
 
-#### `RouteConfig`
+**RouteConfig:**
 
 ```typescript
 interface RouteConfig {
@@ -375,265 +259,86 @@ interface RouteConfig {
 }
 ```
 
-#### `CorsConfig`
-
-```typescript
-interface CorsConfig {
-  origin?: string | string[];
-  methods?: string[];
-  allowedHeaders?: string[];
-  exposedHeaders?: string[];
-  credentials?: boolean;
-  maxAge?: number;
-}
-```
-
-#### `ConnectionInfo`
-
-```typescript
-interface ConnectionInfo {
-  id: number;
-  method: string;
-  path: string;
-  remoteAddress: string;
-  scheme: string;
-  authority: string;
-  origin: string;
-  headers: IncomingHttpHeaders;
-  query: URLSearchParams;
-  type: RequestType;
-}
-```
-
 ## 🐳 Docker 使用
 
-### 在另一个项目中使用
-
-1. 将代理添加到您的 `docker-compose.yml`：
+挂载您的配置文件（JSON、.cjs 或 .ts）：
 
 ```yaml
 services:
   proxy:
     image: robiki/proxy:latest
-    ports:
-      - '443:443'
-      - '8080:8080'
     volumes:
-      - ./proxy.config.json:/app/proxy.config.json:ro
+      - ./proxy.config.cjs:/app/proxy.config.cjs:ro
       - ./certs:/app/certs:ro
-    networks:
-      - your-network
-
-  your-service:
-    image: your-service-image
-    networks:
-      - your-network
-```
-
-2. 在 `proxy.config.json` 中配置路由以指向您的服务
-
-3. 启动您的堆栈：
-
-```bash
-docker-compose up -d
-```
-
-### 构建自定义镜像
-
-创建自定义 Dockerfile：
-
-```dockerfile
-FROM robiki/proxy:latest
-
-# 复制您的配置
-COPY proxy.config.json /app/proxy.config.json
-COPY certs /app/certs
-
-# 设置环境变量
-ENV PROXY_CONFIG=/app/proxy.config.json
+    environment:
+      - PROXY_CONFIG=/app/proxy.config.cjs
 ```
 
-## 📚 示例
-
-查看 `examples/` 目录以获取更多使用示例：
-
-- `basic-usage.js` - 简单的代理设置
-- `advanced-usage.js` - 高级功能（验证、CORS、重映射）
-- `custom-handlers.js` - 自定义请求处理程序
-- `docker-compose.example.yml` - 完整的 Docker 设置
-
-## 🔐 SSL/TLS 证书
-
-### 生成自签名证书
+## 🔐 SSL 证书
 
-用于开发：
+### 开发环境（自签名）
 
 ```bash
 mkdir -p certs
 openssl req -x509 -newkey rsa:4096 -keyout certs/key.pem -out certs/cert.pem -days 365 -nodes
 ```
 
-### 使用 Let's Encrypt
-
-用于生产，使用 Let's Encrypt 证书：
+### 生产环境（Let's Encrypt）
 
 ```bash
 certbot certonly --standalone -d example.com
 ```
 
-然后在您的配置中引用它们：
-
-```json
-{
-  "ssl": {
-    "key": "/etc/letsencrypt/live/example.com/privkey.pem",
-    "cert": "/etc/letsencrypt/live/example.com/fullchain.pem"
-  }
-}
-```
-
-## 🤝 贡献
-
-欢迎贡献！请随时提交 Pull Request。
-
-## 📄 许可证
-
-MIT © Robiki sp. z o.o.
-
-## 🔗 链接
-
-- [GitHub 仓库](https://github.com/robiki-ai/robiki-proxy)
-- [npm 包](https://www.npmjs.com/package/@robiki/proxy)
-- [问题跟踪器](https://github.com/robiki-ai/robiki-proxy/issues)
-
-## 💡 用例
-
-- **微服务架构**：根据域名/路径将请求路由到不同的服务
-- **开发环境**：用于测试多个服务的本地代理
-- **API 网关**：具有身份验证和速率限制的集中入口点
-- **SSL 终止**：在代理级别处理 SSL/TLS
-- **CORS 管理**：集中式 CORS 配置
-- **负载均衡**：在多个实例之间分配流量（使用自定义处理程序）
-
 ## 🛠️ 故障排除
 
 ### 调试模式
 
-启用详细日志记录以排除连接问题：
+启用详细日志记录：
 
 ```bash
-# 启用调试模式
-DEBUG=true node your-proxy-script.js
-
-# 或使用 Docker
+DEBUG=true node your-script.js
+# 或
 docker run -e DEBUG=true robiki/proxy:latest
-
-# 或在 docker-compose.yml 中
-services:
-  proxy:
-    image: robiki/proxy:latest
-    environment:
-      - DEBUG=true
 ```
 
-当 `DEBUG=true` 时，代理将记录：
-- 所有代理连接尝试（REST、WebSocket、HTTP/2 流）
-- 请求和响应详细信息
-- 连接错误和超时
-- 代理错误和客户端错误
-
 ### 端口已被占用
 
-代理将自动尝试终止配置端口上的进程。如果失败，请手动释放端口：
-
 ```bash
 lsof -ti:443 | xargs kill -9
-lsof -ti:8080 | xargs kill -9
 ```
 
-### SSL 证书错误
-
-确保您的证书文件可读并且格式正确（PEM）。对于开发，使用自签名证书。
-
-### WebSocket 连接问题
-
-确保您的 WebSocket 路由配置了正确的协议（ws/wss），并且目标服务支持 WebSocket 连接。
-
 ## 🧪 测试
 
-Robiki Proxy 包含一个全面的测试套件，涵盖单元测试、集成测试和高级场景。
-
-### 运行测试
-
 ```bash
 # 运行所有测试
 yarn test
 
-# 在监视模式下运行测试
-yarn test:watch
-
-# 运行带覆盖率的测试
+# 带覆盖率
 yarn test:coverage
 
-# 使用 UI 运行测试
-yarn test:ui
-```
-
-### 测试覆盖率
-
-测试套件包括：
-
-- **单元测试**：配置、实用程序、标头转换、CORS 处理
-- **集成测试**：HTTP 代理、路由解析、验证、配置加载
-- **高级测试**：WebSocket 代理、HTTP/2 流、并发连接
-- **Docker 测试**：容器构建、配置加载、运行时行为
-
-### Docker 测试
-
-运行 Docker 集成测试：
-
-```bash
-# 完整的 Docker 集成测试
+# Docker 测试
 yarn test:docker
-
-# 专门测试配置加载
-yarn test:docker:config
-
-# 运行所有测试（单元 + 集成 + Docker）
-yarn test:all
 ```
 
-或使用 Make：
-
-```bash
-# 快速 Docker 构建测试
-make test-docker
-
-# 完整的集成测试套件
-make test-docker-full
-
-# 配置加载测试
-make test-docker-config
+## 📚 示例
 
-# Docker Compose 测试
-make test-docker-compose
-```
+查看 `examples/` 目录：
 
-有关更多详细信息，请参阅 [Docker 测试 README](tests/docker/README.md)。
+- `basic-usage.js` - 简单的代理设置
+- `advanced-usage.js` - 验证、CORS、重映射
+- `custom-handlers.js` - 自定义请求处理器
+- `docker-compose.example.yml` - Docker 设置
 
-## 📊 性能
+## 🤝 贡献
 
-该代理基于 Node.js 原生 HTTP/2 实现，专为高性能而设计：
+欢迎贡献！详情请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
 
-- 高效的流处理
-- 最小的开销
-- 连接池
-- 自动 HTTP/1.1 回退
+## 📄 许可证
 
-对于生产部署，请考虑：
+MIT © Robiki sp. z o.o.
 
-- 使用进程管理器（PM2、systemd）
-- 为多核系统启用集群
-- 使用健康检查进行监控
-- 设置适当的日志记录
+## 🔗 链接
 
+- [GitHub 仓库](https://github.com/robiki-ai/robiki-proxy)
+- [npm 包](https://www.npmjs.com/package/@robiki/proxy)
+- [问题跟踪](https://github.com/robiki-ai/robiki-proxy/issues)