deploy-observability

部署阿里云可观测性 MCP 服务

概述

本技能将指导用户部署和管理阿里云可观测性 MCP 服务，内容包括：

• 首次部署 — 克隆、构建、配置凭据、启动、生成 Agent 配置
• Docker 部署 — 适用于服务器的容器化设置
• 项目更新 — 拉取最新代码、检测变更、重新构建、报告新增工具

该服务为阿里云日志服务（SLS）、云监控（CMS）和 AI 驱动的可观测性提供 60 多种工具。它可以在本地运行（stdio），也可以作为远程 HTTP 服务运行（sse/streamable-http）。

阶段 0：部署前检查

开始任何部署前，先运行以下检查以了解环境：

检测已有安装

# Check if already installed in common locations
for dir in ~/alibabacloud-observability-mcp-server ~/.alibabacloud-observability-mcp-server /opt/alibabacloud-observability-mcp-server; do
  if [ -d "$dir" ] && [ -f "$dir/bin/alibabacloud-observability-mcp-server" ]; then
    echo "Found installation at: $dir"
    "$dir/bin/alibabacloud-observability-mcp-server" version
  fi
done

如果检测到已有安装，请询问用户：

检测到已有安装，是否要更新？还是全新安装到其他位置？

检查 Go 环境

go version 2>/dev/null && echo "Go OK" || echo "Go NOT FOUND"

如果尚未安装 Go：

未安装 Go（需要 >= 1.23）。请前往 https://go.dev/dl/ 下载安装，或使用包管理器：

• macOS：brew install go
• Ubuntu/Debian：sudo apt install golang-go
• CentOS：sudo yum install golang

检查网络

curl -s --connect-timeout 5 https://github.com > /dev/null && echo "GitHub OK" || echo "GitHub UNREACHABLE"

如果无法访问 GitHub（在中国较常见）：

无法访问 GitHub。请检查网络连接，或使用镜像站：

• git clone https://ghproxy.com/https://github.com/aliyun/alibabacloud-observability-mcp-server.git

---

阶段 1：首次部署

询问用户要安装到哪里（默认：~/Projects/alibabacloud-observability-mcp-server）。

获取二进制文件有两种方式。让用户选择：

步骤 1.1a — 下载预构建的二进制文件（最快，推荐）

# macOS arm64 (M1/M2/M3/M4)
wget https://github.com/aliyun/alibabacloud-observability-mcp-server/releases/latest/download/alibabacloud-observability-mcp-server-darwin-arm64.tar.gz
tar -xzf alibabacloud-observability-mcp-server-darwin-arm64.tar.gz
cd alibabacloud-observability-mcp-server

# macOS amd64 (Intel)
wget https://github.com/aliyun/alibabacloud-observability-mcp-server/releases/latest/download/alibabacloud-observability-mcp-server-darwin-amd64.tar.gz
tar -xzf alibabacloud-observability-mcp-server-darwin-amd64.tar.gz
cd alibabacloud-observability-mcp-server

⚠️ macOS“无法验证开发者”提示： 首次运行时，macOS 可能会阻止执行，并提示“无法验证开发者”。解决方法：

1. 系统设置 → 隐私与安全性 → 找到被阻止的文件 → 点击“仍然允许”
2. 或者在终端运行：xattr -d com.apple.quarantine bin/alibabacloud-observability-mcp-server

步骤 1.1b — 克隆并从源代码构建

git clone https://github.com/aliyun/alibabacloud-observability-mcp-server.git <install_path>
cd <install_path>

可选：固定到特定的发布版本：

# List available versions
git tag -l 'go/v*'

# Checkout a specific version
git checkout go/v0.1.8

构建：

go mod tidy
make build
chmod +x bin/alibabacloud-observability-mcp-server

验证：

./bin/alibabacloud-observability-mcp-server version

如果 make build 失败：

• 检查 Go 版本：go version（需要 >= 1.23）
• 先尝试运行 go mod download
• 检查 C 编译器问题（应该不需要 — 纯 Go）

步骤 1.2 — 配置凭据

cp .env.example .env

向用户展示凭据表：

环境变量	说明	必需
ALIBABA_CLOUD_ACCESS_KEY_ID	阿里云 AccessKey ID	是*
ALIBABA_CLOUD_ACCESS_KEY_SECRET	阿里云 AccessKey Secret	是*
ALIBABA_CLOUD_REGION	默认地域	否（默认 cn-hangzhou）
ALIBABA_CLOUD_WORKSPACE	默认工作空间	否
ALIBABA_CLOUD_SECURITY_TOKEN	STS 临时凭证	否

* 如果在 ECS/FC 上运行且已配置 RAM Role，可以跳过 AccessKey，服务会自动使用默认凭据链。

告知用户：

请编辑 .env 文件，填入你的阿里云 AccessKey。 获取方式：https://ram.console.aliyun.com/manage/ak

等待用户确认已填写凭据。

步骤 1.3 — 选择传输模式

让用户选择：

模式	说明	适用场景
stdio	标准输入输出	IDE 集成（Cursor / Claude Code 等），本地使用
sse	Server-Sent Events	远程 HTTP 访问
streamable-http	HTTP 流式传输	远程 HTTP 访问（推荐用于生产环境）

如果选择 stdio： 告知用户：

stdio 模式通常由 IDE 自动启动，无需手动运行。直接跳到步骤 1.4 生成配置。

如果选择 sse 或 streamable-http：

编辑 config.yaml：

server:
  transport: streamable-http  # 或 sse
  host: 0.0.0.0
  port: 8180

启动服务：

./bin/alibabacloud-observability-mcp-server start --config config.yaml

验证：

curl http://localhost:8180/health

如果健康检查失败：

• 检查日志（stderr 输出）
• 验证 .env 中的凭据是否有效
• 检查端口 8180 是否已被占用：lsof -i :8180

步骤 1.4 — 生成 Agent 集成配置

询问用户要连接哪个 AI Agent，然后生成配置。

对于 streamable-http / sse 模式（远程服务）：

{
  "mcpServers": {
    "alibaba_cloud_observability": {
      "url": "http://<server_ip>:8180"
    }
  }
}

对于 stdio 模式（本地）：

{
  "mcpServers": {
    "alibaba_cloud_observability": {
      "command": "<install_path>/bin/alibabacloud-observability-mcp-server",
      "args": ["start", "--stdio"],
      "env": {
        "ALIBABA_CLOUD_ACCESS_KEY_ID": "<your_access_key_id>",
        "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "<your_access_key_secret>"
      }
    }
  }
}

告知用户在哪里粘贴配置：

Agent	配置文件路径
Cursor	Settings → MCP → Add Server（通过 UI 操作）
Claude Code	~/.claude/settings.json 或项目 .claude/settings.json
Kiro	Settings → MCP Servers（通过 UI 操作）
Windsurf	Settings → MCP Configuration
Cline	项目根目录下的 .cline/mcp_settings.json

将以上 JSON 配置粘贴到你的 AI Agent 中。如果是远程服务，将 <server_ip> 替换为实际 IP 地址。

步骤 1.5 — 付费工具提醒

重要：请在用户完成操作前告知其付费工具相关信息：

⚠️ 付费工具提醒

以下 AI 智能工具每次调用都会产生 STAROps 费用：

• sls_text_to_sql — 自然语言转 SQL
• sls_text_to_spl — 自然语言转 SPL
• sls_sop — SLS 智能运维助手
• cms_natural_language_query — 自然语言数据查询

如果不需要 AI 能力，可以在 config.yaml 的 enabled_tools 中仅启用免费工具，避免意外费用。

计费详情：https://www.aliyun.com/price/product#/starops/detail

---

阶段 1b：Docker 部署（替代方案）

适用于偏好容器化部署的用户（服务器、CI/CD 等）：

使用 Docker 构建并运行

# Build image
docker build -t observability-mcp-server .

# Run with environment variables
docker run -d \
  --name observability-mcp \
  -p 8180:8180 \
  -e ALIBABA_CLOUD_ACCESS_KEY_ID=<your_key> \
  -e ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your_secret> \
  -e ALIBABA_CLOUD_REGION=cn-hangzhou \
  observability-mcp-server

或使用 Docker Compose

# Create .env file with credentials
cat > .env << 'EOF'
ALIBABA_CLOUD_ACCESS_KEY_ID=<your_key>
ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your_secret>
ALIBABA_CLOUD_REGION=cn-hangzhou
EOF

# Start
docker-compose up -d

验证：

curl http://localhost:8180/health

Docker 部署完成后，使用 http://<server_ip>:8180 作为 URL 生成 Agent 配置（与步骤 1.5 相同）。

---

阶段 2：项目更新

当用户想要更新现有部署时：

步骤 2.1 — 定位安装目录

如果用户不知道安装路径：

# Search for existing installations
find ~ -maxdepth 3 -name "alibabacloud-observability-mcp-server" -type d 2>/dev/null

步骤 2.2 — 记录当前状态

cd <install_path>

# Save current version and tool list
./bin/alibabacloud-observability-mcp-server version > /tmp/version_before.txt 2>/dev/null || true
./bin/alibabacloud-observability-mcp-server tools > /tmp/tools_before.txt 2>/dev/null || true

步骤 2.3 — 拉取最新代码

git pull origin master
go mod tidy

步骤 2.4 — 检测变更并报告

运行以下检查，并清晰地呈现结果：

1. 依赖项变更：

git diff HEAD@{1} --name-only 2>/dev/null | grep -E 'go\.(mod|sum)' && echo "DEPENDENCIES CHANGED" || echo "No dependency changes"

2. 配置变更：

git diff HEAD@{1} -- config.yaml .env.example 2>/dev/null

如果 .env.example 发生变更，展示新增变量并请用户更新 .env。

3. 重新构建并比较工具：

make build
chmod +x bin/alibabacloud-observability-mcp-server

# Compare tool lists
diff /tmp/tools_before.txt /tmp/tools_after.txt 2>/dev/null || true

步骤 2.5 — 汇总报告

清晰地呈现总结：

📦 更新完成

版本: <old_version> → <new_version>
依赖: 有变更 / 无变更
配置: 需要更新 .env / 无需更新
工具变更:
  ✅ 新增 N 个工具: tool_a, tool_b, ...
  ❌ 移除 N 个工具: tool_x, ...
服务状态: 需要手动重启 / 已在运行

如果服务正在运行，请使用相同的传输模式重启。

---

故障排除

问题	解决方案
command not found: go	安装 Go >= 1.23：https://go.dev/dl/
credentials not configured	编辑 .env，填入 AccessKey ID 和 Secret
config file not found	确保项目目录中存在 config.yaml
address already in use	使用 lsof -i :8180 查看占用进程，使用 kill -9 <PID> 结束进程或更改端口
Health check 返回错误	检查 stderr 日志，并验证 .env 中的凭证是否正确
git clone 超时	国内用户可尝试使用镜像：https://ghproxy.com/https://github.com/...
go mod tidy 失败	检查网络连接，设置 GOPROXY：export GOPROXY=https://goproxy.cn,direct
构建报 undefined 错误	运行 go mod tidy 重新下载依赖
permission denied	chmod +x bin/alibabacloud-observability-mcp-server
付费工具产生意外费用	在 config.yaml 中通过 enabled_tools 仅启用免费工具