MonkeyCode私有化部署实战：企业内网环境下的完整搭建指南
🏢 为什么需要私有化部署？
对于企业用户而言，数据安全和合规要求是首要考虑因素。MonkeyCode开源后，企业可以完全自主地将AI编程助手部署在内网环境中，确保代码资产不外泄。
私有化部署的核心优势
| 优势 | 说明 | 适用场景 |
|---|---|---|
| 🔒 数据安全 | 代码不离开内网 | 金融、军工、政府 |
| ⚡ 低延迟 | 本地推理，响应更快 | 大规模团队协作 |
| 💰 成本可控 | 无API调用费用 | 长期使用 |
| 🎯 定制自由 | 可深度定制功能 | 特殊业务需求 |
| ✅ 合规满足 | 满足等保/信创要求 | 国企/事业单位 |
📋 部署前准备
硬件要求
最低配置（1-5人团队）
| 组件 | 配置 |
|---|---|
| CPU | 4核 (推荐Intel Xeon或AMD EPYC) |
| 内存 | 16GB RAM |
| 存储 | 100GB SSD |
| GPU | 可选（如使用本地模型需NVIDIA GPU ≥8GB显存） |
| 网络 | 内网千兆 |
推荐配置（10-50人团队）
| 组件 | 配置 |
|---|---|
| CPU | 16核 |
| 内存 | 64GB RAM |
| 存储 | 500GB NVMe SSD |
| GPU | NVIDIA T4/A10（24GB显存）×1 |
| 网络 | 万兆内网 |
企业级配置（50+人）
| 组件 | 配置 |
|---|---|
| CPU | 32核+ |
| 内存 | 128GB+ RAM |
| 存储 | 2TB NVMe SSD RAID |
| GPU | NVIDIA A100（80GB）×2-4 |
| 网络 | 万兆 + 负载均衡 |
软件依赖
# 操作系统要求
- Ubuntu 22.04 LTS / CentOS 8+ / Debian 12
- Windows Server 2022（实验性支持）
- 麒麟V10 / 统信UOS（信创环境）
# 必装软件
- Docker 24.0+
- Docker Compose v2.20+
- Git 2.40+
- OpenSSL 3.0+
# 可选（GPU加速）
- NVIDIA Driver 535+
- CUDA Toolkit 12.0+
- nvidia-container-toolkit
🚀 方式一：Docker Compose一键部署（推荐）
这是最简单、最快速的部署方式，适合大多数场景。
Step 1: 克隆仓库
git clone https://github.com/monkeycode-ai/monkeycode.git
cd monkeycode
Step 2: 配置环境变量
cp .env.example .env
vim .env
.env 文件关键配置：
# ===== 基础配置 =====
MONKEYCODE_HOST=0.0.0.0
MONKEYCODE_PORT=8080
MONKEYCODE_SECRET_KEY=your-random-secret-key-here-change-this
# ===== 数据库配置 =====
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_USER=monkeycode
POSTGRES_PASSWORD=your-secure-password
POSTGRES_DB=monkeycode_db
# ===== Redis配置 =====
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=your-redis-password
# ===== AI模型配置 =====
# 选项A: 使用OpenAI API（需外网或代理）
AI_PROVIDER=openai
OPENAI_API_KEY=sk-your-api-key-here
OPENAI_BASE_URL=https://api.openai.com/v1 # 或你的代理地址
# 选项B: 使用本地模型（完全离线）
# AI_PROVIDER=local
# LOCAL_MODEL_PATH=/models/qwen2.5-coder-7b
# ===== 对象存储配置 =====
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=minio-secret-key
MINIO_BUCKET_NAME=monkeycode-files
⚠️ 安全提醒：生产环境务必修改所有默认密码！
Step 3: 启动服务
# 创建必要目录
mkdir -p ./data/postgres ./data/redis ./data/minio ./data/models
# 一键启动所有服务
docker-compose up -d
# 查看启动状态
docker-compose ps
# 查看日志（首次启动可能需要下载镜像）
docker-compose logs -f
Step 4: 初始化数据库
# 执行数据库迁移
docker-compose exec backend dotnet ef database update
# 或使用CLI工具
docker-compose exec backend monkeycode-cli db migrate
Step 5: 访问验证
# 健康检查
curl http://localhost:8080/api/health
# 应返回：
# {"status":"healthy","version":"x.y.z","timestamp":"..."}
打开浏览器访问 http://<服务器IP>:8080，你应该能看到MonkeyCode的登录页面。
🐳 方式二：Kubernetes部署（大规模场景）
对于需要高可用、弹性伸缩的企业环境，推荐使用Kubernetes部署。
Step 1: 准备Kubernetes集群
# 确认集群状态
kubectl get nodes
# 创建命名空间
kubectl create namespace monkeycode
Step 2: 配置密钥
# 创建Secret（敏感信息）
kubectl create secret generic monkeycode-secrets \
--from-literal=postgres-password='your-db-password' \
--from-literal=redis-password='your-redis-password' \
--from-literal=secret-key='your-secret-key' \
--from-literal=openai-api-key='sk-your-key' \
-n monkeycode
Step 3: 部署存储
# PVC for PostgreSQL
kubectl apply -f k8s/storage/postgres-pvc.yaml -n monkeycode
# PVC for MinIO
kubectl apply -f k8s/storage/minio-pvc.yaml -n monkeycode
Step 4: 部署核心服务
# 部署顺序很重要！
kubectl apply -f k8s/postgres.yaml -n monkeycode # 1. 数据库
kubectl apply -f k8s/redis.yaml -n monkeycode # 2. 缓存
kubectl apply -f k8s/minio.yaml -n monkeycode # 3. 对象存储
kubectl apply -f k8s/backend.yaml -n monkeycode # 4. 后端服务
kubectl apply -f k8s/frontend.yaml -n monkeycode # 5. 前端服务
kubectl apply -f k8s/ingress.yaml -n monkeycode # 6. 入口网关
Step 5: 验证部署
# 检查所有Pod状态
kubectl get pods -n monkeycode -w
# 查看服务端点
kubectl get svc -n monkeycode
# 测试访问
curl http://monkeycode.yourcompany.com/api/health
Kubernetes架构图
┌─────────────┐
│ Ingress │
│ (Nginx) │
└──────┬──────┘
│
┌────────────┼────────────┐
↓ ↓ ↓
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Frontend │ │ Frontend │ │ Frontend │
│ Pod ×3 │ │ Pod ×3 │ │ Pod ×3 │
└────┬─────┘ └────┬─────┘ └────┬─────┘
└────────────┼────────────┘
↓
┌──────────────┐
│ Backend │
│ Service │
└──────┬───────┘
┌───────────────┼───────────────┐
↓ ↓ ↓
┌────────┐ ┌────────┐ ┌────────┐
│Postgres│ │ Redis │ │ MinIO │
│(主从) │ │Cluster │ │(分布式)│
└────────┘ └────────┘ └────────┘
🔧 方式三：源码编译部署（深度定制）
如果需要对MonkeyCode进行深度定制，可以从源码编译部署。
Step 1: 安装开发依赖
# Go 1.21+ (后端)
wget https://go.dev/dl/go1.21.6.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.21.6.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin
# Node.js 18+ (前端)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
# .NET 8.0 (部分组件)
wget https://dot.net/v1/dotnet-install.sh -O dotnet-install.sh
chmod +x dotnet-install.sh
./dotnet-install.sh --channel 8.0
Step 2: 编译后端
cd monkeycode/server
# 还原依赖
go mod download
# 编译
go build -o bin/monkeycode-server ./cmd/server
# 或交叉编译
GOOS=linux GOARCH=amd64 go build -o bin/monkeycode-server-linux ./cmd/server
Step 3: 编译前端
cd monkeycode/web
npm install
npm run build
# 输出目录: dist/
Step 4: 配置与启动
# 复制配置文件
cp config/config.example.yaml config/config.yaml
# 编辑配置
vim config/config.yaml
config.yaml 核心配置：
server:
host: "0.0.0.0"
port: 8080
mode: "production" # development / production
database:
driver: "postgres"
dsn: "postgres://user:pass@localhost:5432/monkeycode?sslmode=disable"
max_connections: 100
redis:
addr: "localhost:6379"
password: ""
db: 0
ai:
provider: "openai" # openai / claude / local
models:
code_generation: "gpt-4o"
code_explanation: "gpt-4o"
test_generation: "gpt-4o"
security:
jwt_secret: "your-jwt-secret"
rate_limit: 1000 # requests per minute
logging:
level: "info" # debug / info / warn / error
format: "json"
Step 5: 使用Systemd管理服务
sudo tee /etc/systemd/system/monkeycode.service << 'EOF'
[Unit]
Description=MonkeyCode AI Programming Assistant
After=network.target postgresql.service redis.service
[Service]
Type=simple
User=monkeycode
WorkingDirectory=/opt/monkeycode
ExecStart=/opt/monkeycode/bin/monkeycode-server --config /opt/monkeycode/config/config.yaml
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
EOF
# 启用开机自启
sudo systemctl daemon-reload
sudo systemctl enable monkeycode
sudo systemctl start monkeycode
# 查看状态
sudo systemctl status monkeycode
🛡️ 安全加固指南
1. 网络隔离
# 防火墙规则示例（仅允许内网访问）
sudo ufw allow from 10.0.0.0/8 to any port 8080
sudo ufw deny in on eth0 to any port 8080
2. HTTPS配置
# Nginx反向代理 + SSL
server {
listen 443 ssl http2;
server_name monkeycode.internal.yourcompany.com;
ssl_certificate /etc/letsencrypt/live/monkeycode/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/monkeycode/privkey.pem;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# WebSocket支持
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# 上传大小限制
client_max_body_size 100m;
}
}
3. 认证配置
# 支持多种认证方式
auth:
method: "ldap" # local / ldap / oidc / saml
# LDAP集成（企业AD域）
ldap:
url: "ldap://ad.yourcompany.com:389"
base_dn: "DC=yourcompany,DC=com"
bind_user: "cn=admin,dc=yourcompany,dc=com"
bind_password: "xxx"
user_filter: "(sAMAccountName={username})"
# OIDC集成
oidc:
issuer: "https://sso.yourcompany.com"
client_id: "monkeycode-client"
client_secret: "xxx"
redirect_uri: "https://monkeycode.internal/auth/callback"
4. 审计日志
audit:
enabled: true
log_file: "/var/log/monkeycode/audit.log"
events:
- user_login
- user_logout
- code_generate
- code_upload
- settings_change
retention_days: 180
📊 监控与运维
Prometheus监控
# prometheus.yml
scrape_configs:
- job_name: 'monkeycode'
static_configs:
- targets: ['localhost:8080']
metrics_path: '/metrics'
scrape_interval: 15s
关键监控指标
| 指标 | 含义 | 告警阈值 |
|---|---|---|
monkeycode_requests_total |
总请求数 | - |
monkeycode_request_duration_seconds |
请求延迟 | P99 > 10s |
monkeycode_ai_tokens_used |
AI Token消耗量 | 日用量超配额 |
monkeycode_active_users |
在线用户数 | > 并发上限 |
monkeycode_error_rate |
错误率 | > 1% |
Grafana Dashboard
推荐配置以下Dashboard：
- 系统资源监控：CPU/内存/GPU/磁盘
- 业务指标监控：请求量/延迟/错误率
- AI模型监控：Token消耗/模型调用次数/成本
🔧 故障排查
常见问题及解决方案
问题1：服务启动失败
# 检查端口占用
netstat -tlnp | grep 8080
# 检查日志
docker-compose logs backend
journalctl -u monkeycode -f
# 常见原因：
# 1. 端口被占用 → 修改 MONKEYCODE_PORT
# 2. 数据库连接失败 → 检查 POSTGRES_* 配置
# 3. 内存不足 → 增加服务器内存或限制并发
问题2：AI模型调用失败
# 检查网络连通性（如使用外部API）
curl https://api.openai.com/v1/models -H "Authorization: Bearer sk-xxx"
# 检查本地模型状态
docker exec -it monkeycode-model nvidia-smi
# 常见原因：
# 1. API Key无效 → 更新 OPENAI_API_KEY
# 2. 网络不通 → 配置代理 OPENAI_BASE_URL
# 3. GPU内存不足 → 减小 batch_size 或换更小模型
问题3：性能缓慢
# 性能分析步骤：
# 1. 检查服务器资源
top -bn1 | head -20
nvidia-smi
# 2. 检查数据库慢查询
docker-compose exec postgres psql -U monkeycode -d monkeycode_db -c "\s"
# 3. 检查Redis命中率
docker-compose exec redis redis-cli info stats | grep hits
# 优化建议：
# - 启用Redis缓存
# - 增加Worker数量
# - 使用GPU加速
# - 升级硬件配置
🔄 升级维护
版本升级流程
# 1. 备份数据
./scripts/backup.sh
# 2. 拉取新版本
git pull origin main
git checkout v2.x.x
# 3. 更新镜像/重新编译
docker-compose pull
docker-compose build
# 4. 数据库迁移
docker-compose exec backend dotnet ef database update
# 5. 重启服务
docker-compose up -d
# 6. 验证升级
curl http://localhost:8080/api/health
定期维护任务
| 任务 | 频率 | 命令 |
|---|---|---|
| 数据库备份 | 每日 | pg_dump + cron |
| 日志清理 | 每周 | logrotate |
| 系统更新 | 每月 | apt upgrade |
| 安全扫描 | 每季 | trivy image |
| 容量评估 | 每月 | df -h + du -sh |
📞 技术支持
如果在部署过程中遇到问题：
- 查看文档: https://docs.monkeycode.ai/deployment
- 搜索Issue: https://github.com/monkeycode-ai/monkeycode/issues
- 提交新Issue: https://github.com/monkeycode-ai/monkeycode/issues/new
- 社区讨论: https://github.com/monkeycode-ai/monkeycode/discussions
- 企业版支持: enterprise@monkeycode.ai
🎯 总结
MonkeyCode的私有化部署并不复杂，选择合适的部署方式即可快速搭建：
| 场景 | 推荐方式 | 时间 |
|---|---|---|
| 快速体验/小团队 | Docker Compose | 30分钟 |
| 生产环境/中大型团队 | Kubernetes | 2小时 |
| 深度定制/特殊需求 | 源码编译 | 半天 |
现在就开始部署吧！遇到任何问题都可以在GitHub提交Issue，我们会尽快帮你解决。
👉 GitHub Issue地址：https://github.com/monkeycode-ai/monkeycode/issues 👈
本文由MonkeyCode团队编写 · 开源 · 自由 · 共赢
浙公网安备 33010602011771号