Olares 应用环境变量管理完全指南:从设置界面到控制面板的 Kubernetes 级修改

原创2026-10-15 13:11:241,672 阅读
文章标签:云原生后端运维

Olares 应用环境变量管理完全指南:从设置界面到控制面板的 Kubernetes 级修改

应用环境变量决定了应用在容器中的运行方式——包括应用配置、服务连接以及其他运行时设置。本指南以 Olares 内置的设置 > 应用入口为主线,系统讲解如何在 Olares 中查看、编辑应用专属变量与系统级环境变量,并深入控制面板,演示如何定位变量在 Kubernetes 资源中的存储位置(Deployment、Configmap、Secret),通过 YAML 编辑器直接修改部署变量、配置字典和保密字典,涵盖常规应用与 C/S 架构应用(如 Ollama、Jellyfin、DeerFlow)的完整实操路径。

读完本文,你将掌握:通过图形界面安全修改应用变量的方法;判断变量归属(应用专属 vs 系统引用)的技巧;在控制面板中按资源类型精准定位并修改变量、手动重启工作负载使配置生效的完整流程;以及变量修改后不生效时的排查与重启策略。

查看应用的环境变量

在 Olares 中,所有应用的环境变量都可以通过统一的图形界面入口查看:

  1. 前往设置 > 应用。
  2. 在应用列表中选择目标应用。
  3. 在环境变量部分,点击管理环境变量。

应用环境变量入口

管理环境变量页面会列出当前应用正在使用的所有环境变量:

应用环境变量列表

理解环境变量类型

根据应用的配置方式,页面中会出现两类变量,它们的可编辑性截然不同:

变量类型 说明 可编辑性
应用专属变量 应用本身定义的变量,直接在应用的环境变量列表中定义 正常显示,可直接在当前页面编辑
引用的系统环境变量 应用通过 ValueFrom 引用的系统全局变量,只有当应用实际使用这些变量时才会显示 页面中呈置灰状态,无法直接编辑
  • 应用专属变量:由应用自身(或其安装包)定义,直接属于该应用,可在"管理环境变量"页面中直接修改。
  • 引用的系统环境变量:来自系统级配置(SystemEnv)或用户级配置(UserEnv),只有当应用的 AppEnv 通过 ValueFrom.EnvName 引用了这些全局变量时,它们才会出现在本页。这类变量在此页面为只读,若要修改,请参考设置系统级环境变量。

从源码角度,这一区分在 framework/app-service/pkg/apiserver/handler_appenv.go 中实现:getAppEnv 返回应用命名空间下 AppEnv 资源的 Envs 列表,而 updateAppEnv 在写入时会校验 existingEnv.Editable,对非可编辑变量直接拒绝修改;当新值来自 ValueFrom.EnvName 时,还会查询 SystemEnvList 与 UserEnvList 来解析引用变量的有效值(GetEffectiveValue())。

编辑应用专属变量

对于应用专属变量,修改流程非常直接:

  1. 在变量列表中找到要编辑的变量。
  2. 点击该行右侧的编辑图标(edit_square)。
  3. 在弹出的对话框中更新变量值,点击确认。
  4. 点击页面底部(或右上角)的应用按钮提交更改。

编辑应用环境变量

提交后,应用会自动重启,新配置随之生效。

前端实现的提交机制

Olares 控制面板的前端页面(apps/packages/app/src/pages/settings/Developer/pages/SystemEnvironmentPage.vue)采用"暂存更改 + 批量提交"的设计:每次编辑操作只把变更写入内存中的 pendingChanges 集合,并提示"更改已临时保存";只有点击应用按钮时,submitAllChanges 才会把系统变量与用户变量分开,分别调用 updateSystemEnv 和 updateUserEnv 两个批量接口。如果离开页面时还有未提交的更改,前端会弹出警告对话框。对应的 API 定义位于 apps/packages/app/src/api/settings/env.ts,其中应用级接口为 GET/PUT /api/env/apps/{appName}/env,系统级接口为 GET/PUT /api/env/systemenvs,用户级接口为 GET/POST/PUT/DELETE /api/env/userenvs。

在控制面板中配置变量

除设置页面外,Olares 还允许你通过控制面板直接查看和修改应用的环境变量,适用于调试、功能配置或临时调整场景。

:::info 重要提示 在控制面板中直接修改的变量在应用升级后不会保留。如需永久配置,请设置系统级环境变量或使用应用自身的设置项。 :::

确定变量的存储位置

应用中的环境变量可以存储在不同类型的 Kubernetes 资源中。了解目标变量存储在哪个资源中,决定了你如何修改它、以及修改后是否需要手动重启:

资源类型 典型内容 修改后是否需要重启
部署(Deployment) 直接的键值对 自动重启
配置字典(Configmap) 配置数据、启动参数、配置文件 需手动重启
保密字典(Secret) 敏感数据,如密码、令牌、凭证 需手动重启

从 Kubernetes 语义看,Deployment 中的 env 字段变更会直接触发 Pod 滚动更新(自动重启);而 Configmap/Secret 是独立资源,修改后工作负载不会自动感知,必须重启 Deployment 才能让新值注入容器。

常规应用:通过 YAML 判断注入方式

要确定变量存储在哪里,可在控制面板中打开应用的部署 YAML,查看 spec > containers 部分。注入方式会告诉你变量的来源:

  • env:变量直接在部署中以键值对的形式定义。
  • envFrom 配合 configMapRef:变量存储在引用的 Configmap 中。
  • valueFrom 配合 secretKeyRef:变量存储在引用的 Secret 中。

例如,在下面的 YAML 中,envFrom 引用了 Configmap lobechat-config,而 env 直接定义了 PGID、PUID 和 TZ:

spec:
  containers:
    - name: lobechat
      image: docker.io/beclab/lobehub-lobehub:2.1.18
      ports:
        - name: http
          containerPort: 3210
          protocol: TCP
      envFrom:
        - configMapRef:
            name: lobechat-config
      env:
        - name: PGID
          value: '1000'
        - name: PUID
          value: '1000'
        - name: TZ
          value: Etc/UTC

上述三种注入方式恰好对应 Olares 中 AppEnv 资源对 EnvVarSpec 的建模:framework/app-service/controllers/userenv_controller.go 等控制器会遍历 AppEnv.Envs,把其中的 ValueFrom.EnvName 解析为系统/用户环境变量的实际值,再同步生成或更新 Deployment 的 env 字段——这就是"设置页面修改系统变量 → 应用自动生效"链路的关键环节。

C/S 架构应用:跨命名空间定位

部分应用采用客户端/服务器(C/S)架构,例如 Ollama。它们的变量分布在两个不同的命名空间中:

  • 用户命名空间:存放客户端资源。
  • 系统命名空间:存放服务端资源。

对于 C/S 应用,环境变量通常存储在跨两个命名空间的 Configmap 中。根据你要修改的内容,前往正确的命名空间:

  • 要修改外部访问行为:前往用户命名空间,查找名称中包含 nginx 或 sidecar 的 Configmap(如 nginx-config)。
  • 要修改应用核心参数:前往系统命名空间,查找名称中包含 env、config 或类似标识的 Configmap(如 ollama-env)。

这一命名约定与 Olares 的资源布局保持一致:用户命名空间承载着应用对外访问的前置代理资源(nginx/sidecar),而系统命名空间存放服务端工作负载及其配置。

修改部署中的变量

此方法适用于直接调整工作负载。下面的示例更改 Jellyfin 的时区,使媒体库显示本地时间戳而不是 UTC:

  1. 在控制面板的浏览面板中,选择 Jellyfin 项目。

  2. 在部署资源组下,点击 jellyfin,然后点击编辑图标(edit_square)。

    浏览到 Jellyfin 的部署实例

  3. 在 YAML 编辑器中,找到 containers 部分,定位 jellyfin 的 env 字段,更改 TZ 的值:

    env:
      - name: PGID
        value: '1000'
      - name: PUID
        value: '1000'
      - name: UMASK
        value: '002'
      - name: TZ
        value: Asia/Shanghai   # 原为 Etc/UTC
    
  4. 点击 Confirm。Pod 将自动重启以使更改生效。

由于 env 直接定义在 Deployment 中,修改后 Kubernetes 会触发滚动更新,因此无需手动重启。

修改配置字典中的变量

此方法用于添加第三方 API 密钥、修改启动参数或更新配置文件。修改后必须重启关联的工作负载才能生效。

常规应用 {#modify-standard-apps}

以下示例向 DeerFlow 的配置中添加 Tavily API 密钥,以启用网络搜索:

  1. 在控制面板的浏览面板中,选择 DeerFlow 项目。

  2. 在配置字典下,点击 deerflow-config。

    浏览到 DeerFlow 的配置字典

  3. 在资源详情页,点击右上角的编辑图标(edit_square)打开 YAML 编辑器。

  4. 在 data 部分下添加以下键值对:

    SEARCH_API: tavily
    TAVILY_API_KEY: tvly-xxx # 你的 Tavily API Key
    

    配置 Tavily

  5. 点击 Confirm 保存更改。

  6. 返回部署 > deerflow,点击重启。

    重启 DeerFlow

  7. 在确认对话框中输入 deerflow,然后点击 Confirm。

等待状态图标变为绿色,表示新配置已加载。

C/S 架构应用 {#modify-cs-apps}

根据你要修改的内容,你可能需要在用户命名空间、系统命名空间或两者中修改变量。

在用户命名空间中修改客户端设置

以下步骤将 Ollama 的代理读取超时从 300s 改为 600s:

  1. 在控制面板的浏览面板中,选择 Ollama 项目。

  2. 在部署资源组下,点击 ollamav2,然后点击编辑图标(edit_square)。

    在控制面板中定位 Ollama 实例

  3. 在 YAML 编辑器中,找到 containers 部分,定位并检查 env 字段。这里的配置引用了 nginx.conf。

    编辑 Ollama 实例的 YAML

  4. 点击 Cancel 关闭编辑器(这一步只是确认变量来源,真正的修改在配置字典中完成)。

  5. 展开配置字典,点击 nginx-config,点击右上角的编辑图标(edit_square)。

    定位 Nginx 配置实例

  6. 在 YAML 编辑器中,找到 data 部分,定位 nginx.conf 键,将 proxy_read_timeout 的值从 300s 改为 600s。

    编辑 Nginx 配置

  7. 点击 Confirm。

  8. 返回部署 > ollamav2,点击重启,使更改生效。

等待状态图标变为绿色,表示新配置已加载。

在系统命名空间中修改服务端设置

以下步骤将 Ollama 的最大加载模型数从 3 改为 5:

  1. 在控制面板的浏览面板中,向下滚动并点击 System 展开系统部分。

  2. 选择 ollamaserver-shared,在部署资源组下点击 ollama,再点击编辑图标(edit_square)。

    在系统命名空间中定位 Ollama

  3. 在 YAML 编辑器中,找到 containers 部分,检查 envFrom 字段。这里的配置引用了 ollama-env。

    编辑 YAML

  4. 点击 Cancel 关闭编辑器。

  5. 返回配置字典,点击 ollama-env 实例,点击右上角的编辑图标(edit_square)。

    编辑 Ollama 环境变量

  6. 在 YAML 编辑器中,找到 data 部分,将 OLLAMA_MAX_LOADED_MODELS 的值从 3 改为 5。

    编辑 Ollama 变量

  7. 点击 Confirm。

  8. 返回部署 > ollama,点击重启,使更改生效。

等待状态图标变为绿色,表示新配置已加载。

修改保密字典中的变量

保密字典(Secret)中的修改流程与配置字典完全相同。根据你的应用类型,遵循上述常规应用或 C/S 架构应用中的步骤即可。

:::info 关键注意事项 当你打开保密字典的 YAML 编辑器时,data 字段下的所有值都必须是 Base64 编码的——这是 Kubernetes Secret 的硬性要求,直接写入明文会导致资源创建或更新失败。 :::

常见问题

修改配置字典或保密字典后,更改未生效

这是最高频的坑:修改配置字典或保密字典后,关联的工作负载不会自动重新加载配置。因为 Configmap/Secret 与 Pod 的解耦设计,你必须重启工作负载才能读取新值。使用以下任一方法重启:

  • 在控制面板中重启

    进入应用所在命名空间的部署资源组,点击目标工作负载,然后点击重启。

  • 通过应用市场或设置重启

    如果不确定应该重启哪个工作负载,可以采用"暂停 → 恢复"的方式:

    • 进入应用市场 > 我的 Olares,点击应用操作按钮旁的下拉箭头,选择暂停,然后再点击恢复。
    • 进入设置 > 应用,点击应用,点击暂停,然后点击恢复。

这两种方法都会重新加载配置字典或保密字典中的最新配置,从而使更改生效。

如何区分"自动重启"与"手动重启"场景

可结合上文资源类型表快速判断:修改 Deployment 中直接定义的 env(键值对)→ 自动重启;修改 envFrom 引用的 Configmap 或 valueFrom 引用的 Secret → 必须手动重启。判断依据是 YAML 中变量的注入方式,而非应用类型。

了解更多

  • 设置系统级环境变量:了解如何配置全局环境变量(如第三方 API 密钥),并理解 OLARES_USER_ 前缀、系统配置与用户信息两大类别的锁定/编辑规则。
  • 系统环境变量的后端实现参考 handler_systemenv.go 与 systemenv_controller.go:前者负责 API 层的增删改查与管理员权限校验,后者通过监听 SystemEnv 变更、为引用它的 AppEnv 打上同步注解,驱动应用环境变量的级联刷新。
登录后查看全文
Terminus