【免费下载链接】flexpriceUsage-based pricing and billing for developers Cloud or self-hosted ⚙️ No-code UI Realtime usage metering Credits top-ups Control feature access项目地址https://gitcode.com/gh_mirrors/fl/flexprice点击查看免费下载本文以 FlexPrice 开源仓库中 local-setup-troubleshooting.md 为骨架完整记录在 Apple SiliconM 系列Mac 上通过 OrbStack 内置 Kubernetes 与 Helm 运行 FlexPrice 全栈时遇到的 13 类真实故障——从 Bitnami 镜像拉取失败、Temporal 配置错位到 Kafka KRaft 仲裁破裂与 Helm pending-upgrade 死锁——并给出可复现的根因分析与修复方案。读完本文你将掌握如何在开发者笔记本上把内存预算压到 6 GiB 以内、用一条条helm upgrade命令把 FlexPriceAPI / Consumer / Worker / Temporal / ClickHouse / Kafka / Redis / PostgreSQL跑起来并具备独立排查同类问题的能力。一、环境基线这套方案针对什么运行环境本文所有结论都基于下表所示的实测环境脱离该基线时部分结论需要重新评估项目详情机器Apple SiliconM 系列aarch64操作系统macOS 15.x容器运行时OrbStack替代 Docker DesktopKubernetesOrbStack 内置 k8s 集群Helm4.x通过brew install helm安装Chartinternal/ee/infrastructure/helm/flexprice/Chart.yaml 声明 v1.0.0Temporalserver v1.30.3chart v0.74.0当前仓库中 Chart.yaml 的依赖为postgresql16.7.27、kafka32.4.3、redis20.13.4均来自 Bitnami charts 仓库以及temporal0.74.0来自go.temporal.io/helm-charts条件开关分别对应postgresql.enabled、kafka.enabled、redis.enabled、temporal.enabled四个顶层键。这套依赖是理解下文诸多故障镜像源、默认开启 Elasticsearch、配置模板格式的前提。二、快速上手TL;DR一条龙命令序列下面的命令序列是官方推荐的本地一键启动路径包含一次性环境配置、分阶段部署与最终验证。请注意分阶段部署是有意为之——先只拉起基础设施数据库、消息队列、Temporal跑完迁移再启动应用组件避免迁移 Job 与应用争抢资源。# 前置条件OrbStack 正在运行kubectl context 已指向 OrbStack k8s brew install helm cd helm/ # 即仓库的 internal/ee/infrastructure/helm/ # 一次性把 ingress 的 LoadBalancer IP 与三个域名写入 /etc/hosts sudo sh -c echo $(kubectl get svc -n ingress-nginx ingress-nginx-controller \ -o jsonpath{.status.loadBalancer.ingress[0].ip} 2/dev/null \ || echo 192.168.139.2) api.flexprice.local temporal.flexprice.local /etc/hosts # 一次性安装 ingress-nginxkind 部署清单同样适用于 OrbStack k8s kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/kind/deploy.yaml kubectl wait --namespace ingress-nginx \ --forconditionready pod \ --selectorapp.kubernetes.io/componentcontroller \ --timeout120s # 创建命名空间并部署阶段一仅基础设施全部应用组件关闭 kubectl create namespace flexprice --dry-runclient -o yaml | kubectl apply -f - helm dependency update ./flexprice helm upgrade --install flexprice ./flexprice \ -f ./flexprice/values.yaml -f ./values-local.yaml \ --set api.enabledfalse --set consumer.enabledfalse \ --set worker.enabledfalse --set frontend.enabledfalse \ --set migration.enabledfalse \ -n flexprice --wait --timeout 10m # 阶段二运行数据库迁移 helm upgrade flexprice ./flexprice \ -f ./flexprice/values.yaml -f ./values-local.yaml \ --set api.enabledfalse --set consumer.enabledfalse \ --set worker.enabledfalse --set frontend.enabledfalse \ --set migration.enabledtrue \ -n flexprice --wait --timeout 5m # 阶段三部署应用API Consumer Worker前端保持关闭 helm upgrade flexprice ./flexprice \ -f ./flexprice/values.yaml -f ./values-local.yaml \ --set api.enabledtrue --set consumer.enabledtrue \ --set worker.enabledtrue --set frontend.enabledfalse \ --set migration.enabledfalse \ -n flexprice --wait --timeout 5m # 验证 curl http://api.flexprice.local/health # → {status:ok}要点提醒values-local.yaml位于 internal/ee/infrastructure/helm/values-local.yaml是本地开发覆盖层官方脚本层面仓库还提供了provision.sh一键部署器./provision.sh默认创建 kind 集群flexprice-local支持--source local|ghcr、--skip-tests、--skip-frontend等参数详见 helm READMEkind 集群配置见 kind-cluster.yaml。三、13 类故障的完整排障手册以下每小节都遵循「症状 → 根因 → 修复」结构并补充了仓库源码中的依据与「需要进一步加固」的改进建议。1. 必填值未文档化——缺少密码时 chart 直接失败症状Error: secrets.existingSecret not set and clickhouse.password is empty根因当secrets.existingSecret为空时chart 会渲染自己的 Secret 并强制要求四个明文值postgres.passwordclickhouse.passwordauth.secretsecrets.encryptionKeysecret.yaml 模板 中对四个键逐一使用了 Helm 的required函数任何一个为空都会让渲染直接报错退出。而 values.yaml 中这些字段的默认值都是空字符串因此不带任何覆盖值直接helm install必败。修复values-local.yaml 中已经补齐全部四个值secrets: encryptionKey: dev-encryption-key-32-chars-here auth: provider: flexprice secret: dev-auth-secret-local postgres: password: flexprice123 clickhouse: password: flexprice123加固建议values.yaml中这四个键应标注# REQUIRED: set this注释并在 README 中显式点名。从模板源码看required的错误信息已经足够明确会指出具体缺哪个键但默认值仍为空字符串的现状对新手不友好。2. Bitnami 镜像从 Docker Hub 消失症状failed to pull image docker.io/bitnami/redis:7.4.3-debian-12-r0: not found failed to pull image docker.io/bitnami/kafka:...: not found根因Bitnami 于 2023 年 11 月从 Docker Hub 移除了所有带版本号的镜像 tag只保留:latestredis/postgresql 尚存Kafka 镜像则完全从 Docker Hub 消失。修复改用 ECR Public 的public.ecr.aws/bitnami/它保留了全部版本化 tagpostgresql: image: registry: public.ecr.aws redis: image: registry: public.ecr.aws kafka: image: registry: public.ecr.awsApple Silicon 特别说明ECR Public 上的 Bitnami 镜像只有 amd64 架构。OrbStack 会通过 Rosetta 2 透明运行 amd64 容器因此在 OrbStack k8s 上「开箱即用」但在原生 arm64 的 kind 集群上则无法运行见故障 3。加固建议values.yaml的三个 Bitnami 子 chart 默认registry应直接改为public.ecr.aws。仓库现状是values.yaml中注释示例提到了这一改动但实际默认值仍指向 Docker Hub。另外仓库 values-local.yaml 目前对 PostgreSQL / Redis 使用的是bitnamilegacy/postgresql:16.4.0-debian-12-r17、bitnamilegacy/redis:7.4.0-debian-12-r2的固定 tag 组合固定 tag 保证本地安装可复现避免latest漂移这也是规避镜像消失的另一种思路。3. kind 无法在 Apple Silicon 上运行症状[ERROR] preflight: running with swap on is not supported kube-scheduler refused connection kube-apiserver refused connection或强制DOCKER_DEFAULT_PLATFORMlinux/amd64时kubeadm init failed — k8s control plane binaries do not work under Rosetta根因ARM64 架构的 kind 集群Bitnami 的 amd64 镜像无法通过kind load docker-image正确载入工具只传输了一个 317 字节的 manifest而非真正的镜像层。AMD64 架构的 kind 集群Rosetta 2 不支持kubeadm与 k8s 控制平面所需的全部系统调用。修复 / 推荐方案在 Apple Silicon Mac 上改用OrbStack 内置 Kubernetes而非 kind在 OrbStack 设置 UI 中启用 k8s执行kubectl config use-context orbstack无需创建集群集群始终在运行。local-up.sh目前强制要求 kind脚本应增加--orbstack标志或自动探测 OrbStack。如果确实要用 kind使用 Intel Mac 或 Linux x86_64 机器kind 在这些平台上工作正常。4. OrbStack k8s 与 Docker 共享镜像仓库——无需 kind load影响在 OrbStack k8s 上运行时不需要kind load docker-image。任何docker build构建出的镜像会立即对 OrbStack k8s 的 Pod 可见——两者共享同一个 Docker socket。local-up.sh中原本的模式是docker build -t flexprice-app:local ... kind load docker-image flexprice-app:local --name $CLUSTER_NAME在 OrbStack 上应跳过kind load步骤。Helm values 已设置imagePullPolicy: IfNotPresentPod 会直接使用本地 daemon 中的镜像。修复更新local-up.sh探测 OrbStack 后跳过 kind loadif [[ $KUBECTL_CONTEXT orbstack ]]; then info OrbStack detected — skipping kind load (images shared via Docker daemon) else kind load docker-image flexprice-app:local --name $CLUSTER_NAME fi5. Bitnami 安全校验拒绝 ECR 镜像仓库症状Helm upgrade 表面成功exit code 0 是被管道掩盖的结果见故障 13但 Pod 报Unrecognized images: public.ecr.aws/bitnami/redis:7.4.3-debian-12-r0根因Bitnami chart 会校验镜像必须来自其认可的「安全仓库」白名单ECR Public 不在白名单中。修复global: security: allowInsecureImages: true只要 Bitnami 子 chart 使用 ECR Public 或任何非标准仓库values-local.yaml中就必须设置该选项。6. Temporal 默认部署 Elasticsearch——白白消耗 3 GiB症状阶段一helm install超时卡在等待resource StatefulSet/flexprice/elasticsearch-master not ready. Ready: 0/3即便 chart 已配置 PostgreSQL 作为 visibility 存储仍会部署 3 个 Elasticsearch 副本每个约请求 1 GiB 内存。根因temporalio/temporalchartv0.74.0默认elasticsearch.enabled: true。FlexPrice 的values.yaml正确配置了 Temporal 使用 PostgreSQL 做 visibility但没有显式关闭 Elasticsearch。修复temporal: elasticsearch: enabled: false7. Temporal server 忽略 chart 生成的 ConfigMap读取内嵌 Cassandra 配置症状Temporal 的四个 server Podfrontend、history、matching、worker全部 crash-loopLoading configuration from environment variables only Processing config file as template; filenameconfig_template_embedded.yaml Unable to load configuration: Persistence.DataStoresdefault.Cassandra.Hosts: zero value.根因Temporal server v1.30.3 改变了配置加载行为默认读取内嵌的配置模板该模板使用 Cassandra。Helm chart 会生成一份 PostgreSQL 配置的 ConfigMap 并挂载到/etc/temporal/config/config_template.yaml但除非显式告知 server 使用该文件否则 server 会忽略它。chart 支持两种配置模板格式dockerizeGo 模板{{ .Env.X }}语法用于旧版使用 dockerize 的镜像sprig{{ env X | quote }}语法 # enable-template标记用于 server v1.30。chart 默认configMapsToMount: dockerize对 v1.30 是错误的。修复temporal: server: setConfigFilePath: true # 注入 TEMPORAL_SERVER_CONFIG_FILE_PATH 环境变量 configMapsToMount: sprig # 使用 server v1.30 原生可处理的 sprig 模板验证修复后 server 日志应显示{msg:Starting server for services,value:{frontend:{}}}而不再是 Cassandra 报错。加固建议FlexPrice 的values.yaml中temporal:段应默认带上这两项设置chart 已固定server.image.tag: 1.30.3。仓库 values-local.yaml 中已经落实了该修复configMapsToMount: sprig、setConfigFilePath: true并同时关闭了prometheus、elasticsearch、grafana、cassandra、mysql、temporal 自带的postgresql复用 FlexPrice 自己的 postgresql 子 chartTemporal 的 default/visibility 两套 persistence 均指向flexprice-postgresql服务上的temporal与temporal_visibility数据库。8. 6 GiB 节点内存压力OOMKill 循环症状Pod尤其 PostgreSQL运行 1–3 分钟后反复被 OOMKillexit code 137。根因默认内存限额合计约为 6 GiB OrbStack 节点的127%ClickHouse4 GiBvalues.yaml 默认值Kafka controller × 3每个约 768 MiB合计 2.3 GiBTemporal 监控栈Prometheus Grafana Alertmanager约 1.5 GiB其余组件约 2 GiB。在values-local.yaml中应用的修复服务修复前修复后ClickHouse limit4 GiB1 GiBKafka controller 副本数31Kafka controller limit768 MiB512 MiBKafka broker limit不限512 MiBPostgreSQL limit192 MiB512 MiBPrometheus启用禁用Grafana启用禁用Elasticsearch启用禁用结果内存限额从约 127% 压到约 101%节点 MemoryPressure 解除。加固建议values-local.yaml应作为带预配置资源限额的模板随仓库发布。当前默认值适合生产但让 chart 在开发者笔记本上几乎无法运行。对照仓库当前 values-local.yaml可以看到已落实的瘦身ClickHouse standalone 模式 limit 2 GiB / request 1 GiBKafka 关闭 Bitnami 子 chart改用 confluentinc/cp-kafka 手写模板单副本、internal 组件 limit 1 GiB / request 512 MiBAPI/Consumer 各 1 副本且 limit 512 MiBWorker limit 256 MiBTemporal server limit 512 MiB。9. Temporal schema 迁移期间 PostgreSQL 被 OOMKill症状当flexprice-temporal-schema-*Job 的 init 容器对 postgres 执行 SQL 迁移运行时PostgreSQL Pod 反复 OOMKillexit code 137。根因Bitnami PostgreSQL chart 默认只有 192 MiB 内存限额。Temporal 的 schema 迁移工具会并发运行 SQL 操作6 个 init 容器部分并行PostgreSQL 需要远超 192 MiB 的内存。修复postgresql: primary: resources: requests: memory: 256Mi limits: memory: 512Mi注意这是一个级联问题——若 PostgreSQL 在 Temporal schema Job 的 init 容器运行期间被 OOMKill该 init 容器随即失败。Job 会按指数退避重试PostgreSQL 恢复后重试即可成功但这会制造令人困惑的失败噪音。10. 缩减副本后 Kafka controller 仲裁破裂症状把kafka.controller.replicaCount从 3 减到 1 后唯一的 kafka-controller Pod 崩溃UnknownHostException: flexprice-kafka-controller-1.flexprice-kafka-controller-headless... UnknownHostException: flexprice-kafka-controller-2.flexprice-kafka-controller-headless... ERROR [RaftManager id0] Graceful shutdown of RaftClient failed: TimeoutException根因Kafka controller 的 PVC 中存储的 KRaft 元数据仍引用全部三个 controller ID0、1、2。单个 controller 无法组成仲裁3 个节点需要多数即 2 个于是持续尝试联系缺失的 controller。修复删除过期的 PVC 以强制重新初始化kubectl delete pod flexprice-kafka-controller-0 -n flexprice --force --grace-period0 kubectl delete pvc>helm status flexprice -n flexprice | grep STATUS # STATUS: pending-install (或 pending-upgrade)修复定位并删除处于 pending 状态的 helm release Secretkubectl get secret -n flexprice -l ownerhelm,nameflexprice -o name # 找到 label 中 statuspending-install 或 pending-upgrade 的那个 kubectl get secret sh.helm.release.v1.flexprice.v3 \ -n flexprice -o jsonpath{.metadata.labels.status} # 删除以解除锁 kubectl delete secret sh.helm.release.v1.flexprice.v3 -n flexprice12. Ingress 主机名不匹配症状http://api.flexprice.local/health返回 nginx 404尽管 API Pod 是健康的。根因values.yaml中 ingress 默认主机为flexprice.example.com。文档/脚本要求把api.flexprice.local加入/etc/hosts但 ingress 并未配置匹配该主机名。在values-local.yaml中修复ingress: hosts: - host: api.flexprice.local paths: - path: / pathType: Prefix temporalIngress: host: temporal.flexprice.local关于路由前缀的说明API 的健康检查端点是/health而非/v1/health。ingress 把/下所有路径都路由到 API 服务因此http://api.flexprice.local/health→{status:ok}✅http://api.flexprice.local/v1/health→ 404不存在该路由✅ 符合预期对照仓库当前 values-local.yamlingress、frontendIngresshost:flexprice.local、temporalIngresshost:temporal.flexprice.local三个 Ingress 块均已启用并指向 nginx class。13. local-up.sh 管道退出码被掩盖症状即使 helm 返回错误local-up.sh仍显示成功打印 Phase 1 complete。根因helm upgrade ... 21 | tail -5; echo exit: $?echo exit: $?捕获的是tail的退出码而非 helm 的。只要tail成功打印了输出无论 helm 是否失败tail都返回 0。修复方案一使用set -o pipefail脚本头部已有但只作用于最外层管道或显式捕获退出码helm upgrade ... 21 | tee /tmp/helm-out.log HELM_EXIT${PIPESTATUS[0]} tail -5 /tmp/helm-out.log [[ $HELM_EXIT -eq 0 ]] || die helm upgrade failed (exit $HELM_EXIT)方案二干脆不把 helm 输出接管道helm upgrade ... || die helm upgrade failed四、加固路线图把本地安装推向「一键可用」必须修复在宣称「一键」之前让local-up.sh支持 OrbStack——跳过 kind 集群创建与kind load增加自动探测或--orbstack标志随仓库发布values-local.yaml模板当前已提交于 internal/ee/infrastructure/helm/values-local.yaml预配置全部必填密码、ECR 镜像仓库、Temporal 配置与资源限额修复values.yaml中 Bitnami 镜像仓库默认值——postgresql.image.registry、redis.image.registry、kafka.image.registry默认改为public.ecr.aws修复values.yaml的 Temporal 配置默认值——由于 chart 固定了 server v1.30.3应默认设置temporal.server.setConfigFilePath: true与temporal.server.configMapsToMount: sprig修复内存限额——ClickHouse 4 GiB 对本地开发过高默认应为 1 GiB 或参数化在 README 中文档化必填值——显式点名postgres.password、clickhouse.password、auth.secret、secrets.encryptionKey。锦上添花在local-up.sh中加入/etc/hosts指引——探测 OrbStack ingress IP 并打印确切的echo命令Temporal UI ingress——在 values-local.yaml 中加入temporalIngress并实测健康检查脚本——提供verify-local.sh逐个访问各服务健康端点并报告 pass/fail清理脚本——helm uninstall flexprice -n flexprice kubectl delete namespace flexprice并清理 PVC。五、OrbStack 专属注意事项OrbStack Kubernetes IPOrbStack 内置 k8s 集群的 ingress IP 为192.168.139.2可能因环境而异用kubectl get svc -n ingress-nginx确认。写入/etc/hosts192.168.139.2 api.flexprice.local temporal.flexprice.local flexprice.localOrbStack Docker / k8s 镜像共享宿主机构建的 Docker 镜像可立即被 OrbStack k8s 的 Pod 使用无需kind load。原因是 OrbStack k8s 与 Docker 共享同一个 containerd/OCI 镜像存储。Rosetta 2 与 amd64 容器OrbStack 通过 Apple 的 Rosetta 2 翻译层透明运行 amd64 容器镜像。这对用户态进程数据库、消息代理、应用服务器有效但对 k8s 控制平面本身无效——这正是 amd64 kind 集群无法在 Apple Silicon 上运行的原因。内存分配OrbStack 默认虚拟机获取宿主机约 50% 的内存。16 GiB 的 MacBook 上 VM 约分到 8 GiB全套优化后的 FlexPrice 栈在 6 GiB 内可舒适运行。OrbStack VM 内存在Settings → Resources中配置。端口 80/443OrbStack k8s 直接在宿主机上暴露 ingress-nginx controller无需端口转发。ingress load balancer 会拿到真实 IP可直接写入/etc/hosts。六、常用速查命令# 查看全部 Pod kubectl get pods -n flexprice # API 健康检查 curl http://api.flexprice.local/health # Temporal UI open http://temporal.flexprice.local # 直连 PostgreSQL kubectl exec -it flexprice-postgresql-0 -n flexprice -- \ psql -U flexprice -d flexprice # 直连 ClickHouse kubectl exec -it flexprice-clickhouse-0 -n flexprice -- \ clickhouse-client --userdefault --passwordflexprice123 --databaseflexprice # 查看 API 日志 kubectl logs -n flexprice -l app.kubernetes.io/componentapi -f # 镜像重建后重启应用 Pod kubectl rollout restart deployment flexprice-api flexprice-consumer flexprice-worker -n flexprice # 解除 helm pending 锁 kubectl delete secret -n flexprice \ $(kubectl get secret -n flexprice -l ownerhelm,nameflexprice \ -o jsonpath{.items[?(.metadata.labels.statuspending-upgrade)].metadata.name}) # 卸载清理 helm uninstall flexprice -n flexprice kubectl delete namespace flexprice七、故障分类速览#故障一句话根因核心修复点1必填值缺失Secret 模板对 4 个键使用required且默认值为空在 values 覆盖文件中补齐密码与密钥2Bitnami 镜像 404Docker Hub 已移除版本化 tag改用public.ecr.aws仓库3kind 无法启动Rosetta 不支持 k8s 控制平面 / ARM 无法 load amd64 镜像改用 OrbStack 内置 k8s4kind load 多余OrbStack 与 Docker 共享镜像存储检测到 orbstack 时跳过 kind load5镜像被安全校验拒绝Bitnami 白名单不含 ECRglobal.security.allowInsecureImages: true6白耗 3 GiBTemporal chart 默认开 Elasticsearchtemporal.elasticsearch.enabled: false7Temporal 崩溃循环v1.30 读取内嵌 Cassandra 模板setConfigFilePath: trueconfigMapsToMount: sprig8内存 OOMKill默认限额合计超节点 127%压 ClickHouse/Kafka、关 Prometheus/Grafana/ES9PG 迁移期 OOM192 MiB 限额扛不住并发迁移PostgreSQL 限额升至 256Mi/512Mi10Kafka 仲裁破裂旧 PVC 元数据仍引用 3 个 controller删除过期 PVC 重新初始化11helm 死锁超时遗留 pending 状态删除对应 release Secret12Ingress 404默认主机与本地域名不匹配覆盖 ingress hosts 与 temporalIngress host13退出码被掩盖管道让$?变成 tail 的退出码PIPESTATUS[0]或set -o pipefail八、延伸阅读本地 kind 工作流与provision.sh参数 internal/ee/infrastructure/helm/README.md全部 values 键的内联文档资源限额、ingress、Temporal、迁移步骤等 internal/ee/infrastructure/helm/flexprice/values.yaml本地开发覆盖层已落实本文多数修复 internal/ee/infrastructure/helm/values-local.yamlSecret 渲染与必填校验逻辑 internal/ee/infrastructure/helm/flexprice/templates/app/secret.yamlchart 依赖与版本 internal/ee/infrastructure/helm/flexprice/Chart.yamlkind 集群配置端口映射到 ingress-nginx internal/ee/infrastructure/helm/kind-cluster.yaml赞分享【免费下载链接】flexpriceUsage-based pricing and billing for developers Cloud or self-hosted ⚙️ No-code UI Realtime usage metering Credits top-ups Control feature access项目地址https://gitcode.com/gh_mirrors/fl/flexprice点击查看免费下载相关推荐OpenShell RPM 部署故障排查与升级实战指南OpenShell RPM 部署故障排查与升级实战指南 本指南面向在 Fedora/RHEL 系系统上通过 RPM 包部署 OpenShell 网关gatew人工智能AI Agent自主智能体Agent 沙箱AI 安全治理形式化验证后端CLIOpenJarvis macOS 安装完全指南Apple Silicon 与 Intel 上的本地 AI 部署实战OpenJarvis macOS 安装完全指南Apple Silicon 与 Intel 上的本地 AI 部署实战 OpenJarvis 是面向个人设备的本地一个 Skill 文件、33 类模式Humanizer 一次改写去掉 AI 写作痕迹一个 Skill 文件、33 类模式Humanizer 一次改写去掉 AI 写作痕迹 Humanizer 是给用 AI 写初稿的人准备的写作去 AI 化 agAI 技能AI 写作上一篇Minimal Mistakes 按文章关闭评论comments: false Front Matter 的优先级机制与源码实现解析下一篇Apache Druid Coordinator 服务深度解析段管理、负载均衡与自动压缩机制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考