huawei-cloud-devbridge-tunnel

华为云 DevBridge 开发隧道

通过华为云中继基础设施创建和管理 DevBridge 开发隧道，安全地将本地开发服务开放给远程设备。

概述

DevBridge 是一项开发隧道服务，允许开发者将本地服务（Web 服务器、API、调试端点）开放给远程设备，而无需开放公共入站端口。CLI 工具（devbridge）用于管理隧道、端口、主机连接和 Connect 会话。Host 和 Connect 都会主动向中继服务发起出站连接，因此托管设备无需开放公共入站端口。

架构

Developer Device (Host)                    Remote Device (Connect)
┌──────────────────────┐                  ┌──────────────────────┐
│  Local Service :8080 │                  │  localhost:8080      │
│         │            │                  │         ▲            │
│  devbridge host      │                  │  devbridge connect   │
│         │            │                  │         │            │
└─────────┼────────────┘                  └─────────┼────────────┘
          │ Outbound connection                     │ Outbound connection
          ▼                                         ▼
┌─────────────────────────────────────────────────────────────────┐
│              DevBridge Relay Service (Huawei Cloud)              │
│                                                                  │
│  Tunnel (id) ── Port ── API Key / Token ── Access Policy         │
│  Address: https://<tunnelId>.<clusterId>.myhuaweicloud.com       │
└─────────────────────────────────────────────────────────────────┘

2026-09-20 域名升级通知：DevBridge 隧道域名已切换，原 *.cn-north-4-bridge.myhuaweicloud.com 变更为新集群域名（如 *.devbridge-s2.hwtunnel.com）。旧版端侧（v0.1.x）已无法连接，必须使用 v0.2.x 并重新创建隧道。以 devbridge host 实际输出的 Tunnel URL 为准。

使用场景

• 与团队成员远程调试并进行集成测试
• 与利益相关者分享开发中的网页
• 在本地开发期间接收 Webhook 回调
• 从移动设备或其他机器访问本地服务
• 临时开放本地 API 进行演示

常见用户表达

• “帮我把本地 8080 端口开放给远程设备”
• “为我的前端开发服务器创建一个开发隧道”
• “我需要与团队分享本地 API 以进行测试”
• “从另一台机器连接到隧道”
• “帮我把本地 8080 端口暴露给远程设备”

版本支持

项目	要求
CLI 版本	v0.2.x（从官方渠道安装，例如 0.2.1-release / 0.2.2-release）
身份验证	API Key（devbridge auth login --api-key 或环境变量 HW_API_KEY）或交互式登录
隧道域名	新集群域名（如 devbridge-s2.hwtunnel.com），显示在 devbridge host 输出中
旧版本	不支持 v0.1.x — 已移除 AK/SK 身份验证标志，旧域名也不再连接

动态命令适配层

重要 — 所有隧道/端口/主机操作都必须通过 db_* 封装函数执行（定义于 scripts/devbridge_cmd.sh），不得直接运行 devbridge 命令。只有 devbridge auth 和 devbridge version 除外。

DevBridge CLI 可能会在不同版本中更改标志。适配层会在执行前通过 devbridge <command> --help 动态发现受支持的标志，使该技能在 v0.2.x 范围内不受版本影响。它还会在执行后进行错误恢复：解析 cobra 错误，自动处理已重命名的标志、新增的必需参数或已重命名的命令。如果自动恢复失败，则会显示错误，并建议运行 devbridge <command> --help。

适配层函数

函数	替代项	用途
db_init	—	确保已安装 CLI（v0.2.x+）并完成身份验证（通过 DEVBRIDGE_API_KEY/HW_API_KEY 自动登录）
db_create	devbridge create	创建隧道，仅返回隧道 ID（stdout）
db_port_create	devbridge port create	创建端口（适配端口、协议和匿名标志）
db_host	devbridge host	在后台启动托管，返回 PID（stdout）和隧道 URL（stderr）
db_host_bg	devbridge host + nohup bash -c	在后台启动托管（旧版别名，请改用 db_host）
db_connect	devbridge connect	在后台启动连接，返回 PID（stdout）
db_list	devbridge list	列出隧道
db_show	devbridge show	显示隧道详情
db_update	devbridge update	更新隧道
db_delete	devbridge delete	删除隧道
db_delete_all	devbridge delete-all	删除所有隧道
db_port_list	devbridge port list	列出端口
db_port_delete	devbridge port delete	删除端口（适配端口标志）
db_limits	devbridge limits	显示配额 / 用量 / 余额
db_echo	devbridge echo	启动诊断回显服务
db_ping	devbridge ping	对 URI 执行 ping 以测试连通性
db_version	devbridge version	显示 CLI 版本
db_auth_status	devbridge auth status	检查身份验证状态
db_auth_login	devbridge auth login	登录（交互式或使用 --api-key）
db_tunnel_url	—	从托管日志获取隧道公网 URL（以此为准，请勿手动构造）
db_processes	—	列出正在运行的托管 / 连接进程
db_process_stop	—	按 PID 停止托管 / 连接进程
db_process_logs	—	按 PID 获取进程日志

前置条件

重要 — 在检查前置条件时，切勿向用户请求确认。 db_init 会静默并自动执行：（1）缺少 CLI 时安装；（2）如果是 v0.1.x，则升级（旧域名无法连接）；（3）检查身份验证；（4）通过 DEVBRIDGE_API_KEY 或 HW_API_KEY 环境变量自动登录。只有检查失败时才显示输出。

source <skill_directory>/scripts/devbridge_cmd.sh
db_init

v0.2.x 仅支持 API Key：--access-key / --secret-key / --security-token（AK/SK）参数已移除，不要尝试使用 AK/SK 登录（旧版 skill 的用法在 v0.2.x 中无效）。API Key 可在 DevBridge 管理页面创建：https://devstation.connect.huaweicloud.com/space/devbridge/apikey。

对于自动化环境，请使用 API Key（参见 references/iam-policies.md）。API Key 可在 DevBridge 管理页面创建：https://devstation.connect.huaweicloud.com/space/devbridge/apikey。

安装脚本注意事项：在非交互式 / 无头环境中，始终为安装脚本传入 -s（静默）参数：... | bash -s -- -s。否则，脚本可能会提示“是否覆盖？”，并尝试读取 /dev/tty，在没有终端的环境中导致失败。

GitCode 私有仓库安装：npx skills add 不支持 GitCode token 身份验证。从私有仓库安装 skill 时，请先执行 git clone，然后手动复制：

git clone https://oauth2:<token>@gitcode.com/<org>/<repo>.git /tmp/repo
cp -r /tmp/repo/skills/devtools/devbridge/huawei-cloud-devbridge-tunnel/ ~/.agents/skills/huawei-cloud-devbridge-tunnel/

权限 / 身份验证失败处理

如果任何 DevBridge 命令因凭据无效或缺失而失败：

1. 检查 devbridge auth status；如果尚未登录，请登录（交互式或使用 --api-key）。
2. 如果使用 API Key，请确认其存在且未过期或删除：在 API Key 管理页面重新创建，并通过 HW_API_KEY 注入。
3. 阅读 references/iam-policies.md 了解相关说明。
4. 暂停执行，等待用户确认凭据已更新后再重试。

系统要求

• Bash 和 curl，或 PowerShell 5.1+
• x86-64 或 ARM64 架构
• 能够访问 DevBridge 安装源
• 对 ~/.huawei 目录具有写入权限

工作流

关键事项——创建隧道期间零确认。 全程自动执行（检查 CLI → 加载适配层 → 检查认证 → 创建隧道 → 配置端口 → 启动托管），完全不与用户交互。不得询问用户确认参数，也不得在步骤之间暂停。所有步骤完成后才显示结果。唯一例外是隧道名称冲突——如果 db_create 因名称已存在而失败，继续之前先提供是/否选项（是否复用现有隧道？）。

默认参数

参数	默认值
隧道名称	dev-tunnel-<random>（例如，dev-tunnel-3847）
描述	开发隧道
过期时间	72（小时）——CLI 默认值；范围为 1–720
端口	8080
协议	auto（选项：http / https / auto）
匿名访问	禁止（--deny-anonymous 是 CLI 默认值；仅当用户明确要求允许匿名访问时才使用 -a）

安全变更：匿名访问默认禁止。与较早版本的技能不同，默认不得传入 --anon allow。仅当用户明确要求，或内容明确为公开内容时，才允许匿名访问。

参数解析

对于每个参数，如果用户明确指定了值，就使用该值；否则使用默认值。不要询问确认，直接合并参数并继续。

• 隧道名称：用户提到了名称（例如，“创建一个叫 my-api 的隧道” → my-api）
• 端口：用户提到了端口号（例如，“暴露 3000 端口” → 3000）
• 描述：用户提到了描述（例如，“描述是后端API” → 后端API）
• 过期时间：用户提到了时长（例如，“过期时间24小时” → 24）；否则为 72
• 协议：用户提到了协议（例如，“用https” → https）；否则为 auto
• 匿名访问：用户说“允许匿名访问”或“公网直接访问” → -a；否则禁止（默认）

快速创建流程（用户未指定参数，只说“创建隧道”时）

source <skill_directory>/scripts/devbridge_cmd.sh
db_init
TUNNEL_NAME="dev-tunnel-$((RANDOM % 9000 + 1000))"
TUNNEL_ID=$(db_create "$TUNNEL_NAME" -d "开发隧道" -e 72)
db_port_create "$TUNNEL_ID" -p 8080 --protocol auto
db_host "$TUNNEL_ID"                  # 输出 PID 和 Tunnel URL 到 stdout
TUNNEL_URL=$(db_tunnel_url "$TUNNEL_ID")
echo "Tunnel ID: $TUNNEL_ID"
echo "Tunnel URL: $TUNNEL_URL"

注意：匿名访问默认禁止。 上述流程创建的隧道默认使用 --deny-anonymous，公网访问会返回 authentication required。如果需要直接通过公网访问（例如，将 Web 服务暴露给外部用户），请在 db_port_create 时添加 -a：

db_port_create "$TUNNEL_ID" -p 8080 --protocol auto -a   # 允许匿名访问

完整工作流（用户提供了具体参数时）

步骤 1：安装或更新 DevBridge CLI

devbridge version
# 下载安装脚本到临时文件再执行（避免管道直接执行）
curl -fsSL https://gitcode.com/CloudDeveloperDepartment/devbrige/releases/download/latest/install.sh -o /tmp/devbridge_install.sh
bash /tmp/devbridge_install.sh -s
devbridge version

步骤 2：加载适配层并进行身份验证

export PATH="$HOME/.huawei/bin:$PATH"
source <skill_directory>/scripts/devbridge_cmd.sh
db_init
devbridge auth status 2>/dev/null || devbridge auth login --api-key "$HW_API_KEY"

步骤 3：创建隧道

# <name> = user-specified or "dev-tunnel", <description> = user-specified or "开发隧道", <expiration> = user-specified or 72
# Note: description only allows Chinese characters, digits, and letters (no spaces), max 64 characters
db_create <name> -d "<description>" -e <expiration>

隧道名称冲突处理——零确认的唯一例外。 如果 db_create 失败并提示 "This tunnel name is already in use"：

1. 运行 db_list 查找现有隧道。
2. 静默检查使用状态：db_port_list <tunnelId>（是否已配置端口？）、ps aux | grep "devbridge host <tunnelId>" | grep -v grep（是否正在托管？）、ps aux | grep "devbridge connect <tunnelId>" | grep -v grep（是否有活动连接会话？）。
3. 显示隧道详情和使用状态：活动（托管正在运行／会话处于活动状态——复用可能产生冲突）、空闲（已配置端口但没有活动进程——可安全复用）或空置（没有端口——需要进行设置）。
4. 提供是/否选项：“隧道名称已存在，当前状态为 <active/idle/empty>，是否复用现有隧道？”
   • 是——复用现有隧道，继续执行步骤 4（如果已处于活动状态，则跳过步骤 5）。
   • 否——询问新的隧道名称并重试。

步骤 4：配置端口

# <port> = user-specified or 8080, <protocol> = user-specified or auto
# Anonymous access: default deny; use -a only if user explicitly asks
db_port_create <tunnelId> -p <port> --protocol <protocol>

更新端口后需重启 host： 如果 host 进程已在运行，使用 devbridge port update 修改端口配置（例如，切换匿名访问策略）后，正在运行的 host 进程不会自动感知变更。需要先停止旧 host 进程（db_process_stop <pid>），再重新运行 db_host <tunnelId>，新配置才能生效。

步骤 5：托管本地服务

nohup python3 -m http.server <port> > /tmp/devbridge-service.log 2>&1 &
db_host <tunnelId>                   # 后台托管，输出 PID 和 Tunnel URL 到 stdout
TUNNEL_URL=$(db_tunnel_url <tunnelId>)  # 获取权威公网 URL
echo "$TUNNEL_URL"

另一种一次性临时隧道方式：devbridge host -p 8080 -e 8（创建临时隧道并立即启动托管）。

⚠️ 中继域名会随集群变化，严禁根据文档拼接 URL。请一律使用 db_tunnel_url <id> 读取权威地址。

步骤 6：从远程设备连接

db_connect <tunnelId>

在远程设备上通过 http://localhost:8080 访问该服务。

步骤 7：清理

db_processes                    # List running processes
db_process_stop <pid>           # Stop host/connect process
db_delete <tunnelId>            # Delete tunnel

核心命令

注意： 所有命令均使用 db_* 包装器形式。适配层会自动检测已安装 CLI 版本对应的正确标志名称。

身份验证

命令	说明
devbridge auth login	交互式登录（打开浏览器）。
devbridge auth login --api-key <key>	使用 API Key 登录。
HW_API_KEY=<key> devbridge auth login	使用环境变量中的 API Key 登录。
devbridge auth status	检查当前登录状态。
devbridge auth logout	清除本地凭据。

在 v0.2.x 中移除：不再支持 --access-key、--secret-key、--security-token（AK/SK）。请改用 API Key。

隧道管理

命令	说明
db_create <name> -d <desc> -e <hours>	创建隧道。
db_list	列出当前工作区中的活动隧道。
db_show <tunnelId>	显示隧道详情。
db_update <tunnelId> -n <name> -d <desc> -e <hours>	更新隧道名称、描述或有效期。
db_delete <tunnelId>	删除隧道。
db_delete_all	删除当前工作区中的所有隧道。
devbridge token <tunnelId> -s host	签发新的 Host 令牌。
devbridge token <tunnelId> -s connect	签发新的 Connect 令牌。
devbridge set <tunnelId>	将此隧道设为本机的默认隧道。
devbridge unset	清除默认隧道。
db_limits	显示账户配额、用量和余额。

端口管理

命令	说明
db_port_create <tunnelId> -p <port> --protocol <protocol>	创建端口（默认禁止匿名访问；添加 -a 可允许匿名访问）。
db_port_list <tunnelId>	列出隧道端口。
devbridge port show <tunnelId> -p <port>	显示端口详情。
devbridge port update <tunnelId> -p <port> -a	更新端口匿名访问策略（允许）。
devbridge port update <tunnelId> -p <port> --deny-anonymous	更新端口匿名访问策略（禁止）。
db_port_delete <tunnelId> -p <port>	删除端口。

Host 和 Connect

命令	说明
db_host <tunnelId>	为现有隧道中配置的所有端口提供 Host 服务。
devbridge host -p 8080 -e 8	创建临时隧道并立即提供 Host 服务。
devbridge host <tunnelId> --api-key <key>	使用 API Key 身份验证提供 Host 服务（跳过令牌签发）。
devbridge host <tunnelId> --token <jwt>	使用显式指定的 JWT 令牌提供 Host 服务。
db_connect <tunnelId>	连接到隧道并建立本地端口映射。
devbridge connect <tunnelId> --api-key <key>	使用 API Key 身份验证进行连接。

诊断

命令	说明
db_echo	在本地端口上启动 HTTP 回显服务（默认使用随机端口，地址为 127.0.0.1），以验证隧道链接。
db_ping <uri>	向 URI 发送 HTTP ping，并输出状态码和延迟。默认限时 3 秒（devbridge ping 是持续运行的命令，可避免脚本挂起）；DB_PING_SECONDS=0 时则持续观测。
devbridge -v <command>	为任何命令启用调试日志。

参数

参数	CLI 标志	默认值	范围 / 约束	描述
<name>	db_create	dev-tunnel-<random>	最多 128 个字符	隧道名称。
-d	db_create, db_update	开发隧道	仅限汉字、数字和字母（不含空格），最多 64 个字符	隧道描述。
-e	db_create, db_update, host	72（小时）	1–720 小时	过期时间。
-n	db_update	无	—	新隧道名称。
-s	token	必填	host 或 connect	令牌范围。
-p	db_port_create, db_port_delete	8080	1–65535	端口号（CLI 中为 --port-number）。
--protocol	db_port_create	auto	http、https、auto	协议。
-a / --allow-anonymous	db_port_create	未设置（拒绝）	—	允许匿名访问。
--deny-anonymous	db_port_create	默认值	—	拒绝匿名访问（CLI 默认值）。
-k / --api-key	host, connect	无	—	API Key 身份验证，跳过令牌签发。
-t / --token	host, connect	无	—	JWT 令牌身份验证。
-v / --verbose	全局	false	—	启用调试日志记录。

破坏性操作（db_delete、db_delete_all、db_port_delete）应直接执行，无需询问确认。

输出格式

隧道创建输出（db_create）

标准输出中仅返回隧道 ID（从 CLI 文本输出中提取）：

noh56s7x

Host 输出（db_host）

标准输出中返回 PID 和隧道 URL（带标签格式，每行一项）：

PID: 3519475
Tunnel URL: https://noh56s7x-8080.devbridge-s2.hwtunnel.com

使用 grep 解析：PID=$(db_host <id> | grep -oP 'PID: \K\d+')

使用 db_tunnel_url <tunnelId> 获取权威 URL（不要手动构造——域名可能因集群而异）。

端口创建输出

Port added: TunnelId=noh56s7x, Port=8080

令牌输出

Tunnel ID:     noh56s7x
Scope:         host
Lifetime:      24:00:00
Expires At:    2026-08-09 06:57:10 UTC
Token:         <token-value>

列表输出

Tunnel ID  Name             Description  Tunnel Expiration  Port Count
dwskt2pg   dev-tunnel-5941  开发隧道     3 days             1

注意：v0.2.x 移除了 list 和 port list 的 --json 输出标志。请使用文本表格输出；如有需要，可使用 awk/grep 进行解析。

验证

详细的验证步骤请参阅 references/verification-method.md。

快速验证：

db_init                  # CLI installed + authenticated
db_version               # v0.2.x+
db_auth_status           # Logged in
db_list                  # Tunnels listed
db_port_list <tunnelId>  # Ports listed
db_processes             # Host process running
db_tunnel_url <tunnelId> # Public URL accessible

最佳实践

1. 自动检查身份验证，无需用户交互 — 静默检查身份验证状态，仅在未通过身份验证时引导用户登录。建议在自动化场景中通过 HW_API_KEY 使用 API Key。
2. 设置合理的过期时间 — 使用足以覆盖工作时段的最短过期时间（默认 72 小时，最长 720 小时）。
3. 默认拒绝匿名访问 — 仅在用户明确请求或内容明确公开时才允许（-a）。
4. 重复工作时使用持久隧道 — 创建一次隧道，然后使用 db_host <tunnelId> 重复使用。
5. 设置默认隧道以方便使用 — 使用 devbridge set <tunnelId>，避免重复指定隧道 ID。
6. 使用后清理 — 停止 Host/Connect 进程，并在不再需要时删除隧道。
7. 绝不暴露管理界面 — 管理面板、调试端点和修改数据的 API 应始终禁用匿名访问。
8. 不可用于生产环境 — 开发隧道仅用于开发、调试和临时共享。
9. 将 CLI 升级到 v0.2.x — 2026-09-20 的域名切换使旧客户端失效；较早版本已无法连接。

参考文档

• CLI 安装指南 — DevBridge CLI 安装、PATH 配置和验证。
• API 密钥与访问 — API 密钥管理、身份验证方法和权限失败处理。
• 验证方法 — 分步验证安装、配置和功能。
• 验收标准 — 技能测试的通过／失败标准。
• CLI 命令参考 — 包含所有参数的完整 CLI 命令参考。
• REST API 参考 — 用于以编程方式管理隧道和端口的 REST API。
• 故障排除 — 常见问题及解决方案。

注意事项

安全性

• 切勿在脚本、日志或配置文件中硬编码 API 密钥。 请使用 devbridge auth login --api-key "$HW_API_KEY" 或 HW_API_KEY 环境变量。
• 隧道令牌属于敏感信息——请勿将其写入日志、URL、代码仓库或长期配置文件。
• 匿名访问意味着任何拥有隧道地址的人都可以访问该端口，无需 DevBridge 身份验证。仅对明确公开的内容启用此功能。
• delete-all 是破坏性操作——它会删除当前工作区中的所有隧道。请直接执行，无需询问用户。共享／复用工作区时，先执行 db_list 确认，避免连带删除他人的隧道。

限制

• 每个工作区最多有 10 个活动隧道（默认配额）。
• 隧道有效期：1-720 小时（默认 72 小时）。
• 端口范围：1-65535；同一隧道内端口不可重复。
• CLI 不支持修改现有端口的协议——请删除后重新创建。
• 端口命令不支持 -d（描述）参数。
• 不支持批量删除端口——请逐个删除端口，或删除整个隧道。
• Host 和 Connect 是由后台管理的进程——请使用 db_process_stop <pid> 停止。
• v0.2.x 中的 list／port list 不再支持 --json 输出。

兼容性

• DevBridge CLI v0.2.x 支持 x86-64 和 ARM64 架构。
• Linux/macOS 需要 Bash 和 curl；Windows 需要 PowerShell 5.1+。
• CLI 安装在 ~/.huawei/bin；配置和状态存储在 ~/.huawei/devbridge。
• 切勿将 ~/.huawei/devbridge 提交到版本控制，或在用户之间共享。
• 动态命令适配——scripts/devbridge_cmd.sh 适配层通过 --help 动态发现支持的标志，使此技能兼容任何版本的 DevBridge CLI v0.2.x。无需固定版本。