---
name: troubleshoot
description: >
  当用户报告服务不可用、部署失败、数据库连接问题、磁盘满、内存不足等故障时使用。
  按分层诊断流程定位问题，提供修复方案。
  触发短语：服务挂了、连不上、502、部署失败、磁盘满、OOM、故障排查、troubleshoot。
  不触发：本地开发环境问题（AI 直接诊断）。
---

# 故障排查技能

## 快速诊断（30 秒）

按以下顺序逐层检查，第一个失败的就是问题所在：

```bash
pm2 status              # 应用进程
docker ps               # 基础设施容器
curl localhost:<backend_port>/api/v1/health  # API 健康
df -h                   # 磁盘空间
free -h                 # 内存
```

## 故障分类与修复

### 1. PM2 应用故障

**症状**：pm2 status 显示 errored/stopped

| 常见原因 | 诊断命令 | 修复 |
|---------|---------|------|
| 端口被占用 | `lsof -i:<port>` | `kill -9 <PID>` → `pm2 restart all` |
| 构建产物缺失 | `ls backend/dist/ frontend/.next/` | 重新构建 → `pm2 restart all` |
| 环境变量错误 | `cat .env \| grep DATABASE_URL` | 修正 .env → `pm2 restart all` |

### 2. Nginx 502

| 常见原因 | 诊断命令 | 修复 |
|---------|---------|------|
| 配置错误 | `sudo nginx -t` | 修正配置 → `systemctl restart nginx` |
| 后端未运行 | `pm2 status` | `pm2 restart <backend_process>` |

### 3. Docker 容器故障

| 常见原因 | 诊断命令 | 修复 |
|---------|---------|------|
| 容器未启动 | `docker ps -a` | `bash scripts/deploy/deploy.sh up` |
| 日志报错 | `docker logs <container>` | 根据日志修复 |
| 数据卷损坏 | `docker inspect <container>` | 备份 → 删除 volume → 重建 → 恢复 |

### 4. 数据库连接失败

| 常见原因 | 诊断命令 | 修复 |
|---------|---------|------|
| PostgreSQL 未运行 | `docker ps \| grep postgres` | `bash scripts/deploy/deploy.sh up` |
| 密码不匹配 | 对比 .env 的 DATABASE_URL 和 POSTGRES_PASSWORD | 修正 .env 或重建 volume |
| 迁移冲突 | `npx prisma migrate status` | `prisma migrate resolve` 或 `prisma migrate deploy` |
| 慢查询 | `docker exec psql "SELECT * FROM pg_stat_activity WHERE duration > interval '5s'"` | `VACUUM ANALYZE` 或终止慢查询 |

### 5. 部署失败

1. 先回滚：`bash scripts/deploy/deploy.sh deploy`（用上一个 commit）
2. 查看日志：`pm2 logs --err --lines 50`
3. 常见原因：构建失败、迁移失败、端口冲突

### 6. 资源耗尽

**磁盘满**：
```bash
du -sh /srv/apps/ffoa/logs /srv/apps/ffoa/backups | sort -hr
pm2 flush                               # 清理 PM2 日志
find logs -mtime +7 -delete             # 清理 7 天前日志
docker system prune -f                  # 清理 Docker
```

**内存 OOM**：
- 检查 `ecosystem.config.js` 的 `max_memory_restart` 设置
- 检查 `docker-compose` 的 `mem_limit` 设置
- 检查 DATABASE_URL 的 `connection_limit` 参数

### 7. 权限问题（itadmin 登录失败）

**根因**：系统管理员的 `organizationId` 必须为 `NULL`（全局管理员），不能绑定到具体组织。

诊断：查询 `platform_iam.users` 表检查 `organization_id` 字段。
修复：`cd backend && npm run fix:itadmin-role`

### 8. 灾难恢复

按严重程度：
1. **部署回滚** → 用 `deploy-ops` skill
2. **数据库损坏** → 用 `db-backup` skill 恢复
3. **服务器丢失** → 用 `deploy-ops` skill 首次部署 + `db-backup` skill 恢复数据

## 升级策略

| 级别 | 场景 | 行动 |
|------|------|------|
| L1 自行解决 | 单服务重启、日志清理、配置修正 | 按上述流程操作 |
| L2 需要协助 | 数据损坏、迁移冲突、未知错误 | 提供诊断信息给团队 |
| L3 紧急事件 | 全站不可用、数据丢失 | 立即回滚 + 通知所有相关人员 |

## 报告问题时提供

- 服务器环境（UAT/生产）
- `pm2 status` 和 `docker ps` 输出
- 最近的操作（部署、迁移、配置变更）
- 错误日志（`pm2 logs --err --lines 50`）

## References

- [`docs/standards/11-troubleshooting-methodology.md`](../../../docs/standards/11-troubleshooting-methodology.md) —— 第一性原理 3 层拆解 + P0/P1 复盘 6 段模板。本 skill 负责"运行时诊断"（这台机器现在哪个组件挂了），methodology 负责"事后复盘"（为什么会挂 + 怎么让同类问题以后能自动拦）。