星战科技xingzhan.cloud
返回市场
医生船

医生船

作者：hwclass2 星标更新：2025-11-02
安装使用来源：spider==github.com

项目介绍

<div align="center"> <img src="logo.png" alt="Docktor Logo" width="400"/>

基于Docker AI堆栈的容器原生自动扩展

使用LLMs和MCP监控并扩展Docker Compose服务的自主SRE代理。

Docker Model Runner MCP cagent

</div>

🚀 快速开始

前提条件：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

配置字段

字段类型默认值描述
servicestringweb监控的Docker Compose服务名称
compose_filestringexamples/docker-compose.yaml组合文件路径
scaling.cpu_highfloat75.0触发扩展的CPU百分比阈值
scaling.cpu_lowfloat20.0触发缩减的CPU百分比阈值
scaling.min_replicasint2最小副本数（高可用性）
scaling.max_replicasint10最大副本数（成本/容量限制）
scaling.scale_up_byint2扩展时增加的副本数
scaling.scale_down_byint1缩减时减少的副本数
scaling.check_intervalint10自动扩展检查之间的秒数
scaling.metrics_windowint10收集和平均指标的秒数

多服务及队列感知扩展

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 - 所有容器的平均CPU
  • cpu.min - 最小CPU
  • cpu.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_outpkg/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
}

要添加一个新的队列后端：

  1. 实现Provider接口
  2. 通过queue.Register("yourqueue", NewYourQueueProvider)在init()中注册
  3. 在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      │           │
│                          └─────────────────┘           │
└─────────────────────────────────────────────────────────┘

安装

前提条件

  1. Docker Desktop，启用Model Runner（捆绑提供）

  2. cagent CLI：

    # macOS
brew install cagent

# Linux
# 参见：https://github.com/docker/cagent

  3. Go 1.21+：

    brew install go

构建

git clone https://github.com/hwclass/docktor
cd docktor
go build -o docktor ./cmd/docktor

配置（可选）

对于云LLM或自定义模型设置：