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

作者

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

🌐 项目官网：ITOpsAgentinfo
📝 博客：zjzwfw.cloud
📧 邮箱：huawei_network@foxmail.com
💬 微信公众号：IT Online

IT Online 微信公众号

许可证

本章导读

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

本章练习

基础练习

模拟部署故障：故意设置错误的 JWT_SECRET（留空），观察后端启动失败的情况。然后根据日志信息定位问题，修复后重新启动。
数据库恢复演练：先备份当前数据库，然后模拟数据库损坏（如删除部分页面），使用备份文件恢复。验证恢复后数据的一致性。
CORS 问题排查：将 ALLOWED_ORIGINS 设置为不匹配的域名，观察前端 API 请求的 CORS 错误。使用 curl 验证 CORS 响应头，然后修复配置。

进阶练习

性能压测：使用 wrk 或 ab 工具对后端 API 进行压力测试（如 wrk -t4 -c100 -d30s http://localhost:3001/health），观察性能瓶颈。分析慢查询日志，针对性优化。
全链路排错：故意制造一个复合故障（如修改 Nginx 配置 + 删除数据库索引 + 变更 JWT_SECRET），然后按照排错检查清单逐步排查并修复所有问题。
监控告警配置：配置 Docker 容器的健康监控，当容器 unhealthy 或资源使用超过阈值时发送告警通知（可对接现有的 Webhook 通知渠道）。

思考题

当前项目的日志输出到容器标准输出，通过 docker logs 查看。在生产环境中，日志量可能非常大且需要长期保留。请设计一个日志收集和分析方案（如 ELK Stack 或 Loki + Grafana），说明架构设计和关键配置。
假设平台部署在 Kubernetes 上而非 Docker Compose，本章中提到的大部分排查命令和解决方案需要做哪些调整？请列出关键的差异点和 Kubernetes 特有的排查工具（如 kubectl logs、kubectl exec、kubectl describe 等）。

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

作者 ​

许可证 ​

本章导读 ​

学习目标 ​

核心内容 ​

24.1 排错方法论 ​

24.2 部署问题 ​

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

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

问题 3：镜像拉取失败 ​

24.3 数据库问题 ​

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

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

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

24.4 认证问题 ​

问题 1：Token 过期 ​

问题 2：登录失败 ​

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

24.5 SSH 连接问题 ​

问题 1：SSH 连接超时 ​

问题 2：密钥认证失败 ​

问题 3：命令执行失败 ​

24.6 WebSocket 问题 ​

问题 1：WebSocket 连接断开 ​

问题 2：WebSocket 消息丢失 ​

24.7 性能问题 ​

问题 1：慢查询 ​

问题 2：内存泄漏 ​

问题 3：CPU 使用率过高 ​

24.8 前端问题 ​

问题 1：白屏 ​

问题 2：CORS 错误 ​

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

24.9 LLM 集成问题 ​

问题 1：API 调用失败 ​

问题 2：速率限制 ​

问题 3：响应超时 ​

24.10 系统性排错检查清单 ​

本章小结 ​

本章练习 ​

基础练习 ​

进阶练习 ​

思考题 ​

延伸阅读 ​

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

作者

许可证

本章导读

学习目标

核心内容

24.1 排错方法论

24.2 部署问题

问题 1：Docker 容器无法启动

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

问题 3：镜像拉取失败

24.3 数据库问题

问题 1：数据库文件损坏

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

问题 3：数据库迁移失败

24.4 认证问题

问题 1：Token 过期

问题 2：登录失败

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

24.5 SSH 连接问题

问题 1：SSH 连接超时

问题 2：密钥认证失败

问题 3：命令执行失败

24.6 WebSocket 问题

问题 1：WebSocket 连接断开

问题 2：WebSocket 消息丢失

24.7 性能问题

问题 1：慢查询

问题 2：内存泄漏

问题 3：CPU 使用率过高

24.8 前端问题

问题 1：白屏

问题 2：CORS 错误

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

24.9 LLM 集成问题

问题 1：API 调用失败

问题 2：速率限制

问题 3：响应超时

24.10 系统性排错检查清单

本章小结

本章练习

基础练习

进阶练习

思考题

延伸阅读