常见问题

灵王 OPS 平台问题的全面故障排除指南。每个章节包含诊断步骤和精确命令。

1. 注册 / 登录问题

无法注册新账户

症状： 注册表单提交后账户未创建，或显示错误。

诊断步骤：

# 1. 检查后端 API 是否响应
curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/api/v1/auth/register

# 2. 检查数据库连接
psql -h localhost -p 5432 -U lingops -d lingops_db -c "SELECT 1;"

# 3. 检查后端日志中的注册错误
docker logs lingops-backend --tail=50 2>&1 | grep -i "register\|error\|exception"

# 4. 检查邮件服务是否已配置（用于验证邮件）
grep -r "SMTP\|email" /Users/ling/lingwang-ops/config/ 2>/dev/null | head -20

可能原因： - 数据库连接失败导致用户创建失败 - SMTP 配置缺失，邮件验证无法发送 - 邮箱地址已被注册 - 后端 API 不可达

解决方案： 1. 如果数据库连接失败：确认 PostgreSQL 正在运行且 .env 中的凭据正确 2. 如果邮件未配置：在配置中设置 SMTP_HOST、SMTP_PORT、SMTP_USER、SMTP_PASS 3. 使用唯一的邮箱地址重新注册

登录/注册时出现 500 错误

症状： 浏览器显示 HTTP 500 错误，或表单提交后出现白屏。

诊断步骤：

# 1. 检查后端容器状态
docker ps | grep -E "lingops|backend"

# 2. 查看实时后端日志
docker logs -f lingops-backend --tail=100

# 3. 检查日志中的 panic 或异常
docker logs lingops-backend 2>&1 | grep -E "panic|exception|traceback|FATAL"

# 4. 验证环境配置
cat /Users/ling/lingwang-ops/.env | grep -E "DATABASE_URL|SECRET|JWT"

# 5. 测试数据库架构完整性
psql -h localhost -p 5432 -U lingops -d lingops_db -c "\dt"

可能原因： - 环境变量缺失或无效 - 数据库迁移未完成 - JWT 密钥配置错误 - 后端容器镜像损坏

解决方案： 1. 重新运行数据库迁移：cd /Users/ling/lingwang-ops && docker-compose exec backend alembic upgrade head 2. 确认 .env 文件包含所有必需变量 3. 重启后端：docker-compose restart backend

2. 告警接入问题

告警未出现在仪表盘

症状： Webhook 被调用，但告警未出现在告警列表中。

诊断步骤：

# 1. 验证 Webhook 端点是否可从数据源访问
curl -s -o /dev/null -w "%{http_code}" -X POST http://localhost:8080/api/v1/alerts/webhook \
  -H "Content-Type: application/json" \
  -d '{"alert_id":"test-001","message":"test alert","severity":"warning"}'

# 2. 检查告警接入服务日志
docker logs lingops-backend --tail=50 2>&1 | grep -i "alert\|webhook\|ingest"

# 3. 验证告警规则是否已配置
curl -s http://localhost:8080/api/v1/alerts/rules | jq '.'

# 4. 检查告警存储是否正常
psql -h localhost -p 5432 -U lingops -d lingops_db -c "SELECT COUNT(*) FROM alerts WHERE created_at > NOW() - INTERVAL '5 minutes';"

# 5. 检查 Redis 告警队列（如果使用异步处理）
docker exec lingops-redis redis-cli LLEN alert_queue

可能原因： - Webhook 密钥/令牌不匹配 - 告警格式与预期架构不符 - 告警被静默规则抑制 - 异步队列积压

解决方案： 1. 确认 Webhook 负载符合 API 规范 2. 在仪表盘中检查告警规则匹配情况 3. 如果队列积压，清空告警队列：docker exec lingops-redis redis-cli DEL alert_queue

Webhook 返回 400/500 错误

症状： 监控系统报告 Webhook 投递失败。

诊断步骤：

# 1. 使用正确的负载格式测试 Webhook
curl -v -X POST http://localhost:8080/api/v1/alerts/webhook \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Token: YOUR_WEBHOOK_TOKEN" \
  -d '{
    "alert_id": "test-$(date +%s)",
    "message": "Test alert",
    "severity": "warning",
    "source": "prometheus",
    "labels": {"env": "test"}
  }'

# 2. 检查 Webhook 验证日志
docker logs lingops-backend --tail=100 2>&1 | grep -E "webhook|400|validation"

# 3. 验证 Webhook 令牌配置
grep "WEBHOOK_TOKEN" /Users/ling/lingwang-ops/.env

# 4. 检查负载大小限制
grep -i "body\|size\|limit" /Users/ling/lingwang-ops/config/webhook.yaml 2>/dev/null

常见错误响应： - 400 Bad Request：JSON 格式无效或必填字段缺失 - 401 Unauthorized：Webhook 令牌无效或缺失 - 413 Payload Too Large：告警负载超出大小限制（默认：1MB） - 500 Internal Server Error：后端处理失败

解决方案： 1. 验证 JSON 语法：echo '{"key":"value"}' | jq . 2. 确保 X-Webhook-Token 头与配置的令牌匹配 3. 如果负载过大，将大告警拆分为多次调用

3. 通知问题

未收到邮件通知

症状： 告警触发但没有收到邮件。

诊断步骤：

# 1. 验证通知服务是否运行
docker ps | grep -E "notification|worker|email"

# 2. 检查通知队列深度
docker exec lingops-redis redis-cli LLEN notification_queue

# 3. 测试 SMTP 连接
nc -zv smtp.gmail.com 587 || echo "SMTP port not reachable"

# 4. 检查邮件发送尝试的通知日志
docker logs lingops-backend --tail=100 2>&1 | grep -E "email|notification|smtp|send"

# 5. 验证邮件模板是否存在
ls -la /Users/ling/lingwang-ops/templates/email/ 2>/dev/null

# 6. 测试邮件配置
cd /Users/ling/lingwang-ops && docker-compose exec backend python -c "
from app.core.config import settings
print(f'SMTP Host: {settings.SMTP_HOST}')
print(f'SMTP Port: {settings.SMTP_PORT}')
print(f'From: {settings.EMAIL_FROM}')
"

可能原因： - SMTP 凭据不正确或已过期 - 邮件被标记为垃圾邮件 - 通知队列卡住 - 收件人邮件地址不正确 - 邮件模板渲染失败

解决方案： 1. 测试 SMTP：docker-compose exec backend python -c "import smtplib; s=smtplib.SMTP('smtp.example.com',587); s.starttls()" 2. 清空通知队列：docker exec lingops-redis redis-cli DEL notification_queue 3. 检查垃圾邮件文件夹 4. 确认收件人在通知策略中

钉钉通知无法工作

症状： 告警触发但未收到钉钉消息。

诊断步骤：

# 1. 检查钉钉 Webhook 配置
grep -r "dingtalk\|dingding" /Users/ling/lingwang-ops/config/ 2>/dev/null

# 2. 直接测试钉钉 Webhook
curl -s -X POST "https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"msgtype":"text","text":{"content":"Test from LingOps"}}'

# 3. 检查钉钉错误的通知日志
docker logs lingops-backend --tail=100 2>&1 | grep -i "dingtalk\|dingding"

# 4. 验证钉钉机器人是否仍处于活跃状态
# （访问令牌可能已被撤销或受到速率限制）

# 5. 检查通知通道是否启用
curl -s http://localhost:8080/api/v1/notifications/channels | jq '.dingtalk'

可能原因： - 钉钉访问令牌已过期或被撤销 - 机器人 Webhook URL 已更改 - IP 未在钉钉群中列入白名单 - 超出速率限制（每个机器人最多 20 条/分钟）

解决方案： 1. 在钉钉群设置中重新生成钉钉 Webhook 令牌 2. 在 .env 中更新 DINGTALK_WEBHOOK_URL 3. 重启通知工作器：docker-compose restart notification-worker 4. 等待速率限制窗口重置（通常为 1 分钟）

4. 数据库问题

迁移失败

症状： alembic upgrade head 失败，或容器启动时报错提示表缺失。

诊断步骤：

# 1. 检查当前迁移状态
cd /Users/ling/lingwang-ops && docker-compose exec backend alembic current

# 2. 查看迁移历史
cd /Users/ling/lingwang-ops && docker-compose exec backend alembic history

# 3. 检查待执行的迁移
cd /Users/ling/lingwang-ops && docker-compose exec backend alembic heads

# 4. 查看详细的迁移错误
cd /Users/ling/lingwang-ops && docker-compose exec backend alembic upgrade head --sql 2>&1 | head -50

# 5. 验证数据库连接字符串
grep "DATABASE_URL" /Users/ling/lingwang-ops/.env

# 6. 检查 PostgreSQL 日志
docker logs lingops-postgres --tail=50

常见错误消息：

- "relation 'xxx' does not exist"：迁移未应用，或应用顺序错误
- "duplicate key value violates unique constraint"：数据与迁移冲突
- "permission denied"：数据库用户缺少所需权限
- "connection refused"：PostgreSQL 未运行或主机/端口错误

解决方案：

# 重置迁移（危险：会销毁数据 - 仅在开发环境中使用）
cd /Users/ling/lingwang-ops && docker-compose exec backend alembic downgrade base
cd /Users/ling/lingwang-ops && docker-compose exec backend alembic upgrade head

# 或手动应用特定迁移
cd /Users/ling/lingwang-ops && docker-compose exec backend alembic upgrade <revision>

预防措施： - 启动新容器版本前务必运行迁移 - 重要升级前备份数据库：pg_dump -h localhost -U lingops lingops_db > backup.sql

数据库连接被拒绝

症状： 后端日志显示 "connection refused" 或 "could not connect to server"。

诊断步骤：

# 1. 确认 PostgreSQL 容器正在运行
docker ps | grep postgres

# 2. 测试 PostgreSQL 端口连接
nc -zv localhost 5432 || echo "Port 5432 not reachable"

# 3. 检查 PostgreSQL 日志
docker logs lingops-postgres --tail=50

# 4. 验证连接凭据
cat /Users/ling/lingwang-ops/.env | grep -E "POSTGRES|DATABASE"

# 5. 手动测试连接
psql -h localhost -p 5432 -U lingops -d lingops_db -c "SELECT version();"

# 6. 检查 PostgreSQL 是否接受连接
docker exec lingops-postgres pg_isready -U lingops

可能原因： - PostgreSQL 容器已停止或崩溃 - 连接字符串中的主机/端口错误 - 凭据不正确 - PostgreSQL 最大连接数已满 - 防火墙阻止端口

解决方案：

# 重启 PostgreSQL
docker-compose restart postgres

# 检查 PostgreSQL 最大连接数配置
docker exec lingops-postgres psql -U lingops -c "SHOW max_connections;"

# 如有需要，在 postgresql.conf 中增加连接数

5. 部署问题

端口 8080 已被占用

症状： 后端容器启动失败，报 "port already allocated" 错误。

诊断步骤：

# 1. 查找占用端口 8080 的进程
lsof -i :8080 | grep LISTEN

# 2. 检查是否有正在运行的 LingOps 进程
ps aux | grep -E "lingops|gunicorn|uvicorn" | grep -v grep

# 3. 检查其他使用 8080 的 Docker 容器
docker ps --format "{{.Names}}\t{{.Ports}}" | grep 8080

# 4. 查看端口 8080 上的所有进程
sudo netstat -tlnp | grep :8080

解决方案：

# 选项 1：停止冲突进程
kill $(lsof -t -i :8080)

# 选项 2：在 .env 中更改 LingOps 后端端口
echo "BACKEND_PORT=8081" >> /Users/ling/lingwang-ops/.env
docker-compose down && docker-compose up -d

# 选项 3：如果另一个容器占用 8080，停止它
docker stop <container_name>

常见冲突来源： - 另一个 LingOps 实例已在运行 - Apache/Nginx Web 服务器占用端口 8080 - Java 应用程序通常默认使用端口 8080

前端 3000 无法加载

症状： 浏览器无法连接到 http://localhost:3000。

诊断步骤：

# 1. 检查前端容器是否运行
docker ps | grep frontend

# 2. 检查前端容器日志
docker logs lingops-frontend --tail=50

# 3. 测试端口连接
nc -zv localhost 3000 || echo "Port 3000 not reachable"

# 4. 检查 Next.js 开发服务器是否启动
docker exec lingops-frontend ps aux | grep -E "node|next"

# 5. 检查是否有构建错误
docker exec lingops-frontend npm ls 2>&1 | head -20

# 6. 验证 node_modules 是否已安装
docker exec lingops-frontend ls -la node_modules/.bin/next 2>/dev/null || echo "next not found"

可能原因： - 前端构建失败 - Node 模块未安装 - 端口 3000 已被占用 - Next.js 构建错误 - 内存不足导致构建失败

解决方案：

# 重新构建前端
cd /Users/ling/lingwang-ops/frontend
docker-compose down
docker-compose build --no-cache frontend
docker-compose up -d frontend

# 或如果使用直接 npm
cd /Users/ling/lingwang-ops/frontend
rm -rf node_modules
npm install
npm run build
npm start

6. 性能问题

服务器缓慢或无响应

症状： API 请求耗时过长，出现超时。

诊断步骤：

# 1. 检查系统资源使用情况
top -o %CPU
free -h
df -h

# 2. 检查 Docker 资源限制
docker stats --no-stream

# 3. 检查后端进程日志中的慢查询
docker logs lingops-backend --tail=200 2>&1 | grep -E "slow|timeout|Slow"

# 4. 检查数据库查询性能
psql -h localhost -p 5432 -U lingops -d lingops_db -c "
SELECT pid, now() - query_start AS duration, state, query
FROM pg_stat_activity
WHERE state != 'idle'
ORDER BY duration DESC;
"

# 5. 检查 Redis 内存使用情况
docker exec lingops-redis redis-cli INFO memory | grep -E "used_memory_human|maxmemory"

# 6. 检查网络 I/O
docker network ls
docker network inspect lingops lingops_default | jq '.[].Containers'

可能原因： - 数据库查询缺少索引 - 分配给容器的内存不足 - 并发连接过多 - 磁盘 I/O 瓶颈 - 服务间网络延迟

解决方案：

# 重启服务以清除连接
docker-compose restart

# 检查并添加缺失的索引
psql -h localhost -p 5432 -U lingops -d lingops_db -c "\di" | grep -E "alerts|users"

# 如果内存压力，清除 Redis 缓存
docker exec lingops-redis redis-cli FLUSHDB

# 如果使用异步处理，扩大工作器数量
docker-compose up -d --scale worker=3

大量告警导致超时

症状： 告警风暴导致 API 超时和服务降级。

诊断步骤：

# 1. 检查当前告警量
psql -h localhost -p 5432 -U lingops -d lingops_db -c "
SELECT COUNT(*) FROM alerts 
WHERE created_at > NOW() - INTERVAL '5 minutes';
"

# 2. 检查告警处理积压
docker exec lingops-redis redis-cli LLEN alert_queue

# 3. 查看最近的高容量告警来源
psql -h localhost -p 5432 -U lingops -d lingops_db -c "
SELECT source, COUNT(*) as cnt 
FROM alerts 
WHERE created_at > NOW() - INTERVAL '1 hour'
GROUP BY source 
ORDER BY cnt DESC LIMIT 10;
"

# 4. 检查被抑制/排队的通知
docker exec lingops-redis redis-cli LLEN notification_queue

# 5. 检查静默规则
curl -s http://localhost:8080/api/v1/alerts/silences | jq '.'

可能原因： - 监控源产生过多告警 - 告警聚合未配置 - 静默规则已过期或缺失 - Webhook 未启用速率限制

解决方案：

# 为嘈杂的源创建静默规则
curl -X POST http://localhost:8080/api/v1/alerts/silences \
  -H "Content-Type: application/json" \
  -d '{"matchers":{"source":"prometheus"},"startsAt":"2024-01-01T00:00:00Z","endsAt":"2024-01-02T00:00:00Z","createdBy":"admin"}'

# 在 Webhook 端点启用速率限制
# 编辑 /Users/ling/lingwang-ops/config/webhook.yaml:
# rate_limit:
#   enabled: true
#   requests_per_minute: 100

# 配置更改后重启
docker-compose restart backend

7. 代理问题

代理显示为离线

症状： LingOps 代理状态在仪表盘中显示为 "offline"。

诊断步骤：

# 1. 检查目标机器上的代理进程
ps aux | grep -E "lingops-agent|node_exporter" | grep -v grep

# 2. 检查代理日志
journalctl -u lingops-agent --no-pager -n 50
# 或对于 Docker 代理：
docker logs lingops-agent --tail=50

# 3. 验证代理可以连接到后端
curl -s -o /dev/null -w "%{http_code}" http://YOUR_BACKEND_HOST:8080/api/v1/agent/heartbeat

# 4. 检查防火墙规则
sudo iptables -L -n | grep 8080

# 5. 验证代理注册
curl -s http://localhost:8080/api/v1/agents | jq '.[] | select(.status=="offline")'

# 6. 检查代理配置
cat /etc/lingops/agent.yaml | grep -E "server_url|api_key|heartbeat"

可能原因： - 代理服务已停止 - 到后端的网络连接问题 - API 密钥或代理 ID 无效 - 后端不可达（防火墙阻止） - 心跳间隔过长导致检测延迟

解决方案：

# 重启代理服务
sudo systemctl restart lingops-agent
# 或
docker-compose -f agent-docker-compose.yml restart

# 如需要，重新注册代理
lingops-agent register --server http://YOUR_BACKEND:8080 --api-key YOUR_API_KEY

# 检查网络路径
traceroute YOUR_BACKEND_HOST
ping YOUR_BACKEND_HOST

仪表盘中未显示指标

症状： 代理在线，但没有指标图表显示。

诊断步骤：

# 1. 验证代理正在收集指标
curl -s http://localhost:9100/metrics | head -20

# 2. 检查 node_exporter 是否运行
curl -s -o /dev/null -w "%{http_code}" http://localhost:9100/metrics

# 3. 检查代理指标导出日志
docker logs lingops-agent --tail=100 2>&1 | grep -E "metric|export|scrape"

# 4. 验证后端中的指标管道
psql -h localhost -p 5432 -U lingops -d lingops_db -c "
SELECT COUNT(*) FROM metrics 
WHERE agent_id = 'YOUR_AGENT_ID' 
AND collected_at > NOW() - INTERVAL '5 minutes';
"

# 5. 检查指标接入端点
curl -s http://localhost:8080/api/v1/metrics/ingest -X POST \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"test","metrics":[{"name":"cpu_usage","value":0.5}]}'

# 6. 检查 Prometheus 抓取配置
grep -r "scrape_configs\|targets" /Users/ling/lingwang-ops/config/prometheus* 2>/dev/null

可能原因： - node_exporter 未在代理机器上运行 - 指标端点被防火墙阻止 - 指标名称/标签与仪表盘查询不匹配 - 代理未授权发送指标 - 代理与服务器之间的时间同步问题

解决方案：

# 启动 node_exporter
docker run -d \
  --name node_exporter \
  -p 9100:9100 \
  prom/node-exporter

# 测试完整指标管道
curl -s http://localhost:9100/metrics | grep -E "node_cpu|node_memory"

# 检查代理时区
timedatectl | grep Time

# 强制代理重新发送指标
docker exec lingops-agent lingops-agent push --force

8. 团队管理问题

无法邀请新用户

症状： 邀请表单显示错误或邀请未送达。

诊断步骤：

# 1. 检查您是否具有管理员权限
curl -s -H "Authorization: Bearer *** http://localhost:8080/api/v1/users/me | jq '.role'

# 2. 验证邀请服务是否正常工作
docker logs lingops-backend --tail=50 2>&1 | grep -i "invite\|email\|send"

# 3. 检查团队成员限制
curl -s -H "Authorization: Bearer *** http://localhost:8080/api/v1/teams | jq '.member_count'

# 4. 检查重复的邮箱邀请
psql -h localhost -p 5432 -U lingops -d lingops_db -c "
SELECT * FROM invitations 
WHERE email = '[email protected]' 
AND status = 'pending';
"

# 5. 验证邀请邮件模板是否存在
ls -la /Users/ling/lingwang-ops/templates/email/invitation.html 2>/dev/null

可能原因： - 用户缺少邀请所需的管理员/所有者角色 - 该邮箱已有待处理的邀请 - 团队已达到成员上限 - 邀请邮件被垃圾邮件过滤器阻止 - SMTP 配置无效

解决方案：

# 取消现有的待处理邀请
psql -h localhost -p 5432 -U lingops -d lingops_db -c "
DELETE FROM invitations WHERE email = '[email protected]' AND status = 'pending';
"

# 重新发送邀请
curl -X POST http://localhost:8080/api/v1/invitations/resend \
  -H "Authorization: Bearer *** \
  -H "Content-Type: application/json" \
  -d '{"invitation_id":"INVITATION_ID"}'

# 直接在数据库中检查邀请
psql -h localhost -p 5432 -U lingops -d lingops_db -c "\x on"
psql -h localhost -p 5432 -U lingops -d lingops_db -c "SELECT * FROM invitations LIMIT 5;"

邀请已过期

症状： 用户点击邀请链接但看到 "邀请已过期" 错误。

诊断步骤：

# 1. 检查邀请状态和过期时间
psql -h localhost -p 5432 -U lingops -d lingops_db -c "
SELECT id, email, status, created_at, expires_at 
FROM invitations 
WHERE id = 'YOUR_INVITATION_ID';
"

# 2. 验证服务器时间
date
docker exec lingops-backend date

# 3. 检查邀请 TTL 设置
grep -r "invitation.*expiry\|INVITATION_TTL" /Users/ling/lingwang-ops/config/ 2>/dev/null

# 4. 检查邀请过期清理任务
docker logs lingops-backend --tail=50 2>&1 | grep -i "expiry\|cleanup\|cron"

默认邀请过期时间： 48 小时（可配置）

解决方案：

# 延长邀请过期时间（仅限管理员）
psql -h localhost -p 5432 -U lingops -d lingops_db -c "
UPDATE invitations 
SET expires_at = NOW() + INTERVAL '48 hours' 
WHERE id = 'YOUR_INVITATION_ID' 
AND status = 'pending';
"

# 创建新邀请
curl -X POST http://localhost:8080/api/v1/invitations \
  -H "Authorization: Bearer *** \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","role":"member","team_id":"TEAM_ID"}'

# 在配置中更改默认过期时间
# 编辑 /Users/ling/lingwang-ops/config/invitation.yaml:
# default_ttl: 168  # 7 days in hours

快速参考命令

# 检查所有服务状态
docker-compose ps

# 查看特定服务的日志
docker logs -f lingops-backend

# 重启所有服务
docker-compose restart

# 检查数据库连接
psql -h localhost -p 5432 -U lingops -d lingops_db -c "SELECT 1;"

# 检查 Redis 连接
docker exec lingops-redis redis-cli ping

# 查看所有环境变量
cat /Users/ling/lingwang-ops/.env

# 检查端口占用情况
lsof -i :8080
lsof -i :3000
lsof -i :5432

# 检查资源使用情况
docker stats --no-stream

# 备份数据库
pg_dump -h localhost -p 5432 -U lingops lingops_db > backup_$(date +%Y%m%d).sql

# 访问后端 shell
docker-compose exec backend /bin/sh

# 访问数据库 shell
docker-compose exec postgres psql -U lingops -d lingops_db

文档版本：1.0 最后更新：2026-04-12 如需更多支持，请查阅 LingOps 社区论坛或联系您的系统管理员。