agent space启动失败因8080端口被占，需四步解决：一、用netstat/lsof查pid并kill；二、修改application.yml中server.port为8081等空闲端口后重启；三、检查docker容器端口映射冲突并清理残留容器；四、临时关闭防火墙排除拦截干扰。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
Agent Space启动失败、卡在“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反向代理），你就得让Agent Space主动让路。
第一步：打开项目根目录下的application.yml文件。
第二步：找到server:区块下的port:字段，把值改成一个当前未被占用的端口，比如8081或9091。
第三步：保存文件后，在终端执行：agent-space restart。
第四步：验证是否生效：访问http://localhost:8081/actuator/health，返回HTTP 200即成功。
检查Docker容器端口映射冲突
如果你用Docker运行Agent Space，宿主机端口可能被容器内其他服务或旧容器残留映射占住。
方法一：查看所有正在运行的容器及其端口绑定：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。
验证真实监听状态并排除防火墙误报
有时候lsof或netstat显示端口空闲，但Agent Space启动仍失败——这很可能是防火墙拦截了bind系统调用，而非端口真被占。
临时关闭防火墙验证是否为干扰项。
Windows：以管理员身份运行PowerShell，执行Set-NetFirewallProfile -Profile Domain,Private,Public -Enabled False。
Linux：执行sudo ufw disable（若启用ufw）或sudo systemctl stop firewalld（若启用firewalld）。
