OpsKeeper
快速上手

快速开始

本指南带你本地跑起 OpsKeeper 的闭环演示场景。需要 Docker、Go 1.25+、Node.js 20+ 和 pnpm 9+ —— Makefile 会帮你检查这些依赖。

前置依赖

  • Docker 24+ 含 Compose 插件
  • Go 1.25+（见 .tool-versions）
  • Node.js 20+ 与 pnpm 9+
  • Python 3.11+（仅插件测试需要）
  • zip / tar / 标准 POSIX 工具

1. 安装

克隆仓库，在仓库根目录启动本地环境：

bootstrap
git clone https://github.com/vincent-wuhan/opskeeper.git
cd opskeeper
cp deploy/demo.env.example .env

# 构建并启动整套演示环境（首次构建需要几分钟）
docker compose up -d --build
docker compose ps                      # 等待所有服务 healthy

# 校验控制平面健康（opskeeper 的 HTTP 端口是 8080）
curl -fsS http://localhost:8080/healthz

2. 写入场景

deploy/incident-events/ 下有四个可复现的 PostgreSQL 场景，用 incident-seed 工具把它们写入事件记忆库：

seed
# 先校验数据集（不写数据库）
go run ./cmd/incident-seed -dry-run -dir deploy/incident-events

# 把 4 个场景全部写入事件记忆库
go run ./cmd/incident-seed \
  -dsn "postgres://opskeeper:opskeeper@localhost:5432/opskeeper?sslmode=disable" \
  -dir deploy/incident-events

写入的事件覆盖连接池耗尽、磁盘 I/O 饱和、锁等待 / 长事务、副本 replay 延迟。通过事件 API 查看指标、召回日志与 runbook：

inspect
# 控制平面提供的事件指标 + runbook
curl -fsS "http://localhost:8080/v1/incidents/metrics" | jq .
curl -fsS "http://localhost:8080/v1/incidents/runbooks" | jq .

3. 打开 Web Console

OpsKeeper 的 Web Console 是一个 React + Vite SPA，位于 web/，通过 /api/v1 与控制平面通信。

web
cd web
pnpm install --frozen-lockfile
pnpm dev
# → http://localhost:5173

4. 安装一个 Worker 插件

把 TeamHarness MCP 代理塞进任何讲 stdio MCP 的 Worker。它暴露 17 个工具，使用 Bearer + HMAC 鉴权，全部通过环境变量配置：

plugin
cd plugins/opskeeper-teamharness

OPSKEEPER_BACKEND_URL=http://localhost:8080 \
OPSKEEPER_GATEWAY_KEY="$GATEWAY_KEY" \
OPSKEEPER_TENANT_ID=default \
python3 mcp/server.py

AgentTeams Dashboard 插件包请运行 make build-plugins，然后在 Dashboard 里安装生成的 zip（热部署：qwenpaw plugin install <path> --force）。

演示

写入场景后，跑一遍验证 Harness，确认 Manager、critic、verifier 都正确接入。每个场景都是带 runner 容器的独立 compose 栈：

verify
# 在插件目录下执行 —— alert_storm / rca_loop / recovery_verify
bash plugins/opskeeper-teamharness/eval/scenarios/alert_storm/run.sh
bash plugins/opskeeper-teamharness/eval/scenarios/rca_loop/run.sh
bash plugins/opskeeper-teamharness/eval/scenarios/recovery_verify/run.sh

下一步

阅读 架构 文档，了解数据平面、Manager 派发表和安全边界。