项目介绍
<div align="center">
<img src="logo.png" alt="Docktor Logo" width="400"/>
基于Docker AI堆栈的容器原生自动扩展
使用LLMs和MCP监控并扩展Docker Compose服务的自主SRE代理。
🚀 快速开始
前提条件：Docker Desktop + Model Runner, cagent, Go 1.21+（参见安装）
自主守护进程模式（推荐）
为了实现完全自主的24/7操作 - 不需要用户干预：
# 1. 克隆并构建
git clone https://github.com/hwclass/docktor
cd docktor
go build -o docktor ./cmd/docktor
# 2. 启动自主守护进程（自动扩展）
./docktor daemon start
# 3. 生成负载以触发扩展（在另一个终端中）
# 选项A：增量负载模拟器（推荐用于演示）
bash examples/single-service/load-incremental.sh
# 选项B：快速测试 - 瞬时高负载（90秒）
bash examples/single-service/load-quick.sh
# 4. 实时监控守护进程
./docktor daemon logs
# 5. 检查状态
./docktor daemon status
# 6. 完成后停止守护进程
./docktor daemon stop
高级选项：
# 自定义组合文件和服务
./docktor daemon start --compose-file ./production.yaml --service api
# 手动模式（每个动作都需要批准）
./docktor daemon start --manual
交互模式（学习用）
为了通过聊天界面进行交互式探索 - 需要用户干预：
# 1. 运行Docktor（打开cagent TUI）
./docktor ai up
# 2. 在TUI中发送消息以启动自动扩展：
# 输入："现在开始自动扩展web服务"
# 3. 生成负载（在另一个终端中）
bash examples/load-cpu.sh
# 4. 观看容器扩展
bash examples/watch.sh
模式比较：
- 守护进程（推荐）：完全自主，后台运行，不需要用户输入
- 交互：手动聊天界面，适合了解决策过程
📖 完整的测试指南：参见AUTOSCALE_GUIDE.md
⚙️ 配置
Docktor 使用 docktor.yaml 文件进行每个应用的扩展配置。这允许自定义阈值而无需更改代码。
示例配置
# docktor.yaml
version: "1"
service: web
compose_file: docker-compose.yaml
scaling:
cpu_high: 75.0 # 当CPU ≥ 75%时扩展
cpu_low: 20.0 # 当CPU ≤ 20%时缩减
min_replicas: 2 # 不会低于2个副本（高可用性）
max_replicas: 10 # 不会超过10个副本（容量限制）
scale_up_by: 2 # 扩展时增加2个副本
scale_down_by: 1 # 缩减时减少1个副本
check_interval: 10 # 每10秒检查一次
metrics_window: 10 # 平均10秒内的指标
使用配置
# 使用默认的docktor.yaml
./docktor daemon start
# 使用自定义配置
./docktor daemon start --config my-app.yaml
# 覆盖特定值
./docktor daemon start --config prod.yaml --service api
配置字段
| 字段 | 类型 | 默认值 | 描述 |
|---|---|---|---|
service | string | web | 监控的Docker Compose服务名称 |
compose_file | string | examples/docker-compose.yaml | 组合文件路径 |
scaling.cpu_high | float | 75.0 | 触发扩展的CPU百分比阈值 |
scaling.cpu_low | float | 20.0 | 触发缩减的CPU百分比阈值 |
scaling.min_replicas | int | 2 | 最小副本数（高可用性） |
scaling.max_replicas | int | 10 | 最大副本数（成本/容量限制） |
scaling.scale_up_by | int | 2 | 扩展时增加的副本数 |
scaling.scale_down_by | int | 1 | 缩减时减少的副本数 |
scaling.check_interval | int | 10 | 自动扩展检查之间的秒数 |
scaling.metrics_window | int | 10 | 收集和平均指标的秒数 |
多服务及队列感知扩展
Docktor支持同时监控多个服务，并具有队列感知扩展功能（NATS JetStream、RabbitMQ、Kafka即将推出）。
多服务配置
# docktor.yaml
version: "1"
compose_file: docker-compose.yaml
# 监控多个服务及其不同配置
services:
- name: web
min_replicas: 2
max_replicas: 10
check_interval: 10
metrics_window: 10
rules:
scale_up_when:
- metric: cpu.avg
op: ">"
value: 75.0
scale_down_when:
- metric: cpu.avg
op: "<"
value: 20.0
- name: consumer
min_replicas: 1
max_replicas: 20
check_interval: 10
metrics_window: 10
rules:
scale_up_when:
# 或逻辑：如果任何条件匹配则扩展
- metric: queue.backlog
op: ">"
value: 500
- metric: queue.rate_in
op: ">"
value: 200
scale_down_when:
# 与逻辑：只有所有条件都匹配时才缩减
- metric: queue.backlog
op: "<="
value: 100
- metric: queue.rate_in
op: "<"
value: 150
queue:
kind: nats
url: nats://nats:4222
jetstream: true
stream: EVENTS
consumer: WEB_WORKERS
subject: events.web
可用指标
CPU指标（始终可用）：
cpu.avg- 所有容器的平均CPUcpu.min- 最小CPUcpu.max- 最大CPU
队列指标（当配置队列时）：
queue.backlog- 消费者的待处理消息queue.lag- 流头与消费者之间的消息queue.rate_in- 接收消息速率（每秒消息数）queue.rate_out- 处理速率（每秒消息数）
扩展逻辑
扩展规则：或逻辑 - 如果任何条件匹配则扩展 缩减规则：与逻辑 - 只有所有条件匹配时才缩减
这可以防止过早缩减，同时允许快速响应扩展需求。
示例：NATS JetStream队列扩展
# 运行完整的NATS示例
cd examples/multi-service/nats-queue
docker compose up -d
cd ../../..
./docktor daemon start --config examples/multi-service/nats-queue/docktor.yaml
# 监控扩展决策
./docktor explain --tail 20
# 验证配置
./docktor config validate
📖 完整的NATS示例：参见examples/multi-service/nats-queue/README.md
队列插件架构
Docktor使用可扩展的插件系统来支持队列后端。当前和计划的支持：
| 队列系统 | 状态 | 可用指标 | 插件位置 |
|---|---|---|---|
| NATS JetStream | ✅ 可用 | backlog, lag, rate_in, rate_out | pkg/queue/nats.go |
| RabbitMQ | 🔜 计划 | 队列深度, 消费者数量, 率 | 即将推出 |
| Apache Kafka | 🔜 计划 | 消费者滞后, 分区偏移量 | 即将推出 |
| Redis Streams | 🔜 计划 | 待处理条目, 消费者组滞后 | 即将推出 |
| AWS SQS | 🔜 计划 | 可用消息, 在途 | 即将推出 |
添加新的队列后端：
插件接口定义在pkg/queue/queue.go：
type Provider interface {
Connect() error
GetMetrics(windowSec int) (*Metrics, error)
Validate() error
Close() error
}
要添加一个新的队列后端：
- 实现
Provider接口 - 通过
queue.Register("yourqueue", NewYourQueueProvider)在init()中注册 - 在
docktor.yaml中添加配置，使用kind: yourqueue
参见pkg/queue/nats.go作为参考实现。
📚 参见AGENTS.md 获取代理指令详细信息和agents.md规范。
🤖 LLM模型选择
Docktor支持切换不同的LLM模型来进行自动扩展决策。选择最适合您需求的模型 - 从轻量级本地模型到强大的云LLM。
快速开始
# 列出Docker Model Runner中的可用模型
./docktor config list-models
# 切换到特定模型
./docktor config set-model ai/granite-4.0-h-micro
# 切换到OpenAI
./docktor config set-model gpt-4o-mini --provider=openai --base-url=https://api.openai.com/v1
# 然后设置：export OPENAI_API_KEY=sk-...
# 使用选定模型启动守护进程
./docktor daemon start
模型提供商
Docker Model Runner (DMR) - 推荐用于本地
- ✅ 完全免费且私密
- ✅ 不需要API密钥
- ✅ 可离线工作
- 可用模型：Llama 3.2, IBM Granite, Phi-3, SmolLM2等
兼容OpenAI的提供商
- OpenAI (GPT-4, GPT-4o-mini)
- Anthropic Claude（通过代理）
- Azure OpenAI
- 任何兼容OpenAI的端点
配置
LLM配置存储在docktor.yaml中：
llm:
provider: dmr # "dmr"或"openai"
base_url: "http://localhost:12434/engines/llama.cpp/v1" # API端点
model: "ai/llama3.2" # 模型ID
# 对于OpenAI或兼容提供商：
# llm:
# provider: openai
# base_url: "https://api.openai.com/v1"
# model: "gpt-4o-mini"
# 然后：export OPENAI_API_KEY=sk-...
决策来源
每个自动扩展决策包括显示哪个模型做出该决策的元数据：
{
"timestamp": "2024-03-15T10:30:45Z",
"iteration": 42,
"avg_cpu": 87.3,
"action": "scale_up",
"current_replicas": 2,
"target_replicas": 4,
"reason": "CPU高至87.3%",
"metadata": {
"provider": "dmr",
"model": "ai/granite-4.0-h-micro"
}
}
这允许您：
- 比较不同模型的决策质量
- 审计在事件期间活跃的模型
- 对您的工作负载进行模型性能基准测试
示例：切换模型
# 使用Llama 3.2（快速，轻量级）
./docktor config set-model ai/llama3.2
./docktor daemon start
# ...观察扩展行为...
./docktor daemon stop
# 使用IBM Granite（企业级）
./docktor config set-model ai/granite-4.0-h-micro
./docktor daemon start
# ...比较决策质量...
./docktor daemon stop
# 比较日志以查看哪个模型表现更好
grep '"metadata"' /tmp/docktor-daemon.log | jq '.metadata.model' | sort | uniq -c
⚠️ 已知限制
Llama 3.2（3B）模型约束：
使用Docker Model Runner和Llama 3.2（3.21B参数）时，可能会遇到：
- 不一致的约束执行（可能违反
min_replicas） - 类型转换问题（工具调用中的数字变为字符串）
- 不完整的自主循环（初始迭代后停止）
生产推荐：
# 选项1：使用云LLM（更可靠）
# 创建.env.cagent：
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4 # 或gpt-4-turbo, claude-3-opus
# 选项2：通过Docker Model Runner使用更大的本地模型
# 使用Llama 3.1（70B）或Qwen 2.5（32B）以获得更好的可靠性
✅ Llama 3.2适用于演示和测试 🚀 使用GPT-4或Claude进行生产工作负载
Docktor是什么？
Docktor是一个使用本地LLM进行智能扩展决策的Docker Compose服务自动扩展系统。
关键特性
- 🤖 AI原生：使用Docker Model Runner中的Llama 3.2（3B）进行决策
- 📊 动态扩展：代理计算最优副本数（非硬编码）
- 🔍 可解释性：每个决策都有完整的MCP审计跟踪
- 🏠 完全本地化：无需API密钥，无云依赖
- 🐳 Docker原生：与标准组合文件一起工作
工作原理
每隔约60秒：
1. get_metrics → 从所有'web'容器收集CPU%
2. analyze → LLM计算平均值，计数副本
3. decide → 如果CPU > 80%：扩展（+2）
如果CPU < 20%：缩减（-1）
否则：保持稳定
4. apply_scale → 执行docker compose --scale web=N
所有操作都通过MCP记录，以实现全面可观测性。
架构
┌─────────────────────────────────────────────────────────┐
│ DOCKER DESKTOP │
│ │
│ ┌────────────────┐ ┌──────────────┐ │
│ │ Model Runner │────────▶│ Llama 3.2 3B │ │
│ │ (llama.cpp) │ │ (本地LLM) │ │
│ └────────────────┘ └──────┬───────┘ │
│ │ │
│ ┌──────────▼────────┐ │
│ │ cagent │ │
│ │ (AI代理) │ │
│ └──────────┬────────┘ │
│ │ │
│ │ MCP (JSON-RPC) │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Docktor MCP │ │
│ │ • get_metrics │ │
│ │ • detect_anomaly│ │
│ │ • propose_scale │ │
│ │ • apply_scale │ │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Docker Compose │ │
│ │ web: ×1-10 │ │
│ │ lb: ×1 │ │
│ │ redis: ×1 │ │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────┘
安装
前提条件
-
Docker Desktop，启用Model Runner（捆绑提供）
-
cagent CLI：
# macOS brew install cagent # Linux # 参见：https://github.com/docker/cagent -
Go 1.21+：
brew install go
构建
git clone https://github.com/hwclass/docktor
cd docktor
go build -o docktor ./cmd/docktor
配置（可选）
对于云LLM或自定义模型设置：