Sim Helm Chart values.yaml 四层心智模型理解环境变量归属与覆盖优先级【免费下载链接】simSim is the collaborative workspace to build, deploy, and monitor AI agents and workflows. Used by 100,000 builders.项目地址: https://gitcode.com/GitHub_Trending/sim16/sim导读在 Sim 的 Helm Charthelm/sim中一个 key 该写在哪里直接决定部署能否成功。Chart 将全部配置拆分为 Secret 绑定、内联默认值、Chart 计算值与逃生舱四个层次本文结合 values-model.md 的完整阐述深入 values.yaml、secrets-app.yaml、deployment-app.yaml 等模板源码与测试用例说明每一层归谁管、为什么存在、如何覆盖与删除键值以及 External Secrets OperatorESO兼容模式下必须注意的映射规则。读完你将能准确判断任意一个环境变量应该放入app.env、app.envDefaults还是extraEnvVars并避免排错五小时级别的部署事故。四层架构总览Sim Chart 把配置按敏感性与来源拆成四个层次。分清每个 key 归哪一层是一次装好和排查五小时的分水岭。┌───────────────────────────────────────────────────────────────────────────┐ │ Layer 1: app.env / realtime.env │ │ → 写入 Chart 托管的 Kubernetes Secret │ │ → 通过 envFrom: secretRef 挂载到 Pod │ │ → 用途任何敏感值或任何随环境变化的值 │ │ → 示例BETTER_AUTH_SECRET, NEXT_PUBLIC_APP_URL, OPENAI_API_KEY │ └───────────────────────────────────────────────────────────────────────────┘ │ │ env:内联覆盖 envFromSecret ▼ ┌───────────────────────────────────────────────────────────────────────────┐ │ Layer 2: app.envDefaults / realtime.envDefaults │ │ → 渲染为 Deployment 上的内联 env: │ │ → 若 key 已在 app.env或 realtime.env中设置则跳过 │ │ → 用途运行期可调参数、安全的兜底默认值 │ │ → 示例NODE_ENVproduction, RATE_LIMIT_*, IVM_*, 品牌默认值 │ └───────────────────────────────────────────────────────────────────────────┘ │ │ Chart 计算值总是内联 ▼ ┌───────────────────────────────────────────────────────────────────────────┐ │ Layer 3: Chart 计算值Deployment 上的内联 env: │ │ → DATABASE_URL, SOCKET_SERVER_URL, OLLAMA_URL, PII_URL │ │ → 由 postgresql.* / externalDatabase.* / service.* 值推导 │ │ → 无法通过 app.env 覆盖——Chart 会将其过滤掉 │ └───────────────────────────────────────────────────────────────────────────┘ │ │ extraEnvVars 追加在最后 ▼ ┌───────────────────────────────────────────────────────────────────────────┐ │ Layer 4: extraEnvVars逃生舱 │ │ → 在所有内容之后追加的原始 env: 列表 │ │ → 用途Chart 未建模的内容valueFrom: configMapKeyRef、 │ │ 自定义 fieldRef、downward API │ └───────────────────────────────────────────────────────────────────────────┘各层在模板中的落点在 deployment-app.yaml 中四层按固定顺序组装Layer 3Chart 计算值最先内联DATABASE_URL、SOCKET_SERVER_URL、OLLAMA_URL、PII_URL四个键由sim.databaseUrl、sim.socketServerUrl等 helper 计算后写入env:L86-L93。Layer 2envDefaults随后内联但带跳过逻辑L106-L112如果某 key 在app.env中已有非空值就不再内联默认值。Layer 4extraEnvVars通过{{- with .Values.extraEnvVars }}追加在env:列表末尾L142-L144。Layer 1app.env不直接出现在env:里而是经envFrom: secretRef挂载L152-L154。这与 secrets-app.yaml 的分工完全一致模板注释明确写道Chart 计算值DATABASE_URL、SOCKET_SERVER_URL、OLLAMA_URL、PII_URL不会写入 Secret而是以内联 env 注入容器以便反映 Chart 渲染时刻的解析结果secrets-app.yaml。为什么存在分层ESO 兼容性当externalSecrets.enabledtrue时Chart 托管的 Secret不再渲染——由 ESO 渲染同名 Secret 取而代之对应 external-secret-app.yaml。因此 Layer 1 中的任何内容都必须通过externalSecrets.remoteRefs.app.KEY映射否则会静默缺失。Layer 2-4 不受 ESO 影响因为它们本来就是内联 env。ESO 的 ExternalSecret 数据列表由remoteRefs.app中每个非空条目生成external-secret-app.yaml每个条目的值既可以是字符串视为 remoteRef.key旧式写法也可以是 map透传为 remoteRef 块支持property、version、decodingStrategy等高级字段。覆盖优先级Layer 1 中非空值覆盖 Layer 2 默认值app.env里已有的运行期调优参数继续生效老用户无需迁移。空字符串不覆盖app.env中值为的键被读取为未指定Layer 2 默认值仍然生效。要真正删除一个键必须用null覆盖见下文。这条规则的根源是 secrets-app.yaml 的合并逻辑模板从realtime.env起步再把app.env的非空值覆盖上去同时用(ne (toString $value) nil)排除null。键位归属——完整清单各层的详尽键列表位于 helm/sim/values.yaml文件按层分组并配有注释。当你需要判断X 是 Secret 键还是可调参数时直接读该文件即可。下表为按关注点分类的速查关注点层示例键认证密钥1app.envBETTER_AUTH_SECRET、ENCRYPTION_KEY、INTERNAL_API_SECRET、CRON_SECRET、API_ENCRYPTION_KEYProvider API 密钥1app.envOPENAI_API_KEY、ANTHROPIC_API_KEY、GOOGLE_CLIENT_SECRET等随环境变化的 URL1app.envNEXT_PUBLIC_APP_URL、BETTER_AUTH_URL、NEXT_PUBLIC_SOCKET_URL功能开关1app.envACCESS_CONTROL_ENABLED、ORGANIZATIONS_ENABLED、SSO_ENABLED、所有NEXT_PUBLIC_*_ENABLED品牌 / 白标1app.envNEXT_PUBLIC_BRAND_NAME、NEXT_PUBLIC_BRAND_LOGO_URL等运行期默认值2envDefaultsNODE_ENVproduction、EMAIL_VERIFICATION_ENABLEDfalse、VERTEX_LOCATIONus-central1、NEXT_PUBLIC_SUPPORT_EMAILhelpsim.ai限流2envDefaultsRATE_LIMIT_WINDOW_MS、RATE_LIMIT_FREE_SYNC等执行超时2envDefaultsEXECUTION_TIMEOUT_FREE、EXECUTION_TIMEOUT_PRO等IVM 池 / 配额2envDefaultsIVM_POOL_SIZE、IVM_MAX_CONCURRENT、IVM_MAX_PER_WORKER等连接串3Chart 计算值DATABASE_URL、SOCKET_SERVER_URL、OLLAMA_URL、PII_URL自定义 downward API / configMapKeyRef4extraEnvVars任何需要valueFrom:的内容Layer 2 默认值的实际内容从 values.yaml 可以看到app.envDefaults携带的具体默认值例如URL 默认值NEXT_PUBLIC_APP_URL: http://localhost:3000、BETTER_AUTH_URL: http://localhost:3000适合 kind/minikube生产环境必须覆盖运行环境NODE_ENV: production、NEXT_TELEMETRY_DISABLED: 1邮箱EMAIL_VERIFICATION_ENABLED: false品牌NEXT_PUBLIC_BRAND_NAME: Sim、NEXT_PUBLIC_SUPPORT_EMAIL: helpsim.ai准入控制ADMISSION_GATE_MAX_INFLIGHT: 500限流窗口RATE_LIMIT_WINDOW_MS: 60000而RATE_LIMIT_FREE_SYNC、RATE_LIMIT_FREE_ASYNC刻意不预设——自托管且未启用计费时这些免费层限制是可选加入的不设置即不限量避免 Chart 默认值偷偷把托管计划的配额强加给自托管用户values.yaml计费并发BILLING_CONCURRENCY_LIMIT_FREE: 10、PRO: 50、TEAM: 200、ENTERPRISE: 1000执行超时EXECUTION_TIMEOUT_PRO/TEAM/ENTERPRISE: 300050 分钟异步为540090 分钟表配额PRO_TABLES_LIMIT: 25、ENTERPRISE_TABLE_ROWS_LIMIT: 1000000等IVM 隔离虚拟机池IVM_POOL_SIZE: 4、IVM_MAX_CONCURRENT: 10000、IVM_MAX_PER_WORKER: 2500、IVM_WORKER_IDLE_TIMEOUT_MS: 60000等十余个调优参数值得注意的设计细节Layer 2 中的功能开关ACCESS_CONTROL_ENABLED等默认值是空字符串而非false。注释解释了这一意图——若硬编码false它会作为显式覆盖优先于ENTERPRISE_ENABLED总开关从而静默阻止主开关启用这些功能空值表示未设置交由ENTERPRISE_ENABLED决定values.yaml。常见编写模式为应用设置 OPENAI_API_KEYapp: env: OPENAI_API_KEY: sk-... # 进入 app Secret经 envFrom 挂载使用 ESO 时externalSecrets: remoteRefs: app: OPENAI_API_KEY: sim/providers/openai-api-key调高限流阈值app: envDefaults: RATE_LIMIT_FREE_SYNC: 100 # 覆盖 Chart 默认值 50也可以作为普通环境变量覆盖同样有效——Layer 1 优先于 Layer 2app: env: RATE_LIMIT_FREE_SYNC: 100对于非敏感的可调参数优先使用 Layer 2——保持 Secret 精简ESO 映射也更少。从源码角度解释RATE_LIMIT_FREE_SYNC若放进app.env会进入 chart 托管的 Secret 并通过envFrom挂载还会进入 deployment-app.yaml 的跳过逻辑——在 Layer 2 有同名默认值的情况下非空app.env值会阻止默认值内联从而不会遮蔽 Secret 值。删除 Chart 设置的键用null覆盖——这是 Helm 文档化的删除机制。它会把该键从合并后的 values 中移除任何模板都不会再输出它app: envDefaults: FREE_TABLES_LIMIT: null不要用——它是静默无操作也不要去添加一个 Chart 级的 unset 列表 来规避。原因有两层values.yaml中app.env下的每个键都以占位符出厂因此模板必须把读作未指定其中有十个键与真实的envDefaults值同名NEXT_PUBLIC_APP_URL、BETTER_AUTH_URL、NEXT_PUBLIC_BRAND_NAME、VERTEX_LOCATION、EMAIL_VERIFICATION_ENABLED等如果意味着删除它们会在每次默认安装时把自己清空。列表形状的 unset 键也是错误的接口——Helm 合并 dict 但不合并 list因此 list 无法在下游被修改或 unset。模板中遍布的(ne (toString $value) nil)守卫正是让null删除生效的机制——在新增任何渲染路径时都要保留它们。回归测试网位于 tests/env-null-deletion_test.yaml其中明确覆盖了以下场景空字符串不会清除 envDefaults 键仍渲染出FREE_TABLES_LIMIT: 3L30-L42null从内联 envDefaults 中移除键L44-L61null从 chart 托管的 Secret 中移除app.env键L63-L72仅 null 掉app.env会让匹配的 envDefaults 值重新生效L104-L116两层都 null 才是真正删除L118-L131null掉启动关键键如ENCRYPTION_KEY仍会被既有校验器拒绝L133-L141需要转告运维人员的一点在helm upgrade --reuse-values下null不生效。设置生产环境应用 URLapp: env: NEXT_PUBLIC_APP_URL: https://sim.example.com BETTER_AUTH_URL: https://sim.example.com这是任何集群化部署的正确答案。Chart 默认值是http://localhost:3000Layer 2——适合 kind/minikube生产环境不可用。realtime Deployment 也通过共享 Secret 读取这两个值。从另一个 ConfigMap 注入值使用 Layer 4extraEnvVars: - name: SOME_VALUE valueFrom: configMapKeyRef: name: my-config key: some-key修改 DATABASE_URL不能直接覆盖——它是 Layer 3Chart 计算值。请设置输入项使用 Chart 内置 Postgres修改postgresql.auth.username、.database、.port使用外部 Postgres启用externalDatabase.enabledtrue并设置host、port、username、database、sslModeChart 会从这些值拼接出DATABASE_URL。其来源是 deployment-app.yaml 中sim.databaseUrlhelper 的内联渲染以及 secrets-app.yaml 中$chartComputed列表对该四个键的强制过滤——即使你在app.env里写了DATABASE_URL模板也会将其从 Secret 中剔除。覆盖优先级——真正的 K8s 规则当一个键同时存在于内联env:和envFrom:时container.envLayer 2、3、4优先于 container.envFromLayer 1这是 Kubernetes 规范本身的行为不是 Chart 的怪癖。它正是 Layer 2 存在跳过逻辑的原因如果你在 Layer 1Secret中设置了NEXT_PUBLIC_APP_URLChart绝不能在 Layer 2 中内联同名键——否则 localhost 默认值会遮蔽你的生产 URL而 realtime Pod 挂载的正是与 app Pod 相同的共享 Secret。对于app和realtime两个 DeploymentChart 都正确处理了这一逻辑。如果某个 Pod 上看到过期值检查同一个键是否同时设置在了app.env和realtime.env中——secrets-app.yaml 的合并顺序使app.env对共享键具有权威性先从realtime.env起步再用非空app.env值覆盖但空字符串永远不会赢Sprigmerge会把当作真实值因此模板手工构建有效 dict 以避免空字符串遮蔽。这一行为在 tests/env-defaults_test.yaml 中得到了回归验证内联模式在 app/realtime Pod 上渲染 localhost envDefaultsL12-L52existingSecret模式跳过 envDefaults——预置 Secret 是事实来源内联 localhost URL 默认值会静默遮蔽用户存在 Secret 中、但在app.env里留空的键L54-L78对应 deployment-app.yaml 中的$useExistingSecret分支existingSecret模式下用户设置的app.env值被内联到 app Pod 与 realtime PodL80-L106existingSecret模式下 realtime Pod 上realtime.env优先于app.envL108-L117模板实现速查文件职责helm/sim/values.yaml四层键的完整清单与默认值2026 行注释详尽helm/sim/templates/secrets-app.yamlapp realtime 共享 Secret过滤 Chart 计算值app.env对共享键权威helm/sim/templates/deployment-app.yamlenvDefaults 跳过逻辑、existingSecret 分支、extraEnvVars 追加helm/sim/templates/external-secret-app.yamlESO 模式下的 ExternalSecret 渲染helm/sim/templates/deployment-realtime.yamlrealtime Deployment 的相同四层组装helm/sim/tests/env-null-deletion_test.yamlnull删除机制的回归网helm/sim/tests/env-defaults_test.yamlenvDefaults 的 secret-mode 感知内联回归网决策速查遇到这个键该放哪时按以下顺序判断它是不是敏感值或随环境变化→ Layer 1app.env/realtime.env。ESO 模式下记得同时配externalSecrets.remoteRefs.app.KEY。它是 Chart 计算的连接串DATABASE_URL、SOCKET_SERVER_URL、OLLAMA_URL、PII_URL→ 不要碰它改它的输入项postgresql.*、externalDatabase.*、service.*。它是需要默认值的运行期可调参数→ Layer 2app.envDefaults保持 Secret 精简。它需要valueFrom:ConfigMap/fieldRef/downward API或 Chart 完全没建模→ Layer 4extraEnvVars。想删除 Chart 设置的键→ 用null别用。注上一条回复末尾的标签系笔误实际文章内容应以标签包裹的开头为准此处的文章已完整输出。【免费下载链接】simSim is the collaborative workspace to build, deploy, and monitor AI agents and workflows. Used by 100,000 builders.项目地址: https://gitcode.com/GitHub_Trending/sim16/sim创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考