Troubleshooting
故障排查
按现象、日志、命令和修复路径组织的排障流程，优先定位真实原因。每篇都尽量保留现场判断、根因分层和回归验证。
从“看到什么错误”进入，而不是从概念目录里找答案。
LaoHand 的排障流程按真实故障现场组织，每篇文章都从某个具体错误现象出发，而不是从技术概念目录开始。24 个分类覆盖 Nginx、Docker、Kubernetes、Linux、Git、数据库（MySQL / PostgreSQL / Redis）、消息队列（Kafka / RabbitMQ / RocketMQ）、Elasticsearch、CI/CD（Jenkins / GitLab CI / GitHub Actions）和 AI 部署等开发者日常运维的绝大部分场景。
排障流程的核心设计原则是 "命令证据优先"——每篇文章都给出可在目标机器上直接复制的排查命令，并解释命令输出的含义和判断依据。避免在没有任何证据的情况下猜测根因，而是按"入口层 → 链路层 → 应用层 → 资源限制"的顺序逐层定位，最后通过回归验证确认修复生效。
如果你不确定当前问题属于哪个分类，可以直接使用搜索框或按分类筛选器缩小范围。每个排障流程都包含：适用场景说明、典型症状列表、排查前需要确认的事项、常见根因分层、分步诊断流程（含可复制命令）、风险提示、修复验证方法和后续预防建议。
全部排障文章
Certbot 证书自动续期失败排查
Certbot 自动续期 Let's Encrypt 证书失败时，用 certbot renew --dry-run 复现真实错误，覆盖 80 端口 HTTP-01 验证不通、Nginx 未放行 .well-known/acme-challenge、DNS TXT 记录未生效和 certbot.timer 未触发等常见根因。
FrontendCI 构建内存不足与进程被杀排查
CI 构建时出现 JavaScript heap out of memory、Killed 或 exit code 137，先区分 Node 堆内存不足与系统 OOM，再调整 NODE_OPTIONS=--max-old-space-size、Runner 内存和并发 job，覆盖 GitHub Actions、GitLab CI 和自建 Runner 场景。
CICDCI 缓存失效排查方法
CI 缓存不命中、每次构建都从零安装依赖时，先对比 restore/save 步骤打印的 cache key 是否变化，再检查缓存路径配置、runner OS 前缀和 gh cache list 中的实际条目，常见根因是 key 把易变内容算入或 restore-keys 顺序不对。
CICDCI 中 Docker 构建失败排查方法
CI 流水线 docker build 报错、层缓存失效或 permission denied 时，用 --progress=plain --no-cache 输出完整构建日志，检查 docker.sock 权限、buildx builder 和 Dockerfile 指令顺序，常见根因是 socket 无权限、上下文频繁变化或缓存未持久化。
FrontendCORS 预检 OPTIONS 请求失败排查
浏览器请求被 CORS 拦截、OPTIONS 预检返回 404/405 或缺少 Access-Control-Allow-Origin 头时，用 curl -X OPTIONS 复现预检，核对服务端允许的 Origin、Method、Headers 与 credentials 组合，注意带 Cookie 时不能用 * 通配。
Linuxcrontab 定时任务不执行的常见原因
crontab 定时任务到点不执行时，先看 /var/log/cron 或 syslog 确认任务是否触发，再确认 crond 服务状态、命令绝对路径、cron 最小 PATH 环境变量、脚本执行权限和 SHELL 差异等常见根因。
Networkcurl 使用代理连接超时排查
curl -x 通过 HTTP/SOCKS5 代理访问超时或 Failed to connect to proxy 时，用 curl -v 定位卡在代理还是目标站，区分 http 与 socks5/socks5h 协议、代理端 DNS 解析和 NO_PROXY 环境变量是否排除了目标域名。
NetworkDNS 解析失败排查：NXDOMAIN、SERVFAIL 和超时
域名解析出现 NXDOMAIN、SERVFAIL、Temporary failure in name resolution 或解析慢时，用 dig、dig @1.1.1.1、dig +trace、resolvectl status 交叉对比本机解析器、公共 DNS 和权威 DNS，快速定位问题出在哪一层。
DockerDocker Compose 容器反复重启排查
Docker Compose 容器一直 Restarting 时，用 docker compose ps 看退出码和重启次数，读取失败服务的历史日志、docker compose config 展开环境变量与端口卷，常见根因是启动命令失败、环境变量缺失、端口冲突或 depends_on 未等依赖 ready。
DockerDocker 镜像清理与瘦身
Docker 镜像和构建缓存占满磁盘时，用 docker system df 查看整体占用，按 dangling 中间层、未使用镜像、构建缓存的顺序渐进清理，避免直接 docker system prune -a 误删仍被停止容器引用的镜像。
DockerDocker 镜像拉取失败排查：超时、证书和架构不匹配
docker pull 出现 TLS handshake timeout、manifest unknown、no matching manifest 或 x509 unknown authority 时，先按错误文本区分网络、Registry 认证、镜像 tag 不存在或 CPU 架构不匹配，再针对性配置代理、镜像源、docker login 或私有仓库 CA。
DockerDocker 容器网络不通排查
Docker 容器之间 ping/curl 不通、DNS 无法解析容器名或访问不了宿主机服务时，用 docker network inspect 查看网络成员，确认容器是否在同一自定义 network，Docker 内置 DNS 只在自定义网络生效，宿主机访问用 host.docker.internal。