logclaw-mcp-server

LogClaw

部署在你的 VPC 中的 AI SRE。 实时异常检测、与追踪数据关联的事件工单，以及 AI 根因分析——你的日志永远不会离开你的基础设施。

---

TL;DR — 立即试用

选项 A：托管云（无需安装——最快）

立即在 console.logclaw.ai 体验完整功能——包括 AI 根因分析、API 密钥管理、多租户隔离和完整的事件处理流程。无需 Docker。

选项 B：Docker Compose（可自托管，无需 Kubernetes）

curl -O https://raw.githubusercontent.com/logclaw/logclaw/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/logclaw/logclaw/main/otel-collector-config.yaml
docker compose up -d

打开 http://localhost:3000 ——LogClaw 堆栈正在运行：

• 仪表板（:3000）——事件、日志采集、配置
• OTel Collector（:4317 gRPC、:4318 HTTP）——通过 OTLP 发送日志
• Bridge（:8080）——异常检测 + 追踪关联
• Ticketing Agent（:18081）——AI 驱动的事件管理
• OpenSearch（:9200）——日志存储 + 搜索
• Kafka（:9092）——事件总线

所有镜像均从 ghcr.io/logclaw/ 拉取——无需注册表身份验证。

注意： 本地堆栈以单租户模式运行，且已禁用由大模型驱动的根因分析。如需使用 AI RCA、API 密钥管理和多租户隔离，请使用托管云，或通过 LLM_PROVIDER=claude|openai|ollama 部署到 Kubernetes。

选项 C：Kind 集群（完整 Kubernetes 堆栈）

git clone https://github.com/logclaw/logclaw.git && cd logclaw
./scripts/setup-dev.sh

此操作会创建 Kind 集群、安装所有运算符和服务、构建仪表板并运行冒烟测试。在配备 16 GB 内存的笔记本电脑上大约需要 20 分钟。

容器镜像

所有 LogClaw 镜像都作为公开软件包发布到 GHCR：

服务	镜像	最新稳定版
仪表板	ghcr.io/logclaw/logclaw-dashboard	stable / 2.5.0
Bridge	ghcr.io/logclaw/logclaw-bridge	stable / 1.3.0
Ticketing Agent	ghcr.io/logclaw/logclaw-ticketing-agent	stable / 1.5.0
Flink Jobs	ghcr.io/logclaw/logclaw-flink-jobs	stable / 0.1.1

直接拉取任意镜像：

docker pull ghcr.io/logclaw/logclaw-dashboard:stable

---

实际效果

事件管理	AI 根因分析
日志采集	仪表板概览

在线演示： console.logclaw.ai | 视频演示： logclaw.ai

---

开源版 vs 云端版 vs 企业版

功能	开源版（免费）	云端版（$0.30/GB）	企业版（定制）
日志摄取（OTLP）	无限制	每天免费 1 GB	无限制
异常检测	Z-score 统计分析	Z-score + ML 流水线	Z-score + ML + 定制模型
AI 根因分析	自带 LLM（Ollama/OpenAI/Claude）	已包含	已包含 + 微调模型
事件工单	PagerDuty、Jira、ServiceNow、OpsGenie、Slack、Zammad	全部 6 个平台	全部 6 个平台 + 定制连接器
仪表板	完整 UI（日志、事件、配置）	完整 UI + 托管服务	完整 UI + 白标选项
身份验证	无（开放访问）	Clerk OAuth + 组织管理	SSO（SAML/OIDC）+ RBAC
多租户	单租户	多组织、多项目、多环境	每个租户完全隔离命名空间
API 密钥	不适用	每个项目单独配置、使用 SHA-256 哈希、可撤销	每个项目单独配置 + 定制范围
数据驻留	你的基础设施	LogClaw 管理的云端	你的 VPC（AWS/Azure/GCP）
密钥加密	静态加密（OpenSearch）	静态加密 + 传输中加密	密钥使用 AES-256-GCM 加密 + 完整 TLS
配置管理	环境变量	6 个选项卡的设置 UI	UI + API + GitOps
保留期限	可通过 Helm 配置	日志保留 9 天，事件保留 97 天	定制保留策略
隔离网络模式	支持（Zammad + Ollama）	不支持	支持
MCP 服务	可自托管	托管（mcp.logclaw.ai）	两种方式均可
支持	GitHub Issues	电子邮件（[email protected]）	专属 SRE 团队 + SLA
定价	永久免费（Apache 2.0）	每摄取 1 GB 收费 $0.30	定制

不按席位收费。不按主机收费。所有级别均包含 AI 功能。

免费开始使用（云端版）  |  从 GitHub 部署（OSS）  |  预约演示（企业版）

---

架构

以下所有组件均包含在每个级别中——开源版、云端版和企业版。

LogClaw Stack (per tenant, namespace-isolated)
│
├── logclaw-auth-proxy       API key validation + tenant ID injection
├── logclaw-otel-collector   OpenTelemetry Collector (OTLP gRPC + HTTP)
├── logclaw-ingestion        Vector.dev edge ingestion (optional)
├── logclaw-kafka            Strimzi Kafka 3-broker KRaft cluster
├── logclaw-flink            ETL + enrichment + anomaly scoring
├── logclaw-opensearch       OpenSearch cluster (hot-tier log storage)
├── logclaw-bridge           OTLP ETL + trace correlation + lifecycle manager
├── logclaw-ml-engine        Feast Feature Store + KServe/TorchServe + Ollama
├── logclaw-airflow          Apache Airflow (ML training DAGs)
├── logclaw-ticketing-agent  AI-powered RCA + multi-platform ticketing
├── logclaw-agent            In-cluster infrastructure health collector
├── logclaw-dashboard        Next.js web UI (ingestion, incidents, config, dark mode)
└── logclaw-console          Enterprise SaaS console (multi-tenant)

数据流： 日志 → Auth Proxy（API 密钥 + 注入租户信息）→ OTel Collector（OTLP 摄取）→ Kafka → Bridge（ETL + 异常检测 + 追踪关联）→ OpenSearch + 工单 Agent → 事件工单

所有图表均由 logclaw-tenant umbrella chart 连接在一起——一次 helm install 即可为一个租户部署完整技术栈。

---

快速开始（生产环境 / ArgoCD）

前置条件

一次性集群设置（操作符，每个集群运行一次）：

helmfile -f helmfile.d/00-operators.yaml apply

接入新租户

1. 复制模板：

   cp gitops/tenants/_template.yaml gitops/tenants/tenant-<id>.yaml
   

2. 填写必需的值（tenantId、tier、cloudProvider、密钥存储配置）。

3. 提交并推送——ArgoCD 会检测到新文件，并在约 30 分钟内部署完整技术栈。

手动安装（开发/预发布环境）

helm install logclaw-acme charts/logclaw-tenant \
  --namespace logclaw-acme \
  --create-namespace \
  -f gitops/tenants/tenant-acme.yaml

---

本地运行（分步指南）

想用一条命令完成设置？运行 ./scripts/setup-dev.sh，然后跳到第 6 步。

前置条件

# macOS (Homebrew)
brew install helm helmfile kind kubectl node python3

# Helm plugins
helm plugin install https://github.com/databus23/helm-diff
helm plugin install https://github.com/helm-unittest/helm-unittest

# Docker Desktop must be running
open -a Docker

1 — 创建本地 Kubernetes 集群

make kind-create

验证：

kubectl cluster-info --context kind-logclaw-dev

2 — 安装集群级操作符

make install-operators

等待操作符就绪（约 3 分钟）：

kubectl get pods -n strimzi-system -w
kubectl get pods -n opensearch-operator-system -w

3 — 安装完整的租户技术栈

make install TENANT_ID=dev-local STORAGE_CLASS=standard

这会按依赖顺序部署全部 16 个 helmfile 发行版。监控进度：

watch kubectl get pods -n logclaw-dev-local

时间	里程碑
T+2 分钟	命名空间、RBAC、NetworkPolicies
T+6 分钟	Kafka broker 就绪
T+10 分钟	OpenSearch 集群状态变为绿色
T+15 分钟	Bridge + Ticketing Agent 正在运行
T+20 分钟	完整技术栈已投入运行

4 — 构建并部署仪表板

仪表板需要构建 Docker 镜像：

docker build -t logclaw-dashboard:dev apps/dashboard/
kind load docker-image logclaw-dashboard:dev --name logclaw-dev

helm upgrade --install logclaw-dashboard-dev-local charts/logclaw-dashboard \
  --namespace logclaw-dev-local \
  --set global.tenantId=dev-local \
  -f charts/logclaw-dashboard/ci/default-values.yaml

5 — 访问服务

# Dashboard (main UI)
kubectl port-forward svc/logclaw-dashboard-dev-local 3333:3000 -n logclaw-dev-local
open http://localhost:3333

# OpenSearch (query API)
kubectl port-forward svc/logclaw-opensearch-dev-local 9200:9200 -n logclaw-dev-local

# Airflow (ML pipelines)
kubectl port-forward svc/logclaw-airflow-dev-local-webserver 8080:8080 -n logclaw-dev-local
open http://localhost:8080   # admin / admin

6 — 发送日志

LogClaw 通过 OTLP（OpenTelemetry Protocol） 接收日志，这是 CNCF 行业标准。为 OTel Collector 设置端口转发：

kubectl port-forward svc/logclaw-otel-collector-dev-local 4318:4318 -n logclaw-dev-local &

通过 OTLP HTTP 发送单条日志：

curl -X POST http://localhost:4318/v1/logs \
  -H "Content-Type: application/json" \
  -d '{
    "resourceLogs": [{
      "resource": {
        "attributes": [
          {"key": "service.name", "value": {"stringValue": "payment-api"}}
        ]
      },
      "scopeLogs": [{
        "logRecords": [{
          "timeUnixNano": "'$(date +%s)000000000'",
          "severityText": "ERROR",
          "body": {"stringValue": "Connection refused to database"},
          "traceId": "abcdef1234567890abcdef1234567890",
          "spanId": "abcdef12345678"
        }]
      }]
    }]
  }'

任何 OpenTelemetry SDK 或 Agent 都可以向 LogClaw 发送日志，无需自定义集成。SDK 示例请参阅 OTLP 集成指南。

生成并导入 900 条 Apple Pay 示例日志：

# Generate sample OTel logs
python3 scripts/generate-applepay-logs.py    # → 500 payment flow logs
python3 scripts/generate-applepay-logs-2.py  # → 400 infra/security errors

# Ingest them
./scripts/ingest-logs.sh scripts/applepay-otel-500.json
./scripts/ingest-logs.sh scripts/applepay-otel-400-batch2.json

也可以使用辅助脚本：

./scripts/ingest-logs.sh --generate   # generates + ingests all sample logs
./scripts/ingest-logs.sh --smoke      # single test log

7 — 查看运行效果

导入错误日志后，Bridge 会检测异常，Ticketing Agent 会创建事件工单。查看这些工单：

# Watch Bridge trace correlation in real-time
kubectl logs -f deployment/logclaw-bridge-dev-local -n logclaw-dev-local

# Check auto-created incidents
kubectl port-forward svc/logclaw-opensearch-dev-local 9200:9200 -n logclaw-dev-local &
curl -s 'http://localhost:9200/logclaw-incidents-*/_search?size=5&sort=created_at:desc' | python3 -m json.tool

# Or use the Dashboard
open http://localhost:3333/incidents

8 — 拆除

# Remove just the tenant
make uninstall TENANT_ID=dev-local

# Remove everything including the Kind cluster
make kind-delete

---

仓库布局

charts/
├── logclaw-tenant/           # Umbrella chart — single install entry point
├── logclaw-auth-proxy/       # API key validation + tenant ID injection
├── logclaw-otel-collector/   # OpenTelemetry Collector (OTLP gRPC + HTTP)
├── logclaw-ingestion/        # Vector.dev edge ingestion
├── logclaw-kafka/            # Strimzi Kafka + KafkaConnect + MirrorMaker2
├── logclaw-flink/            # Flink ETL + enrichment + anomaly jobs
├── logclaw-opensearch/       # OpenSearch cluster via Opster operator
├── logclaw-bridge/           # OTLP ETL + trace correlation + lifecycle manager
├── logclaw-ml-engine/        # Feast + KServe/TorchServe + Ollama
├── logclaw-airflow/          # Apache Airflow
├── logclaw-ticketing-agent/  # AI-powered RCA + multi-platform ticketing
├── logclaw-agent/            # In-cluster infrastructure health agent
├── logclaw-dashboard/        # Next.js web UI
└── logclaw-console/          # Enterprise SaaS console

apps/
├── bridge/                # Python — OTLP ETL + anomaly detection + trace correlation
├── agent/                 # Go — infrastructure health collector
├── dashboard/             # Next.js — web UI (incidents, logs, config, dark mode)
├── ticketing-agent/       # Python — AI-powered RCA + multi-platform ticketing
├── flink-jobs/            # Java — Flink stream processing jobs
├── logclaw-auth-proxy/    # TypeScript/Express — API key validation + tenant injection
├── logclaw-slack-bot/     # TypeScript/Hono — Slack incident bot (Cloudflare Workers)
├── logclaw-mcp-server/    # TypeScript — MCP server for AI coding tools (8 tools)
└── logclaw-mcp-remote/    # TypeScript — remote MCP client (OAuth 2.1)

cli/                        # Go CLI (logclaw start/stop/status)

scripts/
├── setup-dev.sh                # One-command local dev setup (Kind cluster)
├── setup-gke.sh                # GKE production cluster setup
├── ingest-logs.sh              # Log ingestion helper (--generate, --smoke)
├── generate-applepay-logs.py   # Generate 500 OTel sample logs (batch 1)
├── generate-applepay-logs-2.py # Generate 400 infra/security logs (batch 2)
├── trigger-anomaly.sh          # Trigger test anomaly for demo
└── trigger-request-failure.sh  # Trigger test request failure for demo

operators/                    # Cluster-level operator bootstrap (once per cluster)
├── strimzi/                  # strimzi-kafka-operator 0.41.0
├── flink-operator/           # flink-kubernetes-operator 1.9.0
├── opensearch-operator/      # opensearch-operator 2.6.1
├── eso/                      # external-secrets 0.10.3
└── cert-manager/             # cert-manager v1.16.1

helmfile.d/                   # Ordered helmfile releases (00-operators → 90-dashboard)
gitops/                       # ArgoCD ApplicationSet + per-tenant value files
tests/                        # Helm chart tests + integration test pods
docs/                         # Architecture, onboarding, values reference

---

主要功能

如需并排比较不同版本，请参阅上文的 开源版、云版与企业版。

与追踪关联的 AI 工单引擎

Bridge 运行一个 5 层追踪关联引擎：

1. ETL 消费者 — 从 Kafka 消费增强后的日志
2. 异常检测器 — 对错误率进行统计异常评分
3. OpenSearch 索引器 — 为日志建立索引，以便搜索和关联
4. 生命周期引擎 — 追踪跨服务的因果链，计算影响范围，并创建／去重事件

检测到异常时，系统会：

• 查询所有共享同一 trace_id 的日志
• 构建因果链，展示错误如何在服务间传播
• 计算影响范围（受影响服务的百分比）
• 创建去重后的事件工单，并附上完整的追踪上下文

多平台工单管理

logclaw-ticketing-agent 支持同时使用 6 个可独立开关的平台：

平台	类型	出站流量
PagerDuty	SaaS	外部 HTTPS
Jira	SaaS	外部 HTTPS
ServiceNow	SaaS	外部 HTTPS
OpsGenie	SaaS	外部 HTTPS
Slack	SaaS	外部 HTTPS
Zammad	集群内	无外部出站流量

按严重程度路由（critical → PagerDuty、medium → Jira 等）可通过 config.routing.* 配置。

断网模式

与 Zammad（外部 ITSM 图表）和用于本地大模型推理的 Ollama 配合时，needsExternalHttps 助手会将 NetworkPolicy 设置为无外部出站流量，实现完全断网。日志、工单或模型调用都不会离开集群。

大模型提供商抽象

global:
  llm:
    provider: ollama   # claude | openai | ollama | vllm | disabled
    model: llama3.2:8b

仪表板

仪表板提供：

• 深色模式 — 自动适配系统设置，并支持手动切换（浅色／深色／系统）；设置保存在 localStorage 中
• 拖放上传 — 支持 JSON、NDJSON、CSV 和纯文本文件
• 批量事件操作 — 选择多个事件并批量确认、解决或升级
• CSV 导出 — 将事件下载为 CSV 文件
• 加载骨架屏 — 数据加载期间显示流畅的动画占位内容
• 错误边界 — 发生崩溃时提供平稳恢复，并显示重试界面
• 大模型回退标记 — 大模型根因分析不可用并改用基于规则的回退方案时显示提示
• 事件自动去重 — 防止同一异常创建重复事件

日志导入 — 原生支持 OTLP

LogClaw 仅使用 OTLP（OpenTelemetry Protocol） 作为日志导入协议，这是 CNCF 行业标准，受到所有主流可观测性供应商（Datadog、Splunk、Grafana、AWS、GCP、Azure）的支持。

支持的传输方式：

• gRPC — <collector>:4317（高吞吐场景推荐）
• HTTP/JSON — <collector>:4318/v1/logs

任何 OpenTelemetry SDK、Agent 或 Collector 都可以直接向 LogClaw 发送日志，无需自定义集成。OTel Collector 会为每条日志添加 tenant_id，将其分批处理，并使用 otlp_json 编码写入 Kafka。

{
  "resourceLogs": [{
    "resource": {
      "attributes": [
        {"key": "service.name", "value": {"stringValue": "my-service"}},
        {"key": "host.name", "value": {"stringValue": "my-service-pod-abc12"}}
      ]
    },
    "scopeLogs": [{
      "logRecords": [{
        "timeUnixNano": "1709510400000000000",
        "severityText": "ERROR",
        "body": {"stringValue": "Something went wrong"},
        "traceId": "abcdef1234567890abcdef1234567890",
        "spanId": "abcdef12345678",
        "attributes": [
          {"key": "environment", "value": {"stringValue": "production"}}
        ]
      }]
    }]
  }]
}

Python、Java 和 Node.js SDK 示例请参阅 OTLP 集成指南。

MCP 服务 — AI 编码工具

logclaw-mcp-server 通过 Model Context Protocol 将 AI 编码工具连接到 LogClaw 事件、日志和异常。作为 npm 包发布，包含 8 个工具。

npx logclaw-mcp-server

可与 Claude Code、Cursor、Windsurf 以及任何兼容 MCP 的客户端配合使用。也可作为托管服务使用，地址为 https://mcp.logclaw.ai（OAuth 2.1，无需安装）。

有关设置说明，请参阅 MCP 集成指南。

Slack 机器人 — 事件通知

logclaw-slack-bot 可将实时事件通知发送到 Slack，支持丰富的 Block Kit 格式、私信和 OAuth。运行于 Cloudflare Workers。

有关设置，请参阅集成。

Auth Proxy — API 密钥验证

logclaw-auth-proxy 位于入口和 OTel Collector 之间。它会针对 PostgreSQL 验证 API 密钥，将 tenant_id 注入 OTLP 负载，并强制执行速率限制（未认证请求为 200 req/min，每个租户为 6000 req/min）。它是无状态的，可水平扩展。

---

组件版本

组件	版本
Apache Kafka (Strimzi)	3.7.0
Apache Flink	1.19.0
OpenSearch	2.14.0
External Secrets Operator	0.10.3
cert-manager	v1.16.1
Apache Airflow	1.14.0
Zammad	12.4.1
OpenTelemetry Collector Contrib	0.114.0
KServe	0.13.0
Feast	0.40.0
Next.js（仪表板）	16.1.6

---

开发

仪表板（Next.js）

cd apps/dashboard
npm install
npm run dev
# → http://localhost:3000

Bridge（Python）

cd apps/bridge
pip install -r requirements.txt
export KAFKA_BROKERS="localhost:9092"
export OPENSEARCH_ENDPOINT="http://localhost:9200"
python main.py
# → HTTP API on :8080 (/health, /metrics, /config)

配置参考请参阅 Bridge 文档。

工单 Agent（Python）

cd apps/ticketing-agent
pip install -r requirements.txt
export KAFKA_BROKERS="localhost:9092"
export OPENSEARCH_ENDPOINT="http://localhost:9200"
python main.py
# → HTTP API on :8080

Agent（Go）

cd apps/agent
go run main.go
# → HTTP API on :8080 (/health, /ready, /metrics)

Auth Proxy（TypeScript）

cd apps/logclaw-auth-proxy
npm install
npm run dev
# → HTTP API on :4318

需要一个包含 API 密钥的 PostgreSQL 数据库。请参阅 API 密钥文档。

MCP 服务（TypeScript）

cd apps/logclaw-mcp-server
npm install && npm run build
LOGCLAW_API_KEY=lc_proj_test npx .

Helm Charts

# Lint all charts
make lint

# Render templates (dry-run, no cluster needed)
make template TENANT_ID=ci-test

# Diff current vs new
make template-diff TENANT_ID=dev-local

# Package charts as .tgz
make package

# Push to OCI registry
make push HELM_REGISTRY=oci://ghcr.io/logclaw/charts

---

文档

完整文档请访问 docs.logclaw.ai。

快速入门：

• 快速入门 — 发送日志
• API 密钥
• 本地开发
• 架构

组件：

• Bridge — 异常检测 + Trace 关联
• 仪表板 — Web UI
• 工单 Agent — 多平台事件路由
• OTel Collector — OTLP 数据接入
• 事件分类 — 综合评分

集成：

• 集成概览 — PagerDuty、Jira、ServiceNow、OpsGenie、Slack
• MCP 服务 — Claude Code、Cursor、Windsurf

参考：

• OTLP 集成指南 — Python、Java、Node.js、Go SDK 示例
• Values 参考 — Helm chart 配置
• 接入新租户
• API 参考

企业版：

• 企业控制台 — 多组织、API 密钥管理、项目设置

---

贡献

欢迎贡献！提交 PR 前，请阅读我们的指南：

• 贡献指南
• 行为准则
• 安全策略

请使用问题模板提交 Bug 报告和功能请求。

---

许可证

Apache 2.0 — 详见 LICENSE