@newton-cloud/server

可独立部署的 Node.js 浏览器安全网关。它在服务器上持有 secret、完成上游鉴权，并向浏览器中的 @newton-cloud/sdk 暴露任务 API。

如何选择

| 需求 | 安装包 | | --- | --- | | 在 React 应用中开箱即用地接入完整 Agent | @newton-cloud/react | | 自行组合框架或界面，只使用任务状态与控制能力 | @newton-cloud/sdk | | 只使用受控 React 组件和默认样式 | @newton-cloud/ui | | 在自己的服务器上部署浏览器安全网关 | @newton-cloud/server |

包之间的关系

• npm 运行时依赖：@newton-cloud/react 精确依赖 @newton-cloud/sdk 和 @newton-cloud/ui，安装 React 集成时会自动安装这两个包。
• HTTPS 部署关系：@newton-cloud/sdk 通过 HTTPS 调用 @newton-cloud/server 或兼容的企业网关，再由网关访问 Newton Cloud Open API。
• 独立使用：@newton-cloud/ui 不依赖 SDK，可由应用直接传入 props 和处理交互意图。
• 独立部署：@newton-cloud/server 不会进入浏览器 bundle，也不会随 React 集成自动安装或部署。

运行环境

• Node.js >=16.0.0
• Package entry：从 @newton-cloud/server 导入 createNewtonServer()
• CLI entry：newton-cloud-server
• 健康检查：GET /healthz

安装

使用精确版本安装，不依赖 latest：

npm install --save-exact @newton-cloud/[email protected]

部署项目必须保留 lockfile，以便复核和回滚。

必填环境变量

已安装 CLI 缺少任一必填部署值时会在监听端口前失败：

• NEWTON_APP_KEY：Open Platform app key
• NEWTON_APP_SECRET：Open Platform app secret

可选运行参数：

• NEWTON_CLOUD_API_BASE：Newton Cloud Open API base URL；未配置时使用产品默认网关
• NEWTON_ACCESS_TOKEN：服务端 access token；也可由单次请求安全提供
• NEWTON_SERVER_PORT：监听端口，默认 3001
• PORT：NEWTON_SERVER_PORT 之前使用的后备端口
• NEWTON_SERVER_HOST：监听地址

secret 必须来自服务器环境变量、进程管理器环境文件或 secret store。不得提交 registry token、 app secret 或 access token。

CLI 使用

NEWTON_CLOUD_API_BASE=<cloud-api-base> \
NEWTON_APP_KEY=<app-key> \
NEWTON_APP_SECRET=<app-secret> \
NEWTON_ACCESS_TOKEN=<access-token> \
NEWTON_SERVER_PORT=3001 \
newton-cloud-server

然后验证：

curl -fsS http://127.0.0.1:3001/healthz

Library 使用

import { createNewtonServer } from '@newton-cloud/server';

const server = createNewtonServer({
  cloudApiBase: process.env.NEWTON_CLOUD_API_BASE,
  appKey: process.env.NEWTON_APP_KEY,
  appSecret: process.env.NEWTON_APP_SECRET,
  accessToken: process.env.NEWTON_ACCESS_TOKEN,
  port: Number(process.env.NEWTON_SERVER_PORT || 3001),
});

await server.listen();

License

Apache-2.0。Copyright 2026 Newton Cloud Open Contributors.