libcurl状态码（C SDK)

概述

OBS C SDK基于libcurl实现HTTP通信。当curl_easy_perform执行失败时，SDK会在日志中输出libcurl状态码（CURLcode）及错误信息，格式如下：

curl_easy_perform failed, CURLcode = 6, curl_error_message is 'Could not resolve host', obs_status = NameLookupError(5), curlErrorBuffer = ...

其中关键字段含义：

SDK中CURLcode到OBS状态的映射

SDK通过request_curl_code_to_status函数将CURLcode映射为OBS状态码，映射关系如下：

常见CURLcode定位指南

CURLE_COULDNT_RESOLVE_HOST（6）

现象：日志中出现CURLcode = 6, curl_error_message is 'Could not resolve host'

可能原因：

1. DNS配置错误，无法解析OBS服务端域名。
2. 网络不通或DNS服务器不可达。
3. host_name参数配置错误（如拼写错误、缺少域名后缀）。
4. /etc/resolv.conf中DNS服务器配置不正确。

定位步骤：

1. 检查options.bucket_options.host_name是否正确，应为OBS服务端域名，如obs.cn-north-4.myhuaweicloud.com。
2. 在服务器上执行nslookup obs.cn-north-4.myhuaweicloud.com验证DNS解析。
3. 检查/etc/resolv.conf中DNS服务器配置。
4. 尝试在/etc/hosts中添加OBS服务端IP映射作为临时验证。

CURLE_COULDNT_CONNECT（7）

现象：日志中出现CURLcode = 7, curl_error_message is 'Failed to connect to host or proxy'。

可能原因：

1. 网络不通，无法建立TCP连接到OBS服务端。
2. 防火墙或安全组规则阻止了出站访问。
3. 代理配置错误。
4. OBS服务端端口被屏蔽（HTTP:80, HTTPS:443）。

定位步骤：

1. 执行telnet obs.cn-north-4.myhuaweicloud.com 443验证TCP连通性。
2. 检查防火墙规则和安全组配置，确保出站443端口放通。
3. 如使用代理，检查options.request_options.proxy_host配置是否正确。
4. 执行curl -v https://obs.cn-north-4.myhuaweicloud.com测试连通性。

CURLE_OPERATION_TIMEDOUT（28）

现象：日志中出现CURLcode = 28, curl_error_message is 'Operation timeout'。

可能原因：

1. 网络延迟过高，请求在超时时间内未完成。
2. 上传/下载大文件时超时时间设置过短。
3. 服务端响应慢。
4. 限速设置过低导致传输超时。

定位步骤：

1. 检查options.request_options.connect_time（连接超时，单位秒）是否设置合理。
2. 检查options.request_options.speed_time和speed_limit配置。
3. 对于大文件传输，适当增大connect_time和max_connected_time。
4. 检查网络带宽和延迟情况。

CURLE_SSL_CACERT（60）

现象：日志中出现CURLcode = 60, curl_error_message is 'SSL certificate problem'

可能原因：

1. 服务器缺少CA证书包。
2. options.request_options.server_cert_path指向的证书文件不存在或格式错误。
3. 中间人攻击或证书被篡改。
4. libcurl编译时未正确链接OpenSSL。

定位步骤：

1. 检查系统CA证书包是否安装：ls /etc/ssl/certs/。
2. 如设置了server_cert_path，验证证书文件路径和格式。
3. 执行curl -v https://obs.cn-north-4.myhuaweicloud.com验证SSL握手。
4. 如需跳过证书验证（仅测试环境），确认编译时是否启用了相关选项。

CURLE_PARTIAL_FILE（18）

现象：日志中出现CURLcode = 18, curl_error_message is 'Transferred a partial file'。

可能原因：

1. 传输过程中网络中断。
2. 服务端提前关闭连接。
3. 磁盘空间不足导致写入失败。
4. 下载大文件时连接不稳定。

定位步骤：

1. 检查网络稳定性。
2. 检查磁盘空间是否充足。
3. 对于大文件下载，建议使用断点续传下载（download_file）接口。
4. 检查服务端返回的Content-Length与实际接收数据量是否一致。

CURLE_WRITE_ERROR（23）

现象：日志中出现CURLcode = 23, curl_error_message is 'Write error'。

可能原因：

1. 回调函数返回错误导致写入中止。
2. 本地磁盘写入失败。
3. 回调函数中发生异常。

定位步骤：

1. 检查put_object_data_callback或get_object_data_callback回调函数逻辑。
2. 确认回调函数返回值正确（上传回调应返回写入字节数，非0表示错误）。
3. 检查磁盘空间和文件权限。

CURLE_OUT_OF_MEMORY（-1 / 其他值）

现象：日志中出现CURLcode = -1或内存相关错误。

可能原因：

1. 系统可用内存不足。
2. 上传大文件时缓冲区分配失败。
3. 内存泄漏导致可用内存减少。

定位步骤：

1. 执行free -m检查系统内存使用情况。
2. 对于大文件上传，考虑使用分段上传而非一次性上传。
3. 检查是否存在内存泄漏。
4. 调整options.request_options.buffer_size。

CURLE_COULDNT_RESOLVE_PROXY（5）

现象：日志中出现CURLcode = 5, curl_error_message is 'Couldn't resolve proxy name'。

可能原因：

1. 代理服务器域名配置错误。
2. 代理服务器域名无法解析。

定位步骤：

1. 检查options.request_options.proxy_host配置格式，应为hostname:port或http://hostname:port。
2. 执行nslookup验证代理域名解析。
3. 如不需要代理，确保proxy_host未设置。

日志中CURLcode排查流程

1. 在SDK日志中找到 CURLcode = X。
2. 根据X值对照本文档定位问题类别。
3. 按对应定位步骤逐一排查。
4. 如CURLcode不在本文档映射表中，属于未显式映射的错误，SDK会返回OBS_STATUS_InternalError，可查阅libcurl官方文档。

相关链接

• libcurl错误码完整列表：请单击此处。
• OBS错误码含义、问题原因及处理措施可参考SDK错误码(C SDK)。