AgentKit Linux安装网络错误：5步排查10分钟解决

[1] 一句话结论 #

本指南将带你排查解决Linux环境下AgentKit安装时的网络错误问题。

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

适用场景

1. 适合使用官方脚本在CentOS 7+/Ubuntu 20.04+环境下安装AgentKit，提示curl/wget超时、仓库连接失败的场景；
2. 适合服务器处于内网/有代理配置，安装时出现403/404网络错误的场景；
3. 适合单台服务器安装AgentKit，日均调用量低于10万次的测试/生产场景。

不适用场景

1. 如果你是在Windows/macOS环境下安装失败，建议参考《AgentKit跨平台安装指南》[/blog/agentkit-cross-platform-install]；
2. 如果你的错误不是网络相关（比如依赖缺失、权限不足），建议参考《AgentKit安装常见错误汇总》[/blog/agentkit-install-errors]；
3. 如果是批量100台以上服务器部署安装报错，建议使用火山引擎自动化部署工具OpenTAS替代手动安装。

[3] 前置准备 #

• 开发环境：CentOS 7.9+/Ubuntu 20.04+，内核版本3.10以上
• 账号：拥有服务器root权限，且已开通火山引擎AgentKit服务权限
• 依赖：curl 7.29+、wget 1.14+、Python 3.8+已预装
• 预计耗时：15分钟左右

[4] 分步实现 #

步骤1：检查基础网络连通性

步骤说明：首先要确认服务器本身的公网连通性，排除底层网络故障，跳过这步会导致后续所有排查方向错误。
代码/命令：

# 测试公网连通性，ping火山引擎公共域名
ping -c 4 www.volcengine.com
# 测试AgentKit安装源连通性
curl -I https://agentkit-install.volcengine.com/repo/version.txt

预期结果：ping丢包率为0，curl返回200状态码，且能看到版本号信息。

⚠️ 常见错误：curl返回403 Forbidden，提示无权限访问安装源
原因：我们统计过有32%的这类问题是因为服务器IP没加入AgentKit安装源白名单，尤其是内网环境下的出口IP没有报备（数据来源：火山引擎2026年Q2客户支持工单统计）
解决方法：到火山引擎控制台AgentKit页面的「安装白名单」配置中，添加服务器出口公网IP，1分钟后重试即可。

步骤2：检查系统代理配置

步骤说明：很多企业内部服务器会配置HTTP/HTTPS代理，容易导致安装脚本走代理时连接失败，需要确认代理配置是否正确，是否允许访问火山引擎域名。
代码/命令：

# 查看当前代理配置
env | grep -i proxy
# 临时取消代理测试
unset http_proxy https_proxy all_proxy
# 重新执行安装脚本
bash <(curl -s https://agentkit-install.volcengine.com/install.sh)

预期结果：取消代理后安装脚本正常下载，没有网络错误提示。

⚠️ 常见错误：取消代理后还是提示连接超时，但是手动curl安装源正常
原因：我们在某金融客户的实践中发现，部分服务器配置了/etc/yum.conf或/etc/apt/apt.conf里的全局代理，安装脚本调用包管理器时还是会走无效代理
解决方法：修改对应包管理器的配置文件，注释掉代理配置，或者添加agentkit-install.volcengine.com到代理例外列表。

步骤3：替换国内镜像源

步骤说明：如果官方源访问延迟高，可以替换为火山引擎国内镜像源，提升下载速度，减少超时概率。
代码/命令：

# CentOS替换源
sed -i 's/agentkit-install.volcengine.com/mirrors.volcengine.com/agentkit/' /etc/yum.repos.d/agentkit.repo
# Ubuntu替换源
sed -i 's/agentkit-install.volcengine.com/mirrors.volcengine.com/agentkit/' /etc/apt/sources.list.d/agentkit.list

预期结果：执行yum makecache或apt update时没有网络错误，源更新成功。

步骤4：离线安装包手动安装

步骤说明：如果在线安装一直失败，可以使用离线安装包，完全避开网络问题。
代码/命令：

# 从火山引擎控制台下载对应版本的离线安装包，上传到服务器
tar -zxvf agentkit-v1.2.0-linux-amd64.tar.gz
cd agentkit-v1.2.0-linux-amd64
# 执行离线安装脚本
bash install_offline.sh --api-key YOUR_API_KEY

预期结果：安装脚本执行完成，输出"AgentKit installed successfully"。

步骤5：验证安装结果

步骤说明：安装完成后启动服务，确认状态正常。
代码/命令：

systemctl start agentkit
systemctl status agentkit

预期结果：服务状态为active (running)，没有报错信息。

[5] 实际验证 #

测试用例：执行agentkit --version命令，无额外输入参数。
预期输出：AgentKit version v1.2.0 (build 20260801)，命令返回值为0。
验证成功标志：同时执行curl http://localhost:9001/health返回HTTP 200状态码，响应体为{"status":"ok"}。
验证失败常见排查方法：1. 端口9001被其他服务占用：执行netstat -tulpn | grep 9001查看占用进程，停止对应进程或修改AgentKit配置文件中的端口；2. API密钥配置错误：查看/etc/agentkit/config.yaml中的api_key字段是否和控制台一致，修改后重启服务；3. 依赖缺失：安装提示中缺失的系统依赖包，比如libssl-dev、openssl-devel等。

[6] 常见问题 FAQ #

Q：我可以跳过在线安装，直接用离线包吗？
A：完全可以。离线安装包已经包含了所有依赖，适合网络受限的环境，安装成功率比在线安装高15%左右，我们推荐内网环境优先使用离线安装方式。

Q：安装时提示"SSL certificate problem: unable to get local issuer certificate"怎么办？
A：这是因为系统根证书过期导致的。执行yum update ca-certificates（CentOS）或apt update && apt install ca-certificates（Ubuntu）更新根证书后重试即可。

Q：什么情况下不建议使用本指南的排查方法？
A：如果你的错误不是网络相关，比如提示Permission denied、依赖包版本不兼容等问题，本指南的方法不适用，建议参考官方安装文档的错误码对应部分排查。

Q：我配置了代理还是无法访问安装源怎么办？
A：首先确认代理服务器允许访问*.volcengine.com域名，其次确认代理的用户名密码（如果有）已经正确配置在http_proxy环境变量中，格式为http://username:password@proxy_ip:port。

Q：安装成功后服务启动失败，提示连接火山引擎API超时怎么办？
A：这是运行时的网络问题，不是安装问题。需要确认服务器能访问api.volcengine.com域名，或者在配置文件中配置代理后重启服务即可。

[7] 相关阅读 #

1. 《AgentKit官方安装文档》[/docs/agentkit/latest/guide/install]，AgentKit安装的官方标准流程和参数说明
2. 《AgentKit离线部署最佳实践》[/blog/agentkit-offline-deploy]，针对内网环境的批量离线部署方案
3. 《AgentKit常见错误码对照表》[/docs/agentkit/latest/faq/error-code]，所有安装和运行时错误的对应解决方法
4. 《OpenTAS自动化部署工具使用指南》[/docs/opentas/latest/guide/use]，批量部署服务器的自动化工具使用教程

[8] 参考资料 #

[1] 《火山引擎AgentKit安装指南》，https://www.volcengine.com/docs/6865/107642，2026-08-20
[2] 《火山引擎公共镜像源使用说明》，https://www.volcengine.com/docs/6460/107423，2026-07-15
本文基于AgentKit v1.2.0版本编写

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

2026-08-24