@agent-device/proxy

中文文档
0.21.38发布于 2026/11/17MITTypeScriptES Module零依赖构建来源已验证近 30 天下载 2万

在代理设备守护进程前的运输中性认证代理.

中文使用文档
文档目录8 节
  1. 安装
  2. 为 HTTP 代理服务
  3. 带上自己的交通工具
  4. 通过 TLS 隧道上传服务
  5. 在自己的交通工具上到达守护进程
  6. 认证每个客户端
  7. 选项
  8. 保健和重新启动

@ agent-device/ 代理服务器

后面的代理服务器 agent-device proxy作为图书馆。 把它嵌入你自己的网关 给远程 agent-device 客户端访问另一台机器上的守护进程, 超过您选择的运输方式 .

代理服务器 :

  • 用您选择的符号或您自己的支票认证客户端, 并且从不曝光 守护进程本身的标志;
  • 仅转发远程客户端需要的路径 : /health, (中文(简体) ), /rpc,上传,文物,以及 要求诊断;
  • 拒绝在守护进程主机上安装名为文件的源 ;
  • 重写上传门票,所以客户端通过代理上传,而不是直接到守护进程.

需要节点js 22.12 或以后.

安装

npm install @agent-device/proxy

保持其版本接近其背后的守护进程. 客户拒绝代理 守护进程说 不同的 RPC 协议版本,在命令运行之前.

为 HTTP 代理服务

import { createDaemonProxyServer } from '@agent-device/proxy';

const server = createDaemonProxyServer({
  upstreamBaseUrl: 'http://127.0.0.1:4310',
  upstreamToken: process.env.AGENT_DEVICE_DAEMON_TOKEN!,
  clientToken: process.env.GATEWAY_CLIENT_TOKEN!,
});
server.listen(8080);

连接客户端 agent-device connect proxy --daemon-base-url https://gateway.example.com/agent-device 财务报告和审定财务报表 AGENT_DEVICE_DAEMON_AUTH_TOKEN 设置为 clientToken。每个代理人自行设置 AGENT_DEVICE_SESSION (或通过) --session: 拒绝在代理连接上命名会话的命令 .

要挂载已存在的代理 node:http 或者说 node:https 服务器,使用 createDaemonProxyRequestListener(createDaemonProxy(options))。 。 。 .

带上自己的交通工具

createDaemonProxy 没有自己的服务器 。 符合标准 Request 有标准的对象 Response 对象,因此,任何可兼容的节点.js运行时间或框架,会讲到获取 API 主机:

import { createDaemonProxy } from '@agent-device/proxy';

const proxy = createDaemonProxy({
  upstreamBaseUrl: 'http://127.0.0.1:4310',
  upstreamToken: daemonToken,
  clientToken,
});

// A fetch-style server entry, as used by Bun and by Hono on Node.js
export default { fetch: proxy.handle };

对于 WebSocket 或其他信件传输,将每个信件转换为 Request 发送 页:1 Response 回来 代理所依赖的三件事:

  • 无 publicOrigin,构造 request.url 使用 Cononic 客户端创建的 URL 请求。 嵌入器负责这个URL. Forwarded 财务报告和审定财务报表 X-Forwarded-* 信头有 不选择上传票源.
  • request.signal 当客户端消失时中止 。 代理机然后取消守护进程请求, 所以 客户端停止等待的工作不会继续运行.
  • 反应体流. 艺术下载可以很大,所以在身体到达时向前.

handle 从不拒绝。 错误作为 JSON 响应返回, 状态为 4xx 或 5xxx, 路由除外 代理服务器不服务, 它得到一个普通 Not found 404号.

通过 TLS 隧道上传服务

设定 publicOrigin 当 TLS 在代理服务器前终止时, 向公共 HTTP( S) 源头发送 https://public.example:8443。使用方案、主机和可选端口,没有证书、路径, 查询或片段。 与CLI,运行 agent-device proxy --port 4310 --public-origin https://public.example:8443. 对于麻风 隧道,先获取其公共名称,然后配置并重新启动代理 。 这个取代了 前一个..X-Forwarded-Proto 行为.

没有固定的源头,节点收听器会使用实际的套接字方案并验证一个 Host 头曰. 支持实际节点 HTTPS 套接字 。 自定义直接守护 HTTP 嵌入到 TLS 后面 终止可以通过 publicOrigin 改为 createDaemonHttpServer。内置守护进程监听 回放 HTTP; 通过配置的代理在 TLS 后面曝光 .

您的节点 HTTP 客户端必须发送一个有效的 Host 每个请求,包括 /health。缺失、重复或格式错误的主机头会收到 HTTP 400,即使使用 publicOrigin 已配置 。 配置原始口袋和HTTP/1.0健康探测器 Host: localhost (或你的电话) 部署的主机和端口).

在自己的交通工具上到达守护进程

默认情况下, 代理服务器使用全局调用守护进程 fetch。通过 upstreamFetch 当守护进程 只能以其他方式达到, 如设备主机打开的通道:

const proxy = createDaemonProxy({
  upstreamBaseUrl: 'http://device-host-17.internal',
  upstreamToken: daemonToken,
  clientToken,
  upstreamFetch: (request) => deviceHostTunnel.send(request),
});

upstreamFetch 收到一个 Request 代表团致 upstreamBaseUrl 并且必须同 守护进程 Response时中止交换 request.signal 流产.

认证每个客户端

一个 clientToken 每个客户共享。 给每个客户自己的证书,通过 authenticate 换句话说 它接收每个客户请求(其JSON机构设在 /rpc返回时 承租人作为,或 null 以401号拒绝:

const proxy = createDaemonProxy({
  upstreamBaseUrl: 'http://127.0.0.1:4310',
  upstreamToken: daemonToken,
  authenticate: async (request) => {
    const account = await accounts.findByApiKey(request.headers.get('authorization'));
    return account ? { tenantId: account.id } : null;
  },
});

代理将所有经认证的请求 发给守护进程 作为租户,无论租户 指定客户,并将其会议与其他租户会议隔离. GET /health 没有 经认证,没有房客。 租户身份证是1-128个字母、数字、点、下划线或 连字符; 任何其他 id 以 500 键失败请求 。 打开 /rpc 代理仅接受 agent_device.command 编辑 agent_device.lease.* 方法(或同名拼写) agent-device.command 财务报告和审定财务报表 agent-device.lease.*),并用401来拒绝其他人.

客户端上传文件时会携带一张票,上面写有要发送的信头的名字. 代理机构建了这张票 从守护进程票 content-type 和客户自己的证书, 所以它从来没有携带 守护神的标志。 默认证明是客户端的 authorization 财务报告和审定财务报表 x-agent-device-token 头. 如果您的客户端使用另一个信头, 如饼干或 API 密钥 信头,还原为 uploadHeaders 因此,上传通过 authenticate 还有:

authenticate: async (request) => {
  const apiKey = request.headers.get('x-api-key');
  if (!apiKey) return null;
  const account = await accounts.findByApiKey(apiKey);
  return account ? { tenantId: account.id, uploadHeaders: { 'x-api-key': apiKey } } : null;
},

选项

选项默认含义
upstreamBaseUrl所需经费守护进程 HTTP 服务器的基址 .
upstreamToken所需经费守护神的认证符.
clientToken无需 authenticate托肯客户端必须发送作为其守护进程认证符.
authenticate无认证每个客户并命名其租户;替换 clientToken。 。 。 .
upstreamFetch全球 fetch向守护进程发送一个请求 .
maxRpcBodyBytes64 MiB,守护进程自己请求的限制大一点 /rpc 尸体得到400个响应.
upstreamTimeoutMs无一个守护进程的请求可能要花很长时间 包括它的身体 没有它,一个请求会持续到客户端等待的时间,客户端的命令超时就会被限制.

maxRpcBodyBytes 限制一个字节 /rpc 躯体。 代理读取整个身体之前 认证客户端,然后解码并解析. 因此,一项未经认证的请求可以 持有多于限制的内存:生字节外加解码字符串和解析请求. 对于 一个面对互联网的代理,设置 maxRpcBodyBytes 低于64 MiB 默认值, 最大 请求您的客户发送.

限制检查后,代理重写了正文:它添加了守护进程代号,并带有 authenticate租户的田地 重写体能比 客户的。 守护进程应用了自己的64 MiB 限制,所以在64 MiB 的幅度内有一个客户机构 通过代理,守护进程拒绝。 客户拒绝超过64个MiB的请求,然后发送, 因此,只有处于这一狭小边缘的一具尸体才会受到影响.

保健和重新启动

GET /health (兼任) /agent-device/health)不需要符号。 它报告代理版本和 instanceId,以及 包括守护进程自身的健康 upstream。一个新的 createDaemonProxy 呼叫得到一个新的 instanceId,因此连接的客户端在发送前注意到重新启动并重新检查连接 更多的命令。 更多命令.

版本与发布记录

@agent-device/proxy 共发布 51 个版本,首次发布于 2026/10/07;过去 12 个月发布了 51 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.21.38latest2026/11/17今天
0.22.0-nightly-0-22.20261116.179nightly-0.222026/11/16今天
0.21.38-nightly.20261113.167nightly2026/11/133 天前
0.21.372026/11/133 天前
0.21.37-nightly.20261111.1612026/11/115 天前
0.21.37-nightly.20261111.1572026/11/115 天前

关于 @agent-device/proxy 的常见问题

@agent-device/proxy 是什么?

在代理设备守护进程前的运输中性认证代理.

如何安装 @agent-device/proxy?

在项目目录运行 npm install @agent-device/proxy,或使用 pnpm add / yarn add / bun add。

@agent-device/proxy 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@agent-device/proxy 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@agent-device/proxy 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.12。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@agent-device/proxy 可以商用吗?

@agent-device/proxy 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@agent-device/proxy 的下载量有多少?

根据 npm 官方下载统计,@agent-device/proxy 在 2026/10/05 – 2026/11/03 这 30 天内被下载 20,367 次,日均约 679 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@agent-device/proxy 还在维护吗?

最新版本 0.21.38 发布于 2026/11/17(今天);至今共发布 51 个版本,其中过去 12 个月发布了 51 个;首次发布于 2026/10/07。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。