perses-onboard

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Perses Onboard

Perses 入职引导

First-time Perses setup and Claude Code integration pipeline.

Perses首次设置与Claude Code集成流程。

Operator Context

技能运行上下文

This skill operates as an onboarding pipeline for new Perses users, guiding them from zero to a working Perses setup with Claude Code MCP integration.

本技能作为Perses新用户的入职引导流程，指导用户从零基础完成Perses的设置，并集成Claude Code MCP。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

Check before deploy: Always check if Perses is already running before offering to deploy
MCP setup: Always offer to configure the Perses MCP server for Claude Code integration
Verify each phase: Don't proceed to next phase until current phase passes validation

部署前检查：在提供部署选项前，始终先检查Perses是否已在运行
MCP设置：始终提供配置Perses MCP服务器以集成Claude Code的选项
阶段验证：当前阶段通过验证后，才能进入下一阶段

Default Behaviors (ON unless disabled)

默认行为（默认启用，可关闭）

Interactive: Ask for confirmation at each phase gate
Local-first: Default to Docker deployment if no server URL provided
Demo datasource: Offer to connect to demo.perses.dev for exploration

交互式操作：在每个阶段的节点处请求用户确认
本地优先：若未提供服务器URL，默认使用Docker部署本地实例
演示数据源：提供连接到demo.perses.dev进行探索的选项

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，可启用）

Production mode: Configure auth, TLS, SQL database
Team onboarding: Create multiple projects and RBAC roles

生产模式：配置认证、TLS、SQL数据库
团队入职：创建多个项目和RBAC角色

What This Skill CAN Do

本技能可实现的功能

Discover existing Perses instances or deploy new ones
Configure Claude Code MCP integration
Create initial projects and datasources
Verify end-to-end connectivity

发现现有Perses实例或部署新实例
配置Claude Code MCP集成
创建初始项目和数据源
验证端到端连接

What This Skill CANNOT Do

本技能无法实现的功能

Create dashboards (use perses-dashboard-create after onboarding)
Configure complex auth (use perses-deploy for production setups)
Develop plugins (use perses-plugin-create)

创建仪表盘（请在入职完成后使用perses-dashboard-create）
配置复杂认证（请使用perses-deploy进行生产环境设置）
开发插件（请使用perses-plugin-create）

Instructions

操作说明

Phase 1: DISCOVER

阶段1：DISCOVER（发现）

Goal: Find or deploy a Perses server.

Step 1: Check for existing Perses

bash

undefined

目标：找到或部署Perses服务器。

步骤1：检查现有Perses实例

bash

undefined

Check if percli is installed

检查percli是否已安装

which percli 2>/dev/null

Check if already logged in

检查是否已登录

percli whoami 2>/dev/null

Check common ports

检查常用端口

curl -s http://localhost:8080/api/v1/health 2>/dev/null


**Step 2: Determine path**

| Scenario | Action |
|----------|--------|
| percli is logged in | Skip to Phase 2: CONNECT |
| Perses is running locally | Login with percli, proceed to Phase 2 |
| No Perses found, user has URL | Login to provided URL |
| No Perses found, no URL | Offer: (a) deploy locally with Docker, (b) use demo.perses.dev |

**Step 3: Deploy if needed** (route to perses-deploy skill)

For quick local setup:
```bash
docker run --name perses -d -p 127.0.0.1:8080:8080 persesdev/perses

Step 4: Login

bash

percli login http://localhost:8080

curl -s http://localhost:8080/api/v1/health 2>/dev/null


**步骤2：确定操作路径**

| 场景 | 操作 |
|----------|--------|
| percli已登录 | 直接进入阶段2：CONNECT（连接） |
| Perses已在本地运行 | 使用percli登录，然后进入阶段2 |
| 未找到Perses实例，但用户提供了URL | 登录到提供的URL |
| 未找到Perses实例，且用户未提供URL | 提供选项：(a) 使用Docker部署本地实例，(b) 使用demo.perses.dev |

**步骤3：按需部署**（跳转至perses-deploy技能）

快速本地部署命令：
```bash
docker run --name perses -d -p 127.0.0.1:8080:8080 persesdev/perses

步骤4：登录

bash

percli login http://localhost:8080

For demo: percli login https://demo.perses.dev

演示环境登录：percli login https://demo.perses.dev


**Gate**: Perses server accessible, percli authenticated. Proceed to Phase 2.


**节点验证**：Perses服务器可访问，percli已完成认证。进入阶段2。

Phase 2: CONNECT

阶段2：CONNECT（连接）

Goal: Set up Claude Code MCP integration.

Step 1: Check for Perses MCP server

bash

which perses-mcp-server 2>/dev/null

Step 2: Install if needed

Guide user to install from https://github.com/perses/mcp-server/releases

Step 3: Configure MCP server

Create

perses-mcp-config.yaml

yaml

transport: stdio
read_only: false
resources: "dashboard,project,datasource,globaldatasource,variable,globalvariable,plugin"
perses_server:
  url: "http://localhost:8080"
  authorization:
    type: Bearer
    credentials: "<token from percli whoami --show-token>"

Step 4: Register in Claude Code settings

Add to

~/.claude/settings.json

under

mcpServers

json

{
  "perses": {
    "command": "perses-mcp-server",
    "args": ["--config", "/path/to/perses-mcp-config.yaml"]
  }
}

Step 5: Verify MCP connection

Use ToolSearch("perses") to check if MCP tools are discoverable. If found, test with

perses_list_projects

Gate: MCP server configured and responsive. Proceed to Phase 3.

目标：完成Claude Code MCP集成设置。

步骤1：检查Perses MCP服务器

bash

which perses-mcp-server 2>/dev/null

步骤2：按需安装

引导用户从https://github.com/perses/mcp-server/releases下载安装。

步骤3：配置MCP服务器

创建

perses-mcp-config.yaml

文件：

yaml

transport: stdio
read_only: false
resources: "dashboard,project,datasource,globaldatasource,variable,globalvariable,plugin"
perses_server:
  url: "http://localhost:8080"
  authorization:
    type: Bearer
    credentials: "<token from percli whoami --show-token>"

步骤4：在Claude Code设置中注册

在

~/.claude/settings.json

的

mcpServers

字段中添加以下内容：

json

{
  "perses": {
    "command": "perses-mcp-server",
    "args": ["--config", "/path/to/perses-mcp-config.yaml"]
  }
}

步骤5：验证MCP连接

使用ToolSearch("perses")检查MCP工具是否可被发现。若已发现，使用

perses_list_projects

进行测试。

节点验证：MCP服务器已配置并响应。进入阶段3。

Phase 3: CONFIGURE

阶段3：CONFIGURE（配置）

Goal: Create initial project and datasources.

Step 1: Create a project

bash

percli apply -f - <<EOF
kind: Project
metadata:
  name: default
spec: {}
EOF
percli project default

Or via MCP:

perses_create_project(project="default")

Step 2: Add a datasource (if user has Prometheus/Tempo/Loki available)

bash

percli apply -f - <<EOF
kind: GlobalDatasource
metadata:
  name: prometheus
spec:
  default: true
  plugin:
    kind: PrometheusDatasource
    spec:
      proxy:
        kind: HTTPProxy
        spec:
          url: http://prometheus:9090
          allowedEndpoints:
            - endpointPattern: /api/v1/.*
              method: POST
            - endpointPattern: /api/v1/.*
              method: GET
EOF

Gate: Project and datasource configured. Proceed to Phase 4.

目标：创建初始项目和数据源。

步骤1：创建项目

bash

percli apply -f - <<EOF
kind: Project
metadata:
  name: default
spec: {}
EOF
percli project default

或通过MCP执行：

perses_create_project(project="default")

步骤2：添加数据源（若用户有Prometheus/Tempo/Loki可用）

bash

percli apply -f - <<EOF
kind: GlobalDatasource
metadata:
  name: prometheus
spec:
  default: true
  plugin:
    kind: PrometheusDatasource
    spec:
      proxy:
        kind: HTTPProxy
        spec:
          url: http://prometheus:9090
          allowedEndpoints:
            - endpointPattern: /api/v1/.*
              method: POST
            - endpointPattern: /api/v1/.*
              method: GET
EOF

节点验证：项目和数据源已配置。进入阶段4。

Phase 4: VALIDATE

阶段4：VALIDATE（验证）

Goal: Verify the full setup works end-to-end.

Checklist:

```
percli whoami
```
shows authenticated user
```
percli get project
```
lists the created project
```
percli get globaldatasource
```
lists configured datasources (if any)
MCP tools respond (if configured):
```
perses_list_projects
```
returns data
Perses UI is accessible in browser at the configured URL

Summary output:

Perses Onboarding Complete:
  Server: http://localhost:8080
  Project: default
  Datasources: prometheus (global, default)
  MCP: configured (25+ tools available)
  CLI: percli authenticated as <user>

Next steps:
  - Create a dashboard: /do create perses dashboard
  - Migrate Grafana dashboards: /do migrate grafana to perses
  - Set up Dashboard-as-Code: /do perses dac

Gate: All checks pass. Onboarding complete.

目标：验证完整设置是否端到端可用。

检查清单：

```
percli whoami
```
显示已认证用户
```
percli get project
```
列出已创建的项目
```
percli get globaldatasource
```
列出已配置的数据源（若有）
MCP工具可响应（若已配置）：
```
perses_list_projects
```
返回数据
Perses UI可在浏览器中通过配置的URL访问

总结输出：

Perses Onboarding Complete:
  Server: http://localhost:8080
  Project: default
  Datasources: prometheus (global, default)
  MCP: configured (25+ tools available)
  CLI: percli authenticated as <user>

Next steps:
  - Create a dashboard: /do create perses dashboard
  - Migrate Grafana dashboards: /do migrate grafana to perses
  - Set up Dashboard-as-Code: /do perses dac

节点验证：所有检查项通过。入职设置完成。