# @agent-device/proxy 中文文档

规范地址：https://npmcn.com/package/%40agent-device/proxy/

版本：0\.21\.38
npm 元数据更新时间：2026-11-16T18:15:30.479Z
中文译文更新时间：2026-11-16T18:18:12.243Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agent-device/proxy
原文对照：https://npmcn.com/package/%40agent-device/proxy/?lang=original
项目主页：https://agent-device.dev/
源码仓库：https://github.com/callstack/agent-device

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：134 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12
- 运行依赖：0 个
- 首次发布：2026-10-07T04:54:17.075Z
- 最新版本发布：2026-11-16T18:15:29.886Z
- 近 30 天下载量：20367（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：51（近 12 个月 51 个）

## 中文简介

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

## 安装

```sh
npm install @agent-device/proxy
```

也可以使用：`pnpm add @agent-device/proxy`、`yarn add @agent-device/proxy`、`bun add @agent-device/proxy`

## README

# @ agent-device/ 代理服务器

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

代理服务器 :

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

需要节点js 22.12 或以后.

## 安装

```bash
npm install @agent-device/proxy
```

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

## 为 HTTP 代理服务

```ts
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 主机:

```ts
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` 当守护进程 只能以其他方式达到, 如设备主机打开的通道:

```ts
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号拒绝:

```ts
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` 还有:

```ts
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` | 向守护进程发送一个请求 . |
| `maxRpcBodyBytes` | 64 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 是什么？

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

### 如何安装 @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 和提交记录判断。

