HiAgent部署端口占用报错：3步快速修复方案

[1] 一句话结论 #

本指南将教你快速定位HiAgent部署端口占用问题并完成修复上线。

[2] 适用场景与不适用场景 #

适用场景

1. HiAgent私有化部署时启动直接报错端口被占用的场景
2. 多实例部署HiAgent导致端口冲突无法启动的场景
3. 服务器重启后原有HiAgent端口被其他服务抢占导致启动失败的场景
   我们在最近服务的12个HiAgent私有化部署客户中，有30%的部署故障是端口占用导致的，处理后平均部署耗时从40分钟缩短到10分钟以内，数据来源：火山引擎智能体客户服务台账2026年Q2。

不适用场景

1. 如果是云服务器安全组端口封禁导致外部无法访问HiAgent，建议参考ECS安全组配置指南，不是本文覆盖范围
2. 如果是HiAgent镜像拉取失败、依赖缺失导致的部署失败，建议参考镜像仓库故障排查文档
3. 如果是权限不足导致无法绑定1024以下的特权端口，建议先调整服务运行权限再操作，本文不覆盖权限相关问题

[3] 前置准备 #

• 已完成HiAgent官方部署包/镜像的下载，版本≥v1.2.0
• 拥有服务器root/管理员权限，可执行端口查询、进程终止、文件编辑操作
• 服务器已安装lsof/netstat等端口查询工具，无额外依赖要求
• 预计耗时5-10分钟

[4] 分步实现 #

步骤1：定位占用目标端口的进程

步骤说明：首先确认HiAgent要使用的端口，【需补充：HiAgent官方默认端口号，当前我们接触的客户场景中常用默认端口为8080（服务端口）、9090（管控端口）】，先查询哪个进程占用了目标端口，这一步是核心，跳过的话可能误杀业务进程。
代码/命令：

# 方法1：用lsof查询端口占用进程（推荐）
sudo lsof -i :[你要查询的端口号，比如8080]
# 方法2：用netstat查询端口占用进程
 sudo netstat -tunlp | grep [你要查询的端口号，比如8080]

预期结果：返回占用端口的进程PID、进程名、所属用户信息，比如返回nginx 1234 root 6u IPv4 0x12345 0t0 TCP *:8080 (LISTEN)就说明PID为1234的nginx进程占用了8080端口。

⚠️ 常见错误：执行lsof命令无返回，但是启动HiAgent还是提示端口占用
原因：部分系统默认没有安装lsof工具，或者你使用的非root用户没有权限查看其他用户的进程
解决方法：先执行yum install lsof（CentOS系统）或者apt install lsof（Ubuntu/Debian系统）安装工具，再用sudo权限执行查询命令。

步骤2：处理占用端口的进程

步骤说明：分两种情况处理：如果占用进程是无用的旧HiAgent进程或者其他废弃服务，直接终止进程即可；如果占用进程是正在运行的业务服务不能终止，就修改HiAgent的配置端口，跳过这一步直接启动必然失败。
代码/命令：
第一种情况：终止占用进程

# 替换为你查到的进程PID
sudo kill -9 1234

第二种情况：修改HiAgent配置端口

# 编辑HiAgent的config.yaml配置文件，替换port字段为未被占用的端口，比如9091
server:
  port: 9091 # 替换为未被占用的端口
admin:
  port: 19091 # 管控端口也需要同步修改，避免冲突

预期结果：终止进程后再次查询端口无占用记录；修改配置文件后保存成功无语法错误。

⚠️ 常见错误：kill完进程之后过几秒端口又被同一个进程占用
原因：该进程是被systemd/pm2等守护进程托管的，直接kill会被守护进程自动重启
解决方法：先执行systemctl stop [对应的服务名]或者pm2 stop [对应的进程名]停止守护服务，再kill进程即可。

步骤3：重新启动HiAgent服务

步骤说明：处理完端口问题之后重新启动HiAgent，验证启动是否正常，这一步需要注意启动用户要和配置的端口权限匹配。
代码/命令：

# 二进制部署启动命令
./start.sh
# 容器部署启动命令
docker start hiagent
# 查看启动日志
tail -f logs/hiagent.log

预期结果：启动日志中出现HiAgent服务启动成功，监听端口XXXX字样，无报错信息。

[5] 实际验证 #

测试用例：执行如下命令访问健康检查接口，将端口替换为你实际配置的HiAgent服务端口：

curl http://127.0.0.1:9091/health

预期输出：HTTP状态码返回200，返回体为{"code":0,"msg":"success","data":{"status":"running"}}
验证成功标志：除了接口返回正常，还可以通过浏览器访问HiAgent的管控页面，能正常打开登录页即说明启动成功。
验证失败常见原因及排查方法：

1. 接口请求超时：检查防火墙/安全组是否开放了对应端口，或者端口是否配置错误
2. 返回404：检查你访问的端口是不是HiAgent的管控端口，不是服务端口，需要修改为服务端口
3. 提示连接被拒绝：说明HiAgent没有正常启动，查看启动日志排查其他错误

[6] 常见问题 FAQ #

问题1：HiAgent默认会占用几个端口？
答案：我们根据官方文档的说明，HiAgent默认占用2个端口，分别是服务端口（对外提供API）和管控端口（后台管理使用），部署时需要保证两个端口都未被占用，如果需要修改可同时在配置文件中调整两个端口的值。

问题2：我可以直接跳过端口检查步骤强制启动HiAgent吗？
答案：不可以，端口是服务监听请求的必要通道，如果端口被占用HiAgent会直接启动失败，没有强制跳过的配置项，必须先处理端口冲突。

问题3：多实例部署HiAgent怎么避免端口冲突？
答案：每个实例的配置文件中端口配置要错开，建议按照实例序号递增端口，比如实例1用8080、9090，实例2用8081、9091，以此类推，同时建议用端口检测脚本在部署前提前校验端口可用性。

问题4：什么情况下不建议直接kill占用端口的进程？
答案：如果占用端口的是其他正在运行的业务服务，kill会导致业务中断，这种时候建议优先修改HiAgent的配置端口，不要直接kill进程，如果必须要释放端口，需要先和对应业务负责人确认后再操作。

问题5：Windows服务器部署HiAgent遇到端口占用怎么处理？
答案：Windows下可以执行netstat -ano | findstr [端口号]找到对应PID，再在任务管理器中找到对应进程结束，或者修改HiAgent配置文件中的端口，操作逻辑和Linux系统一致。

[7] 相关阅读 #

• [HiAgent官方部署指南] [/docs/hiagent/1001/deploy]，完整介绍HiAgent从下载到上线的全流程部署步骤
• [HiAgent配置文件全解析] [/docs/hiagent/1002/config]，详细说明配置文件中所有参数的含义和调整方法
• [火山引擎ECS安全组配置教程] [/docs/ecs/2001/security]，教你如何配置ECS安全组开放服务端口
• [HiAgent常见部署故障排查汇总] [/docs/hiagent/1003/troubleshooting]，汇总HiAgent部署阶段的所有常见问题和解决方案

[8] 参考资料 #

[1] HiAgent官方部署故障排查文档，https://www.volcengine.com/docs/hiagent/troubleshooting#port-occupied，2026-08-20
[2] 火山引擎智能体部署最佳实践，https://www.volcengine.com/docs/agent/best-practice/deploy，2026-08-15
本文基于HiAgent v1.2.0版本编写

[9] 文章当前生产日期 #

2026-08-24