# 第二十四章 常见问题与排错指南

## 作者

**谭策** — 独立开发者 | AIOps 领域探索者

- 🌐 项目官网：[ITOpsAgentinfo](https://www.zjzwfw.cloud/ITOpsAgentinfo)
- 📝 博客：[zjzwfw.cloud](https://www.zjzwfw.cloud/)
- 📧 邮箱：<huawei_network@foxmail.com>
- 💬 微信公众号：**IT Online**

<p align="left">
  <img src="../../frontend/public/wechaterweima.png" width="200" alt="IT Online 微信公众号">
</p>

## 许可证

[MPL-2.0](../../LICENSE) © 谭策


## 本章导读

在实际部署和使用 ITOps Agent Platform 的过程中，运维人员和开发者会遇到各种各样的问题。本章汇总了最常见的故障场景和排查方法，涵盖部署、数据库、认证、SSH、WebSocket、性能、前端和 LLM 集成等各个方面。通过本章学习，你将掌握系统性的故障排查方法论，能够快速定位和解决各类问题。

## 学习目标

- 掌握常见部署问题的排查与解决方法
- 理解数据库故障（损坏、备份恢复、迁移失败）的处理流程
- 学会诊断认证问题（Token 过期、登录失败）
- 掌握 SSH 连接、WebSocket、性能等问题的排查技巧
- 理解前端常见问题（白屏、CORS、路由）的根因和解决方案
- 掌握 LLM 集成问题的排查方法
- 建立系统性的故障排查方法论

## 核心内容

### 24.1 排错方法论

在深入具体问题之前，先建立系统性的排查方法论：

**故障排查五步法：**

```
┌──────────────────────────────────────────────────────┐
│              故障排查五步法                            │
│                                                      │
│  1. 确认症状 (Symptom)                                │
│     - 问题是什么？                                    │
│     - 影响范围？                                      │
│     - 何时开始的？                                    │
│                                                      │
│  2. 收集证据 (Evidence)                               │
│     - 查看日志 (docker logs)                          │
│     - 检查服务状态 (docker ps)                         │
│     - 检查资源使用 (docker stats)                      │
│     - 复现问题                                        │
│                                                      │
│  3. 分析根因 (Root Cause)                             │
│     - 最近有什么变更？                                 │
│     - 缩小范围 (网络 → 应用 → 数据库)                  │
│     - 提出假设并验证                                   │
│                                                      │
│  4. 实施修复 (Fix)                                    │
│     - 最小变更原则                                     │
│     - 验证修复效果                                     │
│     - 记录变更                                        │
│                                                      │
│  5. 预防复发 (Prevent)                                │
│     - 添加监控告警                                     │
│     - 更新文档                                        │
│     - 必要时修改架构                                   │
└──────────────────────────────────────────────────────┘
```

**日志优先级：**

```
ERROR  → 立即处理，服务可能不可用
WARN   → 关注，可能导致问题
INFO   → 正常运行信息
DEBUG  → 开发调试信息（生产环境通常关闭）
```

### 24.2 部署问题

#### 问题 1：Docker 容器无法启动

**症状：** `docker compose up` 后容器状态为 Exited 或 Restarting。

**排查步骤：**

```bash
# 1. 查看容器状态
docker compose ps

# 2. 查看失败容器的日志
docker logs itops-backend --tail 100
docker logs itops-frontend --tail 100

# 3. 检查健康状态
docker inspect --format='{{.State.Health.Status}}' itops-backend
```

**常见原因与解决方案：**

| 错误信息 | 原因 | 解决方案 |
|----------|------|----------|
| `Missing required environment variable: JWT_SECRET` | 生产环境未设置 JWT_SECRET | 在 `.env` 中添加 `JWT_SECRET=$(openssl rand -hex 32)` |
| `Cannot use default JWT_SECRET in production` | 使用了不安全的默认密钥 | 设置强随机 JWT_SECRET |
| `EACCES: permission denied, mkdir '/app/data'` | 数据目录权限不足 | `docker compose down && docker volume rm itops-app-data && docker compose up -d` |
| `listen EADDRINUSE: address already in use :::3001` | 端口被占用 | `lsof -i :3001` 查找占用进程，或修改 docker-compose 中的端口映射 |

#### 问题 2：前端无法访问后端

**症状：** 前端页面白屏或 API 请求返回 502/504。

**排查步骤：**

```bash
# 1. 检查后端是否运行
docker exec itops-frontend wget -qO- http://backend:3001/health

# 2. 检查 Docker 网络
docker network inspect itops-itops-network

# 3. 查看 Nginx 错误日志
docker exec itops-frontend cat /var/log/nginx/error.log

# 4. 检查后端日志中的 CORS 错误
docker logs itops-backend 2>&1 | grep -i cors
```

**解决方案：**

```bash
# 确认 ALLOWED_ORIGINS 配置包含前端地址
# .env 文件：
ALLOWED_ORIGINS=http://localhost:8080,http://your-domain.com

# 重启后端使配置生效
docker compose restart backend
```

#### 问题 3：镜像拉取失败

**症状：** `docker compose up` 时报错 `pull access denied`。

```bash
# 手动测试拉取
docker pull registry.cn-hangzhou.aliyuncs.com/huluwa666/tsq-images-hub:IT_Onlin-ITOps-backend-latest

# 如果认证失败，登录阿里云镜像仓库
docker login registry.cn-hangzhou.aliyuncs.com
# 输入用户名和密码

# 或使用 CI/CD 推送的个人访问凭证
echo "YOUR_PASSWORD" | docker login --username YOUR_USERNAME --password-stdin registry.cn-hangzhou.aliyuncs.com
```

### 24.3 数据库问题

#### 问题 1：数据库文件损坏

**症状：** 后端启动时报 `database disk image is malformed`。

**排查与修复：**

```bash
# 1. 进入容器检查数据库
docker exec itops-backend sh -c "node -e \"
const db = require('better-sqlite3')('/app/data/app.db');
console.log(db.pragma('integrity_check'));
\""

# 2. 如果有备份，恢复备份
docker cp backup-2024-01-15.db itops-backend:/app/data/app.db
docker compose restart backend

# 3. 如果没有备份，尝试恢复
docker exec itops-backend sh -c "
sqlite3 /app/data/app.db '.recover' > /app/data/recovered.sql
sqlite3 /app/data/app.db.recovered < /app/data/recovered.sql
"

# 4. 替换损坏的数据库
docker cp itops-backend:/app/data/app.db.recovered ./app.db
# 替换后重启
```

**数据库完整性检查端点：**

```bash
# 数据库完整性检查
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "integrity_check"}' \
  http://localhost:3001/api/database/maintenance
```

#### 问题 2：数据库备份与恢复

**备份操作：**

```bash
# 方式一：直接复制数据库文件（需要先 WAL 检查点）
docker exec itops-backend sh -c "
sqlite3 /app/data/app.db 'PRAGMA wal_checkpoint(TRUNCATE);'
"
docker cp itops-backend:/app/data/app.db ./backup-$(date +%Y%m%d).db

# 方式二：使用内置备份 API
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:3001/api/backups/create
```

**恢复操作：**

```bash
# 1. 停止后端服务
docker compose stop backend

# 2. 替换数据库文件
docker cp ./backup-20240115.db itops-backend:/app/data/app.db

# 3. 删除 WAL 和 SHM 文件（避免不一致）
docker exec itops-backend rm -f /app/data/app.db-wal /app/data/app.db-shm

# 4. 启动后端
docker compose start backend
```

**定时备份配置：**

```bash
# crontab 定时备份
0 2 * * * docker exec itops-backend sqlite3 /app/data/app.db "PRAGMA wal_checkpoint(TRUNCATE);" && docker cp itops-backend:/app/data/app.db /backup/app-$(date +\%Y\%m\%d).db

# 保留最近 7 天的备份
find /backup -name "app-*.db" -mtime +7 -delete
```

#### 问题 3：数据库迁移失败

**症状：** 后端启动时日志显示 `Applying migration: xxx` 后报错。

```bash
# 1. 查看已执行的迁移
docker exec itops-backend sh -c "
sqlite3 /app/data/app.db 'SELECT * FROM migrations ORDER BY applied_at DESC LIMIT 10;'
"

# 2. 如果迁移部分执行导致表结构不一致
# 查看当前表结构
docker exec itops-backend sh -c "
sqlite3 /app/data/app.db '.schema'
"

# 3. 手动修复（在备份后操作）
# 如果迁移创建了表但插入数据失败
docker exec itops-backend sh -c "
sqlite3 /app/data/app.db 'DROP TABLE IF EXISTS problematic_table;'
"
# 删除迁移记录，让下次启动重新执行
docker exec itops-backend sh -c "
sqlite3 /app/data/app.db 'DELETE FROM migrations WHERE id = \"failed-migration-id\";'
"

# 4. 重启后端重新执行迁移
docker compose restart backend
```

### 24.4 认证问题

#### 问题 1：Token 过期

**症状：** API 请求返回 401 `Token已过期`。

**诊断与解决：**

```bash
# 1. 检查 JWT 配置
# .env 文件中：
JWT_EXPIRES_IN=24h   # 默认 24 小时

# 2. 使用 Refresh Token 获取新 Token
curl -X POST http://localhost:3001/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "YOUR_REFRESH_TOKEN"}'

# 预期响应
{"success": true, "data": {"token": "new_access_token", "refreshToken": "new_refresh_token"}}
```

**前端自动刷新逻辑：**

```typescript
// 在 API 拦截器中处理 Token 过期
api.interceptors.response.use(
  (response) => response,
  async (error) => {
    if (error.response?.status === 401 && error.response?.data?.message === 'Token已过期') {
      const refreshToken = localStorage.getItem('refreshToken');
      if (refreshToken) {
        const { data } = await axios.post('/api/auth/refresh', { refreshToken });
        localStorage.setItem('token', data.data.token);
        localStorage.setItem('refreshToken', data.data.refreshToken);
        // 重试原请求
        error.config.headers.Authorization = `Bearer ${data.data.token}`;
        return api.request(error.config);
      }
    }
    return Promise.reject(error);
  }
);
```

#### 问题 2：登录失败

**症状：** 登录页面提示 "用户名或密码错误"。

**排查步骤：**

```bash
# 1. 确认用户是否存在
docker exec itops-backend sh -c "
sqlite3 /app/data/app.db \"SELECT id, username, role, enabled FROM users;\"
"

# 2. 确认账户是否被禁用
# 如果 enabled = 0，需要启用
docker exec itops-backend sh -c "
sqlite3 /app/data/app.db \"UPDATE users SET enabled = 1 WHERE username = 'admin';\"
"

# 3. 重置管理员密码（忘记密码时）
# 生成新的 bcrypt 哈希（需要 bcrypt 库）
docker exec itops-backend sh -c "
node -e \"
const bcrypt = require('bcryptjs');
const hash = bcrypt.hashSync('NewPassword123!', 12);
const db = require('/app/dist/models/database').default;
db.prepare('UPDATE users SET password = ? WHERE username = ?').run(hash, 'admin');
console.log('Password reset successfully');
\"
"

# 4. 检查审计日志中的登录尝试
docker exec itops-backend sh -c "
sqlite3 /app/data/app.db \"
  SELECT * FROM audit_logs WHERE action = 'login' ORDER BY created_at DESC LIMIT 10;
\"
"
```

#### 问题 3：JWT_SECRET 变更导致所有 Token 失效

**症状：** 修改 JWT_SECRET 后，所有已登录用户被强制登出。

**原因分析：** JWT 签名基于 JWT_SECRET，密钥变更后所有旧 Token 的签名验证都会失败。

**解决方案：**

```bash
# 这是预期行为，无需修复
# 如果需要保留用户登录状态，不应在生产环境修改 JWT_SECRET

# 如果必须修改（如密钥泄露），通知所有用户重新登录即可
# 旧 Token 会自动失效（因为签名验证不通过）
```

### 24.5 SSH 连接问题

#### 问题 1：SSH 连接超时

**症状：** Web 终端连接后一直显示 "connecting"，最终超时。

**排查步骤：**

```bash
# 1. 检查后端到目标服务器的网络连通性
docker exec itops-backend nc -zv <target-host> 22

# 2. 检查 SSH 服务状态
docker exec itops-backend ssh -o ConnectTimeout=5 -o StrictHostKeyChecking=no \
  -o BatchMode=yes target-user@target-host echo "SSH OK"

# 3. 检查防火墙规则
# 在目标服务器上
iptables -L -n | grep 22

# 4. 检查后端日志中的 SSH 错误
docker logs itops-backend 2>&1 | grep -i ssh
```

**常见原因：**

| 原因 | 解决方案 |
|------|----------|
| 目标服务器防火墙阻止 22 端口 | 在安全组/防火墙中放行 22 端口 |
| SSH 服务未运行 | `systemctl start sshd` |
| 网络不通（容器无法访问外部） | 检查 Docker 网络配置，确认容器有外网访问权限 |
| SSH 端口非 22 | 在服务器配置中指定正确的端口 |

#### 问题 2：密钥认证失败

**症状：** 使用 SSH Key 连接时提示认证失败。

**排查：**

```bash
# 1. 确认私钥格式正确（应为 PEM 格式）
# 如果私钥是 OpenSSH 格式，需要转换
ssh-keygen -p -m PEM -f your-private-key

# 2. 确认公钥已添加到目标服务器
# 在目标服务器上
cat ~/.ssh/authorized_keys | grep "your-public-key"

# 3. 检查私钥权限（600）
chmod 600 your-private-key

# 4. 测试连接
ssh -i your-private-key -o StrictHostKeyChecking=no user@host echo "OK"
```

#### 问题 3：命令执行失败

**症状：** Web 终端中执行命令返回错误或被拦截。

**排查：**

```bash
# 1. 检查命令过滤日志
docker logs itops-backend 2>&1 | grep -i "command"

# 2. 检查用户角色
docker exec itops-backend sh -c "
sqlite3 /app/data/app.db \"SELECT username, role FROM users WHERE username = '当前用户';\"
"

# 3. 查看命令过滤策略
# 某些命令被策略拦截（如 rm -rf /）
# 参考 commandFilter.ts 中的 DANGEROUS_COMMANDS 列表

# 4. 如果是 sudo 命令，确认 SSH 用户有 sudo 权限
# 在目标服务器上
sudo -l
```

### 24.6 WebSocket 问题

#### 问题 1：WebSocket 连接断开

**症状：** Web 终端使用一段时间后自动断开。

**排查：**

```bash
# 1. 检查 Socket.IO 配置
# backend/src/app.ts
# pingTimeout: 60000 (60秒无响应断开)
# pingInterval: 25000 (25秒发送一次 ping)

# 2. 检查 Nginx 超时配置
# docker/nginx.conf
# proxy_read_timeout 3600s; (WebSocket 代理超时 1 小时)

# 3. 查看 Nginx 错误日志
docker exec itops-frontend cat /var/log/nginx/error.log | grep -i websocket

# 4. 检查浏览器控制台的网络面板
# 查看 WebSocket 连接状态和关闭代码
```

**解决方案：**

| 问题 | 解决方案 |
|------|----------|
| Nginx 超时 | 确认 `proxy_read_timeout` 设置为 3600s |
| Socket.IO pingTimeout 过短 | 增加 `pingTimeout` 到 120000 |
| 网络不稳定 | 前端已实现指数退避重连，无需额外处理 |
| 后端重启 | 等待后端启动完成后，前端自动重连 |

#### 问题 2：WebSocket 消息丢失

**症状：** 终端中输入的命令或输出不完整。

**排查：**

```bash
# 1. 检查 Socket.IO 消息大小限制
# backend/src/app.ts
# maxHttpBufferSize: 1e6 (1MB)

# 2. 检查网络带宽
docker stats itops-backend

# 3. 查看是否有内存压力
docker exec itops-backend node -e "console.log(process.memoryUsage())"
```

### 24.7 性能问题

#### 问题 1：慢查询

**症状：** 页面加载缓慢，特别是告警列表、审计日志等大数据量页面。

**排查：**

```bash
# 1. 检查表数据量
docker exec itops-backend sh -c "
sqlite3 /app/data/app.db \"
  SELECT name,
    (SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name = t.name) as exists_flag
  FROM sqlite_master t WHERE type='table'
  UNION ALL
  SELECT 'alerts: ' || COUNT(*), 1 FROM alerts
  UNION ALL
  SELECT 'audit_logs: ' || COUNT(*), 1 FROM audit_logs
  UNION ALL
  SELECT 'agent_executions: ' || COUNT(*), 1 FROM agent_executions;
\"
"

# 2. 检查索引是否被使用
docker exec itops-backend sh -c "
sqlite3 /app/data/app.db \"
  EXPLAIN QUERY PLAN SELECT * FROM alerts WHERE status = 'new' ORDER BY created_at DESC LIMIT 50;
\"
"

# 3. 如果没有使用索引，检查索引是否存在
docker exec itops-backend sh -c "
sqlite3 /app/data/app.db \"
  SELECT name, tbl_name FROM sqlite_master WHERE type='index' AND tbl_name = 'alerts';
\"
"

# 4. 执行数据库维护
docker exec itops-backend sh -c "
sqlite3 /app/data/app.db \"VACUUM; ANALYZE;\"
"
```

**优化方案：**

```sql
-- 为高频查询添加索引
CREATE INDEX IF NOT EXISTS idx_alerts_status_created ON alerts(status, created_at DESC);

-- 清理过期数据（审计日志保留 90 天）
DELETE FROM audit_logs WHERE created_at < datetime('now', '-90 days');

-- 清理过期 Token 黑名单
DELETE FROM token_blacklist WHERE expires_at < CURRENT_TIMESTAMP;
```

#### 问题 2：内存泄漏

**症状：** 后端容器内存使用持续增长。

**排查：**

```bash
# 1. 监控内存使用
docker stats itops-backend --no-stream

# 2. 检查 Node.js 堆内存
docker exec itops-backend node -e "
const mem = process.memoryUsage();
console.log('RSS:', (mem.rss / 1024 / 1024).toFixed(1), 'MB');
console.log('Heap Used:', (mem.heapUsed / 1024 / 1024).toFixed(1), 'MB');
console.log('Heap Total:', (mem.heapTotal / 1024 / 1024).toFixed(1), 'MB');
"

# 3. 检查缓存大小
# Token 黑名单缓存（最大 10000 条）
# 用户信息缓存（最大 1000 条，TTL 60 秒）
# 速率限制缓存（最大 10000 条）
```

**解决方案：**

```bash
# 如果内存持续增长，重启容器释放内存
docker compose restart backend

# 长期方案：调整缓存限制
# 修改代码中的 MAX_CACHE_SIZE 和 MAX_STORE_SIZE 常量
```

#### 问题 3：CPU 使用率过高

**症状：** 后端容器 CPU 持续占用超过 100%。

**排查：**

```bash
# 1. 监控 CPU 使用
docker stats itops-backend --no-stream

# 2. 查看是否有密集循环或大查询
docker logs itops-backend --tail 50

# 3. 检查是否有大量并发 LLM 请求
docker exec itops-backend sh -c "
sqlite3 /app/data/app.db \"
  SELECT status, COUNT(*) FROM agent_executions
  GROUP BY status;
\"
"
```

### 24.8 前端问题

#### 问题 1：白屏

**症状：** 访问前端页面显示空白。

**排查：**

```bash
# 1. 打开浏览器开发者工具 (F12)
# 查看 Console 面板是否有 JavaScript 错误

# 2. 查看 Network 面板
# 确认 index.html 和 JS/CSS 文件是否正常加载

# 3. 检查 Nginx 是否正常
docker exec itops-frontend nginx -t

# 4. 检查 SPA 路由配置
# 如果直接访问子路由（如 /servers）返回 404
# 确认 Nginx 配置了 try_files $uri $uri/ /index.html
docker exec itops-frontend cat /etc/nginx/conf.d/default.conf | grep try_files
```

**常见原因与解决：**

| 原因 | 解决方案 |
|------|----------|
| JS 文件 404 | 清除浏览器缓存或强制刷新 (Ctrl+Shift+R) |
| 路由 404 | 确认 Nginx `try_files` 配置正确 |
| React 渲染错误 | 查看 Console 面板的具体错误信息 |
| API 请求失败 | 检查后端服务和 CORS 配置 |

#### 问题 2：CORS 错误

**症状：** 浏览器 Console 显示 `Access to fetch at ... has been blocked by CORS policy`。

**排查与解决：**

```bash
# 1. 确认 ALLOWED_ORIGINS 配置
cat .env | grep ALLOWED_ORIGINS

# 2. 配置正确的前端地址
ALLOWED_ORIGINS=http://localhost:8080,http://your-domain.com

# 3. 重启后端
docker compose restart backend

# 4. 验证 CORS 响应头
curl -I -H "Origin: http://localhost:8080" http://localhost:3001/health
# 应该看到 Access-Control-Allow-Origin: http://localhost:8080
```

#### 问题 3：路由跳转后页面不更新

**症状：** 点击导航链接后 URL 变化，但页面内容不变。

**排查：**

```bash
# 1. 确认使用了 React Router 的 Link 组件而非 <a> 标签
# 错误: <a href="/servers">服务器</a>  ← 会整页刷新
# 正确: <NavLink to="/servers">服务器</NavLink>

# 2. 检查 App.tsx 中的路由定义
# 确认 Route path 与 NavLink to 匹配

# 3. 清除浏览器缓存
# 某些情况下旧版本的 JS 文件被缓存
```

### 24.9 LLM 集成问题

#### 问题 1：API 调用失败

**症状：** Agent 执行时返回错误，或输出为空。

**排查：**

```bash
# 1. 确认 API Key 配置
docker exec itops-backend sh -c "
sqlite3 /app/data/app.db \"SELECT key, value FROM settings WHERE key LIKE '%API_KEY%';\"
"

# 2. 检查 API Base URL
docker exec itops-backend sh -c "
sqlite3 /app/data/app.db \"SELECT key, value FROM settings WHERE key LIKE '%API_BASE%';\"
"

# 3. 测试 LLM API 连通性
curl -X POST https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 10
  }'

# 4. 查看 Agent 执行日志
docker logs itops-backend 2>&1 | grep -i "llm\|agent\|doubao\|openai"
```

**常见错误码：**

| 错误码 | 原因 | 解决方案 |
|--------|------|----------|
| 401 | API Key 无效 | 检查 Key 是否正确 |
| 403 | 账户欠费或权限不足 | 检查账户状态 |
| 429 | 请求频率超限 | 降低请求频率或升级套餐 |
| 500 | 服务端错误 | 稍后重试 |
| timeout | 请求超时 | 检查网络，增加超时时间 |

#### 问题 2：速率限制

**症状：** 短时间内大量 Agent 执行时，部分请求被限流。

**解决方案：**

```bash
# 1. 降低并发度
# 在工作流中限制并行节点数量

# 2. 使用队列
# 后端已有 rateLimiter 中间件
# /api/copilot: 每分钟 30 次

# 3. 增加 API Key（多 Key 轮询）
# 需要在代码中实现多 Key 负载均衡
```

#### 问题 3：响应超时

**症状：** Agent 执行时长时间等待后超时。

```bash
# 1. 检查 Nginx 超时配置
# proxy_read_timeout 300s; (API 代理)
# proxy_read_timeout 3600s; (WebSocket)

# 2. 对于流式响应，确认使用 SSE (Server-Sent Events)
# 而非等待完整响应

# 3. 调整 LLM 的 max_tokens 参数
# 过大的 max_tokens 会导致响应时间过长
```

### 24.10 系统性排错检查清单

**完整排错检查清单：**

```
□ 1. 确认问题范围
     - 单个用户 vs 所有用户
     - 单个功能 vs 全局
     - 最近是否有部署变更

□ 2. 检查基础设施
     - docker compose ps (容器状态)
     - docker stats (资源使用)
     - df -h (磁盘空间)
     - free -m (内存)

□ 3. 检查服务日志
     - docker logs itops-backend --tail 200
     - docker logs itops-frontend --tail 200

□ 4. 检查数据库
     - docker exec ... sqlite3 ... "PRAGMA integrity_check;"
     - 检查表数据量
     - 检查慢查询

□ 5. 检查网络
     - 容器间网络连通性
     - 外部 API 可达性
     - 防火墙/安全组

□ 6. 检查认证
     - Token 是否过期
     - JWT_SECRET 是否变更
     - 用户状态 (enabled)

□ 7. 检查前端
     - 浏览器 Console 错误
     - Network 面板请求状态
     - 缓存是否过期

□ 8. 检查外部依赖
     - LLM API 状态
     - SSH 目标服务器状态
     - 告警源 Webhook 状态
```

## 本章小结

本章汇总了 ITOps Agent Platform 运维中最常见的故障场景和排查方法。掌握系统性排错方法论（五步法）是解决一切问题的基础：确认症状、收集证据、分析根因、实施修复、预防复发。针对具体问题，本章提供了详细的排查命令、常见原因分析和解决方案。建议运维人员将本章的检查清单作为日常运维的参考指南。

## 本章练习

### 基础练习

1. **模拟部署故障**：故意设置错误的 JWT_SECRET（留空），观察后端启动失败的情况。然后根据日志信息定位问题，修复后重新启动。

2. **数据库恢复演练**：先备份当前数据库，然后模拟数据库损坏（如删除部分页面），使用备份文件恢复。验证恢复后数据的一致性。

3. **CORS 问题排查**：将 `ALLOWED_ORIGINS` 设置为不匹配的域名，观察前端 API 请求的 CORS 错误。使用 curl 验证 CORS 响应头，然后修复配置。

### 进阶练习

4. **性能压测**：使用 `wrk` 或 `ab` 工具对后端 API 进行压力测试（如 `wrk -t4 -c100 -d30s http://localhost:3001/health`），观察性能瓶颈。分析慢查询日志，针对性优化。

5. **全链路排错**：故意制造一个复合故障（如修改 Nginx 配置 + 删除数据库索引 + 变更 JWT_SECRET），然后按照排错检查清单逐步排查并修复所有问题。

6. **监控告警配置**：配置 Docker 容器的健康监控，当容器 unhealthy 或资源使用超过阈值时发送告警通知（可对接现有的 Webhook 通知渠道）。

### 思考题

7. 当前项目的日志输出到容器标准输出，通过 `docker logs` 查看。在生产环境中，日志量可能非常大且需要长期保留。请设计一个日志收集和分析方案（如 ELK Stack 或 Loki + Grafana），说明架构设计和关键配置。

8. 假设平台部署在 Kubernetes 上而非 Docker Compose，本章中提到的大部分排查命令和解决方案需要做哪些调整？请列出关键的差异点和 Kubernetes 特有的排查工具（如 `kubectl logs`、`kubectl exec`、`kubectl describe` 等）。

## 延伸阅读

- Docker 故障排查指南: [https://docs.docker.com/config/containers/logging/](https://docs.docker.com/config/containers/logging/)
- SQLite 数据库修复: [https://www.sqlite.org/lang_recover.html](https://www.sqlite.org/lang_recover.html)
- Socket.IO 故障排查: [https://socket.io/docs/v4/troubleshooting-connection-issues/](https://socket.io/docs/v4/troubleshooting-connection-issues/)
- CORS 详解: [https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
- 书籍推荐：《Site Reliability Engineering》- Google SRE 实践指南
