端口被占用导致HermesAgent Gateway启动失败，需依次排查：一、定位并终止占用进程；二、修改application.yml中server.port为可用端口；三、检查Docker容器端口映射冲突；四、验证真实监听状态并排除防火墙误报。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试启动HermesAgent Gateway服务，但控制台提示端口被占用，则说明配置中指定的监听端口（如8080、9090等）正被其他进程独占绑定，导致网关无法完成TCP监听初始化。以下是解决此问题的步骤：
一、定位并终止占用端口的进程
该方法直接解除端口冲突，适用于已确认端口未被关键服务使用且可安全释放的场景。操作前需确保目标进程非系统必需或业务核心服务。
1、在终端中执行命令查看监听目标端口的进程：netstat -ano | findstr :8080（Windows）或 lsof -i :8080（Linux/macOS）。
2、从输出结果中提取PID（进程标识符）列对应的数字编号。
3、执行命令强制结束该进程：taskkill /PID 12345 /F（Windows）或 kill -9 12345（Linux/macOS）。
4、重新运行hermes gateway start命令，观察日志是否出现“Started HermesAgentGateway”字样。
二、修改网关配置文件中的监听端口
该方法避免终止其他进程，通过变更HermesAgent自身绑定端口实现共存，适用于端口占用方为不可中断服务（如Nginx、数据库）的情形。
1、打开HermesAgent项目根目录下的application.yml文件。
2、查找server.port字段，将其值修改为当前系统中未被占用的端口，例如8081或9091。
3、保存文件后，在终端执行hermes gateway restart命令使配置生效。
4、使用curl http://localhost:8081/actuator/health验证服务是否返回HTTP 200响应。
三、检查Docker容器端口映射冲突
该方法针对容器化部署场景，当HermesAgent以Docker方式运行时，宿主机端口可能被其他容器的-p参数映射所抢占。
1、执行docker ps -a命令列出所有容器及其端口映射关系。
2、查找Ports列中包含8080->或9090->的容器记录。
3、若该容器非必要，执行docker stop 容器ID与docker rm 容器ID彻底移除。
4、若需保留该容器，修改HermesAgent的docker run命令，将-p参数后的宿主机端口更换为未使用端口，例如-p 8082:8080。
四、验证端口实际监听状态并排除防火墙拦截误报
部分安全软件会模拟端口占用行为以实施拦截，导致日志显示“Address already in use”但实际无进程绑定，需通过底层协议探测确认真实状态。
1、执行netstat -tuln | grep :8080（Linux/macOS）或 netstat -ano | findstr :8080（Windows），确认LISTEN状态行是否存在。
2、若无LISTEN输出但错误仍存在，临时禁用Windows Defender防火墙或执行sudo ufw disable（Ubuntu）排除干扰。
3、再次启动网关，若成功则说明是防火墙策略伪装为端口占用，需转至防火墙放行规则配置步骤。
4、使用telnet localhost 8080测试本地连接可达性，响应“Connected”即表示端口已就绪。
