内容
# <img src="https://github.com/melosso/portway/blob/main/Source/logo.webp?raw=true" alt="" width="34" style="vertical-align: middle;"> 端点网关
[](LICENSE)
[](https://github.com/melosso/portway/commits/main)
[](https://github.com/melosso/portway/releases/latest)
端点网关（Portway）是一个适用于Windows和Linux容器的轻量级**API网关**，它简化了安全服务路由和基础设施管理。
它通过简单的基于文件的配置，将数据库、内部服务和Webhook统一到一个接口中。内置的缓存、审计日志和自动文档使您的数据流可靠且易于控制。
开箱即用，端点网关处理代理传递、SQL端点和Webhook，并原生支持MCP和OData。它还包括Azure Key Vault身份验证、速率限制、管理和完整的Prometheus或任何OTLP收集器的可观察性。
<div>
<p align="center">
<strong>🔍 <a href="https://portway-demo.melosso.com/">查看演示！</a></strong>
</p>
</div>
---
## 前置条件
在部署端点网关之前，请确保您的环境满足以下要求。这些要求确保所有功能（尤其是SQL和身份验证）都能正常运行。
* .NET托管包
* 预览版 >= `v0.7.0`: [.NET 11](https://dotnet.microsoft.com/en-us/download/dotnet/11.0) （目前为预览版）
* 生产环境: [.NET 10 LTS](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) 版本仍然可用
* 如果您在Windows上运行：Internet Information Services（IIS）
* 支持的SQL数据库（如果您使用SQL端点）：SQL Server、PostgreSQL、MySQL/MariaDB或SQLite
准备好了吗？那么让我们继续：
## 快速入门
按照以下步骤让端点网关在您的环境中启动并运行。设置快速且模块化，使您能够轻松配置所需的内容。
### 1. 下载和提取
#### Windows服务器（推荐）
获取[最新版本](https://github.com/melosso/portway/releases)并将其提取到您的部署文件夹中。此版本已包含一组示例环境和端点配置。
注意，在Internet Information Services中配置应用程序之前，请确保配置您的环境特定机密：
```powershell
$bytes = New-Object byte[] 48; [Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes); [Environment]::SetEnvironmentVariable("PORTWAY_ENCRYPTION_KEY", [Convert]::ToBase64String($bytes), "Machine")
```
在容器化环境中，可以使用同名的`PORTWAY_ENCRYPTION_KEY`变量完成此操作。
---
#### **替代方案：Docker Compose**
您可以使用Docker Compose和官方镜像快速部署端点网关：
```yaml
services:
portway:
image: ghcr.io/melosso/portway:latest
ports:
- "8080:8080"
volumes:
- portway_app:/app
- ./environments:/app/environments
- ./endpoints:/app/endpoints
- ./tokens:/app/tokens
- ./log:/app/log
- ./data:/app/data
environment:
# 在此处设置您的加密机密（例如使用openssl rand -hex 32）
- PORTWAY_ENCRYPTION_KEY=您的加密密钥
# 配置CORS、路径前缀和访问令牌
- AllowedHosts=*
- PathBase=
- WebUi__AdminApiKey=不安全-更改-管理员-API-密钥
volumes:
portway_app:
```
然后运行：
```sh
docker compose pull && docker compose up -d
```
这将启动端口为[8080](#)的端点网关，并挂载您的配置文件。根据您的环境调整路径和端口。
### 2. 定义您的环境
定义服务器和环境设置，以隔离您可能需要的各种环境（例如`prod`和`dev`）。这些配置用于您稍后配置的端点。首先，配置允许的环境，然后定义各个环境：
**`environments/settings.json`**
```json
{
"Environment": {
"ServerName": "localhost",
"AllowedEnvironments": ["prod", "dev"]
}
}
```
**`environments/prod/settings.json`**
```json
{
"ServerName": "localhost",
"ConnectionString": "Server=localhost;Database=prod;Trusted_Connection=True;Connection Timeout=5;TrustServerCertificate=true;"
}
```
### 3. 定义您的端点
端点配置为JSON文件。每个类型都有自己的目录和格式，使它们易于管理和扩展。这些是简单的示例，对于更高级的配置，您可能需要阅读我们在<a href="https://melosso.github.io/portway/" target="_blank" rel="noopener noreferrer">文档页面</a>上的详尽文档。端点网关支持多种类型：
* **SQL** （SQL Server、PostgreSQL、MySQL、SQLite）：具有模式级控制和文档的直接CRUD访问
* **代理**：转发到内部服务；支持复杂编排
* **复合**：将多个端点调用链接到一个事务中
* **文件系统**：从本地存储或缓存（内存和/或Redis）读取/写入
* **Webhook**：接收外部调用并将数据持久化到SQL
* **静态**：读取静态文件或设置模拟端点
这些在下面单独处理。配置完成后，每个类型的请求端点将在[示例](#examples)下显示。
<br>
<details>
<summary>SQL端点</summary>
这些直接指向您的数据库表。您可以选择公开哪些列以及它们的公共名称应该是什么。它保持了干净的表面积，并允许您隐藏内部模式或命名怪癖。
#### 示例 — `endpoints/SQL/Products/entity.json`
```json
{
"DatabaseObjectName": "Items",
"DatabaseSchema": "dbo",
"PrimaryKey": "ItemCode",
"AllowedColumns": [
"ItemCode;ProductNumber",
"LongDescription;Description",
"Assortment;AssortmentCode",
"sysguid;InternalID"
],
"AllowedEnvironments": ["prod", "dev"]
}
```
</details>
<br>
<details>
<summary>代理端点</summary>
这些只是将调用传递给另一个服务。它基本上是一个小型反向代理，您可以决定要支持哪些HTTP动词。
#### 示例 — `endpoints/Proxy/Accounts/entity.json`
```json
{
"Url": "http://localhost:8020/services/Exact.Entity.REST.EG/Account",
"Methods": ["GET", "POST", "PUT", "DELETE", "MERGE"],
"AllowedEnvironments": ["prod", "dev"]
}
```
</details>
<br>
<details>
<summary>复合端点</summary>
这些有助于在单个逻辑操作实际上意味着“按特定顺序调用多个其他端点”。考虑创建一个具有多个行和标题的订单。您将步骤连接起来，引擎处理排序。
#### 示例 — `endpoints/Proxy/SalesOrder/entity.json`
```json
{
"Type": "Composite",
"Url": "http://localhost:8020/services/Exact.Entity.REST.EG",
"Methods": ["POST"],
"CompositeConfig": {
"Name": "SalesOrder",
"Description": "使用多个行和标题创建完整的销售订单",
"Steps": [
{
"Name": "CreateOrderLines",
"Endpoint": "SalesOrderLine",
"Method": "POST",
"IsArray": true,
"ArrayProperty": "Lines",
"TemplateTransformations": {
"TransactionKey": "$guid"
}
},
{
"Name": "CreateOrderHeader",
"Endpoint": "SalesOrderHeader",
"Method": "POST",
"SourceProperty": "Header",
"TemplateTransformations": {
"TransactionKey": "$prev.CreateOrderLines.0.d.TransactionKey"
}
}
]
}
}
```
</details>
<br>
<details>
<summary>静态端点</summary>
有时您只需要提供一个文件。JSON、XML、CSV，什么都行。这些端点公开静态内容，如果您启用它，还可以使用OData过滤。
#### 示例 — `endpoints/Static/ProductionMachine/entity.json`
```json
{
"ContentType": "application/xml",
"ContentFile": "summary.xml",
"EnableFiltering": true,
"AllowedEnvironments": ["prod", "dev"]
}
```
</details>
<br>
<details>
<summary>文件端点</summary>
用于存储或检索实际文件，而不是行或JSON。适用于文档、图像、导出。
#### 示例 — `endpoints/Files/Documents/entity.json`
```json
{
"StorageType": "Local",
"BaseDirectory": "documents",
"AllowedExtensions": [".pdf", ".docx", ".xlsx", ".txt"],
"AllowedEnvironments": ["prod", "dev"]
}
```
</details>
<br>
<details>
<summary>Webhook端点</summary>
当外部服务需要将数据推送到您的系统时，这是入口点。有效载荷直接进入您选择的表中。
#### 示例 — `endpoints/Webhooks/Integrations/Inbound/entity.json`
```json
{
"DatabaseObjectName": "WebhookData",
"DatabaseSchema": "dbo",
"AllowedColumns": ["webhook1", "webhook2"]
}
```
</details>
### 4. 部署
当您准备好在IIS或Docker中托管时，请遵循<a href="https://melosso.github.io/portway/guide/deployment" target="_blank" rel="noopener noreferrer">部署指南</a>。它涵盖了应用程序池标识（对于NTLM代理场景是必需的）、安全设置和生产强化。
---
## 安全
端点网关使用基于令牌的轻量级身份验证系统。在请求头中包含令牌，带有Bearer前缀：
```bash
Authorization: Bearer YOUR_TOKEN_HERE
```
首次运行令牌文件、范围控制、Azure Key Vault、静态机密加密和NTLM场景的应用程序标识在<a href="https://melosso.github.io/portway/guide/security" target="_blank" rel="noopener noreferrer">安全指南</a>中涵盖。
---
## 示例
以下是使用端点网关端点的常见请求的示例。
<details>
<summary>SQL</summary>
<br>
使用完整的OData支持查询特定数据：
```bash
GET /api/prod/Products?$filter=Assortment eq 'Books'&$select=ItemCode,Description
````
</details>
<details>
<summary>代理</summary>
<br>
将调用转发到内部REST服务：
```bash
GET /api/prod/Accounts
POST /api/prod/Accounts
```
</details>
<details>
<summary>复合</summary>
<br>
将多个操作链接到一个：
```bash
POST /api/prod/composite/SalesOrder
Content-Type: application/json
{
"Header": {
"OrderDebtor": "60093",
"YourReference": "Connect async"
},
"Lines": [
{ "Itemcode": "ITEM-001", "Quantity": 2, "Price": 0 },
{ "Itemcode": "ITEM-002", "Quantity": 4, "Price": 0 }
]
}
```
</details>
<details>
<summary>静态</summary>
<br>
提供具有可选OData过滤的静态内容：
```bash
GET /api/prod/ProductionMachine?$top=1&$filter=status eq 'running'
Accept: application/xml
```
</details>
<details>
<summary>文件</summary>
<br>
上传、列出和下载文件：
```bash
POST /api/prod/files/Documents
Content-Type: multipart/form-data
file=@report.pdf
GET /api/prod/files/Documents/list
GET /api/prod/files/Documents/abc123fileId
```
</details>
<details>
<summary>Webhook</summary>
<br>
从外部服务接收数据：
```bash
POST /api/prod/Integrations/Inbound/webhook1
Content-Type: application/json
{
"eventType": "order.created",
"data": {
"orderId": "12345",
"customer": "ACME Corp"
}
}
```
</details>
您将在我们的<a href="https://melosso.github.io/portway/" target="_blank" rel="noopener noreferrer">文档页面</a>上找到综合配置示例。
## 文档
我们允许您使用可配置的文档端点公开API。此功能可以禁用。
### 交互式文档
应用程序使用<a href="https://github.com/scalar/scalar" target="_blank" rel="noopener noreferrer">Scalar</a>将您的OpenAPI规范渲染为交互式API文档。在`/docs`处访问它，以探索端点、测试请求和查看响应模式，这些都是根据您的端点配置自动生成的。
### 模型上下文协议（MCP）
应用程序还可以通过HTTP充当MCP服务器。您的端点可以出现在MCP工具注册表中，并可被任何MCP兼容的客户端调用，例如Mistral、VS Code Copilot、自定义代理或内置聊天界面。请注意，这是可选的，默认情况下并非所有端点都作为工具公开。端点网关自己的身份验证和环境范围适用于每个工具调用。请在<a href="https://melosso.github.io/portway/guide/mcp" target="_blank" rel="noopener noreferrer">MCP文档</a>中阅读更多关于MCP集成的相关信息。
### 演练
我们的<a href="https://melosso.github.io/portway/" target="_blank" rel="noopener noreferrer">文档页面</a>将指导您设置端点网关。这涵盖了基本用法和高级配置。如果您希望看到文档中的更改，请随时提交拉取请求。
## 贡献
欢迎贡献，请提交PR帮助改进项目。
## 许可证
在 **EUPL-1.2** 下许可。有关更多信息，请参见 [许可证](LICENSE) 文件。
连接信息
猜你喜欢
暂无推荐服务器