当前位置：首页 > news >正文

ClaudeCode真经第六章：问题排查与故障处理

news 2025/10/6 12:53:57

文章目录

ClaudeCode真经第六章：问题排查与故障处理
- 6.1 常见问题诊断
- - 6.1.1 连接问题排查
  - 6.1.2 性能问题诊断
  - 6.1.3 权限与认证问题
  - 6.1.4 平台特定问题
- 6.2 故障排查方法
- - 6.2.1 日志分析技巧
  - 6.2.2 调试工具使用
  - 6.2.3 网络抓包分析
  - 6.2.4 系统级故障诊断
- 6.3 解决方案与系统优化
- - 6.3.1 性能调优策略
  - 6.3.2 稳定性提升
  - 6.3.3 监控与告警体系
- 6.4 生产环境部署与维护
- - 6.4.1 部署环境准备
  - 6.4.2 运维管理体系
  - 6.4.3 自动化运维流程

ClaudeCode真经第六章：问题排查与故障处理

在实际使用ClaudeCode的过程中，开发者可能会遇到各种问题和挑战。本章将系统性地介绍常见问题的诊断方法、故障排查技巧，以及高效的解决方案，帮助你快速恢复正常的开发工作流。

6.1 常见问题诊断

6.1.1 连接问题排查

网络连接故障

ClaudeCode作为云端AI工具，依赖稳定的网络连接。常见的网络问题包括：

问题现象：命令执行超时、响应缓慢、连接中断

快速检测方法：

# 检查网络连通性
ping api.anthropic.com# 检查DNS解析
nslookup claude.ai# 测试HTTPS连接
curl -I https://api.anthropic.com

解决策略：
- 检查防火墙和代理设置
- 确认网络稳定性和带宽充足
- 考虑使用企业网络或移动热点进行对比测试

API密钥配置错误

这是最常见的初次使用问题：

错误信息示例：

Authentication failed: Invalid API key
Error: Unable to authenticate with Anthropic API

诊断步骤：

# 检查当前配置
claude doctor# 验证API密钥格式
echo $ANTHROPIC_API_KEY | wc -c  # 应该是合理的长度

解决方法：
- 重新登录：claude logout → claude
- 检查环境变量设置
- 确认API密钥没有过期或被撤销

代理设置问题

企业环境或国际网络访问常遇到的问题：

检测代理配置：

echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $NO_PROXY

代理相关错误：
- 代理服务器无响应
- 证书验证失败
- 代理认证问题

6.1.2 性能问题诊断

响应速度慢

问题表现：
- 命令执行时间过长
- 代码生成响应延迟
- 文件读取缓慢

性能分析工具：

# 启用详细日志模式
claude --verbose# 检查系统资源使用
top -p $(pgrep claude)
htop# 网络延迟测试
traceroute api.anthropic.com

常见原因：
- 网络带宽不足
- 本地系统资源紧张
- 大型项目上下文处理
- 并发请求过多

内存使用过高

监控内存使用：

# 实时监控ClaudeCode进程
watch -n 1 'ps aux | grep claude'# 系统内存状态
free -h
cat /proc/meminfo

内存优化策略：
- 定期使用 /compact 命令减少上下文
- 避免同时处理多个大型文件
- 关闭不必要的会话窗口

长时间运行命令超时

超时问题识别：

# 设置合理的超时时间
claude --max-turns 5 -p "your query"# 使用后台执行模式
nohup claude -p "long running task" > output.log 2>&1 &

6.1.3 权限与认证问题

重复权限提示

当ClaudeCode频繁询问相同操作的权限时：

问题现象：每次执行git命令都需要确认

解决方案：配置权限白名单

# 在交互模式中使用
/permissions# 或启动时指定允许的工具
claude --allowedTools "Bash(git log:*)" "Bash(git diff:*)" "Read"

认证失效问题

症状表现：
- 突然要求重新登录
- API调用被拒绝
- 会话中断

恢复步骤：

# 清除认证信息并重新登录
/logout
rm -rf ~/.config/claude/auth.json
claude

6.1.4 平台特定问题

Windows WSL环境问题

OS/平台检测错误：

# 设置正确的操作系统类型
npm config set os linux# 强制安装（如果需要）
npm install -g @anthropic-ai/claude --force --no-os-check

Node.js路径冲突：

# 检查Node.js安装位置
which node
which npm# 应该显示Linux路径（/usr/）而不是Windows路径（/mnt/c/）

WSL2网络配置问题：
- 防火墙阻止内部通信
- NAT网络模式导致IDE检测失败
- 解决方案：配置防火墙规则或启用镜像网络模式

macOS和Linux权限问题

全局安装权限错误：

# 使用本地安装替代
claude migrate-installer# 或使用原生安装器
curl -fsSL https://claude.ai/install.sh | bash

PATH配置问题：

# 检查安装位置
which claude# 确认PATH包含安装目录
echo $PATH | grep -o ~/.local/bin

6.2 故障排查方法

6.2.1 日志分析技巧

启用详细日志

详细的日志信息是排查问题的关键：

# 启动时启用详细模式
claude --verbose# 或在运行中切换
/debug on

错误信息解读

常见错误信息及其含义：

# API相关错误
"Rate limit exceeded" → API调用频率超限
"Invalid model" → 模型名称错误或不支持
"Context length exceeded" → 上下文长度超出限制# 网络相关错误
"Connection timeout" → 网络连接超时
"SSL certificate verify failed" → SSL证书验证失败
"DNS resolution failed" → 域名解析失败# 权限相关错误
"Permission denied" → 文件或目录权限不足
"Authentication failed" → 认证失败或过期
"Access denied" → API访问被拒绝

问题复现方法

建立可靠的问题复现流程：

# 创建最小复现环境
mkdir debug-session
cd debug-session# 记录完整的操作序列
script session-log.txt
claude --verbose -p "your problematic query"
exit# 收集系统信息
claude doctor > system-info.txt
env | grep -E "(CLAUDE|ANTHROPIC|PROXY)" > env-vars.txt

6.2.2 调试工具使用

内置诊断命令

ClaudeCode提供了多种内置的诊断工具：

# 系统健康检查
claude doctor# 检查安装状态
/doctor# 查看版本信息
claude --version# 测试网络连接
/ping

外部监控工具

结合系统工具进行深度分析：

# 网络监控
sudo netstat -tulpn | grep claude
ss -tulpn | grep claude# 进程监控
ps aux | grep claude
pstree -p | grep claude# 文件系统监控
lsof | grep claude
find ~/.config/claude -type f -ls

性能分析工具

# CPU和内存使用情况
pidstat -p $(pgrep claude) 1# I/O性能分析
iotop -p $(pgrep claude)# 网络流量分析
nethogs
bandwhich

6.2.3 网络抓包分析

基础网络诊断

# HTTP/HTTPS流量捕获
tcpdump -i any host api.anthropic.com -w claude-traffic.pcap# 使用Wireshark分析
wireshark claude-traffic.pcap# 简化的curl测试
curl -v https://api.anthropic.com/v1/ping

代理环境调试

# 检查代理连通性
curl --proxy $HTTP_PROXY https://api.anthropic.com# 代理认证测试
curl --proxy-user username:password --proxy $HTTP_PROXY https://api.anthropic.com# 绕过代理测试
curl --noproxy '*' https://api.anthropic.com

6.2.4 系统级故障诊断

文件系统问题

# 检查磁盘空间
df -h
du -sh ~/.config/claude# 文件权限检查
ls -la ~/.config/claude/
find ~/.config/claude -type f ! -readable# 文件系统完整性
fsck -n /dev/your-disk-partition

依赖关系问题

# Node.js环境检查
node --version
npm --version
npm list -g @anthropic-ai/claude# 系统依赖验证
which ripgrep || echo "ripgrep not found"
ldd $(which claude)  # Linux下检查动态库依赖

6.3 解决方案与系统优化

6.3.1 性能调优策略

缓存机制优化

ClaudeCode的缓存系统对性能影响巨大：

本地缓存管理：

# 清理缓存
/clear
/compact# 查看缓存使用情况
du -sh ~/.config/claude/cache/# 定期清理策略
find ~/.config/claude/cache -mtime +7 -delete

Redis集群优化（企业环境）：

# Redis性能监控
redis-cli --latency-history -h your-redis-host# 缓存命中率分析
redis-cli info stats | grep cache_hit# 内存使用优化
redis-cli config set maxmemory-policy allkeys-lru

CDN加速配置：

# 配置CDN端点
export CLAUDE_API_ENDPOINT="https://your-cdn-endpoint.com"# 地理位置优化
curl -s https://ipinfo.io/json | jq .region

并发处理改进

线程池调优：

# 设置最大并发数
export CLAUDE_MAX_CONCURRENT=4# 监控并发性能
watch -n 1 'ps -eLf | grep claude | wc -l'

异步处理优化：

# 使用后台模式处理大型任务
claude -p "complex task" --max-turns 10 > task.log 2>&1 &# 任务队列管理
jobs
fg %1  # 恢复后台任务

负载均衡策略：

# 多实例负载分配
for i in {1..3}; doclaude -p "subtask $i" &
done
wait  # 等待所有任务完成

资源使用优化

内存池管理：

# 设置内存限制
export CLAUDE_MEMORY_LIMIT=2G# 内存使用监控
pmap $(pgrep claude) | tail -1

数据库连接池优化：

# 设置数据库连接参数
export DB_POOL_SIZE=10
export DB_POOL_TIMEOUT=30000# 连接池状态监控
netstat -an | grep :5432 | wc -l  # PostgreSQL连接数

API调用优化：

# 批量请求处理
claude -p --input-format stream-json < batch-requests.json# API速率限制管理
export CLAUDE_RATE_LIMIT=60  # 每分钟60次请求

6.3.2 稳定性提升

异常处理机制

实现全面的异常捕获和处理：

# 全局异常捕获脚本
#!/bin/bash
claude_with_retry() {local max_attempts=3local attempt=1while [ $attempt -le $max_attempts ]; doif claude "$@"; thenreturn 0elseecho "Attempt $attempt failed, retrying..."sleep $((attempt * 2))((attempt++))fidoneecho "All attempts failed, logging error"echo "$(date): Failed to execute: $*" >> ~/.config/claude/error.logreturn 1
}

重试策略设计

指数退避算法：

# 智能重试函数
exponential_backoff() {local command="$1"local max_attempts=5local base_delay=1for attempt in $(seq 1 $max_attempts); doif eval "$command"; thenreturn 0filocal delay=$((base_delay * 2**(attempt-1)))echo "Retry $attempt/$max_attempts after ${delay}s..."sleep $delaydonereturn 1
}# 使用示例
exponential_backoff "claude -p 'your command'"

熔断器模式：

# 熔断器状态管理
CIRCUIT_BREAKER_STATE="CLOSED"  # CLOSED, OPEN, HALF_OPEN
FAILURE_THRESHOLD=5
RECOVERY_TIMEOUT=60circuit_breaker_call() {case $CIRCUIT_BREAKER_STATE in"OPEN")if [ $(($(date +%s) - $LAST_FAILURE_TIME)) -gt $RECOVERY_TIMEOUT ]; thenCIRCUIT_BREAKER_STATE="HALF_OPEN"elseecho "Circuit breaker is OPEN, request blocked"return 1fi;;esac# 执行实际调用if claude "$@"; thenFAILURE_COUNT=0CIRCUIT_BREAKER_STATE="CLOSED"return 0else((FAILURE_COUNT++))LAST_FAILURE_TIME=$(date +%s)if [ $FAILURE_COUNT -ge $FAILURE_THRESHOLD ]; thenCIRCUIT_BREAKER_STATE="OPEN"fireturn 1fi
}

降级方案准备

服务降级策略：

# 服务可用性检测
check_service_health() {if ! claude doctor >/dev/null 2>&1; thenecho "ClaudeCode service unhealthy, switching to fallback"return 1fireturn 0
}# 降级处理函数
fallback_handler() {echo "Entering degraded mode..."# 使用本地缓存响应# 或切换到备用服务# 或提供基础功能
}

数据备份恢复：

# 自动备份会话数据
backup_sessions() {local backup_dir="$HOME/.config/claude/backup/$(date +%Y%m%d)"mkdir -p "$backup_dir"cp -r ~/.config/claude/sessions "$backup_dir/"cp -r ~/.config/claude/cache "$backup_dir/"# 压缩旧备份find ~/.config/claude/backup -mtime +30 -name "*.tar.gz" -deletetar czf "$backup_dir.tar.gz" "$backup_dir" && rm -rf "$backup_dir"
}# 恢复函数
restore_session() {local backup_date="$1"local backup_file="$HOME/.config/claude/backup/${backup_date}.tar.gz"if [ -f "$backup_file" ]; thentar xzf "$backup_file" -C "$HOME/.config/claude/"echo "Session restored from $backup_date"fi
}

6.3.3 监控与告警体系

实时监控仪表盘

构建综合监控系统：

# 监控脚本
#!/bin/bash
monitor_claude() {while true; do{echo "=== ClaudeCode Monitor $(date) ==="# 服务状态if pgrep -x claude >/dev/null; thenecho "✓ ClaudeCode process running"elseecho "✗ ClaudeCode process not found"fi# 资源使用情况echo "Memory: $(ps -o pid,vsz,rss,comm -p $(pgrep claude) 2>/dev/null)"# 网络连通性if curl -s --max-time 5 https://api.anthropic.com >/dev/null; thenecho "✓ API connectivity OK"elseecho "✗ API connectivity failed"fi# 磁盘空间echo "Cache size: $(du -sh ~/.config/claude/cache 2>/dev/null || echo 'N/A')"} | tee -a ~/.config/claude/monitor.logsleep 60done
}# 启动监控
monitor_claude &
MONITOR_PID=$!
echo $MONITOR_PID > ~/.config/claude/monitor.pid

关键指标告警设置

# 告警配置
MEMORY_THRESHOLD_MB=1000
CPU_THRESHOLD_PERCENT=80
RESPONSE_TIME_THRESHOLD_MS=10000
ERROR_RATE_THRESHOLD=0.1# 告警检查函数
check_alerts() {# 内存使用告警memory_usage=$(ps -o rss= -p $(pgrep claude) 2>/dev/null | awk '{print $1}')if [ "${memory_usage:-0}" -gt $MEMORY_THRESHOLD_MB ]; thensend_alert "High memory usage: ${memory_usage}MB"fi# CPU使用告警cpu_usage=$(ps -o %cpu= -p $(pgrep claude) 2>/dev/null)if [ "${cpu_usage:-0.0}" > "$CPU_THRESHOLD_PERCENT" ]; thensend_alert "High CPU usage: ${cpu_usage}%"fi# 错误率告警recent_errors=$(tail -100 ~/.config/claude/error.log | grep "$(date +%Y-%m-%d)" | wc -l)if [ $recent_errors -gt 10 ]; thensend_alert "High error rate: $recent_errors errors today"fi
}# 告警发送函数
send_alert() {local message="$1"echo "$(date): ALERT - $message" >> ~/.config/claude/alerts.log# 发送邮件告警（可选）# echo "$message" | mail -s "ClaudeCode Alert" admin@yourcompany.com# 发送Slack通知（可选）# curl -X POST -H 'Content-type: application/json' \#      --data "{\"text\":\"ClaudeCode Alert: $message\"}" \#      YOUR_SLACK_WEBHOOK_URL
}

故障自动处理流程

# 自动恢复脚本
auto_recovery() {local issue="$1"case $issue in"high_memory")echo "Triggering memory cleanup..."claude -p "/compact" >/dev/null 2>&1;;"service_down")echo "Restarting ClaudeCode..."pkill claudesleep 5claude &;;"network_issue")echo "Checking network configuration..."# 重置网络设置或切换代理;;"auth_failure")echo "Refreshing authentication..."claude logout && claude;;esac
}# 健康检查和自动恢复
health_check_and_recover() {if ! claude doctor >/dev/null 2>&1; thenauto_recovery "service_down"fi# 检查响应时间response_time=$(timeout 30 time claude -p "ping" 2>&1 | grep real | awk '{print $2}')if [[ $response_time > "0m30s" ]]; thenauto_recovery "high_response_time"fi
}

6.4 生产环境部署与维护

6.4.1 部署环境准备

环境隔离与配置管理

生产环境的ClaudeCode部署需要严格的环境隔离：

# 环境配置分离
mkdir -p /opt/claude/{prod,staging,dev}# 生产环境配置
cat > /opt/claude/prod/config.env << 'EOF'
# ClaudeCode生产环境配置
CLAUDE_ENV=production
CLAUDE_LOG_LEVEL=warn
CLAUDE_MAX_CONCURRENT=8
CLAUDE_MEMORY_LIMIT=4G
CLAUDE_CACHE_TTL=3600# API配置
ANTHROPIC_API_KEY=${PROD_API_KEY}
ANTHROPIC_API_ENDPOINT=https://api.anthropic.com# 安全配置
CLAUDE_SECURITY_MODE=strict
CLAUDE_AUDIT_ENABLED=true
CLAUDE_BACKUP_ENABLED=true# 网络配置
HTTP_PROXY=${PROD_HTTP_PROXY}
HTTPS_PROXY=${PROD_HTTPS_PROXY}
NO_PROXY=localhost,127.0.0.1,.internal# 存储配置
CLAUDE_DATA_DIR=/var/lib/claude
CLAUDE_LOG_DIR=/var/log/claude
CLAUDE_BACKUP_DIR=/backup/claude
EOF# 权限设置
chmod 600 /opt/claude/prod/config.env
chown claude-service:claude-service /opt/claude/prod/config.env

容器化部署最佳实践

使用Docker进行标准化部署：

# Dockerfile for ClaudeCode
FROM node:18-alpine# 创建应用用户
RUN addgroup -g 1001 -S claude && \adduser -S claude -u 1001 -G claude# 安装系统依赖
RUN apk add --no-cache \bash \curl \git \ripgrep \python3 \py3-pip# 安装ClaudeCode
RUN npm install -g @anthropic-ai/claude# 创建数据目录
RUN mkdir -p /app/data /app/logs /app/cache && \chown -R claude:claude /app# 切换到应用用户
USER claude
WORKDIR /app# 复制配置文件
COPY --chown=claude:claude config/ ./config/
COPY --chown=claude:claude scripts/ ./scripts/# 健康检查
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \CMD claude doctor || exit 1# 启动脚本
CMD ["./scripts/start.sh"]

# docker-compose.yml
version: '3.8'
services:claude:build: .container_name: claude-prodrestart: unless-stoppedenvironment:- NODE_ENV=production- CLAUDE_LOG_LEVEL=infoenv_file:- ./config/prod.envvolumes:- claude-data:/app/data- claude-logs:/app/logs- claude-cache:/app/cache- /var/run/docker.sock:/var/run/docker.sock:ronetworks:- claude-networkdeploy:resources:limits:cpus: '2.0'memory: 4Greservations:cpus: '0.5'memory: 1Gredis:image: redis:7-alpinecontainer_name: claude-redisrestart: unless-stoppedvolumes:- redis-data:/datanetworks:- claude-networkvolumes:claude-data:claude-logs:claude-cache:redis-data:networks:claude-network:driver: bridge

自动化部署脚本

#!/bin/bash
# deploy.sh - ClaudeCode自动化部署脚本set -euo pipefailSCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_DIR="$(dirname "$SCRIPT_DIR")"# 配置参数
ENVIRONMENT="${1:-staging}"
VERSION="${2:-latest}"
NAMESPACE="claude-${ENVIRONMENT}"# 日志函数
log() {echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*"
}# 预检查
pre_deployment_check() {log "Starting pre-deployment checks..."# 检查Docker环境if ! docker --version >/dev/null 2>&1; thenlog "ERROR: Docker not found"exit 1fi# 检查配置文件if [ ! -f "${PROJECT_DIR}/config/${ENVIRONMENT}.env" ]; thenlog "ERROR: Environment config not found: ${ENVIRONMENT}.env"exit 1fi# 检查资源可用性if [ "$(docker system df -q | awk '/Total/{print $4}' | sed 's/GB//')" -lt "5" ]; thenlog "WARNING: Low disk space available"filog "Pre-deployment checks passed"
}# 构建镜像
build_image() {log "Building ClaudeCode image for ${ENVIRONMENT}..."docker build \--tag "claude:${VERSION}" \--tag "claude:${ENVIRONMENT}-latest" \--build-arg ENVIRONMENT="${ENVIRONMENT}" \--build-arg VERSION="${VERSION}" \"${PROJECT_DIR}"log "Image built successfully"
}# 部署服务
deploy_service() {log "Deploying ClaudeCode ${ENVIRONMENT} environment..."# 停止现有服务docker-compose -f "${PROJECT_DIR}/docker-compose.${ENVIRONMENT}.yml" down --remove-orphans# 清理旧镜像（保留最近3个版本）docker images claude --format "table {{.Repository}}:{{.Tag}}" | \grep -v "${ENVIRONMENT}-latest" | \tail -n +4 | \xargs -r docker rmi# 启动新服务docker-compose -f "${PROJECT_DIR}/docker-compose.${ENVIRONMENT}.yml" up -dlog "Service deployed successfully"
}# 健康检查
health_check() {log "Performing health check..."local max_attempts=30local attempt=1while [ $attempt -le $max_attempts ]; doif docker-compose -f "${PROJECT_DIR}/docker-compose.${ENVIRONMENT}.yml" \exec -T claude claude doctor >/dev/null 2>&1; thenlog "Health check passed"return 0filog "Health check attempt $attempt/$max_attempts failed, waiting..."sleep 10((attempt++))donelog "ERROR: Health check failed after $max_attempts attempts"return 1
}# 回滚函数
rollback() {log "Starting rollback procedure..."local previous_versionprevious_version=$(docker images claude --format "table {{.Tag}}" | \grep -v latest | head -2 | tail -1)if [ -n "$previous_version" ]; thenlog "Rolling back to version: $previous_version"# 更新docker-compose配置sed -i "s/image: claude:.*/image: claude:$previous_version/" \"${PROJECT_DIR}/docker-compose.${ENVIRONMENT}.yml"# 重新部署docker-compose -f "${PROJECT_DIR}/docker-compose.${ENVIRONMENT}.yml" up -d# 验证回滚if health_check; thenlog "Rollback completed successfully"elselog "ERROR: Rollback failed"exit 1fielselog "ERROR: No previous version found for rollback"exit 1fi
}# 主执行流程
main() {log "Starting deployment of ClaudeCode ${ENVIRONMENT} v${VERSION}"pre_deployment_checkbuild_imagedeploy_serviceif ! health_check; thenlog "Deployment failed, initiating rollback"rollbackelselog "Deployment completed successfully"# 发送通知curl -X POST -H 'Content-type: application/json' \--data "{\"text\":\"ClaudeCode ${ENVIRONMENT} v${VERSION} deployed successfully\"}" \"${SLACK_WEBHOOK_URL:-}" 2>/dev/null || truefi
}# 错误处理
trap 'log "ERROR: Deployment failed at line $LINENO"' ERR# 执行主流程
main "$@"

6.4.2 运维管理体系

日志聚合与分析

建立统一的日志管理系统：

# ELK Stack配置 - Filebeat
# filebeat.yml
filebeat.inputs:
- type: logenabled: truepaths:- /var/log/claude/*.logfields:service: claudeenvironment: productionfields_under_root: truemultiline.pattern: '^\d{4}-\d{2}-\d{2}'multiline.negate: truemultiline.match: afteroutput.elasticsearch:hosts: ["elasticsearch:9200"]index: "claude-logs-%{+yyyy.MM.dd}"logging.level: info
logging.to_files: true
logging.files:path: /var/log/filebeatname: filebeatkeepfiles: 7permissions: 0644# Logstash配置
# logstash.conf
input {beats {port => 5044}
}filter {if [service] == "claude" {grok {match => { "message" => "%{TIMESTAMP_ISO8601:timestamp} \[%{LOGLEVEL:level}\] %{GREEDYDATA:log_message}" }}date {match => [ "timestamp", "ISO8601" ]}if [level] == "ERROR" {mutate {add_tag => [ "alert" ]}}}
}output {elasticsearch {hosts => ["elasticsearch:9200"]index => "claude-logs-%{+YYYY.MM.dd}"}
}

性能监控与调优

# Prometheus监控配置
# prometheus.yml
global:scrape_interval: 15sscrape_configs:- job_name: 'claude'static_configs:- targets: ['claude:9090']scrape_interval: 30smetrics_path: /metricsrule_files:- "claude-alerts.yml"alerting:alertmanagers:- static_configs:- targets:- alertmanager:9093# 告警规则
# claude-alerts.yml
groups:
- name: clauderules:- alert: HighMemoryUsageexpr: process_resident_memory_bytes{job="claude"} > 2147483648  # 2GBfor: 5mlabels:severity: warningannotations:summary: "ClaudeCode high memory usage"description: "Memory usage is above 2GB for more than 5 minutes"- alert: HighErrorRateexpr: rate(claude_code_errors_total[5m]) > 0.1for: 2mlabels:severity: criticalannotations:summary: "High error rate detected"description: "Error rate is above 10% for more than 2 minutes"- alert: ServiceDownexpr: up{job="claude"} == 0for: 1mlabels:severity: criticalannotations:summary: "ClaudeCode service is down"description: "ClaudeCode service has been down for more than 1 minute"

安全扫描与防护

# 安全扫描脚本
#!/bin/bash
# security-scan.shSCAN_DATE=$(date +%Y%m%d)
REPORT_DIR="/var/log/claude/security"
mkdir -p "$REPORT_DIR"# 容器安全扫描
container_security_scan() {echo "Starting container security scan..."# 使用Trivy扫描容器镜像trivy image --format json --output "$REPORT_DIR/trivy-$SCAN_DATE.json" claude:latest# 检查高危漏洞high_vulns=$(jq '.Results[].Vulnerabilities[]? | select(.Severity=="HIGH" or .Severity=="CRITICAL") | .VulnerabilityID' \"$REPORT_DIR/trivy-$SCAN_DATE.json" | wc -l)if [ "$high_vulns" -gt 0 ]; thenecho "WARNING: Found $high_vulns high/critical vulnerabilities"send_security_alert "Container vulnerabilities detected: $high_vulns high/critical issues"fi
}# 配置安全检查
config_security_check() {echo "Checking configuration security..."# 检查敏感信息泄露if grep -r "password\|secret\|key" /opt/claude/config/ --exclude="*.example" >/dev/null 2>&1; thenecho "WARNING: Potential secrets in configuration files"send_security_alert "Potential secrets found in configuration files"fi# 检查文件权限find /opt/claude -type f -perm /o+rwx -print > "$REPORT_DIR/permissions-$SCAN_DATE.txt"if [ -s "$REPORT_DIR/permissions-$SCAN_DATE.txt" ]; thenecho "WARNING: World-writable files found"send_security_alert "World-writable files detected"fi
}# 网络安全检查
network_security_check() {echo "Performing network security check..."# 端口扫描nmap -sS -O localhost > "$REPORT_DIR/nmap-$SCAN_DATE.txt"# 检查开放端口open_ports=$(ss -tlnp | grep -v 127.0.0.1 | wc -l)echo "Open network ports: $open_ports"# SSL/TLS检查if command -v testssl.sh >/dev/null 2>&1; thentestssl.sh --quiet --jsonfile "$REPORT_DIR/ssl-$SCAN_DATE.json" https://your-claude-endpoint.comfi
}# 安全告警发送
send_security_alert() {local message="$1"echo "$(date): SECURITY ALERT - $message" >> "$REPORT_DIR/security-alerts.log"# 发送到安全团队curl -X POST -H 'Content-type: application/json' \--data "{\"text\":\"🚨 ClaudeCode Security Alert: $message\"}" \"$SECURITY_SLACK_WEBHOOK" 2>/dev/null || true
}# 执行安全扫描
main() {echo "Starting security scan at $(date)"container_security_scanconfig_security_checknetwork_security_check# 生成安全报告{echo "# ClaudeCode Security Scan Report - $SCAN_DATE"echo ""echo "## Container Security"jq '.Results[].Vulnerabilities[]? | select(.Severity=="HIGH" or .Severity=="CRITICAL")' \"$REPORT_DIR/trivy-$SCAN_DATE.json" 2>/dev/null || echo "No critical vulnerabilities found"echo ""echo "## Configuration Security"if [ -s "$REPORT_DIR/permissions-$SCAN_DATE.txt" ]; thenecho "### Permissions Issues:"cat "$REPORT_DIR/permissions-$SCAN_DATE.txt"elseecho "No permission issues found"fiecho ""echo "## Network Security"echo "Open ports:"cat "$REPORT_DIR/nmap-$SCAN_DATE.txt" | grep "open"} > "$REPORT_DIR/security-report-$SCAN_DATE.md"echo "Security scan completed. Report saved to $REPORT_DIR/security-report-$SCAN_DATE.md"
}# 定时执行（添加到crontab）
# 0 2 * * * /opt/claude/scripts/security-scan.shmain "$@"

6.4.3 自动化运维流程

CI/CD集成

# .github/workflows/claude-deploy.yml
name: ClaudeCode Deploymenton:push:branches: [main]pull_request:branches: [main]env:REGISTRY: ghcr.ioIMAGE_NAME: ${{ github.repository }}/claudejobs:test:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v3- name: Setup Node.jsuses: actions/setup-node@v3with:node-version: '18'cache: 'npm'- name: Install dependenciesrun: npm ci- name: Run testsrun: npm test- name: Run security scanuses: securecodewarrior/github-action-add-sarif@v1with:sarif-file: 'security-scan-results.sarif'build:needs: testruns-on: ubuntu-latestpermissions:contents: readpackages: writesteps:- name: Checkoutuses: actions/checkout@v3- name: Log in to Container Registryuses: docker/login-action@v2with:registry: ${{ env.REGISTRY }}username: ${{ github.actor }}password: ${{ secrets.GITHUB_TOKEN }}- name: Extract metadataid: metauses: docker/metadata-action@v4with:images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}tags: |type=ref,event=branchtype=ref,event=prtype=sha,prefix={{branch}}-type=raw,value=latest,enable={{is_default_branch}}- name: Build and pushuses: docker/build-push-action@v4with:context: .platforms: linux/amd64,linux/arm64push: truetags: ${{ steps.meta.outputs.tags }}labels: ${{ steps.meta.outputs.labels }}deploy:if: github.ref == 'refs/heads/main'needs: [test, build]runs-on: ubuntu-latestenvironment: productionsteps:- name: Deploy to productionuses: appleboy/ssh-action@v0.1.7with:host: ${{ secrets.PROD_HOST }}username: ${{ secrets.PROD_USER }}key: ${{ secrets.PROD_SSH_KEY }}script: |cd /opt/claude./scripts/deploy.sh production ${{ github.sha }}- name: Health checkrun: |sleep 30curl -f https://your-claude-endpoint.com/health || exit 1- name: Notify deploymentuses: 8398a7/action-slack@v3with:status: ${{ job.status }}channel: '#deployments'webhook_url: ${{ secrets.SLACK_WEBHOOK }}

备份与恢复自动化

#!/bin/bash
# backup-restore.shBACKUP_ROOT="/backup/claude"
RETENTION_DAYS=30
S3_BUCKET="claude-backups"# 备份函数
backup_data() {local backup_date=$(date +%Y%m%d-%H%M%S)local backup_dir="$BACKUP_ROOT/$backup_date"echo "Starting backup: $backup_date"mkdir -p "$backup_dir"# 备份配置文件tar czf "$backup_dir/config.tar.gz" -C /opt/claude config/# 备份用户数据docker exec claude-prod tar czf - /app/data | cat > "$backup_dir/data.tar.gz"# 备份数据库（如果使用）if docker ps | grep -q postgres; thendocker exec postgres-claude pg_dump -U claude claude_db | \gzip > "$backup_dir/database.sql.gz"fi# 生成备份清单{echo "Backup created: $backup_date"echo "Backup size: $(du -sh $backup_dir | cut -f1)"echo "Files included:"find "$backup_dir" -type f -exec basename {} \;} > "$backup_dir/manifest.txt"# 上传到云存储if command -v aws >/dev/null 2>&1; thenaws s3 sync "$backup_dir" "s3://$S3_BUCKET/$backup_date/" \--storage-class STANDARD_IAecho "Backup uploaded to S3: s3://$S3_BUCKET/$backup_date/"fiecho "Backup completed: $backup_dir"
}# 清理旧备份
cleanup_old_backups() {echo "Cleaning up backups older than $RETENTION_DAYS days"find "$BACKUP_ROOT" -maxdepth 1 -type d -mtime +$RETENTION_DAYS -print0 | \xargs -0 -r rm -rf# 清理云存储中的旧备份if command -v aws >/dev/null 2>&1; thenaws s3api list-objects-v2 --bucket "$S3_BUCKET" \--query "Contents[?LastModified<='$(date -d "$RETENTION_DAYS days ago" -Iseconds)'].Key" \--output text | xargs -r -n1 aws s3 rm "s3://$S3_BUCKET/"fi
}# 恢复函数
restore_data() {local backup_date="$1"local backup_dir="$BACKUP_ROOT/$backup_date"if [ ! -d "$backup_dir" ]; thenecho "Backup not found locally, attempting to download from S3..."if command -v aws >/dev/null 2>&1; thenmkdir -p "$backup_dir"aws s3 sync "s3://$S3_BUCKET/$backup_date/" "$backup_dir/"elseecho "ERROR: Backup $backup_date not found"return 1fifiecho "Starting restore from backup: $backup_date"# 停止服务docker-compose -f /opt/claude/docker-compose.prod.yml down# 恢复配置if [ -f "$backup_dir/config.tar.gz" ]; thentar xzf "$backup_dir/config.tar.gz" -C /opt/claude/fi# 恢复数据if [ -f "$backup_dir/data.tar.gz" ]; thendocker run --rm -v claude-data:/app/data -v "$backup_dir":/backup \alpine tar xzf /backup/data.tar.gz -C /fi# 恢复数据库if [ -f "$backup_dir/database.sql.gz" ]; thenzcat "$backup_dir/database.sql.gz" | \docker exec -i postgres-claude psql -U claude claude_dbfi# 重启服务docker-compose -f /opt/claude/docker-compose.prod.yml up -decho "Restore completed from backup: $backup_date"
}# 列出可用备份
list_backups() {echo "Available local backups:"ls -la "$BACKUP_ROOT" | grep "^d" | awk '{print $9}' | grep -E '^[0-9]{8}-[0-9]{6}$'if command -v aws >/dev/null 2>&1; thenecho ""echo "Available S3 backups:"aws s3 ls "s3://$S3_BUCKET/" | awk '{print $2}' | sed 's/\/$//'fi
}# 验证备份完整性
verify_backup() {local backup_date="$1"local backup_dir="$BACKUP_ROOT/$backup_date"echo "Verifying backup: $backup_date"local errors=0# 检查必需文件for file in config.tar.gz data.tar.gz manifest.txt; doif [ ! -f "$backup_dir/$file" ]; thenecho "ERROR: Missing file $file"((errors++))fidone# 验证压缩文件完整性if ! tar tzf "$backup_dir/config.tar.gz" >/dev/null 2>&1; thenecho "ERROR: config.tar.gz is corrupted"((errors++))fiif ! tar tzf "$backup_dir/data.tar.gz" >/dev/null 2>&1; thenecho "ERROR: data.tar.gz is corrupted"((errors++))fiif [ $errors -eq 0 ]; thenecho "Backup verification passed"return 0elseecho "Backup verification failed with $errors errors"return 1fi
}# 主函数
case "${1:-}" inbackup)backup_datacleanup_old_backups;;restore)if [ -z "${2:-}" ]; thenecho "Usage: $0 restore <backup_date>"echo "Available backups:"list_backupsexit 1firestore_data "$2";;list)list_backups;;verify)if [ -z "${2:-}" ]; thenecho "Usage: $0 verify <backup_date>"exit 1fiverify_backup "$2";;*)echo "Usage: $0 {backup|restore|list|verify} [backup_date]"echo ""echo "Commands:"echo "  backup          Create a new backup"echo "  restore <date>  Restore from backup"echo "  list           List available backups"echo "  verify <date>  Verify backup integrity"exit 1;;
esac