开发隧道命令行参考
开发隧道提供了用于创建和管理开发隧道的命令行接口（CLI）工具。 本文介绍各种 devtunnel CLI 命令的语法和参数。
重要
此功能目前处于公开预览状态。 此预览版在提供时没有附带服务级别协议，不建议将其用于生产工作负荷。 某些功能可能不受支持或者受限。
注意
devtunnel CLI 命令以预览版提供。 将来的版本中，命令名称和选项可能会更改。
全局选项
-v, --verbose：启用详细输出。-?, -h, --help：显示帮助和使用情况信息。
管理用户凭据
开发隧道服务需要登录才能授权管理和访问开发隧道。 默认情况下，只有创建开发隧道的用户才能访问开发隧道，但该用户可能会向其他人授予访问权限。
登录后，登录令牌将缓存在系统安全密钥链中，并在过期前几天有效。 注销 CLI 会清除此缓存的令牌，但不会清除任何浏览器 Cookie。 如果浏览器用于通过开发隧道进行身份验证，则可能包括开发隧道访问令牌。
| 命令 | 说明 |
|---|---|
devtunnel user login |
使用 Microsoft 或 GitHub 帐户登录。 |
devtunnel user logout |
清除缓存的令牌 |
devtunnel user show |
显示当前登录状态 |
提示
devtunnel login 以及 devtunnel logout 用于登录和注销的速记命令。
下面是有关使用这些命令的一些示例：
| 示例 | 说明 |
|---|---|
devtunnel user login |
使用 Microsoft 组织（Microsoft Entra ID）或个人帐户登录 |
devtunnel user login -g |
使用 GitHub 帐户登录 |
devtunnel user login -d |
如果无法通过本地交互式浏览器登录，请使用设备代码登录的 GitHub 帐户登录 |
devtunnel user login -g -d |
如果无法通过本地交互式浏览器登录，请使用设备代码登录的 GitHub 帐户登录 |
托管开发隧道
devtunnel host 是用于托管开发隧道的主命令。 应在运行要通过开发隧道访问的服务器的主机系统上运行该命令。
| 命令 | 说明 |
|---|---|
devtunnel host |
托管开发隧道。 如果未指定开发隧道 ID，则会创建一个新的 临时 开发隧道，该隧道在连接关闭后将被删除。 |
下面是有关使用此命令的一些示例：
| 示例 | 说明 |
|---|---|
devtunnel host -p 3000 |
为在主机系统上侦听端口 3000 的服务器托管临时开发隧道。 |
devtunnel host -p 3000 --allow-anonymous |
托管临时开发隧道并启用匿名客户端访问。 |
devtunnel host -p 3000 5000 |
为侦听端口 3000 和 5000 的本地服务器托管临时开发隧道。 |
devtunnel host -p 8443 --protocol https |
为使用 HTTPS 协议的端口 8443 上的服务器托管临时开发隧道。 |
devtunnel host -p 8000 --expiration 2d |
托管具有自定义过期时间的临时开发隧道。 最小值为 1 小时（1 小时），最大值为 30 天（30d）。 |
devtunnel host TUNNELID |
托管以前已配置的现有开发隧道。 |
警告
允许匿名访问开发隧道意味着 Internet 上的任何人都可以连接到本地服务器（如果他们可以猜测开发隧道 ID）。
按 Control-C 停止开发隧道主机进程，并通过开发隧道终止任何客户端连接。 如果未提供现有开发隧道，进程自动创建的开发隧道将在进程退出时被删除。
连接开发隧道
使用 Web 转发 UI：
该 devtunnel host 命令显示类似于以下内容的输出：
Hosting port 3000 at https://l3rs99qw-3000.usw2.devtunnels.ms/
显示的 https: URI 对于开发隧道端口是唯一的：第一个组件是包含给定开发隧道 ID 和端口号的子域。
如果托管端口连接到 Web 服务器，则可以从任何位置直接在浏览器中打开该 URI。 如果访问开发隧道需要授权，则对 URI 的初始请求将重定向到登录页，并在用户获得授权后返回到站点。
如果托管端口连接到 Web 服务，则该 URI 可由 Web 服务客户端应用程序用作基 URI。 但是，如果开发隧道不允许匿名访问，则 Web 服务客户端通常不知道如何进行身份验证。 如果 Web 服务可以安全地公开，请考虑允许匿名访问。 否则，Web 服务客户端可能会添加具有开发隧道访问令牌的请求标头来授权连接。
使用 CLI：
CLI 可用于将客户端端口上的端口转发到开发隧道端口，而不是让客户端浏览器或应用程序直接连接到开发隧道中继 URI。 如果开发隧道不允许匿名访问，客户端可能还需要登录。
devtunnel connect TUNNELID
- 替换为
TUNNELID主机上使用的同一开发隧道 ID。
成功的客户端输出类似于以下内容：
Connected to tunnel: l3rs99qw
SSH: Forwarding from 127.0.0.1:3000 to host port 3000.
SSH: Forwarding from [::1]:3000 to host port 3000.
现在，在客户端上可以使用 localhost:3000 IPv4 或 IPv6 在主机上共享的服务器 3000。 （“SSH”前缀是因为开发隧道服务基于用于端口转发的标准 SSH 协议生成。如果托管端口连接到 Web 服务器， http://localhost:3000/ 则可以在浏览器中打开。 在这种情况下，无需进一步授权，因为客户端的 CLI 登录令牌用于在必要时授权连接。
高级：管理开发隧道
无需托管开发隧道即可创建开发隧道。 这对于高级开发隧道配置和管理非常有用，例如：
- 列出所有拥有开发隧道
- 添加和删除开发隧道的端口
- 管理开发隧道访问控制
- 将元数据添加到开发隧道，例如说明和标记
| 命令 | 说明 |
|---|---|
devtunnel create |
创建持久性开发隧道 |
devtunnel list |
列出开发隧道 |
devtunnel show |
显示开发隧道详细信息 |
devtunnel update |
更新开发隧道属性 |
devtunnel delete |
删除开发隧道 |
devtunnel delete-all |
删除所有开发隧道 |
下面是有关使用这些命令的一些示例：
| 示例 | 说明 |
|---|---|
devtunnel create -a |
创建允许匿名访问的持久性开发隧道。 |
devtunnel create -d 'my tunnel description' |
创建具有不可搜索说明的持久开发隧道。 |
devtunnel create --expiration 4h |
创建具有自定义过期时间的持久开发隧道。 最小值为 1 小时（1 小时），最大值为 30 天（30d）。 |
devtunnel create myTunnelID |
创建具有自定义隧道 ID 的持久开发隧道。 |
devtunnel create --tags my-web-app v1 |
创建持久开发隧道并应用可搜索标记。 |
devtunnel list --tags my-web-app |
列出具有任何指定标记的开发隧道。 |
devtunnel list --all-tags my-web-app v1 |
列出具有所有指定标记的开发隧道。 |
devtunnel show |
显示上次使用的开发隧道的详细信息。 |
devtunnel show TUNNELID |
显示开发隧道的详细信息。 |
devtunnel update TUNNELID -d 'my new tunnel description' |
更新开发隧道的说明。 |
devtunnel update TUNNELID --remove-tags |
从开发隧道中删除所有标记。 |
devtunnel update TUNNELID --expiration 10d |
使用新的自定义过期时间更新开发隧道。 最小值为 1 小时（1 小时），最大值为 30 天（30d）。 |
devtunnel delete TUNNELID |
删除开发隧道。 |
devtunnel delete-all |
删除所有开发隧道。 |
提示
大多数 CLI 命令隐式地对上次使用的开发隧道进行操作，但如有必要，可以选择指定开发隧道 ID。
高级：管理开发隧道端口
最初使用 devtunnel create 命令创建的开发隧道没有端口。 使用 devtunnel port 命令在托管之前添加端口：
| 命令 | 说明 |
|---|---|
devtunnel port create |
创建开发隧道端口 |
devtunnel port list |
列出开发隧道端口 |
devtunnel port show |
显示开发隧道端口详细信息 |
devtunnel port update |
更新开发隧道端口属性 |
devtunnel port delete |
删除开发隧道端口 |
| 示例 | 说明 |
|---|---|
devtunnel port create -p 3000 --protocol http |
添加具有指定协议的端口 |
devtunnel port list TUNNELID |
列出当前端口 |
devtunnel port show TUNNELID -p 3000 |
显示端口 3000 的详细信息 |
devtunnel port update -p 3000 --description 'frontend port' |
更新开发隧道端口说明 |
devtunnel port delete -p 3000 |
删除端口 |
创建端口时，如果自动检测无法正常工作，则可以选择指定协议。 当前选项为“http”、“https”或“auto”（默认值）。 如果托管端口为 HTTPS，则建议将端口协议设置为“https”;否则，“auto”可能很好。
使用上述命令配置开发隧道后，开始托管它：
devtunnel host
高级：管理开发隧道访问
使用以下命令，可以颁发开发隧道访问令牌，以提供对开发隧道的其他客户端访问权限，而无需允许匿名访问。 访问控制项命令允许你在开发隧道和开发隧道端口上配置访问控制。
| 命令 | 说明 |
|---|---|
devtunnel token |
颁发开发隧道访问令牌 |
devtunnel access create |
创建访问控制项 |
devtunnel access list |
列出访问控制条目 |
devtunnel access delete |
删除访问控制项 |
devtunnel access reset |
将访问控制条目重置为默认值 |
下面是有关使用这些命令的一些示例：
| 示例 | 说明 |
|---|---|
devtunnel token TUNNELID --scopes connect |
获取可共享的开发隧道的“连接”访问令牌，以便暂时访问开发隧道。 |
devtunnel access create TUNNELID --anonymous |
在开发隧道上启用匿名客户端访问。 |
devtunnel access create TUNNELID --anonymous --expiration 4h |
使用自定义访问控制过期时间在开发隧道上启用匿名客户端访问。 最小值为 1 小时（1 小时），最大值为 30 天（30d）。 |
devtunnel access create TUNNELID --port 3000 --anonymous |
在端口 3000 上启用匿名客户端访问。 |
devtunnel access create TUNNELID --tenant |
在开发隧道上启用当前的 Microsoft Entra 租户访问。 |
devtunnel access create TUNNELID --org ORG |
在开发隧道上按名称启用 GitHub 组织访问。 |
提示
GitHub 组织访问权限需要 将 Dev Tunnels GitHub 应用安装到组织。
补充命令
如果需要显式设置或取消设置上次使用开发隧道的此本地缓存，可以使用这些命令。
| 命令 | 说明 |
|---|---|
devtunnel set |
设置默认开发隧道 |
devtunnel unset |
清除默认开发隧道 |
诊断命令
| 命令 | 说明 |
|---|---|
devtunnel clusters |
按位置列出可用的服务群集 |
devtunnel echo |
在本地端口上运行诊断回显服务器 |
devtunnel ping |
将诊断消息发送到远程回显服务器 |
| 示例 | 说明 |
|---|---|
devtunnel clusters --ping |
列出按度量延迟排序的可用服务群集。 |
devtunnel echo http --port 8080 --interface 127.0.0.1 |
在端口 8080 上启动本地 http 诊断服务器。 |
疑难解答
若要排查 CLI 问题 devtunnel ，以下提示可能很有用：
- 确保使用的是最新版本的
devtunnelCLI。 使用devtunnel --version.. 检查当前安装的版本。 - 该
--verbose选项输出调试消息，这些消息可以提供额外的诊断信息。