samply/beam-connect

Samply.Beam.Connect 镜像文档

!https://github.com/samply/beam-connect/raw/main/doc/Logo.svg

镜像概述和主要用途

Samply.Beam.Connect是分布式任务代理https://github.com/samply/beam%E7%9A%84HTTP%E4%B8%AD%E7%BB%A7%E5%BA%94%E7%94%A8%E3%80%82%E5%AE%83%E7%94%A8%E4%BA%8E%E6%8F%90%E4%BE%9B%E9%80%8F%E6%98%8E%E7%9A%84HTTP%E5%B0%81%E8%A3%85%E6%96%B9%E6%B3%95%EF%BC%8C%E9%80%9A%E8%BF%87Samply.Beam%E4%BB%BB%E5%8A%A1%E6%9C%BA%E5%88%B6%E4%BC%A0%E8%BE%93%E8%AF%B7%E6%B1%82%E5%92%8C%E5%9B%9E%E5%A4%8D%EF%BC%8C%E5%85%B6%E4%BD%BF%E7%94%A8%E9%81%B5%E5%BE%AA%E5%B8%B8%E8%A7%84HTTP%E4%BB%A3%E7%90%86%E8%AF%AD%E4%B9%89%E3%80%82

核心功能和特性

• 转发模式（Forwarder Mode）：封装HTTP请求并发送到Samply.Beam管道中。
• 接收模式（Receiver Mode）：接收封装的HTTP请求，并通过与目标端点通信进行回复。
• 双模同时运行：单个Beam.Connect进程可同时运行转发和接收两种模式。
• HTTP代理语义：使用方式符合标准HTTP代理的使用习惯。
• 灵活部署：支持本地构建运行或通过Docker镜像部署。

使用场景和适用范围

本镜像适用于已部署Samply.Beam环境的场景，需已存在运行中的Samply.Beam.Broker（中央代理）、Samply.Beam.CA（证书颁发机构）和至少两个本地Samply.Proxies（代理节点）。如需搭建此环境，请参考https://github.com/samply/beam/blob/main/README.md%E3%80%82

详细使用方法和配置说明

本地构建和运行

克隆仓库并进入目录

bash
git clone https://github.com/samply/beam-connect.git
cd beam-connect

通过Rust构建

bash
cargo build --release

作为应用运行

进入二进制文件目录（默认构建后路径为./target/release），启动Samply.Beam.Connect：

bash
./connect --proxy-url <PROXY_URL> --app-id <APP_ID> --local-targets-file <LOCAL_TARGETS_FILE> --discovery-url <DISCOVERY_URL> (--proxy-apikey <PROXY_APIKEY>) (--bind-addr 0.0.0.0:8062)

命令行参数说明

• 必填参数：

  • PROXY_URL：用于连接Samply.Broker的本地Samply.Proxy的URL。
  • APP_ID：Beam.Connect应用的BeamId。
  • LOCAL_TARGETS_FILE：本地服务解析文件的路径（见请求路由）。
  • DISCOVERY_URL：用于查询中央服务发现的URL（或本地文件路径）（见请求路由）。

• 仅接收模式需填参数：

  • PROXY_APIKEY：Beam.Connect在Samply.Broker上注册监听时使用的API密钥。

• 可选参数：

  • BIND_ADDR：Beam.Connect监听的接口和端口，默认值为0.0.0.0:8062。
  • NO_AUTH：可选标志，设置后Samply.Beam.Connect不要求Proxy Authorization头，即转发请求时不进行（客户端）认证。

所有参数均可通过环境变量指定。

使用Docker运行

拉取镜像

bash
docker pull samply/beam-connect

启动容器

通过环境变量提供与作为应用运行相同的参数：

bash
docker run -e PROXY_URL='<PROXY_URL>' \
           -e APP_ID='<APP_ID>' \
           -e LOCAL_TARGETS_FILE='<LOCAL_TARGETS_FILE>' \
           -e DISCOVERY_URL='<DISCOVERY_URL>' \
           -e PROXY_APIKEY='<PROXY_APIKEY>' \
           -e BIND_ADDR='<BIND_ADDR>' \
           -e NO_AUTH='true' \
           samply/beam-connect

说明：环境变量PROXY_APIKEY仅在接收模式下需要；BIND_ADDR和NO_AUTH为可选参数。

使用Beam.Connect转发HTTP请求

以下是使用cURL通过Beam.Connect访问第23大学医院（uk23）内部服务的示例：

bash
curl -x http://localbeamconnect:8081 -H "Proxy-Authorization: ApiKey connect1.proxy23.localhost Connect1Secret" -H "Authorization: basic YWxhZGRpbjpvcGVuc2VzYW1l" http://uk23.virtual/json

参数说明

• -x http://localbeamconnect:8081：指定Beam.Connect作为HTTP代理。
• -H "Proxy-Authorization: ApiKey connect1.proxy23.localhost Connect1Secret"：Beam.Connect与Samply.Proxy之间的认证信息。
• -H "Authorization: basic YWxhZGRpbjpvcGVuc2VzYW1l"：将被转发到目标资源的认证头。
• http://uk23.virtual/json：请求的目标资源。

请求路由

需提供请求资源与Beam.AppId之间的可配置映射以路由消息。此映射通过以下方式实现：首先，中央服务发现将HTTP权威部分（示例中的uk23.virtual）映射到可访问的Beam.AppId（接收方）；然后，同一权威部分通过本地目标文件替换为内部主机名。映射示例可在examples/文件夹中找到。

通信中的错误将以适当的HTTP响应返回。

若Beam.Connect前部署了一个或多个反向代理，Host头可能被代理覆盖。此时，可设置X-Replace-Host头手动替换Beam.Connect中的主机头。

站点发现

如命令行参数列表所述，中央站点发现信息从指定的URL或本地JSON文件获取。为避免本地服务需要对外连接，Samply.Beam.Connect将接收的信息通过本地REST端点导出：GET http://<beam_connect_url>:<beam_connect_port>/sites。注意，此信息仅在启动时获取，在程序运行期间保持静态。

HTTPS支持

支持HTTPS，但需配置以下参数：

• SSL_CERT_PEM：用于传入SSL连接的PEM证书文件路径。
• SSL_CERT_KEY：SSL连接对应的密钥文件路径。
• TLS_CA_CERTIFICATES_DIR：若本地目标使用自签名证书且未被beam-connect信任，需将目标证书作为PEM文件放置于此目录下。

注意事项

• 目前Samply.Beam.Connect不实现流传输功能。在预期使用场景中，Beam.Connect和Samply.Proxy位于同一特权网络中，因此可使用纯HTTP通信，或配置HTTPS。当然，对于出站流量，Samply.Proxy会自行对 payload 进行签名和加密。
• 在接收模式下，Beam.Connect仅中继白名单资源的请求，以减轻潜在滥用风险。