用 HuaweiCloud DevKit 把本地静态页面推到公网：一次完整的踩坑记录

做前端 demo 最烦的一步从来不是写页面，而是"怎么让别人打开看一眼"。这次我拿一个单文件 2048 页面做实验，把从零到公网可访问的完整链路走了一遍，中间踩了几个坑，记下来备查。

## 一、环境准备

容器里先确认 Node 版本，DevKit 要求 >= 22：

```

node -v # v22.23.3

```

装 DevKit，一条命令装到本机所有 agent：

```

npx --yes huaweicloud-devkit install --target all

```

它会识别 OpenCode、CodeArts、WorkBuddy、DSH、Hermes、OpenClaw、AtomCode 等目标，装完顺手把 KooCLI 也带上了。

接着配置凭证：

```

npx --yes huaweicloud-devkit auth init

```

最后跑自检，这一步很重要，能提前发现问题：

```

npx --yes huaweicloud-devkit doctor --target all

```

我的结果是 11 项全部通过、0 警告。如果 doctor 挂了，基本就是 Node 版本、PATH 或者凭证三件事之一。

## 二、先把本地服务跑起来

静态页面不需要任何框架，python 自带的服务就够：

```

cd /root/workspace

nohup python3 -m http.server 8080 --bind 0.0.0.0 > /tmp/http8080.log 2>&1 &

curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8080/index.html

```

返回 200 就说明页面本身没问题，后面出问题一定是隧道层，不用再怀疑页面。

## 三、DevBridge 隧道：这里有两个坑

DevBridge 是 DevKit 体系里负责端口转发、把本地服务暴露成公网地址的组件，可执行文件一般已经在 PATH 里：

```

which devbridge # /usr/local/bin/devbridge

```

### 坑 1：description 不允许空格

第一次创建隧道：

```

devbridge create game2048 -d "2048 game tunnel"

```

报错：

```

Failed to create tunnel: Invalid tunnel description:

only Chinese characters, digits, letters, length 0-64

```

提示里只说了"只允许中文、数字、字母"，但实际是**连空格都不允许**。把描述改成不带空格的 `2048game` 就能过。建议官方把这条校验信息写得更明确一点，否则很容易在这里卡住。

### 坑 2：create 之前必须先 auth

改成合法描述后再试：

```

devbridge create game2048 -d "2048game"

```

这次报的是另一个错：

```

Failed to create tunnel: API key expired, please login again

```

查状态：

```

devbridge auth status # Not logged in

```

登录方式只有一个参数：

```

devbridge auth login --api-key <API_KEY>

```

也就是说 DevBridge 用的是**独立于 KooCLI 的 API Key**。这就带来一个实际困扰：KooCLI 那边平台已经注入了临时 AK/SK/SecurityToken，`hcloud` 调 IAM 完全正常，但 DevBridge 不认这套，还需要单独一把 key。在体验版容器里，这把 key 没有任何地方提供，于是隧道这一步就断在这儿。

## 四、如果隧道通了，验证方式是这样

拿到公网地址后，一定要从外部验一次，而不是只看本地：

```

curl -sI https://xxx.devbridge-s2.hwtunnel.com/index.html

```

必须是 200。只看本地 200 是不够的，因为隧道可能只做了 TCP 转发没做 HTTP 层校验，或者安全组没放行。

## 五、几点经验

1. **先 doctor 再干活**。DevKit 的 doctor 会把 Node 版本、agent 安装、KooCLI、凭证、网络连通性一起检查，比一个个手工试快得多。

2. **分层定位**。本地 curl 200 → 隧道层 → 公网 curl 200，三段分开验证，能省掉大量瞎猜。

3. **临时凭证和长期凭证要分清**。平台注入的 STS 只对 KooCLI/API 有效，像 DevBridge 这种需要独立 key 的组件，得单独准备。

4. **报错信息不完全可信**。`Invalid tunnel description` 没提空格，得自己试出来。

## 六、小结

DevKit 把"云上部署"这件事的门槛压得很低：装插件、配凭证、跑 doctor，三步就能让 agent 具备操作云资源的能力。真正容易卡住的往往不是这些主流程，而是 DevBridge 这种边缘组件的鉴权细节。

如果后面 DevBridge 能复用平台已经注入的临时凭证，或者至少在 `devbridge create` 的报错里把约束写全，这条链路会顺畅很多。