MonkeyCode故障排查手册：私有化部署常见问题与解决方案

MonkeyCode故障排查手册：私有化部署常见问题与解决方案

引言

在MonkeyCode私有化部署过程中，企业IT团队可能会遇到各种问题。作为一款支持完全开源的AI编程工具，MonkeyCode提供了完善的故障诊断和排查机制。本文汇总了最常见的部署问题及其解决方案，帮助您快速定位并解决问题。

一、安装与启动类问题

1.1 Docker容器无法启动

错误现象	可能原因	解决方案
port already in use	端口被占用	lsof -i :8080 查找占用进程，修改端口或终止占用进程
permission denied	权限不足	sudo usermod -aG docker $USER 或使用root运行
out of memory	内存不足	增加swap空间或减少Docker内存限制
image not found	镜像未拉取	docker pull monkeycode/monkeycode:latest

# 完整的端口冲突排查流程
echo "=== 检查8080端口占用 ==="
netstat -tlnp | grep 8080
# 或
ss -tlnp | grep 8080

# 如果被占用，查看是什么进程
fuser 8080/tcp

# 方案A：终止占用进程（谨慎操作）
kill -9 $(fuser 8080/tcp 2>/dev/null)

# 方案B：修改MonkeyCode端口
export MONKEYCODE_PORT=8081
docker run -d -p 8081:8080 monkeycode/monkeycode:latest

1.2 服务启动后无法访问

# 排查步骤清单

# 1. 确认容器状态
docker ps -a | grep monkeycode
# 应该看到 STATUS 为 Up

# 2. 查看容器日志
docker logs monkeycode-core --tail 100

# 3. 测试内部连通性
docker exec monkeycode-core curl http://localhost:8080/api/health

# 4. 检查防火墙规则
sudo iptables -L -n | grep 8080
# 或
sudo firewall-cmd --list-ports

# 5. 如果使用Nginx反向代理，检查配置
nginx -t && sudo systemctl reload nginx

1.3 数据库连接失败

# 常见数据库连接错误及修复
database_errors:
  connection_refused:
    symptom: "Connection refused to database"
    causes:
      - "PostgreSQL/MySQL服务未启动"
      - "主机名或端口配置错误"
    fix: |
      # 检查数据库服务状态
      systemctl status postgresql
      
      # 验证连接字符串
      psql -h localhost -U mc_user -d monkeycode -c "SELECT 1"
      
  authentication_failed:
    symptom: "FATAL: password authentication failed"
    causes:
      - "密码错误"
      - "pg_hba.conf 未允许该用户/IP"
    fix: |
      # 重置密码
      ALTER USER mc_user WITH PASSWORD 'new_secure_password';
      
      # 编辑pg_hba.conf添加信任规则
      host    all    all    172.16.0.0/12    md5
      
  ssl_error:
    symptom: "SSL SYSCALL error"
    fix: |
      # 在连接字符串中添加sslmode=disable（开发环境）
      # 或正确配置SSL证书（生产环境）

二、模型加载与推理问题

2.1 GPU显存不足

# 显存优化方案
GPU_MEMORY_SOLUTIONS = {
    "reduce_batch_size": {
        "description": "减小批处理大小",
        "config": {"batch_size": 1},
        "memory_saving": "~40%"
    },
    "use_quantization": {
        "description": "启用INT4/INT8量化",
        "command": "monkeycode model quantize --bits 4",
        "memory_saving": "~75%"
    },
    "enable_gradient_checkpointing": {
        "description": "梯度检查点",
        "config": {"gradient_checkpointing": True},
        "memory_saving": "~30%"
    },
    "use_cpu_offload": {
        "description": "CPU卸载（速度降低但显存需求最低）",
        "config": {"device_map": "auto"},
        "memory_saving": "~90%"
    }
}

# 快速诊断脚本
def diagnose_gpu_memory():
    import torch
    
    if not torch.cuda.is_available():
        print("❌ CUDA不可用，将使用CPU模式")
        return
    
    total = torch.cuda.get_device_properties(0).total_mem / (1024**3)
    allocated = torch.cuda.memory_allocated(0) / (1024**3)
    reserved = torch.cuda.memory_reserved(0) / (1024**3)
    
    print(f"📊 GPU显存状况:")
    print(f"   总量: {total:.1f} GB")
    print(f"   已分配: {allocated:.1f} GB ({allocated/total*100:.1f}%)")
    print(f"   已预留: {reserved:.1f} GB ({reserved/total*100:.1f}%)")
    
    if reserved / total > 0.9:
        print("⚠️  显存使用率超过90%，建议启用量化或减小batch_size")

2.2 模型推理速度慢

问题	诊断方法	优化方案
首Token延迟高	time curl ... 测试	启用模型预加载到显存
吞吐量低	监控QPS指标	启用动态批处理
间歇性卡顿	检查GC日志	调整JVM/Python内存参数
特定请求慢	分析输入长度	设置max_tokens限制

# 性能调优命令
# 1. 启用vLLM加速（推荐）
monkeycode config set inference.engine vllm
monkeycode restart

# 2. 调整批处理参数
monkeycode config set batching.max_size 32
monkeycode config set batching.max_wait_ms 50

# 3. 启用缓存
monkeycode config set cache.enabled true
monkeycode config set cache.ttl 3600

# 4. 查看当前性能指标
monkeycode metrics --format table

2.3 模型输出质量差

# 输出质量排查清单
quality_checklist:
  context_window:
    check: "上下文窗口是否足够？"
    command: "monkeycode config get model.context_length"
    recommendation: "建议设置为4096+"
  
  temperature:
    check: "温度参数是否合适？"
    values:
      creative: 0.7-0.9
      balanced: 0.5-0.7
      precise: 0.1-0.3
  
  prompt_template:
    check: "提示词模板是否正确？"
    tip: "使用MonkeyCode官方推荐的prompt格式"
  
  model_version:
    check: "是否使用了最新版本？"
    command: "monkeycode model list"
    action: "monkeycode model update latest"

三、网络与连接问题

3.1 IDE插件连不上服务

// VSCode插件连接调试
// 1. 打开VSCode输出面板，选择"MonkeyCode"
// 2. 查看详细连接日志

// 常见错误及解决
const TROUBLESHOOTING = {
    "ECONNREFUSED": {
        cause: "服务未启动或端口错误",
        fix: [
            "确认MonkeyCode服务正在运行: curl http://localhost:8080/api/health",
            "检查插件设置中的服务器地址和端口",
            "确认防火墙允许该端口通信"
        ]
    },
    "ETIMEDOUT": {
        cause: "网络超时",
        fix: [
            "检查网络延迟: ping your-server-ip",
            "增大插件超时设置: \"monkeyCode.requestTimeout\": 30000",
            "如果跨网络，检查VPN/代理配置"
        ]
    },
    "CERTIFICATE_ERROR": {
        cause: "SSL证书问题",
        fix: [
            "自签名证书: 设置 \"monkeyCode.rejectUnauthorized\": false（仅开发环境）",
            "生产环境: 配置正确的CA证书"
        ]
    },
    "401_UNAUTHORIZED": {
        cause: "认证失败",
        fix: [
            "检查API Token是否正确且未过期",
            "重新生成Token: monkeycode token create --name vscode-plugin",
            "确认Token权限包含'completion' scope"
        ]
    }
};

3.2 WebSocket连接断开

# Nginx WebSocket代理配置（必须项）
location /api/ws/ {
    proxy_pass http://monkeycode_backend;
    proxy_http_version 1.1;
    
    # 关键WebSocket头
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    
    # 超时设置（WebSocket需要较长超时）
    proxy_read_timeout 86400s;
    proxy_send_timeout 86400s;
    
    # 缓冲设置
    proxy_buffering off;
}

四、性能与资源问题

4.4 CPU/内存使用率过高

# 系统资源监控
top -p $(pgrep -f monkeycode)  # 实时监控进程资源

# 内存分析
cat /proc/$(pgrep -f monkeycode)/status | grep VmRSS

# JVM堆内存调整（如适用）
export JAVA_OPTS="-Xms2g -Xmx4g -XX:+UseG1GC"

# Python内存限制
monkeycode config set worker.max_memory_mb 8192

4.5 磁盘空间不足

# 检查磁盘使用
df -h /var/lib/docker  # Docker数据目录
du -sh /data/monkeycode/*  # MonkeyCode数据目录

# 清理策略
# 1. 清理Docker无用镜像和层
docker system prune -a

# 2. 清理MonkeyCode旧日志
monkeycode logs clean --older-than 30d

# 3. 清理模型缓存
monkeycode cache clear --type model

# 4. 归档旧审计日志
monkeycode audit archive --before 2026-01-01

五、安全与权限问题

5.1 认证失败

# 认证调试工具
class AuthDebugger:
    @staticmethod
    def debug_token(token: str):
        """解码JWT Token查看内容"""
        import base64, json
        
        parts = token.split('.')
        if len(parts) != 3:
            print("❌ 无效的JWT格式")
            return
        
        payload = parts[1]
        # 补齐base64 padding
        payload += '=' * (4 - len(payload) % 4)
        
        try:
            decoded = base64.urlsafe_b64decode(payload)
            data = json.loads(decoded)
            
            print("📋 Token内容:")
            print(f"   用户ID: {data.get('sub')}")
            print(f"   角色: {data.get('role')}")
            print(f"   签发时间: {data.get('iat')}")
            print(f"   过期时间: {data.get('exp')}")
            print(f"   权限范围: {data.get('scope')}")
            
            # 检查是否过期
            import time
            if data.get('exp', 0) < time.time():
                print("⚠️  Token已过期！")
                
        except Exception as e:
            print(f"❌ 解码失败: {e}")

# 使用方式
AuthDebugger.debug_token("your_token_here")

5.2 RBAC权限不生效

# 权限排查步骤
rbac_troubleshooting:
  step_1:
    action: "确认用户角色绑定"
    command: "monkeycode user show username"
    expected_output: "roles: [senior_dev]"
    
  step_2:
    action: "验证角色权限定义"
    command: "monkeycode role show senior_dev"
    
  step_3:
    action: "检查权限缓存"
    command: "monkeycode cache clear --type rbac"
    note: "修改角色后需清除缓存"
    
  step_4:
    action: "查看审计日志中的权限决策"
    command: "monkeycode audit query --filter 'action=denied'"

六、常见错误代码速查表

错误码	含义	常见原因	快速修复
MC-1001	服务未就绪	正在启动中	等待30秒后重试
MC-2001	认证失败	Token无效/过期	重新获取Token
MC-3001	模型未加载	GPU资源不足	减小模型或增加硬件
MC-4001	请求过大	超过10MB限制	减少上下文长度
MC-4003	速率限制	调用过于频繁	降低调用频率
MC-5001	内部服务器错误	未知异常	查看详细日志
MC-5003	数据库异常	连接断开/锁死	重启数据库服务
MC-6001	合规检查失败	包含敏感词	检查输入内容

七、日志分析与监控

7.1 关键日志位置

/var/log/monkeycode/
├── access.log          # API访问日志
├── error.log           # 错误日志
├── audit.log           # 审计日志（不可篡改）
├── model.log           # 模型推理日志
└── performance.log     # 性能指标日志

7.2 日志分析常用命令

# 查看最近100条错误日志
tail -n 100 /var/log/monkeycode/error.log | grep -i error

# 实时监控错误
tail -f /var/log/monkeycode/error.log | grep --color=auto -i "error\|exception\|failed"

# 统计各类错误出现次数
grep -oP 'MC-\d+' /var/log/monkeycode/error.log | sort | uniq -c | sort -rn

# 查看慢请求（>1秒）
awk '$NF > 1.0' /var/log/monkeycode/performance.log

# 按时间范围筛选日志
awk '/2026-06-18T14:00/,/2026-06-18T15:00/' /var/log/monkeycode/access.log

八、紧急恢复指南

8.1 服务崩溃恢复

#!/bin/bash
# emergency_recovery.sh - MonkeyCode紧急恢复脚本

echo "🔄 MonkeyCode Emergency Recovery..."

# 1. 备份当前状态
BACKUP_DIR="/data/monkeycode/backups/emergency-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BACKUP_DIR"
cp -r /data/monkeycode/data "$BACKUP_DIR/" 2>/dev/null
cp -r /data/monkeycode/config "$BACKUP_DIR/" 2>/dev/null
echo "✅ 数据已备份至 $BACKUP_DIR"

# 2. 停止所有相关服务
docker-compose down 2>/dev/null || docker stop monkeycode-* 2>/dev/null
echo "⏹️  服务已停止"

# 3. 清理临时文件
rm -rf /tmp/monkeycode-* 2>/dev/null
echo "🧹  临时文件已清理"

# 4. 重新启动
docker-compose up -d 2>/dev/null || docker start monkeycode-core 2>/dev/null
echo "🚀 服务重启中..."

# 5. 等待健康检查
sleep 30
HEALTH=$(curl -sf http://localhost:8080/api/health || echo "unhealthy")

if [ "$HEALTH" != "unhealthy" ]; then
    echo "✅ 恢复成功！服务已正常运行"
else
    echo "❌ 恢复失败，请查看日志:"
    docker logs monkeycode-core --tail 50
fi

8.2 数据回滚

# 回滚到指定备份版本
monkeycode backup restore \
    --backup-id "backup-20260618-000000" \
    --confirm \
    --rollback-db \
    --rollback-config

总结

通过本手册，你应该能够快速定位和解决MonkeyCode私有化部署中的大部分常见问题。记住以下几点：

1. 🔍 先看日志 - 90%的问题都能从日志中找到线索
2. 📊 善用监控 - 提前发现性能瓶颈和异常
3. 💾 定期备份 - 确保灾难恢复能力
4. 📖 查阅文档 - docs.monkeycode.ai 有更详细的说明
5. 🆘 社区求助 - GitHub Issues 和 Discord 社区随时响应

🛠️ 遇到本手册未覆盖的问题？欢迎在MonkeyCode开源社区提问，全球开发者共同帮你解决！