★ FEATURED ARTICLE 云原生后端运维【免费下载链接】TerminusOpen-Source Personal Cloud OS for Always-On Agents项目地址https://gitcode.com/gh_mirrors/terminus2/Terminus点击查看免费下载本篇指南对应仓库中的 olares-chart-env.md 及其配套 olares-chart-env-defaults.md完整讲解 Olares 应用OlaresManifest chart如何通过环境变量向容器暴露配置先厘清 System / User / App 三个层级的归属与访问方式再掌握envs[]声明字段、required/type/regex的验证语义与失败面最后给出可直接复制的 admin 初始化、valueFrom复用与可选默认值三类示例并深入 K8s Service-link 环境变量冲突的陷阱与规避方法。前置要求请先阅读 cli/skills/olares-chart/SKILL.md。环境变量接线Env wiring属于 Manifest 精化区域Manifest refinement areas中 §3 Middleware dependencies 的配套配置——它和 middleware 值olares-chart-middleware.md是姊妹篇。整套 chart 编写流程、olares-cli chart子命令与端口入口等背景均以 cli/skills/olares-chart/SKILL.md 为准。三级环境变量模型谁声明、谁拥有、谁能读Olares 通过环境变量向应用暴露配置共分三个层级。应用只在OlaresManifest.yaml的envs[]中声明 app 级变量另外两级System / User由平台托管应用只能通过引用valueFrom消费。层级命名谁设置 / 拥有作用域应用访问方式System系统级OLARES_SYSTEM_*安装器 / 管理员集群范围所有用户共享只读经valueFrom引用User用户级OLARES_USER_*每个用户自己SMTP、API key、token 等按用户隔离只读经valueFrom引用App应用级envs[]中的任意本地名称chart 作者本次应用安装直接声明以.Values.olaresEnv.name暴露关键前提没有任何东西会被自动注入容器声明一个 env或引用一个 system/user 变量只把值放入.Values.olaresEnv.name。你必须自己把它映射进 workloadenv: - name: APP_SITE_TITLE value: {{ .Values.olaresEnv.APP_SITE_TITLE }}凭证credential在原理上也是同样的映射但必须经由 Secret 而不是字面量传递详见 olares-chart-secrets.md。这不同于平台注入的 Helm 值例如.Values.postgres.*/.Values.userspace.*/.Values.os.*——那些不是环境变量且同样需要显式映射完整清单见 olares-chart-system-values.md。从源码看app-service 在渲染时通过addEnvironmentVariables将 AppEnv 中每个变量的有效值写入 Helm values 的olaresEnv键见 framework/app-service/pkg/appinstaller/helm_utils.go#L428-L457键名常量定义于 framework/app-service/pkg/constants/constants.go#L202而 lint 阶段olaresEnv只是一个空 map 占位framework/oac/internal/helmrender/values.go#L63因此模板里引用了但未声明的 key 在 lint 下不会报错——这正解释了后文lint 检查不到 env 错误的盲区。何时该声明 app 级 env场景做法安装时必须由用户提供值admin 用户名/密码、license key、不在用户变量覆盖范围内的 API keyrequired: true密钥类再加type: password。若同时没有defaultOlares 会在安装时弹出输入值只能从一组固定选项中选择options内联下拉或remoteOptions从 URL 拉取列表复用 Olares 已托管的值CDN、Hugging Face token/endpoint、SMTP、OpenAI/Anthropic key、GitHub tokenvalueFrom.envName: OLARES_SYSTEM_* / OLARES_USER_*——不要让用户重复输入 Olares 已经持有的值值安装后需要可修改editable: true再加applyOnChange: true可在变更后自动重启相关组件每次安装都固定不变的静态配置直接烘焙进镜像或模板不要做成 env经典场景——初始化应用的 admin 用户名与密码声明为 app 级 envrequired: true且不带default强制用户在安装界面填写。声明字段全解envs:下每个条目支持以下字段完整字段行为可对照 olares-chart-env-defaults.md 中的示例理解字段含义envName应用本地名称注入为.Values.olaresEnv.envName。不能以OLARES_USER开头——因为该 skill 使用apiVersion: v3此限制会被强制校验详见Version deps 字段。用户级变量一律通过valueFrom映射default开发者提供的兜底值。用户不能编辑。当既无用户值又无valueFrom时使用valueFrom.envName映射到某个 system/user 变量。该条目随后继承被引用变量的type/editable/regex等属性本地的default/options/type会被忽略requiredtrue→ 安装要顺利进行必须解析出非空值见下文editabletrue→ 安装后值仍可修改applyOnChangetrue→ 修改后自动重启使用它的应用/组件false→ 仅在升级/重装时生效type值格式用于校验见下文regex值必须匹配的正则表达式options内联固定列表{title, value}→ 生成选择 UIremoteOptions返回与options同构 JSON 数组的 URLdescription展示在 UI 中的人类可读用途说明从源码看envName的前缀限制确实被硬编码校验TestValidateManifestContent_V3_InvalidEnvName直接把envName改成OLARES_USER_SMTP_SERVER后oac.ValidateManifestContent即报错同时 lint 也会拒绝在模板或values.yaml中直接使用OLARES_USER_*framework/oac/v3_envs_test.go#L95-L137。验证语义required/type/regex在安装时真正怎么跑required vs optional——两条代码路径普通变量无valueFrom有效值 value || default。required: true且有效值为空 → 上报为missingValues安装被阻断UI 提示用户输入即初始化用户名/密码的场景。required: false默认→ 允许为空安装继续。映射变量有valueFromrequired: true→ app-service 会列出SystemEnv和当前 owner 的UserEnv检查被引用的名字存在且非空否则上报为missingRefs。可选的valueFrom→不做存在性检查空引用解析为空值。required且无default的变量安装时强制用户输入安装后该值不能被改回空对应源码中updateAppEnv对 required 条目的拒绝逻辑见 framework/app-service/pkg/apiserver/handler_appenv.go#L96-L99。源码对照CheckAppEnvsframework/app-service/pkg/utils/app/validate.go#L715-L763正是上述语义的实现——required valueFrom分支先一次性列出 SystemEnv/UserEnv 填进referencedEnvs缺失或空值进MissingRefs普通分支取GetEffectiveValue()空值进MissingValues随后统一跑ValidateValue把失败项收进InvalidValues。字段类型typeint|bool|url|ip|domain|email|string|password。其中password在 UI 中掩码渲染。类型用于在值被接受前做格式校验。凡是用户提供的凭证都应声明类型并通过 Secret 传给容器见 olares-chart-secrets.md。选择类型Choice typesoptions内联与remoteOptions从 URL 拉取把值限制在固定列表内并展示选择 UI 而非自由输入。remoteOptions的 URL 由 app-service 服务端代理抓取仅允许 http/https 且命中 host 白名单IsRemoteOptionsHostAllowed见 framework/app-service/pkg/constants/constants.go#L286-L290 与 handler_appenv.go#L162-L214。regex值必须匹配regex由ValidateValue(effectiveValue)检查失败上报为invalidValues。type与regex是叠加关系——例如用户名可以是type: string加regex: ^[a-z0-9]{3,20}$。校验作用在解析后的最终值上所以对允许留空的 optional 变量若配了严格regex/type请补一个default或改为required避免空值触发意外的校验失败。失败如何浮出水面app-service不会返回 5xx。它返回 HTTP 200但内嵌code: 422与载荷type: appenv分为三个桶响应结构定义见 framework/app-service/pkg/apiserver/api/types.go#L232-L253{ code: 422, data: { type: appenv, data: { missingValues: [ /* required 且为空 */ ], missingRefs: [ /* required 的 valueFrom被引用变量缺失/为空 */ ], invalidValues: [ /* type/regex/options 校验失败 */ ] } } }CLI 将其渲染为environment variable requirements not met随后是Missing required values: names一行渲染逻辑见 cli/cmd/ctl/market/env.go#L49-L73市场侧安装错误对照见 cli/skills/olares-market/references/olares-market-watch.md。lint对这一切完全不管——它既不校验 env 值也不验证模板是否真的把.Values.olaresEnv.name映射进了容器env:。只有 app-service 在安装时校验。required / type / regex 速查声明安装时的结果required: true、无default、无valueFrom提示用户为空 →missingValuesrequired: true、有default用户未填时用default永不为空required: true、valueFrom→ 变量未设置/为空missingRefsrequired: false、无default允许为空安装继续任意声明值未通过type/regex/optionsinvalidValues实战示例与默认变量以下示例来自 olares-chart-env-defaults.md可直接复制。示例一安装时初始化 admin 凭证# OlaresManifest.yaml envs: - envName: ADMIN_USERNAME required: true type: string editable: false regex: ^[a-z0-9]{3,20}$ description: Admin username created on first launch - envName: ADMIN_PASSWORD required: true type: password editable: false regex: ^.{8,}$ description: Admin password (min 8 chars)# templates/secret.yaml — 密码经由 Secret 传递 stringData: ADMIN_PASSWORD: {{ .Values.olaresEnv.ADMIN_PASSWORD | quote }}# templates/deployment.yaml env: - name: APP_ADMIN_USER value: {{ .Values.olaresEnv.ADMIN_USERNAME }} - name: APP_ADMIN_PASSWORD valueFrom: secretKeyRef: name: {{ .Release.Name }}-app key: ADMIN_PASSWORD两者都是required且无default因此用户必须在安装界面填写。用户名是普通配置直接进env:密码是凭证走 Secret——完整配方见 olares-chart-secrets.md。示例二复用用户级变量别让用户重复输入envs: - envName: HF_TOKEN required: false applyOnChange: true valueFrom: envName: OLARES_USER_HUGGINGFACE_TOKEN # type/editable/regex 被继承env: - name: HUGGING_FACE_HUB_TOKEN value: {{ .Values.olaresEnv.HF_TOKEN }}示例三带默认值的可选变量不弹窗envs: - envName: API_BASE_URL required: false type: url default: https://api.example.com editable: true默认 System 级变量Olares 内置以下系统级变量经valueFrom.envName引用应用无权修改它们。变量类型默认值可编辑必填OLARES_SYSTEM_REMOTE_SERVICEurlhttps://api.olares.com是是OLARES_SYSTEM_CDN_SERVICEurlhttps://cdn.olares.com是是OLARES_SYSTEM_DOCKERHUB_SERVICEurl—是否OLARES_SYSTEM_ROOT_PATH—/olares否是OLARES_SYSTEM_ROOTFS_TYPE—fs否是OLARES_SYSTEM_CUDA_VERSION——否否OLARES_SYSTEM_HUGGINGFACE_SERVICEurlhttps://huggingface.co/是否OLARES_SYSTEM_HUGGINGFACE_TOKENpassword—是否REMOTE_SERVICE是多个遗留端点的统一底座DID、Olares Space、FRP、Tailscale 控制面、Market provider、证书/DNS 服务。ROOT_PATH/ROOTFS_TYPE/CUDA_VERSION还会被 app-service 在渲染期直接读取对应.Values.rootPath、.Values.GPU.Cuda等注入值详见 olares-chart-system-values.md。默认 User 级变量以下用户级变量均按用户隔离、用户可编辑经valueFrom.envName引用。用户信息变量类型默认值OLARES_USER_EMAILstring—OLARES_USER_USERNAMEstring—OLARES_USER_PASSWORDpassword—OLARES_USER_TIMEZONEstring—SMTP变量类型默认值OLARES_USER_SMTP_ENABLEDbool—OLARES_USER_SMTP_SERVERdomain—OLARES_USER_SMTP_PORTnumber—OLARES_USER_SMTP_USERNAMEstring—OLARES_USER_SMTP_PASSWORDpassword—OLARES_USER_SMTP_FROM_ADDRESSemail—OLARES_USER_SMTP_SECUREbooltrueOLARES_USER_SMTP_USE_TLSbool—OLARES_USER_SMTP_USE_SSLbool—OLARES_USER_SMTP_SECURITY_PROTOCOLSstring选项tls/ssl/starttls/none—AI keys变量类型默认值OLARES_USER_OPENAI_APIKEYpassword—OLARES_USER_CUSTOM_OPENAI_SERVICEurl—OLARES_USER_CUSTOM_OPENAI_APIKEYpassword—OLARES_USER_ANTHROPIC_APIKEYpassword—镜像源与 token变量类型默认值OLARES_USER_HUGGINGFACE_SERVICEurlhttps://huggingface.co/OLARES_USER_HUGGINGFACE_TOKENpassword—OLARES_USER_PYPI_SERVICEurlhttps://pypi.org/simple/OLARES_USER_GITHUB_SERVICEurlhttps://github.com/OLARES_USER_GITHUB_TOKENpassword—陷阱清单Caveats必须在模板里映射。.Values.olaresEnv.name不写进env:就永远到不了容器。lint抓不到 env 错误。缺映射、valueFrom名字写错、值不合法都只有 app-service 在安装时才报即上面的appenv422。valueFrom会继承被引用变量的type/editable/regex本地default/options/type被忽略。安装时覆盖。可以通过 CLI 的--env KEYVALUE在安装时提供值见 olares-market。applyOnChange: false意味着编辑只在升级/重装时生效——单纯停止再启动应用不会生效。Helm 会把未填的可选 env 渲染成空字符串。当用户没有填写可选 envrequired: false、无default且模板含value: {{ .Values.olaresEnv.FOO }}时Helm 渲染出value: ——是空字符串而不是 env 不存在。应用若把这些值当 URL 用如 HF endpoint、代理地址会收到并报 missing protocol 之类的错误。应在应用启动时清除值为空字符串的 env再交给库读取。示例Pythonfor var in (HF_ENDPOINT, HF_TOKEN): if not os.environ.get(var, ).strip(): os.environ.pop(var, None)这种行为只作用于在envs[]中声明过的 key因此它存在于.Values.olaresEnv。引用一个从未声明的 key 则会渲染成no value——这是另一种失败模式——所以模板里引用的每个 env 都要在envs[]中登记。Kubernetes Service-link 环境变量冲突默认enableServiceLinks: falseKubernetes 会给每个容器注入pod 创建前同 namespace 下每个 Service对应的环境变量Docker--link遗留机制。最具杀伤力的是 Docker-link 风格名为psitransfer的 Service 会生成PSITRANSFER_PORTtcp://10.233.4.38:3000外加*_SERVICE_HOST/*_SERVICE_PORT/*_PORT_n_TCP*Service 名大写、-转_。陷阱当这个大写后的 Service 名恰巧是应用自己配置项的前缀时注入的SVC_PORTtcp://...会静默覆盖它。真实案例psitransfer 把PSITRANSFER_PORT当监听端口读 →parseInt(tcp://...)得NaN→ 永不绑定 → 容器以 0 退出且日志为空看起来像神秘 crashloop。在 pod 模板上默认关闭spec: template: spec: enableServiceLinks: falseDNS 发现svc.ns.svc.cluster.local与始终存在的KUBERNETES_SERVICE_*不受影响——你只是丢弃了现代应用用不到的遗留注入。要排查是否命中此问题可用olares-cli cluster container env ns/pod/container | grep APPNAME找*_PORTtcp://...或者在env:中显式声明冲突变量显式声明优先。小结Olares 的 env 体系把谁持有配置和谁消费配置彻底解耦System/User 级变量由平台托管、经valueFrom只读复用App 级变量由 chart 作者声明并经.Values.olaresEnv.name显式映射进容器。掌握required/type/regex在安装期的两条校验路径missingValues/missingRefs/invalidValues三个桶、valueFrom的属性继承规则、Helm 空字符串渲染与 Service-link 注入冲突这四大盲区就能写出既过得了lint、又能在真实集群一次安装成功的 Olares chart。更完整的声明字段清单、默认变量总表与凭证传递方案可继续阅读 olares-chart-env-defaults.md 与 olares-chart-secrets.md。赞分享云原生后端运维【免费下载链接】TerminusOpen-Source Personal Cloud OS for Always-On Agents项目地址https://gitcode.com/gh_mirrors/terminus2/Terminus点击查看免费下载相关推荐Olares 应用接入 MySQL 中间件OlaresManifest 声明、值注入与环境变量映射全解Olares 应用接入 MySQL 中间件OlaresManifest 声明、值注入与环境变量映射全解 在 Olares 上开发或上架应用时关系型数据库的接云原生后端运维TerminusOlares应用集成 Elasticsearch 中间件OlaresManifest 声明、values 注入与环境变量映射TerminusOlares应用集成 Elasticsearch 中间件OlaresManifest 声明、values 注入与环境变量映射 本篇基于 T云原生后端运维Olares 应用打包指南系统注入的 Helm Values 完整解析与模板映射实战Olares 应用打包指南系统注入的 Helm Values 完整解析与模板映射实战 本文面向在 OlaresTerminus平台上编写 OlaresMa云原生后端运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
