zeabur-port-mismatch

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Zeabur Port Mismatch

Zeabur端口不匹配

Always use
npx zeabur@latest
to invoke Zeabur CLI. Never use
zeabur
directly or any other installation method. If
npx
is not available, install Node.js first.

请始终使用
npx zeabur@latest
调用Zeabur CLI。切勿直接使用
zeabur
或其他任何安装方式。如果
npx
不可用，请先安装Node.js。

Symptom

症状

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

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

Cause

原因

Proxy expects service on port X, but service listens on port Y.

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

Diagnose

诊断步骤

Check port forwarding status and actual forwarded ports:
bash
```
npx zeabur@latest service network --id SERVICE_ID
```
Check what port the container is actually listening on:
bash
```
npx zeabur@latest service exec --id SERVICE_ID -- netstat -tlnp
```
(use the
```
zeabur-deployment-logs
```
skill to also check logs for port binding info)
Check what port proxy expects (from Caddyfile/nginx.conf)
Check what port container exposes (Dockerfile
```
EXPOSE
```
)

检查端口转发状态及实际转发端口：

bash

npx zeabur@latest service network --id SERVICE_ID

检查容器实际监听的端口：
bash
```
npx zeabur@latest service exec --id SERVICE_ID -- netstat -tlnp
```
（也可使用
```
zeabur-deployment-logs
```
技能查看日志中的端口绑定信息）
检查代理期望的端口（从Caddyfile/nginx.conf中查看）
检查容器暴露的端口（Dockerfile中的
```
EXPOSE
```
指令）

Common Mismatches

常见不匹配场景

Proxy expects	Container has	Fix
`:3000`	nginx default `:80`	Change template port to 80
`:80`	app on `:3000`	Change template port to 3000

代理期望	容器实际配置	修复方案
`:3000`	nginx默认 `:80`	将模板端口改为80
`:80`	应用运行在 `:3000`	将模板端口改为3000

Fix in Template

在模板中修复

Use the

zeabur-template

skill for full YAML reference on port configuration and

portForwarding

yaml

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

Check official Dockerfile for
EXPOSE
directive.

使用

zeabur-template

技能获取端口配置和

portForwarding

的完整YAML参考：

yaml

ports:
  - id: web
    port: 3000  # 与容器实际暴露的端口保持一致
    type: HTTP

请查看官方Dockerfile中的
EXPOSE
指令。

Headless Service (502 with no listener)

无头服务（无监听导致502错误）

Symptom

症状

Service is running (no crash), but proxy returns 502 Bad Gateway permanently.

服务正在运行（未崩溃），但代理持续返回502 Bad Gateway错误。

Cause

原因

Service does not listen on any HTTP port. Examples: chatbot gateways, background workers, message queue consumers. The template declares an HTTP port but nothing binds to it.

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

Fix

修复方案

Add a lightweight HTTP health check server that runs in the background alongside the main process:

bash

undefined

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

bash

undefined

Start before main process in startup script

在启动脚本中先启动该服务

IMPORTANT: port must match spec.ports[].port in your template

重要：端口必须与模板中spec.ports[].port的配置一致

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

undefined

undefined

Port Forwarding Not Working

端口转发不生效

If a TCP service is deployed but not reachable externally:

Check if port forwarding is enabled:

bash

npx zeabur@latest service port-forward --id SERVICE_ID

Enable it if disabled:

bash

npx zeabur@latest service port-forward --id SERVICE_ID --enable

Verify the forwarded endpoint:

bash

npx zeabur@latest service network --id SERVICE_ID
# Output: proxy (TCP 8888) → 34.x.x.x:20143

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

检查端口转发是否已启用：

bash

npx zeabur@latest service port-forward --id SERVICE_ID

若未启用则开启：

bash

npx zeabur@latest service port-forward --id SERVICE_ID --enable

验证转发端点：

bash

npx zeabur@latest service network --id SERVICE_ID
# 输出示例：proxy (TCP 8888) → 34.x.x.x:20143