LabEx
免费加入

使用服务绑定连接 Workers

CloudflareBeginner
立即练习

简介

支持 API 需要使用另一个 Worker 所拥有的目录。你将把公共 API 连接到提供的内部目录，复现并修复缺失的绑定，然后部署两个服务，同时确保目录没有公共端点。

使用你自己的 Cloudflare 学习账号，以及之前实验中学习的授权、配置和部署知识。这个独立 VM 从 /home/labex/project/service-binding 开始，环境中已安装 Node.js 22.22.0、项目本地 Wrangler 4.131.1 和一个合成目录测试装置。不会复用之前的 VM 或资源。本实验不需要购买域名、数据库或付费升级；少量请求会计入账号的正常用量。

保持一个终端窗口打开。你将使用两个本地进程，创建两个名称唯一且可临时使用的云端 Worker，验证它们的连接，删除调用方和依赖项，然后在结束 VM 前退出登录。

复现缺失的服务绑定

在本步骤中，你将创建一个公共 API，但故意不配置它的目录依赖项。另一个提供的 Worker 拥有两个合成目录条目。目前，两个进程都只在此 VM 中运行。

cd /home/labex/project/service-binding

node --version

npx wrangler --version

cat catalog/index.js

预期会看到 Node v22.22.0 和 Wrangler 4.131.1。初始化过程已经安装了项目本地依赖；如果在其他机器上操作，请使用此项目的 lockfile 执行 npm ci。测试装置会返回公共服务标签、两个条目，以及可选的合成 probe 查询值，用于跟踪请求。它不会存储任何数据。

生成一个临时使用的基础名称，并在普通配置中记录两个资源的身份。保持此终端打开，以便 WORKER_NAME 继续可用。目录 Worker 的 main 路径相对于它自己的配置目录。

WORKER_NAME="labex-binding-$(openssl rand -hex 6)"

cat > wrangler.jsonc <<CONFIG
{
  "name": "$WORKER_NAME",
  "main": "src/index.js",
  "compatibility_date": "2026-09-14",
  "workers_dev": true,
  "preview_urls": false,
  "services": []
}
CONFIG

cat > catalog/wrangler.jsonc <<CONFIG
{
  "name": "$WORKER_NAME-catalog",
  "main": "index.js",
  "compatibility_date": "2026-09-14",
  "workers_dev": false,
  "preview_urls": false,
  "routes": [],
  "vars": {"SERVICE_ID": "$WORKER_NAME-catalog"}
}
CONFIG

目录 Worker 同时禁用了 workers.dev 和预览 URL，也没有配置路由。本地开发仍会开放一个回环端口用于测试；这不会创建公共云端点。公共 API 的空 services 列表就是你需要诊断的缺陷。

编写公共处理程序。/health 独立工作。/catalog 会先检查绑定是否存在，然后才发起内部调用。catalog.internal 是一个完全限定的占位 URL，不是需要注册的 DNS 名称：env.CATALOG 会选择目标。我们只构造一个包含指定查询值的新 GET 请求，不转发客户端任意的请求头。

cat > src/index.js <<'JS'
export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    if (url.pathname === '/health' && request.method === 'GET') {
      return Response.json({status: 'ok'});
    }
    if (url.pathname !== '/catalog') return Response.json({error: 'not_found'}, {status: 404});
    if (request.method !== 'GET') {
      return Response.json({error: 'method_not_allowed'}, {status: 405, headers: {Allow: 'GET'}});
    }
    if (!env.CATALOG) return Response.json({error: 'catalog_binding_missing'}, {status: 503});
    // This hostname completes the Request URL. The binding selects the target Worker.
    const target = new URL('https://catalog.internal/catalog');
    target.searchParams.set('probe', url.searchParams.get('probe') || '');
    try {
      return await env.CATALOG.fetch(new Request(target, {method: 'GET'}));
    } catch {
      return Response.json({error: 'catalog_unavailable'}, {status: 502});
    }
  }
};
JS

将提供的目录 Worker 和 API 分别作为后台任务启动，并为它们使用不同的 HTTP 端口和检查器端口。日志会显示启动过程；& 会立即返回 shell 提示符。

npx wrangler dev --config catalog/wrangler.jsonc --ip 127.0.0.1 --port 8081 --inspector-port 9230 > catalog.log 2>&1 &

npx wrangler dev --config wrangler.jsonc --ip 127.0.0.1 --port 8080 --inspector-port 9231 > api.log 2>&1 &

cat catalog.log

cat api.log

等待两个日志都显示已准备就绪；必要时重复执行 cat，然后检查响应：

curl -i http://127.0.0.1:8081/catalog

curl -i http://127.0.0.1:8080/health

curl -i http://127.0.0.1:8080/catalog

目录 Worker 应返回 200 和两个条目；健康检查应返回 200 {"status":"ok"}；API 的目录路由应返回 503 {"error":"catalog_binding_missing"}。依赖项正在运行，但调用方没有访问它所需的配置能力。在缺失绑定的状态仍然存在时，完成验证。

声明并测试内部连接

在本步骤中，你将修复配置，不修改 API 代码。先检查实际的后台任务，只停止 API 进程；以下示例假设它是任务 2。

jobs

kill %2

cat > wrangler.jsonc <<CONFIG
{
  "name": "$WORKER_NAME",
  "main": "src/index.js",
  "compatibility_date": "2026-09-14",
  "workers_dev": true,
  "preview_urls": false,
  "services": [{"binding": "CATALOG", "service": "$WORKER_NAME-catalog"}]
}
CONFIG

binding 是可通过 env.CATALOG 使用的属性名称。service 是目标 Worker 配置中的准确名称。如果其中任一部分拼写不匹配，问题类型就不同：缺少属性会触发明确的 503；目标不可用时，可能触发 502 或启动/部署错误。不要将绑定调用替换为公共 fetch URL。

npx wrangler dev --config wrangler.jsonc --ip 127.0.0.1 --port 8080 --inspector-port 9231 > api.log 2>&1 &

cat api.log

等待 API 准备就绪，然后检查绑定表。Wrangler 会按名称发现正在运行的目录 Worker，并报告连接状态。如果显示未连接，请确认目录进程正在运行，并检查两个配置中的名称是否一致，然后重试。

curl -i "http://127.0.0.1:8080/catalog?probe=local-check"

curl -i -X POST http://127.0.0.1:8080/catalog

curl -i http://127.0.0.1:8080/missing

第一个响应应为 200，并包含目录的准确服务标签、两个条目以及 probe: local-check。方法检查应返回 405，未知路由应返回 404。在两个服务器都运行时完成验证；这会通过公共 API 发送一个新的探测请求，并检查完整契约。

绑定属于配置环境。如果之后使用 --env preview，请在 env.preview 下声明完整的 services 数组，并将它指向预期的已部署目标；服务绑定不会从顶层配置继承。本实验使用一个未命名环境，且从不传递 --env。请参阅 Wrangler 环境 和 HTTP 服务绑定接口。

部署内部服务和公共 API

在本步骤中，你将把相同的连接部署到自己的学习账号。先执行 jobs，然后停止其中显示的两个实际本地任务；以下示例假设它们是任务 1 和任务 2。

jobs

kill %1 %2

npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_tail:read

在已登录的浏览器中打开终端显示的设备链接，输入当前验证码，查看 Wrangler 请求的权限和 Background Access，然后按照之前的说明只选择你的学习账号。等待终端完成操作。

npx wrangler whoami --json

确认输出中的 loggedIn: true，以及实际的账号名称和 ID，即使列表中只有一个账号也要确认。将下面两个命令中的 YOUR_ACCOUNT_ID 替换为同一个 ID；保留原先生成的名称和绑定。

cat > catalog/wrangler.jsonc <<CONFIG
{
  "name": "$WORKER_NAME-catalog",
  "main": "index.js",
  "compatibility_date": "2026-09-14",
  "account_id": "YOUR_ACCOUNT_ID",
  "workers_dev": false,
  "preview_urls": false,
  "routes": [],
  "vars": {"SERVICE_ID": "$WORKER_NAME-catalog"}
}
CONFIG

cat > wrangler.jsonc <<CONFIG
{
  "name": "$WORKER_NAME",
  "main": "src/index.js",
  "compatibility_date": "2026-09-14",
  "account_id": "YOUR_ACCOUNT_ID",
  "workers_dev": true,
  "preview_urls": false,
  "services": [{"binding": "CATALOG", "service": "$WORKER_NAME-catalog"}]
}
CONFIG

先部署目标 Worker，确保公共 Worker 声明的依赖项已经存在。这是两次独立部署，而不是一次原子发布。

npx wrangler deploy --config catalog/wrangler.jsonc

npx wrangler deploy --config wrangler.jsonc

目录 Worker 不应有公共路由。API 的输出会显示其 workers.dev URL 和 CATALOG 绑定。将准确的 API URL 复制到下面的变量中；使用账号现有的 workers.dev 子域名。首次使用账号时，可以按照 Wrangler 显示的可用子域名提示操作，但不要更改已有子域名。

API_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"

curl -i "$API_URL/health"

curl -i "$API_URL/catalog?probe=remote-check"

预期健康检查返回 200，目录结果中包含 probe: remote-check。首次部署或主机名传播可能需要短暂等待后重试；如果持续返回 503 或 502，请检查绑定配置和目标部署状态。

在 Dashboard 中打开同一个学习账号，进入 Compute → Workers & Pages，找到这两个准确名称。打开公共 API 的 Bindings 选项卡。图示应显示 CATALOG 绑定；在下方表格中，比较 Name（CATALOG）和 Value（与之匹配的 -catalog Worker）。绑定名称会在处理程序中成为 env.CATALOG，而绑定值用于标识已部署的依赖项。

公共 API 使用 CATALOG 服务绑定，并指向匹配的内部目录 Worker

点击表格中的目录 Worker 链接，然后选择其 Domains 选项卡。确认顶部面包屑导航现在以 -catalog 结尾。在 Worker URL 下，Production 和 Preview 开关都应处于关闭状态。在 Custom Domains and Routes 下不应有任何条目，如下图所示。

内部目录 Worker 已禁用生产和预览 URL，且没有自定义域名或路由

这里显示的名称只是示例；请使用你生成的后缀和账号子域名。关闭的开关表示显示的地址不是已启用的公共入口。上面的正常 API 请求通过服务绑定访问此 Worker。保持此检查为只读操作：不要启用公共端点、添加路由，或复制绑定来实现内部调用。完成验证：它会独立检查账号所有权、已部署的服务绑定、端点设置，以及携带新探测值的远程响应。禁用这些端点不会阻止获得授权的账号操作员绑定到该服务或修改该服务；这也不是用户登录系统。

在依赖项之前删除调用方

在本步骤中，你将趁授权仍然有效，删除两个临时使用的云端 Worker。配置文件就是你的资源清单。删除前，确认其中生成的名称和账号 ID。

cat wrangler.jsonc

cat catalog/wrangler.jsonc

先删除公共调用方，再删除内部目录 Worker。这样可以避免已部署的调用方继续指向已删除的服务。在每个提示处，检查准确的实验名称，然后按一次 y 键。

npx wrangler delete --config wrangler.jsonc

npx wrangler delete --config catalog/wrangler.jsonc

删除脚本后，Wrangler 4.131.1 可能会报告旧版 Workers Sites KV 身份验证错误。不要扩大权限，也不要把这条诊断信息当作删除成功的证明。刷新 Workers & Pages 并完成验证：成功的授权资源清单应显示这两个准确名称都不存在。网络或身份验证失败无法得出结论。保留其他 Worker、账号及其现有子域名。

断开实验 VM 的连接

在本步骤中，确认两个云端资源都已删除后，移除 VM 的授权。

npx wrangler logout

npx wrangler whoami --json

预期会明确显示 "loggedIn": false。未认证的状态命令可能以非零状态退出；重要证据是其中的结构化结果。完成验证后结束 VM。Dashboard 中的浏览器登录是独立的，可以保持登录状态以便进行其他实验。结束 VM 不能替代云端删除或退出登录。

总结

你诊断了一个正在运行、但从调用方绑定中缺失的依赖项，声明了它的准确服务名称，并通过 env.CATALOG.fetch() 发送请求。本地和已部署的探测请求都返回了目录的身份信息和数据。你检查了已部署的连接，保持内部服务的公共端点处于禁用状态，然后先删除调用方，再删除依赖项，最后断开了 VM 的连接。

服务绑定明确声明了 Worker 之间的内部连接。命名环境需要单独声明绑定；本地连接正常本身并不能证明远程所有权或端点配置正确。

相关 Cloudflare 课程
Cloudflare Workers 入门

Cloudflare Workers 入门

cloudflareserverlessjavascript