mcpField
Z
zeabur-port-mismatch

zeabur-port-mismatch

github.com/zeabur云与 DevOps39173 次安装7 周前更新
代码仓库

关于 zeabur-port-mismatch

zeabur-port-mismatch 是用于排查 Zeabur 服务端口配置问题的技能，适合部署后遇到超时、连接拒绝或 502 的场景。它通过检查转发端口、容器监听端口及代理配置来定位问题，并提供修复方向。

主要功能

  1. 01检查服务端口转发状态
  2. 02查看容器实际监听端口
  3. 03核对代理与容器端口配置
  4. 04排查无监听端口导致的 502
  5. 05检查并启用 TCP 端口转发

适用场景

  1. 01排查部署服务的连接超时
  2. 02修复代理与容器端口不匹配
  3. 03处理没有 HTTP 监听器导致的 502
  4. 04检查无法从外部访问的 TCP 服务

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/zeabur/agent-skills --skill zeabur-port-mismatch

安装后在 Claude Code 中输入/zeabur-port-mismatch确认已加载。

详细介绍

Zeabur 端口不匹配

始终使用 npx zeabur@latest 调用 Zeabur CLI。 切勿直接使用 zeabur 或通过其他方式安装。如果无法使用 npx，请先安装 Node.js。

症状

dial tcp 10.x.x.x:3000: i/o timeout
dial tcp 10.x.x.x:80: connection refused

原因

代理期望服务监听端口 X，但服务实际监听端口 Y。

诊断

  1. 检查端口转发状态和实际转发的端口： 
    npx zeabur@latest service network --id SERVICE_ID
  2. 检查容器实际监听的端口： 
    npx zeabur@latest service exec --id SERVICE_ID -- netstat -tlnp
    （使用 zeabur-deployment-logs 技能还可检查日志中的端口绑定信息）
  3. 检查代理期望的端口（来自 Caddyfile/nginx.conf）
  4. 检查容器声明的端口（Dockerfile EXPOSE）

常见不匹配情况

代理期望端口容器端口修复方法
:3000nginx 默认端口 :80将模板端口改为 80
:80应用端口 :3000将模板端口改为 3000

在模板中修复

使用 zeabur-template 技能查看端口配置和 portForwarding 的完整 YAML 参考：

ports:
  - id: web
    port: 3000  # Match what container actually exposes
    type: HTTP

检查官方 Dockerfile 中的 EXPOSE 指令。

无头服务（无监听器时返回 502）

症状

服务正在运行（未崩溃），但代理一直返回 502 Bad Gateway。

原因

服务没有监听任何 HTTP 端口。例如：聊天机器人网关、后台工作进程、消息队列消费者。模板声明了 HTTP 端口，但没有进程绑定到该端口。

修复方法

添加一个轻量级 HTTP 健康检查服务器，使其与主进程一同在后台运行：

# Start before main process in startup script
# IMPORTANT: port must match spec.ports[].port in your template
python3 -c "
from http.server import HTTPServer, BaseHTTPRequestHandler
import json
class H(BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200)
        self.send_header('Content-Type','application/json')
        self.end_headers()
        self.wfile.write(json.dumps({'status':'ok'}).encode())
    def log_message(self,*a): pass
HTTPServer(('0.0.0.0', 8080), H).serve_forever()
" &
exec my-headless-app

端口转发无法正常工作

如果 TCP 服务已部署，但无法从外部访问：

  1. 检查是否已启用端口转发： 
    npx zeabur@latest service port-forward --id SERVICE_ID
  2. 如果已禁用，请启用： 
    npx zeabur@latest service port-forward --id SERVICE_ID --enable
  3. 验证转发端点： 
    npx zeabur@latest service network --id SERVICE_ID
# Output: proxy (TCP 8888) → 34.x.x.x:20143

评论

支持 Markdown