端口被占用导致Hermes Agent网关启动失败，需依次排查：一、定位并终止占用进程；二、修改application.yml中server.port为可用端口；三、检查Docker容器端口映射冲突；四、验证真实监听状态并排除防火墙误报。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
Hermes Agent网关启动时卡在“Binding to port 8080…”或直接报错“Address already in use”，说明目标端口已被其他进程独占绑定，TCP监听无法初始化，服务进程因此阻塞或崩溃退出。
快速定位并杀死占用端口的进程
这一步操作起来很简单，直接在终端执行命令就能看到谁在抢你的端口。
Windows用户运行：netstat -ano | findstr :8080；Linux/macOS用户运行：lsof -i :8080。
输出结果中找PID列的数字——它就是占用端口的进程号，比如12345。
Windows执行：taskkill /PID 12345 /F；Linux/macOS执行：kill -9 12345。
【务必确认该PID对应进程非数据库、Nginx等关键服务，否则强制终止会导致业务中断】
修改application.yml切换监听端口
当占用端口的是不可关停的服务（例如公司统一部署的Nginx反向代理），你就得让Hermes Agent主动让路。
打开项目根目录下的application.yml文件。
找到server:区块下的port:字段，把值改成一个当前未被占用的端口，比如8081或9091。
保存文件后，在终端执行：hermes gateway restart。
验证是否生效：访问http://localhost:8081/actuator/health，返回HTTP 200即成功。
检查Docker容器端口映射冲突
如果你用Docker运行Hermes Agent，宿主机端口可能被容器内其他服务或旧容器残留映射占住。
方法一：查看所有正在运行的容器及其端口绑定：docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Ports}}" | grep 8080。
方法二：检查已停止但未清理的容器是否仍持有端口：docker ps -a | grep -E "(Exited|Created)" | grep 8080。
发现冲突容器后，先停掉再删干净：docker stop 容器ID && docker rm 容器ID。
注意：不要只删容器不删网络配置，残留的docker network有时也会导致端口“幽灵占用”。
验证真实监听状态并排除防火墙误报
有时候lsof或netstat显示端口空闲，但Hermes Agent启动仍失败——这很可能是防火墙拦截了bind系统调用，而非端口真被占。
第一步：临时关闭防火墙验证是否为干扰项。
Windows：以管理员身份运行PowerShell，执行Set-NetFirewallProfile -Profile Domain,Private,Public -Enabled False；
Linux（firewalld）：sudo systemctl stop firewalld；Ubuntu（ufw）：sudo ufw disable。
第二步：重启Hermes Agent网关，若此时能正常启动，说明防火墙策略是元凶。
第三步：立即恢复防火墙，并添加精准放行规则：
Windows：New-NetFirewallRule -DisplayName "HermesAgent-8080" -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow；
Linux：sudo firewall-cmd --permanent --add-port=8080/tcp && sudo firewall-cmd --reload。
【切勿长期关闭防火墙，放行规则必须限定协议为TCP、方向为Inbound、端口精确到单个数字】
