企业官网建设流程全解析

• 云原生
• 后端
• 运维

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

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

查看应用的环境变量

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

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

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

理解环境变量类型

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

• 应用专属变量：由应用自身（或其安装包）定义，直接属于该应用，可在"管理环境变量"页面中直接修改。
• 引用的系统环境变量：来自系统级配置（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 资源中。了解目标变量存储在哪个资源中，决定了你如何修改它、以及修改后是否需要手动重启：

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

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

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

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

例如，在下面的 YAML 中，envFrom引用了 Configmaplobechat-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）。

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。

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

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

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

5. 点击Confirm保存更改。

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

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

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

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

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

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

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

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

2. 在部署资源组下，点击ollamav2，然后点击编辑图标（edit_square）。

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

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

5. 展开配置字典，点击nginx-config，点击右上角的编辑图标（edit_square）。

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

7. 点击Confirm。

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

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

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

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

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

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

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

4. 点击Cancel关闭编辑器。

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

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

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打上同步注解，驱动应用环境变量的级联刷新。

• 云原生
• 后端
• 运维