From 075a54ad49098e259577ca1ae046bc0a686fd43d Mon Sep 17 00:00:00 2001 From: Haro Date: Tue, 2 Jun 2026 08:24:03 +0000 Subject: [PATCH 1/9] [UPDATE][manifest] OlaresManifest 0.12.0 spec update - Update version to 0.12.0 - Add apiVersion v3 for shared apps (v2 deprecated after 1.12.6) - Add spec.accelerator for GPU resource declaration - Add workloadReplicas field - Add overlayGateway field - Add LLMGatewaySupported in options - Add appCommon and externalData permissions - Mark spec.subCharts and options.appScope as deprecated for apiVersion v3 --- docs/developer/develop/package/manifest.md | 120 ++++- docs/zh/developer/develop/package/manifest.md | 471 +++++++++++------- 2 files changed, 400 insertions(+), 191 deletions(-) diff --git a/docs/developer/develop/package/manifest.md b/docs/developer/develop/package/manifest.md index eea7c57717..cd7fc88082 100644 --- a/docs/developer/develop/package/manifest.md +++ b/docs/developer/develop/package/manifest.md @@ -7,14 +7,34 @@ outline: [2, 3] Every **Olares Application Chart** should include an `OlaresManifest.yaml` file in the root directory. `OlaresManifest.yaml` provides all the essential information about an Olares App. Both the **Olares Market protocol** and the Olares depend on this information to distribute and install applications. :::info NOTE -Latest Olares Manifest version: `0.11.0` -- Removed deprecated fields of sysData -- Updated the example of shared app -- Added the apiVersion -- Added the sharedEntrance section +Latest Olares Manifest version: `0.12.0` +- Added `apiVersion` field (`v1` for regular apps, `v3` for shared apps) +- Added `spec.accelerator` field for GPU resource declaration +- Added `workloadReplicas` field to declare all workload replica counts +- Added `overlayGateway` field for L2 overlay LAN discovery support +- Added `LLMGatewaySupported` in options for LLM Gateway support +- Added `appCommon` and `externalData` permissions +- Marked `spec.subCharts` and `options.appScope` as deprecated for `apiVersion: 'v3'` +- `apiVersion: 'v2'` for CSV2 apps is deprecated and will be removed after 1.12.6 ::: :::details Changelog +`0.12.0` +- Added `apiVersion` field: `v1` for regular apps, `v3` for shared apps (`v3` apps installed in xxx-shared namespace) +- Added `spec.accelerator` field for GPU resource declaration (modes: `nvidia`, `nvidia-gb10`, `apple-m`, `strix-halo`, `mthreads-m1000`, `cpu`) +- Added `workloadReplicas` field to declare all workload replica counts +- Added `overlayGateway` field for L2 overlay LAN discovery support +- Added `LLMGatewaySupported` in options +- Added `appCommon` and `externalData` permissions +- Marked `spec.subCharts` and `options.appScope` as deprecated for `apiVersion: 'v3'` +- `apiVersion: 'v2'` for CSV2 apps is deprecated, will be removed after 1.12.6 + +`0.11.0` +- Removed deprecated `sysData` field +- Updated shared app example +- Added `apiVersion` field +- Added `sharedEntrance` section + `0.10.0` - Modified the `categories` field - Added the `provider` field in the Permission section @@ -140,10 +160,14 @@ olaresManifest.version: "3.0.122" ## apiVersion - Type: `string` - Optional -- Accepted Value: `v1`,`v2` +- Accepted Value: `v1`, `v3` - Default: `v1` -For shared applications, use version `v2`, which supports multiple subcharts in a single OAC. For other applications, use `v1`. +For shared applications, use version `v3`, which will be installed in the `xxx-shared` namespace. For other applications, use `v1`. + +:::info NOTE +`apiVersion: 'v2'` is for CSV2 apps and is deprecated. It will be removed after Olares OS 1.12.6. Migrate to `v3` for shared applications. +::: ## Metadata @@ -438,6 +462,22 @@ Whether the app requires read and write permission to the `Cache` folder. If `.V Whether the app requires read and write permission to the `Data` folder. If `.Values.userspace.appData` is used in the deployment YAML, then `appData` must be set to `true`. +### appCommon + +- Type: `boolean` +- Optional + +Whether the app requires read and write permission to the `App Common` folder (cross-node, cross-app shared models). Use `{{ .Values.userspace.appCommon }}` in the deployment YAML to get the App Common directory path. + + +### externalData + +- Type: `boolean` +- Optional + +Whether the app requires read and write permission to the `External` folder (mounted NAS or other external disk data). This does not affect the access permissions of already-deployed apps on version 0.11.0. + + ### userData - Type: `list` @@ -604,6 +644,47 @@ When set to `true`, only the admin can install this app. When set to `true`, Olares forces the application to run under user ID `1000` (as a non-root user). +### accelerator +- Type: `map` +- Optional + +Declares GPU resources required by the application. For apps that need GPU, use `spec.accelerator` to declare resources instead of `spec.requiredMemory` or similar fields. + +:::info Example +```yaml +spec: + accelerator: + mode: nvidia # Supported modes: nvidia, nvidia-gb10, apple-m, strix-halo, mthreads-m1000, cpu + limitedCpu: 7000m + requiredCpu: 150m + requiredDisk: 50Mi + limitedDisk: 500Gi + limitedMemory: 40Gi + requiredMemory: 5Gi + requiredGPUMemory: 1Gi + limitedGPUMemory: 24Gi +``` +::: + +### workloadReplicas +- Type: `map` +- Optional + +Declares the replica count for each workload in the chart. Starting from 0.12.0, apps must add this variable in `OlaresManifest.yaml` to declare replica counts for all workloads. + +:::info Example +```yaml +workloadReplicas: + affine: 1 +``` +::: +The corresponding `values.yaml` must also include this value for backward compatibility: +```yaml +workloads: + affine: + replicaCount: 1 +``` + ## Middleware - Type: `map` - Optional @@ -964,6 +1045,31 @@ allowedOutboundPorts: This application supports deploying multiple independent instances within the same Olares cluster. This setting does not apply to paid applications or clients of shared applications. +### LLMGatewaySupported +- Type: `boolean` +- Default: `false` +- Optional + +When set to `true`, the application supports LLM Gateway calls. + +### overlayGateway +- Type: `map` +- Optional + +Declares the app's support for L2 overlay LAN discovery. When enabled, other apps can access this app via IP address in the LAN. +:::info Example +```yaml +overlayGateway: + enable: true # Enable L2 overlay LAN discovery, default false + entrances: + - port: 8096 # Overlay listening port + title: Jellyfin # Overlay entrance name + workload: jellyfin # Workload name for OAC validation + description: "Access Jellyfin using IP address in LAN" + protocol: tcp # Supported protocols: tcp/udp; defaults to both tcp and udp if omitted +``` +::: + ## Envs Declare the environment variables required for your application to run here. You can allow users to manually enter these values or reference existing system environment variables directly. diff --git a/docs/zh/developer/develop/package/manifest.md b/docs/zh/developer/develop/package/manifest.md index a771b597f1..73d7232bcd 100644 --- a/docs/zh/developer/develop/package/manifest.md +++ b/docs/zh/developer/develop/package/manifest.md @@ -7,36 +7,56 @@ outline: [2, 3] 每一个 Olares 应用的 Chart 根目录下都必须有一个名为 `OlaresManifest.yaml` 的文件。`OlaresManifest.yaml` 描述了一个 Olares 应用的所有基本信息。Olares 应用市场协议和 Olares 系统依赖这些关键信息来正确分发和安装应用。 :::info 提示 -最新的 Olares 系统使用的 Manifest 版本为: `0.11.0` -- 移除 已不支持的sysData 配置项 -- 修改 共享应用的案例 -- 增加 apiVersion 字段说明 -- 增加 共享入口的配置说明 +最新的 Olares 系统使用的 Manifest 版本为: `0.12.0` +- 增加 `apiVersion` 字段(`v1` 为普通应用,`v3` 为共享应用) +- 增加 `spec.accelerator` 字段,用于 GPU 资源声明 +- 增加 `workloadReplicas` 字段,声明所有 workload 的副本数 +- 增加 `overlayGateway` 字段,支持 L2 overlay 局域网发现 +- 增加 `LLMGatewaySupported` 选项,支持 LLM Gateway +- 增加 `appCommon` 和 `externalData` 权限 +- `apiVersion: 'v3'` 的应用将禁止包含 `spec.subCharts` 和 `options.appScope` 字段 +- `apiVersion: 'v2'` 用于 CSV2 应用,将在 1.12.6 发布后逐步停止支持 ::: :::details Changelog +`0.12.0` +- 增加 `apiVersion` 字段:`v1` 为普通应用,`v3` 为共享应用(`v3` 应用安装在 xxx-shared namespace 中) +- 增加 `spec.accelerator` 字段,用于 GPU 资源声明(mode:`nvidia`、`nvidia-gb10`、`apple-m`、`strix-halo`、`mthreads-m1000`、`cpu`) +- 增加 `workloadReplicas` 字段,声明所有 workload 的副本数 +- 增加 `overlayGateway` 字段,支持 L2 overlay 局域网发现 +- 增加 `LLMGatewaySupported` 选项 +- 增加 `appCommon` 和 `externalData` 权限 +- `apiVersion: 'v3'` 的应用将禁止包含 `spec.subCharts` 和 `options.appScope` 字段 +- `apiVersion: 'v2'` 用于 CSV2 应用,将在 1.12.6 发布后逐步停止支持 + +`0.11.0` +- 移除已不支持的 `sysData` 配置项 +- 修改共享应用的案例 +- 增加 `apiVersion` 字段说明 +- 增加共享入口的配置说明 + `0.10.0` - 修改 `categories` 分类 - 增加 Permission 部分中 `provider` 权限的申请 -- 增加 Provider 部分，用于让应用对集群内暴露指定服务接口 +- 增加 Provider 部分,用于让应用对集群内暴露指定服务接口 - 移除 Spec 部分已不支持的一些配置项 - 移除 Option 部分已不支持的一些配置项 -- 增加 `allowMultipleInstall` 配置，允许应用克隆出多个独立的实例 -- 增加 Envs 部分，支持应用声明需要的环境变量 +- 增加 `allowMultipleInstall` 配置,允许应用克隆出多个独立的实例 +- 增加 Envs 部分,支持应用声明需要的环境变量 `0.9.0` - 在 `options` 中增加 `conflict` 字段, 用于声明不兼容的应用 - 移除 `options` 中 `analytics` 配置项 - 修改 `tailscale` 字段的配置格式 -- 增加 `allowedOutboundPorts` 配置，允许通过指定端口进行非 HTTP 协议的对外访问 +- 增加 `allowedOutboundPorts` 配置,允许通过指定端口进行非 HTTP 协议的对外访问 - 修改 `ports` 部分的配置 `0.8.3` - 在 `dependencies` 配置项里增加 `mandatory` 字段以表示该依赖应用必须安装。 -- 增加 `tailscaleAcls` 配置项，允许 Tailscale 为应用开放指定端口 +- 增加 `tailscaleAcls` 配置项,允许 Tailscale 为应用开放指定端口 `0.8.2` -- 添加 `runAsUser` 选项，用于限制应用程序在非root权限的用户下运行 +- 添加 `runAsUser` 选项,用于限制应用程序在非root权限的用户下运行 `0.8.1` - 添加 `ports` 选项以指定 UDP 或 TCP 的暴露端口 @@ -46,7 +66,7 @@ outline: [2, 3] - 将 `spec`>`language` 改为 `spec`>`locale` 并支持 i18n ::: -一个 `OlaresManifest.yaml` 文件的示例如下： +一个 `OlaresManifest.yaml` 文件的示例如下: ::: details `OlaresManifest.yaml` 示例 @@ -110,27 +130,27 @@ options: ## olaresManifest.type -- 类型：`string` -- 有效值： `app`、`recommend`、`middleware` +- 类型:`string` +- 有效值: `app`、`recommend`、`middleware` -Olares 市场目前支持 3 种类型的应用，各自对应不同场景。本文档以 “app” 为例来解释各个字段。其他类型请参考相应的配置指南。 +Olares 市场目前支持 3 种类型的应用,各自对应不同场景。本文档以 "app" 为例来解释各个字段。其他类型请参考相应的配置指南。 - [推荐算法配置指南](recommend.md) :::info 提示 -Olares Market 目前不展示 `recommend` 类型的应用，但你可以上传自定义 Chart 来给 Wise 安装推荐算法 +Olares Market 目前不展示 `recommend` 类型的应用,但你可以上传自定义 Chart 来给 Wise 安装推荐算法 ::: ## olaresManifest.version -- 类型：`string` +- 类型:`string` -随着 Olares 更新，`OlaresManifest.yaml` 的配置规范可能会发生变化。你可以通过检查 `olaresManifest.version` 来确定这些更改是否会影响你的应用程序。 `olaresManifest.version` 由三个用英文句点分隔的整数组成。 +随着 Olares 更新,`OlaresManifest.yaml` 的配置规范可能会发生变化。你可以通过检查 `olaresManifest.version` 来确定这些更改是否会影响你的应用程序。 `olaresManifest.version` 由三个用英文句点分隔的整数组成。 -- 第 1 位数字增加意味着引入了不兼容的配置项，未升级对应 `OlaresManifest.yaml` 的应用将无法分发或安装。 -- 第 2 位数字增加意味着分发和安装必须字段存在变化，但 Olares 系统仍兼容之前所有版本配置的应用分发与安装。我们建议开发者尽快更新升级应用的 `OlaresManifest.yaml` 文件。 -- 第 3 位数字的改变，不影响应用分发和安装。 +- 第 1 位数字增加意味着引入了不兼容的配置项,未升级对应 `OlaresManifest.yaml` 的应用将无法分发或安装。 +- 第 2 位数字增加意味着分发和安装必须字段存在变化,但 Olares 系统仍兼容之前所有版本配置的应用分发与安装。我们建议开发者尽快更新升级应用的 `OlaresManifest.yaml` 文件。 +- 第 3 位数字的改变,不影响应用分发和安装。 -开发者可以使用 1-3 位的版本号来标识该应用遵循的配置版本。以下是有效版本的一些示例： +开发者可以使用 1-3 位的版本号来标识该应用遵循的配置版本。以下是有效版本的一些示例: ```yaml olaresManifest.version: 1 olaresManifest.version: 1.1.0 @@ -139,16 +159,19 @@ olaresManifest.version: "3.0.122" ``` ## apiVersion -- 类型：`string` +- 类型:`string` - 可选 -- 有效值：`v1`,`v2` -- 默认值：`v1` +- 有效值:`v1`、`v3` +- 默认值:`v1` -共享应用需使用 `v2` 版本，支持一个 OAC 中包含多个子图表。其他应用请使用`v1` +共享应用需使用 `v3`,将被安装在 `xxx-shared` namespace 中。其他应用请使用 `v1`。 +:::info 提示 +`apiVersion: 'v2'` 用于 CSV2 应用,将于 Olares OS 1.12.6 发布后逐步停止支持。共享应用请迁移到 `v3`。 +::: ## Metadata -应用的基本信息，用于在 Olares 系统和应用市场中展示应用。 +应用的基本信息,用于在 Olares 系统和应用市场中展示应用。 :::info 示例 ```yaml @@ -166,62 +189,62 @@ metadata: ### name -- 类型：`string` -- 有效值：`^[a-z][a-z0-9]{0,29}$` +- 类型:`string` +- 有效值:`^[a-z][a-z0-9]{0,29}$` -Olares 中的应用的命名空间，仅限小写字母数字字符。最多 30 个字符，需要与 `Chart.yaml` 中的 `FolderName` 和 `name` 字段保持一致。 +Olares 中的应用的命名空间,仅限小写字母数字字符。最多 30 个字符,需要与 `Chart.yaml` 中的 `FolderName` 和 `name` 字段保持一致。 ### title -- 类型：`string` +- 类型:`string` 在应用市场中显示的应用标题。长度不超过 `30` 个字符。 ### description -- 类型：`string` +- 类型:`string` Olares 应用市场中的应用名称下方显示的简短说明。 ### icon -- 类型：`url` +- 类型:`url` 应用图标。 -图标必须是 `PNG` 或 `WEBP` 格式文件，最大为 `512 KB`，尺寸为 `256x256 px`。 +图标必须是 `PNG` 或 `WEBP` 格式文件,最大为 `512 KB`,尺寸为 `256x256 px`。 ### version -- 类型：`string` +- 类型:`string` -应用的 Chart Version，每次改变 Chart 目录里的内容时应递增。需遵循[语义化版本规范](https://semver.org/)，需要与 `Chart.yaml` 中的 `version` 字段一致。 +应用的 Chart Version,每次改变 Chart 目录里的内容时应递增。需遵循[语义化版本规范](https://semver.org/),需要与 `Chart.yaml` 中的 `version` 字段一致。 ### categories -- 类型： `list` +- 类型: `list` 描述在应用市场的哪个类别下展示应用。 -OS 1.11 有效值： +OS 1.11 有效值: - `Blockchain`, `Utilities`, `Social Network`, `Entertainment`, `Productivity` -OS 1.12 有效值： -- `Creativity`：设计创作 -- `Productivity_v112`：工作效率 -- `Developer Tools`：开发工具 -- `Fun`：休闲娱乐 -- `Lifestyle`：生活方式 -- `Utilities_v112`：实用工具 -- `AI`：AI +OS 1.12 有效值: +- `Creativity`:设计创作 +- `Productivity_v112`:工作效率 +- `Developer Tools`:开发工具 +- `Fun`:休闲娱乐 +- `Lifestyle`:生活方式 +- `Utilities_v112`:实用工具 +- `AI`:AI :::info 提示 -Olares OS 1.12.0 版本对应用商店的应用分类进行了调整，因此如果应用需要同时兼容 1.11 和 1.12 版本，请同时填写两个版本所需的分类。 +Olares OS 1.12.0 版本对应用商店的应用分类进行了调整,因此如果应用需要同时兼容 1.11 和 1.12 版本,请同时填写两个版本所需的分类。 ::: ## Entrances -指定此应用访问入口的数量。每个应用允许最少 1 个，最多 10 个入口 。 +指定此应用访问入口的数量。每个应用允许最少 1 个,最多 10 个入口 。 :::info 示例 ```yaml @@ -241,75 +264,75 @@ entrances: ### name -- 类型：`string` +- 类型:`string` - Accepted Value: `[a-z]([-a-z0-9]*[a-z0-9])?` - 入口的名称，长度不超过 `63` 个字符。一个应用内不能重复。 + 入口的名称,长度不超过 `63` 个字符。一个应用内不能重复。 ### port -- 类型： `int` -- 有效值： `0-65535` +- 类型: `int` +- 有效值: `0-65535` ### host -- 类型：`string` -- 有效值： `[a-z]([-a-z0-9]*[a-z0-9])?` +- 类型:`string` +- 有效值: `[a-z]([-a-z0-9]*[a-z0-9])?` - 当前入口的 Ingress 名称，只包含小写字母和数字和中划线`-`，长度不超过 63 个字符。 + 当前入口的 Ingress 名称,只包含小写字母和数字和中划线`-`,长度不超过 63 个字符。 ### title -- 类型：`string` +- 类型:`string` 安装后 Olares 桌面的显示名称。长度不超过 `30` 个字符。 ### icon -- 类型： `url` +- 类型: `url` - 可选 -应用安装后 Olares 桌面上的图标。图片文件必须是 `PNG` 或 `WEBP` 格式，不超过 `512 KB`，尺寸为 `256x256 px`。 +应用安装后 Olares 桌面上的图标。图片文件必须是 `PNG` 或 `WEBP` 格式,不超过 `512 KB`,尺寸为 `256x256 px`。 ### authLevel -- 类型：`string` -- 有效值： `public`, `private`, `internal` -- 默认值： `private` +- 类型:`string` +- 有效值: `public`, `private`, `internal` +- 默认值: `private` - 可选 指定入口的认证级别。 -- **Public**：互联网上的任何人都可以不受限制地访问。 -- **Private**：需要从内部和外部网络访问的授权。 -- **Internal**：需要授权才能从外部网络访问。从内部网络（通过 LAN/专用网络）访问时不需要身份验证。 +- **Public**:互联网上的任何人都可以不受限制地访问。 +- **Private**:需要从内部和外部网络访问的授权。 +- **Internal**:需要授权才能从外部网络访问。从内部网络(通过 LAN/专用网络)访问时不需要身份验证。 ### invisible -- 类型： `boolean` -- 默认值：`false` +- 类型: `boolean` +- 默认值:`false` - 可选 -当 `invisible` 为` true` 时，该入口不会显示在 Olares 桌面上。 +当 `invisible` 为` true` 时,该入口不会显示在 Olares 桌面上。 ### openMethod -- 类型：`string` -- 有效值： `default`, `iframe`, `window` -- 默认值： `default` +- 类型:`string` +- 有效值: `default`, `iframe`, `window` +- 默认值: `default` - 可选 指定该入口在桌面的打开方式。 -`iframe` 代表在桌面的窗口内通过 iframe 新建一个窗口，`window` 代表在浏览器新的 Tab 页打开。`default` 代表跟随系统的默认选择，系统默认的选择是`iframe`。 +`iframe` 代表在桌面的窗口内通过 iframe 新建一个窗口,`window` 代表在浏览器新的 Tab 页打开。`default` 代表跟随系统的默认选择,系统默认的选择是`iframe`。 ### windowPushState -- 类型： `boolean` -- 默认值：`false` +- 类型: `boolean` +- 默认值:`false` - 可选 -将应用嵌入到桌面上的 iframe 中时，应用的 URL 可能会动态更改。由于浏览器的同源策略，桌面（父窗口）无法直接检测到 iframe URL 中的这些变化。因此，如果你重新打开应用程序选项卡，它将显示初始 URL，而不是更新后的 URL。 +将应用嵌入到桌面上的 iframe 中时,应用的 URL 可能会动态更改。由于浏览器的同源策略,桌面(父窗口)无法直接检测到 iframe URL 中的这些变化。因此,如果你重新打开应用程序选项卡,它将显示初始 URL,而不是更新后的 URL。 -为了确保无缝的用户体验，你可以通过将其设置为 true 来启用此选项。此操作会提示网关自动将以下代码注入到 iframe 中。每当 iframe 的 URL 发生更改时，此代码都会向父窗口（桌面）发送一个事件。因此，桌面可以跟踪 URL 更改并打开正确的页面。 +为了确保无缝的用户体验,你可以通过将其设置为 true 来启用此选项。此操作会提示网关自动将以下代码注入到 iframe 中。每当 iframe 的 URL 发生更改时,此代码都会向父窗口(桌面)发送一个事件。因此,桌面可以跟踪 URL 更改并打开正确的页面。 ::: details 代码 ```Javascript @@ -337,7 +360,7 @@ entrances: ## sharedEntrances -共享入口是共享应用为集群内其他应用调用提供的接口地址。共享入口的字段配置和常规入口基本一致，一个典型的共享入口配置如下 +共享入口是共享应用为集群内其他应用调用提供的接口地址。共享入口的字段配置和常规入口基本一致,一个典型的共享入口配置如下 :::info 示例 ```yaml @@ -362,38 +385,38 @@ ports: - name: rdp-tcp # 提供服务的入口名称 host: windows-svc # 提供服务的 Ingress 主机名称 port: 3389 # 提供服务的端口号 - protocol: udp # 暴露端口使用的协议 - exposePort: 46879 # 暴露的端口，在集群内一次只能分配给一个应用程序 + protocol: udp # 暴露端口使用的协议 + exposePort: 46879 # 暴露的端口,在集群内一次只能分配给一个应用程序 addToTailscaleAcl: true # 自动添加到 Tailscale 的 ACL 列表中 ``` ::: ### exposePort -- 类型： `int` +- 类型: `int` - 可选 -- 有效值： `0-65535`，保留端口 `22`, `80`, `81`, `443`, `444`, `2379`, `18088` 除外 -Olares 会为你的应用暴露指定的端口，这些端口可通过应用域名在本地网络下访问，如`84864c1f.your_olares_id.olares.com:46879`。对于每个公开的端口，Olares 会自动配置相同端口号的 TCP 和 UDP。 +- 有效值: `0-65535`,保留端口 `22`, `80`, `81`, `443`, `444`, `2379`, `18088` 除外 +Olares 会为你的应用暴露指定的端口,这些端口可通过应用域名在本地网络下访问,如`84864c1f.your_olares_id.olares.com:46879`。对于每个公开的端口,Olares 会自动配置相同端口号的 TCP 和 UDP。 :::info 提示 暴露的端口只能通过本地网络或 Olares 专用网络访问。 ::: ### protocol -- 类型： `string` +- 类型: `string` - 可选 -- 有效值： `udp`、`tcp` +- 有效值: `udp`、`tcp` -暴露端口使用的协议 ，如果不填默认同时开通udp和tcp。 +暴露端口使用的协议 ,如果不填默认同时开通udp和tcp。 ### addToTailscaleAcl -- 类型： `boolean` +- 类型: `boolean` - 可选 -- 默认值：`false` +- 默认值:`false` -当将 addToTailscaleAcl 字段设置为 true 时，系统会为该端口分配一个随机端口，并自动将其加入到 Tailscale 的 ACL 中。 +当将 addToTailscaleAcl 字段设置为 true 时,系统会为该端口分配一个随机端口,并自动将其加入到 Tailscale 的 ACL 中。 ## Tailscale -- 类型：`map` +- 类型:`map` - 可选 允许应用在 Tailscale 的ACL(Access Control Lists)中开放指定端口。 @@ -405,9 +428,9 @@ tailscale: - proto: tcp dst: - "*:46879" - - proto: "" # 可选, 如果未指定，则允许使用所有支持的协议 + - proto: "" # 可选, 如果未指定,则允许使用所有支持的协议 dst: - - "*:4557" + - "*:4557" ``` ::: @@ -425,42 +448,56 @@ permission: ### appCache -- 类型： `boolean` +- 类型: `boolean` - 可选 是否需要在 `Cache` 目录创建应用的目录。如需要在部署 yaml 文件中使用`.Values.userspace.appCache`, `appCache` 必须设为 `true`。 ### appData -- 类型： `boolean` +- 类型: `boolean` - 可选 是否需要在 `Data` 目录创建应用的目录。如需要在部署 yaml 中使用`.Values.userspace.appData`, `appData` 必须设为 `true`。 +### appCommon + +- 类型: `boolean` +- 可选 + +是否需要对 `App Common` 目录(跨节点跨应用共享模型)进行读写权限。在部署 yaml 文件中使用 `{{ .Values.userspace.appCommon }}` 获取 App Common 目录地址。 + +### externalData + +- 类型: `boolean` +- 可选 + +是否需要对 `External` 目录(挂载 NAS 或其他外部磁盘数据)进行读写权限。不影响已部署的 0.11.0 版本的应用的访问权限。 + ### userData -- 类型：`string` +- 类型:`string` - 可选 应用是否需要对用户的 `Home` 文件夹进行读写权限。列出应用需要访问的用户 `Home` 下的所有目录。部署 YAML 中配置的所有 `userData` 目录都必须包含在此处。 ### provider -- 类型：`list` +- 类型:`list` - 可选 -用于声明本应用需访问的其他应用接口。被访问的应用需在其 `provider` 部分声明对外开放的 `providerName`，详见下方 Provider 章节。 +用于声明本应用需访问的其他应用接口。被访问的应用需在其 `provider` 部分声明对外开放的 `providerName`,详见下方 Provider 章节。 配置访问的方式如下 1. 在 `appName` 字段填写目标应用的 `name` 字段。 2. 在`providerName` 字段填写目标应用 `provider` 配置中的 `name` 字段。 -你可以使用 `podSelectors` 字段来指定本应用中哪些 pod 需要访问目标应用。如果未声明此字段，则默认为本应用的所有 pod 注入 `outbound envoy sidecar`。 +你可以使用 `podSelectors` 字段来指定本应用中哪些 pod 需要访问目标应用。如果未声明此字段,则默认为本应用的所有 pod 注入 `outbound envoy sidecar`。 :::info 调用应用示例 ```yaml -# 需要调用其他应用的应用，如 sonarr -permission: +# 需要调用其他应用的应用,如 sonarr +permission: provider: - appName: bazarr providerName: bazarr-svc @@ -471,7 +508,7 @@ permission: ::: :::info 被调用应用示例 ```yaml -# 被调用方应用，如 bazarr +# 被调用方应用,如 bazarr provider: - name: bazarr-svc entrance: bazarr-svc @@ -482,16 +519,16 @@ provider: ## Spec -记录额外的应用信息，主要用于应用商店的展示。 +记录额外的应用信息,主要用于应用商店的展示。 :::info 示例 ```yaml spec: - versionName: '10.8.11' - # 此 Chart 包含的应用程序的版本。建议将版本号括在引号中。该值对应于 Chart.yaml 文件中的 appVersion 字段。请注意，它与 version 字段无关。 + versionName: '10.8.11' + # 此 Chart 包含的应用程序的版本。建议将版本号括在引号中。该值对应于 Chart.yaml 文件中的 appVersion 字段。请注意,它与 version 字段无关。 featuredImage: https://app.cdn.olares.com/appstore/jellyfin/promote_image_1.jpg - # 当应用在应用市场上推荐时，会显示特色图像。 + # 当应用在应用市场上推荐时,会显示特色图像。 promoteImage: - https://app.cdn.olares.com/appstore/jellyfin/promote_image_1.jpg @@ -514,12 +551,12 @@ spec: requiredMemory: 256Mi requiredDisk: 128Mi requiredCpu: 0.5 - # 指定安装和运行应用所需的最少资源。安装应用后，系统将保留这些资源以确保最佳性能。 + # 指定安装和运行应用所需的最少资源。安装应用后,系统将保留这些资源以确保最佳性能。 limitedDisk: 256Mi limitedCpu: 1 limitedMemory: 512Mi - # 指定应用的最大资源限制。如果应用超出这些限制，它将暂时暂停，以防止系统过载并确保稳定性。 + # 指定应用的最大资源限制。如果应用超出这些限制,它将暂时暂停,以防止系统过载并确保稳定性。 legal: - text: Community Standards @@ -537,11 +574,11 @@ spec: ### i18n -要在 Olares 应用市场中为应用添加多语言支持： +要在 Olares 应用市场中为应用添加多语言支持: 1. 在 Olares Application Chart 根目录中创建一个 `i18n` 文件夹。 -2. 在 `i18n` 文件夹中，为每个支持的语言环境创建单独的子目录。 -3. 在每个语言环境子目录中，放置 `OlaresManifest.yaml` 文件的本地化版本。 +2. 在 `i18n` 文件夹中,为每个支持的语言环境创建单独的子目录。 +3. 在每个语言环境子目录中,放置 `OlaresManifest.yaml` 文件的本地化版本。 Olares 应用市场将根据用户的区域设置自动显示相应的 `OlaresManifest.yaml` 文件的内容。 :::info 示例 @@ -561,7 +598,7 @@ Olares 应用市场将根据用户的区域设置自动显示相应的 `OlaresMa └── values.yaml ``` ::: -目前，你可以为以下字段添加 i18n 内容： +目前,你可以为以下字段添加 i18n 内容: ```yaml metadata: description: @@ -596,24 +633,64 @@ Olares 目前不支持混合架构的集群。 - 默认值: `false` - 可选 -设置为 `true` 时，只有管理员可以安装此应用程序。 +设置为 `true` 时,只有管理员可以安装此应用程序。 ### runAsUser - 类型: `boolean` - 可选 -当设置为 `true` 时，Olares 会强制以用户 ID “1000”（非 root 用户）运行应用程序。 +当设置为 `true` 时，Olares 会强制以用户 ID "1000"（非 root 用户）运行应用程序。 + +### accelerator +- 类型: `map` +- 可选 + +声明应用所需的 GPU 资源。需要 GPU 的应用，使用 `spec.accelerator` 字段声明资源，不能包含原来的 `spec.requiredMemory` 等字段。 + +:::info 示例 +```yaml +spec: + accelerator: + mode: nvidia # 支持的 mode：nvidia、nvidia-gb10、apple-m、strix-halo、mthreads-m1000、cpu + limitedCpu: 7000m + requiredCpu: 150m + requiredDisk: 50Mi + limitedDisk: 500Gi + limitedMemory: 40Gi + requiredMemory: 5Gi + requiredGPUMemory: 1Gi + limitedGPUMemory: 24Gi +``` +::: + +### workloadReplicas +- 类型: `map` +- 可选 + +声明 chart 中所有 workload 的副本数。从 0.12.0 开始，应用需要在 OlaresManifest 里添加变量，声明 chart 中所有 workload 的副本数量。 +:::info 示例 +```yaml +workloadReplicas: + affine: 1 +``` +::: +对应的 `values.yaml` 中也必须填入这个值（用于旧版本兼容）： +```yaml +workloads: + affine: + replicaCount: 1 +``` ## Middleware -- 类型：`map` +- 类型:`map` - 可选 -系统提供了高可用的中间件服务，开发者无需重复安装中间件，只需在此填写对应的中间件信息即可，然后可以直接使用应用程序的 deployment YAML 文件中相应的中间件信息。 +系统提供了高可用的中间件服务,开发者无需重复安装中间件,只需在此填写对应的中间件信息即可,然后可以直接使用应用程序的 deployment YAML 文件中相应的中间件信息。 -使用 `scripts` 字段指定创建数据库后应执行的脚本。此外，使用 `extension` 字段在数据库中添加相应的扩展名。 +使用 `scripts` 字段指定创建数据库后应执行的脚本。此外,使用 `extension` 字段在数据库中添加相应的扩展名。 :::info 提示 -MongoDB，MySQL，MariaDB，MinIO，RabbitMQ 需要管理员从 Market 安装后才能被其他应用使用 +MongoDB,MySQL,MariaDB,MinIO,RabbitMQ 需要管理员从 Market 安装后才能被其他应用使用 ::: ### PostgreSQL @@ -628,18 +705,18 @@ middleware: - vectors - earthdistance scripts: - - BEGIN; + - BEGIN; - ALTER DATABASE $databasename SET search_path TO "$user", public, vectors; - ALTER SCHEMA vectors OWNER TO $dbusername; - COMMIT; - # 操作系统提供了两个变量 $databasename 和 $dbusername，命令执行时会被 Olares 应用运行时替换。 + # 操作系统提供了两个变量 $databasename 和 $dbusername,命令执行时会被 Olares 应用运行时替换。 ``` ::: -使用 deployment YAML 中的中间件信息： +使用 deployment YAML 中的中间件信息: ```yaml -# 对于 PostgreSQL，对应值如下 +# 对于 PostgreSQL,对应值如下 - env: - - name: DB_POSTGRESDB_DATABASE # 你在 OlaresManifest 中配置的数据库名称，在 middleware.postgres.databases[i].name 中指定 + - name: DB_POSTGRESDB_DATABASE # 你在 OlaresManifest 中配置的数据库名称,在 middleware.postgres.databases[i].name 中指定 value: {{ .Values.postgres.databases. }} - name: DB_POSTGRESDB_HOST value: {{ .Values.postgres.host }} @@ -660,9 +737,9 @@ middleware: namespace: db0 ``` ::: -使用 deployment YAML 中的中间件信息： +使用 deployment YAML 中的中间件信息: ```yaml -# 对于 Redis，对应的值如下 +# 对于 Redis,对应的值如下 host --> {{ .Values.redis.host }}For Redis, the corresponding value is as follow port --> "{{ .Values.redis.port }}" password --> "{{ .Values.redis.password }}" @@ -670,7 +747,7 @@ password --> "{{ .Values.redis.password }}" ### MongoDB :::info 示例 ```yaml -middleware: +middleware: mongodb: username: chromium databases: @@ -680,28 +757,28 @@ middleware: # 请确保每一行都是完整的查询。 ``` ::: -使用 deployment YAML 中的中间件信息： +使用 deployment YAML 中的中间件信息: ```yaml -# 对于 MongoDB，对应的值如下 +# 对于 MongoDB,对应的值如下 host --> {{ .Values.mongodb.host }} port --> "{{ .Values.mongodb.port }}" # yaml 文件中的端口和密码需要用双引号括起来。 username --> {{ .Values.mongodb.username }} password --> "{{ .Values.mongodb.password }}" # yaml 文件中的端口和密码需要用双引号括起来。 -databases --> "{{ .Values.mongodb.databases }}" # 数据库的值类型是 map。你可以使用 {{ .Values.mongodb.databases. }} 获取数据库。 是你在 OlaresManifest 中配置的名称，在 middleware.mongodb.databases[i].name 中指定 +databases --> "{{ .Values.mongodb.databases }}" # 数据库的值类型是 map。你可以使用 {{ .Values.mongodb.databases. }} 获取数据库。 是你在 OlaresManifest 中配置的名称,在 middleware.mongodb.databases[i].name 中指定 ``` ### MinIO :::info 示例 ```yaml -middleware: +middleware: minio: username: miniouser buckets: - name: mybucket ``` ::: -使用 deployment YAML 中的中间件信息： +使用 deployment YAML 中的中间件信息: ```yaml -# 对于 MinIO，对应的值如下 +# 对于 MinIO,对应的值如下 - env: - name: MINIO_ENDPOINT value: '{{ .Values.minio.host }}:{{ .Values.minio.port }}' @@ -717,16 +794,16 @@ middleware: ### RabbitMQ :::info 示例 ```yaml -middleware: +middleware: rabbitmq: username: rabbitmquser vhosts: - name: aaa ``` ::: -使用 deployment YAML 中的中间件信息： +使用 deployment YAML 中的中间件信息: ```yaml -# 对于 RabbitMQ，对应的值如下 +# 对于 RabbitMQ,对应的值如下 - env: - name: RABBITMQ_HOST value: '{{ .Values.rabbitmq.host }}' @@ -737,7 +814,7 @@ middleware: - name: RABBITMQ_PASSWORD value: "{{ .Values.rabbitmq.password }}" - name: RABBITMQ_VHOST - value: "{{ .Values.rabbitmq.vhosts.aaa }}" + value: "{{ .Values.rabbitmq.vhosts.aaa }}" user := os.Getenv("RABBITMQ_USER") password := os.Getenv("RABBITMQ_PASSWORD") @@ -749,16 +826,16 @@ url := fmt.Sprintf("amqp://%s:%s@%s:%s/%s", user, password, host, portMQ, vhost) ### MariaDB :::info 示例 ```yaml -middleware: +middleware: mariadb: username: mariadbclient databases: - name: aaa ``` ::: -使用 deployment YAML 中的中间件信息： +使用 deployment YAML 中的中间件信息: ```yaml -# 对于 MariaDB，对应的值如下 +# 对于 MariaDB,对应的值如下 - env: - name: MDB_HOST value: '{{ .Values.mariadb.host }}' @@ -774,17 +851,17 @@ middleware: ### MySQL :::info 示例 ```yaml -middleware: +middleware: mysql: username: mysqlclient databases: - - name: aaa + - name: aaa ``` ::: -使用 deployment YAML 中的中间件信息： +使用 deployment YAML 中的中间件信息: ```yaml -# 对于 MySQL，对应的值如下 +# 对于 MySQL,对应的值如下 - env: - name: MDB_HOST value: '{{ .Values.mysql.host }}' @@ -795,7 +872,7 @@ middleware: - name: MDB_PASSWORD value: "{{ .Values.mysql.password }}" - name: MDB_DB - value: "{{ .Values.mysql.databases.aaa }}" + value: "{{ .Values.mysql.databases.aaa }}" ``` ## Options @@ -803,7 +880,7 @@ middleware: 此部分用于配置与Olares系统相关的选项。 ### policies -- 类型：`list` +- 类型:`list` - 可选 定义应用子域的详细访问控制。 @@ -821,10 +898,10 @@ options: ::: ### appScope -- 类型：`map` +- 类型:`map` - 可选 -是否为 Olares 集群中的所有用户安装此应用程序。对用共享应用，需要设置 `clusterScoped` 为 `true`, 同时在 `appRef` 字段填入应用名称 +是否为 Olares 集群中的所有用户安装此应用程序。对用共享应用,需要设置 `clusterScoped` 为 `true`, 同时在 `appRef` 字段填入应用名称 :::info 应用ollamav2示例 @@ -845,22 +922,22 @@ options: version: '>=1.12.3-0' type: system {{- if and .Values.admin .Values.bfl.username (eq .Values.admin .Values.bfl.username) }} - {{- else }} + {{- else }} - name: ollamav2 type: application version: '>=1.0.1' - mandatory: true # 其他用户安装客户端，依赖管理员安装的共享服务 + mandatory: true # 其他用户安装客户端,依赖管理员安装的共享服务 {{- end }} ``` ::: ### dependencies -- 类型：`list` +- 类型:`list` -如果此应用依赖于其他应用或需要特定操作系统版本，请在此处声明。 +如果此应用依赖于其他应用或需要特定操作系统版本,请在此处声明。 -如果此应用程序需要依赖其他应用程序才能正确安装，则应将 `mandatory` 字段设置为 `true`。 +如果此应用程序需要依赖其他应用程序才能正确安装,则应将 `mandatory` 字段设置为 `true`。 :::info 示例 ```yaml @@ -872,12 +949,12 @@ options: - name: mongodb version: ">=6.0.0-0" type: middleware - mandatory: true # 如果必须先安装此依赖，请将此字段设为 true。 + mandatory: true # 如果必须先安装此依赖,请将此字段设为 true。 ``` ::: ### conflicts -- 类型：`list` +- 类型:`list` - 可选 请在此处声明与该应用冲突的其他应用。必须卸载冲突应用后才能安装此应用。 @@ -889,17 +966,17 @@ options: - name: comfyui type: application - name: comfyuiclient - type: application + type: application ``` ::: ### mobileSupported -- 类型： `boolean` -- 默认值： `false` +- 类型: `boolean` +- 默认值: `false` - 可选 -确定应用是否与移动网络浏览器兼容并且可以在移动版本的 Olares 桌面上显示。如果应用程序针对移动网络浏览器进行了优化，请启用此选项。这将使该应用程序在移动版 Olares 桌面上可见并可访问。 +确定应用是否与移动网络浏览器兼容并且可以在移动版本的 Olares 桌面上显示。如果应用程序针对移动网络浏览器进行了优化,请启用此选项。这将使该应用程序在移动版 Olares 桌面上可见并可访问。 :::info 示例 ```yaml @@ -908,10 +985,10 @@ mobileSupported: true ::: ### oidc -- 类型：`map` +- 类型:`map` - 可选 -Olares 包含内置的 OpenID Connect 身份验证组件，以简化用户的身份验证。启用此选项可在你的应用中使用 OpenID。 +Olares 包含内置的 OpenID Connect 身份验证组件,以简化用户的身份验证。启用此选项可在你的应用中使用 OpenID。 ```yaml # yaml 中 OpenID 相关变量 {{ .Values.oidc.client.id }} @@ -929,10 +1006,10 @@ oidc: ::: ### apiTimeout -- 类型：`int` +- 类型:`int` - 可选 -指定 API 提供程序的超时限制（以秒为单位）。默认值为 `15`。使用 `0` 允许无限制的 API 连接。 +指定 API 提供程序的超时限制(以秒为单位)。默认值为 `15`。使用 `0` 允许无限制的 API 连接。 :::info 示例 ```yaml @@ -941,10 +1018,10 @@ apiTimeout: 0 ::: ### allowedOutboundPorts -- 类型： `list` +- 类型: `list` - 可选 -要求开通以下端口进行非 HTTP 协议的对外访问，例如 SMTP 服务等。 +要求开通以下端口进行非 HTTP 协议的对外访问,例如 SMTP 服务等。 :::info 示例 ```yaml @@ -952,40 +1029,66 @@ allowedOutboundPorts: - 465 - 587 ``` -::: +::: ### allowMultipleInstall -- 类型： `boolean` -- 默认值： `false` +- 类型: `boolean` +- 默认值: `false` - 可选 该应用支持在同一 Olares 集群中部署多个独立实例。此设置对付费应用和共享应用客户端无效。 +### LLMGatewaySupported +- 类型: `boolean` +- 默认值: `false` +- 可选 + +设置为 `true` 时，表示应用支持 LLM Gateway 调用。 + + +### overlayGateway +- 类型: `map` +- 可选 + +声明应用支持 L2 overlay 局域网发现。开启后，其他应用可通过 IP 地址在局域网内访问该应用。 +:::info 示例 +```yaml +overlayGateway: + enable: true # 开启 L2 overlay 局域网发现，默认为 false + entrances: + - port: 8096 # Overlay 监听端口号 + title: Jellyfin # Overlay 入口名称 + workload: jellyfin # Workload 的名字，oac 需要校验 + description: "Access Jellyfin using IP address in LAN" + protocol: tcp # 支持的协议：tcp/udp，不填默认 tcp/udp 都支持 +``` +::: + ## Envs -在此声明应用运行所需的环境变量，既支持用户手动输入，也可以直接引用已有的系统环境变量值。 +在此声明应用运行所需的环境变量,既支持用户手动输入,也可以直接引用已有的系统环境变量值。 :::info 提示 该配置需要 Olares OS 版本在 1.12.2 及以上才生效 -::: +::: :::info 示例 ```yaml envs: - envName: ENV_NAME - # 在部署应用时，该键会被注入为.Values.olaresEnv.ENV_NAME + # 在部署应用时,该键会被注入为.Values.olaresEnv.ENV_NAME required: true # 是否为必填项 - # 若为true且未设置default，则用户安装应用时必须填写此值，且修改value时不允许清空 + # 若为true且未设置default,则用户安装应用时必须填写此值,且修改value时不允许清空 default: "DEFAULT" - # 环境变量的默认值，开发者可在编写时提供，用户不可修改。 + # 环境变量的默认值,开发者可在编写时提供,用户不可修改。 type: string - # 环境变量的类型，目前有int/bool/url/ip/domain/email/string/password。如果声明，会对value进行类型校验 + # 环境变量的类型,目前有int/bool/url/ip/domain/email/string/password。如果声明,会对value进行类型校验 - editable: true + editable: true # 是否可在应用部署后编辑 options: @@ -993,30 +1096,30 @@ envs: value: "11" - title: Windows10 value: "10" - # 允许值列表，此环境变量的值只允许从该列表中选择 - # title为展示给用户的名称，value为实际注入系统的值 + # 允许值列表,此环境变量的值只允许从该列表中选择 + # title为展示给用户的名称,value为实际注入系统的值 remoteOptions: https://xxx.xxx/xx - # 提供允许值列表的一个url，response body需为JSON编码的options列表 + # 提供允许值列表的一个url,response body需为JSON编码的options列表 regex: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$' # 该环境变量的值必须匹配此正则表达式 valueFrom: envName: OLARES_SYSTEM_CLUSTER_DNS_SERVICE - # 引用系统环境变量的值。如果采用该方式，将不允许用户手动指定/修改其value - # 引用后，此环境变量的可声明字段(type,editable)将被系统环境变量的对应属性覆盖，default/value字段也会失效 - + # 引用系统环境变量的值。如果采用该方式,将不允许用户手动指定/修改其value + # 引用后,此环境变量的可声明字段(type,editable)将被系统环境变量的对应属性覆盖,default/value字段也会失效 + applyOnChange: true - # 是否在此环境变量的值变化时自动重新部署应用，使变化生效 - # 若该字段为false，在环境变量变化时，即使停止/启动应用，也不会生效，只有升级/重装会生效 - + # 是否在此环境变量的值变化时自动重新部署应用,使变化生效 + # 若该字段为false,在环境变量变化时,即使停止/启动应用,也不会生效,只有升级/重装会生效 + description: "DESCRIPTION" # 对环境变量的描述 ``` ::: -如需在部署 YAML 文件中使用环境变量的值，只需在相应位置使用 `.Values.olaresEnv.ENV_NAME` 即可。系统会在应用部署时自动将对应的 olaresEnv 变量注入到 values 中。例如 +如需在部署 YAML 文件中使用环境变量的值,只需在相应位置使用 `.Values.olaresEnv.ENV_NAME` 即可。系统会在应用部署时自动将对应的 olaresEnv 变量注入到 values 中。例如 :::info 示例 ```yaml @@ -1031,15 +1134,15 @@ BACKEND_MAIL_SENDER: "{{ .Values.olaresEnv.MAIL_SENDER }}" ## Provider -在此声明本应用向其他应用开放的接口。系统会自动为这些接口生成 Service，让集群内其他应用能够通过内部网络访问。如果其他应用要调用这些接口，需要在 permission 部分申请访问该 provider 的权限。 +在此声明本应用向其他应用开放的接口。系统会自动为这些接口生成 Service,让集群内其他应用能够通过内部网络访问。如果其他应用要调用这些接口,需要在 permission 部分申请访问该 provider 的权限。 :::info 示例 ```yaml provider: - name: bazarr entrance: bazarr-svc # 该服务的入口名称 - paths: ["/api*"] # 开放的接口路径，不能只包含通配符 * - verbs: ["*"] # 支持post,get,put,delete,patch；"*"表示允许所有方法 + paths: ["/api*"] # 开放的接口路径,不能只包含通配符 * + verbs: ["*"] # 支持post,get,put,delete,patch;"*"表示允许所有方法 ``` ::: From 64df5174f07fd3396bf3972051110c07748406e3 Mon Sep 17 00:00:00 2001 From: RiddleMe <142984611+TShentu@users.noreply.github.com> Date: Wed, 3 Jun 2026 14:21:28 +0800 Subject: [PATCH 2/9] fix comma --- docs/developer/develop/package/manifest.md | 15 +- docs/zh/developer/develop/package/manifest.md | 199 +++++++++--------- 2 files changed, 96 insertions(+), 118 deletions(-) diff --git a/docs/developer/develop/package/manifest.md b/docs/developer/develop/package/manifest.md index cd7fc88082..a3b30203ec 100644 --- a/docs/developer/develop/package/manifest.md +++ b/docs/developer/develop/package/manifest.md @@ -8,27 +8,16 @@ Every **Olares Application Chart** should include an `OlaresManifest.yaml` file :::info NOTE Latest Olares Manifest version: `0.12.0` -- Added `apiVersion` field (`v1` for regular apps, `v3` for shared apps) +- Modified the `apiVersion` field: added support for `v3` shared applications; the previous `v2` version of shared applications will be deprecated. - Added `spec.accelerator` field for GPU resource declaration - Added `workloadReplicas` field to declare all workload replica counts - Added `overlayGateway` field for L2 overlay LAN discovery support - Added `LLMGatewaySupported` in options for LLM Gateway support - Added `appCommon` and `externalData` permissions -- Marked `spec.subCharts` and `options.appScope` as deprecated for `apiVersion: 'v3'` -- `apiVersion: 'v2'` for CSV2 apps is deprecated and will be removed after 1.12.6 +- Added `templateOnly` field to mark template-type applications ::: :::details Changelog -`0.12.0` -- Added `apiVersion` field: `v1` for regular apps, `v3` for shared apps (`v3` apps installed in xxx-shared namespace) -- Added `spec.accelerator` field for GPU resource declaration (modes: `nvidia`, `nvidia-gb10`, `apple-m`, `strix-halo`, `mthreads-m1000`, `cpu`) -- Added `workloadReplicas` field to declare all workload replica counts -- Added `overlayGateway` field for L2 overlay LAN discovery support -- Added `LLMGatewaySupported` in options -- Added `appCommon` and `externalData` permissions -- Marked `spec.subCharts` and `options.appScope` as deprecated for `apiVersion: 'v3'` -- `apiVersion: 'v2'` for CSV2 apps is deprecated, will be removed after 1.12.6 - `0.11.0` - Removed deprecated `sysData` field - Updated shared app example diff --git a/docs/zh/developer/develop/package/manifest.md b/docs/zh/developer/develop/package/manifest.md index 73d7232bcd..5b4a9ece66 100644 --- a/docs/zh/developer/develop/package/manifest.md +++ b/docs/zh/developer/develop/package/manifest.md @@ -1,5 +1,5 @@ --- -outline: [2, 3] +outline: [2， 3] --- # OlaresManifest 规范 @@ -8,27 +8,16 @@ outline: [2, 3] :::info 提示 最新的 Olares 系统使用的 Manifest 版本为: `0.12.0` -- 增加 `apiVersion` 字段(`v1` 为普通应用,`v3` 为共享应用) -- 增加 `spec.accelerator` 字段,用于 GPU 资源声明 -- 增加 `workloadReplicas` 字段,声明所有 workload 的副本数 -- 增加 `overlayGateway` 字段,支持 L2 overlay 局域网发现 -- 增加 `LLMGatewaySupported` 选项,支持 LLM Gateway +- 修改 `apiVersion` 字段，增加`v3`共享应用，原`v2`版共享应用将作废 +- 增加 `spec.accelerator` 字段，用于 GPU 资源声明 +- 增加 `workloadReplicas` 字段，声明所有 workload 的副本数 +- 增加 `overlayGateway` 字段，支持 L2 overlay 局域网发现 +- 增加 `LLMGatewaySupported` 选项，支持 LLM Gateway - 增加 `appCommon` 和 `externalData` 权限 -- `apiVersion: 'v3'` 的应用将禁止包含 `spec.subCharts` 和 `options.appScope` 字段 -- `apiVersion: 'v2'` 用于 CSV2 应用,将在 1.12.6 发布后逐步停止支持 +- 增加 `templateOnly`字段，用于标记模版类应用 ::: :::details Changelog -`0.12.0` -- 增加 `apiVersion` 字段:`v1` 为普通应用,`v3` 为共享应用(`v3` 应用安装在 xxx-shared namespace 中) -- 增加 `spec.accelerator` 字段,用于 GPU 资源声明(mode:`nvidia`、`nvidia-gb10`、`apple-m`、`strix-halo`、`mthreads-m1000`、`cpu`) -- 增加 `workloadReplicas` 字段,声明所有 workload 的副本数 -- 增加 `overlayGateway` 字段,支持 L2 overlay 局域网发现 -- 增加 `LLMGatewaySupported` 选项 -- 增加 `appCommon` 和 `externalData` 权限 -- `apiVersion: 'v3'` 的应用将禁止包含 `spec.subCharts` 和 `options.appScope` 字段 -- `apiVersion: 'v2'` 用于 CSV2 应用,将在 1.12.6 发布后逐步停止支持 - `0.11.0` - 移除已不支持的 `sysData` 配置项 - 修改共享应用的案例 @@ -38,25 +27,25 @@ outline: [2, 3] `0.10.0` - 修改 `categories` 分类 - 增加 Permission 部分中 `provider` 权限的申请 -- 增加 Provider 部分,用于让应用对集群内暴露指定服务接口 +- 增加 Provider 部分，用于让应用对集群内暴露指定服务接口 - 移除 Spec 部分已不支持的一些配置项 - 移除 Option 部分已不支持的一些配置项 -- 增加 `allowMultipleInstall` 配置,允许应用克隆出多个独立的实例 -- 增加 Envs 部分,支持应用声明需要的环境变量 +- 增加 `allowMultipleInstall` 配置，允许应用克隆出多个独立的实例 +- 增加 Envs 部分，支持应用声明需要的环境变量 `0.9.0` -- 在 `options` 中增加 `conflict` 字段, 用于声明不兼容的应用 +- 在 `options` 中增加 `conflict` 字段， 用于声明不兼容的应用 - 移除 `options` 中 `analytics` 配置项 - 修改 `tailscale` 字段的配置格式 -- 增加 `allowedOutboundPorts` 配置,允许通过指定端口进行非 HTTP 协议的对外访问 +- 增加 `allowedOutboundPorts` 配置，允许通过指定端口进行非 HTTP 协议的对外访问 - 修改 `ports` 部分的配置 `0.8.3` - 在 `dependencies` 配置项里增加 `mandatory` 字段以表示该依赖应用必须安装。 -- 增加 `tailscaleAcls` 配置项,允许 Tailscale 为应用开放指定端口 +- 增加 `tailscaleAcls` 配置项，允许 Tailscale 为应用开放指定端口 `0.8.2` -- 添加 `runAsUser` 选项,用于限制应用程序在非root权限的用户下运行 +- 添加 `runAsUser` 选项，用于限制应用程序在非root权限的用户下运行 `0.8.1` - 添加 `ports` 选项以指定 UDP 或 TCP 的暴露端口 @@ -133,22 +122,22 @@ options: - 类型:`string` - 有效值: `app`、`recommend`、`middleware` -Olares 市场目前支持 3 种类型的应用,各自对应不同场景。本文档以 "app" 为例来解释各个字段。其他类型请参考相应的配置指南。 +Olares 市场目前支持 3 种类型的应用，各自对应不同场景。本文档以 "app" 为例来解释各个字段。其他类型请参考相应的配置指南。 - [推荐算法配置指南](recommend.md) :::info 提示 -Olares Market 目前不展示 `recommend` 类型的应用,但你可以上传自定义 Chart 来给 Wise 安装推荐算法 +Olares Market 目前不展示 `recommend` 类型的应用，但你可以上传自定义 Chart 来给 Wise 安装推荐算法 ::: ## olaresManifest.version - 类型:`string` -随着 Olares 更新,`OlaresManifest.yaml` 的配置规范可能会发生变化。你可以通过检查 `olaresManifest.version` 来确定这些更改是否会影响你的应用程序。 `olaresManifest.version` 由三个用英文句点分隔的整数组成。 +随着 Olares 更新，`OlaresManifest.yaml` 的配置规范可能会发生变化。你可以通过检查 `olaresManifest.version` 来确定这些更改是否会影响你的应用程序。 `olaresManifest.version` 由三个用英文句点分隔的整数组成。 -- 第 1 位数字增加意味着引入了不兼容的配置项,未升级对应 `OlaresManifest.yaml` 的应用将无法分发或安装。 -- 第 2 位数字增加意味着分发和安装必须字段存在变化,但 Olares 系统仍兼容之前所有版本配置的应用分发与安装。我们建议开发者尽快更新升级应用的 `OlaresManifest.yaml` 文件。 -- 第 3 位数字的改变,不影响应用分发和安装。 +- 第 1 位数字增加意味着引入了不兼容的配置项，未升级对应 `OlaresManifest.yaml` 的应用将无法分发或安装。 +- 第 2 位数字增加意味着分发和安装必须字段存在变化，但 Olares 系统仍兼容之前所有版本配置的应用分发与安装。我们建议开发者尽快更新升级应用的 `OlaresManifest.yaml` 文件。 +- 第 3 位数字的改变，不影响应用分发和安装。 开发者可以使用 1-3 位的版本号来标识该应用遵循的配置版本。以下是有效版本的一些示例: ```yaml @@ -164,14 +153,14 @@ olaresManifest.version: "3.0.122" - 有效值:`v1`、`v3` - 默认值:`v1` -共享应用需使用 `v3`,将被安装在 `xxx-shared` namespace 中。其他应用请使用 `v1`。 +共享应用需使用 `v3`，将被安装在 `xxx-shared` namespace 中。其他应用请使用 `v1`。 :::info 提示 -`apiVersion: 'v2'` 用于 CSV2 应用,将于 Olares OS 1.12.6 发布后逐步停止支持。共享应用请迁移到 `v3`。 +`apiVersion: 'v2'` 用于 CSV2 应用，将于 Olares OS 1.12.6 发布后逐步停止支持。共享应用请迁移到 `v3`。 ::: ## Metadata -应用的基本信息,用于在 Olares 系统和应用市场中展示应用。 +应用的基本信息，用于在 Olares 系统和应用市场中展示应用。 :::info 示例 ```yaml @@ -190,9 +179,9 @@ metadata: ### name - 类型:`string` -- 有效值:`^[a-z][a-z0-9]{0,29}$` +- 有效值:`^[a-z][a-z0-9]{0，29}$` -Olares 中的应用的命名空间,仅限小写字母数字字符。最多 30 个字符,需要与 `Chart.yaml` 中的 `FolderName` 和 `name` 字段保持一致。 +Olares 中的应用的命名空间，仅限小写字母数字字符。最多 30 个字符，需要与 `Chart.yaml` 中的 `FolderName` 和 `name` 字段保持一致。 ### title @@ -212,13 +201,13 @@ Olares 应用市场中的应用名称下方显示的简短说明。 应用图标。 -图标必须是 `PNG` 或 `WEBP` 格式文件,最大为 `512 KB`,尺寸为 `256x256 px`。 +图标必须是 `PNG` 或 `WEBP` 格式文件，最大为 `512 KB`，尺寸为 `256x256 px`。 ### version - 类型:`string` -应用的 Chart Version,每次改变 Chart 目录里的内容时应递增。需遵循[语义化版本规范](https://semver.org/),需要与 `Chart.yaml` 中的 `version` 字段一致。 +应用的 Chart Version，每次改变 Chart 目录里的内容时应递增。需遵循[语义化版本规范](https://semver.org/)，需要与 `Chart.yaml` 中的 `version` 字段一致。 ### categories @@ -239,12 +228,12 @@ OS 1.12 有效值: - `AI`:AI :::info 提示 -Olares OS 1.12.0 版本对应用商店的应用分类进行了调整,因此如果应用需要同时兼容 1.11 和 1.12 版本,请同时填写两个版本所需的分类。 +Olares OS 1.12.0 版本对应用商店的应用分类进行了调整，因此如果应用需要同时兼容 1.11 和 1.12 版本，请同时填写两个版本所需的分类。 ::: ## Entrances -指定此应用访问入口的数量。每个应用允许最少 1 个,最多 10 个入口 。 +指定此应用访问入口的数量。每个应用允许最少 1 个，最多 10 个入口 。 :::info 示例 ```yaml @@ -267,7 +256,7 @@ entrances: - 类型:`string` - Accepted Value: `[a-z]([-a-z0-9]*[a-z0-9])?` - 入口的名称,长度不超过 `63` 个字符。一个应用内不能重复。 + 入口的名称，长度不超过 `63` 个字符。一个应用内不能重复。 ### port @@ -279,7 +268,7 @@ entrances: - 类型:`string` - 有效值: `[a-z]([-a-z0-9]*[a-z0-9])?` - 当前入口的 Ingress 名称,只包含小写字母和数字和中划线`-`,长度不超过 63 个字符。 + 当前入口的 Ingress 名称，只包含小写字母和数字和中划线`-`，长度不超过 63 个字符。 ### title @@ -292,7 +281,7 @@ entrances: - 类型: `url` - 可选 -应用安装后 Olares 桌面上的图标。图片文件必须是 `PNG` 或 `WEBP` 格式,不超过 `512 KB`,尺寸为 `256x256 px`。 +应用安装后 Olares 桌面上的图标。图片文件必须是 `PNG` 或 `WEBP` 格式，不超过 `512 KB`，尺寸为 `256x256 px`。 ### authLevel @@ -312,7 +301,7 @@ entrances: - 默认值:`false` - 可选 -当 `invisible` 为` true` 时,该入口不会显示在 Olares 桌面上。 +当 `invisible` 为` true` 时，该入口不会显示在 Olares 桌面上。 ### openMethod @@ -323,16 +312,16 @@ entrances: 指定该入口在桌面的打开方式。 -`iframe` 代表在桌面的窗口内通过 iframe 新建一个窗口,`window` 代表在浏览器新的 Tab 页打开。`default` 代表跟随系统的默认选择,系统默认的选择是`iframe`。 +`iframe` 代表在桌面的窗口内通过 iframe 新建一个窗口，`window` 代表在浏览器新的 Tab 页打开。`default` 代表跟随系统的默认选择，系统默认的选择是`iframe`。 ### windowPushState - 类型: `boolean` - 默认值:`false` - 可选 -将应用嵌入到桌面上的 iframe 中时,应用的 URL 可能会动态更改。由于浏览器的同源策略,桌面(父窗口)无法直接检测到 iframe URL 中的这些变化。因此,如果你重新打开应用程序选项卡,它将显示初始 URL,而不是更新后的 URL。 +将应用嵌入到桌面上的 iframe 中时，应用的 URL 可能会动态更改。由于浏览器的同源策略，桌面(父窗口)无法直接检测到 iframe URL 中的这些变化。因此，如果你重新打开应用程序选项卡，它将显示初始 URL，而不是更新后的 URL。 -为了确保无缝的用户体验,你可以通过将其设置为 true 来启用此选项。此操作会提示网关自动将以下代码注入到 iframe 中。每当 iframe 的 URL 发生更改时,此代码都会向父窗口(桌面)发送一个事件。因此,桌面可以跟踪 URL 更改并打开正确的页面。 +为了确保无缝的用户体验，你可以通过将其设置为 true 来启用此选项。此操作会提示网关自动将以下代码注入到 iframe 中。每当 iframe 的 URL 发生更改时，此代码都会向父窗口(桌面)发送一个事件。因此，桌面可以跟踪 URL 更改并打开正确的页面。 ::: details 代码 ```Javascript @@ -360,7 +349,7 @@ entrances: ## sharedEntrances -共享入口是共享应用为集群内其他应用调用提供的接口地址。共享入口的字段配置和常规入口基本一致,一个典型的共享入口配置如下 +共享入口是共享应用为集群内其他应用调用提供的接口地址。共享入口的字段配置和常规入口基本一致，一个典型的共享入口配置如下 :::info 示例 ```yaml @@ -386,7 +375,7 @@ ports: host: windows-svc # 提供服务的 Ingress 主机名称 port: 3389 # 提供服务的端口号 protocol: udp # 暴露端口使用的协议 - exposePort: 46879 # 暴露的端口,在集群内一次只能分配给一个应用程序 + exposePort: 46879 # 暴露的端口，在集群内一次只能分配给一个应用程序 addToTailscaleAcl: true # 自动添加到 Tailscale 的 ACL 列表中 ``` ::: @@ -395,7 +384,7 @@ ports: - 类型: `int` - 可选 - 有效值: `0-65535`,保留端口 `22`, `80`, `81`, `443`, `444`, `2379`, `18088` 除外 -Olares 会为你的应用暴露指定的端口,这些端口可通过应用域名在本地网络下访问,如`84864c1f.your_olares_id.olares.com:46879`。对于每个公开的端口,Olares 会自动配置相同端口号的 TCP 和 UDP。 +Olares 会为你的应用暴露指定的端口，这些端口可通过应用域名在本地网络下访问，如`84864c1f.your_olares_id.olares.com:46879`。对于每个公开的端口，Olares 会自动配置相同端口号的 TCP 和 UDP。 :::info 提示 暴露的端口只能通过本地网络或 Olares 专用网络访问。 @@ -406,14 +395,14 @@ Olares 会为你的应用暴露指定的端口,这些端口可通过应用域名 - 可选 - 有效值: `udp`、`tcp` -暴露端口使用的协议 ,如果不填默认同时开通udp和tcp。 +暴露端口使用的协议 ，如果不填默认同时开通udp和tcp。 ### addToTailscaleAcl - 类型: `boolean` - 可选 - 默认值:`false` -当将 addToTailscaleAcl 字段设置为 true 时,系统会为该端口分配一个随机端口,并自动将其加入到 Tailscale 的 ACL 中。 +当将 addToTailscaleAcl 字段设置为 true 时，系统会为该端口分配一个随机端口，并自动将其加入到 Tailscale 的 ACL 中。 ## Tailscale - 类型:`map` @@ -428,7 +417,7 @@ tailscale: - proto: tcp dst: - "*:46879" - - proto: "" # 可选, 如果未指定,则允许使用所有支持的协议 + - proto: "" # 可选， 如果未指定，则允许使用所有支持的协议 dst: - "*:4557" ``` @@ -451,14 +440,14 @@ permission: - 类型: `boolean` - 可选 -是否需要在 `Cache` 目录创建应用的目录。如需要在部署 yaml 文件中使用`.Values.userspace.appCache`, `appCache` 必须设为 `true`。 +是否需要在 `Cache` 目录创建应用的目录。如需要在部署 yaml 文件中使用`.Values.userspace.appCache`，`appCache` 必须设为 `true`。 ### appData - 类型: `boolean` - 可选 -是否需要在 `Data` 目录创建应用的目录。如需要在部署 yaml 中使用`.Values.userspace.appData`, `appData` 必须设为 `true`。 +是否需要在 `Data` 目录创建应用的目录。如需要在部署 yaml 中使用`.Values.userspace.appData`，`appData` 必须设为 `true`。 ### appCommon @@ -486,17 +475,17 @@ permission: - 类型:`list` - 可选 -用于声明本应用需访问的其他应用接口。被访问的应用需在其 `provider` 部分声明对外开放的 `providerName`,详见下方 Provider 章节。 +用于声明本应用需访问的其他应用接口。被访问的应用需在其 `provider` 部分声明对外开放的 `providerName`，详见下方 Provider 章节。 配置访问的方式如下 1. 在 `appName` 字段填写目标应用的 `name` 字段。 2. 在`providerName` 字段填写目标应用 `provider` 配置中的 `name` 字段。 -你可以使用 `podSelectors` 字段来指定本应用中哪些 pod 需要访问目标应用。如果未声明此字段,则默认为本应用的所有 pod 注入 `outbound envoy sidecar`。 +你可以使用 `podSelectors` 字段来指定本应用中哪些 pod 需要访问目标应用。如果未声明此字段，则默认为本应用的所有 pod 注入 `outbound envoy sidecar`。 :::info 调用应用示例 ```yaml -# 需要调用其他应用的应用,如 sonarr +# 需要调用其他应用的应用，如 sonarr permission: provider: - appName: bazarr @@ -508,7 +497,7 @@ permission: ::: :::info 被调用应用示例 ```yaml -# 被调用方应用,如 bazarr +# 被调用方应用，如 bazarr provider: - name: bazarr-svc entrance: bazarr-svc @@ -519,16 +508,16 @@ provider: ## Spec -记录额外的应用信息,主要用于应用商店的展示。 +记录额外的应用信息，主要用于应用商店的展示。 :::info 示例 ```yaml spec: versionName: '10.8.11' - # 此 Chart 包含的应用程序的版本。建议将版本号括在引号中。该值对应于 Chart.yaml 文件中的 appVersion 字段。请注意,它与 version 字段无关。 + # 此 Chart 包含的应用程序的版本。建议将版本号括在引号中。该值对应于 Chart.yaml 文件中的 appVersion 字段。请注意，它与 version 字段无关。 featuredImage: https://app.cdn.olares.com/appstore/jellyfin/promote_image_1.jpg - # 当应用在应用市场上推荐时,会显示特色图像。 + # 当应用在应用市场上推荐时，会显示特色图像。 promoteImage: - https://app.cdn.olares.com/appstore/jellyfin/promote_image_1.jpg @@ -551,12 +540,12 @@ spec: requiredMemory: 256Mi requiredDisk: 128Mi requiredCpu: 0.5 - # 指定安装和运行应用所需的最少资源。安装应用后,系统将保留这些资源以确保最佳性能。 + # 指定安装和运行应用所需的最少资源。安装应用后，系统将保留这些资源以确保最佳性能。 limitedDisk: 256Mi limitedCpu: 1 limitedMemory: 512Mi - # 指定应用的最大资源限制。如果应用超出这些限制,它将暂时暂停,以防止系统过载并确保稳定性。 + # 指定应用的最大资源限制。如果应用超出这些限制，它将暂时暂停，以防止系统过载并确保稳定性。 legal: - text: Community Standards @@ -577,8 +566,8 @@ spec: 要在 Olares 应用市场中为应用添加多语言支持: 1. 在 Olares Application Chart 根目录中创建一个 `i18n` 文件夹。 -2. 在 `i18n` 文件夹中,为每个支持的语言环境创建单独的子目录。 -3. 在每个语言环境子目录中,放置 `OlaresManifest.yaml` 文件的本地化版本。 +2. 在 `i18n` 文件夹中，为每个支持的语言环境创建单独的子目录。 +3. 在每个语言环境子目录中，放置 `OlaresManifest.yaml` 文件的本地化版本。 Olares 应用市场将根据用户的区域设置自动显示相应的 `OlaresManifest.yaml` 文件的内容。 :::info 示例 @@ -598,7 +587,7 @@ Olares 应用市场将根据用户的区域设置自动显示相应的 `OlaresMa └── values.yaml ``` ::: -目前,你可以为以下字段添加 i18n 内容: +目前，你可以为以下字段添加 i18n 内容: ```yaml metadata: description: @@ -633,7 +622,7 @@ Olares 目前不支持混合架构的集群。 - 默认值: `false` - 可选 -设置为 `true` 时,只有管理员可以安装此应用程序。 +设置为 `true` 时，只有管理员可以安装此应用程序。 ### runAsUser - 类型: `boolean` @@ -685,9 +674,9 @@ workloads: - 类型:`map` - 可选 -系统提供了高可用的中间件服务,开发者无需重复安装中间件,只需在此填写对应的中间件信息即可,然后可以直接使用应用程序的 deployment YAML 文件中相应的中间件信息。 +系统提供了高可用的中间件服务，开发者无需重复安装中间件，只需在此填写对应的中间件信息即可，然后可以直接使用应用程序的 deployment YAML 文件中相应的中间件信息。 -使用 `scripts` 字段指定创建数据库后应执行的脚本。此外,使用 `extension` 字段在数据库中添加相应的扩展名。 +使用 `scripts` 字段指定创建数据库后应执行的脚本。此外，使用 `extension` 字段在数据库中添加相应的扩展名。 :::info 提示 MongoDB,MySQL,MariaDB,MinIO,RabbitMQ 需要管理员从 Market 安装后才能被其他应用使用 @@ -709,14 +698,14 @@ middleware: - ALTER DATABASE $databasename SET search_path TO "$user", public, vectors; - ALTER SCHEMA vectors OWNER TO $dbusername; - COMMIT; - # 操作系统提供了两个变量 $databasename 和 $dbusername,命令执行时会被 Olares 应用运行时替换。 + # 操作系统提供了两个变量 $databasename 和 $dbusername，命令执行时会被 Olares 应用运行时替换。 ``` ::: 使用 deployment YAML 中的中间件信息: ```yaml -# 对于 PostgreSQL,对应值如下 +# 对于 PostgreSQL，对应值如下 - env: - - name: DB_POSTGRESDB_DATABASE # 你在 OlaresManifest 中配置的数据库名称,在 middleware.postgres.databases[i].name 中指定 + - name: DB_POSTGRESDB_DATABASE # 你在 OlaresManifest 中配置的数据库名称，在 middleware.postgres.databases[i].name 中指定 value: {{ .Values.postgres.databases. }} - name: DB_POSTGRESDB_HOST value: {{ .Values.postgres.host }} @@ -739,7 +728,7 @@ middleware: ::: 使用 deployment YAML 中的中间件信息: ```yaml -# 对于 Redis,对应的值如下 +# 对于 Redis，对应的值如下 host --> {{ .Values.redis.host }}For Redis, the corresponding value is as follow port --> "{{ .Values.redis.port }}" password --> "{{ .Values.redis.password }}" @@ -759,12 +748,12 @@ middleware: ::: 使用 deployment YAML 中的中间件信息: ```yaml -# 对于 MongoDB,对应的值如下 +# 对于 MongoDB，对应的值如下 host --> {{ .Values.mongodb.host }} port --> "{{ .Values.mongodb.port }}" # yaml 文件中的端口和密码需要用双引号括起来。 username --> {{ .Values.mongodb.username }} password --> "{{ .Values.mongodb.password }}" # yaml 文件中的端口和密码需要用双引号括起来。 -databases --> "{{ .Values.mongodb.databases }}" # 数据库的值类型是 map。你可以使用 {{ .Values.mongodb.databases. }} 获取数据库。 是你在 OlaresManifest 中配置的名称,在 middleware.mongodb.databases[i].name 中指定 +databases --> "{{ .Values.mongodb.databases }}" # 数据库的值类型是 map。你可以使用 {{ .Values.mongodb.databases. }} 获取数据库。 是你在 OlaresManifest 中配置的名称，在 middleware.mongodb.databases[i].name 中指定 ``` ### MinIO :::info 示例 @@ -778,7 +767,7 @@ middleware: ::: 使用 deployment YAML 中的中间件信息: ```yaml -# 对于 MinIO,对应的值如下 +# 对于 MinIO，对应的值如下 - env: - name: MINIO_ENDPOINT value: '{{ .Values.minio.host }}:{{ .Values.minio.port }}' @@ -803,7 +792,7 @@ middleware: ::: 使用 deployment YAML 中的中间件信息: ```yaml -# 对于 RabbitMQ,对应的值如下 +# 对于 RabbitMQ，对应的值如下 - env: - name: RABBITMQ_HOST value: '{{ .Values.rabbitmq.host }}' @@ -835,7 +824,7 @@ middleware: ::: 使用 deployment YAML 中的中间件信息: ```yaml -# 对于 MariaDB,对应的值如下 +# 对于 MariaDB，对应的值如下 - env: - name: MDB_HOST value: '{{ .Values.mariadb.host }}' @@ -861,7 +850,7 @@ middleware: 使用 deployment YAML 中的中间件信息: ```yaml -# 对于 MySQL,对应的值如下 +# 对于 MySQL，对应的值如下 - env: - name: MDB_HOST value: '{{ .Values.mysql.host }}' @@ -901,7 +890,7 @@ options: - 类型:`map` - 可选 -是否为 Olares 集群中的所有用户安装此应用程序。对用共享应用,需要设置 `clusterScoped` 为 `true`, 同时在 `appRef` 字段填入应用名称 +是否为 Olares 集群中的所有用户安装此应用程序。对用共享应用，需要设置 `clusterScoped` 为 `true`， 同时在 `appRef` 字段填入应用名称 :::info 应用ollamav2示例 @@ -926,7 +915,7 @@ options: - name: ollamav2 type: application version: '>=1.0.1' - mandatory: true # 其他用户安装客户端,依赖管理员安装的共享服务 + mandatory: true # 其他用户安装客户端，依赖管理员安装的共享服务 {{- end }} ``` ::: @@ -935,9 +924,9 @@ options: ### dependencies - 类型:`list` -如果此应用依赖于其他应用或需要特定操作系统版本,请在此处声明。 +如果此应用依赖于其他应用或需要特定操作系统版本，请在此处声明。 -如果此应用程序需要依赖其他应用程序才能正确安装,则应将 `mandatory` 字段设置为 `true`。 +如果此应用程序需要依赖其他应用程序才能正确安装，则应将 `mandatory` 字段设置为 `true`。 :::info 示例 ```yaml @@ -949,7 +938,7 @@ options: - name: mongodb version: ">=6.0.0-0" type: middleware - mandatory: true # 如果必须先安装此依赖,请将此字段设为 true。 + mandatory: true # 如果必须先安装此依赖，请将此字段设为 true。 ``` ::: @@ -976,7 +965,7 @@ options: - 默认值: `false` - 可选 -确定应用是否与移动网络浏览器兼容并且可以在移动版本的 Olares 桌面上显示。如果应用程序针对移动网络浏览器进行了优化,请启用此选项。这将使该应用程序在移动版 Olares 桌面上可见并可访问。 +确定应用是否与移动网络浏览器兼容并且可以在移动版本的 Olares 桌面上显示。如果应用程序针对移动网络浏览器进行了优化，请启用此选项。这将使该应用程序在移动版 Olares 桌面上可见并可访问。 :::info 示例 ```yaml @@ -988,7 +977,7 @@ mobileSupported: true - 类型:`map` - 可选 -Olares 包含内置的 OpenID Connect 身份验证组件,以简化用户的身份验证。启用此选项可在你的应用中使用 OpenID。 +Olares 包含内置的 OpenID Connect 身份验证组件，以简化用户的身份验证。启用此选项可在你的应用中使用 OpenID。 ```yaml # yaml 中 OpenID 相关变量 {{ .Values.oidc.client.id }} @@ -1021,7 +1010,7 @@ apiTimeout: 0 - 类型: `list` - 可选 -要求开通以下端口进行非 HTTP 协议的对外访问,例如 SMTP 服务等。 +要求开通以下端口进行非 HTTP 协议的对外访问，例如 SMTP 服务等。 :::info 示例 ```yaml @@ -1066,7 +1055,7 @@ overlayGateway: ## Envs -在此声明应用运行所需的环境变量,既支持用户手动输入,也可以直接引用已有的系统环境变量值。 +在此声明应用运行所需的环境变量，既支持用户手动输入，也可以直接引用已有的系统环境变量值。 :::info 提示 该配置需要 Olares OS 版本在 1.12.2 及以上才生效 @@ -1076,17 +1065,17 @@ overlayGateway: ```yaml envs: - envName: ENV_NAME - # 在部署应用时,该键会被注入为.Values.olaresEnv.ENV_NAME + # 在部署应用时，该键会被注入为.Values.olaresEnv.ENV_NAME required: true # 是否为必填项 - # 若为true且未设置default,则用户安装应用时必须填写此值,且修改value时不允许清空 + # 若为true且未设置default，则用户安装应用时必须填写此值，且修改value时不允许清空 default: "DEFAULT" - # 环境变量的默认值,开发者可在编写时提供,用户不可修改。 + # 环境变量的默认值，开发者可在编写时提供，用户不可修改。 type: string - # 环境变量的类型,目前有int/bool/url/ip/domain/email/string/password。如果声明,会对value进行类型校验 + # 环境变量的类型，目前有int/bool/url/ip/domain/email/string/password。如果声明，会对value进行类型校验 editable: true # 是否可在应用部署后编辑 @@ -1096,30 +1085,30 @@ envs: value: "11" - title: Windows10 value: "10" - # 允许值列表,此环境变量的值只允许从该列表中选择 - # title为展示给用户的名称,value为实际注入系统的值 + # 允许值列表，此环境变量的值只允许从该列表中选择 + # title为展示给用户的名称，value为实际注入系统的值 remoteOptions: https://xxx.xxx/xx - # 提供允许值列表的一个url,response body需为JSON编码的options列表 + # 提供允许值列表的一个url，response body需为JSON编码的options列表 - regex: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$' + regex: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2，}$' # 该环境变量的值必须匹配此正则表达式 valueFrom: envName: OLARES_SYSTEM_CLUSTER_DNS_SERVICE - # 引用系统环境变量的值。如果采用该方式,将不允许用户手动指定/修改其value - # 引用后,此环境变量的可声明字段(type,editable)将被系统环境变量的对应属性覆盖,default/value字段也会失效 + # 引用系统环境变量的值。如果采用该方式，将不允许用户手动指定/修改其value + # 引用后，此环境变量的可声明字段(type，editable)将被系统环境变量的对应属性覆盖，default/value字段也会失效 applyOnChange: true - # 是否在此环境变量的值变化时自动重新部署应用,使变化生效 - # 若该字段为false,在环境变量变化时,即使停止/启动应用,也不会生效,只有升级/重装会生效 + # 是否在此环境变量的值变化时自动重新部署应用，使变化生效 + # 若该字段为false，在环境变量变化时，即使停止/启动应用，也不会生效，只有升级/重装会生效 description: "DESCRIPTION" # 对环境变量的描述 ``` ::: -如需在部署 YAML 文件中使用环境变量的值,只需在相应位置使用 `.Values.olaresEnv.ENV_NAME` 即可。系统会在应用部署时自动将对应的 olaresEnv 变量注入到 values 中。例如 +如需在部署 YAML 文件中使用环境变量的值，只需在相应位置使用 `.Values.olaresEnv.ENV_NAME` 即可。系统会在应用部署时自动将对应的 olaresEnv 变量注入到 values 中。例如 :::info 示例 ```yaml @@ -1134,15 +1123,15 @@ BACKEND_MAIL_SENDER: "{{ .Values.olaresEnv.MAIL_SENDER }}" ## Provider -在此声明本应用向其他应用开放的接口。系统会自动为这些接口生成 Service,让集群内其他应用能够通过内部网络访问。如果其他应用要调用这些接口,需要在 permission 部分申请访问该 provider 的权限。 +在此声明本应用向其他应用开放的接口。系统会自动为这些接口生成 Service，让集群内其他应用能够通过内部网络访问。如果其他应用要调用这些接口，需要在 permission 部分申请访问该 provider 的权限。 :::info 示例 ```yaml provider: - name: bazarr entrance: bazarr-svc # 该服务的入口名称 - paths: ["/api*"] # 开放的接口路径,不能只包含通配符 * - verbs: ["*"] # 支持post,get,put,delete,patch;"*"表示允许所有方法 + paths: ["/api*"] # 开放的接口路径，不能只包含通配符 * + verbs: ["*"] # 支持post，get，put，delete，patch;"*"表示允许所有方法 ``` ::: From d0e15488e04581dcd397ed757346e9cc9222e132 Mon Sep 17 00:00:00 2001 From: RiddleMe <142984611+TShentu@users.noreply.github.com> Date: Wed, 3 Jun 2026 14:32:26 +0800 Subject: [PATCH 3/9] fix punctuation marks --- docs/zh/developer/develop/package/manifest.md | 158 +++++++++--------- 1 file changed, 79 insertions(+), 79 deletions(-) diff --git a/docs/zh/developer/develop/package/manifest.md b/docs/zh/developer/develop/package/manifest.md index 5b4a9ece66..b94e619fe8 100644 --- a/docs/zh/developer/develop/package/manifest.md +++ b/docs/zh/developer/develop/package/manifest.md @@ -7,7 +7,7 @@ outline: [2， 3] 每一个 Olares 应用的 Chart 根目录下都必须有一个名为 `OlaresManifest.yaml` 的文件。`OlaresManifest.yaml` 描述了一个 Olares 应用的所有基本信息。Olares 应用市场协议和 Olares 系统依赖这些关键信息来正确分发和安装应用。 :::info 提示 -最新的 Olares 系统使用的 Manifest 版本为: `0.12.0` +最新的 Olares 系统使用的 Manifest 版本为： `0.12.0` - 修改 `apiVersion` 字段，增加`v3`共享应用，原`v2`版共享应用将作废 - 增加 `spec.accelerator` 字段，用于 GPU 资源声明 - 增加 `workloadReplicas` 字段，声明所有 workload 的副本数 @@ -55,7 +55,7 @@ outline: [2， 3] - 将 `spec`>`language` 改为 `spec`>`locale` 并支持 i18n ::: -一个 `OlaresManifest.yaml` 文件的示例如下: +一个 `OlaresManifest.yaml` 文件的示例如下： ::: details `OlaresManifest.yaml` 示例 @@ -119,8 +119,8 @@ options: ## olaresManifest.type -- 类型:`string` -- 有效值: `app`、`recommend`、`middleware` +- 类型：`string` +- 有效值： `app`、`recommend`、`middleware` Olares 市场目前支持 3 种类型的应用，各自对应不同场景。本文档以 "app" 为例来解释各个字段。其他类型请参考相应的配置指南。 - [推荐算法配置指南](recommend.md) @@ -131,7 +131,7 @@ Olares Market 目前不展示 `recommend` 类型的应用，但你可以上传 ## olaresManifest.version -- 类型:`string` +- 类型：`string` 随着 Olares 更新，`OlaresManifest.yaml` 的配置规范可能会发生变化。你可以通过检查 `olaresManifest.version` 来确定这些更改是否会影响你的应用程序。 `olaresManifest.version` 由三个用英文句点分隔的整数组成。 @@ -139,7 +139,7 @@ Olares Market 目前不展示 `recommend` 类型的应用，但你可以上传 - 第 2 位数字增加意味着分发和安装必须字段存在变化，但 Olares 系统仍兼容之前所有版本配置的应用分发与安装。我们建议开发者尽快更新升级应用的 `OlaresManifest.yaml` 文件。 - 第 3 位数字的改变，不影响应用分发和安装。 -开发者可以使用 1-3 位的版本号来标识该应用遵循的配置版本。以下是有效版本的一些示例: +开发者可以使用 1-3 位的版本号来标识该应用遵循的配置版本。以下是有效版本的一些示例： ```yaml olaresManifest.version: 1 olaresManifest.version: 1.1.0 @@ -148,10 +148,10 @@ olaresManifest.version: "3.0.122" ``` ## apiVersion -- 类型:`string` +- 类型：`string` - 可选 -- 有效值:`v1`、`v3` -- 默认值:`v1` +- 有效值：`v1`、`v3` +- 默认值：`v1` 共享应用需使用 `v3`，将被安装在 `xxx-shared` namespace 中。其他应用请使用 `v1`。 :::info 提示 @@ -178,26 +178,26 @@ metadata: ### name -- 类型:`string` -- 有效值:`^[a-z][a-z0-9]{0，29}$` +- 类型：`string` +- 有效值：`^[a-z][a-z0-9]{0，29}$` Olares 中的应用的命名空间，仅限小写字母数字字符。最多 30 个字符，需要与 `Chart.yaml` 中的 `FolderName` 和 `name` 字段保持一致。 ### title -- 类型:`string` +- 类型：`string` 在应用市场中显示的应用标题。长度不超过 `30` 个字符。 ### description -- 类型:`string` +- 类型：`string` Olares 应用市场中的应用名称下方显示的简短说明。 ### icon -- 类型:`url` +- 类型：`url` 应用图标。 @@ -205,20 +205,20 @@ Olares 应用市场中的应用名称下方显示的简短说明。 ### version -- 类型:`string` +- 类型：`string` 应用的 Chart Version，每次改变 Chart 目录里的内容时应递增。需遵循[语义化版本规范](https://semver.org/)，需要与 `Chart.yaml` 中的 `version` 字段一致。 ### categories -- 类型: `list` +- 类型： `list` 描述在应用市场的哪个类别下展示应用。 -OS 1.11 有效值: +OS 1.11 有效值： - `Blockchain`, `Utilities`, `Social Network`, `Entertainment`, `Productivity` -OS 1.12 有效值: +OS 1.12 有效值： - `Creativity`:设计创作 - `Productivity_v112`:工作效率 - `Developer Tools`:开发工具 @@ -253,41 +253,41 @@ entrances: ### name -- 类型:`string` +- 类型：`string` - Accepted Value: `[a-z]([-a-z0-9]*[a-z0-9])?` 入口的名称，长度不超过 `63` 个字符。一个应用内不能重复。 ### port -- 类型: `int` -- 有效值: `0-65535` +- 类型： `int` +- 有效值： `0-65535` ### host -- 类型:`string` -- 有效值: `[a-z]([-a-z0-9]*[a-z0-9])?` +- 类型：`string` +- 有效值： `[a-z]([-a-z0-9]*[a-z0-9])?` 当前入口的 Ingress 名称，只包含小写字母和数字和中划线`-`，长度不超过 63 个字符。 ### title -- 类型:`string` +- 类型：`string` 安装后 Olares 桌面的显示名称。长度不超过 `30` 个字符。 ### icon -- 类型: `url` +- 类型： `url` - 可选 应用安装后 Olares 桌面上的图标。图片文件必须是 `PNG` 或 `WEBP` 格式，不超过 `512 KB`，尺寸为 `256x256 px`。 ### authLevel -- 类型:`string` -- 有效值: `public`, `private`, `internal` -- 默认值: `private` +- 类型：`string` +- 有效值： `public`, `private`, `internal` +- 默认值： `private` - 可选 指定入口的认证级别。 @@ -297,17 +297,17 @@ entrances: ### invisible -- 类型: `boolean` -- 默认值:`false` +- 类型： `boolean` +- 默认值：`false` - 可选 当 `invisible` 为` true` 时，该入口不会显示在 Olares 桌面上。 ### openMethod -- 类型:`string` -- 有效值: `default`, `iframe`, `window` -- 默认值: `default` +- 类型：`string` +- 有效值： `default`, `iframe`, `window` +- 默认值： `default` - 可选 指定该入口在桌面的打开方式。 @@ -315,8 +315,8 @@ entrances: `iframe` 代表在桌面的窗口内通过 iframe 新建一个窗口，`window` 代表在浏览器新的 Tab 页打开。`default` 代表跟随系统的默认选择，系统默认的选择是`iframe`。 ### windowPushState -- 类型: `boolean` -- 默认值:`false` +- 类型： `boolean` +- 默认值：`false` - 可选 将应用嵌入到桌面上的 iframe 中时，应用的 URL 可能会动态更改。由于浏览器的同源策略，桌面(父窗口)无法直接检测到 iframe URL 中的这些变化。因此，如果你重新打开应用程序选项卡，它将显示初始 URL，而不是更新后的 URL。 @@ -381,9 +381,9 @@ ports: ::: ### exposePort -- 类型: `int` +- 类型： `int` - 可选 -- 有效值: `0-65535`,保留端口 `22`, `80`, `81`, `443`, `444`, `2379`, `18088` 除外 +- 有效值： `0-65535`,保留端口 `22`, `80`, `81`, `443`, `444`, `2379`, `18088` 除外 Olares 会为你的应用暴露指定的端口，这些端口可通过应用域名在本地网络下访问，如`84864c1f.your_olares_id.olares.com:46879`。对于每个公开的端口，Olares 会自动配置相同端口号的 TCP 和 UDP。 :::info 提示 @@ -391,21 +391,21 @@ Olares 会为你的应用暴露指定的端口，这些端口可通过应用域 ::: ### protocol -- 类型: `string` +- 类型： `string` - 可选 -- 有效值: `udp`、`tcp` +- 有效值： `udp`、`tcp` 暴露端口使用的协议 ，如果不填默认同时开通udp和tcp。 ### addToTailscaleAcl -- 类型: `boolean` +- 类型： `boolean` - 可选 -- 默认值:`false` +- 默认值：`false` 当将 addToTailscaleAcl 字段设置为 true 时，系统会为该端口分配一个随机端口，并自动将其加入到 Tailscale 的 ACL 中。 ## Tailscale -- 类型:`map` +- 类型：`map` - 可选 允许应用在 Tailscale 的ACL(Access Control Lists)中开放指定端口。 @@ -437,42 +437,42 @@ permission: ### appCache -- 类型: `boolean` +- 类型： `boolean` - 可选 是否需要在 `Cache` 目录创建应用的目录。如需要在部署 yaml 文件中使用`.Values.userspace.appCache`，`appCache` 必须设为 `true`。 ### appData -- 类型: `boolean` +- 类型： `boolean` - 可选 是否需要在 `Data` 目录创建应用的目录。如需要在部署 yaml 中使用`.Values.userspace.appData`，`appData` 必须设为 `true`。 ### appCommon -- 类型: `boolean` +- 类型： `boolean` - 可选 是否需要对 `App Common` 目录(跨节点跨应用共享模型)进行读写权限。在部署 yaml 文件中使用 `{{ .Values.userspace.appCommon }}` 获取 App Common 目录地址。 ### externalData -- 类型: `boolean` +- 类型： `boolean` - 可选 是否需要对 `External` 目录(挂载 NAS 或其他外部磁盘数据)进行读写权限。不影响已部署的 0.11.0 版本的应用的访问权限。 ### userData -- 类型:`string` +- 类型：`string` - 可选 应用是否需要对用户的 `Home` 文件夹进行读写权限。列出应用需要访问的用户 `Home` 下的所有目录。部署 YAML 中配置的所有 `userData` 目录都必须包含在此处。 ### provider -- 类型:`list` +- 类型：`list` - 可选 用于声明本应用需访问的其他应用接口。被访问的应用需在其 `provider` 部分声明对外开放的 `providerName`，详见下方 Provider 章节。 @@ -563,7 +563,7 @@ spec: ### i18n -要在 Olares 应用市场中为应用添加多语言支持: +要在 Olares 应用市场中为应用添加多语言支持： 1. 在 Olares Application Chart 根目录中创建一个 `i18n` 文件夹。 2. 在 `i18n` 文件夹中，为每个支持的语言环境创建单独的子目录。 @@ -587,7 +587,7 @@ Olares 应用市场将根据用户的区域设置自动显示相应的 `OlaresMa └── values.yaml ``` ::: -目前，你可以为以下字段添加 i18n 内容: +目前，你可以为以下字段添加 i18n 内容： ```yaml metadata: description: @@ -598,8 +598,8 @@ spec: ``` ### supportArch -- 类型: `list` -- 有效值: `amd64`, `arm64` +- 类型： `list` +- 有效值： `amd64`, `arm64` - 可选 该字段用于声明应用程序支持的 CPU 架构。目前仅支持 `amd64` 和 `arm64` 两种类型。 @@ -618,20 +618,20 @@ Olares 目前不支持混合架构的集群。 ::: ### onlyAdmin -- 类型: `boolean` -- 默认值: `false` +- 类型： `boolean` +- 默认值： `false` - 可选 设置为 `true` 时，只有管理员可以安装此应用程序。 ### runAsUser -- 类型: `boolean` +- 类型： `boolean` - 可选 当设置为 `true` 时，Olares 会强制以用户 ID "1000"（非 root 用户）运行应用程序。 ### accelerator -- 类型: `map` +- 类型： `map` - 可选 声明应用所需的 GPU 资源。需要 GPU 的应用，使用 `spec.accelerator` 字段声明资源，不能包含原来的 `spec.requiredMemory` 等字段。 @@ -653,7 +653,7 @@ spec: ::: ### workloadReplicas -- 类型: `map` +- 类型： `map` - 可选 声明 chart 中所有 workload 的副本数。从 0.12.0 开始，应用需要在 OlaresManifest 里添加变量，声明 chart 中所有 workload 的副本数量。 @@ -671,7 +671,7 @@ workloads: ``` ## Middleware -- 类型:`map` +- 类型：`map` - 可选 系统提供了高可用的中间件服务，开发者无需重复安装中间件，只需在此填写对应的中间件信息即可，然后可以直接使用应用程序的 deployment YAML 文件中相应的中间件信息。 @@ -701,7 +701,7 @@ middleware: # 操作系统提供了两个变量 $databasename 和 $dbusername，命令执行时会被 Olares 应用运行时替换。 ``` ::: -使用 deployment YAML 中的中间件信息: +使用 deployment YAML 中的中间件信息： ```yaml # 对于 PostgreSQL，对应值如下 - env: @@ -726,7 +726,7 @@ middleware: namespace: db0 ``` ::: -使用 deployment YAML 中的中间件信息: +使用 deployment YAML 中的中间件信息： ```yaml # 对于 Redis，对应的值如下 host --> {{ .Values.redis.host }}For Redis, the corresponding value is as follow @@ -746,7 +746,7 @@ middleware: # 请确保每一行都是完整的查询。 ``` ::: -使用 deployment YAML 中的中间件信息: +使用 deployment YAML 中的中间件信息： ```yaml # 对于 MongoDB，对应的值如下 host --> {{ .Values.mongodb.host }} @@ -765,7 +765,7 @@ middleware: - name: mybucket ``` ::: -使用 deployment YAML 中的中间件信息: +使用 deployment YAML 中的中间件信息： ```yaml # 对于 MinIO，对应的值如下 - env: @@ -790,7 +790,7 @@ middleware: - name: aaa ``` ::: -使用 deployment YAML 中的中间件信息: +使用 deployment YAML 中的中间件信息： ```yaml # 对于 RabbitMQ，对应的值如下 - env: @@ -822,7 +822,7 @@ middleware: - name: aaa ``` ::: -使用 deployment YAML 中的中间件信息: +使用 deployment YAML 中的中间件信息： ```yaml # 对于 MariaDB，对应的值如下 - env: @@ -847,7 +847,7 @@ middleware: - name: aaa ``` ::: -使用 deployment YAML 中的中间件信息: +使用 deployment YAML 中的中间件信息： ```yaml # 对于 MySQL，对应的值如下 @@ -869,7 +869,7 @@ middleware: 此部分用于配置与Olares系统相关的选项。 ### policies -- 类型:`list` +- 类型：`list` - 可选 定义应用子域的详细访问控制。 @@ -887,7 +887,7 @@ options: ::: ### appScope -- 类型:`map` +- 类型：`map` - 可选 是否为 Olares 集群中的所有用户安装此应用程序。对用共享应用，需要设置 `clusterScoped` 为 `true`， 同时在 `appRef` 字段填入应用名称 @@ -922,7 +922,7 @@ options: ### dependencies -- 类型:`list` +- 类型：`list` 如果此应用依赖于其他应用或需要特定操作系统版本，请在此处声明。 @@ -943,7 +943,7 @@ options: ::: ### conflicts -- 类型:`list` +- 类型：`list` - 可选 请在此处声明与该应用冲突的其他应用。必须卸载冲突应用后才能安装此应用。 @@ -961,8 +961,8 @@ options: ### mobileSupported -- 类型: `boolean` -- 默认值: `false` +- 类型： `boolean` +- 默认值： `false` - 可选 确定应用是否与移动网络浏览器兼容并且可以在移动版本的 Olares 桌面上显示。如果应用程序针对移动网络浏览器进行了优化，请启用此选项。这将使该应用程序在移动版 Olares 桌面上可见并可访问。 @@ -974,7 +974,7 @@ mobileSupported: true ::: ### oidc -- 类型:`map` +- 类型：`map` - 可选 Olares 包含内置的 OpenID Connect 身份验证组件，以简化用户的身份验证。启用此选项可在你的应用中使用 OpenID。 @@ -995,7 +995,7 @@ oidc: ::: ### apiTimeout -- 类型:`int` +- 类型：`int` - 可选 指定 API 提供程序的超时限制(以秒为单位)。默认值为 `15`。使用 `0` 允许无限制的 API 连接。 @@ -1007,7 +1007,7 @@ apiTimeout: 0 ::: ### allowedOutboundPorts -- 类型: `list` +- 类型： `list` - 可选 要求开通以下端口进行非 HTTP 协议的对外访问，例如 SMTP 服务等。 @@ -1021,22 +1021,22 @@ allowedOutboundPorts: ::: ### allowMultipleInstall -- 类型: `boolean` -- 默认值: `false` +- 类型： `boolean` +- 默认值： `false` - 可选 该应用支持在同一 Olares 集群中部署多个独立实例。此设置对付费应用和共享应用客户端无效。 ### LLMGatewaySupported -- 类型: `boolean` -- 默认值: `false` +- 类型： `boolean` +- 默认值： `false` - 可选 设置为 `true` 时，表示应用支持 LLM Gateway 调用。 ### overlayGateway -- 类型: `map` +- 类型： `map` - 可选 声明应用支持 L2 overlay 局域网发现。开启后，其他应用可通过 IP 地址在局域网内访问该应用。 From 1d1b8228d7900c26d0a2dd6feebac4381b8dacf9 Mon Sep 17 00:00:00 2001 From: RiddleMe <142984611+TShentu@users.noreply.github.com> Date: Wed, 3 Jun 2026 14:36:41 +0800 Subject: [PATCH 4/9] fix punctuation marks --- docs/zh/developer/develop/package/manifest.md | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/zh/developer/develop/package/manifest.md b/docs/zh/developer/develop/package/manifest.md index b94e619fe8..0fe28f3e3e 100644 --- a/docs/zh/developer/develop/package/manifest.md +++ b/docs/zh/developer/develop/package/manifest.md @@ -1,5 +1,5 @@ --- -outline: [2， 3] +outline: [2, 3] --- # OlaresManifest 规范 @@ -34,7 +34,7 @@ outline: [2， 3] - 增加 Envs 部分，支持应用声明需要的环境变量 `0.9.0` -- 在 `options` 中增加 `conflict` 字段， 用于声明不兼容的应用 +- 在 `options` 中增加 `conflict` 字段，用于声明不兼容的应用 - 移除 `options` 中 `analytics` 配置项 - 修改 `tailscale` 字段的配置格式 - 增加 `allowedOutboundPorts` 配置，允许通过指定端口进行非 HTTP 协议的对外访问 @@ -179,7 +179,7 @@ metadata: ### name - 类型：`string` -- 有效值：`^[a-z][a-z0-9]{0，29}$` +- 有效值：`^[a-z][a-z0-9]{0,29}$` Olares 中的应用的命名空间，仅限小写字母数字字符。最多 30 个字符，需要与 `Chart.yaml` 中的 `FolderName` 和 `name` 字段保持一致。 @@ -219,13 +219,13 @@ OS 1.11 有效值： - `Blockchain`, `Utilities`, `Social Network`, `Entertainment`, `Productivity` OS 1.12 有效值： -- `Creativity`:设计创作 -- `Productivity_v112`:工作效率 -- `Developer Tools`:开发工具 -- `Fun`:休闲娱乐 -- `Lifestyle`:生活方式 -- `Utilities_v112`:实用工具 -- `AI`:AI +- `Creativity`：设计创作 +- `Productivity_v112`：工作效率 +- `Developer Tools`：开发工具 +- `Fun`：休闲娱乐 +- `Lifestyle`：生活方式 +- `Utilities_v112`：实用工具 +- `AI`：AI :::info 提示 Olares OS 1.12.0 版本对应用商店的应用分类进行了调整，因此如果应用需要同时兼容 1.11 和 1.12 版本，请同时填写两个版本所需的分类。 @@ -291,9 +291,9 @@ entrances: - 可选 指定入口的认证级别。 -- **Public**:互联网上的任何人都可以不受限制地访问。 -- **Private**:需要从内部和外部网络访问的授权。 -- **Internal**:需要授权才能从外部网络访问。从内部网络(通过 LAN/专用网络)访问时不需要身份验证。 +- **Public**：互联网上的任何人都可以不受限制地访问。 +- **Private**：需要从内部和外部网络访问的授权。 +- **Internal**：需要授权才能从外部网络访问。从内部网络(通过 LAN/专用网络)访问时不需要身份验证。 ### invisible @@ -679,7 +679,7 @@ workloads: 使用 `scripts` 字段指定创建数据库后应执行的脚本。此外，使用 `extension` 字段在数据库中添加相应的扩展名。 :::info 提示 -MongoDB,MySQL,MariaDB,MinIO,RabbitMQ 需要管理员从 Market 安装后才能被其他应用使用 +MongoDB、MySQL、MariaDB、MinIO、RabbitMQ 需要管理员从 Market 安装后才能被其他应用使用 ::: ### PostgreSQL From 5c6825d888a7287bca75d71b67dded51ac600f2e Mon Sep 17 00:00:00 2001 From: RiddleMe <142984611+TShentu@users.noreply.github.com> Date: Wed, 3 Jun 2026 14:42:53 +0800 Subject: [PATCH 5/9] fix apiVersion --- docs/developer/develop/package/manifest.md | 13 ++++--------- docs/zh/developer/develop/package/manifest.md | 13 ++++--------- 2 files changed, 8 insertions(+), 18 deletions(-) diff --git a/docs/developer/develop/package/manifest.md b/docs/developer/develop/package/manifest.md index a3b30203ec..8774239562 100644 --- a/docs/developer/develop/package/manifest.md +++ b/docs/developer/develop/package/manifest.md @@ -120,14 +120,9 @@ options: ## olaresManifest.type - Type: `string` -- Accepted Value: `app`, `recommend`, `middleware` +- Accepted Value: `app`, `middleware` -Olares currently supports 3 types of applications, each requiring different fields. This document uses `app` as an example to explain each field. For information on other types, please refer to the corresponding configuration guide. -- [Recommend Configuration Guide](recommend.md) - -:::info NOTE -`recommend` apps will not be listed in the Olares Market, but you can install recommendation algorithms for Wise by uploading a custom Chart. -::: +Olares currently supports 2 types of applications, each requiring different fields. This document uses `app` as an example to explain each field. ## olaresManifest.version @@ -152,10 +147,10 @@ olaresManifest.version: "3.0.122" - Accepted Value: `v1`, `v3` - Default: `v1` -For shared applications, use version `v3`, which will be installed in the `xxx-shared` namespace. For other applications, use `v1`. +For shared applications, use version `v3`, which will be installed in the `-shared` namespace. For other applications, use `v1`. :::info NOTE -`apiVersion: 'v2'` is for CSV2 apps and is deprecated. It will be removed after Olares OS 1.12.6. Migrate to `v3` for shared applications. +`apiVersion: 'v2'` is used for shared applications on Olares OS version 1.12.5 and earlier. Support for this version will be gradually discontinued after the release of 1.12.6. Please migrate your shared applications to `v3` as soon as possible. ::: ## Metadata diff --git a/docs/zh/developer/develop/package/manifest.md b/docs/zh/developer/develop/package/manifest.md index 0fe28f3e3e..cd70ab99ed 100644 --- a/docs/zh/developer/develop/package/manifest.md +++ b/docs/zh/developer/develop/package/manifest.md @@ -120,14 +120,9 @@ options: ## olaresManifest.type - 类型：`string` -- 有效值： `app`、`recommend`、`middleware` +- 有效值： `app`、`middleware` -Olares 市场目前支持 3 种类型的应用，各自对应不同场景。本文档以 "app" 为例来解释各个字段。其他类型请参考相应的配置指南。 -- [推荐算法配置指南](recommend.md) - -:::info 提示 -Olares Market 目前不展示 `recommend` 类型的应用，但你可以上传自定义 Chart 来给 Wise 安装推荐算法 -::: +Olares 市场目前支持 2 种类型的应用，各自对应不同场景。本文档以 "app" 为例来解释各个字段。 ## olaresManifest.version @@ -153,9 +148,9 @@ olaresManifest.version: "3.0.122" - 有效值：`v1`、`v3` - 默认值：`v1` -共享应用需使用 `v3`，将被安装在 `xxx-shared` namespace 中。其他应用请使用 `v1`。 +共享应用需使用 `v3`，将被安装在 `-shared` namespace 中。其他应用请使用 `v1`。 :::info 提示 -`apiVersion: 'v2'` 用于 CSV2 应用，将于 Olares OS 1.12.6 发布后逐步停止支持。共享应用请迁移到 `v3`。 +`apiVersion: 'v2'` 用于Olares OS 1.12.5及以前版本的共享应用，并将在 1.12.6 发布后逐步停止支持。请尽快迁移共享应用至 `v3` ::: ## Metadata From 0693a9d7baeb5b9cb843c323ae7e0112fe093652 Mon Sep 17 00:00:00 2001 From: RiddleMe <142984611+TShentu@users.noreply.github.com> Date: Wed, 3 Jun 2026 14:43:15 +0800 Subject: [PATCH 6/9] Revert "docs(use-cases/hermes): add Olares skills, OpenAI API, and restart command updates" This reverts commit ef3f95239ed44fdfd1e3ce0d41e0c569942018da. --- docs/use-cases/hermes.md | 90 +--------------------------------------- 1 file changed, 1 insertion(+), 89 deletions(-) diff --git a/docs/use-cases/hermes.md b/docs/use-cases/hermes.md index 1fcc6e9b54..d2f94831d5 100644 --- a/docs/use-cases/hermes.md +++ b/docs/use-cases/hermes.md @@ -217,7 +217,7 @@ You can restart the gateway manually using one of the following methods: This is the fastest method. Open the Hermes CLI from the Launchpad, and then run the following command: ```bash - hermes restart-gateway + touch /opt/data/.gateway-restart-requested ``` - **Use the Hermes Dashboard** @@ -240,94 +240,6 @@ After you complete the basic setup, explore the official resources to expand you The Hermes CLI in the Olares environment does not support `sudo` commands. Ignore any steps in the official documentation that require `sudo` privileges. ::: -## Install Olares Skills - -Hermes Agent supports installing Olares skills to extend its capabilities. These skills provide integration with Olares applications such as Files, Settings, and Dashboard. - -To install Olares skills: - -1. Open the Hermes CLI from the Launchpad. -2. Run the following command to install each skill: - - ```bash - hermes skills install clawhub/olares-shared --yes - ``` - -3. Repeat the command for each of the following skills: - - `clawhub/olares-market` - - `clawhub/olares-dashboard` - - `clawhub/olares-settings` - - `clawhub/olares-files` - -4. After installation, the skills can be used just like OpenClaw skills. - -## Call Hermes Agent via OpenAI-compatible API - -Hermes Agent supports being called by other applications through an OpenAI-compatible API, allowing you to integrate it with tools like OpenWebUI. - -### Step 1: Enable the Gateway API - -1. Open **Settings** > **Applications** > **Hermes Agent**. -2. In the environment variables section, set **API_SERVER_ENABLED** to `true`. -3. Set an **API_SERVER_KEY** value: - - The key must be at least 8 characters long. - - Allowed characters: letters, numbers, and `-_.` - - Avoid placeholder values like `your_api_key`. - - ![Enable Gateway API](/images/manual/use-cases/hermes-api-settings.png#bordered) - -4. Wait for the application to restart. - -### Step 2: Find the Gateway API URL - -1. Go back to **Settings** > **Applications** > **Hermes Agent**. -2. Find the **Hermes Gateway API** URL and copy it. For example: - - ``` - https://baf3d7172.olarestest003.olares.com - ``` - -### Step 3: Verify the API is running - -Open your browser and navigate to: - -``` -https:///health -``` - -If enabled successfully, you will see a response confirming the API is running. - -### Step 4: Connect from another application - -1. Open the application you want to connect (for example, OpenWebUI). -2. Navigate to the admin panel and select **Connection** or **Models**. -3. Add a new OpenAI-compatible model entry with the following settings: - - **Base URL**: Your Hermes Gateway API URL + `/v1` - - For example: `https://baf3d7172.olarestest003.olares.com/v1` - - **Auth**: Select **Bearer** and enter the `API_SERVER_KEY` you set in Step 1. -4. Click the refresh button next to the toggle to check the connection. - -5. Once connected, the Hermes Agent model will appear in your application, and you can start chatting with it. - -![Connect OpenWebUI](/images/manual/use-cases/hermes-openwebui-connection.png#bordered) - -## FAQ: Gateway API fails to start - -**Symptom** -- Gateway API access shows "Unable to connect". -- Logs display: `[Api_Server] Refusing to start: API_SERVER_KEY is set to a placeholder value` - -**Cause** - -The API key does not meet Hermes security requirements. - -**Solution** - -Reset the API key in **Settings** > **Applications** > **Hermes Agent** with a value that: -- Is at least 8 characters long. -- Contains only letters, numbers, and `-_.` -- Is not a common placeholder value like `your_api_key`. - ## Learn more - [How do I create a server in Discord](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) From f9b929df60189f0e41e4c8182892a8ce0c2be62e Mon Sep 17 00:00:00 2001 From: RiddleMe <142984611+TShentu@users.noreply.github.com> Date: Wed, 3 Jun 2026 14:57:40 +0800 Subject: [PATCH 7/9] fix some details --- docs/developer/develop/package/manifest.md | 16 +++++++++++----- docs/zh/developer/develop/package/manifest.md | 15 +++++++++++---- 2 files changed, 22 insertions(+), 9 deletions(-) diff --git a/docs/developer/develop/package/manifest.md b/docs/developer/develop/package/manifest.md index 8774239562..eb982698a9 100644 --- a/docs/developer/develop/package/manifest.md +++ b/docs/developer/develop/package/manifest.md @@ -451,7 +451,7 @@ Whether the app requires read and write permission to the `Data` folder. If `.Va - Type: `boolean` - Optional -Whether the app requires read and write permission to the `App Common` folder (cross-node, cross-app shared models). Use `{{ .Values.userspace.appCommon }}` in the deployment YAML to get the App Common directory path. +Whether the app requires read and write permission to the `App Common` folder (cross-node, cross-app shared files, such as models). Use `{{ .Values.userspace.appCommon }}` in the deployment YAML to get the App Common directory path. ### externalData @@ -459,8 +459,7 @@ Whether the app requires read and write permission to the `App Common` folder (c - Type: `boolean` - Optional -Whether the app requires read and write permission to the `External` folder (mounted NAS or other external disk data). This does not affect the access permissions of already-deployed apps on version 0.11.0. - +Whether the app requires read and write permission to the `External` directory, typically used for accessing mounted NAS or other external disk data. In version 0.11.0, applications have External access enabled by default. Starting from version 0.12.0, you need to explicitly declare this field. ### userData @@ -650,7 +649,7 @@ spec: ``` ::: -### workloadReplicas +## workloadReplicas - Type: `map` - Optional @@ -1029,12 +1028,19 @@ allowedOutboundPorts: This application supports deploying multiple independent instances within the same Olares cluster. This setting does not apply to paid applications or clients of shared applications. +### templateOnly +- Type: `boolean` +- Default: `false` +- Optional + +When set to `true`, this application is marked as a template app. The app cannot be installed directly. An instance must be created before installation. If this option is enabled, `allowMultipleInstall` must also be set to `true`. + ### LLMGatewaySupported - Type: `boolean` - Default: `false` - Optional -When set to `true`, the application supports LLM Gateway calls. +When set to `true`, the application supports LLM Gateway calls. Mainly used for LLM services. ### overlayGateway - Type: `map` diff --git a/docs/zh/developer/develop/package/manifest.md b/docs/zh/developer/develop/package/manifest.md index cd70ab99ed..dad73b03df 100644 --- a/docs/zh/developer/develop/package/manifest.md +++ b/docs/zh/developer/develop/package/manifest.md @@ -449,14 +449,14 @@ permission: - 类型： `boolean` - 可选 -是否需要对 `App Common` 目录(跨节点跨应用共享模型)进行读写权限。在部署 yaml 文件中使用 `{{ .Values.userspace.appCommon }}` 获取 App Common 目录地址。 +是否需要对 `App Common` 目录(跨节点跨应用共享的文件，例如模型文件)进行读写权限。在部署 yaml 文件中使用 `{{ .Values.userspace.appCommon }}` 获取 App Common 目录地址。 ### externalData - 类型： `boolean` - 可选 -是否需要对 `External` 目录(挂载 NAS 或其他外部磁盘数据)进行读写权限。不影响已部署的 0.11.0 版本的应用的访问权限。 +是否需要 `External` 目录的读写权限，通常用于访问挂载的 NAS 或其他外部磁盘数据。0.11.0 版本的应用默认开启External权限，升级到0.12.0后，需要添加此字段显性声明。 ### userData @@ -647,7 +647,7 @@ spec: ``` ::: -### workloadReplicas +## workloadReplicas - 类型： `map` - 可选 @@ -1022,12 +1022,19 @@ allowedOutboundPorts: 该应用支持在同一 Olares 集群中部署多个独立实例。此设置对付费应用和共享应用客户端无效。 +### templateOnly +- 类型： `boolean` +- 默认值： `false` +- 可选 + +设置为 `true` 时，表示应用为模板应用，不存在可安装本体，只能创建一个实例后再安装该实例。启用此项时，allowMultipleInstall 必须为`true`。 + ### LLMGatewaySupported - 类型： `boolean` - 默认值： `false` - 可选 -设置为 `true` 时，表示应用支持 LLM Gateway 调用。 +设置为 `true` 时，表示应用支持 LLM Gateway 调用。主要用于 LLM 服务。 ### overlayGateway From 9aac1a1c3c96ced837b5cb4c5ad24c62fea2b3a2 Mon Sep 17 00:00:00 2001 From: RiddleMe <142984611+TShentu@users.noreply.github.com> Date: Wed, 3 Jun 2026 16:10:16 +0800 Subject: [PATCH 8/9] fix mode --- docs/developer/develop/package/manifest.md | 2 +- docs/zh/developer/develop/package/manifest.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developer/develop/package/manifest.md b/docs/developer/develop/package/manifest.md index eb982698a9..ead29309c1 100644 --- a/docs/developer/develop/package/manifest.md +++ b/docs/developer/develop/package/manifest.md @@ -637,7 +637,7 @@ Declares GPU resources required by the application. For apps that need GPU, use ```yaml spec: accelerator: - mode: nvidia # Supported modes: nvidia, nvidia-gb10, apple-m, strix-halo, mthreads-m1000, cpu + mode: nvidia # Supported modes: nvidia, nvidia-gb10, apple-m, strix-halo, cpu limitedCpu: 7000m requiredCpu: 150m requiredDisk: 50Mi diff --git a/docs/zh/developer/develop/package/manifest.md b/docs/zh/developer/develop/package/manifest.md index dad73b03df..d108866ebe 100644 --- a/docs/zh/developer/develop/package/manifest.md +++ b/docs/zh/developer/develop/package/manifest.md @@ -635,7 +635,7 @@ Olares 目前不支持混合架构的集群。 ```yaml spec: accelerator: - mode: nvidia # 支持的 mode：nvidia、nvidia-gb10、apple-m、strix-halo、mthreads-m1000、cpu + mode: nvidia # 支持的 mode：nvidia、nvidia-gb10、apple-m、strix-halo、cpu limitedCpu: 7000m requiredCpu: 150m requiredDisk: 50Mi From 8a6a4076e2c74c9e38c1fdeb2bfd17ccf7bab685 Mon Sep 17 00:00:00 2001 From: Teng <142984611+TShentu@users.noreply.github.com> Date: Tue, 23 Jun 2026 20:53:57 +0800 Subject: [PATCH 9/9] Apply suggestions from code review Co-authored-by: Meow33 --- docs/developer/develop/package/manifest.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/developer/develop/package/manifest.md b/docs/developer/develop/package/manifest.md index ead29309c1..67b6a95f77 100644 --- a/docs/developer/develop/package/manifest.md +++ b/docs/developer/develop/package/manifest.md @@ -149,8 +149,8 @@ olaresManifest.version: "3.0.122" For shared applications, use version `v3`, which will be installed in the `-shared` namespace. For other applications, use `v1`. -:::info NOTE -`apiVersion: 'v2'` is used for shared applications on Olares OS version 1.12.5 and earlier. Support for this version will be gradually discontinued after the release of 1.12.6. Please migrate your shared applications to `v3` as soon as possible. +:::warning Deprecation notice +For new shared applications, use `apiVersion: 'v3'`. Existing shared applications should migrate to `v3` to ensure future compatibility because support for `v2` will be gradually discontinued after Olares OS 1.12.6. ::: ## Metadata @@ -1046,7 +1046,7 @@ When set to `true`, the application supports LLM Gateway calls. Mainly used for - Type: `map` - Optional -Declares the app's support for L2 overlay LAN discovery. When enabled, other apps can access this app via IP address in the LAN. +Declares the app's support for L2 overlay LAN discovery, enabling other apps to access it via an IP address in the local network. This is typically used for media servers or local network services. :::info Example ```yaml overlayGateway: