Logo

菜单

发布于 2026-01-06 4 阅读
0

如何使用 ngrok 在本地测试应用程序身份验证

如何使用 ngrok 在本地测试应用程序身份验证

本文最初发表于BigCommerce 开发者博客，日期为 2019 年 1 月 5 日。

本地开发的优势在于可以快速便捷地测试修改，但无法访问网络也有其弊端。在开发阶段，您可能会遇到需要公开访问的 URL 的情况。例如，您可能想向同事或客户展示您的成果，或者需要一个安全且公开的回调 URL 来与 Web 服务交互。您可以将应用上传到 Heroku 等托管平台，但这样每次更新都需要将这些更改推送到托管服务器……这显然不太理想。

幸运的是，我们有 ngrok。ngrok 是一款便捷的工具，它可以为运行在本地主机上的应用程序创建一个安全且可公开访问的隧道 URL。您可以共享此隧道 URL 以便其他人查看您的工作成果，或者您可以创建可公开访问的路由来执行诸如完成 OAuth 握手之类的操作。

在本教程中，我们将构建一个非常简单的用于 BigCommerce 的 Node 应用，并演示如何使用 ngrok 从 BigCommerce 身份验证服务中获取 OAuth 令牌，以及如何将应用安装到您的商店中，所有操作均可在本地完成。本教程将为您提供在本地测试、运行和验证 BigCommerce 应用的全面指南。

ngrok是什么？

Ngrok 是一款免费程序，它可以将运行在本地主机上的进程暴露给公共互联网。启动 ngrok 时，您需要指定本地服务器运行的端口，ngrok 会创建一个安全的隧道 URL，使本地应用程序可以公开访问。访问 ngrok URL，您将看到与访问http://localhost:myport相同的内容。

启动 ngrok 后，您会在终端中看到类似这样的输出：

ngrok 控制面板

注意这两个转发地址了吗？Ngrok 提供了指向本地主机的 URL 的 https 和 http 版本。Ngrok 还提供了一个 Web 界面控制面板，可以显示所有通过隧道传输的 http 流量的详细信息。这在应用程序开发过程中非常有用，尤其是在处理 Webhook 时。

默认情况下，ngrok 每次启动都会生成一个随机子域名。这对于测试来说没问题，但如果你要长期开发一个项目，每次重启 ngrok 后都需要更新项目中的 URL，那就很麻烦了。如果你注册了付费套餐，ngrok 允许你指定自定义子域名，这样每次都会使用相同的 URL。

其实，解释 ngrok 工作原理的最佳方法就是演示给你看。我们下载 ngrok，然后快速创建一个简单的应用程序在本地主机上运行来演示一下。

如何设置 ngrok

准备好开始了吗？你可以使用 npm 安装 ngrok（我推荐的方法），也可以手动安装。

使用 npm 安装

  1. 请确保您的计算机上已安装Node.js。运行以下终端命令以确认 Node 已安装并检查您的版本：
    node -v

  2. 运行此npm install -g ngrok命令以全局安装 ngrok。现在您可以从任何目录运行 ngrok 命令。

手动安装

  1. 请访问https://ngrok.com/download并下载与您的操作系统对应的软件包。

  2. 将文件解压缩到容易访问的位置，例如根文件夹。

  3. 您可以导航到解压缩 ngrok 的文件夹来运行它，或者如果您想从任何位置运行 ngrok，您可以将其移动到 $PATH 中的目录，通常是 /usr/local/bin。

启动 ngrok

  1. 打开终端窗口，并导航到你解压 ngrok 的位置。如果你已经全局安装了 ngrok 或将其移动到了 $PATH 环境变量中，那么你可以从任何目录运行 ngrok。

  2. 运行以下命令启动 ngrok 并创建到本地主机端口 3000 的隧道：
    ngrok http 3000

  3. 按 Ctrl + C 停止 ngrok。

创建 Express 应用

Express是一个用于创建 Node.js 应用框架的框架。它是快速创建应用文件结构的绝佳方式。

  1. 使用以下终端命令安装 express generator 命令行工具：
    npm install express-generator -g

  2. 创建应用。我们指定应用应使用 Handlebars 视图引擎，并创建在名为 myapp 的文件夹中：
    express — view=hbs myapp

  3. 进入 myapp 文件夹：
    cd myapp

  4. 安装依赖项：
    npm install

  5. 使用以下命令启动应用程序：
    npm start

将 ngrok 隧道连接到本地主机

是时候把所有部件组装起来了。我们已经安装了 ngrok，并使用 Express 创建了一个框架应用。现在，我们将启动应用和 ngrok，看看隧道 URL 是否正常工作。

  1. 打开终端窗口并导航到你的 myapp 目录。运行npm start命令启动应用。默认情况下，Express 生成器应用会在 localhost:3000 启动服务器。如果你想更改端口，可以在应用的 bin/www 文件第 15 行找到设置，但目前我们暂且使用 3000 端口。

  2. 打开浏览器窗口并访问http://localhost:3000。您应该会看到 Express 应用的主页：

express localhost

  1. 打开一个新的终端窗口（保持第一个终端窗口运行），并在端口 3000 上启动 ngrok：
    ngrok http 3000

  2. 从终端复制 https 转发 URL，并将其粘贴到新的浏览器标签页中。您应该会看到与本地主机 URL 上相同的 Express 应用主页：

快捷 ngrok

太棒了！虽然现在看起来可能没什么特别的，但我们已经展示了 ngrok 的一个强大功能。你可以把 ngrok 转发 URL 发给朋友，他们就能看到同样的 Express 应用首页（前提是你的终端里运行着 ngrok）。这很酷，但接下来我们将展示如何使用 ngrok 做更多的事情。我们将创建一个转发 URL，允许我们在应用内创建公开访问的路由，以便完成在 BigCommerce 商店安装应用所需的 OAuth 流程。

BigCommerce 应用身份验证

在继续之前，了解一些 BigCommerce 应用身份验证的背景知识会有所帮助，以便说明为什么需要 ngrok 来安装仍然托管在本地的应用。

BigCommerce 应用在安装过程中使用 OAuth 以编程方式生成针对特定店铺的 API 令牌。应用收到店铺的 API 令牌后，即可将其保存到数据库中，以便在调用 API 时重复使用。

获取 OAuth 令牌的过程需要在 BigCommerce 和应用托管商之间进行一些交互。首先，应用需要向 BigCommerce 请求一个临时授权码。BigCommerce 在发送临时令牌时，还会同时发送一些其他信息：API 令牌的授权范围以及安装该应用的商店的哈希值（或标识符）。

接下来，该应用会返回一个包含一系列声明的响应，以告知 BigCommerce 身份验证服务可以返回真正的 OAuth 令牌。这些声明包括之前从 BigCommerce 收到的临时身份验证令牌、商店哈希值、权限范围以及在应用注册期间提供的客户端 ID 和客户端密钥。如果一切正常，BigCommerce 身份验证服务会返回一个永久的 OAuth 令牌，并且应用会在商店控制面板中显示为“已安装”。

所有这些网络请求都需要通过公开可访问的 URL 进行。在测试应用程序安装和身份验证时，我们需要将应用程序托管在服务器或 Heroku 等平台上，或者使用 ngrok 等工具从本地主机创建隧道 URL。

注册应用

要在 BigCommerce 商店中安装应用程序，您需要一个商店，这并不奇怪。请访问https://www.bigcommerce.com/注册免费试用版。

然后，点击右上角的“创建账户”，在https://developer.bigcommerce.com/注册一个开发者工具账户。请务必使用您注册试用商店时使用的同一个邮箱地址。使用同一个邮箱地址会将您的试用商店账户和开发者工具账户关联起来，这样您在开发者工具中创建的任何应用都可以在您商店控制面板的“草稿应用”区域安装。

开发者工具是创建 BigCommerce 应用的工作区。如果您是应用市场的供应商，您需要在这里注册新应用并管理应用列表详情。现在，我们只需完成注册新应用并获取客户端 ID 和客户端密钥的最简步骤即可。

  1. 登录开发者工具，然后点击橙色的“创建应用”按钮。

  2. 请输入您的应用名称。名称可以随意，例如“我的测试应用”、“Node 应用”等等。

  3. 点击“创建应用”。

  4. 点击您创建的应用上的“编辑应用”图标。

  5. 在步骤 1 中，您可以跳过填写个人资料表单。此表单仅用于收集 BigCommerce 所需的开发者信息，以便他们将应用提交到应用市场。虽然并非必须，但我建议您在底部的应用摘要区域上传一张图片。该图片将显示在控制面板中您的应用草稿卡片上。再次强调，这不是必需的，但上传图片确实能让应用看起来更美观。

  6. 跳过步骤 2：应用详情，直接进入步骤 3。只有想要将应用提交到应用商店的开发者才需要填写应用详情。

  7. 在步骤 3 中，填写回调 URL 字段，并将 example.com 替换为您从 ngrok 获取的 https 转发 URL。例如：
    身份验证：https: //4022ffe4.ngrok.io/auth
    ； 加载：https://4022ffe4.ngrok.io/load
    ；卸载：https://4022ffe4.ngrok.io/uninstall

  8. 单击“下一步”，直到到达步骤 6，然后单击“更新并关闭”。

在 Express 中创建路线

在应用注册过程中，我们定义了三个回调 URL：Auth（授权）、Load（加载）和 Uninstall（卸载）。这些 URL 会告诉 BigCommerce：当用户安装、加载或卸载我的应用时，应该将相应的 HTTP 请求发送到这些 URL。接下来，我们将在 Express 应用中创建这些路由，以处理来自 BigCommerce 的授权、加载和卸载请求。

路由监听对特定路径的 HTTP 请求（GET 或 POST），然后在 HTTP 请求发生时执行某些操作，例如运行函数或调用响应方法。

创建身份验证路由：

  1. 在您的应用程序目录下运行 `npm install node-bigcommerce` 命令，即可安装BigCommerce Node 客户端。该软件包由Conversio的开发人员编写，用于对 BigCommerce API 进行身份验证和调用。

  2. 在 routes 目录中创建一个名为 auth.js 的新文件。

  3. 将以下内容粘贴到文件内容中：

const express = require('express'),
router = express.Router(),
BigCommerce = require('node-bigcommerce');

const bigCommerce = new BigCommerce({
clientId: 'your Client Id from app registration',
secret: 'your Client Secret from app registration',
callback: 'https://your-ngrokURL/auth',
responseType: 'json'
});

router.get('/', (req, res, next) => {
bigCommerce.authorize(req.query)
.then(data => console.log(data))
.then(data => res.render('auth', { title: 'Authorized!' })
.catch(err));
});
module.exports = router;

在这里，我们在文件顶部引入了 Express 路由器和 BigCommerce Node Client，并实例化了一个新的 BigCommerce 配置对象。

请查看 BigCommerce 配置对象下方的函数。通过该函数router.get(‘/’, (req, res, next)，我们告诉路由器，当收到发送到此路径（此路径为 /auth，因为我们位于 routes/auth.js 文件中）的 GET 请求时，调用 Node Client 依赖项中的 authorize 函数。

授权函数会从 BigCommerce 返回一个数据对象，其中包含商店哈希值、用户电子邮件地址（用于识别用户）以及与该商店关联的 OAuth 令牌。如果我们要进一步开发此应用程序，我们会希望将这些信息保存到数据库中以便重复使用。

返回 OAuth 令牌后，我们调用 res.render 来渲染一个名为“auth”的视图，该视图会传入文本“已授权！”

  1. 请替换您的客户端 ID、客户端密钥和 ngrok 隧道 URL 的值。

  2. 在 Views 文件夹中创建一个名为 auth.hbs 的新文件，创建“auth”视图。

  3. 将以下内容粘贴到文件内容中：
    <h1>{{title}}</h1>

创建加载路由：

  1. 在 Routes 文件夹中创建一个名为 load.js 的新文件。

  2. 将以下内容粘贴到文件内容中：

const express = require('express'),
router = express.Router(),
BigCommerce = require('node-bigcommerce');
const bigCommerce = new BigCommerce({
secret: 'your Client Secret',
responseType: 'json'
});

router.get('/', (req, res, next) => {
try {
const data = bigCommerce.verify(req.query['signed_payload']);
console.log(data);
res.render('welcome', { title: 'Welcome!'});
} catch (err) {
next(err);
}
});

module.exports = router;

  1. 将“secret”的值替换为您的客户端密钥。与我们创建的 /auth 路由类似，我们指定了一个回调函数，该函数将在向 /load 路由发送 GET 请求后执行。我们调用了verify函数，该函数会验证请求是否来自 BigCommerce，并识别商店和用户。验证成功后，我们会将数据对象记录到控制台，并渲染名为“welcome”的视图。

  2. 在 Views 目录中创建一个名为 welcome.hbs 的新文件，即可创建“欢迎”视图。

  3. 将以下内容粘贴到文件内容中：
    <h1>{{title}}</h1>

创建卸载路径：

  1. 在你的 Routes 目录中创建一个名为 uninstall.js 的新文件。

  2. 将以下内容粘贴到文件内容中：

const express = require('express'),
router = express.Router(),
BigCommerce = require('node-bigcommerce');
const bigCommerce = new BigCommerce({
secret: 'Your Client Secret',
responseType: 'json'
});

router.get('/', (req, next) => {
try {
const data = bigCommerce.verify(req.query['signed_payload']);
console.log(data);
} catch (err) {
next(err);
}
});

module.exports = router;
  1. 将“secret”的值替换为您的客户端密钥。在 /uninstall 回调函数中，我们使用 verify 函数解码 BigCommerce 发送的签名有效负载，并记录用于识别卸载应用的用户的有效负载。在这种情况下，我们没有渲染视图，因为任何发送回 BigCommerce 的 HTML 都不会被 BigCommerce 渲染。

在 App.js 中加载路由模块

在使用我们创建的路由模块之前，我们需要将路由模块挂载到主应用程序文件中的某个路径上。

  1. 在 app.js 文件的顶部附近添加以下代码：
var auth = require(‘./routes/auth’);
var load = require(‘./routes/load’);
var uninstall = require(‘./routes/uninstall’);
  1. 找到 app.js 文件中间附近的以下几行代码：
app.use(‘/’, index);
app.use(‘/users’, users);

在它们下面添加：

app.use(‘/auth’, auth);
app.use(‘/load’, load);
app.use(‘/uninstall’, uninstall);

安装应用

现在我们已经将应用程序连接到了相应的路由路径，是时候在您的商店中安装该应用程序了。

  1. npm start在您的 myapp 目录中运行命令来启动 Express 应用。

  2. 打开第二个终端窗口，并在端口 3000 上启动 ngrok：
    ngrok http 3000

请务必将开发者工具中的 ngrok URL 更新为与当前会话中的 ngrok URL 匹配。

  1. 登录您的 BigCommerce 商店，然后导航至“应用”>“我的应用”>“我的草稿应用”选项卡。

  2. 点击应用卡片上的“了解更多”，然后点击“安装”。您应该会看到应用的“已授权！”消息。“已授权！”视图表明我们已成功从 BigCommerce 收到 OAuth 令牌。

  3. 返回控制面板中的“我的应用”部分，测试“加载”路径。应用安装完成后，您会看到两个新按钮：“加载”和“卸载”。点击“加载”按钮即可显示欢迎界面。

  4. 现在，点击“卸载”按钮。该应用将从“我的应用”部分移除。检查终端控制台，查看是否有已记录的身份验证、加载和卸载数据对象。

常问问题

我已经安装了ngrok。为什么我尝试启动它时会收到“命令未找到”的错误提示？

您可能没有从 ngrok 可执行文件所在的当前工作目录运行它。您可以将该文件移动到 $PATH 环境变量指定的目录，或者导航到包含 ngrok .exe 文件的目录。例如，如果您将 ngrok 解压缩到根目录，则可以使用以下命令运行它：

cd ~

./ngrok http 3000

如何使用ngrok测试webhook？

Webhook 允许您监听第三方平台上发生的事件。例如，您的应用可能希望在 BigCommerce 产品库存发生变化时收到通知，以便您的应用可以采取相应的操作。

注册 Webhook 时，您可以将 ngrok 隧道 URL 提供为目标 URL。Webhook 事件发生时，您将通过隧道接收 Webhook 数据对象。您可以在 ngrok Web 界面控制面板中显示数据对象的详细信息，并在您的应用程序中处理该事件。

有关使用 ngrok 测试 webhook 的更多详细信息，请参阅这篇关于注册和测试 webhook 的教程。

为什么我访问我的 ngrok 隧道 URL 时会收到 502 Bad Gateway 错误？

Ngrok 需要本地主机上运行一个 Web 服务器。如果没有服务器运行，你会看到 502 错误，并附带一条消息，提示 ngrok 无法完成隧道连接。默认情况下，Express 生成器应用程序会在 3000 端口启动一个服务器，因此你只需确保在向 ngrok URL 发送请求之前启动你的应用程序即可。

概括

在本教程中，我们安装了 ngrok，并使用它将我们在本地托管的应用程序中注册的路由重定向到可公开访问的回调 URL。做得好！现在，您已经朝着在本地构建和测试应用程序的目标迈出了重要一步——在开发阶段，无需将更改部署到应用程序主机。

以此为起点，逐步构建更复杂的应用程序：将 OAuth 令牌保存到数据库，并使用它来调用 BigCommerce API，或者创建视图模板，为应用程序用户提供用户界面。正在寻找 Python、PHP 或 Ruby 的 Hello World 应用程序示例？请访问 BigCommerce工具和资源页面，查看其他语言的示例应用程序和 API 客户端。

请告诉我们您正在进行的项目，提出您的问题，并向我们发送您的反馈！请在下方留言或在推特上关注我们@BigCommerceDevs。

文章来源：https://dev.to/karen_pwhite/how-to-test-app-authentication-locally-with-ngrok-4p9h
使用 CSS 变量实现主题化 什么...
深入探索 Angular 中的 R...