服务端未启动或端口被占用导致连接被拒绝

Question

常见问题：本地启动 Spring Boot 应用时抛出 `java.net.BindException: Address already in use: bind` 或客户端连接时报 `Connection refused`，排查发现服务进程未运行或端口（如 8080）被其他 Java 进程、Docker 容器、IDE 调试实例甚至残留 zombie 进程占用。典型诱因包括：开发中多次热重启未彻底终止旧进程；IDE（如 IntelliJ）调试中断后未释放端口；`application.properties` 中 `server.port=8080` 与本地已运行的 Nginx、Tomcat 或另一个 Spring Boot 实例冲突；macOS/Linux 下 `lsof -i :8080` 查不到进程，实则被 `launchd` 托管的后台服务占用。该问题表面是网络异常，本质是端口资源竞争，需结合进程检查、端口释放与配置隔离三步定位，而非简单重试连接。

Answer 1

```html

一、现象层：识别典型错误信号与表象特征

• java.net.BindException: Address already in use: bind —— Spring Boot 启动阶段即失败，表明端口已被绑定；
• Connection refused（客户端 curl / browser 报错）—— 应用未监听或已崩溃，但更常见于端口被抢占后服务根本未启动；
• IDE 控制台无报错却无法访问 http://localhost:8080，netstat -an | grep :8080 显示 LISTEN 但无对应 PID；
• 重启应用后偶现成功、偶现失败，提示“热部署残留”或“调试会话未清理”；
• macOS 上 lsof -i :8080 返回空，但端口仍不可用 —— 暗示 launchd 托管服务（如 com.apple.WebKit.Networking 或自定义 plist）静默占位。

二、进程层：跨平台精准定位占用者

端口竞争本质是 OS 级资源调度问题。不同系统需差异化排查：

系统	核心命令	关键注意事项
Linux	sudo ss -tulpn | grep ':8080'	比 netstat 更快，-p 需 root 权限才显示 PID/Program
macOS	sudo lsof -iTCP:8080 -sTCP:LISTEN -P	若无输出，追加 sudo launchctl list | grep -i "8080\|http"
Windows	netstat -ano | findstr :8080 → tasklist | findstr <PID>	注意 Windows 10+ 的 Hyper-V 虚拟交换机可能劫持 80/443/8080

三、容器与环境层：Docker、IDE 与僵尸进程的隐性干扰

现代开发栈中，端口冲突常源于非 Java 进程：

• Docker：运行 docker ps --format "table {{.ID}}\t{{.Ports}}\t{{.Names}}" | grep 8080 可快速发现映射到宿主机 8080 的容器；
• IntelliJ IDEA：调试中断后，若勾选了 “On ‘Update’ action” → “Update classes and resources” 而非 “Reload page”，旧 JVM 进程可能仍在后台存活；
• Zombie 进程：Linux 下 ps aux | grep java | grep -v grep 结合 ps -eo pid,ppid,comm,args | awk '$2==1 {print}' 可筛查孤儿 Java 进程；
• macOS launchd：检查 /Library/LaunchDaemons/ 和 ~/Library/LaunchAgents/ 中含 <key>Sockets</key> 的 plist 文件，使用 launchctl bootout gui/$UID <service-id> 强制卸载。

四、配置层：构建可预测、可隔离的端口治理策略

避免重复踩坑需从工程实践入手：

1. 在 application.yml 中启用随机端口：server.port: 0（测试/CI 场景首选）；
2. 按 profile 隔离端口：spring.profiles.active=dev → application-dev.yml 设为 8081，test 设为 8090；
3. 通过 Maven 属性注入：mvn spring-boot:run -Dspring-boot.run.jvmArguments="-Dserver.port=8082"；
4. IDEA 运行配置中添加 -Dserver.port=8083 并勾选 “Single instance only”；
5. 编写预启动钩子脚本（如 pre-start.sh），自动 kill 占用进程：lsof -ti:8080 | xargs kill -9 2>/dev/null || true。

五、自动化诊断流程图（Mermaid）

flowchart TD
  A[启动失败？] --> B{BindException or Connection refused?}
  B -->|Yes| C[执行端口扫描]
  C --> D[Linux: ss -tulpn
macOS: sudo lsof -iTCP:8080
Win: netstat -ano]
  D --> E{是否返回 PID？}
  E -->|Yes| F[kill -9 PID
或 taskkill /F /PID]
  E -->|No| G[检查 Docker / launchd / Hyper-V]
  G --> H[Docker ps -f port=8080
launchctl list | grep 8080
netsh interface portproxy show v4tov4]
  H --> I[释放端口并验证]
  I --> J[修改 server.port 或启用 port=0]
  J --> K[加入 CI/CD 预检脚本]

六、高阶防御：构建开发者端口健康看板

面向 5+ 年经验工程师，建议落地以下增强实践：

• 在项目根目录放置 port-check.sh，集成 Git Hook（pre-commit/pre-push）自动检测常用端口占用；
• 利用 Spring Boot Actuator + Prometheus + Grafana，暴露 process.uptime 与自定义端口探测指标；
• 在 IDE 中配置 External Tool：绑定快捷键一键执行 lsof -iTCP:8080 -sTCP:LISTEN -t | xargs kill -9；
• 为团队统一制定 .port-registry.md 文档，登记各本地服务端口（如：Auth Service→8085, API Gateway→8086, Mock Server→8099）；
• 使用 spring-boot-devtools 的 restart.exclude 配置避免类加载器泄漏导致的端口残留。

```