RUNBOOK / Python / pip
uv sync 索引 TLS 失败：证书链与锁文件边界
uv sync 访问包索引时出现 certificate verify failed 或连接超时。
故障现象与判断依据
最可能原因
uv 的索引访问同样依赖系统信任链和明确的 index 配置；不要以永久跳过 TLS 校验代替修复。
LOGERROR: Could not install packages due to an OSError:
HTTPSConnectionPool(host='pypi.org', port=443):
Read timed out. (read timeout=15)安全诊断
以下命令用于读取状态、验证解析或复现请求；先确认目标主机、权限与影响范围。命令中的占位符必须替换为当前环境的实际值。
READ / VERIFYpython -m pip install -vvv --timeout 60 --retries 5 <package>
HTTPS_PROXY=http://127.0.0.1:7897 HTTP_PROXY=http://127.0.0.1:7897 curl -Iv --connect-timeout 10 https://pypi.org/simple/推荐修复步骤
- 1在已配置本地 Clash 代理的受控 shell 中执行 uv sync -v，保留目标索引和失败阶段。
- 2仅通过已配置的本地代理使用 curl -Iv 验证同一索引的证书链与主机名。
- 3在受控配置中更新企业 CA 或索引地址后，重新执行 uv lock --check。
验证、限制与回滚
修复后的验证
uv sync 与 uv lock --check 均成功，锁文件没有非预期漂移。
风险提示与回滚
不要以关闭证书校验、删除全部缓存、无限重试、关闭防火墙或放宽到 chmod 777 来替代根因定位。任何配置变更前先保留原文件和校验结果；若验证失败，恢复该备份并重新采集日志。
可信来源与适用边界
参考来源Package indexes | uv ↗
package index configuration 此页将环境级案例与本 Runbook 的检查步骤分开呈现，不能把示例日志当作当前服务器的真实事件。
网络环境检测
当 DNS、代理链路、海外依赖源或下载超时已通过本页命令确认是网络层问题时，可继续核对独立网络服务；这不替代本地根因修复。
访问边界云官方网站 →具体套餐、价格、可用线路、服务内容及相关规则以官网当前页面为准；不会携带你在工作台输入的命令、日志、Token、IP 或邮箱。