🔧 故障排查指南

📋 故障排查流程

问题分级

🚀 安装问题

Node.js 安装失败

1. 检查是否已安装：which node
2. 使用 nvm 安装 (推荐):

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
   nvm install --lts
   nvm use --lts

3. 验证安装：node -v && npm -v

OpenClaw 安装失败

# 方案 1: 手动下载安装
curl -fsSL https://claude.ai/install.sh -o install.sh
chmod +x install.sh
sudo ./install.sh

# 方案 2: 使用 npm 安装
sudo npm install -g @anthropic-ai/claude-code

🔐 认证与配置问题

API Key 无效

# 1. 检查环境变量
echo $ANTHROPIC_API_KEY

# 2. 检查格式 (应以 sk-ant-开头)
echo $ANTHROPIC_API_KEY | grep "^sk-ant-"

# 3. 重新设置
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxx"

# 4. 验证 API Key
curl -X POST https://api.anthropic.com/v1/messages \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'

工作区信任问题

claude config set trusted_directories '["/path/to/project"]'

⚡ 任务执行问题

任务卡住不执行

Token 超限问题

# 方案 1: 减少上下文 (在 CLAUDE.md 中指定关注目录)
cat > CLAUDE.md << EOF
# 项目说明
只关注以下目录:
- src/routers/
- src/schemas/

忽略以下目录:
- node_modules/
- .git/
EOF

# 方案 2: 分批次处理
claude "先实现用户认证模块"
claude "接下来实现订单管理模块"

# 方案 3: 使用小模型
export ANTHROPIC_MODEL="claude-sonnet-4-20250514"

💻 代码生成问题

生成的代码无法运行

# 1. 检查包版本
pip show fastapi

# 2. 升级/降级
pip install --upgrade fastapi
# 或
pip install fastapi==0.104.1

# 3. 让 AI 修复
claude "检测到 FastAPI 导入错误，请修复兼容性问题"

代码风格不一致

# 添加代码规范到 CLAUDE.md
cat >> CLAUDE.md << EOF

## 代码风格规范
- 变量和函数：snake_case
- 类名：PascalCase
- 缩进：4 空格
- 导入顺序：标准库 → 第三方库 → 本地模块
EOF

# 使用格式化工具
pip install black isort
black src/
isort src/

🧪 测试相关问题

测试覆盖率不达标

# 1. 识别未覆盖的代码
pytest tests/ --cov=src --cov-report=html
open htmlcov/index.html

# 2. 让 AI 生成补充测试
claude "以下代码行未被测试覆盖，请生成对应的测试用例"

# 3. 运行补充测试
pytest tests/ --cov=src --cov-fail-under=80

测试间歇性失败

# 解决方案：隔离测试数据 + Mock 外部依赖
@pytest.fixture
def clean_db():
    db.drop_all()
    db.create_all()
    yield db
    db.drop_all()

@patch('requests.post')
def test_external_api(mock_post):
    mock_post.return_value.status_code = 200
    # 测试逻辑

🚢 CI/CD 部署问题

K8s 部署失败 - ImagePullBackOff

# 1. 查看 Pod 详情
kubectl describe pod order-service-xxx -n test

# 2. 查看事件日志
kubectl get events -n test --sort-by='.lastTimestamp'

# 3. 检查镜像拉取凭证
kubectl get secret registry-credentials -n test -o yaml

# 4. 更新凭证
kubectl create secret docker-registry registry-credentials \
  --docker-server=harbor.internal.com \
  --docker-username=admin \
  --docker-password=Harbor12345 \
  -n test

健康检查失败

# Helm Chart values.yaml
healthCheck:
  readinessProbe:
    initialDelaySeconds: 30  # 从 10 增加到 30
    periodSeconds: 10
    
  livenessProbe:
    initialDelaySeconds: 60  # 从 30 增加到 60
    periodSeconds: 20

# 确保应用实现健康检查端点
@app.get("/health/ready")
def health_ready():
    return {"status": "ready"}

🔒 安全问题

API Key 泄露紧急处理

1. 立即撤销泄露的 API Key (登录 Anthropic Console → API Keys → Revoke)
2. 从 Git 历史中删除:

   java -jar bfg.jar --delete-files .env
   git reflog expire --expire=now --all
   git gc --prune=now --aggressive

3. 轮换所有相关凭证 (生成新的 API Key)
4. 审计 API 调用记录 (检查异常调用)
5. 添加预防措施 (git-secrets / pre-commit hooks)

容器安全漏洞

# 使用 Trivy 扫描
trivy image order-service:latest

# 修复方案:
# 1. 使用最小化基础镜像
FROM python:3.12-slim

# 2. 多阶段构建
FROM node:22 AS builder
...
FROM python:3.12-slim
COPY --from=builder ...

# 3. 非 root 用户运行
RUN useradd -m -u 1000 appuser
USER appuser

📊 日志分析

日志位置

常用日志分析命令

# 实时查看日志
tail -f /var/log/app/application.log

# 搜索错误
grep -i "error\|exception\|critical" application.log

# 查看错误上下文
grep -B 5 -A 5 "ERROR" application.log

# 按时间过滤
awk '/2026-03-16 10:00:00/,/2026-03-16 11:00:00/' application.log

# JSON 日志分析
cat application.log | jq 'select(.level == "ERROR")'

🆘 紧急恢复流程

K8s 回滚操作

# 1. 查看部署历史
kubectl rollout history deployment/order-service -n test

# 2. 回滚到上一个版本
kubectl rollout undo deployment/order-service -n test

# 3. 回滚到指定版本
kubectl rollout undo deployment/order-service -n test --to-revision=5

# 4. 验证回滚
kubectl rollout status deployment/order-service -n test

数据库回滚

# 使用 Alembic 回滚迁移
alembic downgrade -1        # 回滚一个版本
alembic downgrade head~3    # 回滚三个版本
alembic downgrade base      # 回滚到初始状态

# 从备份恢复
pg_restore -U postgres -d orders_db -Fc backup_20260315.dump

📞 联系支持