主题
故障排查
先看哪里
用户反馈打不开
├─ 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/
排查顺序:
- 看 UA 是否被
map命中:curl -A "iPhone" -I https://emphant.com/text/word-counter/; - 浏览器里是否已有
view_pref=pccookie(30 天); - 该工具是否在
$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-counter4. 发布后还是旧页面
| 原因 | 验证 |
|---|---|
| 浏览器缓存 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 | 服务器没装 rsync | apt 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 即可认为站点正常。
拿到用户反馈时先问
- 访问的是哪个域名、哪个页面?
- 手机还是电脑?什么浏览器?
- 有没有截图 / 报错文字?
- 是突然打不开,还是一直如此?
有了这四条,绝大多数问题能直接定位到 vhost、缓存、UA 或某次发布的产物。