网络与超时Read timed out
pip install Read timed out：从 DNS 到镜像的系统化排障
安装 requests、torch 或私有依赖时卡在 Read timed out，重试后仍失败。
FXXT技术栈Linux、Docker、Nginx 与后端运维打开交互工作台RUNBOOK DIRECTORY / 38 PUBLISHED
按运行环境浏览运维排障手册
先锁定系统、工具或运行环境，再按错误特征和故障阶段进入可验证、可回滚的诊断路径。
- 已发布
- 38
- 运行环境
- 17
- 内容状态
- 已验证
ENVIRONMENT
Python / pip
网络与超时Connection reset by peer
pip 下载 Connection reset by peer：代理与缓存排查
包下载到一半被重置，CI 环境尤为常见。
证书与信任CERTIFICATE_VERIFY_FAILED
pip SSL CERTIFICATE_VERIFY_FAILED：证书链和系统时间修复
pip 报 SSL 证书校验失败，临时 --trusted-host 看似能绕过。
仓库与依赖No matching distribution found
pip No matching distribution found：平台标签与 Python 版本
明明存在的包却提示没有匹配版本。
网络与超时私有 PyPI 访问超时
私有 PyPI 访问超时：索引优先级与凭据隔离
公司私有包与公共包混用时，安装速度慢或频繁 401。
网络与超时pipx install 失败
pipx install 失败：共享虚拟环境与解释器路径
pipx 安装命令行工具时提示虚拟环境创建失败或找不到 Python。
网络与超时uv sync 索引 TLS 失败
uv sync 索引 TLS 失败：证书链与锁文件边界
uv sync 访问包索引时出现 certificate verify failed 或连接超时。
ENVIRONMENT
Homebrew
网络与超时Homebrew 卡在 Updating Homebrew
Homebrew 卡在 Updating Homebrew：安全跳过与恢复更新
brew install 长时间停在 Updating Homebrew，终端没有明显进度。
网络与超时RPC failed
brew update Git RPC failed：仓库远端与网络 MTU
Updating Homebrew 后出现 RPC failed、early EOF 或连接超时。
网络与超时Homebrew bottle 下载慢
Homebrew bottle 下载慢：CDN、镜像与缓存策略
公式更新很快，但安装时 bottle 下载只有几 KB/s。
ENVIRONMENT
Ubuntu / apt
网络与超时Temporary failure in name resolution
Ubuntu apt Temporary failure in name resolution：DNS 恢复清单
apt update 提示 Temporary failure in name resolution。
网络与超时Ubuntu Release file 超时
Ubuntu Release file 超时：源列表与 IPv6 优先级
apt update 在某个镜像站等待或连接超时。
证书与信任NO_PUBKEY
apt NO_PUBKEY：仓库签名密钥与 signed-by 修复
apt update 返回 NO_PUBKEY 或仓库签名无法验证。
仓库与依赖404 Release
apt update 404 Release：发行版代号与归档源
升级后 apt update 对 Release 文件返回 404。
ENVIRONMENT
CentOS / yum
网络与超时CentOS yum/dnf 仓库连接超时
CentOS yum/dnf 仓库连接超时：baseurl 与 DNS
yum makecache 或 dnf update 无法连接 mirrorlist。
ENVIRONMENT
CentOS / dnf
证书与信任Failed to download metadata
DNF metadata download 失败：代理、签名与缓存
Failed to download metadata 或 GPG 校验异常同时出现。
ENVIRONMENT
Docker
网络与超时i/o timeout
Docker Build 拉取基础镜像失败：registry 网络分层排查
docker build 在 FROM 阶段报 i/o timeout 或 TLS handshake timeout。
网络与超时Docker registry token 获取失败
Docker registry token 获取失败：鉴权端点与企业代理
拉取公开镜像却在 token 服务返回超时或 401。
网络与超时TLS handshake timeout
Podman 拉取镜像 TLS 失败：registries.conf 与证书目录
podman pull 在私有 Registry 报 x509 或 TLS handshake timeout。
网络与超时docker compose pull 失败
docker compose pull 失败：服务范围、依赖与镜像拉取边界
Compose 项目中某个服务拉取失败，直接执行全量 pull 时难以判断是哪个镜像或依赖发生问题。
ENVIRONMENT
Rust / Cargo
仓库与依赖Cargo crates.io 下载缓慢
Cargo crates.io 下载缓慢：稀疏索引与网络配置
cargo build 更新索引或下载 crate 极慢。
网络与超时Cargo git dependency 超时
Cargo git dependency 超时：SSH、HTTPS 与锁文件
普通 crate 可下载，只有 git 依赖超时或认证失败。
ENVIRONMENT
Go Modules
网络与超时Go Modules 下载慢
Go Modules 下载慢：GOPROXY、GOSUMDB 与私有模块
go mod download 超时，公共与私有模块混合时更明显。
网络与超时Go sumdb 超时或 410
Go sumdb 超时或 410：校验服务与离线构建策略
模块已从代理获取，但校验数据库请求失败。
ENVIRONMENT
Network
网络与超时包管理器反复超时
包管理器反复超时：识别出口 QoS 与强制重置
pip、brew、apt、Docker 都偶发失败，换源只能短暂改善。
ENVIRONMENT
CI / SRE
网络与超时CI 依赖安装不稳定
CI 依赖安装不稳定：超时预算、重试与可观测性
本地正常、CI 间歇性失败，导致发布被阻塞。
ENVIRONMENT
Git / SSH
网络与超时RPC failed
git clone TLS 超时：代理变量、CA 与 HTTP 追踪
git clone HTTPS 地址时卡住、报 SSL certificate problem 或 RPC failed。
网络与超时handshake timeout
SSH handshake timeout：路由、端口与 known_hosts
ssh 或 Git SSH 远端在握手前超时。
仓库与依赖Git LFS 文件显示为 pointer
Git LFS 文件显示为 pointer：初始化与仓库对象边界
仓库中的大文件显示为 Git LFS pointer 文本，而不是预期的二进制内容。
ENVIRONMENT
systemd
服务与运行时service failed
systemctl service failed：退出码、依赖与 journal
服务启动后立刻 failed，只有 systemctl 状态摘要。
服务与运行时systemctl reset-failed
systemctl reset-failed：先修复根因再清除失败状态
systemctl status 显示 unit 仍处于 failed，修复配置后需要区分服务是否已恢复与 failed 状态是否已重置。
ENVIRONMENT
Nginx / TLS
服务与运行时upstream connect
Nginx upstream connect 失败：监听地址与反向代理分层
Nginx 返回 502，error.log 出现 connect() failed 或 upstream timed out。
证书与信任curl/OpenSSL 证书校验错误
curl/OpenSSL 证书校验错误：完整链、SNI 与系统 CA
curl 报 SSL certificate problem，OpenSSL 显示 verify error。
网络与超时wget 下载超时
wget 下载超时：环境代理与 DNS 对照
wget 通过自动代理或环境变量下载文件时反复超时。
ENVIRONMENT
Conda
仓库与依赖conda env create 使用错误环境文件
conda env create 使用错误环境文件：--file、名称与路径优先级
在非项目目录执行 conda env create 后，环境没有按预期名称创建，或读取了错误的 environment.yml。
ENVIRONMENT
Kubernetes
权限与认证Kubernetes ImagePullBackOff
Kubernetes ImagePullBackOff：私有 Registry 凭据与命名空间
Pod 拉取私有镜像失败，describe 中出现 ImagePullBackOff、鉴权失败或找不到 imagePullSecrets。
ENVIRONMENT
Ollama
网络与超时ollama pull 下载模型卡住
ollama pull 下载模型卡住：状态流、模型名与本地服务核查
执行 ollama pull 后模型没有完成下载，或调用本地拉取 API 时无法判断下载是否仍在进行。
ENVIRONMENT
Node.js
服务与运行时Node.js EADDRINUSE
Node.js EADDRINUSE：端口已被占用的安全定位与恢复
Node 服务启动时出现 listen EADDRINUSE: address already in use，或因已有进程监听端口而无法绑定。