From 776848d2e2c8300a24f4cb9d30cb21f004498fe9 Mon Sep 17 00:00:00 2001 From: Meow33 Date: Thu, 5 Mar 2026 17:52:22 +0800 Subject: [PATCH] docs: add application environment variables (#2577) * docs: updated installation env vars and runtime values references * docs: fix content * docs: update content * Update table of contents, and refactored docs. * Fixed capitalization. * batch update to fix readability * refactored declarative env var * Updated translation. * Updated based on suggestions. * Updated based on suggestions. --------- Co-authored-by: yajing wang <413741312@qq.com> --- docs/.vitepress/developer.en.ts | 20 +- docs/.vitepress/developer.zh.ts | 19 +- docs/.vitepress/en.ts | 1 - docs/.vitepress/zh.ts | 5 +- docs/developer/develop/app-env-index.md | 25 ++ docs/developer/develop/app-env-vars.md | 199 ++++++++++++++++ .../develop/app-sys-injected-variables.md | 216 +++++++++++++++++ .../developer/develop/mw-integrate-with-es.md | 23 +- .../develop/mw-integrate-with-mariadb.md | 24 +- .../develop/mw-integrate-with-minio.md | 23 +- .../develop/mw-integrate-with-mongodb.md | 22 +- .../develop/mw-integrate-with-mysql.md | 22 +- .../developer/develop/mw-integrate-with-pg.md | 23 +- .../develop/mw-integrate-with-rabbitmq.md | 22 +- .../develop/mw-integrate-with-redis.md | 21 +- .../install/environment-variables.md | 213 +++++++++-------- docs/zh/developer/develop/app-env-index.md | 24 ++ docs/zh/developer/develop/app-env-vars.md | 197 ++++++++++++++++ .../develop/app-sys-injected-variables.md | 218 ++++++++++++++++++ .../developer/develop/mw-integrate-with-es.md | 20 +- .../develop/mw-integrate-with-mariadb.md | 20 +- .../develop/mw-integrate-with-minio.md | 20 +- .../develop/mw-integrate-with-mongodb.md | 20 +- .../develop/mw-integrate-with-mysql.md | 20 +- .../developer/develop/mw-integrate-with-pg.md | 21 +- .../develop/mw-integrate-with-rabbitmq.md | 20 +- .../develop/mw-integrate-with-redis.md | 18 +- .../install/environment-variables.md | 168 ++++++++------ 28 files changed, 1294 insertions(+), 350 deletions(-) create mode 100644 docs/developer/develop/app-env-index.md create mode 100644 docs/developer/develop/app-env-vars.md create mode 100644 docs/developer/develop/app-sys-injected-variables.md create mode 100644 docs/zh/developer/develop/app-env-index.md create mode 100644 docs/zh/developer/develop/app-env-vars.md create mode 100644 docs/zh/developer/develop/app-sys-injected-variables.md diff --git a/docs/.vitepress/developer.en.ts b/docs/.vitepress/developer.en.ts index f17d82a9d..f0211514a 100644 --- a/docs/.vitepress/developer.en.ts +++ b/docs/.vitepress/developer.en.ts @@ -213,12 +213,28 @@ export const developerSidebar: DefaultTheme.Sidebar = { // }, // ], // }, + { + text: "Application environment variables", + link: "/developer/develop/app-env-index", + collapsed: true, + items: [ + { + text: "Declarative environment variables", + link: "/developer/develop/app-env-vars", + collapsed: true, + }, + { + text: "System-injected variables", + link: "/developer/develop/app-sys-injected-variables", + }, + ] + }, { text: "Middleware", link: "/developer/develop/mw-overview", collapsed: true, items: [ - { + /*{ text: "Elasticsearch", collapsed: true, items :[ @@ -230,7 +246,7 @@ export const developerSidebar: DefaultTheme.Sidebar = { link: "/developer/develop/mw-view-es-data", }, ] - }, + },*/ { text: "Grafana", link :"/developer/develop/mw-view-grafana-data", diff --git a/docs/.vitepress/developer.zh.ts b/docs/.vitepress/developer.zh.ts index f260b4511..57f6ef868 100644 --- a/docs/.vitepress/developer.zh.ts +++ b/docs/.vitepress/developer.zh.ts @@ -228,12 +228,27 @@ export const developerSidebar: DefaultTheme.Sidebar = { // }, // ], // }, + { + text: "应用环境变量", + link: "/zh/developer/develop/app-env-index", + collapsed: true, + items: [ + { + text: "声明式环境变量", + link: "/zh/developer/develop/app-env-vars", + }, + { + text: "系统注入的运行时变量", + link: "/zh/developer/develop/app-sys-injected-variables", + }, + ] + }, { text: "中间件", link: "/zh/developer/develop/mw-overview", collapsed: true, items: [ - { + /*{ text: "Elasticsearch", collapsed: true, items :[ @@ -245,7 +260,7 @@ export const developerSidebar: DefaultTheme.Sidebar = { link: "zh/developer/develop/mw-view-es-data", }, ] - }, + },*/ { text: "Grafana", link: "zh/developer/develop/mw-view-grafana-data", diff --git a/docs/.vitepress/en.ts b/docs/.vitepress/en.ts index 7ddf2bb65..8494ef9e6 100644 --- a/docs/.vitepress/en.ts +++ b/docs/.vitepress/en.ts @@ -152,7 +152,6 @@ const side = { }, { text: "Olares applications", - link: "/manual/olares/", items: [ { text: "Desktop", link: "/manual/olares/desktop", }, { diff --git a/docs/.vitepress/zh.ts b/docs/.vitepress/zh.ts index 97ca2a823..4cf7b4a91 100644 --- a/docs/.vitepress/zh.ts +++ b/docs/.vitepress/zh.ts @@ -150,7 +150,6 @@ const side = { }, { "text": "Olares 应用", - "link": "/zh/manual/olares/", "items": [ { "text": "桌面", "link": "/zh/manual/olares/desktop" }, { @@ -466,10 +465,10 @@ const side = { text: "设置自定义域名", link: "/zh/manual/best-practices/set-custom-domain", }, - { + /*{ text: "使用 Wise 管理知识", link: "/zh/manual/best-practices/organize-content", - }, + },*/ { text: "安装多节点", link: "/zh/manual/best-practices/install-olares-multi-node", diff --git a/docs/developer/develop/app-env-index.md b/docs/developer/develop/app-env-index.md new file mode 100644 index 000000000..4fcacbad2 --- /dev/null +++ b/docs/developer/develop/app-env-index.md @@ -0,0 +1,25 @@ +--- +outline: [2, 3] +description: Learn how variables are injected during Olares app deployment, including declarative environment variables (.Values.olaresEnv) and system-injected runtime Helm values (.Values.*). +--- + +# Environment variables overview + +Olares apps use app-service to inject runtime context and configuration into the app's `values.yaml`. In Helm templates, you can reference these values via `.Values.*`. + +:::info Variables and Helm values +In this document, "variables" mainly refer to Helm values. They are not automatically passed into container environment variables. If you need them inside containers, explicitly map them to `env:` in your templates. +::: + +## How variables are injected + +Olares injects variables through two channels: + +- **Declarative environment variables**: The developer declares variables under `envs` in `OlaresManifest.yaml`. At deployment, app-service resolves and injects the values into `.Values.olaresEnv` in `values.yaml`. + +- **System-injected runtime variables**: Injected automatically by Olares at deployment time. No declaration is required, though some values are only available after you declare the relevant dependency, such as middleware. + +## Next steps + +1. [Declarative environment variables](app-env-vars.md): Field reference for the `envs` schema, including variable mapping and variable references. +2. [System-injected runtime variables](app-sys-injected-variables.md): Full reference for all system-injected runtime variables. \ No newline at end of file diff --git a/docs/developer/develop/app-env-vars.md b/docs/developer/develop/app-env-vars.md new file mode 100644 index 000000000..abc441b68 --- /dev/null +++ b/docs/developer/develop/app-env-vars.md @@ -0,0 +1,199 @@ +--- +outline: [2, 4] +description: Declare and validate app configuration via envs in `OlaresManifest.yaml`, and reference values in templates through `.Values.olaresEnv`. +--- +# Declarative environment variables + +Use `envs` in `OlaresManifest.yaml` to declare the configuration parameters, such as passwords, API endpoints, or feature flags. During deployment, app-service resolves the values and injects them into `.Values.olaresEnv` in `values.yaml`. Reference them in Helm templates as {{ .Values.olaresEnv.<envName> }}. + +## Variable sources + +Declarative variables can obtain values from configurations managed outside the application: + +- **System variables**: Environment variables defined at the Olares cluster level. They are set during system installation or centrally managed by administrators, and are shared by all users within the cluster. +- **User variables**: Environment variables defined at the Olares user level. They are managed individually by each user, and are isolated from one another within the same cluster. + +Applications cannot modify these variables directly. To use them, map the variable via the `valueFrom` field. + +## Map environment variables + +Both system environment variables and user environment variables use the same mapping mechanism via `valueFrom`. + +The following example maps the system variable `OLARES_SYSTEM_CDN_SERVICE` to an application variable `APP_CDN_ENDPOINT`: + +1. In `OlaresManifest.yaml`, declare an app variable under `envs` and set `valueFrom.envName` to the system variable name. + + ```yaml + # Map system variable OLARES_SYSTEM_CDN_SERVICE to app variable APP_CDN_ENDPOINT + olaresManifest.version: '0.10.0' + olaresManifest.type: app + + envs: + - envName: APP_CDN_ENDPOINT + required: true + applyOnChange: true + valueFrom: + envName: OLARES_SYSTEM_CDN_SERVICE + ``` + +2. In your Helm template, reference the app variable via `.Values.olaresEnv.`. + + ```yaml + # Use APP_CDN_ENDPOINT in a container environment variable + env: + - name: CDN_ENDPOINT + value: "{{ .Values.olaresEnv.APP_CDN_ENDPOINT }}" + ``` + +At deployment, app-service resolves the referenced variable and injects the value into `values.yaml`: + +```yaml +# Injected by app-service into values.yaml at deployment +olaresEnv: + APP_CDN_ENDPOINT: "https://cdn.olares.com" +``` + +For the full list of available environment variables, see [Variable references](#variable-references). + +## Declaration fields + +The following fields are available under each `envs` entry. + +### envName + +The name of the variable as injected into `values.yaml`. Reference it in templates as {{ .Values.olaresEnv.<envName> }}. + +### default + +The default value for the variable. Provided by the developer at authoring time. Users cannot modify it. Used when no value is supplied by the user or by `valueFrom`. + +### valueFrom + +Maps this variable to a system or user environment variable. When set, the current variable inherits all fields from the referenced variable (`type`, `editable`, `regex`, and so on). Any fields defined locally on the current variable are ignored. `default` and `options` have no effect when `valueFrom` is used. + +**Example**: map the app variable `APP_CDN_ENDPOINT` to the system variable `OLARES_SYSTEM_CDN_SERVICE`. + +```yaml +# Map app env APP_CDN_ENDPOINT to system variable OLARES_SYSTEM_CDN_SERVICE +envs: + - envName: APP_CDN_ENDPOINT + required: true + applyOnChange: true + valueFrom: + envName: OLARES_SYSTEM_CDN_SERVICE +``` + +### required + +Boolean. When `true`, the variable must have a value for installation to proceed. If no `default` is set, the user is prompted to enter one. After installation, the value cannot be set to empty. + +### editable + +Boolean. When `true`, the variable can be modified after installation. + +### applyOnChange + +Boolean. When `true`, changing this variable automatically restarts all apps or components that use it. When `false`, a change only takes effect after the app is upgraded or reinstalled. Stopping and starting the app manually has no effect. + +### type + +The expected type of the value. Used for validation before the value is accepted. Supported types: `int`, `bool`, `url`, `ip`, `domain`, `email`, `string`, `password`. + +### regex + +A regular expression the value must match. If validation fails, the value cannot be set and installation or upgrade may fail. + +### options + +Restricts the variable to a fixed list of allowed values. The system presents users with a selection UI. + +**Example**: a dropdown list of supported Windows versions for installation. + +```yaml +# Dropdown: title shown in UI, value stored internally +envs: + - envName: VERSION + options: + - title: "Windows 11 Pro" + value: "iso/Win11_24H2_English_x64.iso" + - title: "Windows 7 Ultimate" + value: "iso/win7_sp1_x64_1.iso" +``` + +### remoteOptions + +Loads the options list from a URL instead of defining it inline. The response body must be a JSON-encoded array in the same format as `options`. + +**Example**: options fetched from a remote endpoint. + +```yaml +# Options list fetched from remote URL at install time +envs: + - envName: VERSION + remoteOptions: https://app.cdn.olares.com/appstore/windows/version_options.json +``` + +### description + +A human-readable description of the variable's purpose and valid values. Displayed in the Olares interface. + +## Variable references + +### System environment variables + +The following table lists system-level environment variables that can be referenced via `valueFrom`. + +| Variable | Type | Default | Editable | Required | Description | +| --- | --- | --- | --- | --- | --- | +| `OLARES_SYSTEM_REMOTE_SERVICE` | `url` | `https://api.olares.com` | Yes | Yes | Remote service endpoint for Olares, such as Market and Olares Space. | +| `OLARES_SYSTEM_CDN_SERVICE` | `url` | `https://cdn.olares.com` | Yes | Yes | CDN endpoint for system resources. | +| `OLARES_SYSTEM_DOCKERHUB_SERVICE` | `url` | None | Yes | No | Docker Hub mirror or accelerator endpoint. | +| `OLARES_SYSTEM_ROOT_PATH` | `string` | `/olares` | No | Yes | Olares root directory path. | +| `OLARES_SYSTEM_ROOTFS_TYPE` | `string` | `fs` | No | Yes | Olares filesystem type. | +| `OLARES_SYSTEM_CUDA_VERSION` | `string` | None | No | No | Host CUDA version. | + +### User environment variables + +All user environment variables are editable by the user. + +#### User information + +| Variable | Type | Default | Description | +| --- | --- | --- | --- | +| `OLARES_USER_EMAIL` | `string` | None | User email address. | +| `OLARES_USER_USERNAME` | `string` | None | Username. | +| `OLARES_USER_PASSWORD` | `password` | None | User password. | +| `OLARES_USER_TIMEZONE` | `string` | None | User timezone. For example, `Asia/Shanghai`. | + +#### SMTP settings + +| Variable | Type | Default | Description | +| --- | --- | --- | --- | +| `OLARES_USER_SMTP_ENABLED` | `bool` | None | Whether to enable SMTP. | +| `OLARES_USER_SMTP_SERVER` | `domain` | None | SMTP server domain. | +| `OLARES_USER_SMTP_PORT` | `int` | None | SMTP server port. Typically `465` or `587`. | +| `OLARES_USER_SMTP_USERNAME` | `string` | None | SMTP username. | +| `OLARES_USER_SMTP_PASSWORD` | `password` | None | SMTP password or authorization code. | +| `OLARES_USER_SMTP_FROM_ADDRESS` | `email` | None | Sender email address. | +| `OLARES_USER_SMTP_SECURE` | `bool` | `"true"` | Whether to use a secure protocol. | +| `OLARES_USER_SMTP_USE_TLS` | `bool` | None | Whether to use TLS. | +| `OLARES_USER_SMTP_USE_SSL` | `bool` | None | Whether to use SSL. | +| `OLARES_USER_SMTP_SECURITY_PROTOCOLS` | `string` | None | Security protocol. Allowed values: `tls`, `ssl`, `starttls`, `none`. | + +#### Mirror and proxy endpoints + +| Variable | Type | Default | Description | +| --- | --- | --- | --- | +| `OLARES_USER_HUGGINGFACE_SERVICE` | `url` | `https://huggingface.co/` | Hugging Face service URL. | +| `OLARES_USER_HUGGINGFACE_TOKEN` | `string` | None | Hugging Face access token. | +| `OLARES_USER_PYPI_SERVICE` | `url` | `https://pypi.org/simple/` | PyPI mirror URL. | +| `OLARES_USER_GITHUB_SERVICE` | `url` | `https://github.com/` | GitHub mirror URL. | +| `OLARES_USER_GITHUB_TOKEN` | `string` | None | GitHub personal access token. | + +#### API keys + +| Variable | Type | Default | Description | +| --- | --- | --- | --- | +| `OLARES_USER_OPENAI_APIKEY` | `password` | None | OpenAI API key. | +| `OLARES_USER_CUSTOM_OPENAI_SERVICE` | `url` | None | Custom OpenAI-compatible service URL. | +| `OLARES_USER_CUSTOM_OPENAI_APIKEY` | `password` | None | API key for the custom OpenAI-compatible service. | diff --git a/docs/developer/develop/app-sys-injected-variables.md b/docs/developer/develop/app-sys-injected-variables.md new file mode 100644 index 000000000..7ca38c346 --- /dev/null +++ b/docs/developer/develop/app-sys-injected-variables.md @@ -0,0 +1,216 @@ +--- +outline: [2, 4] +description: Reference for runtime values injected into application `values.yaml` during Olares deployment. +--- + +# System-injected runtime values + +At deployment, Olares automatically injects a set of system-managed values into the app's `values.yaml`. These values are read-only and cover user identity, storage paths, cluster metadata, app dependencies, and middleware credentials. + +Because they are Helm values, they are not automatically available inside containers. To pass one into a container, map it explicitly under `env:` in your deployment template. + +## Use in your app + +Reference these values directly in your Helm templates, such as `deployment.yaml`. + +**Example**: pass the current username and Postgres host into container environment variables. + +```yaml +# Pass system-injected runtime values into container environment variables +spec: + containers: + - name: my-app + env: + - name: APP_USER + value: "{{ .Values.bfl.username }}" + - name: DB_HOST + value: "{{ .Values.postgres.host }}" +``` + +For the full list of available values, see [Value reference](#value-reference). + +## Value references + +The Type column describes the Helm value data type. It does not correspond to the `type` field in `OlaresManifest.yaml`. + +### User and identity + +| Value | Type | Description | +| --- | --- | --- | +| `.Values.bfl.username` | String | Current username. | +| `.Values.user.zone` | String | Current user's domain. | +| `.Values.admin` | String | Administrator username. | + +### Application and system information + +| Value | Type | Description | +| --- | --- | --- | +| `.Values.domain` | Map\ | App entrance URLs. Each entry maps an entrance name to its URL. | +| `.Values.sysVersion` | String | Current Olares system version. | +| `.Values.deviceName` | String | Device name. | +| `.Values.downloadCdnURL` | String | CDN address used for system resource downloads. | + +### Storage paths + +| Value | Type | Description | +| --- | --- | --- | +| `.Values.userspace.appData` | String | Cluster storage path for the app. Path: `/Data/`. | +| `.Values.userspace.appCache` | String | Node-local cache path for the app. Path: `/Cache/`. | +| `.Values.userspace.userData` | String | User's home data directory. Path: `/Files/Home/`. | +| `.Values.sharedlib` | String | User's external storage directory. Path: `/Files/External//`. | + +### Cluster hardware metadata + +| Value | Type | Description | +| --- | --- | --- | +| `.Values.cluster.arch` | String | Cluster CPU architecture, such as `amd64`. Mixed-architecture clusters are not supported. | +| `.Values.nodes` | List\ | Hardware metadata for each node in the cluster. | + +Each entry in `.Values.nodes` follows this structure: + +```json +// Single entry in the .Values.nodes list +[ + { + "cudaVersion": "12.9", + "cpu": [ + { + "coreNumber": 16, + "arch": "amd64", + "frequency": 4900000000, + "model": "151", + "modelName": "12th Gen Intel(R) Core(TM) i5-12600KF", + "vendor": "GenuineIntel" + } + ], + "memory": { + "total": 50351353856 + }, + "gpus": [ + { + "vendor": "NVIDIA", + "arch": "Ada Lovelace", + "model": "4060", + "memory": 17175674880, + "modelName": "NVIDIA GeForce RTX 4060 Ti" + } + ] + } +] +``` + +### Application dependencies + +When an app declares a dependency in `OlaresManifest.yaml`, Olares injects connection information into `values.yaml`. + +| Value | Type | Description | +| --- | --- | --- | +| `.Values.deps` | Map\ | Main entry host and port for each declared dependency. Keys follow the pattern `_host` and `_port`. | +| `.Values.svcs` | Map\ | All service hosts and ports for each declared dependency. Keys follow the pattern `_host` and `_port`. Port values are lists to support multiple ports per service. | + +**Example**: for a dependency with entry name `aserver` and service name `aserver-svc`. + +`.Values.deps`: +```json +{ + "aserver_host": "aserver-svc.", + "aserver_port": 80 +} +``` + +`.Values.svcs`: +```json +{ + "aserver-svc_host": "aserver-svc.", + "aserver-svc_port": [80] +} +``` + +### Middleware values + +Middleware values are injected only after you declare the middleware dependency in the `middleware` section of `OlaresManifest.yaml`. + +PostgreSQL and Redis are preinstalled. MongoDB, MinIO, RabbitMQ, MySQL and MariaDB must be installed separately before your app can use them. + +#### MariaDB + +See [Integrate with MariaDB](/developer/develop/mw-integrate-with-mariadb.md) for installation and configuration details. + +| Value | Type | Description | +| --- | --- | --- | +| `.Values.mariadb.host` | String | MariaDB host. | +| `.Values.mariadb.port` | Number | MariaDB port. | +| `.Values.mariadb.username` | String | MariaDB username. | +| `.Values.mariadb.password` | String | MariaDB password. | +| `.Values.mariadb.databases` | Map\ | Requested databases, keyed by database name. For example, a request for `app_db` is available at `.Values.mariadb.databases.app_db`. | + +#### MinIO + +See [Integrate with MinIO](/developer/develop/mw-integrate-with-minio.md) for installation and configuration details. + +| Value | Type | Description | +| --- | --- | --- | +| `.Values.minio.host` | String | MinIO service host. | +| `.Values.minio.port` | Number | MinIO service port. | +| `.Values.minio.username` | String | MinIO access key. | +| `.Values.minio.password` | String | MinIO secret key. | +| `.Values.minio.buckets` | Map\ | Requested buckets, keyed by bucket name. For example, a request for `mybucket` is available at `.Values.minio.buckets.mybucket`. | + +#### MongoDB + +See [Integrate with MongoDB](/developer/develop/mw-integrate-with-mongodb.md) for installation and configuration details. + +| Value | Type | Description | +| --- | --- | --- | +| `.Values.mongodb.host` | String | MongoDB host. | +| `.Values.mongodb.port` | Number | MongoDB port. | +| `.Values.mongodb.username` | String | MongoDB username. | +| `.Values.mongodb.password` | String | MongoDB password. | +| `.Values.mongodb.databases` | Map\ | Requested databases, keyed by database name. For example, a request for `app_db` is available at `.Values.mongodb.databases.app_db`. | + +#### MySQL + +See [Integrate with MySQL](/developer/develop/mw-integrate-with-mysql.md) for installation and configuration details. + +| Value | Type | Description | +| --- | --- | --- | +| `.Values.mysql.host` | String | MySQL host. | +| `.Values.mysql.port` | Number | MySQL port. | +| `.Values.mysql.username` | String | MySQL username. | +| `.Values.mysql.password` | String | MySQL password. | +| `.Values.mysql.databases` | Map\ | Requested databases, keyed by database name. For example, a request for `app_db` is available at `.Values.mysql.databases.app_db`. | + +#### PostgreSQL + +See [Integrate with PostgreSQL](/developer/develop/mw-integrate-with-pg.md) for installation and configuration details. + +| Value | Type | Description | +| --- | --- | --- | +| `.Values.postgres.host` | String | PostgreSQL host. | +| `.Values.postgres.port` | Number | PostgreSQL port. | +| `.Values.postgres.username` | String | PostgreSQL username. | +| `.Values.postgres.password` | String | PostgreSQL password. | +| `.Values.postgres.databases` | Map\ | Requested databases, keyed by database name. For example, a request for `app_db` is available at `.Values.postgres.databases.app_db`. | + +#### RabbitMQ + +See [Integrate with RabbitMQ](/developer/develop/mw-integrate-with-rabbitmq.md) for installation and configuration details. + +| Value | Type | Description | +| --- | --- | --- | +| `.Values.rabbitmq.host` | String | RabbitMQ host. | +| `.Values.rabbitmq.port` | Number | RabbitMQ port. | +| `.Values.rabbitmq.username` | String | RabbitMQ username. | +| `.Values.rabbitmq.password` | String | RabbitMQ password. | +| `.Values.rabbitmq.vhosts` | Map\ | Requested vhosts, keyed by vhost name. For example, a request for `myvhost` is available at `.Values.rabbitmq.vhosts.myvhost`. | + +#### Redis + +See [Integrate with Redis](/developer/develop/mw-integrate-with-redis.md) for installation and configuration details. + +| Value | Type | Description | +| --- | --- | --- | +| `.Values.redis.host` | String | Redis host. | +| `.Values.redis.port` | Number | Redis port. | +| `.Values.redis.password` | String | Redis password. | +| `.Values.redis.namespaces` | Map\ | Requested namespaces, keyed by namespace name. For example, a request for `app_ns` is available at `.Values.redis.namespaces.app_ns`. | diff --git a/docs/developer/develop/mw-integrate-with-es.md b/docs/developer/develop/mw-integrate-with-es.md index 65b227e86..df7876c7e 100644 --- a/docs/developer/develop/mw-integrate-with-es.md +++ b/docs/developer/develop/mw-integrate-with-es.md @@ -32,9 +32,8 @@ middleware: - name: aaa ``` -## Inject environment variables - -In your deployment YAML, map the injected `.Values.elasticsearch.*` fields to the environment variables your app uses. +## Map to environment variables +In your deployment YAML, map the injected `.Values.elasticsearch.*` fields to the container environment variables your app requires. **Example** ```yaml @@ -59,14 +58,14 @@ containers: value: "{{ .Values.elasticsearch.indexes.aaa }}" ``` -## Elasticsearch Values reference +## Elasticsearch values reference -Elasticsearch Values are predefined environment variables injected into `values.yaml` during deployment. They are system-managed and not user-editable. +Elasticsearch values are predefined runtime values injected into `values.yaml` during deployment. They are system-managed and not user-editable. -| Key | Type | Description | -|--|--|--| -|`.Values.elasticsearch.host`| String | Elasticsearch service host | -|`.Values.elasticsearch.port`| Number | Elasticsearch service port | -|`.Values.elasticsearch.username`| String | Elasticsearch username | -|`.Values.elasticsearch.password`| String | Elasticsearch password | -|`.Values.elasticsearch.indexes` | Map | The requested index name is used
as the key. For example, if you request `aaa`, the value is available at `.Values.elasticsearch.indexes.aaa`. | \ No newline at end of file +| Value | Type | Description | +| --- | --- | --- | +| `.Values.elasticsearch.host` | String | Elasticsearch service host. | +| `.Values.elasticsearch.port` | Number | Elasticsearch service port. | +| `.Values.elasticsearch.username` | String | Elasticsearch username. | +| `.Values.elasticsearch.password` | String | Elasticsearch password. | +| `.Values.elasticsearch.indexes` | Map\ | Requested indexes, keyed by index name. For example, a request for `aaa` is available at `.Values.elasticsearch.indexes.aaa`. | \ No newline at end of file diff --git a/docs/developer/develop/mw-integrate-with-mariadb.md b/docs/developer/develop/mw-integrate-with-mariadb.md index 5a01acc76..6a13f31de 100644 --- a/docs/developer/develop/mw-integrate-with-mariadb.md +++ b/docs/developer/develop/mw-integrate-with-mariadb.md @@ -31,9 +31,8 @@ middleware: - name: aaa ``` -## Inject environment variables - -In your deployment YAML, map the injected `.Values.mariadb.*` fields to the environment variables your app uses. +## Map to environment variables +In your deployment YAML, map the injected `.Values.mariadb.*` fields to the container environment variables your app requires. **Example** ```yaml @@ -59,14 +58,13 @@ containers: value: "{{ .Values.mariadb.databases.aaa }}" ``` -## MariaDB Values reference +## MariaDB values reference +MariaDB values are predefined runtime values injected into `values.yaml` during deployment. They are system-managed and not user-editable. -MariaDB Values are predefined environment variables injected into `values.yaml` during deployment. They are system-managed and not user-editable. - -| Key | Type | Description | -|--|--|--| -| `.Values.mariadb.host` | String | MariaDB database host | -| `.Values.mariadb.port` | Number | MariaDB database port | -| `.Values.mariadb.username` | String | MariaDB database username | -| `.Values.mariadb.password` | String | MariaDB database password | -| `.Values.mariadb.databases` | Map | The requested database name is used as the key.
For example, if you request `aaa`, the value is available at `.Values.mariadb.databases.aaa`. | \ No newline at end of file +| Value | Type | Description | +| --- | --- | --- | +| `.Values.mariadb.host` | String | MariaDB host. | +| `.Values.mariadb.port` | Number | MariaDB port. | +| `.Values.mariadb.username` | String | MariaDB username. | +| `.Values.mariadb.password` | String | MariaDB password. | +| `.Values.mariadb.databases` | Map\ | Requested databases, keyed by database name. For example, a request for `app_db` is available at `.Values.mariadb.databases.app_db`. | \ No newline at end of file diff --git a/docs/developer/develop/mw-integrate-with-minio.md b/docs/developer/develop/mw-integrate-with-minio.md index 175717fcb..9cddac97a 100644 --- a/docs/developer/develop/mw-integrate-with-minio.md +++ b/docs/developer/develop/mw-integrate-with-minio.md @@ -31,9 +31,8 @@ middleware: - name: mybucket ``` -## Inject environment variables - -In your deployment YAML, map the injected `.Values.minio.*` fields to the environment variables your app uses. +## Map to environment variables +In your deployment YAML, map the injected `.Values.minio.*` fields to the container environment variables your app requires. **Example** ```yaml @@ -60,14 +59,14 @@ containers: value: "{{ .Values.minio.buckets.mybucket }}" ``` -## MinIO Values reference +## MinIO values reference -MinIO Values are predefined environment variables injected into `values.yaml` during deployment. They are system-managed and not user-editable. +MinIO values are predefined runtime values injected into `values.yaml` during deployment. They are system-managed and not user-editable. -| Key | Type | Description | -|--|--|--| -| `.Values.minio.host` | String | MinIO service host | -| `.Values.minio.port` | Number | MinIO service port | -| `.Values.minio.username` | String | MinIO access key | -| `.Values.minio.password` | String | MinIO secret key | -| `.Values.minio.buckets` | Map | The requested bucket name is used as the key.
For example, if you request `mybucket`, the value is available at `.Values.minio.buckets.mybucket`. | \ No newline at end of file +| Value | Type | Description | +| --- | --- | --- | +| `.Values.minio.host` | String | MinIO service host. | +| `.Values.minio.port` | Number | MinIO service port. | +| `.Values.minio.username` | String | MinIO access key. | +| `.Values.minio.password` | String | MinIO secret key. | +| `.Values.minio.buckets` | Map\ | Requested buckets, keyed by bucket name. For example, a request for `mybucket` is available at `.Values.minio.buckets.mybucket`. | \ No newline at end of file diff --git a/docs/developer/develop/mw-integrate-with-mongodb.md b/docs/developer/develop/mw-integrate-with-mongodb.md index 8cd25c59b..b30c921d5 100644 --- a/docs/developer/develop/mw-integrate-with-mongodb.md +++ b/docs/developer/develop/mw-integrate-with-mongodb.md @@ -35,9 +35,9 @@ middleware: # Please make sure each line is a complete query. ``` -## Inject environment variables +## Map to environment variables -In your deployment YAML, map the injected `.Values.mongodb.*` fields to the environment variables your app uses. +In your deployment YAML, map the injected `.Values.mongodb.*` fields to the container environment variables your app requires. **Example** ```yaml @@ -63,14 +63,14 @@ containers: value: "{{ .Values.mongodb.databases.app_db }}" ``` -## MongoDB Values reference +## MongoDB values reference -MongoDB Values are predefined environment variables injected into `values.yaml` during deployment. They are system-managed and not user-editable. +MongoDB values are predefined runtime values injected into `values.yaml` during deployment. They are system-managed and not user-editable. -| Key | Type | Description | -|--|--|--| -| `.Values.mongodb.host` | String | MongoDB database host | -| `.Values.mongodb.port` | Number | MongoDB database port | -| `.Values.mongodb.username` | String | MongoDB database username | -| `.Values.mongodb.password` | String | MongoDB database password | -| `.Values.mongodb.databases` | Map | The requested database name is used as the key.
For example, if you request `app_db`, the value is available at `.Values.mongodb.databases.app_db`. | \ No newline at end of file +| Value | Type | Description | +| --- | --- | --- | +| `.Values.mongodb.host` | String | MongoDB host. | +| `.Values.mongodb.port` | Number | MongoDB port. | +| `.Values.mongodb.username` | String | MongoDB username. | +| `.Values.mongodb.password` | String | MongoDB password. | +| `.Values.mongodb.databases` | Map\ | Requested databases, keyed by database name. For example, a request for `app_db` is available at `.Values.mongodb.databases.app_db`. | \ No newline at end of file diff --git a/docs/developer/develop/mw-integrate-with-mysql.md b/docs/developer/develop/mw-integrate-with-mysql.md index 9d1805d53..15fab119d 100644 --- a/docs/developer/develop/mw-integrate-with-mysql.md +++ b/docs/developer/develop/mw-integrate-with-mysql.md @@ -31,9 +31,9 @@ middleware: - name: aaa ``` -## Inject environment variables +## Map to environment variables -In your deployment YAML, map the injected `.Values.mysql.*` fields to the environment variables your app uses. +In your deployment YAML, map the injected `.Values.mysql.*` fields to the container environment variables your app requires. **Example** ```yaml @@ -59,14 +59,14 @@ containers: value: "{{ .Values.mysql.databases.aaa }}" ``` -## MySQL Values reference +## MySQL values reference -MySQL Values are predefined environment variables injected into `values.yaml` during deployment. They are system-managed and not user-editable. +MySQL values are predefined runtime values injected into `values.yaml` during deployment. They are system-managed and not user-editable. -| Key | Type | Description | -|--|--|--| -| `.Values.mysql.host` | String | MySQL database host | -| `.Values.mysql.port` | Number | MySQL database port | -| `.Values.mysql.username` | String | MySQL database username | -| `.Values.mysql.password` | String | MySQL database password | -| `.Values.mysql.databases` | Map | The requested database name is used as the key.
For example, if you request `aaa`, the value is available at `.Values.mysql.databases.aaa`. | \ No newline at end of file +| Value | Type | Description | +| --- | --- | --- | +| `.Values.mysql.host` | String | MySQL host. | +| `.Values.mysql.port` | Number | MySQL port. | +| `.Values.mysql.username` | String | MySQL username. | +| `.Values.mysql.password` | String | MySQL password. | +| `.Values.mysql.databases` | Map\ | Requested databases, keyed by database name. For example, a request for `app_db` is available at `.Values.mysql.databases.app_db`. | \ No newline at end of file diff --git a/docs/developer/develop/mw-integrate-with-pg.md b/docs/developer/develop/mw-integrate-with-pg.md index f22c4694a..1e7611687 100644 --- a/docs/developer/develop/mw-integrate-with-pg.md +++ b/docs/developer/develop/mw-integrate-with-pg.md @@ -38,9 +38,9 @@ middleware: - COMMIT; ``` -## Inject environment variables +## Map to environment variables -In your deployment YAML, map the injected `.Values.postgres.*` fields to the environment variables your app uses. +In your deployment YAML, map the injected `.Values.postgres.*` fields to the container environment variables your app requires. **Example** ```yaml @@ -69,13 +69,14 @@ containers: value: {{ .Values.postgres.password }} ``` -## PostgreSQL Values reference +## PostgreSQL values reference -PostgreSQL Values are predefined environment variables injected into `values.yaml` during deployment. They are system-managed and not user-editable. -| Key | Type | Description | -|--|--|--| -| `.Values.postgres.host` | String | PostgreSQL database host | -| `.Values.postgres.port` | Number | PostgreSQL database port | -| `.Values.postgres.username` | String | PostgreSQL database username | -| `.Values.postgres.password` | String | PostgreSQL database password | -| `.Values.postgres.databases` | Map | The requested database name is used as the key.
For example, if you request `app_db`, the value is available at `.Values.postgres.databases.app_db`| \ No newline at end of file +PostgreSQL values are predefined runtime values injected into `values.yaml` during deployment. They are system-managed and not user-editable. + +| Value | Type | Description | +| --- | --- | --- | +| `.Values.postgres.host` | String | PostgreSQL host. | +| `.Values.postgres.port` | Number | PostgreSQL port. | +| `.Values.postgres.username` | String | PostgreSQL username. | +| `.Values.postgres.password` | String | PostgreSQL password. | +| `.Values.postgres.databases` | Map\ | Requested databases, keyed by database name. For example, a request for `app_db` is available at `.Values.postgres.databases.app_db`. | \ No newline at end of file diff --git a/docs/developer/develop/mw-integrate-with-rabbitmq.md b/docs/developer/develop/mw-integrate-with-rabbitmq.md index af126ebb5..2bc73cbe6 100644 --- a/docs/developer/develop/mw-integrate-with-rabbitmq.md +++ b/docs/developer/develop/mw-integrate-with-rabbitmq.md @@ -31,9 +31,9 @@ middleware: - name: aaa ``` -## Inject environment variables +## Map to environment variables -In your deployment YAML, map the injected `.Values.rabbitmq.*` fields to the environment variables your app uses. +In your deployment YAML, map the injected `.Values.rabbitmq.*` fields to the container environment variables your app requires. **Example** ```yaml @@ -78,14 +78,14 @@ portMQ := os.Getenv("RABBITMQ_PORT") url := fmt.Sprintf("amqp://%s:%s@%s:%s/%s", user, password, host, portMQ, vhost) ``` -## RabbitMQ Values reference +## RabbitMQ values reference -RabbitMQ Values are predefined environment variables injected into `values.yaml` during deployment. They are system-managed and not user-editable. +RabbitMQ values are predefined runtime values injected into `values.yaml` during deployment. They are system-managed and not user-editable. -| Key | Type | Description | -|--|--|--| -| `.Values.rabbitmq.host` | String | RabbitMQ service host | -| `.Values.rabbitmq.port` | Number | RabbitMQ service port | -| `.Values.rabbitmq.username` | String | RabbitMQ username | -| `.Values.rabbitmq.password` | String | RabbitMQ password | -| `.Values.rabbitmq.vhosts` | Map | The requested vhost name is used as the key.
For example, if you request `aaa`, the value is available at `.Values.rabbitmq.vhosts.aaa`. | \ No newline at end of file +| Value | Type | Description | +| --- | --- | --- | +| `.Values.rabbitmq.host` | String | RabbitMQ host. | +| `.Values.rabbitmq.port` | Number | RabbitMQ port. | +| `.Values.rabbitmq.username` | String | RabbitMQ username. | +| `.Values.rabbitmq.password` | String | RabbitMQ password. | +| `.Values.rabbitmq.vhosts` | Map\ | Requested vhosts, keyed by vhost name. For example, a request for `myvhost` is available at `.Values.rabbitmq.vhosts.myvhost`. | \ No newline at end of file diff --git a/docs/developer/develop/mw-integrate-with-redis.md b/docs/developer/develop/mw-integrate-with-redis.md index 14c5e0269..2e10fbde0 100644 --- a/docs/developer/develop/mw-integrate-with-redis.md +++ b/docs/developer/develop/mw-integrate-with-redis.md @@ -25,9 +25,9 @@ middleware: namespace: db0 ``` -## Inject environment variables +## Map to environment variables -In your deployment YAML, map the injected `.Values.redis.*` fields to the environment variables your app uses. +In your deployment YAML, map the injected `.Values.redis.*` fields to the container environment variables your app requires. **Example** ```yaml @@ -54,12 +54,13 @@ containers: value: {{ .Values.redis.namespaces. }} ``` -## Redis Values reference +## Redis values reference -Redis Values are predefined environment variables injected into `values.yaml` during deployment. They are system-managed and not user-editable. -| Key | Type | Description | -|--|--|--| -| `.Values.redis.host` | String | Redis service host | -| `.Values.redis.port` | Number | Redis service port | -| `.Values.redis.password`| String | Redis service password | -| `.Values.redis.namespaces` | Map | The requested namespace is used as the key.
For example, if you request `app_ns`, the value is available at `.Values.redis.namespaces.app_ns`. | +Redis values are predefined runtime values injected into `values.yaml` during deployment. They are system-managed and not user-editable. + +| Value | Type | Description | +| --- | --- | --- | +| `.Values.redis.host` | String | Redis host. | +| `.Values.redis.port` | Number | Redis port. | +| `.Values.redis.password` | String | Redis password. | +| `.Values.redis.namespaces` | Map\ | Requested namespaces, keyed by namespace name. For example, a request for `app_ns` is available at `.Values.redis.namespaces.app_ns`. | \ No newline at end of file diff --git a/docs/developer/install/environment-variables.md b/docs/developer/install/environment-variables.md index d0db37cc1..65335b5e9 100644 --- a/docs/developer/install/environment-variables.md +++ b/docs/developer/install/environment-variables.md @@ -15,128 +15,147 @@ To customize the installation process, you can set the environment variables bef export KUBE_TYPE=k8s \ && curl -sSfL https://olares.sh | bash - ``` + Or, if you have already downloaded the installation script `install.sh`: ```bash # Specify Kubernetes (k8s) instead of k3s export KUBE_TYPE=k8s && bash install.sh ``` -Both methods achieve the same result. The environment variable `KUBE_TYPE` will be passed to the script, and the script will use it to modify its behavior. + +Both methods achieve the same result. The environment variable `KUBE_TYPE` is passed to the installation script and modifies its behavior accordingly. ## Environment variables reference -The section lists all the environment variables, along with their default values, optional values, and descriptions. Configure them as needed. +The section lists all the environment variables, along with their default values, optional values, and descriptions. Configure them as needed. -### `CLOUDFLARE_ENABLE` -Specifies whether to enable the Cloudflare proxy. +### CLOUDFLARE_ENABLE + +Specifies whether to enable the Cloudflare proxy. +- **Valid values**: + - `0` (disable) + - `1` (enable) +- **Default**: `0` + +### FRP_AUTH_METHOD + +Sets the FRP authentication method. +- **Valid values**: + - `jws ` + - `token` (requires `FRP_AUTH_TOKEN`) + - (empty) – No authentication +- **Default**: `jws` + +### FRP_AUTH_TOKEN + +Specifies the token for FRP communication (required if `FRP_AUTH_METHOD=token`). +- **Valid values**: Any non-empty string +- **Default**: None + +### FRP_ENABLE + +Specifies whether to enable FRP for internal network tunneling. Requires additional FRP-related variables if using a custom server. +- **Valid values**: + - `0` (disable) + - `1` (enable) +- **Default**: `0` + +### FRP_PORT + +Specifies the FRP server's listening port. +- **Valid values**: An integer in the range `1–65535` +- **Default**: `7000` (if not set or set to `0`) + +### JUICEFS + +Installs [JuiceFS](https://juicefs.com/) alongside Olares. +- **Valid values**: `1` +- **Default**: None (does not install JuiceFS if not set) + +### KUBE_TYPE + +Determines the Kubernetes distribution to install. +- **Valid values**: + - `k8s`(full Kubernetes) + - `k3s` (lightweight Kubernetes) +- **Default**: `k3s` + +### LOCAL_GPU_ENABLE +Specifies whether to enable GPU support and install related drivers. +- **Valid values**: + - `0` (disable) + - `1` (enable) +- **Default**: `0` + +### LOCAL_GPU_SHARE + +Specifies whether to enable GPU sharing. Applies only if GPU is enabled. - **Valid values**: - - `0` (disable) - - `1` (enable) -- **Default**: `0` + - `0` (disable) + - `1` (enable) +- **Default**: `0` -### `FRP_AUTH_METHOD` -Sets the FRP authentication method. -- **Valid values**: - - `jws` - - `token` (requires `FRP_AUTH_TOKEN`) - - (empty) – No authentication -- **Default**: `jws` +### NVIDIA_CONTAINER_REPO_MIRROR -### `FRP_AUTH_TOKEN` -Specifies the token for FRP communication (required if `FRP_AUTH_METHOD=token`). -- **Valid values**: Any non-empty string -- **Default**: None +Specifies the APT repository mirror for installing NVIDIA Container Toolkit. +- **Valid values**: + - `nvidia.github.io` + - `mirrors.ustc.edu.cn` (recommended for better connectivity in mainland China) +- **Default**: `nvidia.github.io` -### `FRP_ENABLE` -Specifies whether to enable FRP for internal network tunneling. Requires additional FRP-related variables if using a custom server. -- **Valid values**: - - `0` (disable) - - `1` (enable) -- **Default**: `0` +### PREINSTALL -### `FRP_PORT` -Specifies the FRP server's listening port. -- **Valid values**: An integer in the range `1–65535` -- **Default**: `7000` (if not set or set to `0`) +Runs only the pre-installation phase (system dependency setup) without proceeding to the full Olares installation. +- **Valid values**: `1` +- **Default**: None (performs full installation if not set) -### `JUICEFS` -Installs [JuiceFS](https://juicefs.com/) alongside Olares. -- **Valid values**: `1` -- **Default**: None (does not install JuiceFS if not set) +### PUBLICLY_ACCESSIBLE -### `KUBE_TYPE` -Determines the Kubernetes distribution to install. -- **Valid values**: - - `k8s` (full Kubernetes) - - `k3s` (lightweight Kubernetes) -- **Default**: `k3s` - -### `LOCAL_GPU_ENABLE` -Specifies whether to enable GPU support and install related drivers. -- **Valid values**: - - `0` (disable) - - `1` (enable) -- **Default**: `0` - -### `LOCAL_GPU_SHARE` -Specifies whether to enable GPU sharing. Applies only if GPU is enabled. -- **Valid values**: - - `0` (disable) - - `1` (enable) -- **Default**: `0` - -### `NVIDIA_CONTAINER_REPO_MIRROR` -Specifies the APT repository mirror for installing NVIDIA Container Toolkit. -- **Valid values**: - - `nvidia.github.io` - - `mirrors.ustc.edu.cn` (recommended for better connectivity in mainland China) -- **Default**: `nvidia.github.io` - -### `PREINSTALL` -Runs only the pre-installation phase (system dependency setup) without proceeding to the full Olares installation. -- **Valid values**: `1` -- **Default**: None (performs full installation if not set) - -### `PUBLICLY_ACCESSIBLE` Explicitly specifies that this machine is accessible publicly on the internet, and a reverse proxy should not be used. - **Valid values**: - - `0` (false) - - `1` (true) -- **Default**: `0` + - `0` (false) + - `1` (true) +- **Default**: `0` +### REGISTRY_MIRRORS -### `REGISTRY_MIRRORS` -Specifies a custom Docker registry mirror for faster image pulls. -- **Valid values**: `https://mirrors.olares.com` or any other valid URL -- **Default**: `https://registry-1.docker.io` +Specifies a custom Docker registry mirror for faster image pulls. +- **Valid values**: `https://mirrors.olares.com` or any other valid URL +- **Default**: `https://registry-1.docker.io` -### `TERMINUS_IS_CLOUD_VERSION` -Marks the machine explicitly as a cloud instance. -- **Valid values**: `true` -- **Default**: None +### TERMINUS_IS_CLOUD_VERSION -### `TERMINUS_OS_DOMAINNAME` -Sets the domain name before installation to skip the interactive prompt. -- **Valid values**: Any valid domain name -- **Default**: None (prompts for domain name if not set) +Marks the machine explicitly as a cloud instance. +- **Valid values**: `true` +- **Default**: None -### `TERMINUS_OS_EMAIL` -Specifies the email address to use instead of a generated one. -- **Valid values**: Any valid email address -- **Default**: None (a temporary email is generated if not set) +### TERMINUS_OS_DOMAINNAME -### `TERMINUS_OS_PASSWORD` -Specifies the password to use instead of a generated one. -- **Valid values**: A valid password with 6–32 characters -- **Default**: A randomly generated 8-character password +Sets the domain name before installation to skip the interactive prompt. +- **Valid values**: Any valid domain name +- **Default**: None (prompts for domain name if not set) -### `TERMINUS_OS_USERNAME` -Specifies the username before installation to skip the interactive prompt. -- **Valid values**: Any valid username (2–250 characters, excluding reserved keywords) -- **Default**: None (prompts for username if not set) -- **Validation**: Reserved keywords include `user`, `system`, `space`, `default`, `os`, `kubesphere`, `kube`, `kubekey`, `kubernetes`, `gpu`, `tapr`, `bfl`, `bytetrade`, `project`, `pod` +### TERMINUS_OS_EMAIL -### `TOKEN_MAX_AGE` -Sets the maximum validity period for a token (in seconds). -- **Valid values**: Any integer (in seconds) +Specifies the email address to use instead of a generated one. +- **Valid values**: Any valid email address +- **Default**: None (a temporary email is generated if not set) + +### TERMINUS_OS_PASSWORD + +Specifies the password to use instead of a generated one. +- **Valid values**: A valid password with 6–32 characters +- **Default**: A randomly generated 8-character password + +### TERMINUS_OS_USERNAME + +Specifies the username before installation to skip the interactive prompt. +- **Valid values**: Any valid username (2–250 characters, excluding reserved keywords) +- **Default**: None (prompts for username if not set) +- **Validation**: Reserved keywords include `user`, `system`, `space`, `default`, `os`, `kubesphere`, `kube`, `kubekey`, `kubernetes`, `gpu`, `tapr`, `bfl`, `bytetrade`, `project`, `pod`. + +### TOKEN_MAX_AGE + +Sets the maximum validity period for a token (in seconds). +- **Valid values**: Any integer (in seconds) - **Default**: `31536000` (365 days) \ No newline at end of file diff --git a/docs/zh/developer/develop/app-env-index.md b/docs/zh/developer/develop/app-env-index.md new file mode 100644 index 000000000..acd8001b2 --- /dev/null +++ b/docs/zh/developer/develop/app-env-index.md @@ -0,0 +1,24 @@ +--- +outline: [2, 3] +description: 了解 Olares 应用在部署期间的变量注入机制：声明式环境变量（.Values.olaresEnv）与系统自动注入的运行时 Helm Values（.Values.*）。 +--- + +# 环境变量概览 + +Olares 应用通过 app-service 将运行时信息与配置项注入到应用的 `values.yaml` 中。应用在 Helm 模板中通过 `.Values.*` 引用这些值。 + +:::info 变量与 Helm 值 +本文提到的“变量”主要指 Helm 值。它们不会自动进入容器环境变量。如需在容器内使用，请在模板中显式映射到 `env:`。 +::: + +## 变量注入通道 + +Olares 通过两种通道注入变量： + +- **声明式环境变量**：开发者在 `OlaresManifest.yaml` 的 `envs` 下声明变量。在部署时，app-service 会解析这些值并将其注入到 `values.yaml` 的 `.Values.olaresEnv` 路径下。 +- **系统注入的运行时变量**：由 Olares 在部署时自动注入，无需声明。不过，某些值（例如中间件）只有在声明相关依赖后才可用。 + +## 下一步 + +1. [声明式环境变量](app-env-vars.md)：`envs` 字段说明、变量映射以及变量参考。 +2. [系统注入的运行时变量](app-sys-injected-variables.md)：所有系统注入运行时变量的完整参考。 \ No newline at end of file diff --git a/docs/zh/developer/develop/app-env-vars.md b/docs/zh/developer/develop/app-env-vars.md new file mode 100644 index 000000000..9be272ed4 --- /dev/null +++ b/docs/zh/developer/develop/app-env-vars.md @@ -0,0 +1,197 @@ +--- +outline: [2, 4] +description: 通过 `OlaresManifest.yaml` 中的 `envs` 声明并校验应用配置，并在模板中通过 `.Values.olaresEnv` 引用变量值。 +--- + +# 声明式环境变量 + +在 `OlaresManifest.yaml` 中使用 `envs` 字段来声明配置参数，例如密码、API 端点或功能开关。在部署过程中，app-service 会解析这些变量，并将其注入到 `values.yaml` 的 `.Values.olaresEnv` 中。你可以在 Helm 模板中通过 {{ .Values.olaresEnv.<envName> }} 引用。 + +## 变量来源 + +声明式变量可以从应用外部管理的配置中获取值： + +- **系统变量**：Olares 集群实例级别的环境变量，在系统安装时设置，或由管理员统一管理。集群中的所有用户共享。 +- **用户变量**：Olares 用户级别的环境变量，由用户自行管理。在同一集群中，不同用户的变量彼此独立。 + +应用本身无法直接修改这些变量。如需使用，需通过 `valueFrom` 字段映射。 + +## 映射环境变量 + +系统环境变量和用户环境变量都通过 `valueFrom` 使用相同的映射机制。 + +以下示例演示了如何将系统变量 `OLARES_SYSTEM_CDN_SERVICE` 映射为应用变量 `APP_CDN_ENDPOINT`： + +1. 在 `OlaresManifest.yaml` 中，在 `envs` 下声明一个应用变量，并将 `valueFrom.envName` 设置为系统变量名。 + + ```yaml + # 将系统变量 OLARES_SYSTEM_CDN_SERVICE 映射为应用变量 APP_CDN_ENDPOINT + olaresManifest.version: '0.10.0' + olaresManifest.type: app + + envs: + - envName: APP_CDN_ENDPOINT + required: true + applyOnChange: true + valueFrom: + envName: OLARES_SYSTEM_CDN_SERVICE + ``` + +2. 在 Helm 模板中，通过 `.Values.olaresEnv.` 引用该应用变量。 + + ```yaml + # 在容器环境变量中使用 APP_CDN_ENDPOINT + env: + - name: CDN_ENDPOINT + value: "{{ .Values.olaresEnv.APP_CDN_ENDPOINT }}" + ``` + +部署时，app-service 会解析引用的变量，并将值注入到 `values.yaml` 中： + +```yaml +# 由 app-service 在部署时注入 +olaresEnv: + APP_CDN_ENDPOINT: "https://cdn.olares.com" +``` + +可用环境变量的完整列表，请参阅[变量参考](#变量参考)。 + +## 声明字段 + +`envs` 列表中的每个条目支持以下字段。 + +### envName + +注入到 `values.yaml` 中的变量名。在模板中通过 {{ .Values.olaresEnv.<envName> }} 引用。 + +### default + +变量的默认值。由开发者在编写应用时提供。用户不可修改。当用户未提供值或未通过 `valueFrom` 引用时使用。 + +### valueFrom + +将当前变量映射到系统或用户环境变量。设置后，当前变量将继承所引用变量的所有字段（如 `type`、`editable`、`regex` 等）。当前变量本地定义的同名字段将被忽略。使用 `valueFrom` `时，default` 和 `options` 不生效。 + +**示例**： 将应用变量 `APP_CDN_ENDPOINT` 映射到系统变量 `OLARES_SYSTEM_CDN_SERVICE`。 + +```yaml +envs: + - envName: APP_CDN_ENDPOINT + required: true + applyOnChange: true + valueFrom: + envName: OLARES_SYSTEM_CDN_SERVICE +``` + +### required + +布尔值。为 `true` 时，安装必须提供该变量值。如果未设置 `default`，系统会提示用户输入。安装后该值不能设为空。 + +### editable + +布尔值。为 `true` 时，该变量在安装后允许修改。 + +### applyOnChange + +布尔值。为 `true` 时，修改该变量会自动重启使用该变量的应用或组件。为 `false` 时，修改仅在应用升级或重装后生效。手动停止和启动应用不会使其生效。 + +### type + +值的预期类型。用于在接受输入前进行校验。支持的类型包括：`int`、`bool`、`url`、`ip`、`domain`、`email`、`string`、`password`。 + +### regex + +值必须匹配的正则表达式。如果校验失败，则无法设置该值，且安装或升级可能失败。 + +### options + +将变量限制为固定的可选值列表。系统会在界面中提供选择界面。 + +**示例**：显示可安装的 Windows 版本的下拉列表。 + +```yaml +envs: + - envName: VERSION + options: + - title: "Windows 11 Pro" + value: "iso/Win11_24H2_English_x64.iso" + - title: "Windows 7 Ultimate" + value: "iso/win7_sp1_x64_1.iso" +``` + +### remoteOptions + +从 URL 加载选项列表，而不是在行内定义。响应体必须是与 `options` 格式相同的 JSON 编码数组。 + +**示例**：在安装时从远程端点获取选项列表。 + +```yaml +envs: + - envName: VERSION + remoteOptions: https://app.cdn.olares.com/appstore/windows/version_options.json +``` + +### description + +变量用途及有效取值范围的说明。显示在 Olares 界面中。 + +## 变量参考 + +### 系统环境变量 + +下表列出了可通过 `valueFrom` 引用的系统级环境变量。 + +| 变量 | 类型 | 默认值 | 可编辑 | 必填 | 描述 | +| --- | --- | --- | --- | --- | --- | +| `OLARES_SYSTEM_REMOTE_SERVICE` | `url` | `https://api.olares.com` | 是 | 是 | Olares 远程服务端点，例如应用商店与 Olares Space。 | +| `OLARES_SYSTEM_CDN_SERVICE` | `url` | `https://cdn.olares.com` | 是 | 是 | 系统资源 CDN 端点。 | +| `OLARES_SYSTEM_DOCKERHUB_SERVICE` | `url` | 无 | 是 | 否 | Docker Hub 镜像或加速端点。 | +| `OLARES_SYSTEM_ROOT_PATH` | `string` | `/olares` | 否 | 是 | Olares 根目录路径。 | +| `OLARES_SYSTEM_ROOTFS_TYPE` | `string` | `fs` | 否 | 是 | Olares 文件系统类型。 | +| `OLARES_SYSTEM_CUDA_VERSION` | `string` | 无 | 否 | 否 | 主机 CUDA 版本。 | + +### 用户环境变量 + +所有用户环境变量均可由用户编辑。 + +#### 用户信息 + +| 变量 | 类型 | 默认值 | 描述 | +| --- | --- | --- | --- | +| `OLARES_USER_EMAIL` | `string` | 无 | 用户邮箱地址。 | +| `OLARES_USER_USERNAME` | `string` | 无 | 用户名。 | +| `OLARES_USER_PASSWORD` | `password` | 无 | 用户密码。 | +| `OLARES_USER_TIMEZONE` | `string` | 无 | 用户时区，例如 `Asia/Shanghai`。 | + +#### SMTP 设置 + +| 变量 | 类型 | 默认值 | 描述 | +| --- | --- | --- | --- | +| `OLARES_USER_SMTP_ENABLED` | `bool` | 无 | 是否启用 SMTP。 | +| `OLARES_USER_SMTP_SERVER` | `domain` | 无 | SMTP 服务器域名。 | +| `OLARES_USER_SMTP_PORT` | `int` | 无 | SMTP 服务端口，通常为 `465` 或 `587`。 | +| `OLARES_USER_SMTP_USERNAME` | `string` | 无 | SMTP 用户名。 | +| `OLARES_USER_SMTP_PASSWORD` | `password` | 无 | SMTP 密码或授权码。 | +| `OLARES_USER_SMTP_FROM_ADDRESS` | `email` | 无 | 发件人邮箱地址。 | +| `OLARES_USER_SMTP_SECURE` | `bool` | `"true"` | 是否使用安全协议。 | +| `OLARES_USER_SMTP_USE_TLS` | `bool` | 无 | 是否使用 TLS。 | +| `OLARES_USER_SMTP_USE_SSL` | `bool` | 无 | 是否使用 SSL。 | +| `OLARES_USER_SMTP_SECURITY_PROTOCOLS` | `string` | 无 | 安全协议类型，可选值包括：`tls`、`ssl`、`starttls`、`none`。 | + +#### 镜像与代理端点 + +| 变量 | 类型 | 默认值 | 描述 | +| --- | --- | --- | --- | +| `OLARES_USER_HUGGINGFACE_SERVICE` | `url` | `https://huggingface.co/` | Hugging Face 服务地址。 | +| `OLARES_USER_HUGGINGFACE_TOKEN` | `string` | 无 | Hugging Face 访问令牌。 | +| `OLARES_USER_PYPI_SERVICE` | `url` | `https://pypi.org/simple/` | PyPI 镜像地址。 | +| `OLARES_USER_GITHUB_SERVICE` | `url` | `https://github.com/` | GitHub 镜像地址。 | +| `OLARES_USER_GITHUB_TOKEN` | `string` | 无 | GitHub 个人访问令牌。 | + +#### API keys + +| 变量 | 类型 | 默认值 | 描述 | +| --- | --- | --- | --- | +| `OLARES_USER_OPENAI_APIKEY` | `password` | 无 | OpenAI API key。 | +| `OLARES_USER_CUSTOM_OPENAI_SERVICE` | `url` | 无 | 自定义 OpenAI 兼容服务地址。 | +| `OLARES_USER_CUSTOM_OPENAI_APIKEY` | `password` | 无 | 自定义 OpenAI 兼容服务的 API key。 | \ No newline at end of file diff --git a/docs/zh/developer/develop/app-sys-injected-variables.md b/docs/zh/developer/develop/app-sys-injected-variables.md new file mode 100644 index 000000000..18e4e1a0d --- /dev/null +++ b/docs/zh/developer/develop/app-sys-injected-variables.md @@ -0,0 +1,218 @@ +--- +outline: [2, 4] +description: Olares 在应用部署期间注入到 `application values.yaml` 中的运行时变量。 +--- + +# 系统注入的运行时变量 + +在部署时，Olares 会自动向应用的 `values.yaml` 注入由系统管理的变量。这些变量为只读，涵盖用户身份、存储路径、集群元数据、应用依赖以及中间件凭据等信息。 + +由于它们属于 Helm values，因此不会自动传递到容器内部。如需在容器内部使用，请在部署模板中通过 `env:` 显式映射。 + +## 在应用中使用 + +你可以在 Helm 模板（如 `deployment.yaml`）中直接引用这些值。 + +**示例**：将当前用户名和 Postgres 主机地址传入容器环境变量。 + +```yaml +# 将系统注入的运行时变量传入容器环境变量 +spec: + containers: + - name: my-app + env: + - name: APP_USER + value: "{{ .Values.bfl.username }}" + - name: DB_HOST + value: "{{ .Values.postgres.host }}" +``` + +完整变量列表请参见[变量参考](#变量参考)。 + +## 变量参考 + +“类型”列描述的是 Helm value 的数据类型，并不对应 `OlaresManifest.yaml` 中的 `type` 字段。 + +### 用户与身份信息 +| 变量 | 类型 | 说明 | +| -- | -- | -- | +| `.Values.bfl.username` | String | 当前用户名。 | +| `.Values.user.zone` | String | 当前用户的域名。 | +| `.Values.admin` | String | 管理员用户名。 | + +### 应用与系统信息 + +| 变量 | 类型 | 说明 | +| -- | -- | -- | +| `.Values.domain` | Map | 应用入口地址映射，每个条目将入口名称映射为对应的 URL。 | +| `.Values.sysVersion` | String | 系统版本号。 | +| `.Values.deviceName` | String | 设备名称。 | +| `.Values.downloadCdnURL` | String | 系统资源下载使用的 CDN 地址。 | + +### 存储路径 + +| 变量 | 类型 | 说明 | +| -- | -- | -- | +| `.Values.userspace.appData` | String | 应用的集群存储路径，路径为 `/Data/`。 | +| `.Values.userspace.appCache` | String | 应用的节点本地缓存路径，路径为 `/Cache/`。 | +| `.Values.userspace.userData` | String | 用户数据目录，路径为 `/Files/Home/`。 | +| `.Values.sharedlib` | String | 用户外部存储目录，路径为 `/Files/External//`。 | + +### 集群硬件信息 + +集群硬件信息会在部署时注入到 `values.yaml` 中。 + +| 变量 | 类型 | 说明 | +| -- | -- | -- | +| `.Values.cluster.arch` | String | 集群 CPU 架构（例如 `amd64`）。Olares 目前不支持混合架构组成集群。 | +| `.Values.nodes` | List\ | 节点硬件元数据列表，注入在 `values["nodes"]`下。 | + +`.Values.nodes` 中每个条目结构如下： + +```json +[ + { + "cudaVersion": "12.9", + "cpu": [ + { + "coreNumber": 16, + "arch": "amd64", + "frequency": 4900000000, + "model": "151", + "modelName": "12th Gen Intel(R) Core(TM) i5-12600KF", + "vendor": "GenuineIntel" + } + ], + "memory": { + "total": 50351353856 + }, + "gpus": [ + { + "vendor": "NVIDIA", + "arch": "Ada Lovelace", + "model": "4060", + "memory": 17175674880, + "modelName": "NVIDIA GeForce RTX 4060 Ti" + } + ] + } +] +``` + +### 应用依赖 + +当应用在 `OlaresManifest.yaml` 中声明对其他应用的依赖时，Olares 会将连接信息注入到 `values.yaml`。 + +| 变量 | 类型 | 说明 | +| -- | -- | -- | +| `.Values.deps` | Map | 每个声明依赖的服务主机地址与端口。键名格式为 `_host` 与 `_port`。| +| `.Values.svcs` | Map | 每个声明依赖的所有服务主机地址与端口。键名格式为 `_host` 与 `_port`。端口值为列表类型，用于支持多端口服务。 | + +**示例**：依赖入口名为 `aserver`，服务名为 `aserver-svc`。 + +`.Values.deps`： + +```json +{ + "aserver_host": "aserver-svc.", + "aserver_port": 80 +} +``` + +`.Values.svcs`： + +```json +{ + "aserver-svc_host": "aserver-svc.", + "aserver-svc_port": [80] +} +``` + +### 中间件变量 + +仅当在 `OlaresManifest.yaml` 的 `middleware` 部分声明中间件依赖时，才会注入对应变量。 + +PostgreSQL 与 Redis 为预安装组件。MongoDB、MinIO、RabbitMQ、MySQL 和 MariaDB 需要单独安装后方可使用。 + +#### MariaDB + +安装与配置详情请参见[集成 MariaDB](/zh/developer/develop/mw-integrate-with-mariadb.md)。 + +| 变量 | 类型 | 说明 | +|--|--|--| +| `.Values.mariadb.host` | String | MariaDB 主机地址。 | +| `.Values.mariadb.port` | Number | MariaDB 端口。 | +| `.Values.mariadb.username` | String | MariaDB 用户名。 | +| `.Values.mariadb.password` | String | MariaDB 密码。 | +| `.Values.mariadb.databases` | Map | 请求的数据库集合，按数据库名为键。
例如申请 `app_db`，可通过 `.Values.mariadb.databases.app_db` 获取对应的值。 | + +#### MinIO + +安装与配置详情请参见[集成 MinIO](/zh/developer/develop/mw-integrate-with-minio.md)。 + +| 变量 | 类型 | 说明 | +|--|--|--| +| `.Values.minio.host` | String | MinIO 服务地址。 | +| `.Values.minio.port` | Number | MinIO 服务端口。 | +| `.Values.minio.username` | String | MinIO 访问密钥。 | +| `.Values.minio.password` | String | MinIO 密钥。 | +| `.Values.minio.buckets` | Map | 请求的存储桶集合，按桶名为键。例如申请 `mybucket`，可通过 `.Values.minio.buckets.mybucket` 获取对应的值。 | + +#### MongoDB + +安装与配置详情请参见[集成 MongoDB](/zh/developer/develop/mw-integrate-with-mongodb.md)。 + +| 变量 | 类型 | 说明 | +|--|--|--| +| `.Values.mongodb.host` | String | MongoDB 主机地址。 | +| `.Values.mongodb.port` | Number | MongoDB 端口。 | +| `.Values.mongodb.username` | String | MongoDB 用户名。 | +| `.Values.mongodb.password` | String | MongoDB 密码。 | +| `.Values.mongodb.databases` | Map | 请求的数据库集合，按数据库名为键。
例如申请 `app_db`，可通过 `.Values.mongodb.databases.app_db` 获取对应的值。 | + +#### MySQL + +安装与配置详情请参见[集成 MySQL](/zh/developer/develop/mw-integrate-with-mysql.md)。 + +| 变量 | 类型 | 说明 | +|--|--|--| +| `.Values.mysql.host` | String | MySQL 主机地址。 | +| `.Values.mysql.port` | Number | MySQL端口。 | +| `.Values.mysql.username` | String | MySQL 用户名。 | +| `.Values.mysql.password` | String | MySQL 密码。 | +| `.Values.mysql.databases` | Map | 请求的数据库集合，按数据库名为键。
例如申请 `app_db`，可通过 `.Values.mysql.databases.app_db` 获取对应的值。 | + +#### PostgreSQL + +安装与配置详情请参见[集成 PostgreSQL](/zh/developer/develop/mw-integrate-with-pg.md)。 + +| 变量 | 类型 | 说明 | +|--|--|--| +| `.Values.postgres.host` | String | PostgreSQL 主机地址。 | +| `.Values.postgres.port` | Number | PostgreSQL 端口。 | +| `.Values.postgres.username` | String | PostgreSQL 用户名。 | +| `.Values.postgres.password` | String | PostgreSQL 密码。 | +| `.Values.postgres.databases` | Map | 请求的数据库集合，按数据库名为键。例如，若申请的数据库名为 `app_db`，可通过 `.Values.postgres.databases.app_db`获取对应值。| + +#### RabbitMQ + +安装与配置详情请参见[集成 RabbitMQ](/zh/developer/develop/mw-integrate-with-rabbitmq.md)。 + +| 变量 | 类型 | 说明 | +|--|--|--| +| `.Values.rabbitmq.host` | String | RabbitMQ 主机地址。 | +| `.Values.rabbitmq.port` | Number | RabbitMQ 端口。 | +| `.Values.rabbitmq.username` | String | RabbitMQ 用户名。 | +| `.Values.rabbitmq.password` | String | RabbitMQ 密码。 | +| `.Values.rabbitmq.vhosts` | Map | 请求的虚拟主机集合，按名称为键。
例如申请 `myvhost`，可通过 `.Values.rabbitmq.vhosts.myvhost` 获取对应的值。 | + +#### Redis + +安装与配置详情请参见[集成 Redis](/zh/developer/develop/mw-integrate-with-redis.md)。 + +| 变量 | 类型 | 说明 | +|--|--|--| +| `.Values.redis.host` | String | Redis 主机地址。 | +| `.Values.redis.port` | Number | Redis 端口。 | +| `.Values.redis.password`| String | Redis 密码。 | +| `.Values.redis.namespaces` | Map | 请求的命名空间集合，按名称为键。
例如，请求 `app_ns`，可通过 `.Values.redis.namespaces.app_ns`获取对应值。 | \ No newline at end of file diff --git a/docs/zh/developer/develop/mw-integrate-with-es.md b/docs/zh/developer/develop/mw-integrate-with-es.md index 44fe79fb2..ccf3d98c0 100644 --- a/docs/zh/developer/develop/mw-integrate-with-es.md +++ b/docs/zh/developer/develop/mw-integrate-with-es.md @@ -31,9 +31,9 @@ middleware: - name: aaa ``` -## 注入环境变量 +## 映射环境变量 -在应用的部署 YAML 中，将系统注入的 `.Values.elasticsearch.*` 字段映射为应用所使用的环境变量。 +在应用的部署 YAML 中，将系统注入的 `.Values.elasticsearch.*` 字段映射为应用所需的环境变量。 **示例** ```yaml @@ -58,14 +58,14 @@ containers: value: "{{ .Values.elasticsearch.indexes.aaa }}" ``` -## Elasticsearch Values 参考 +## Elasticsearch 变量参考 -Elasticsearch Values 是在部署过程中由系统自动注入到 `values.yaml` 中的预定义变量。这些值由系统统一管理，用户无法自行修改。 +Elasticsearch 运行时变量会在部署过程中注入到 `values.yaml` 中。这些变量由系统统一管理，用户无法自行修改。 -| 键 | 类型 | 说明 | +| 变量 | 类型 | 说明 | |--|--|--| -| `.Values.elasticsearch.host` | String | Elasticsearch 服务地址 | -| `.Values.elasticsearch.port` | Number | Elasticsearch 服务端口 | -| `.Values.elasticsearch.username` | String | Elasticsearch 用户名 | -| `.Values.elasticsearch.password` | String | Elasticsearch 密码 | -| `.Values.elasticsearch.indexes` | Map | 以申请的索引名称作为键。例如申请 `aaa`，可通过 `.Values.elasticsearch.indexes.aaa` 获取对应的值。 | \ No newline at end of file +| `.Values.elasticsearch.host` | String | Elasticsearch 服务地址。 | +| `.Values.elasticsearch.port` | Number | Elasticsearch 服务端口。 | +| `.Values.elasticsearch.username` | String | Elasticsearch 用户名。 | +| `.Values.elasticsearch.password` | String | Elasticsearch 密码。 | +| `.Values.elasticsearch.indexes` | Map | 请求的索引集合，按索引名为键。例如申请 `aaa`，可通过 `.Values.elasticsearch.indexes.aaa` 获取对应的值。 | \ No newline at end of file diff --git a/docs/zh/developer/develop/mw-integrate-with-mariadb.md b/docs/zh/developer/develop/mw-integrate-with-mariadb.md index 297b31937..4165df27b 100644 --- a/docs/zh/developer/develop/mw-integrate-with-mariadb.md +++ b/docs/zh/developer/develop/mw-integrate-with-mariadb.md @@ -31,9 +31,9 @@ middleware: - name: aaa ``` -## 注入环境变量 +## 映射环境变量 -在应用的部署 YAML 中，将系统注入的 `.Values.mariadb.*` 字段映射为应用所使用的环境变量。 +在应用的部署 YAML 中，将系统注入的 `.Values.mariadb.*` 字段映射为应用所需的环境变量。 **示例** ```yaml @@ -59,14 +59,14 @@ containers: value: "{{ .Values.mariadb.databases.aaa }}" ``` -## MariaDB Values 参考 +## MariaDB 变量参考 -MariaDB Values 是在部署过程中由系统自动注入到 `values.yaml` 中的预定义变量。这些值由系统统一管理，用户无法自行修改。 +MariaDB 运运行时变量会在部署过程中注入到 `values.yaml` 中。这些变量由系统统一管理，用户无法自行修改。 -| 键 | 类型 | 说明 | +| 变量 | 类型 | 说明 | |--|--|--| -| `.Values.mariadb.host` | String | MariaDB 数据库地址 | -| `.Values.mariadb.port` | Number | MariaDB 数据库端口 | -| `.Values.mariadb.username` | String | MariaDB 数据库用户名 | -| `.Values.mariadb.password` | String | MariaDB 数据库密码 | -| `.Values.mariadb.databases` | Map | 以申请的数据库名作为键。
例如申请 `aaa`，可通过 `.Values.mariadb.databases.aaa` 获取对应的值。 | \ No newline at end of file +| `.Values.mariadb.host` | String | MariaDB 主机地址。 | +| `.Values.mariadb.port` | Number | MariaDB 端口。 | +| `.Values.mariadb.username` | String | MariaDB 用户名。 | +| `.Values.mariadb.password` | String | MariaDB 密码。 | +| `.Values.mariadb.databases` | Map | 请求的数据库集合，按数据库名为键。
例如申请 `app_db`，可通过 `.Values.mariadb.databases.app_db` 获取对应的值。 | \ No newline at end of file diff --git a/docs/zh/developer/develop/mw-integrate-with-minio.md b/docs/zh/developer/develop/mw-integrate-with-minio.md index e19110ef6..efa445c83 100644 --- a/docs/zh/developer/develop/mw-integrate-with-minio.md +++ b/docs/zh/developer/develop/mw-integrate-with-minio.md @@ -31,9 +31,9 @@ middleware: - name: mybucket ``` -## 注入环境变量 +## 映射环境变量 -在应用的部署 YAML 中，将系统注入的 `.Values.minio.*` 字段映射为应用所使用的环境变量。 +在应用的部署 YAML 中，将系统注入的 `.Values.minio.*` 字段映射为应用所需的环境变量。 **示例** ```yaml @@ -60,14 +60,14 @@ containers: value: "{{ .Values.minio.buckets.mybucket }}" ``` -## MinIO Values 参考 +## MinIO 变量参考 -MinIO Values 是在部署过程中由系统自动注入到 `values.yaml` 中的预定义变量。这些值由系统统一管理，用户无法自行修改。 +MinIO 运行时变量会在部署过程中注入到 `values.yaml` 中。这些变量由系统统一管理，用户无法自行修改。 -| 键 | 类型 | 说明 | +| 变量 | 类型 | 说明 | |--|--|--| -| `.Values.minio.host` | String | MinIO 服务地址 | -| `.Values.minio.port` | Number | MinIO 服务端口 | -| `.Values.minio.username` | String | MinIO 访问密钥（Access Key） | -| `.Values.minio.password` | String | MinIO 密钥（Secret Key） | -| `.Values.minio.buckets` | Map | 以申请的存储桶名称作为键。例如申请 `mybucket`，可通过 `.Values.minio.buckets.mybucket` 获取对应的值。 | \ No newline at end of file +| `.Values.minio.host` | String | MinIO 服务地址。 | +| `.Values.minio.port` | Number | MinIO 服务端口。 | +| `.Values.minio.username` | String | MinIO 访问密钥。 | +| `.Values.minio.password` | String | MinIO 密钥。 | +| `.Values.minio.buckets` | Map | 请求的存储桶集合，按桶名为键。例如申请 `mybucket`，可通过 `.Values.minio.buckets.mybucket` 获取对应的值。 | \ No newline at end of file diff --git a/docs/zh/developer/develop/mw-integrate-with-mongodb.md b/docs/zh/developer/develop/mw-integrate-with-mongodb.md index 33628bec2..44092b63a 100644 --- a/docs/zh/developer/develop/mw-integrate-with-mongodb.md +++ b/docs/zh/developer/develop/mw-integrate-with-mongodb.md @@ -35,9 +35,9 @@ middleware: # 请确保每一行都是完整的查询语句。 ``` -## 注入环境变量 +## 映射环境变量 -在应用的部署 YAML 中，将系统注入的 `.Values.mongodb.*` 字段映射为应用所使用的环境变量。 +在应用的部署 YAML 中，将系统注入的 `.Values.mongodb.*` 字段映射为应用所需的环境变量。 **示例** ```yaml @@ -63,14 +63,14 @@ containers: value: "{{ .Values.mongodb.databases.app_db }}" ``` -## MongoDB Values 参考 +## MongoDB 变量参考 -MongoDB Values 是在部署过程中自动注入到 `values.yaml` 中的预定义变量，由系统统一管理，用户不可手动修改。 +MongoDB 运行时变量会在部署过程中注入到 `values.yaml` 中。这些变量由系统统一管理，用户无法自行修改。 -| 键 | 类型 | 说明 | +| 变量 | 类型 | 说明 | |--|--|--| -| `.Values.mongodb.host` | String | MongoDB 数据库地址 | -| `.Values.mongodb.port` | Number | MongoDB 数据库端口 | -| `.Values.mongodb.username` | String | MongoDB 数据库用户名 | -| `.Values.mongodb.password` | String | MongoDB 数据库密码 | -| `.Values.mongodb.databases` | Map | 以申请的数据库名作为键。
例如申请 `app_db`，可通过 `.Values.mongodb.databases.app_db` 获取对应的值。 | \ No newline at end of file +| `.Values.mongodb.host` | String | MongoDB 主机地址。 | +| `.Values.mongodb.port` | Number | MongoDB 端口。 | +| `.Values.mongodb.username` | String | MongoDB 用户名。 | +| `.Values.mongodb.password` | String | MongoDB 密码。 | +| `.Values.mongodb.databases` | Map | 请求的数据库集合，按数据库名为键。
例如申请 `app_db`，可通过 `.Values.mongodb.databases.app_db` 获取对应的值。 | \ No newline at end of file diff --git a/docs/zh/developer/develop/mw-integrate-with-mysql.md b/docs/zh/developer/develop/mw-integrate-with-mysql.md index 736e14486..512a53477 100644 --- a/docs/zh/developer/develop/mw-integrate-with-mysql.md +++ b/docs/zh/developer/develop/mw-integrate-with-mysql.md @@ -31,9 +31,9 @@ middleware: - name: aaa ``` -## 注入环境变量 +## 映射环境变量 -在应用的部署 YAML 中，将系统注入的 `.Values.mysql.*` 字段映射为应用所使用的环境变量。 +在应用的部署 YAML 中，将系统注入的 `.Values.mysql.*` 字段映射为应用所需的环境变量。 **示例** ```yaml @@ -59,14 +59,14 @@ containers: value: "{{ .Values.mysql.databases.aaa }}" ``` -## MySQL Values 参考 +## MySQL 变量参考 -MySQL Values 是在部署过程中由系统自动注入到 `values.yaml` 中的预定义变量。这些值由系统统一管理，用户无法自行修改。 +MySQL 运行时变量会在部署过程中注入到 `values.yaml` 中。这些变量由系统统一管理，用户无法自行修改。 -| 键 | 类型 | 说明 | +| 变量 | 类型 | 说明 | |--|--|--| -| `.Values.mysql.host` | String | MySQL 数据库地址 | -| `.Values.mysql.port` | Number | MySQL 数据库端口 | -| `.Values.mysql.username` | String | MySQL 数据库用户名 | -| `.Values.mysql.password` | String | MySQL 数据库密码 | -| `.Values.mysql.databases` | Map | 以申请的数据库名作为键。
例如申请 `aaa`，可通过 `.Values.mysql.databases.aaa` 获取对应的值。 | \ No newline at end of file +| `.Values.mysql.host` | String | MySQL 主机地址。 | +| `.Values.mysql.port` | Number | MySQL端口。 | +| `.Values.mysql.username` | String | MySQL 用户名。 | +| `.Values.mysql.password` | String | MySQL 密码。 | +| `.Values.mysql.databases` | Map | 请求的数据库集合，按数据库名为键。
例如申请 `app_db`，可通过 `.Values.mysql.databases.app_db` 获取对应的值。 | \ No newline at end of file diff --git a/docs/zh/developer/develop/mw-integrate-with-pg.md b/docs/zh/developer/develop/mw-integrate-with-pg.md index 99b32978f..bb5ca9f3d 100644 --- a/docs/zh/developer/develop/mw-integrate-with-pg.md +++ b/docs/zh/developer/develop/mw-integrate-with-pg.md @@ -38,9 +38,9 @@ middleware: - COMMIT; ``` -## 注入环境变量 +## 映射环境变量 -在应用的部署 YAML 中，将系统注入的 `.Values.postgres.*` 字段映射为应用所使用的环境变量。 +在应用的部署 YAML 中，将系统注入的 `.Values.postgres.*` 字段映射为应用所需的环境变量。 **示例** ```yaml @@ -70,13 +70,14 @@ containers: value: {{ .Values.postgres.password }} ``` -## PostgreSQL Values 参考 -PostgreSQL Values 是在部署过程中由系统自动注入到 `values.yaml` 中的预定义变量。这些值由系统统一管理，用户无法自行修改。 +## PostgreSQL 变量参考 -| 键 | 类型 | 说明 | +PostgreSQL 运行时变量会在部署过程中注入到 `values.yaml` 中。这些变量由系统统一管理，用户无法自行修改。 + +| 变量 | 类型 | 说明 | |--|--|--| -| `.Values.postgres.host` | String | PostgreSQL 数据库地址 | -| `.Values.postgres.port` | Number | PostgreSQL 数据库端口 | -| `.Values.postgres.username` | String | PostgreSQL 数据库用户名 | -| `.Values.postgres.password` | String | PostgreSQL 数据库密码 | -| `.Values.postgres.databases` | Map | PostgreSQL 数据库以申请的数据库名作为键。例如，若申请的数据库名为 `app_db`，可通过 `.Values.postgres.databases.app_db`获取对应值。| \ No newline at end of file +| `.Values.postgres.host` | String | PostgreSQL 主机地址。 | +| `.Values.postgres.port` | Number | PostgreSQL 端口。 | +| `.Values.postgres.username` | String | PostgreSQL 用户名。 | +| `.Values.postgres.password` | String | PostgreSQL 密码。 | +| `.Values.postgres.databases` | Map | 请求的数据库集合，按数据库名为键。例如，若申请的数据库名为 `app_db`，可通过 `.Values.postgres.databases.app_db`获取对应值。| \ No newline at end of file diff --git a/docs/zh/developer/develop/mw-integrate-with-rabbitmq.md b/docs/zh/developer/develop/mw-integrate-with-rabbitmq.md index 6ca2c7ea1..ee6583863 100644 --- a/docs/zh/developer/develop/mw-integrate-with-rabbitmq.md +++ b/docs/zh/developer/develop/mw-integrate-with-rabbitmq.md @@ -31,9 +31,9 @@ middleware: - name: aaa ``` -## 注入环境变量 +## 映射环境变量 -在应用的部署 YAML 中，将系统注入的 `.Values.rabbitmq.*` 字段映射为应用所使用的环境变量。 +在应用的部署 YAML 中，将系统注入的 `.Values.rabbitmq.*` 字段映射为应用所需的环境变量。 **示例** ```yaml @@ -78,14 +78,14 @@ portMQ := os.Getenv("RABBITMQ_PORT") url := fmt.Sprintf("amqp://%s:%s@%s:%s/%s", user, password, host, portMQ, vhost) ``` -## RabbitMQ Values 参考 +## RabbitMQ 变量参考 -RabbitMQ Values 是在部署过程中自动注入到 `values.yaml` 中的预定义变量，由系统统一管理，用户不可手动修改。 +RabbitMQ 运行时变量会在部署过程中注入到 `values.yaml` 中。这些变量由系统统一管理，用户无法自行修改。 -| 键 | 类型 | 说明 | +| 变量 | 类型 | 说明 | |--|--|--| -| `.Values.rabbitmq.host` | String | RabbitMQ 服务地址 | -| `.Values.rabbitmq.port` | Number | RabbitMQ 服务端口 | -| `.Values.rabbitmq.username` | String | RabbitMQ 用户名 | -| `.Values.rabbitmq.password` | String | RabbitMQ 密码 | -| `.Values.rabbitmq.vhosts` | Map | 以申请的 vhost 名作为键。
例如申请 `aaa`，可通过 `.Values.rabbitmq.vhosts.aaa` 获取对应的值。 | \ No newline at end of file +| `.Values.rabbitmq.host` | String | RabbitMQ 主机地址。 | +| `.Values.rabbitmq.port` | Number | RabbitMQ 端口。 | +| `.Values.rabbitmq.username` | String | RabbitMQ 用户名。 | +| `.Values.rabbitmq.password` | String | RabbitMQ 密码。 | +| `.Values.rabbitmq.vhosts` | Map | 请求的虚拟主机集合，按名称为键。
例如申请 `myvhost`，可通过 `.Values.rabbitmq.vhosts.myvhost` 获取对应的值。 | \ No newline at end of file diff --git a/docs/zh/developer/develop/mw-integrate-with-redis.md b/docs/zh/developer/develop/mw-integrate-with-redis.md index 62a38d4b8..7f4c47452 100644 --- a/docs/zh/developer/develop/mw-integrate-with-redis.md +++ b/docs/zh/developer/develop/mw-integrate-with-redis.md @@ -25,9 +25,9 @@ middleware: namespace: db0 ``` -## 注入环境变量 +## 映射环境变量 -在应用的部署 YAML 中，将系统注入的 `.Values.redis.*` 字段映射为应用所使用的环境变量。 +在应用的部署 YAML 中，将系统注入的 `.Values.redis.*` 字段映射为应用所需的环境变量。 **示例** ```yaml @@ -54,13 +54,13 @@ containers: value: {{ .Values.redis.namespaces. }} ``` -## Redis Values 参考 +## Redis 变量参考 -Redis Values 是在部署过程中由系统自动注入到 `values.yaml` 中的预定义变量。这些值由系统统一管理，用户无法自行修改。 +Redis 运行时变量会在部署过程中注入到 `values.yaml` 中。这些变量由系统统一管理，用户无法自行修改。 -| 键 | 类型 | 说明 | +| 变量 | 类型 | 说明 | |--|--|--| -| `.Values.redis.host` | String | Redis 数据库地址 | -| `.Values.redis.port` | Number | Redis 数据库端口 | -| `.Values.redis.password`| String | Redis 数据库密码 | -| `.Values.redis.namespaces` | Map | Redis 命名空间名称，以申请命名空间作为键。例如，若申请的命名空间名为 `app_ns`，可通过 `.Values.redis.namespaces.app_ns`获取对应值。 | +| `.Values.redis.host` | String | Redis 主机地址。 | +| `.Values.redis.port` | Number | Redis 端口。 | +| `.Values.redis.password`| String | Redis 密码。 | +| `.Values.redis.namespaces` | Map | 请求的命名空间集合，按名称为键。
例如，请求 `app_ns`，可通过 `.Values.redis.namespaces.app_ns`获取对应值。 | diff --git a/docs/zh/developer/install/environment-variables.md b/docs/zh/developer/install/environment-variables.md index 6ee0d67f9..5cdc2b322 100644 --- a/docs/zh/developer/install/environment-variables.md +++ b/docs/zh/developer/install/environment-variables.md @@ -1,6 +1,6 @@ --- outline: [2, 3] -description: Olares 提供的环境变量，用于自定义网络、认证、GPU 支持等功能。包含配置示例和详细规格说明。 +description: Olares 提供了丰富的环境变量以满足定制化安装需求。通过修改这些变量，你可以覆盖默认安装设置，实现灵活的个性化安装配置。 --- # Olares 环境变量参考 @@ -22,7 +22,7 @@ export KUBE_TYPE=k8s \ # 指定使用完整的 Kubernetes (k8s) 而非轻量级 k3s export KUBE_TYPE=k8s && bash install.sh ``` -两种方式的执行效果相同：环境变量 `KUBE_TYPE` 会传递给安装脚本，脚本会根据这个变量来调整其安装逻辑。 +两种方式的执行效果相同。环境变量 `KUBE_TYPE` 会传递给安装脚本，并据此修改安装行为。 当然，你也可以组合多个环境变量来实现更灵活的自定义效果。例如中国大陆的用户通过`cn.olares.sh`获取的安装脚本，就是一个在默认安装脚本之上设置了一系列环境变量的脚本： @@ -45,115 +45,133 @@ curl -sSfL https://olares.sh | bash 以下列出了安装脚本所支持的环境变量及其默认值、可选值和说明。请根据具体需求进行配置。 -### `CLOUDFLARE_ENABLE` -指定是否启用 Cloudflare 代理。 -- **可选值**： - - `0`（禁用） - - `1`（启用） -- **默认值**：`0`（禁用） +### CLOUDFLARE_ENABLE + +指定是否启用 Cloudflare 代理。 +- **可选值**： + - `0`（禁用） + - `1`（启用） +- **默认值**：`0` + +### FRP_AUTH_METHOD -### `FRP_AUTH_METHOD` 设置 FRP 的认证方式。 - **可选值**： - - `jws` - - `token`（需要设置 `FRP_AUTH_TOKEN`） - - *（空字符串）* —— 不使用认证 -- **默认值**：`jws` + - `jws ` + - `token`（需要设置`FRP_AUTH_TOKEN`） + - *（空字符串）* —— 不使用认证 +- **默认值**：`jws` -### `FRP_AUTH_TOKEN` -当 `FRP_AUTH_METHOD=token` 时，用于指定服务器通信所需的 Token。 -- **可选值**：任意非空字符串 +### FRP_AUTH_TOKEN + +当 `FRP_AUTH_METHOD=token` 时，用于指定服务器通信所需的 Token。 +- **可选值**：任意非空字符串 - **默认值**：无 -### `FRP_ENABLE` -指定是否启用 FRP 内网穿透。如果使用自定义 FRP 服务器，还需额外设置相关变量。 -- **可选值**： - - `0`（禁用） - - `1`（启用） -- **默认值**：`0`（禁用） +### FRP_ENABLE + +指定是否启用 FRP 内网穿透。如果使用自定义 FRP 服务器，还需额外设置相关变量。 +- **可选值**： + - `0`（禁用） + - `1`（启用） +- **默认值**：`0` + +### FRP_PORT -### `FRP_PORT` 设置 FRP 服务端监听端口。 -- **可选值**：整数范围 `1～65535` +- **可选值**：整数范围 `1–65535` - **默认值**：未设置或设为 `0` 时默认为 `7000` -### `JUICEFS` -随 Olares 一起安装 [JuiceFS](https://juicefs.com/)。 -- **可选值**：`1` +### JUICEFS + +随 Olares 一起安装 [JuiceFS]。 +- **可选值**：`1` - **默认值**：无（若不设置则不安装 JuiceFS） -### `KUBE_TYPE` -指定要使用的 Kubernetes 发行版。 -- **可选值**： - - `k8s`（完整的 Kubernetes） - - `k3s`（Kubernetes 的轻量级发行版） -- **默认值**：`k3s` +### KUBE_TYPE -### `LOCAL_GPU_ENABLE` -指定是否启用 GPU 并安装相关驱动。 +指定要使用的 Kubernetes 发行版。 - **可选值**： - - `0`（禁用） - - `1`（启用） -- **默认值**：`0`（禁用） + - `k8s`（完整的 Kubernetes） + - `k3s`（Kubernetes 的轻量级发行版） +- **默认值**：`k3s` -### `LOCAL_GPU_SHARE` -指定是否启用 GPU 共享功能。仅在已启用 GPU 时生效。 +### LOCAL_GPU_ENABLE +指定是否启用 GPU 并安装相关驱动。 - **可选值**： - - `0`（禁用） - - `1`（启用） -- **默认值**：`0`（禁用） + - `0`（禁用） + - `1`（启用） +- **默认值**：`0` + +### LOCAL_GPU_SHARE + +指定是否启用 GPU 共享功能。仅在已启用 GPU 时生效。 +- **Valid values**: + - `0`（禁用） + - `1`（启用） +- **默认值**：`0` + +### NVIDIA_CONTAINER_REPO_MIRROR -### `NVIDIA_CONTAINER_REPO_MIRROR` 配置 `nvidia-container-toolkit` 的 APT 安装镜像源。 - **可选值**： - - `nvidia.github.io` - - `mirrors.ustc.edu.cn`（推荐中国大陆用户使用，连接性更好） -- **默认值**：`nvidia.github.io` + - `nvidia.github.io` + - `mirrors.ustc.edu.cn`（推荐中国大陆用户使用，连接性更好） +- **默认值**：`nvidia.github.io` + +### PREINSTALL -### `PREINSTALL` 仅执行预安装阶段（系统依赖配置），不进行完整的 Olares 安装。 -- **可选值**：`1` +- **可选值**：`1` - **默认值**：无（若不设置则执行完整安装） -### `PUBLICLY_ACCESSIBLE` +### PUBLICLY_ACCESSIBLE + 明确指定该机器可以在互联网上公开访问，同时不设置反向代理。 -- **可选值**： - - `0` (否) - - `1` (是) -- **默认值**: `0` +- **可选值**： + - `0`（否） + - `1`（是） +- **默认值**：`0` + +### REGISTRY_MIRRORS -### `REGISTRY_MIRRORS` 设置 Docker 镜像加速地址。 -- **可选值**：`https://mirrors.olares.cn` 或其他镜像源地址 -- **默认值**：`https://registry-1.docker.io` +- **可选值**：`https://mirrors.olares.com`或其他镜像源地址 +- **默认值**：`https://registry-1.docker.io` -### `TERMINUS_IS_CLOUD_VERSION` -明确将此机器标记为云端实例（cloud instance）。 -- **可选值**：`true` +### TERMINUS_IS_CLOUD_VERSION + +明确将此机器标记为云端实例（cloud instance）。 +- **可选值**：`true` - **默认值**：无 -### `TERMINUS_OS_DOMAINNAME` -在安装前预先设置域名，会跳过安装过程中的交互式提示。 -- **可选值**：任意有效域名 +### TERMINUS_OS_DOMAINNAME + +在安装前预先设置域名，会跳过安装过程中的交互式提示。 +- **可选值**：任意有效域名 - **默认值**：无（若不设置则会提示输入域名） -### `TERMINUS_OS_EMAIL` -在安装前预先设置邮箱地址，会跳过安装过程中的交互式提示。 -- **可选值**：任意有效邮箱地址 +### TERMINUS_OS_EMAIL + +在安装前预先设置邮箱地址，会跳过安装过程中的交互式提示。 +- **可选值**：任意有效邮箱地址 - **默认值**：无（若不设置则自动生成临时邮箱） -### `TERMINUS_OS_PASSWORD` -在安装前预先设置密码，会跳过安装过程中的交互式提示。 -- **可选值**：6～32 个字符的有效密码 -- **默认值**：随机生成 8 位密码 +### TERMINUS_OS_PASSWORD + +在安装前预先设置密码，会跳过安装过程中的交互式提示。 +- **可选值**：6～32 个字符的有效密码 +- **默认值**：随机生成 8 位密码 + +### TERMINUS_OS_USERNAME -### `TERMINUS_OS_USERNAME` 在安装前预先设置用户名，会跳过安装过程中的对应交互式提示。 -- **可选值**：任意有效用户名（长度 2～250，且不与保留关键词冲突） +- **可选值**：任意有效用户名（长度 2～250，且不与保留关键词冲突） - **默认值**：无（若不设置则会提示输入用户名） - **验证规则**：保留关键词包括 `user`、`system`、`space`、`default`、`os`、`kubesphere`、`kube`、`kubekey`、`kubernetes`、`gpu`、`tapr`、`bfl`、`bytetrade`、`project`、`pod` -### `TOKEN_MAX_AGE` -设置 Token 的最大有效时长（单位：秒）。 -- **可选值**：任意整数（单位：秒） +### TOKEN_MAX_AGE + +设置 Token 的最大有效时长（单位：秒）。 +- **可选值**：任意整数（单位：秒） - **默认值**：`31536000`（365 天） \ No newline at end of file