Skip to content

故障排查 ​

先看哪里 ​

用户反馈打不开
   ├─ curl -I https://域名/          → 状态码?
   ├─ nginx -t                        → 配置是否合法
   ├─ tail /var/log/nginx/error.log   → 有没有权限/路径错误
   ├─ systemctl status nginx          → 进程是否在跑
   └─ df -h                           → 磁盘是否满了

常见问题 ​

1. 访问子域跳到主站 ​

现象:打开 docs.emphant.com 直接跳到 emphant.com。

原因:主站 server 是 default_server,子域 vhost 不存在或 server_name 写错。

排查:

bash
nginx -T | grep -A3 "server_name docs.emphant.com"

处理:./deploy.sh sites 重新下发子域配置;确认 /etc/nginx/conf.d/emphant-subdomains.conf 存在。

2. 文档页 404,但首页正常 ​

现象:/guide/quick-start 打不开,/guide/quick-start.html 能打开。

原因:VitePress 开了 cleanUrls,产物没有无扩展名文件,必须靠 try_files 补 .html。

处理:

nginx
location / { try_files $uri $uri.html $uri/ =404; }

同理,随笔站的 $uri.html 不能漏。

3. 手机访问工具页没跳到 /m/ ​

排查顺序:

  1. 看 UA 是否被 map 命中:curl -A "iPhone" -I https://emphant.com/text/word-counter/;
  2. 浏览器里是否已有 view_pref=pc cookie(30 天);
  3. 该工具是否在 $is_desktop_only_page 名单里。
bash
curl -A "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) Mobile" \
  -I https://emphant.com/text/word-counter/
# 期望 302,Location: /m/#/t/text/word-counter

4. 发布后还是旧页面 ​

原因验证
浏览器缓存 HTML强制刷新 / 无痕窗口
CDN 缓存curl -I 看 age / x-cache
发布到了旧目录ls -la /var/www/emphant/index.html 看时间
rsync 没覆盖看发布日志有没有 rsync 报错

首页设置了 Cache-Control: no-cache,正常情况下不应该出现旧页面。

5. 图片 / 资源 404 ​

  • pc-web 的资源在 dist/assets/,路径以 /assets/ 开头;
  • mobile-web 用 base='./',资源路径是相对的,不能用绝对域名拼;
  • 如果手工拷了 dist 但漏了 assets/,页面会白屏。

6. 证书错误 ​

见 HTTPS 证书 的「常见问题」。

7. 发布脚本失败 ​

报错原因处理
缺少 paramiko本机没装pip3 install paramiko
Authentication failed密码/账号变更用 SSH_PASS 环境变量传入
rsync: command not found服务器没装 rsyncapt install rsync
Permission denied目标目录权限确认以 root 发布
nginx -t 失败模板写错脚本已自动回滚,看输出修模板

8. 磁盘满 ​

bash
df -h
du -sh /var/www/.releases /var/log /var/lib/docker 2>/dev/null

常见占用:.releases 旧备份、nginx 日志、certbot 归档。清理前先确认备份策略。

快速健康检查脚本 ​

bash
#!/usr/bin/env bash
set -u
for u in https://emphant.com/ \
         https://emphant.com/text/word-counter/ \
         https://emphant.com/sitemap.xml \
         https://docs.emphant.com/ \
         https://blog.emphant.com/ \
         https://blog.emphant.com/rss.xml; do
  code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 10 "$u")
  printf '%-52s %s\n' "$u" "$code"
done
nginx -t && systemctl is-active nginx

全部 200 且 nginx active 即可认为站点正常。

拿到用户反馈时先问 ​

  1. 访问的是哪个域名、哪个页面?
  2. 手机还是电脑?什么浏览器?
  3. 有没有截图 / 报错文字?
  4. 是突然打不开,还是一直如此?

有了这四条,绝大多数问题能直接定位到 vhost、缓存、UA 或某次发布的产物。

文档随仓库一起更新,站点内容全部在浏览器本地运行。