From 39c9c1b624f29979ff4cc3419ff4c90b8d844c94 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=BB=B4=E5=9F=BA=E9=B1=BC?= Date: Thu, 19 Jun 2025 15:30:25 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E4=B8=AD=E6=96=87?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 10 +- doc/zh/Command.md | 104 +-- doc/zh/DevelopGuide.md | 377 --------- doc/zh/DevelopInstruction.md | 140 ++++ doc/zh/{MCPGuide.md => MCPInstruction.md} | 4 +- doc/zh/UseCase.md | 948 ++++++++++++++++++++-- 6 files changed, 1076 insertions(+), 507 deletions(-) delete mode 100644 doc/zh/DevelopGuide.md create mode 100644 doc/zh/DevelopInstruction.md rename doc/zh/{MCPGuide.md => MCPInstruction.md} (93%) diff --git a/README.md b/README.md index e093a9b..b7b3778 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# 简介/Introduction +# 简介 / Introduction oeDeploy 是一款轻量级的软件部署工具，旨在帮助开发者快速、高效地完成各类软件环境部署，对单节点与分布式场景均可适配。 @@ -7,14 +7,14 @@ oeDeploy 是一款轻量级的软件部署工具，旨在帮助开发者快速 - **灵活的插件化管理**：oeDeploy 提供可扩展架构，支持开发者基于实际需求，使用自定义编写的定制插件，精准匹配自身业务特性。 - **高效开发体验**：oeDeploy 已支持命令行，并将提供可视化工具；开发者仅需关注步骤编排与核心功能开发，用更少的代码，实现更高效的软件部署。 -# 下载/Download +# 下载 / Download - [命令行工具 oedp (noarch)](https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/noarch/) - [oeDeploy 部署插件](https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/plugins/) -# 文档/Docs +# 文档 / Docs - [命令行工具 oedp 使用指南](https://gitee.com/openeuler/oeDeploy/tree/master/doc/zh/Command.md) - [oeDeploy 应用案例](https://gitee.com/openeuler/oeDeploy/tree/master/doc/zh/UseCase.md) -- [oeDeploy 插件开发指南](https://gitee.com/openeuler/oeDeploy/tree/master/doc/zh/DevelopGuide.md) -- [oeDeploy MCP Server 使用说明](https://gitee.com/openeuler/oeDeploy/tree/master/doc/zh/MCPGuide.md) +- [oeDeploy 插件开发指南](https://gitee.com/openeuler/oeDeploy/tree/master/doc/zh/DevelopInstruction.md) +- [oeDeploy MCP Server 使用说明](https://gitee.com/openeuler/oeDeploy/tree/master/doc/zh/MCPInstruction.md) diff --git a/doc/zh/Command.md b/doc/zh/Command.md index 350bae9..f423569 100644 --- a/doc/zh/Command.md +++ b/doc/zh/Command.md @@ -8,7 +8,7 @@ ## `oedp info` -查看项目的详细信息，默认为当前路径 +查看项目的详细信息，默认为当前路径。 | 选项 | 简写 | 是否必需 | 功能说明 | | -------------------- | ------ | -------- | ------------------------ | @@ -16,7 +16,7 @@ ## `oedp run [action]` -执行项目某个方法，默认为当前路径；`[action]`为插件可使用的方法，可通过 `oedp info`命令查询 +执行项目某个方法，默认为当前路径；`[action]`为插件可使用的方法，可通过 `oedp info`命令查询。 | 选项 | 简写 | 是否必需 | 功能说明 | | -------------------- | ------ | -------- | ------------------------ | @@ -25,23 +25,23 @@ ## `oedp list` -列举插件源中可用的插件 +列举源中可用的插件。 ## `oedp init [plugin]` -插件初始化到指定路径，`[plugin]`可以是插件压缩包路径、插件下载地址、插件名称 +插件初始化到指定路径，`[plugin]`可以是插件压缩包路径、插件下载地址、插件名称。 -- `[plugin]`如果为本地的插件压缩包（以`tar.gz`结尾），则直接初始化到指定路径 -- `[plugin]`如果为插件下载地址（以`tar.gz`结尾），则先下载到缓存路径`/var/oedp/plugin/`，再初始化到指定路径 -- `[plugin]`如果为插件名称，从已经配置的插件源中查找，下载到缓存路径后初始化到指定路径 +- `[plugin]`如果为本地的插件压缩包（以`tar.gz`结尾），则直接初始化到指定路径。 +- `[plugin]`如果为插件下载地址（以`tar.gz`结尾），则先下载到缓存路径`/var/oedp/plugin/`，再初始化到指定路径。 +- `[plugin]`如果为插件名称，从已经配置的插件源中查找，下载到缓存路径后初始化到指定路径。 | 选项 | 简写 | 是否必需 | 功能说明 | | ------------------ | ---- | -------- | ------------------------------------------------------------ | | `--project [path]` | `-p` | N | 项目路径，若不存在则创建 | -| `--dir [path]` | `-d` | N | 项目的父路径，若不存在则创建。如果未指定项目路径与父路径，则父路径默认取当前目录。 | +| `--dir [path]` | `-d` | N | 项目的父路径，若不存在则创建。如果未指定项目路径与父路径，则父路径默认取当前目录 | | `--force` | `-f` | N | 强制覆盖路径，请谨慎使用；如果路径存在，会先删除该路径中的所有文件，再初始化 | -示例：假设当前路径为家目录`~`，如下5个命令执行后，都是初始化了一个目录为`~/kubernetes-1.31.1`的 oeDeploy 插件 +示例：假设当前路径为家目录`~`，如下5个命令的效果，都是初始化了一个目录为`~/kubernetes-1.31.1`的 oeDeploy 插件。 ````bash oedp init kubernetes-1.31.1 @@ -53,21 +53,18 @@ oedp init kubernetes-1.31.1 -d ~ ## `oedp repo` -插件源管理。 +插件源管理。支持本地插件源、远端插件源。 -- 支持本地插件源、远端插件源。 -- 插件源不可重名。 - -| 选项 | 功能说明 | -| ------------------ | ---------------------- | +| 选项 | 功能说明 | +| -------------------- | ---------------------- | | `list` | 查询所有已配置的插件源 | | `update` | 更新插件索引缓存 | -| `set [name] [url]` | 增加/修改插件源地址 | +| `set [name] [url]` | 修改插件源地址 | | `del [name]` | 删除插件源 | | `enable [name]` | 使能插件源 | | `disable [name]` | 去使能插件源 | -插件源配置文件 `/etc/oedp/config/repo/repo.conf`示例 +插件源配置文件 `/etc/oedp/config/repo/repo.conf`示例。 ````ini [openEuler] @@ -79,20 +76,32 @@ url = file:///root/.oedp/plugins/ enabled = false ```` +## `oedp check [action]`（开发中） + +检查项目中指定方法的检查项，默认为当前路径。 + +| 选项 | 简写 | 是否必需 | 功能说明 | +| -------------------- | ------ | -------- | ------------------------ | +| `--project [path]` | `-p` | N | 项目路径，默认为当前路径 | + +## `oedp clean`（开发中） + +清理所有临时插件文件。 + # # `oedp`工具相关文件与路径 -| 路径 | 说明 | -| --------------------------------- | ------------------------------------------------------------ | -| `/etc/oedp/config/` | 配置文件路径 | -| `/etc/oedp/config/repo/cache/` | 插件源索引文件缓存路径，每个已经生效的插件源都会生成一个`.yaml`文件 | -| `/etc/oedp/config/repo/repo.conf` | 插件源配置文件 | -| `/usr/lib/oedp/src/` | 源码路径 | -| `/var/oedp/log/` | 日志文件路径 | -| `/var/oedp/plugin/` | 插件缓存路径 | +| 路径 | 说明 | +| --------------------------------- | ---------------------- | +| `/etc/oedp/config/` | 配置文件路径 | +| `/etc/oedp/config/repo/cache/` | 插件源索引文件缓存路径 | +| `/etc/oedp/config/repo/repo.conf` | 插件源配置文件 | +| `/usr/lib/oedp/src/` | 源码路径 | +| `/var/oedp/log/` | 日志文件路径 | +| `/var/oedp/plugin/` | 插件缓存路径 | -# # oeDeploy 插件源 +# # 插件源 -## 插件源格式说明 +## 格式说明 oeDeploy 支持从可访问的插件源自动获取安装部署插件，并初始化到本地。 @@ -100,7 +109,7 @@ oeDeploy 支持从可访问的插件源自动获取安装部署插件，并初 oeDeploy 提供了脚本 `tools/make_repo_index/make_repo_index.py`，用于自动生成 `index.yaml`。 -`index.yaml`示例如下： +`index.yaml`格式如下： ```yaml --- @@ -110,7 +119,7 @@ plugins: - name: kubernetes-1.31.1 version: 1.0.0-1 updated: "2025-03-05T10:31:02.608017752+08:00" - description: oeDeploy pulgin for kubernetes deployment + description: oeDeploy plugin for kubernetes deployment icon: https://gitee.com/openeuler/oeDeploy/blob/master/oedp/build/static/oeDeploy.png type: app sha256sum: 683995d14bbf425f18d1086858f210fc704b1d14edb274382d0e518a5d2a92c1 @@ -124,7 +133,7 @@ plugins: - name: pytorch version: 1.0.0-1 updated: "2025-03-05T10:31:02.608017752+08:00" - description: oeDeploy pulgin for pytorch deployment + description: oeDeploy plugin for pytorch deployment icon: https://gitee.com/openeuler/oeDeploy/blob/master/oedp/build/static/oeDeploy.png type: app sha256sum: 3fe0cb97e01ac9af2c1c8d12d12753f82988ab0e39b5878f359829574102c79d @@ -135,26 +144,25 @@ plugins: ... ``` -首层字段含义： - -| 字段 | 含义 | -| ------------ | ------------------------------------------------------------ | -| `plugins` | 含有多个插件名称（默认字母序排序），一个插件名称中可能包含多个不同版本的插件（默认根据版本号倒序排序） | -| `apiversion` | 索引文件格式的版本号。保留字段，暂不生效。默认值 `v1`。 | - 插件字段含义： -| 字段 | 含义 | 获取方式 | -| ------------- | ------------------------------------------------------------ | ------------------------------- | -| `name` | 插件名称。允许插件名称中带有版本号，表示软件本身的版本，而非插件的版本。 | 与插件压缩包同名（不带.tar.gz） | -| `version` | 插件版本号，并非所部署软件的版本号。 | 读取main.yaml | -| `updated` | 插件更新的时间，格式为`%Y-%m-%dT%H:%M:%S%z`。允许为空。 | 插件压缩包最后修改时间 | -| `description` | 插件介绍。允许为空。 | 读取main.yaml | -| `icon` | 插件图标地址，用于Web端显示。允许为空。 | 读取main.yaml | -| `type` | 插件类型。保留字段，暂不生效。默认值 `app`。 | 读取main.yaml | -| `sha256sum` | 插件文件sha256数值，用于下载时的完整性校验。 | sha256计算 | -| `size` | 插件文件大小，单位Bytes。 | 压缩包实际大小 | -| `urls` | 插件下载地址，可以有多个。所有url地址都必须在当前插件源目录的范围内。 | 前缀与相对路径的拼接结果 | +| 字段 | 含义 | 获取方式 | +| ------------- | ------------------------------------------------------------ | ------------------------------ | +| `name` | 插件名称。允许插件名称中带有版本号，表示软件本身的版本，而非插件的版本。 | 读取main.yaml | +| `version` | 插件版本号。 | 读取main.yaml | +| `updated` | 插件更新的时间，格式为`%Y-%m-%dT%H:%M:%S%z`。允许为空。 | 读取main.yaml | +| `description` | 插件介绍。允许为空。 | 读取main.yaml | +| `icon` | 插件图标地址，用于Web端显示。允许为空。 | 读取main.yaml | +| `type` | 插件类型。保留字段，暂不生效。默认值 `app`。 | 读取main.yaml | +| `sha256sum` | 插件文件sha256数值，用于下载时的完整性校验。 | `sha256sum xxx.tar.gz`命令查询 | +| `size` | 插件文件大小，单位Bytes。 | 压缩包实际大小 | +| `urls` | 插件下载地址，可以有多个。所有url地址都必须在当前插件源目录的范围内。 | 前缀与相对路径的拼接结果 | + +其他字段： + +| 字段 | 含义 | 获取方式 | +| -------------- | --------------------------------------------------------- | -------- | +| `apiversion` | 索引文件格式的版本号。保留字段，暂不生效。默认值 `v1`。 | 脚本生成 | ## 插件源构建方式 diff --git a/doc/zh/DevelopGuide.md b/doc/zh/DevelopGuide.md deleted file mode 100644 index 040a261..0000000 --- a/doc/zh/DevelopGuide.md +++ /dev/null @@ -1,377 +0,0 @@ -# oeDeploy 插件开发指南 - -## 1 oeDeploy 插件概念介绍 - -- oeDeploy 插件（plugin）是 oedp 工具中提供自动化部署能力的组件，将复杂的部署流程脚本化来实现自动化部署。 -- 一个插件中可能会集成多种部署操作（action），例如安装、卸载、环境清理等。 -- 每一个部署操作都会对应一个或多个步骤（task），每个步骤对应一个部署脚本（例如 ansible 的 playbook）。 - -## 2 oeDeploy 插件目录结构 - -oeDeploy 插件目录名称，即插件名称，可以包含版本号（表示软件本身的版本，而非插件的版本） - -插件目录下包含如下内容： - -| 文件或者目录名 | 类型 | 介绍 | -| -------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| config.yaml | yaml | 对用户暴露的唯一配置文件。包含主机相关的配置，如 ip、密码、密钥、端口号等，还包含了软件部署相关的配置项。 | -| main.yaml | yaml | 包含了插件的各种信息，例如名称、版本号、描述，也包含了每个部署操作（action）执行时的具体步骤，每个步骤都对应一个脚本或者playbook（以workspace为根目录）。 | -| doc | 目录 | 承载插件相关的用户文档。该目录非必需。 | -| workspace | 目录 | 承载了软件安装部署所使用的所有文件、源码、二进制、脚本、playbook等等。目录内结构不做限制。 | - -## 3 `main.yaml` - -`main.yaml`主要用于记录插件的关键信息，包括：名称（`name`）、版本（`version`）、插件介绍（`description`）、操作（`action`）等。 - -- 当用户执行`oedp info`命令时，`oedp`工具会读取并解析该文件，向用户展示相关信息。 -- 当用户执行`oedp run xxxx`命令时，`oedp`工具会根据`action`字段中的内容，执行对应的自动化脚本。 - -### 3.1 `main.yaml`格式说明： - -- `action`字段中包含了一个或者多个操作。 -- 每一个具体操的key是操作名称，`description` 项是该操作的介绍，`tasks`中承载该操作所需执行的具体步骤（一个列表），当该操作被用户触发，将按顺序执行每一步骤。 -- 每一个步骤包含如下几个字段： - `name`：步骤名称，必填字段。 - `playbook`：表示用`ansible-playbook`执行对应的脚本，内容为 playbook 的路径（基于`workspace`目录的相对路径）。必填字段。目前仅支持`playbook`这一种模式。 - `vars`：脚本执行时所读取的配置文件路径（基于`workspace`目录的相对路径）。非必填字段。 - `scope`：限定了需要执行该步骤的节点，即主机组（在`config.yaml`中定义）。必填字段，通常默认为`all`。 -- 当用户执行了命令行`oedp run `，`oedp`工具会按顺序逐一执行这个操作下的所有的步骤（`tasks`）。 -- 在`playbook`模式下，每个步骤等价于如下命令行： - -```bash -ansible-playbook .yaml -i config.yaml -e @.yaml --limit -``` - -### 3.2 `main.yaml`举例说明： - -```yaml -name: kubernetes-1.31.1 # 插件名称 -version: 1.0.0 # 插件版本号 -description: install kubernetes 1.31.1 # 插件描述 -action: - install: # 操作install - description: install kubernetes # 操作install的描述 - tasks: - - name: prepare for install # 操作install的第1个步骤 - playbook: set-env.yml # 当前步骤所执行的playbook文件（基于workspace目录的相对路径） - scope: all # 执行当前步骤的主机组名称（在config.yaml中定义） - - name: install kubernetes # 操作install的第2个步骤 - playbook: init-k8s.yml # 当前步骤所执行的playbook文件（基于workspace目录的相对路径） - vars: variables.yml # 当前步骤所读取的配置文件（基于workspace目录的相对路径） - scope: all # 执行当前步骤的主机组名称（在config.yaml中定义） - delete: - description: delete kubernetes - tasks: - - name: delete kubernetes - playbook: delete-k8s.yml - scope: all - clean: - description: clean cache files - tasks: - - name: clean cache files - playbook: clean-k8s.yml - scope: all -``` - -- 在这个示例中，当用户执行了 `oedp run install` 命令，工具会按顺序执行如下命令： - `ansible-playbook set-env.yml -i config.yaml --limit all` - `ansible-playbook init-k8s.yml -i config.yaml -e @variables.yml --limit all` -- 用户可以通过`oedp run install`、`oedp run delete`、`oedp run clean`命令行来触发对应的操作。 - -## 4 `config.yaml` - -部署脚本在执行过程中的可调整参数都在同一个配置文件`config.yaml`中承载，降低使用者的学习成本和开发者的维护成本。 - -- `config.yaml`包含部署环境的节点信息（主机组），以及部署软件相关的参数配置。 -- `config.yaml`遵循 ansible 的 inventory 文件配置规则，工具在执行 ansible playbook 时直接作为 inventory 传入。 -- 需要注意，`config.yaml`是对普通用户暴露的唯一配置文件，应当注意美观，避免歧义，并保留尽可能详细的注释说明。 -- 在`playbook`模式下，通过如下命令行的方式导入`config.yaml`中的配置： - -```bash -ansible-playbook .yaml -i config.yaml -e @.yaml --limit -``` - -### 4.1 `config.yaml`示例1：本地部署 - -```yaml -all: - hosts: - localhost: - ansible_connection: local - vars: - deepseek_version: 8b - ollama_download_url: - amd64: https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/files/ollama-linux-amd64.tgz - arm64: https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/files/ollama-linux-arm64.tgz - ollama_download_path: /root/tmp # 下载的目标路径 - modelfile_download: https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/files/DeepSeek-R1-Distill-Llama-8B-Q4_K_M.gguf - modelfile_download_path: /root/tmp # 下载的目标路径 - # 模型参数 - parameter: - temperature: 0.7 - top_p: 0.7 - top_k: 30 - num_ctx: 4096 - num_thread: 4 # 线程数，建议不超过CPU核数 - num_gpu: 0 # GPU数 0 for none, -1 for all. - download_checksum: true # 是否打开sha256sum校验 - download_timeout: 600 # 下载大文件时的超时时间(秒) - download_retry: 6 # 下载大文件重试次数 - ansible_ssh_common_args: '-o StrictHostKeyChecking=no' -``` - -### 4.2 `config.yaml`示例2：单节点部署 - -```yaml -all: - hosts: - host1: - ansible_host: 127.0.0.1 # 远端IP - ansible_port: 22 # 端口号 - ansible_user: root # 用户名 - ansible_password: PASSWORD # 密码 - vars: - ansible_ssh_common_args: '-o StrictHostKeyChecking=no' - - kubectl_apply: pytorch-deployment.yaml - namespace: pytorch-namespace - replicas: 1 - containers: - http: - name: http-container - image: hub.oepkgs.net/oedeploy/pytorch/pytorch:latest # amd64 - workspace_mount: /tmp - service: - port: 8080 - target_port: 8080 - node_port: 30699 - training: - epoch: 2 # 训练轮数 -``` - -### 4.3 `config.yaml`示例3：多节点部署 - -```yaml -all: - hosts: - host1: - ansible_host: 192.168.1.101 - ansible_port: 22 - ansible_user: root - ansible_password: "PASSWORD" - architecture: amd64 # e.g. [ amd64, arm64 ] - host2: - ansible_host: 192.168.1.102 - ansible_port: 22 - ansible_user: root - ansible_password: "PASSWORD" - architecture: amd64 # e.g. [ amd64, arm64 ] - vars: - version: 3.9.0 - download_url: https://get.helm.sh/ - temp_path: /tmp - install_path: /usr/local/bin - force_install: yes - ansible_ssh_common_args: '-o StrictHostKeyChecking=no' -``` - -### 4.4 `config.yaml`示例4：多节点分组部署 - -```yaml -all: - children: - masters: - hosts: - HOST1: # e.g. 192.168.10.1 - ansible_host: 192.168.10.1 # e.g. 192.168.10.1 - ansible_port: 22 - ansible_user: root - ansible_password: "PASSWORD" - architecture: amd64 # e.g. [ amd64, arm64 ] - oeversion: 24.03-LTS # e.g. [ 22.03-LTS, 24.03-LTS ] - runtime: docker # e.g. [ docker, containerd ] - workers: - hosts: - HOST2: - ansible_host: 192.168.10.2 - ansible_port: 22 - ansible_user: root - ansible_password: "PASSWORD" - architecture: amd64 - oeversion: 24.03-LTS - runtime: docker - HOST3: - ansible_host: 192.168.10.3 - ansible_port: 22 - ansible_user: root - ansible_password: "PASSWORD" - architecture: amd64 - oeversion: 24.03-LTS - runtime: docker - new-workers: # new-workers字段不可删除 - hosts: - vars: - ansible_ssh_common_args: '-o StrictHostKeyChecking=no' - - init_cluster_force: "true" # e.g. [ "true", "false" ] 强制初始化集群 - remove_master_no_schedule_taints: "true" - service_cidr: 10.96.0.0/16 # 服务网段 - pod_cidr: 10.244.0.0/16 # pod ip 网段 - certs_expired: 3650 # 证书过期时间 - # lb_kube_apiserver_ip: - lb_kube_apiserver_port: 8443 - has_deployed_containerd: "false" # e.g. [ "true", "false" ] 是否已有 containerd - - # 以下参数需要与build过程中的host.ini保持一致，如果不涉及请忽视 - kubernetes_version: 1.31.1 - calico_version: 3.28.2 - pause_image: "registry.k8s.io/pause:3.10" -``` - -## 5 `workspace`目录 - -`workspace`目录中承载了部署脚本的主体内容，目录结构不做限制。 - -- `main.yaml`和 `config.yaml`涉及的各种文件、源码、二进制、脚本、playbook，都在`workspace`目录中承载，开发者可自定义其中的子目录。 - -- `workspace`目录视为整个插件执行过程的根目录。 - -### 5.1 `workspace`示例 - -这里有一个用于部署nginx服务的 oeDeploy 插件 - -`config.yaml`内容如下： - -```yaml -name: nginx -version: 1.25.3 -description: Install and configure nginx web server -action: - install: - description: Install nginx and start service - tasks: - - name: Install nginx via yum - playbook: install.yml - - name: Configure and start nginx - playbook: configure.yml -``` - -`config.yaml`的内容如下： - -```yaml -all: - hosts: - 127.0.0.1: - ansible_host: 127.0.0.1 - ansible_port: 22 - ansible_user: root # 必须为root用户 - ansible_password: xxxxxxxx - vars: - nginx_port: 80 - ansible_ssh_common_args: "-o StrictHostKeyChecking=no" -``` - -`workspace`目录下包含如下文件： - -1. `install.yml`：用于安装nginx及其他依赖软件 -2. `configure.yml`：用于配置nginx参数并启动nginx服务 -3. `nginx.conf.j2`：作为配置nginx参数的模板。虽然未在`config.yaml`中体现，但会在`configure.yml`中被使用。 - -`install.yml`的内容如下： - -```yaml ---- -- hosts: all - become: yes - tasks: - - name: Install nginx - yum: - name: nginx - state: present - - name: Ensure nginx is running and enabled - service: - name: nginx - state: started - enabled: yes -``` - -`configure.yml`的内容如下： - -```yaml ---- -- hosts: all - become: yes - tasks: - - name: Generate nginx configuration - template: - src: nginx.conf.j2 - dest: /etc/nginx/nginx.conf - owner: root - group: root - mode: '0644' - - name: Validate nginx configuration - command: nginx -t - register: nginx_test - changed_when: false - notify: restart nginx - - name: Restart nginx - service: - name: nginx - state: restarted - when: nginx_test.rc == 0 -``` - -`nginx.conf.j2`的内容如下： - -```jinja2 -worker_processes auto; -events { - worker_connections 1024; -} - -http { - include /etc/nginx/mime.types; - default_type application/octet-stream; - - sendfile on; - keepalive_timeout 65; - - server { - listen {{ nginx_port }}; - server_name localhost; - - location / { - root /usr/share/nginx/html; - index index.html index.htm; - } - - error_page 500 502 503 504 /50x.html; - location = /50x.html { - root /usr/share/nginx/html; - } - } -} -``` - -## 6 插件打包 - -如果要发布插件供其他用户使用，需要将插件打包成`{plugin_name}.tar.gz`的格式，压缩包的名称与插件名称保持一致，且解压后应当仅生成一个目录，例如： - -``` -kubernetes-1.31.1.tar.gz -`-- kubernetes-1.31.1 - |-- main.yaml - |-- config.yaml - `-- workspace/ -``` - -通常可以使用如下命令行完成打包： - -```bash -tar zcvf kubernetes-1.31.1.tar.gz kubernetes-1.31.1/ -``` - -## 7 插件开发Tips - -- 如果 ansible 脚本中涉及文件的跨节点拷贝，建议在拷贝之前，在目标节点上安装软件包`python3-libselinux` -- 为了部署的流畅性，建议在`config.yaml`中的`vars`字段增加配置项`ansible_ssh_common_args: '-o StrictHostKeyChecking=no'`，从而关闭严格的 HostKey 校验。 diff --git a/doc/zh/DevelopInstruction.md b/doc/zh/DevelopInstruction.md new file mode 100644 index 0000000..3176ec5 --- /dev/null +++ b/doc/zh/DevelopInstruction.md @@ -0,0 +1,140 @@ +# oeDeploy 插件开发 + +## 1 oeDeploy 插件介绍 + +oeDeploy 插件（plugin）是 oedp 工具中提供自动化部署能力的组件，将复杂的部署流程 ansible 化来实现自动化部署。插件中可能会集成多种部署操作（action），例如安装、卸载、环境清理等，每一个部署操作都会对应一个或多个 ansible playbook。插件的所有可配置项都应当集中配置，以降低使用者的学习成本和开发者的维护成本。 + +## 2 插件目录结构 + +oeDeploy 插件目录名称，即插件名称，可以包含版本号（表示软件本身的版本，而非插件的版本） + +插件目录下包含如下内容： + +| 文件或者目录名 | 类型 | 介绍 | +| -------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| config.yaml | yaml | 对用户暴露的唯一配置文件。包含主机相关的配置，如 ip、密码、密钥、端口号等，还包含了软件部署相关的配置项。 | +| main.yaml | yaml | 包含了插件的各种信息，例如名称、版本号、描述，也包含了每个部署操作（action）执行时的具体步骤，每个步骤都对应一个脚本或者playbook（以workspace为根目录）。 | +| doc | 目录 | 承载插件相关的用户文档。该目录非必需。 | +| workspace | 目录 | 承载了软件安装部署所使用的所有文件、源码、二进制、脚本、playbook等等。目录内结构不做限制。 | + +## 3 main.yaml + +`main.yaml`主要用于记录插件的关键信息，包括：名称（`name`）、版本（`version`）、介绍（`description`）、操作（`action`）等，当用户执行 `oedp info` 命令时，`oedp` 工具会读取并解析该文件，然后向用户展示其详细信息。 + +- `action` 字段是一个字典（key-value map），每一个 key 将作为操作的名称。在下方的案例中，用户可以通过 `oedp run install`、`oedp run delete`、`oedp run clean` 命令行来触发对应的执行步骤（`tasks`）。 +- 每一个具体操作中，`description` 项是该操作的说明，用于在执行 `oedp info` 命令时向用户展示；而 `tasks` 项中则记录该操作的具体步骤，为一个列表，执行该操作时，将按顺序执行每一项步骤。 +- 在每个步骤中，开发者应当指定该步骤需要执行的 `playbook` 的路径，也可以在 `vars` 中指定变量文件的路径，`vars` 字段不是必需的。这里所填写的路径都是 `workspace` 目录的相对路径。此外，可以指定 `scope`，即该步骤需要执行的主机组，默认为 all。 +- 在下方的案例中，当用户执行了 `oedp run install` 命令，工具会按顺序执行如下命令： + `ansible-playbook set-env.yml -i config.yaml -e variables.yml --limit all` + `ansible-playbook init-k8s.yml -i config.yaml -e variables.yml --limit all` + 这里的 `config.yaml` 会在下文介绍。 + +```yaml +name: kubernetes +version: 1.31.1 +description: install kubernetes 1.31.1 +action: + install: + description: install kubernetes + tasks: + - name: prepare for install + playbook: set-env.yml + scope: all + - name: install kubernetes + playbook: init-k8s.yml + vars: variables.yml + scope: all + delete: + description: delete kubernetes + tasks: + - name: delete kubernetes + playbook: delete-k8s.yml + scope: all + clean: + description: clean cache files + tasks: + - name: clean cache files + playbook: clean-k8s.yml + scope: all +``` + +## 4 config.yaml + +`config.yaml`是插件中的用户配置文件，主要包含主机组的节点信息，以及部署软件相关的信息，遵循 ansible 的 inventory 文件配置规则，工具在执行 ansible playbook 时直接作为 inventory 传入。 + +需要注意，`config.yaml` 是对普通用户暴露的唯一配置文件，应当注意美观，避免歧义，并保留适当的注释说明。 + +```yaml +all: + children: + masters: + hosts: + 172.27.76.114: # master node IP + ansible_host: 172.27.76.114 # master node IP + ansible_port: 22 + ansible_user: root + ansible_password: PASSWORD + architecture: amd64 # amd64 or arm64 + oeversion: 24.03-LTS # 22.03-LTS or 24.03-LTS + workers: + hosts: + 172.27.70.60: # worker node IP + ansible_host: 172.27.70.60 # worker node IP + ansible_port: 22 + ansible_user: root + ansible_password: PASSWORD + architecture: amd64 + oeversion: 24.03-LTS + 172.27.72.90: # worker node IP + ansible_host: 172.27.72.90 # worker node IP + ansible_port: 22 + ansible_user: root + ansible_password: PASSWORD + architecture: amd64 + oeversion: 24.03-LTS + vars: + init_cluster_force: "true" + service_cidr: 10.96.0.0/16 + pod_cidr: 10.244.0.0/16 + certs_expired: 3650 + has_deployed_containerd: "false" + ansible_ssh_common_args: "-o StrictHostKeyChecking=no" +``` + +## 5 workspace + +`workspace` 目录中承载了部署脚本的主体内容，目录结构不做限制，需要与 `main.yaml`和 `config.yaml`中的各参数对应。 + +`workspace` 目录视为整个插件执行过程中的根目录。 + +当前示例中，`workspace`中的目录结构为： + +```text +workspace +|-- roles +| `-- ... +|-- clean-k8s.yml +|-- delete-k8s.yml +|-- init-k8s.yml +|-- set-env.yml +|-- variables.yml +`-- ... +``` + +## 6 插件打包 + +如果要发布插件供用户使用，需要将插件打包成 `{plugin_name}.tar.gz` 的格式，压缩包的名称和包内目录的名称要对应，且解压后应当仅生成一个目录，例如： + +```text +kubernetes-1.31.1.tar.gz +`-- kubernetes-1.31.1 + |-- main.yaml + |-- config.yaml + `-- workspace/ +``` + +当前示例中，使用如下命令行完成打包： + +````bash +tar zcvf kubernetes-1.31.1.tar.gz kubernetes-1.31.1/ +```` diff --git a/doc/zh/MCPGuide.md b/doc/zh/MCPInstruction.md similarity index 93% rename from doc/zh/MCPGuide.md rename to doc/zh/MCPInstruction.md index 2022a7c..09b48e3 100644 --- a/doc/zh/MCPGuide.md +++ b/doc/zh/MCPInstruction.md @@ -1,8 +1,8 @@ -# oeDeploy MCP Server 指南 +# oeDeploy MCP Server 使用说明 MCP（Model Context Protocol，模型上下文协议）是一项开放协议，旨在为 AI 系统与外部数据源、工具之间建立标准化连接接口；其核心是通过客户端—服务器架构，让大语言模型能安全高效地访问本地文件、数据库、API服务等资源，实现跨平台、跨工具的智能交互。 oeDeploy 当前提供两种 MCP Server： 1. [oeDeploy MCP Server mcp-oedp](https://gitee.com/openeuler/oeDeploy/blob/master/oedp-mcp/mcp-oedp/README.md)，该 MCP Server 用于帮助用户智能调用 oeDeploy 相关能力实现软件快速部署。 -2. [oeDeploy MCP Server mcp-make-oedp-plugin](https://gitee.com/openeuler/oeDeploy/blob/master/oedp-mcp/mcp-make-oedp-plugin/README.md)，该 MCP Server 用于帮助用户快速开发自定义 oeDeploy 插件。 \ No newline at end of file +2. [oeDeploy MCP Server mcp-make-oedp-plugin](https://gitee.com/openeuler/oeDeploy/blob/master/oedp-mcp/mcp-make-oedp-plugin/README.md)，该 MCP Server 用于帮助用户快速开发自定义 oeDeploy 插件。 diff --git a/doc/zh/UseCase.md b/doc/zh/UseCase.md index ae9953b..45c47df 100644 --- a/doc/zh/UseCase.md +++ b/doc/zh/UseCase.md @@ -1,100 +1,898 @@ # oeDeploy 应用案例 -## 应用案例 1：kubernetes 一键部署 +## 应用案例 1：Kubernetes 一键部署 -准备 3 个 2U4G 的虚拟机环境（三层网络互通），使用的 OS 版本为 openEuler 24.03 或 22.03 的任意版本，目标是部署由 1 个 master、2 个 worker 构成的 k8s 集群。 +1. 准备 3 个 2U4G 的虚拟机环境（三层网络互通），使用的 OS 版本为 openEuler 24.03 或 22.03 的任意版本，目标是部署由 1 个 master、2 个 worker 构成的 k8s 集群。 -在任意节点上，下载并安装 oeDeploy 的命令行工具 oedp。 +2. 在任意节点上，下载并安装 oeDeploy 的命令行工具 oedp。 -````bash -wget https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/noarch/oedp-1.0.2-1.oe2503.noarch.rpm -yum install -y oedp-1.0.2-1.oe2503.noarch.rpm -```` + ````bash + wget https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/noarch/oedp-1.1.1-0.oe2403sp2.noarch.rpm + yum install -y oedp-1.1.1-0.oe2403sp2.noarch.rpm + ```` -执行以下命令，获取插件包，确保当前目录下出现了目录`kubernetes-1.31.1`。 +3. 执行以下命令，获取插件包，确保当前目录下出现了目录`kubernetes-1.31.1`。 -```shell -oedp repo update -oedp init kubernetes-1.31.1 -``` + ```shell + oedp repo update + oedp init kubernetes-1.31.1 + ``` -执行`info`命令以查看插件详细信息： +4. 执行`info`命令以查看插件详细信息。 -```shell -oedp info -p kubernetes-1.31.1 -``` + ```shell + oedp info -p kubernetes-1.31.1 + ``` -修改项目配置文件，根据实际情况配置节点信息： +5. 修改项目配置文件，根据实际情况配置节点信息。 -```shell -vim kubernetes-1.31.1/config.yaml -``` + ```shell + vim kubernetes-1.31.1/config.yaml + ``` -````yaml -all: - children: - masters: + ````yaml + all: + children: + masters: + hosts: + # master节点数量须为奇数 + 172.27.76.114: # master node IP + ansible_host: 172.27.76.114 # master node IP + ansible_port: 22 + ansible_user: root + ansible_password: "" + architecture: amd64 # [ amd64, arm64 ] + oeversion: 24.03-LTS # [ 22.03-LTS, 24.03-LTS ] + runtime: docker # [ docker, containerd ] + workers: + hosts: + 172.27.70.60: # worker node IP + ansible_host: 172.27.70.60 # worker node IP + ansible_port: 22 + ansible_user: root + ansible_password: "" + architecture: amd64 + oeversion: 24.03-LTS + runtime: docker + 172.27.72.90: + ansible_host: 172.27.72.90 + ansible_port: 22 + ansible_user: root + ansible_password: "" + architecture: amd64 + oeversion: 24.03-LTS + runtime: docker + new-workers: # new-workers 字段不可删除 + hosts: + vars: + ansible_ssh_common_args: '-o StrictHostKeyChecking=no' + + init_cluster_force: "true" # e.g. [ "true", "false" ] 强制初始化集群 + remove_master_no_schedule_taints: "true" + service_cidr: 10.96.0.0/16 # 服务网段 + pod_cidr: 10.244.0.0/16 # pod ip 网段 + certs_expired: 3650 # 证书过期时间 + # lb_kube_apiserver_ip: + lb_kube_apiserver_port: 8443 + has_deployed_containerd: "false" # e.g. [ "true", "false" ] 是否已有 containerd + + # 以下参数需要与 build 过程中的 host.ini 保持一致，如果不涉及请忽视 + kubernetes_version: 1.31.1 + calico_version: 3.28.2 + pause_image: "registry.k8s.io/pause:3.10" + ```` + + > 注意：须确保节点间 ssh 可联通，支持密码登录和密钥登录，如果使用密钥登录，则不需要配置密码。 + +6. 执行以下命令以开始自动化部署。 + + ```shell + oedp run install -p kubernetes-1.31.1 + ``` + +7. 执行以下命令以卸载 Kubernetes。 + + ```shell + oedp run uninstall -p kubernetes-1.31.1 + ``` + + > -p 参数表示解压后的文件目录。如果进入 kubernetes-1.31.1 插件根目录，执行 oedp 命令时无需 -p 参数。 + +## 应用案例 2：AnythingLLM 一键部署 + +1. 下载 oedp 命令行工具，并用 yum 安装。如有更新的 oedp 版本，可以选择新版本。 + + ```bash + wget https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/noarch/oedp-1.1.1-0.oe2403sp2.noarch.rpm + yum install -y oedp-1.1.1-0.oe2403sp2.noarch.rpm + ``` + +2. 获取并初始化`AnythingLLM`插件。 + + ```shell + oedp repo update + oedp init anythingLLM + ``` + +3. 根据实际情况，修改 config.yaml。确保部署节点网络正常。 + +4. 一键部署： + + ````bash + oedp run install -p angthingLLM # -p <插件目录> + ```` + +5. 一键卸载： + + ````bash + oedp run uninstall -p angthingLLM # -p <插件目录> + ```` + +### Demo：部署并打印 AnythingLLM 信息 + +1. 编辑 config.yaml 文件。 + + ````yaml + all: + hosts: + host1: + ansible_host: 192.168.124.17 # 远端IP + ansible_port: 22 # 端口号 + ansible_user: root # 用户名 + ansible_password: passwd # 密码 + + vars: + docker_download_url: + x86_64: https://download.docker.com/linux/static/stable/x86_64/docker-26.1.4.tgz + aarch64: https://download.docker.com/linux/static/stable/aarch64/docker-26.1.4.tgz + docker_download_path: /tmp + docker_image_urls: https://docker.m.daocloud.io + + container_name: "anythinglLLM-container" + docker_image: "mintplexlabs/anythingllm" + storage_location: "{{ lookup('env', 'HOME') }}/anythingllm" + host_port: 3001 + ```` + +2. 进入容器并测试 AnythingLLM 服务。 + + - 进入容器： + + ````bash + docker exec -it anythinglLLM-container /bin/bash + ```` + + - 测试 AnythingLLM 服务： + + ````bash + curl localhost:3001 + ```` + +3. 部署环境测试 AnythingLLM 服务。 + + ```bash + -curl 192.168.124.17:3001/ curl localhost:3001 + ``` + +4. 正常返回如下: + + ```html + + + + + + + AnythingLLM | Your personal LLM trained on anything + + + + + + + + + + + + + + + + + + +
+ + + ``` + +## 应用案例 3：DeepSeek-R1 一键部署 + +1. 准备一个 openEuler 环境（22.03-LTS-SPX、24.03-LTS-SPX），8B 模型的建议规格大于 8U16G。 + +2. 下载 oedp 命令行工具，并用 yum 安装。 + + ````bash + wget https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/noarch/oedp-1.1.1-0.oe2403sp2.noarch.rpm + yum install -y oedp-1.1.1-0.oe2403sp2.noarch.rpm + ```` + +3. 获取并初始化`DeepSeek-R1`插件。 + + ````bash + oedp repo update + oedp init deepseek-r1 + ```` + +4. 根据实际情况修改 deepseek-r1/config.yaml。用户可以直接使用这里的示例，不需要任何修改。 + + ````yaml + all: + hosts: + # 本地部署 或 远端部署 二选一 + # ================ 本地部署 ===================== + localhost: + ansible_connection: local + # ================ 远端部署 ===================== + # host1: + # ansible_host: 127.0.0.1 # 远端IP + # ansible_port: 22 # 端口号 + # ansible_user: root # 用户名 + # ansible_password: PASSWORD # 密码 + vars: + deepseek_version: 8b + # ollama 官方下载地址: https://ollama.com/download/ollama-linux-amd64.tgz，注意区分amd64和arm64 + # 为提高下载速度，已暂存在 OEPKGS 服务器上 + ollama_download: https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/2025.0330/ollama-linux-amd64.tgz + ollama_download_path: /tmp # 下载的目标路径 + # 模型文件下载地址: https://www.modelscope.cn/models/unsloth/DeepSeek-R1-Distill-Llama-8B-GGUF/resolve/master/DeepSeek-R1-Distill-Llama-8B-Q4_K_M.gguf + # 为提高下载速度，已暂存在 OEPKGS 服务器上 + modelfile_download: https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/2025.0330/DeepSeek-R1-Distill-Llama-8B-Q4_K_M.gguf + modelfile_download_path: /tmp # 下载的目标路径 + # 模型参数 + parameter: + temperature: 0.7 + top_p: 0.7 + top_k: 30 + num_ctx: 4096 + num_thread: 8 # 线程数，建议不超过 CPU 核数 + num_gpu: 0 # GPU数 0 for none, -1 for all. + + ansible_ssh_common_args: '-o StrictHostKeyChecking=no' + ```` + +5. 一键触发 DeepSeek-R1 自动化部署，oeDeploy 工具会下载所需的文件，自动安装部署，并完成对 DeepSeek-R1 的配置。 + + ````bash + oedp run install -p deepseek-r1 # -p + ```` + +6. 在部署完成后的节点上，打开 DeepSeek-R1 交互终端，开始对话。 + + ````bash + ollama run deepseek-r1:8b + ```` + +## 应用案例 4：EulerCopilot 一键部署 + +### 前提条件 + +1. 组件介绍 + + | 组件 | 端口 | 说明 | + |-------------------------|-------------------------|------------| + | euler-copilot-framework | 8002（内部端口） | 智能体框架服务 | + | euler-copilot-web | 8080 | 智能体前端界面 | + | euler-copilot-rag | 9988（内部端口） | 检索增强服务 | + | authhub-backend-service | 11120 （内部端口） | 鉴权服务后端 | + | authhub-web-service | 8000 | 鉴权服务前端 | + | mysql | 3306（内部端口） | MySQL数据库 | + | redis | 6379（内部端口） | Redis数据库 | + | minio | 9000（内部端口） 9001（外部部端口） | minio数据库 | + | mongo | 27017（内部端口） | mongo数据库 | + | postgres | 5432（内部端口） | 向量数据库 | + | secret_inject | 无 | 配置文件安全复制工具 | + +2. 软件要求 + + | 类型 | 版本要求 | 说明 | + |--------|----------------------------------|-----------------------------------------------------------| + | 操作系统 | openEuler 22.03 LTS 及以上版本 | 无 | + | K3s | >= v1.30.2，带有 Traefik Ingress 工具 | K3s 提供轻量级的 Kubernetes 集群，易于部署和管理 | + | Helm | >= v3.15.3 | Helm 是一个 Kubernetes 的包管理工具，其目的是快速安装、升级、卸载 EulerCopilot 服务 | + | python | >= 3.9.9 | python3.9.9 以上版本为模型的下载和安装提供运行环境 | + +3. 硬件要求 + + | 硬件资源 | 服务器（最小要求） | 服务器（推荐） | + |----------|-----------------------------|-------------------------| + | CPU | 4 核心 | 16 核心及以上 | + | RAM | 4 GB | 64 GB | + | 存储 | 32 GB | 64G | + | 大模型名称 | deepseek-llm-7b-chat | DeepSeek-R1-Llama-8B | + | 显存（GPU） | 8 GB（NVIDIA RTX A4000, 1个） | 16 GB（NVIDIA A100, 2个） | + + **注意**： + + - 若无 GPU 或 NPU 资源，建议通过调用 OpenAI 接口的方式来实现功能。 + - 调用第三方 OpenAI 接口的方式不需要安装高版本的 python (>=3.9.9)。 + - 如有 k8s 集群环境，则不需要单独安装 k3s，要求 version >= 1.28。 + +4. 网络要求 + + - 可访问 hub.oepkgs.net + - 可访问 modelscope.cn + - 开放端口：80/443/ + +5. 域名要求 + + 为确保 EulerCopilot 的正确部署和使用，请准备以下两个服务的域名：authhub、eulercopilot。这些子域名需属于同一个主域名下，例如 + `www.eulercopilot.local`、`authhub.eulercopilot.local`。 + + 您可以通过两种方式来完成这项准备工作： + + - **预先申请域名**：为每个服务（AuthHub、Euler Copilot）分别注册上述格式的子域名。 + - **本地配置**：如果是在开发或测试环境中，您可以直接在本地 Windows 主机文件中进行配置。打开位于 + `C:\Windows\System32\drivers\etc\hosts` 的文件，并添加相应的条目以映射这些子域名到本地或特定的 IP 地址，例如： + + ```bash + 172.0.0.1 authhub.eulercopilot.local + 172.0.0.1 www.eulercopilot.local + ``` + +### 部署过程 + +1. 安装 oeDeploy 工具。 + + ```shell + wget https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/noarch/oedp-1.1.1-0.oe2403sp2.noarch.rpm + yum install -y oedp-1.1.1-0.oe2403sp2.noarch.rpm + ``` + +2. 获取并初始化 EulerCopilot 插件。 + + ```shell + oedp repo update + oedp init euler-copilot + ``` + +3. 根据实际情况修改 `config.yaml` 文件，示例如下： + + ```yaml + all: hosts: - # master节点数量须为奇数 - 172.27.76.114: # master node IP - ansible_host: 172.27.76.114 # master node IP + host1: + # 节点空余内存需要大于 16G，建议规格 32G 以上 + # 部署节点 IP + ansible_host: HOST_IP + # 部署节点 SSH 端口 ansible_port: 22 - ansible_user: root - ansible_password: "" - architecture: amd64 # [ amd64, arm64 ] - oeversion: 24.03-LTS # [ 22.03-LTS, 24.03-LTS ] - runtime: docker # [ docker, containerd ] - workers: + # 部署节点用户 + ansible_user: root # 目前仅支持 root 用户 + # 部署节点密码 + ansible_password: PASSWORD + + vars: + ansible_ssh_common_args: '-o StrictHostKeyChecking=no' + + # 部署日志目录 + log_dir: "/var/log/deploy-euler-copilot" + + # 源码仓库配置 + repo_config: + # 源码 url + url: "https://gitee.com/openeuler/euler-copilot-framework.git" + # 源码仓放置目录 + dest_dir: "/opt/euler-copilot-framework" + # 指定分支、tag 和 commit + version: "release-0.9.5" + # 是否覆盖本地修改 + force: yes + + # 模型配置 + models: + # 用于问答的大模型；需要为 OpenAI 兼容接口 + answer: + # [必填] 接口 URL（无需带上“v1”后缀） + endpoint: https://api.deepseek.com + # [必填] 接口 API Key；默认置空 + key: sk-xxx + # [必填] 模型名称 + name: deepseek-chat + # [必填] 模型最大上下文数；建议 >= 8192 + ctxLength: 8192 + # 模型最大输出长度，建议 >= 2048 + maxTokens: 8192 + # 用于 Function Call 的模型；建议使用特定推理框架 + functionCall: + # 推理框架类型，默认为 ollama + # 可用的框架类型：["vllm", "sglang", "ollama", "openai"] + backend: openai + # 模型地址；不填则与问答模型一致 + endpoint: https://dashscope.aliyuncs.com/compatible-mode/v1 + # API Key；不填则与问答模型一致 + key: sk-xxx + # 模型名称；不填则与问答模型一致 + name: qwen-plus + # 模型最大上下文数；不填则与问答模型一致 + ctxLength: + # 模型最大输出长度；不填则与问答模型一致 + maxTokens: + # 用于数据向量化（Embedding）的模型 + embedding: + # 推理框架类型，默认为 openai + # [必填] Embedding 接口类型：["openai", "mindie"] + type: openai + # [必填] Embedding URL（需要带上“v1”后缀） + endpoint: https://api.siliconflow.cn/v1 + # [必填] Embedding 模型 API Key + key: sk-xxx + # [必填] Embedding 模型名称 + name: BAAI/bge-m3 + ``` + +4. 一键部署： + + ```shell + oedp run install -p ./euler-copilot + ``` + +5. 验证安装： + + 您可以参考 [此文档](https://e.gitee.com/open_euler/repos/openeuler/euler-copilot-framework/blob/master/docs/user-guide/%E9%83%A8%E7%BD%B2%E6%8C%87%E5%8D%97/%E7%BD%91%E7%BB%9C%E7%8E%AF%E5%A2%83%E4%B8%8B%E9%83%A8%E7%BD%B2%E6%8C%87%E5%8D%97.md#%E9%AA%8C%E8%AF%81%E5%AE%89%E8%A3%85) 来验证安装是否成功。 + +6. 一键卸载： + + ```shell + oedp run uninstall -p ./euler-copilot + ``` + +## 应用案例 5：KubeRay 一键部署 + +### 环境准备 + +1. 部署 Kubernetes 集群： + + 在目标集群机器上部署 Kubernetes 1.31.1，此处以 1 master + 2 worker 的标准 K8S 集群为例，其中 master 节点的 IP 为 192.168.1.101。可使用`kubernetes-1.31.1`插件进行自动化部署。 + +2. 安装 Helm： + + 在 master 节点上安装 Helm，可使用`helm-3.9.0`插件进行自动化安装。 + +### 部署 KubeRay + +1. 获取`kuberay`插件： + + 使用以下命令，获取并初始化`kuberay`插件。 + + ```shell + oedp repo update + oedp init kuberay + ``` + +2. 修改`config.yaml`： + + 以下是`kuberay/config.yaml`的示例，根据实际情况修改此文件。 + + ```yaml + all: hosts: - 172.27.70.60: # worker node IP - ansible_host: 172.27.70.60 # worker node IP - ansible_port: 22 - ansible_user: root - ansible_password: "" - architecture: amd64 - oeversion: 24.03-LTS - runtime: docker - 172.27.72.90: - ansible_host: 172.27.72.90 - ansible_port: 22 - ansible_user: root - ansible_password: "" - architecture: amd64 - oeversion: 24.03-LTS - runtime: docker - new-workers: # new-workers字段不可删除 + host1: + ansible_host: 192.168.1.101 # master 节点的 IP + ansible_port: 22 # ssh 的端口 + ansible_user: root # ssh 的用户，非root用户需要 sudo 权限 + ansible_password: PASSWORD # 上述用户的密码 + vars: + temp_path: /tmp + namespace: kuberay # 命名空间 + version: 1.2.2 # KubeRay chart 的版本 + + helm_repo_name: "kuberay" # 本地 Helm 仓库别名 + helm_repo_url: "https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/2025.0330/kuberay-helm" + + kuberay_operator_values_file: "" + # 以上配置项 kuberay_operator_values_file 为高级配置：指定一个 values 文件，用于自定义 + # KubeRay operator 组件的安装。需填写绝对路径，若留空，则采用以下配置： + kuberay_operator_values: + repository: "hub.oepkgs.net/oedeploy/quay.io/kuberay/operator" # KubeRay operator docker 镜像 url + tag: v1.2.2 # KubeRay operator docker 仓库 tag + + ray_cluster_values_file: "" + # 以上配置项 ray_cluster_values_file 为高级配置：指定一个 values 文件，用于自定义 + # Ray 组件的安装。需填写绝对路径，若留空，则采用以下配置： + ray_cluster_values: + repository: "hub.oepkgs.net/oedeploy/rayproject/ray-with-pytorch" # Ray docker 镜像 url + tag: 2.9.0 # Ray docker 仓库 tag；使用默认 docker 源时，x86 为 2.9.0, arm 为 2.9.0-aarch64；具体的 tag 请至配置的仓库确认 + head: # 头节点资源 + cpu: "1" + memory: "2G" + worker: # 工作节点资源 + num: 1 + cpu: "1" + memory: "1G" + training: # 模型训练参数 + pip: "https://pypi.tuna.tsinghua.edu.cn/simple" + batch_size: 1024 + epoch: 5 + ``` + +3. 执行自动化部署： + + 在插件目录下执行`oedp run install`，或在任意位置执行`oedp run install -p [插件目录]`，即可完成自动化部署 KubeRay。 + +### 查看 Dashboard + +1. 查询对应端口： + + 在 master 节点，使用`kubectl get svc -A`命令查看端口映射： + + ````bash + NAMESPACE NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE + default kubernetes ClusterIP 10.96.0.1 443/TCP 24h + kube-system kube-dns ClusterIP 10.96.0.10 53/UDP,53/TCP,9153/TCP 24h + kuberay kuberay-operator ClusterIP 10.96.175.101 8080/TCP 9h + kuberay ray-cluster-kuberay-head-svc NodePort 10.96.168.232 10001:32414/TCP,8265:31457/TCP,8080:31582/TCP,6379:31938/TCP,8000:32102/TCP 9h + ```` + + 其中 8265 对应的端口，即为 Dashboard 的端口。 + +2. 打开 Dashboard 页面： + 使用 `http://ip:port/` 链接，即可打开 Dashboard 页面，查看 Ray Job / Serve / Cluster 及资源、日志等信息。其中 IP 为 master 节点 IP，port 为 3.1 中 8265 对应的端口。 + +### Demo 1：基于 FashionMNIST 数据集的 MLP 模型训练推理 + +1. 已完成 KubeRay 部署，Pod 资源要求至少 4U。 + +2. 在 master 节点，执行以下命令，即可一键自动完成模型训练、推理。 + + ````bash + oedp run train -p kuberay + ```` + +### Demo 2：单 Pod 与多 Pod 运行同个训练模型的时间对比 + +在 Kuberay 部署前，通过修改 config.yaml，进行 Pod 资源配置。 + +1. 将单 Pod 的资源设置为： + + ````bash + head: + cpu: "7" + memory: "14G" + worker: + num: 0 + ```` + + 然后执行： + + ````bash + oedp run install -p kuberay + oedp run train -p kuberay + ```` + +2. 将多 Pod 的资源设置为： + + ````bash + head: + cpu: "7" + memory: "14G" + worker: + num: 2 + cpu: "5" + memory: "10G" + ```` + + 然后执行： + + ````bash + oedp run install -p kuberay + oedp run train -p kuberay + ```` + +3. 对比两者运行时间： + + 该条件下，单 Pod 运行时间约为 25s，多 Pod 运行时间约为 67s。 + +## 应用案例 6：Pytorch 一键部署 + +1. 准备一个 k8s 集群。 + +2. 下载 oedp 命令行工具，并用 yum 安装。如有更新的 oedp 版本，可以选择新版本。 + + ````bash + wget https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/noarch/oedp-1.1.1-0.oe2403sp2.noarch.rpm + yum install -y oedp-1.1.1-0.oe2403sp2.noarch.rpm + ```` + +3. 获取并初始化`pytorch`插件。 + + ```shell + oedp repo update + oedp init pytorch + ``` + +4. 根据实际情况，修改 config.yaml。请确保目标节点为 k8s 的 master 节点。`kubectl_apply`需要与 workspace 下的 playbook 对应。 + +5. 一键部署： + + ````bash + oedp run install -p pytorch # -p <插件目录> + ```` + +6. 一键卸载： + + ````bash + oedp run uninstall -p pytorch # -p <插件目录> + ```` + +### Demo 1：部署并打印 PyTorch 信息 + +1. 根据实际情况，修改 config.yaml。以下为示例： + + ````yaml + all: + hosts: + localhost: + ansible_connection: local + vars: + ansible_ssh_common_args: '-o StrictHostKeyChecking=no' + # ================ demo 1: pytorch with http.server ===================== + kubectl_apply: pytorch-deployment.yaml + namespace: pytorch-namespace + replicas: 1 + containers: + http: + name: http-container + image: hub.oepkgs.net/oedeploy/pytorch/pytorch:latest # amd64 + # image: hub.oepkgs.net/oedeploy/pytorch/torchserve:latest-arm64 # arm64 + workspace_mount: /tmp + service: + port: 8080 + target_port: 8080 + node_port: 30699 + training: + epoch: 2 + ```` + +2. 执行一键部署。 + + ```shell + oedp run install -p pytorch + ``` + +3. 查看 pod。 + + ````bash + kubectl get pods -n pytorch-namespace + ```` + + ```` + NAME READY STATUS RESTARTS AGE + pytorch-deployment-db5d59bcb-ptqnp 1/1 Running 0 15m + ```` + +4. 查看端口映射。 + + ````bash + kubectl get svc -n pytorch-namespace + ```` + + ```` + NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE + pytorch-service NodePort 10.96.50.156 80:30699/TCP 15m + ```` + +5. 访问网页。 + + ````text + http://x.x.x.x:30699/ # master所在节点 + ```` + +6. 进入容器。 + + ````bash + kubectl exec -n pytorch-namespace -it pytorch-deployment-db5d59bcb-ptqnp -- /bin/bash + ```` + +7. 打印 PyTorch 信息。 + + ````bash + python -c "import torch; print(torch.__version__); print(torch.tensor([1.0, 2.0, 3.0]) + torch.tensor([4.0, 5.0, 6.0]))" + ```` + +### Demo 2：基于 MNIST 数据集的轻量 CNN 模型训练 + +1. 基于 demo 1 已完成 PyTorch 部署。 + +2. 一键自动完成模型训练。 + + ````bash + oedp run train -p pytorch # -p <插件目录> + ```` + + 回显形如： + + ````bash + ...... + TASK [Display training output] ***************************************************************************************************************************************************************************************************************** + ok: [localhost] => { + "msg": [ + "Train Epoch: 0 [0/60000]\tLoss: 2.3114", + "Train Epoch: 0 [6400/60000]\tLoss: 0.3884", + "Train Epoch: 0 [12800/60000]\tLoss: 0.1483", + "Train Epoch: 0 [19200/60000]\tLoss: 0.0510", + "Train Epoch: 0 [25600/60000]\tLoss: 0.1151", + "Train Epoch: 0 [32000/60000]\tLoss: 0.0191", + "Train Epoch: 0 [38400/60000]\tLoss: 0.0690", + "Train Epoch: 0 [44800/60000]\tLoss: 0.1995", + "Train Epoch: 0 [51200/60000]\tLoss: 0.0417", + "Train Epoch: 0 [57600/60000]\tLoss: 0.1821", + "Test Accuracy: 9862/10000 (98.62%)", + "Train Epoch: 1 [0/60000]\tLoss: 0.0052", + ...... + "Train Epoch: 1 [57600/60000]\tLoss: 0.0115", + "Test Accuracy: 9877/10000 (98.77%)" + ] + } + ```` + +## 应用案例 7：TensorFlow 一键部署 + +1. 准备一个 k8s 集群。 + +2. 下载 oedp 命令行工具，并用 yum 安装。如有更新的 oedp 版本，可以选择新版本。 + + ````bash + wget https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/noarch/oedp-1.1.1-0.oe2403sp2.noarch.rpm + yum install -y oedp-1.1.1-0.oe2403sp2.noarch.rpm + ```` + +3. 获取并初始化`tensorflow`插件。 + + ```shell + oedp repo update + oedp init tensorflow + ``` + +4. 根据实际情况，修改 config.yaml。请确保目标节点为 k8s 的 master 节点。`kubectl_apply`需要与 workspace 下的 playbook 对应。 + +5. 一键部署： + + ````bash + oedp run install -p tensorflow # -p <插件目录> + ```` + +6. 一键卸载： + + ````bash + oedp run uninstall -p tensorflow # -p <插件目录> + ```` + +### Demo 1: TensorFlow with Jupyter + +1. 编辑 config.yaml 文件。 + + ````yaml + all: hosts: - vars: - ansible_ssh_common_args: '-o StrictHostKeyChecking=no' + localhost: + ansible_connection: local + + vars: + ansible_ssh_common_args: '-o StrictHostKeyChecking=no' + + kubectl_apply: tensorflow-deployment.yaml + namespace: tensorflow-namespace + replicas: 1 + containers: + name: tensorflow-jupyter + image: hub.oepkgs.net/oedeploy/tensorflow/tensorflow:latest-jupyter # amd64 only + command: ["jupyter", "notebook", "--ip=0.0.0.0", "--allow-root", "--no-browser"] + service: + name: tensorflow-service + port: 80 + target_port: 8888 + node_port: 30088 + ```` - init_cluster_force: "true" # e.g. [ "true", "false" ] 强制初始化集群 - remove_master_no_schedule_taints: "true" - service_cidr: 10.96.0.0/16 # 服务网段 - pod_cidr: 10.244.0.0/16 # pod ip 网段 - certs_expired: 3650 # 证书过期时间 - # lb_kube_apiserver_ip: - lb_kube_apiserver_port: 8443 - has_deployed_containerd: "false" # e.g. [ "true", "false" ] 是否已有 containerd +2. 查看 pod 状态。 - # 以下参数需要与build过程中的host.ini保持一致，如果不涉及请忽视 - kubernetes_version: 1.31.1 - calico_version: 3.28.2 - pause_image: "registry.k8s.io/pause:3.10" + ````bash + kubectl get pods -n tensorflow-namespace + ```` + + ```` + NAME READY STATUS RESTARTS AGE + tensorflow-deployment-75b85948d8-w2n7b 1/1 Running 0 4m1s + ```` + +3. 进入 pod 容器，会有一个很明显的 TensorFlow 大字提示。 + + ````bash + kubectl exec -n tensorflow-namespace -it tensorflow-deployment-75b85948d8-w2n7b -- /bin/bash + ```` + +4. 打印 TensorFlow 信息。 + + ````bash + python -c "import tensorflow as tf; print(tf.__version__)" + ```` + +5. 打开 Jupyter 界面。 + + ````bash + http://x.x.x.x:30088/ # master 所在节点 + ```` + +### Demo 2：分布式部署训练集群 + +1. 编辑 config.yaml 文件。 + + ````yaml + all: + hosts: + localhost: + ansible_connection: local + + vars: + ansible_ssh_common_args: '-o StrictHostKeyChecking=no' + + kubectl_apply: tensorflow-distributed.yaml + namespace: tensorflow-namespace + ps: + replicas: 2 + containers: + name: tensorflow-ps + image: hub.oepkgs.net/oedeploy/tensorflow/tensorflow:latest # amd64 only + service: + name: tensorflow-ps-service + port: 2222 + target_port: 2222 + worker: + replicas: 2 + containers: + name: tensorflow-worker + image: hub.oepkgs.net/oedeploy/tensorflow/tensorflow:latest # amd64 only + service: + name: tensorflow-worker-service + port: 2222 + target_port: 2222 + ```` -```` +2. 查看 pod 状态。 -> 注意：须确保节点间 ssh 可联通，支持密码登录和密钥登录，如果使用密钥登录，则不需要配置密码。 + ````bash + kubectl get pods -n tensorflow-namespace + ```` -执行以下命令以开始自动化部署： + ```` + NAME READY STATUS RESTARTS AGE + tensorflow-ps-fdddfdb5f-8fc98 1/1 Running 0 2m59s + tensorflow-ps-fdddfdb5f-dgqm9 1/1 Running 0 2m59s + tensorflow-worker-6cd8947b75-gxcnq 1/1 Running 0 2m59s + tensorflow-worker-6cd8947b75-wbt57 1/1 Running 0 2m59s + ```` -```shell -oedp run install -p kubernetes-1.31.1 -``` + ````bash + kubectl logs tensorflow-ps-fdddfdb5f-8fc98 -n tensorflow-namespace + ```` -执行以下命令以卸载kubernetes： + ```` + 2025-02-07 09:25:24.882206: I tensorflow/core/util/port.cc:153] oneDNN custom operations are on. You may see slightly different numerical results due to floating-point round-off errors from different computation orders. To turn them off, set the environment variable `TF_ENABLE_ONEDNN_OPTS=0`. + 2025-02-07 09:25:24.915813: I tensorflow/core/platform/cpu_feature_guard.cc:210] This TensorFlow binary is optimized to use available CPU instructions in performance-critical operations. + To enable the following instructions: AVX2 AVX512F AVX512_VNNI FMA, in other operations, rebuild TensorFlow with the appropriate compiler flags. + TensorFlow version: 2.18.0 + Environment variables: environ({'PATH': '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin', 'HOSTNAME': 'tensorflow-ps-fdddfdb5f-8fc98', 'DEBIAN_FRONTEND': 'noninteractive', 'LANG': 'C.UTF-8', 'TF_CONFIG': '{\n "cluster": {\n "ps": ["tensorflow-ps:2222"],\n "worker": ["tensorflow-worker-0:2222", "tensorflow-worker-1:2222"]\n },\n "task": {"type": "ps", "index": 0}\n}\n', 'KUBERNETES_PORT_443_TCP_PROTO': 'tcp', 'TENSORFLOW_PS_PORT_2222_TCP_PROTO': 'tcp', 'TENSORFLOW_WORKER_SERVICE_PORT': '2222', 'TENSORFLOW_WORKER_PORT': 'tcp://10.96.56.106:2222', 'KUBERNETES_SERVICE_HOST': '10.96.0.1', 'KUBERNETES_PORT_443_TCP_PORT': '443', 'TENSORFLOW_PS_PORT_2222_TCP_PORT': '2222', 'TENSORFLOW_WORKER_PORT_2222_TCP_ADDR': '10.96.56.106', 'TENSORFLOW_WORKER_SERVICE_HOST': '10.96.56.106', 'TENSORFLOW_WORKER_PORT_2222_TCP_PROTO': 'tcp', 'KUBERNETES_SERVICE_PORT': '443', 'KUBERNETES_SERVICE_PORT_HTTPS': '443', 'KUBERNETES_PORT': 'tcp://10.96.0.1:443', 'KUBERNETES_PORT_443_TCP': 'tcp://10.96.0.1:443', 'TENSORFLOW_PS_PORT_2222_TCP': 'tcp://10.96.88.2:2222', 'TENSORFLOW_PS_PORT_2222_TCP_ADDR': '10.96.88.2', 'TENSORFLOW_WORKER_PORT_2222_TCP_PORT': '2222', 'KUBERNETES_PORT_443_TCP_ADDR': '10.96.0.1', 'TENSORFLOW_PS_SERVICE_HOST': '10.96.88.2', 'TENSORFLOW_PS_SERVICE_PORT': '2222', 'TENSORFLOW_PS_PORT': 'tcp://10.96.88.2:2222', 'TENSORFLOW_WORKER_PORT_2222_TCP': 'tcp://10.96.56.106:2222', 'HOME': '/root', 'ENABLE_RUNTIME_UPTIME_TELEMETRY': '1', 'TF2_BEHAVIOR': '1', 'TPU_ML_PLATFORM': 'Tensorflow', 'TPU_ML_PLATFORM_VERSION': '2.18.0'}) + This is the parameter server. + [2025-02-07 09:25:26.288107] Parameter server is running... + [2025-02-07 09:26:26.288219] Parameter server is running... + [2025-02-07 09:27:26.288358] Parameter server is running... + [2025-02-07 09:28:26.288519] Parameter server is running... + ```` -```shell -oedp run uninstall -p kubernetes-1.31.1 -``` +3. 卸载 pod。 -> -p 参数表示解压后的文件目录。如果进入 kubernetes-1.31.1 插件根目录，执行 oedp 命令时无需 -p 参数。 + ````bash + kubectl delete -f tensorflow-distributed.yaml + ```` -- Gitee