端口冲突排查——桌面端不会踩这个坑，Docker 和 JAR 会
三种部署方式的端口行为不一样
| 部署方式 | 默认端口 | 冲突怎么办 |
|---|---|---|
| 桌面端 | 动态挑选 | 自动找空闲端口，永远不冲突 |
| Docker Compose | 18080 | 改 docker-compose.yml 的端口映射 |
| 源码 mvn | 18088 | 加 --server.port=19090 |
| 预编译 JAR | 18088 | 加 --server.port=19090 |
桌面端为什么不会冲突
Electron 启动时，内嵌的 Spring Boot 后端会先扫描 5 个连续端口（比如从 17088 开始），找到第一个空闲的就用。前端页面通过 Electron 的 IPC 拿到这个端口，所以前后端自动同步。用户完全不知道端口这件事。
Docker 端口冲突
Docker Compose 里 MateClaw 的端口映射是 18080:18080。如果宿主机的 18080 被占了：
- 找到谁占了：
netstat -ano | findstr :18080 - 要么停掉那个进程，要么改 docker-compose.yml：把 MateClaw 端口映射改成
19090:18080
改完重新 docker compose up -d。注意：对外端口（左边那个）可以改，但容器内部端口（右边那个）不要改——MateClaw 容器里 Spring Boot 固定监听 18080。
JAR 端口冲突
mvn spring-boot:run -Dspring-boot.run.arguments="--server.port=19090" 或 java -jar mateclaw-server.jar --server.port=19090。
端口冲突时的现象
后端起不来，日志里会有类似 Port 18088 was already in use 的报错。检查日志文件确认。