Sim Helm Chart 部署密钥完全指南：生成、存储、轮换与防泄漏实践

Sim Helm Chart 部署密钥完全指南生成、存储、轮换与防泄漏实践【免费下载链接】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/的运维技能文档为骨架系统讲解在 Kubernetes 上部署 Sim构建、部署与监控 AI Agent 与工作流的协作平台时必须掌握的密钥体系四个安装时必需密钥与两个常用可选密钥的生成方式、作用与轮换影响以及三种互斥的存储路径内联--set、预置 Kubernetes Secret、External Secrets Operator。读完本文你将能够独立完成 Sim 生产部署的密钥生命周期管理并理解 Chart 模板层对密钥的校验与渲染机制避免渲染成功、运行时 CrashLoopBackOff的经典故障。一、先认清局面Sim 在安装时需要的四把钥匙Sim Helm Chart 在安装时要求提供四个密码学密钥。它们必须一次性生成、妥善存储在你选定的密钥路径中路径选择见后文并且绝不能在多个环境之间复用。密钥作用推荐长度轮换影响BETTER_AUTH_SECRET为 Better Auth 的用户会话 JWT 签名32 字节 64 个十六进制字符轮换会使所有活跃会话失效用户必须重新登录ENCRYPTION_KEY应用级字段加密敏感字段32 字节 64 个十六进制字符轮换会导致已有数据无法解密必须配合数据迁移INTERNAL_API_SECRETsim-app与sim-realtime两个 Pod 之间的共享认证32 字节 64 个十六进制字符两个 Deployment 必须一起滚动滚动期间会出现短暂的实时服务错误CRON_SECRET为定时 CronJob Pod 向应用发起请求时提供认证32 字节 64 个十六进制字符只需helm upgrade下一次 cron 运行即使用新值另有两个常用可选密钥密钥作用长度要求注意事项API_ENCRYPTION_KEY可选加密用户存储在 Postgres 中的 API Key如 OpenAI Token必须恰好 64 个十六进制字符应用会拒绝其他长度不设置则密钥以明文存储一旦设置未经迁移绝不能轮换POSTGRES_PASSWORD仅 Chart 自带 PostgresPostgres 超级用户密码≥ 8 字符且匹配^[a-zA-Z0-9._-]$schema 强制推荐 32 字节十六进制轮换需要重启 Postgres Pod 并滚动应用为什么POSTGRES_PASSWORD有如此严格的字符约束原因见 values.yamlChart 会把密码直接嵌入DATABASE_URL而不做 URL 编码。而openssl rand -base64输出中的/、、恰好是三个问题字符所以文档用tr -d /将其剔除。Chart 在模板渲染阶段_helpers.tpl中的sim.validateSecrets定义见 templates/_helpers.tpl会通过regexMatch ^[a-zA-Z0-9._-]$强制校验该正则不满足会直接fail渲染。二、一次性生成全部密钥下面的命令段一次性生成全部四个必需密钥外加两个常用可选密钥。每执行一次openssl rand都是独立随机所以生成后请先把值存好再往下进行安装步骤。export BETTER_AUTH_SECRET$(openssl rand -hex 32) export ENCRYPTION_KEY$(openssl rand -hex 32) export INTERNAL_API_SECRET$(openssl rand -hex 32) export CRON_SECRET$(openssl rand -hex 32) # 可选但通常需要 export API_ENCRYPTION_KEY$(openssl rand -hex 32) # 必须恰好 64 个十六进制字符 export POSTGRES_PASSWORD$(openssl rand -base64 24 | tr -d /) # 仅当使用 Chart 自带 Postgres为什么这些值恰好是 64 个十六进制字符openssl rand -hex 32生成 32 字节随机数每个字节以两个十六进制字符表示故得 64 字符。这些密钥在 helm/sim/values.yaml 中均被标注为生产环境必需项REQUIRED并注明生成方式openssl rand -hex 32。三、密钥的存储路径三种互斥方案Sim Helm Chart 为应用 Secret 提供三种互斥的存储路径Chart 在模板渲染阶段会强制执行只能选其一。选型决策树如下原文出自 install-paths.mdIs this a production install? ├── No (dev / kind / minikube / dry-run) │ → Inline --set is fine. Skip to Path A. │ └── Yes │ Do you already manage secrets with Vault / AWS Secrets Manager / Azure Key Vault / GCP Secret Manager / 1Password Connect? │ ├── Yes → External Secrets Operator. Path C. │ └── No │ Do you use GitOps with Sealed Secrets, SOPS, or hand-managed Kubernetes Secrets? │ ├── Yes → Pre-existing Secret. Path B. │ └── No → Install ESO and go to Path C. (Dont skip to inline --set for prod — secrets land in helm get values and release history.)下表概括三种模式的区别同样来自 SKILL.md 的快速参考模式适用场景对应配置代码路径内联--set仅限开发 / kind / dry-run。值会泄漏进helm get valuesapp.env.KEY: ...预置 Kubernetes SecretGitOpsSealed Secrets / SOPS或手工管理 Secretapp.secrets.existingSecret.enabled: true.nameExternal Secrets Operator生产推荐Vault、AWS SM、Azure KV、GCP SM 等externalSecrets.enabled: truesecretStoreRefremoteRefs.app.KEY这三种模式对应用 Secret 而言是互斥的ESO 优先于内联existingSecret优先于内联。当 ESO 启用时Chart 会直接渲染失败——只要某个必需密钥BETTER_AUTH_SECRET、ENCRYPTION_KEY、INTERNAL_API_SECRET以及cronjobs.enabled时的CRON_SECRET既不在app.env中、也未映射到remoteRefs.app见 templates/_helpers.tpl 中的sim.validateExternalSecretCoverage定义。这些校验正是为了消灭渲染成功、运行时 CrashLoopBackOff的失败模式。路径 A内联--set仅限开发环境helm install sim ./helm/sim \ --namespace sim --create-namespace \ --set app.env.BETTER_AUTH_SECRET$(openssl rand -hex 32) \ --set app.env.ENCRYPTION_KEY$(openssl rand -hex 32) \ --set app.env.INTERNAL_API_SECRET$(openssl rand -hex 32) \ --set app.env.CRON_SECRET$(openssl rand -hex 32) \ --set postgresql.auth.password$(openssl rand -base64 24 | tr -d /)Chart 会生成一个名为release-app-secrets的 Secret其中包含app.envrealtime.env中所有非空键app与realtime两个 Deployment 通过envFrom挂载它对应模板见 templates/secrets-app.yaml。风险明确告知Secret 会出现在helm get values release与helm history release输出中任何能读取 release ConfigMapsh.helm.release.v1.release.vN的人都能恢复出密钥——它们以 base64 编码存储其中。路径 B预置 Kubernetes Secret先创建 Secret再让 Chart 引用它kubectl create namespace sim kubectl create secret generic sim-app-secrets --namespace sim \ --from-literalBETTER_AUTH_SECRET$BETTER_AUTH_SECRET \ --from-literalENCRYPTION_KEY$ENCRYPTION_KEY \ --from-literalINTERNAL_API_SECRET$INTERNAL_API_SECRET \ --from-literalCRON_SECRET$CRON_SECRET \ --from-literalAPI_ENCRYPTION_KEY$API_ENCRYPTION_KEY kubectl create secret generic sim-postgres-secret --namespace sim \ --from-literalPOSTGRES_PASSWORD$POSTGRES_PASSWORD# values.yaml app: secrets: existingSecret: enabled: true name: sim-app-secrets postgresql: auth: existingSecret: enabled: true name: sim-postgres-secret passwordKey: POSTGRES_PASSWORD关键限制Chart 无法透视你预置的 Secret 内容。若遗漏必需键Pod 会在运行时以CreateContainerConfigError: secret key X not found失败。必需键为BETTER_AUTH_SECRET、ENCRYPTION_KEY、INTERNAL_API_SECRET以及启用 cronjobs 时的CRON_SECRET。Secret 通过envFrom整体消费键名必须使用标准名称不支持键重映射这一点在 values.yaml 的app.secrets.existingSecret.name注释中明确声明。对于 GitOps请先将kubectl create secret ... --dry-runclient -o yaml的输出经kubesealSealed Secrets或sops加密后再提交绝不提交明文kubectl create secret输出。路径 CExternal Secrets Operator生产环境推荐首先把生成的值推送到你的密钥管理器中以 AWS Secrets Manager 为例aws secretsmanager create-secret --name sim/app/better-auth-secret --secret-string $BETTER_AUTH_SECRET aws secretsmanager create-secret --name sim/app/encryption-key --secret-string $ENCRYPTION_KEY aws secretsmanager create-secret --name sim/app/internal-api-secret --secret-string $INTERNAL_API_SECRET aws secretsmanager create-secret --name sim/app/cron-secret --secret-string $CRON_SECRET aws secretsmanager create-secret --name sim/app/api-encryption-key --secret-string $API_ENCRYPTION_KEY aws secretsmanager create-secret --name sim/postgresql/password --secret-string $POSTGRES_PASSWORD前置条件每个集群安装一次 ESOhelm repo add external-secrets https://charts.external-secrets.io helm install external-secrets external-secrets/external-secrets \ -n external-secrets --create-namespace创建指向你密钥管理器的ClusterSecretStore或命名空间级SecretStore各 provider 的认证接线参考 ESO 官方文档。然后在 values 中映射路径externalSecrets: enabled: true apiVersion: v1beta1 # v1beta1 works on ESO 0.7. Bump to v1 only on ESO 0.17. refreshInterval: 1h secretStoreRef: name: my-cluster-secret-store kind: ClusterSecretStore # or SecretStore for namespace-scoped remoteRefs: app: BETTER_AUTH_SECRET: sim/app/better-auth-secret ENCRYPTION_KEY: sim/app/encryption-key INTERNAL_API_SECRET: sim/app/internal-api-secret CRON_SECRET: sim/app/cron-secret # required iff cronjobs.enabled # 可选但通常要映射 API_ENCRYPTION_KEY: sim/app/api-encryption-key OPENAI_API_KEY: sim/providers/openai postgresql: password: sim/postgresql/password # required if postgresql.enabled externalDatabase: password: sim/postgresql/password # required if externalDatabase.enabled # 让 app.env 保持为空或只放 NEXT_PUBLIC_APP_URL 这类非敏感值 app: env: {}Remote ref 的两种形态实现见 templates/external-secret-app.yaml# 简写——只给 store 中的路径/键 BETTER_AUTH_SECRET: sim/app/better-auth-secret# 完整形态——透传 ESO 支持的任意字段 BETTER_AUTH_SECRET: key: sim/app/better-auth-secret property: value # 针对返回 JSON 的 store version: v3 # 固定某个版本 decodingStrategy: Base64 # 针对 base64 存储的值Fail-fast 行为当externalSecrets.enabledtrue时Chart 会在以下情况拒绝渲染任一必需密钥既未在app.env设置、也未映射到remoteRefs.app——错误信息会点名缺失的键某个键在app.env中设置了非空值但未映射到remoteRefs.app——该键会被静默丢弃导致容器启动时没有值。安装后验证同步状态kubectl get externalsecret -n sim kubectl describe externalsecret release-app-secrets -n sim # 状态应显示 SecretSyncedTrue四、从模板源码看密钥的流转链路为了让上文的三条路径落到实处这里从模板层面还原密钥的完整生命周期。1. Chart 管理 Secret 的渲染templates/secrets-app.yamlapp.env与realtime.env中所有非空、非 null的键被合并写入stringData然后两个 Deployment 通过envFrom挂载。合并逻辑刻意避免两个问题Sprig 的merge会把当作真实值因此模板先以realtime.env为底、再把app.env的非空值覆盖其上——既保证app.env对共享键的权威性又杜绝空字符串遮蔽真实值。2. Chart 计算值被排除DATABASE_URL、SOCKET_SERVER_URL、OLLAMA_URL、PII_URL这四个键由 Chart 在渲染期推导见 templates/_helpers.tpl 中sim.databaseUrl等定义被硬编码列表过滤、以内联 env注入容器而非写入 Secret——因为它们必须反映渲染时刻的解析结果。这也解释了为什么你不能直接覆盖DATABASE_URL它是 Chart 计算层values-model 中的 Layer 3只能通过修改postgresql.*或externalDatabase.*输入来间接改变。完整的四层 values 心智模型app.env/app.envDefaults/ Chart 计算值 /extraEnvVars详见 values-model.md。3. 安装时的强制校验templates/_helpers.tpl 的sim.validateSecrets当未使用existingSecret/ ESO 时BETTER_AUTH_SECRET、ENCRYPTION_KEY、INTERNAL_API_SECRET缺失直接fail还会拒绝默认占位值如CHANGE-ME-32-CHAR-SECRET-FOR-PRODUCTION-USECRON_SECRET在cronjobs.enabledtrue时必需。Postgres 密码除必填外还执行^[a-zA-Z0-9._-]$正则校验。4. CRON_SECRET 的消费方式templates/cronjobs.yaml每个 CronJob 容器通过secretKeyRef从应用 Secret 中读取CRON_SECRET随后在 shell 脚本中以Authorization: Bearer ${CRON_SECRET}头调用http://release-app:portpath——这就是为什么轮换CRON_SECRET只需helm upgrade下一次 cron 运行即使用新值。五、密钥轮换流程Sim 没有内置的轮换钩子标准流程如下生成新值并存好执行helm upgrade或让 ESO 在下次刷新时拾取变更重启受影响的工作负载强制重新读取envFromkubectl rollout restart deploy/sim-app deploy/sim-realtime -n sim对BETTER_AUTH_SECRET预期会出现一波401因为旧会话全部失效对ENCRYPTION_KEY/API_ENCRYPTION_KEY未经显式数据迁移不要轮换——已有密文将变得不可解密。六、绝对不要做的事红线清单不要跨环境复用同一密钥dev/staging/prod。某一层泄漏即全盘皆输。不要将密钥提交进 git即使是私有仓库。请使用 Sealed Secrets / SOPS / ESO。不要将密钥粘贴到 Slack、Discord、GitHub issues 或截图中。请像对待数据库密码一样对待它们。不要将密钥存进提交到 git 的values.yaml。这比--set更糟——values 文件会在历史记录中永久留存。不要用弱熵生成密钥。禁止date | md5、password123或开发者生日之类的值。只允许openssl rand或/dev/urandom。七、动手验证你的选择安装前后用以下命令确认密钥配置确实按预期落地# Pod 会挂载哪个 Secret helm template sim helm/sim -f my-values.yaml | grep -A2 envFrom: # 对于 ESOExternalSecret 是否渲染 helm template sim helm/sim -f my-values.yaml | grep -B1 -A10 kind: ExternalSecret # 对于 existingSecret是否引用了你预建的 Secret helm template sim helm/sim -f my-values.yaml | grep -E name: .*-app-secrets在任何helm install/helm upgrade之前建议先跑helm lint helm/sim --values user-values.yaml与helm template sim helm/sim --values user-values.yaml做静态校验——Chart 中的fail语句存在的意义就是把原本会演变成运行时CrashLoopBackOff的配置错误提前暴露在渲染阶段。延伸阅读安装路径选择决策树与三种路径详解values.yaml 心智模型env 与 envDefaults 的分层Sim Helm Chart 完整 values 参考密钥键位与注释应用 Secret 模板stringData 合并逻辑密钥校验与 ESO 覆盖校验模板ExternalSecret 渲染模板CronJob 模板CRON_SECRET 消费方式【免费下载链接】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），仅供参考