【设计】DevStore 特性设计文档

# DevStore 特性设计文档

## 1 DevStore 概述

### 1.1 简介

DevStore 是 openEuler 社区为开发者打造的一站式工具平台，集成了 MCP 服务、oeDeploy 插件等实用工具，提供了丰富的开发者软件资源。用户可以快速查阅各类工具的详细信息，获取对应的安装与使用指南。同时 DevStore 也是 DevStation 平台的默认应用商店，让开发者快速获取、安装所需工具，提升开发效率。

### 1.2 名词介绍

| 名词       | 链接                                                         | 描述                                                         |
| ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| DevStation | [link](https://docs.openeuler.org/zh/docs/25.03/devstation/index.html) | **DevStation** 是基于 openEuler 的智能开发者工作站OS，融合了开箱即用的 AI 运行环境与全栈开发工具链，将软件设计、编码、构建、发布、维护、监控的全流程做智能化改造，大幅提升开发与运维效率。 |
| oeDeploy   | [link](https://docs.openeuler.org/zh/docs/25.03/devstation/oedeploy/introduction.html) | **oeDeploy** 是一款轻量级的软件部署工具，旨在帮助开发者快速、高效地完成各类软件环境部署，支持单节点与分布式场景。自动化部署脚本通过 oeDeploy 插件的格式进行承载。 |
| oedp       | -                                                            | **oedp** 是 oeDeploy 的命令行工具，也可以是 oeDeploy 的简称。 |

## 2 用户场景分析

| 用户场景              | 形态                                                  | 描述                                                         |
| --------------------- | ----------------------------------------------------- | ------------------------------------------------------------ |
| 开发者工具检索        | Web（openEuler 社区官网）+ APP（DevStation 应用商店） | 开发者查询所需的 MCP 服务、oeDeploy 插件，浏览基本信息、介绍文档、安装步骤、使用指南。同时将开发者引流至对应的代码仓、SIG组、社区论坛。 |
| MCP 服务一键安装      | APP（DevStation 应用商店）                            | 为降低开发者使用 MCP 服务的门槛、提升易用性，在 DevStation 上提供一键安装 MCP 服务的能力，解决 MCP 服务的软件依赖，自动写入 MCP 配置。 |
| oeDeploy 插件一键部署 | APP（DevStation 应用商店）                            | 为降低 oeDeploy 工具的使用门槛、提升易用性，在 DevStation 上提供 oeDeploy 插件的一键部署能力，将插件自动初始化到本地，插件所支持的原子化操作都以按钮的形式呈现。 |

### 2.1 形态一：Web（openEuler 社区官网）

**形态：**

- openEuler 社区官网的一个 Web 页面

**主要特性：**

- MCP 服务、oeDeploy 插件以及其他开发者工具的快速检索、首页推荐。
- MCP 服务、oeDeploy 插件以及其他开发者工具的基本信息、介绍文档、安装步骤、使用指南在详情页呈现。
- 安装步骤在详情页中单独呈现，命令行支持一键复制。
- 在醒目位置放置超链接，将开发者引流至对应的代码仓、SIG组、社区论坛，同时收集用户评价、反馈意见。

### 2.2 形态二：APP（DevStation 应用商店）

**形态：**

- DevStation 平台默认集成的一个 APP

**主要特性：**

- 包含了上述 Web 形态下的所有特性。
- 支持 MCP 服务一键安装，以 rpm 包的形式解决软件依赖。可以通过下拉菜单选择承载 MCP 服务的不同应用，并通过脚本自动写入到对应的 MCP 配置文件。
- 支持 oeDeploy 插件的一键部署，调用 oedp 命令行完成相关的部署操作。不同插件支持的操作类型不同，提示信息、操作选项也会存在差异。允许用户直接在界面上编辑配置文件。

## 3 特性设计&功能实现

### 3.1 总体设计

#### 3.1.1 主页（检索页）

#### 3.1.2 详情页（MCP）

#### 3.1.3 详情页（OEDP）

### 3.2 MCP 服务管理

DevStation 的 MCP 服务以 rpm 包的形式管理，并提供一个特定的 yum 源。在本地添加这个 MCP 相关的 yum 源地址后，用户可以用 dnf 或者 yum 命令直接安装对应的 MCP 服务软件包，但需要写入 APP 的 MCP 配置文件才会生效。

提前约定：所有 MCP 服务软件包名称都符合`mcp-servers-xxxx`格式。

DevStore 下载当前环境中已经生效 yum 源的 repodata 文件，将所有符合`mcp-servers-xxxx`格式的软件包信息记录到数据库。

```mermaid
---
config:
 look: classic
---
flowchart LR
 n1["更新repo源 yum makecache"] --> n2["下载并读取已生效repo源的 repodata文件"]
 n2 --> n3["匹配mcp-servers-xxxx 格式的软件包"]
 n3 --> n5["下载对应的软件包"]
 n5 --> n4["解析数据并更新到数据库"]

```

数据库中 MCP 服务直接从 repodata 中读取，部分字段需要从 MCP 软件包的构建配置文件`mcp-rpm.yaml`读取。插件名称与版本号的组合，作为插件的唯一索引（例如`<name>#<version>`）。

字段含义如下：

| 字段 | 含义 | 获取方式 |
| ---------------- | ------------------------------------------------------- | ------------------------------------------------------------ |
| `name` | MCP 服务名称。 | 软件包名去除`mcp-servers-`的前缀 |
| `package_name` | MCP 服务软件包名称，必须与 MCP 源比配。 | 从 repodata 读取 |
| `version` | MCP 服务软件包版本号。 | 从 repodata 读取 |
| `updated` | MCP 服务软件包更新的时间，格式为`%Y-%m-%dT%H:%M:%S%z`。 | 从 repodata 读取 |
| `url` | MCP 服务源码地址。 | 从 repodata 读取 |
| `description` | MCP 服务简介（当多语言简介缺失时，作为缺省值）。 | 从 repodata 读取 |
| `author` | MCP 服务发布者。 | 从`mcp-rpm.yaml`读取 |
| `description_zh` | MCP 服务简介（中文，用于检索匹配）。 | 从`mcp-rpm.yaml`读取 |
| `description_en` | MCP 服务简介（英文，用于检索匹配）。 | 从`mcp-rpm.yaml`读取 |
| `readme` | MCP 服务用户文档链接，仅支持Markdown格式。 | 1. 从`mcp-rpm.yaml`读取 2. `mcp-rpm.yaml`同路径下的`readme.md` |
| `icon` | MCP 服务图标地址，用于Web端显示。 | 1. 从`mcp-rpm.yaml`读取 2. `mcp-rpm.yaml`同路径下的`icon.png` 3. 缺省为`name`前两字母组成的图片 |

`mcp-rpm.yaml`是将 MCP 服务构建成 rpm 包的构建配置文件（已经实装，但需补充缺失的字段），示例：

```yaml
name: "oeDeploy"
summary: "MCP server for oeDeploy"
description_zh: "oeDeploy MCP Server (mcp-oedp) 是一个智能部署工具，通过自然语言交互实现软件的一键式部署。它深度集成oeDeploy能力，支持Kubernetes等复杂系统的自动化部署，用户只需提供简单的节点信息即可完成全流程配置。该工具提供标准MCP接口，可与各类AI平台无缝对接。"
description_en: "The oeDeploy MCP Server (mcp-oedp) is an intelligent deployment tool that enables one-click software deployment through natural language interaction. Deeply integrated with oeDeploy capabilities, it supports automated deployment of complex systems like Kubernetes. Users only need to provide basic node information to complete the entire configuration process. The tool offers standard MCP interfaces for seamless integration with various AI platforms."
readme: https://gitee.com/openeuler/oeDeploy/blob/master/oedp-mcp/README.md
icon: https://gitee.com/openeuler/oeDeploy/blob/master/oedp/build/static/oeDeploy.png

dependencies:
  system:
    - python3
    - uv
    - python3-mcp
  packages:
    - oedp

files:
  required:
    - mcp_config.json
    - src/mcp-oedp.py
  optional:
    - src/requirements.txt
    - src/pyproject.toml
```

### 3.3 oeDeploy 插件管理

DevStore 依赖软件包 oedp，触发`oedp reop update`命令后，oedp 会将所有可用插件源的索引文件下载到`/etc/oedp/config/repo/cache/`，DevStore 读取目录下的全部索引文件，将所有插件信息记录到数据库，通过前端页面进行展示。

数据库中 oeDeploy 插件保留索引文件中插件的所有字段。其中，插件名称与版本号的组合，作为插件的唯一索引（例如`<name>#<version>`）。

#### 3.3.1 插件源管理

DevStore 直接复用 oedp 的插件源索引，使用 oedp 命令行管理插件源。

插件源配置文件 `/etc/oedp/config/repo/repo.conf`示例

````ini
[openEuler]
url = https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/plugins/
enabled = true

[local]
url = file:///root/.oedp/plugins/
enabled = false
````

其中 openEuler 插件源是默认生效的。

#### 3.3.2 插件源索引文件

每个 oeDeploy 插件源的根目录下一定有一个索引文件`index.yaml`，oedp 更新 repo 时会下载所有插件源的索引文件，并重命名为`<插件源name>.yaml`。如果同个插件有多个版本，DevStore 都需用读出来作为独立的插件。

索引文件格式如下：

```yaml
---
apiversion: v1
plugins:
- kubernetes-1.31.1:
  - name: kubernetes-1.31.1
    version: 1.0.0-1
    updated: "2025-03-05T10:31:02.608017752+08:00"
    author: openEuler
    git: https://gitee.com/openeuler/oeDeploy/tree/master/plugins/kubernetes-1.31.1
    description: oeDeploy pulgin for kubernetes deployment
    readme: https://gitee.com/openeuler/oeDeploy/blob/master/plugins/kubernetes-1.31.1/doc/readme.md
    icon: https://gitee.com/openeuler/oeDeploy/blob/master/oedp/build/static/oeDeploy.png
    type: app
    localhost_available: false
    sha256sum: 683995d14bbf425f18d1086858f210fc704b1d14edb274382d0e518a5d2a92c1
    size: 1061949301
    urls:
    - https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/plugins/kubernetes-1.31.1.tar.gz
  - name: kubernetes-1.31.1
    version: 1.0.0-2
    ...
- pytorch:
  - name: pytorch
    version: 1.0.0-1
    updated: "2025-03-05T10:31:02.608017752+08:00"
    author: openEuler
    git: https://gitee.com/openeuler/oeDeploy/tree/master/plugins/pytorch
    description: oeDeploy pulgin for pytorch deployment
    readme: https://gitee.com/openeuler/oeDeploy/blob/master/plugins/pytorch/doc/readme.md
    icon: https://gitee.com/openeuler/oeDeploy/blob/master/oedp/build/static/oeDeploy.png
    type: app
    localhost_available: true
    sha256sum: 3fe0cb97e01ac9af2c1c8d12d12753f82988ab0e39b5878f359829574102c79d
    size: 2373
    urls:
    - https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/plugins/pytorch.tar.gz
  ...
...
```

首层字段含义：

| 字段         | 含义                                                         |
| ------------ | ------------------------------------------------------------ |
| `plugins`    | 含有多个插件名称（默认字母序排序），一个插件名称中可能包含多个不同版本的插件（默认根据版本号倒序排序） |
| `apiversion` | 索引文件格式的版本号。保留字段，暂不生效。默认值 `v1`。      |

插件字段含义：

| 字段                  | 含义                                                         |
| --------------------- | ------------------------------------------------------------ |
| `name`                | 插件名称。允许插件名称中带有版本号，表示软件本身的版本，而非插件的版本。 |
| `version`             | 插件版本号，并非所部署软件的版本号。                         |
| `updated`             | 插件更新的时间，格式为`%Y-%m-%dT%H:%M:%S%z`。                |
| `author`              | 插件发布者。缺省为 openEuler。                               |
| `git`                 | 插件代码地址。                                               |
| `description`         | 插件简介（当多语言简介缺失时，作为缺省值）。                 |
| `description_zh`      | 插件简介（中文，用于检索匹配）。                             |
| `description_en`      | 插件简介（英文，用于检索匹配）。                             |
| `readme`              | 插件用户文档链接。                                           |
| `icon`                | 插件图标地址，用于Web端显示。缺省为`name`前两字母组成的图片  |
| `type`                | 插件类型。保留字段，暂不生效。默认值 `app`。                 |
| `localhost_available` | 插件是否支持本地单节点部署。允许为空，缺省为`false`。        |
| `sha256sum`           | 插件文件sha256数值，用于下载时的完整性校验。                 |
| `size`                | 插件文件大小，单位Bytes。                                    |
| `urls`                | 插件下载地址，可以有多个。所有url地址都必须在当前插件源目录的范围内。 |

#### 3.3.3 插件更新

将 oeDeploy 插件信息同步到 DevStore 数据库分为两个阶段：

1. 执行命令行`oedp repo update`，更新 oedp 的 repo，下载索引文件。
2. 将索引文件中的数据同步到数据库。

插件源更新与数据库同步通过以下条件触发：

1. DevStore 启动/初始化/刷新
2. 点击同步按钮
3. 定时器触发（24H）

```mermaid
---
config:
  look: classic
  layout: dagre
  theme: neo
---
flowchart TD
    n7(["DevStore初始化/启动"]) --> n9["更新插件源repo"]
    n8(["手动触发"]) --> n9
    n9 --> n11["同步到数据库"]
    n12(["定时器触发（24H）"]) --> n9

```

### 3.4 数据检索

当搜索内容为空，或者用户点击清空按钮后，罗列推荐的 MCP 服务或者 oeDeploy 插件，用白名单管理。

当搜索内容非空，以 MCP 服务或者 oeDeploy 插件的`name`和`description`为检索范围，使用 python 库进行检索匹配，按照相关性优先级排序。

### 3.5 MCP 服务一键安装

DevStore 需要根据每个 MCP 服务软件包的安装状态，在页面上呈现不同的状态（安装/卸载）。

当用户点击安装按钮：

1. **安装对应的 rpm：**解决软件依赖，安装所需源码、文件。
2. **执行 MCP 设置脚本：**修改指定 APP 的 MCP 配置文件，使得当前 MCP 服务能被 APP 识别并生效。不同 APP 的 MCP 配置文件不同，配置内参数可能也有差异。因此在 MCP 设置脚本中需要对每个 APP 的 MCP 配置文件做适配开发，并做白名单管理。

当用户点击卸载按钮：

1. **执行 MCP 设置脚本：**修改指定 APP 的 MCP 配置文件，删除当前 MCP 服务。删除失败依然执行下一步。
2. **卸载对应的 rpm**。

> 遗留问题：MCP 服务的安装/卸载没有考虑多个 APP 配置、手动配置的情况，可能导致 APP 中残留不可用 MCP 服务等问题。

### 3.6 oeDeploy 插件一键部署

oeDeploy 插件的详情页，在 Web 形态下只提供用户文档与相关命令行（支持一键复制），在 APP 形态下提供一键部署功能（只有参数`localhost_available`为`true`的插件支持一键部署）。

初始状态下，下载成功进入部署状态，删除则回退。

```mermaid
---
config:
 look: classic
 layout: dagre
 theme: neo
---
flowchart LR
 n1["初始状态 "] -- 点击下载，初始化成功后 --> n2["部署状态"]
 n2 -- 点击删除，删除成功后 --> n1
 n1@{ shape: rect}

```

oeDeploy 插件默认的初始化路径：`~/.oedp/`

oeDeploy 插件的部署能力由 oedp 软件包提供，后端只需调用对应的命令行。

按钮说明：

| 按钮 | 说明 |
| ---------------- | ------------------------------------------------------------ |
| 下载 | 执行`oedp init <plugin> -d ~/.oedp/ -f` |
| 删除 | 删除路径`~/.oedp/<plugin>/` |
| install | 执行`oedp run install -p ~/.oedp/<plugin>/ -l` |
| 其他部署操作 | 同 install 按钮。 从下载插件的`main.yaml`读取支持的操作列表，各显示为一个按钮。 |
| 保存（高级配置） | 备份`config.yaml`为`config.yaml.bak`，用户的输入文本保存为新的`config.yaml`。 |
| 还原（高级配置） | `config.yaml.bak`覆盖`config.yaml`。 |

openEuler/oeDeploy
关闭

内容风险标识

评论 (1)

openEuler/oeDeploy关闭 .gitee-modal { width: 500px !important; }

内容风险标识