Perses Deploy

Perses 部署指南

Deploy and configure Perses server instances across different environments.

在不同环境中部署和配置Perses服务器实例。

Operator Context

操作者说明

This skill operates as a deployment guide for Perses server instances, covering local development, Kubernetes, and bare metal deployments.

本技能作为Perses服务器实例的部署指南，涵盖本地开发、Kubernetes和裸金属服务器部署场景。

Hardcoded Behaviors (Always Apply)

强制遵循规则（始终适用）

Never expose admin credentials in plain text — use environment variables or secrets
Always configure auth for non-local deployments — at minimum enable native auth
Validate connectivity after deployment — check
```
/api/v1/projects
```
endpoint responds

切勿以明文形式暴露管理员凭证——请使用环境变量或机密存储
非本地部署必须配置认证——至少启用原生认证
部署后验证连通性——检查
```
/api/v1/projects
```
端点是否正常响应

Default Behaviors (ON unless disabled)

默认行为（除非禁用否则生效）

Local dev default: Docker with file-based storage if deployment target not specified
Plugin loading: Configure official plugins from perses/plugins repository
Health check: Verify Perses is running and API is accessible after deployment

本地开发默认配置：若未指定部署目标，默认使用Docker搭配文件型存储
插件加载：配置来自perses/plugins仓库的官方插件
健康检查：部署后验证Perses是否正常运行且API可访问

Optional Behaviors (OFF unless enabled)

可选行为（除非启用否则不生效）

Production hardening: TLS, OIDC auth, SQL database, resource limits
Kubernetes operator: Deploy via perses-operator CRDs instead of Helm
MCP server setup: Install and configure perses-mcp-server alongside Perses

生产环境加固：TLS加密、OIDC认证、SQL数据库、资源限制
Kubernetes Operator部署：使用perses-operator CRDs替代Helm进行部署
MCP服务器设置：在Perses旁安装并配置perses-mcp-server

What This Skill CAN Do

本技能可实现的功能

Deploy Perses via Docker, Helm, binary, or K8s operator
Configure server settings: database, auth, plugins, provisioning, frontend
Set up MCP server integration for Claude Code
Verify deployment health and connectivity

通过Docker、Helm、二进制包或K8s Operator部署Perses
配置服务器设置：数据库、认证、插件、资源配置、前端
为Claude Code设置MCP服务器集成
验证部署健康状态与连通性

What This Skill CANNOT Do

本技能无法实现的功能

Create or manage dashboards (use perses-dashboard-create)
Develop plugins (use perses-plugin-create)
Manage Kubernetes clusters (use kubernetes-helm-engineer)

创建或管理仪表板（请使用perses-dashboard-create）
开发插件（请使用perses-plugin-create）
管理Kubernetes集群（请使用kubernetes-helm-engineer）

Instructions

操作步骤

Phase 1: ASSESS Environment

阶段1：环境评估

Goal: Determine deployment target and requirements.

Deployment target: Docker (local dev), Helm (Kubernetes), Binary (bare metal), or Operator (K8s CRDs)
Storage backend: File-based (default, no external DB needed) or SQL (MySQL)
Authentication: None (local dev), Native (username/password), OIDC, OAuth, or K8s ServiceAccount
Plugin requirements: Official plugins only, or custom plugins too?
MCP integration: Should we also set up the Perses MCP server for Claude Code?

Gate: Environment assessed. Proceed to Phase 2.

目标：确定部署目标与需求。

部署目标：Docker（本地开发）、Helm（Kubernetes）、二进制包（裸金属）或Operator（K8s CRDs）
存储后端：文件型（默认，无需外部数据库）或SQL（MySQL）
认证方式：无（仅本地开发）、原生（用户名/密码）、OIDC、OAuth或K8s ServiceAccount
插件需求：仅使用官方插件，还是也需要自定义插件？
MCP集成：是否需要同时为Claude Code配置Perses MCP服务器？

阶段完成标志：环境评估完成，进入阶段2。

Phase 2: DEPLOY

阶段2：部署

Goal: Deploy Perses server.

目标：部署Perses服务器。

Option A: Docker (Local Development)

选项A：Docker（本地开发）

bash

undefined

bash

undefined

Simplest — single container with defaults

最简方式——使用默认配置的单容器

docker run --name perses -d -p 127.0.0.1:8080:8080 persesdev/perses

With custom config

自定义配置启动

docker run --name perses -d -p 127.0.0.1:8080:8080
-v /path/to/config.yaml:/etc/perses/config.yaml
-v /path/to/data:/perses/data
persesdev/perses --config=/etc/perses/config.yaml

undefined

docker run --name perses -d -p 127.0.0.1:8080:8080
-v /path/to/config.yaml:/etc/perses/config.yaml
-v /path/to/data:/perses/data
persesdev/perses --config=/etc/perses/config.yaml

undefined

Option B: Helm (Kubernetes)

选项B：Helm（Kubernetes）

bash

helm repo add perses https://perses.github.io/helm-charts
helm repo update
helm install perses perses/perses \
  --namespace perses --create-namespace \
  --set config.database.file.folder=/perses/data \
  --set config.security.enable_auth=true

bash

helm repo add perses https://perses.github.io/helm-charts
helm repo update
helm install perses perses/perses \
  --namespace perses --create-namespace \
  --set config.database.file.folder=/perses/data \
  --set config.security.enable_auth=true

Option C: Binary (Bare Metal)

选项C：二进制包（裸金属）

bash

undefined

bash

undefined

Install via Homebrew

通过Homebrew安装

brew install perses/tap/perses brew install perses/tap/percli

Or download from GitHub releases

或从GitHub Releases下载安装包

Run with config

使用配置文件启动

perses --config=./config.yaml

undefined

perses --config=./config.yaml

undefined

Option D: Kubernetes Operator

选项D：Kubernetes Operator

bash

helm repo add perses https://perses.github.io/helm-charts
helm install perses-operator perses/perses-operator \
  --namespace perses-system --create-namespace

bash

helm repo add perses https://perses.github.io/helm-charts
helm install perses-operator perses/perses-operator \
  --namespace perses-system --create-namespace

Then create a Perses CR

然后创建Perses自定义资源（CR）

cat <<EOF | kubectl apply -f - apiVersion: perses.dev/v1alpha2 kind: Perses metadata: name: perses namespace: perses spec: config: database: file: folder: '/perses' extension: 'yaml' containerPort: 8080 EOF


**Gate**: Perses server deployed. Proceed to Phase 3.

cat <<EOF | kubectl apply -f - apiVersion: perses.dev/v1alpha2 kind: Perses metadata: name: perses namespace: perses spec: config: database: file: folder: '/perses' extension: 'yaml' containerPort: 8080 EOF


**阶段完成标志**：Perses服务器部署完成，进入阶段3。

Phase 3: CONFIGURE

阶段3：配置

Goal: Configure server settings.

Server configuration (config.yaml):

yaml

undefined

目标：配置服务器设置。

服务器配置文件（config.yaml）：

yaml

undefined

Database

数据库配置

database: file: folder: "/perses/data" extension: "yaml"

Security

安全配置

security: readonly: false enable_auth: true encryption_key: "<32-byte-AES-256-key>" authentication: access_token_ttl: "15m" refresh_token_ttl: "24h" providers: enable_native: true # oidc: # - slug_id: github # name: "GitHub" # client_id: "<client-id>" # client_secret: "<client-secret>" # issuer: "https://github.com" # redirect_uri: "https://perses.example.com/api/auth/providers/oidc/github/callback"

Plugins

插件配置

plugin: archive_path: "plugins-archive" path: "plugins"

Provisioning (auto-load resources from folders)

资源自动加载配置（从文件夹自动加载资源）

provisioning: folders: - "/perses/provisioning"

Frontend

前端配置

frontend: time_range: disable_custom: false


**Environment variables** override config with `PERSES_` prefix:
- `PERSES_DATABASE_FILE_FOLDER=/perses/data`
- `PERSES_SECURITY_ENABLE_AUTH=true`
- `PERSES_SECURITY_ENCRYPTION_KEY=<key>`

**Gate**: Configuration applied. Proceed to Phase 4.

frontend: time_range: disable_custom: false


**环境变量**可覆盖配置文件，前缀为`PERSES_`：
- `PERSES_DATABASE_FILE_FOLDER=/perses/data`
- `PERSES_SECURITY_ENABLE_AUTH=true`
- `PERSES_SECURITY_ENCRYPTION_KEY=<key>`

**阶段完成标志**：配置已应用，进入阶段4。

Phase 4: VALIDATE

阶段4：验证

Goal: Verify deployment is healthy.

bash

undefined

目标：验证部署是否健康。

bash

undefined

Check API is responding

检查API是否正常响应

curl -s http://localhost:8080/api/v1/projects | head

Install percli and login

安装percli并登录

percli login http://localhost:8080 --username admin --password <password> percli whoami

Create a test project

创建测试项目

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

Verify

验证项目是否存在

percli get project


**Optional: Set up MCP server**

```bash

percli get project


**可选：设置MCP服务器**

```bash

Install perses-mcp-server from releases

从Releases安装perses-mcp-server

Create config

创建配置文件

cat > perses-mcp-config.yaml <<EOF transport: stdio read_only: false perses_server: url: "http://localhost:8080" native_auth: login: "admin" password: "<password>" EOF

Add to Claude Code settings.json

添加到Claude Code的settings.json中

mcpServers.perses.command = "perses-mcp-server"

mcpServers.perses.args = ["--config", "/path/to/perses-mcp-config.yaml"]


**Gate**: Deployment verified, connectivity confirmed. Task complete.


**阶段完成标志**：部署验证通过，连通性确认。任务完成。

perses-deploy

Original

Translation

Perses Deploy

Perses 部署指南

Operator Context

操作者说明

Hardcoded Behaviors (Always Apply)

强制遵循规则（始终适用）

Default Behaviors (ON unless disabled)

默认行为（除非禁用否则生效）

Optional Behaviors (OFF unless enabled)

可选行为（除非启用否则不生效）

What This Skill CAN Do

本技能可实现的功能

What This Skill CANNOT Do

本技能无法实现的功能

Instructions

操作步骤

Phase 1: ASSESS Environment

阶段1：环境评估

Phase 2: DEPLOY

阶段2：部署

Option A: Docker (Local Development)

选项A：Docker（本地开发）

Simplest — single container with defaults

最简方式——使用默认配置的单容器

With custom config

自定义配置启动

Option B: Helm (Kubernetes)

选项B：Helm（Kubernetes）

Option C: Binary (Bare Metal)

选项C：二进制包（裸金属）

Install via Homebrew

通过Homebrew安装

Or download from GitHub releases

或从GitHub Releases下载安装包

Run with config

使用配置文件启动

Option D: Kubernetes Operator

选项D：Kubernetes Operator

Then create a Perses CR

然后创建Perses自定义资源（CR）

Phase 3: CONFIGURE

阶段3：配置

Database

数据库配置

Security

安全配置

Plugins

插件配置

Provisioning (auto-load resources from folders)

资源自动加载配置（从文件夹自动加载资源）

Frontend

前端配置

Phase 4: VALIDATE

阶段4：验证

Check API is responding

检查API是否正常响应

Install percli and login

安装percli并登录

Create a test project

创建测试项目

Verify

验证项目是否存在

Install perses-mcp-server from releases

从Releases安装perses-mcp-server

Create config

创建配置文件

Add to Claude Code settings.json

添加到Claude Code的settings.json中

mcpServers.perses.command = "perses-mcp-server"

mcpServers.perses.command = "perses-mcp-server"

mcpServers.perses.args = ["--config", "/path/to/perses-mcp-config.yaml"]

mcpServers.perses.args = ["--config", "/path/to/perses-mcp-config.yaml"]