Connection refused — a firewall or proxy may be blocking it (ECONNREFUSED)

原文：API Error: Connection refused — a firewall or proxy may be blocking it (ECONNREFUSED)
译文：API 错误：连接被拒绝 — 可能是防火墙或代理阻止了连接（ECONNREFUSED）

🎯 原因分析

该错误的根本原因是客户端尝试连接目标 API 时，网络层直接收到 ECONNREFUSED 信号，说明目标端口未监听或被阻断。常见场景：

服务端未启动或未开放对应端口

防火墙、安全组、代理规则拦截了连接

本地或网络环境的出站流量被限制

💡 解决方案

#### 1️⃣ 检查服务端是否正常运行并监听端口

# 查看端口监听状态
netstat -tlnp | grep <端口号>
# 或
ss -tlnp | grep <端口号>

若服务未启动，请先启动服务；若端口被占用，需调整为预期端口。

#### 2️⃣ 检查防火墙与代理配置

# Linux 检查防火墙
sudo ufw status
sudo systemctl status ufw

# 检查代理环境变量
env | grep -i proxy

如存在代理，请确认代理服务正常运行；若无必要代理，临时移除或放行目标地址的访问规则。

# 放行目标 IP/端口示例（ufw）
sudo ufw allow from <客户端IP> to any port <端口号>

#### 3️⃣ 确认 API 地址与端口配置正确
确保请求的主机、端口、协议（HTTP/HTTPS）与服务端匹配，避免因配置错误导致“连接被拒绝”。

🛡️ 预防措施

定期在开发/测试环境与生产环境同步网络配置，统一端口策略，避免环境差异导致连通性问题。

使用连通性检测工具（如 telnet、nc、curl）在部署前后预检网络通畅情况，例如：

  nc -zv <主机> <端口>
  

在 CI/CD 中增加网络健康检查步骤，在发布前验证关键 API 的可达性，提前发现防火墙或代理阻断问题。