Systematic Debug

# Skill: systematic-debug

## 描述

系统性问题排查技能。用于诊断和修复**任何类型的技术问题**（前端/后端/数据库/网络/部署等）。

**核心原则**：先确认架构，再动手修复。不要假设，要验证。

---

## 触发条件

当用户报告**任何问题**且**修复不顺利**时，如：
- "修改代码后没生效"
- "功能突然不工作了"
- "这个问题修不好了"
- "试了很多方法都不行"
- 任何反复出现或长期无法定位的问题

---

## 排查流程（必须按顺序执行）

### 📌 第 1 步：确认系统架构（最重要！）

**不要假设！先检查！**

```bash
# 检查部署方式
docker ps                    # Docker 容器
ps aux | grep <服务名>        # 宿主机进程
systemctl status <服务名>     # systemd 服务

# 检查配置文件
cat <配置文件路径>
cat docker-compose.yml       # Docker Compose
cat <项目目录>/.env          # 环境变量
```

**关键问题**：
- 服务运行在哪里？（Docker/宿主机/云服务器）
- 配置是什么？（端口/路径/环境变量）
- 依赖关系是什么？（数据库/缓存/消息队列）

---

### 📌 第 2 步：确认变更状态

```bash
# 代码变更
git status
git diff <相关文件>
git log --oneline -5

# 配置变更
diff <旧配置> <新配置>

# 最近操作记录
history | tail -20
```

**确认**：
- 最近修改了什么？
- 修改是否已提交/部署？
- 有没有遗漏的步骤？

---

### 📌 第 3 步：确认构建/编译是否生效

```bash
# 前端
npm run build && ls -la dist/

# Java
mvn clean package && ls -la target/

# Go
go build && ls -la <二进制文件>

# 检查输出文件的 hash/timestamp
md5sum <输出文件>
stat <输出文件>
```

**关键点**：
- 构建输出文件的 hash/timestamp 是否变化？
- **如果没变，说明代码实际没变化**

---

### 📌 第 4 步：确认部署是否生效

**根据部署方式选择**：

#### Docker 部署
```bash
# 查看容器信息
docker ps | grep <容器名>
docker inspect <容器名> | grep Mounts

# 更新容器文件
docker cp <文件> <容器名>:<路径>
docker restart <容器名>

# 验证容器内状态
docker exec <容器名> <命令>
docker logs <容器名> | tail -50
```

#### 宿主机部署
```bash
# 检查进程
ps aux | grep <进程名>
pgrep -f <进程名>

# 重启服务
systemctl restart <服务名>
# 或
<进程名> -daemon-reload

# 检查日志
journalctl -u <服务名> -f
tail -f /var/log/<日志文件>
```

---

### 📌 第 5 步：确认运行时状态

```bash
# 检查服务是否监听端口
netstat -tlnp | grep <端口>
ss -tlnp | grep <端口>
lsof -i :<端口>

# 检查网络连接
curl -v http://localhost:<端口>/<健康检查端点>
telnet <host> <port>

# 检查资源使用
top -p $(pgrep <进程名>)
df -h
free -m
```

**关键点**：
- 服务是否在运行？
- 端口是否监听？
- 资源是否充足？

---

### 📌 第 6 步：最后才是代码逻辑调试

只有确认前面 5 步都没问题后，才开始调试代码逻辑：
- 检查日志中的错误信息
- 添加调试日志/断点
- 检查数据流和状态
- 检查 API 请求/响应

---

## 常见错误模式

### ❌ 错误 1：假设部署/运行环境
> "我部署到 `/var/www/html` 了" → 但实际是 Docker 部署
> "服务应该启动了" → 但进程其实挂了

**正确做法**：先 `docker ps` / `ps aux` / `systemctl status` 确认

---

### ❌ 错误 2：盲目修改代码
> 代码改来改去，但运行的一直是旧版本

**正确做法**：先确认构建输出和部署目标的文件 hash/timestamp

---

### ❌ 错误 3：忽略缓存/状态
> "编译了新文件，但行为还是旧的"
> "重启了服务，但配置没生效"

**正确做法**：
- 前端：强制刷新（Ctrl+Shift+R）或清除缓存
- 后端：确认进程真的重启了（检查 PID 变化）
- 配置：确认加载的是正确的配置文件

---

## 检查清单

排查任何问题时，按顺序勾选：

```markdown
- [ ] 1. 确认系统架构（Docker/宿主机/云服务/其他）
- [ ] 2. 确认运行状态（进程/容器/服务是否在运行）
- [ ] 3. 确认最近变更（代码/配置/环境）
- [ ] 4. 确认构建/编译已执行且输出变化
- [ ] 5. 确认部署已生效（目标文件 hash/timestamp）
- [ ] 6. 确认运行时状态（端口/连接/资源）
- [ ] 7. 清除缓存/重启服务
- [ ] 8. 最后才是代码逻辑调试
```

---

## 快速诊断命令

```bash
# 一键检查部署状态
echo "=== Docker 容器 ===" && docker ps | grep -E "nginx|frontend|web"
echo "=== 宿主机 nginx ===" && ps aux | grep nginx | grep -v grep
echo "=== 项目目录 ===" && ls -la | grep -i docker
```

---

## 案例参考

### 案例 1：前端按钮点击无反应

**问题**：用户报告"新建公司按钮点击没反应"

**错误排查**：
1. ❌ 直接修改代码添加对话框
2. ❌ 编译后部署到 `/var/www/html`
3. ❌ 用户反馈还是不行
4. ❌ 继续改代码...

**正确排查**：
1. ✅ `docker ps` → 发现是 Docker 部署
2. ✅ `docker cp` 部署到容器
3. ✅ `docker restart` 重启容器
4. ✅ 指导用户强制刷新
5. ✅ Network 面板确认加载新文件
6. ✅ 问题解决

**根本原因**：部署目标错误，容器内一直是旧代码

---

### 案例 2：后端 API 返回旧数据

**问题**：修改了 API 逻辑，但响应还是旧的

**错误排查**：
1. ❌ 反复修改代码
2. ❌ 怀疑缓存问题
3. ❌ 检查数据库数据

**正确排查**：
1. ✅ `docker ps` → 发现后端也在容器中
2. ✅ `docker logs` → 发现容器没重启
3. ✅ `docker restart` → 重启容器
4. ✅ API 正常响应

**根本原因**：Java 应用需要重启才能加载新代码

---

### 案例 3：配置修改不生效

**问题**：修改了配置文件，但行为没变化

**错误排查**：
1. ❌ 反复修改配置
2. ❌ 怀疑配置格式问题

**正确排查**：
1. ✅ `ps aux | grep <进程>` → 检查启动参数
2. ✅ 发现进程使用的是 `/etc/xxx/config.yml` 而不是修改的 `./config.yml`
3. ✅ 修改正确的配置文件
4. ✅ 重启服务

**根本原因**：修改了错误的配置文件

---

## 核心教训

> **如果一个问题长期修复不了，基本上是定位思路不对。**
> 
> **先确认架构，再动手修复。**
> 
> **不要假设，要验证。**
> 
> **80% 的"疑难杂症"都是架构/部署/状态问题，不是代码逻辑问题。**

---

## 相关技能

- `docker` - Docker 容器操作
- `github` - 代码版本管理
- `healthcheck` - 系统健康检查