前言

最近在使用 AI Agent 开发一些简单的网页工具时，我发现一个比较典型的问题：

AI 已经把网页开发完成，本地服务也显示启动成功，但打开云端提供的预览链接，却出现 502 Bad Gateway。

第一次遇到这种情况，很容易以为是网页代码出了问题。

于是让 AI 重新检查 HTML、修改 JavaScript、重新安装依赖，甚至反复启动项目。

但实际上，502 错误很多时候并不是前端代码本身导致的。

它可能与服务端口、进程生命周期、网络隔离或者云端访问隧道有关。

这篇文章就从一个简单的静态网页项目出发，介绍如何分层排查这类问题，让 AI Agent 少做无效操作，更快找到真正原因。

一、为什么本地正常，外部却无法访问？

假设我们开发了一个简单网页：

mini-app/
├── index.html
├── style.css
└── script.js

通过 Python 启动服务：

python3 -m http.server 3000

然后在终端执行：

curl http://127.0.0.1:3000

能够正常返回 HTML。

说明当前终端所在的网络环境可以访问这个 HTTP 服务。

但是，云端预览链接可能仍然返回：

502 Bad Gateway

这是为什么？

因为本地访问和外部访问经过的网络路径并不相同。

一个典型的云端预览架构可以简化为：

用户浏览器
    ↓
云端访问入口
    ↓
代理或隧道服务
    ↓
开发容器中的监听端口
    ↓
本地 HTTP 服务
    ↓
网页文件

本地 curl 成功，只验证了最后一部分访问路径。

如果中间的代理或隧道无法连接目标服务，外部访问仍然可能失败。

因此，本地 HTTP 200 不等于外部预览一定可用。

二、第一步：确认服务真的在监听端口

遇到 502 时，我认为首先应该检查的是服务本身，而不是立即修改网页代码。

例如：

ss -lntp | grep ':3000 '

这条命令可以检查 TCP 3000 端口的监听情况。

如果没有结果，需要确认：

• HTTP 服务是否已经启动。

• 服务是否因为错误退出。

• 实际监听端口是不是 3000。

• 端口是否被其他进程占用。

再执行：

curl -v --max-time 5 http://127.0.0.1:3000/

如果无法连接，优先排查本地 HTTP 服务。

如果能正常返回网页内容，再继续检查外部访问路径。

这里有一个容易忽略的问题：

终端显示启动命令已经执行，不代表服务进程仍然存活。

AI Agent 有时会把“执行了启动命令”误判成“服务已经持续运行”。

这两件事需要分开验证。

三、第二步：检查监听地址

在 Linux 环境中，服务可能监听不同的地址。

例如：

127.0.0.1:3000

表示只监听本机回环接口。

而：

0.0.0.0:3000

表示监听所有 IPv4 网络接口。

两者的访问范围不同。

如果云端代理需要通过容器的非回环网络接口连接 HTTP 服务，而服务仅绑定到 127.0.0.1，就可能无法访问。

对于支持此方式的开发环境，可以使用：

python3 -m http.server 3000 --bind 0.0.0.0

然后重新检查监听状态。

但需要注意，绑定 0.0.0.0 会扩大服务的网络监听范围，是否适合应根据平台网络隔离和访问控制要求决定。

并不是所有云端预览平台都要求绑定 0.0.0.0。

如果平台通过同一网络命名空间的本地代理访问，绑定回环地址也可能正常工作。

因此，应该优先遵守开发平台的端口和监听规范，而不是把修改绑定地址当成万能解决办法。

四、第三步：检查服务进程是否被自动结束

AI Agent 经常通过工具执行 Shell 命令。

例如：

python3 -m http.server 3000

在普通终端中，这个命令会持续运行。

但是，在部分云端 AI 执行环境中，工具调用结束时，相关会话可能被关闭。

如果 HTTP 服务属于该会话管理的进程组，就可能随之退出。

这会出现一种现象：

1. AI 启动网页服务。

2. 终端暂时显示服务正常。

3. AI 继续执行其他工具。

4. 服务进程被终止。

5. 外部预览链接返回 502。

因此，云端自动化开发需要特别注意进程生命周期管理。

如果平台提供专门的后台进程管理工具，应该优先使用。

例如，某些环境提供独立启动 HTTP 服务的工具，支持指定工作目录、日志文件和 PID 文件。

这种方式通常比依赖临时终端会话更适合自动化工作流。

不过，后台启动也不能省略后续检查。

正确流程应该是：

启动进程 → 确认进程存活 → 检查本地 HTTP → 检查预览入口。

五、第四步：确认云端隧道连接的是正确端口

假设本地服务监听 3000 端口。

但云端预览配置却指向 8080 端口。

此时网页服务本身完全正常，代理也可能因为找不到正确的上游服务而返回 502。

因此，需要确认三个信息：

例如，服务监听 3000，就需要让预览配置与实际监听端口保持一致。

如果平台存在容器隔离，还应当确认端口转发连接的是正确的容器或网络环境。

不能只因为两个地方都写着 3000，就认为它们必然位于同一网络命名空间。

六、第五步：使用分层排查，而不是盲目重启

我认为解决这类问题最有效的方法，是把排查分成几个层次。

第一层：文件层

检查 index.html 是否存在，资源路径是否正确。

第二层：进程层

检查 HTTP 服务进程是否仍在运行。

第三层：端口层

检查监听地址和实际端口。

第四层：本地 HTTP 层

使用 curl 验证网页是否能够正常返回。

第五层：云端隧道层

检查代理、隧道配置以及外部链接是否有效。

只有前一层确认正常，才需要继续检查后一层。

这样可以避免反复出现以下无效操作：

外部访问 502
    ↓
重新修改 HTML
    ↓
重新运行测试
    ↓
重新安装依赖
    ↓
重新启动服务
    ↓
仍然 502

如果问题本来就在隧道配置上，反复修改 HTML 并不会解决它。

七、用一个简单的 Shell 脚本完成基础检查

对于简单网页项目，可以使用一个小脚本检查文件和本地服务。

#!/usr/bin/env bash

PORT=3000

echo "1. 检查首页文件"

if [ ! -f index.html ]; then
    echo "FAIL: index.html 不存在"
    exit 1
fi

echo "2. 检查端口监听"

if ! ss -lnt | grep -q ":${PORT} "; then
    echo "FAIL: 端口未监听"
    exit 1
fi

echo "3. 检查本地 HTTP"

STATUS=$(curl -s -o /dev/null \
    -w "%{http_code}" \
    --max-time 5 \
    "http://127.0.0.1:${PORT}/")

if [ "$STATUS" = "200" ]; then
    echo "PASS: 本地网页返回 HTTP 200"
else
    echo "FAIL: HTTP 状态码为 $STATUS"
    exit 1
fi

echo "本地基础检查完成"

这段代码需要 Linux 环境中具备 ss、curl 和 Bash。

它可以帮助开发者快速确定本地服务是否基本正常。

但它不能验证云端隧道，也不能证明网页上的所有按钮都能正常使用。

因此，如果本地检查全部通过，但外部仍然返回 502，就应该进一步检查平台的代理与隧道状态，而不是继续重复同一组本地测试。

八、AI Agent 如何避免在 502 问题上浪费时间？

对于自动化开发任务，我认为可以在提示词中直接规定排查顺序。

例如：

如果网页预览出现 502，优先检查服务进程、监听地址、实际端口和云端隧道配置。已经通过的本地功能测试不要重复执行。不要在没有证据时重新安装依赖或修改网页代码。

这样的提示词可以让 AI Agent 更明确地定位问题。

同时，还应该限制相同错误的重试次数。

例如，当两次启动服务都出现完全相同的端口冲突时，第三次不应该继续执行相同命令。

而应该先确定端口被哪个进程占用，再选择符合平台要求的备用端口。

对于多个独立项目，也应该为每个项目分配明确的工作目录，避免服务启动时读取了错误的网页文件。

九、临时预览链接不等于正式部署地址

还有一个容易忽略的问题：

一些云端开发环境提供的预览链接，本质上是临时开发隧道。

它们通常用于开发调试，不一定能够长期保持可用。

例如：

开发空间被回收。

后台服务停止。

隧道会话到期。

这些情况都可能导致原本正常的链接失效。

因此，如果作品需要长期公开访问，应该考虑正式的静态网站托管或部署方案。

而不是简单地把临时预览地址当成永久网站。

对于作品展示平台，还需要区分：

• 作品展示页是否长期存在。

• 项目源代码是否已保存到远程仓库。

• 网页应用本身是否具有持续可用的部署地址。

这三件事情并不完全相同。

十、总结

AI Agent 自动开发网页时，502 Bad Gateway 是一个很容易让开发流程陷入反复排查的问题。

但很多时候，真正需要检查的不是前端代码，而是服务进程与网络访问路径。

通过本文的分析，可以总结出几个重要经验：

1. 本地 HTTP 正常不代表云端预览一定正常。

2. 启动命令执行成功不代表服务进程一直存活。

3. 监听地址、端口和隧道配置必须匹配。

4. 排查故障应当按照文件、进程、端口、HTTP 和隧道逐层进行。

5. 临时开发预览链接不能直接视为永久部署地址。

我认为，AI Agent 开发效率的提升，不只是减少工具调用次数，更重要的是每一次工具调用都能帮助缩小问题范围。

对于一个已经开发完成的网页，如果问题只是隧道连接失败，那么最好的修复方式应该是调整服务运行与访问配置，而不是重新开发整个项目。

真正高效的 AI 自动化，不是遇到错误就不断重试，而是能够根据错误发生的位置，快速找到最小可行的修复方案。