在 Apple Silicon Mac 上用 Colima 本地部署 OpenReplay：从环境搭建到问题排查的完整指南

可观测性开发工具前端后端【免费下载链接】openreplaySession replay, cobrowsing and product analytics you can self-host. Best for reproducing issues and iterating on your product.项目地址https://gitcode.com/gh_mirrors/op/openreplay点击查看免费下载本文以仓库 scripts/dev_env/colima/README.md 为核心骨架讲解如何在 Mac M1/M2Apple Silicon上通过 Colima 容器运行时本地运行 OpenReplay 全栈含 Kubernetes 与 Ingress涵盖 Colima 安装与启动、Helm 图表初始化、本地 DNS 配置、无 SSL 环境下的 Tracker 接入以及两个高频故障kubeconfig 复制失败、MinIO 崩溃循环的解决方案。读完本文你将掌握在 macOS 上零云依赖地拉起一套可复现会话录制的 OpenReplay 开发环境并能独立处理本地部署中最常见的两类问题。为什么本地部署需要 ColimaOpenReplay 是支持自托管的会话回放Session Replay、协同浏览Cobrowsing与产品分析平台。它的后端由 Go 微服务、Chalice API、ClickHouse、Kafka、Redis、MinIO 等组件构成官方推荐的本地开发路径是将其部署进一个 Kubernetes 集群仓库通过 Helm 图表编排见 scripts/helmcharts。问题在于Apple SiliconM1/M2Mac 的 Docker Desktop 默认运行 arm64 镜像而 OpenReplay 大量组件镜像包括 k3s 所依赖的基础设施以 x64 为主。直接运行会出现架构不兼容导致的拉取失败或启动异常。Colima 目录下专门存放了 Colima 与 Vagrant 两套本地开发环境方案其中 scripts/dev_env/colima/README.md 即本文的依据。第一步安装 Colima 与 Kubernetes 工具链原文档推荐通过 Homebrew 安装其中 Colima 使用--head安装最新开发版以获取对新版 macOS 与 Docker 的兼容修复brew install --head colima brew install docker kubectl helm k9s stern工具作用colima容器运行时与 Kubernetes 运行时--head为开发版docker本地构建与推送镜像、管理容器kubectl操作 Colima 内置的 Kubernetes 集群helm安装 OpenReplay 的 Helm 图表toolings / databases / openreplayk9s终端 Kubernetes 管理器便于实时观察 Pod 状态stern多 Pod 日志聚合工具排查微服务日志时非常高效安装完成后启动 Colima 并内置 Kubernetes。这里要注意OpenReplay 的 init 脚本默认会尝试安装 k3s但本地开发时集群由 Colima 提供因此必须跳过 k3s 安装见下文 init.sh 参数说明。启动命令原文档原样保留colima start --with-kubernetes --cpu 2 --memory 8 -p openreplay参数含义--with-kubernetes在虚拟机内启用内置 k3s为 OpenReplay 的 Helm 部署提供集群--cpu 2 --memory 8分配 2 核 CPU、8 GB 内存。OpenReplay 组件较多数据库 应用 Ingress若 Mac 内存充裕可适当提高例如--memory 12-p openreplay为该 Colima 实例命名后续colima ssh -p openreplay、colima stop -p openreplay等操作都需要用该 profile 名区分。 安装 docker CLI 后Docker 的默认 context 会被切换为 Colima。执行docker context ls可以查看当前 context若需要切回 Docker Desktop 等可用docker context use name切换。第二步拉取仓库并运行 Helm 初始化脚本拉取代码原文档要求克隆dev分支当前开发分支包含最新的 Helm 图表改动git clone https://github.com/openreplay/openreplay -b dev cd openreplay/scripts/helmcharts理解 init.sh 的开关与环境变量初始化脚本为 scripts/helmcharts/init.sh其main函数init.sh通过conditional_step读取一组SKIP_*环境变量来决定执行哪些阶段SKIP_K8S_INSTALL1 SKIP_K8S_TOOLS1 DOMAIN_NAMEopenreplay.local bash -x init.sh环境变量作用对应 init.sh 源码本场景为何设置SKIP_K8S_INSTALL1跳过install_k8s不再执行curl -sL https://get.k3s.io ...的 k3s 安装init.sh脚本会输出Skipping Kubernetes installation.集群已由 Colima 的--with-kubernetes提供SKIP_K8S_TOOLS1跳过install_tools不安装 kubectl / helm 等 K8s 工具输出Skipping Kubernetes tools installation.已通过brew install装好DOMAIN_NAMEopenreplay.local在create_passwords阶段写入vars.yaml的global.domainNameinit.shIngress 与前端脚本地址均依赖它本地虚拟域名与后续/etc/hosts绑定SKIP_ROTATE_SECRETS可选跳过密码/密钥生成不需要时可不设置SKIP_OR_INSTALL可选跳过 OpenReplay 本体安装仅需基础设施时使用bash -x会打印脚本每一步执行过程便于观察 helm 安装进度与报错点。脚本内部发生了什么结合 init.sh 源码SKIP_*之外的步骤依次为生成动态密码与写入域名create_passwords通过templater -i vars.yaml -o vars.yaml将 scripts/helmcharts/vars.yaml 中的{{ randAlphaNum 20 }}占位符渲染为随机密钥PostgreSQL、MinIO 的 accessKey/secretKey、JWT 系列密钥等再用yq把DOMAIN_NAME写入global.domainName准备共享目录set_permissions创建/openreplay/storage/nfs并chown 1001:1001供各存储类 Pod 挂载按序 Helm 安装三大 Chartinstall_openreplayinit.shhelm upgrade --install toolings ./toolings -n app—— 基础设施工具Ingress Controller、Kyverno 等helm upgrade --install databases ./databases -n db—— ClickHouse、Kafka、Redis、MinIO、PostgreSQL 等数据层helm upgrade --install openreplay ./openreplay -n app—— OpenReplay 应用本体api、frontend、chalice、http、ender、assist 等。三个 Chart 分别位于仓库的 scripts/helmcharts/toolings、scripts/helmcharts/databases、scripts/helmcharts/openreplay 目录。备份与 CLI 注册脚本会把仓库与vars.yaml拷贝到/var/lib/openreplay并安装openreplayCLIinit.sh用于后续的版本管理与组件操作。注意vars.yaml是整个部署的配置中枢。部署完成后如需修改域名、存储、资源配额等编辑仓库内的 scripts/helmcharts/vars.yaml 后重新执行 init 脚本即可。第三步绑定本地 DNSOpenReplay 的所有服务通过 Ingress 按域名路由例如 scripts/helmcharts/openreplay/charts/api/templates/ingress.yaml 中host: {{ .Values.global.domainName }}因此在本地必须把该域名解析到本机sudo vim /etc/hosts 127.0.0.1 openreplay.local这里使用的域名必须与DOMAIN_NAME保持一致。若你换了域名例如or.local此处也要同步修改否则访问http://openreplay.local将无法命中任何 Ingress 规则。第四步访问并注册账号浏览器打开 http://openreplay.local首次访问会进入注册页创建一个管理员账号即可开始使用。由于本地环境没有 SSL需要留意OpenReplay 前端 Chart 会根据global.ORSecureAccess决定注入到页面的 Tracker 脚本地址使用https还是http见 scripts/helmcharts/openreplay/charts/frontend/templates/deployment.yaml。本地无证书场景下务必使用http://访问。第五步让 Tracker 在无 SSL 本地环境正常工作Tracker 默认启用“安全模式”检查只有页面运行在https:协议下才会开始采集。这一逻辑写在 tracker/tracker/src/main/index.tsif (!options.__DISABLE_SECURE_MODE location.protocol ! https:) { console.error( OpenReplay: Your website must be publicly accessible and running on SSL ... You can disable this check by setting __DISABLE_SECURE_MODE option to true ..., ) return }也就是说默认不配置该选项非 HTTPS 页面会直接打印错误并停止初始化无法录制__DISABLE_SECURE_MODE: true跳过该检查允许在本地 HTTP 环境采集。原文档此处的写法为__DISABLE_SECURE_MODE: false从源码逻辑看应设为true才能真正禁用安全模式false或省略等价于默认的安全检查。在初始化 Tracker 时传入new Tracker({ projectKey: PROJECT_KEY, ingestPoint: http://openreplay.local/ingest, __DISABLE_SECURE_MODE: true, })仓库内的单元测试与测试脚手架如 tracker/tracker/src/tests/main.test.ts、tracker/tracker-testing-playground/src/tracker.ts均以__DISABLE_SECURE_MODE: true运行印证了该选项在本地开发中的标准用法。⚠️ 该选项只应在本机测试时开启安全检查的意义在于生产站点必须使用 HTTPS否则资源会被浏览器视为混合内容而无法正确回放。官方文档的 JavaScript SDK 安全章节对此有专门说明。故障排查一Colima 的 kubeconfig 复制报错现象执行colima start --with-kubernetes或后续 kubectl 操作时出现类似error at updating config: error fetching kubeconfig on guest: exit status 1原因Colima 无法自动把虚拟机内的 k3s 配置导出到宿主机常见于 SSH/配置同步异常或 k3s 服务未就绪。解决思路手动从虚拟机内导出 kubeconfig 并让 kubectl 使用它。# 1. 进入 openreplay 虚拟机 colima ssh -p openreplay # 2. 查看并复制 k3s 配置内容注意原文档中 cat echo;... 为笔误正确命令如下 cat /etc/rancher/k3s/k3s.yaml # 复制全部输出然后 exit 退出虚拟机 # 3. 在宿主机保存该配置 cd ~/.kube || ( mkdir ~/.kube cd ~/.kube) vim openreplay-local.yaml # 粘贴刚才复制的内容并保存 # 4. 让 kubectl 使用该配置文件 export KUBECONFIG~/.kube/openreplay-local.yaml之后运行kubectl get nodes应能看到 Colima 提供的节点若后续终端都要使用可把export KUBECONFIG~/.kube/openreplay-local.yaml写入 shell 的 profile如~/.zshrc。故障排查二MinIO 崩溃循环CrashLoopBackOff现象部署后kubectl get pods -n db中minio-*长期处于 CrashLoopBackOff。原因本地 Mac 资源有限MinIO 启动时申请的资源超出 Colima 虚拟机可提供的配额尤其是仅分配 2 核/8 GB 时或默认配置在本地环境不满足启动条件。解决思路在 scripts/helmcharts/vars.yaml 中为 MinIO 显式设置资源上限避免其请求超额资源# 在 vars.yaml 中 minio: resources: limits: cpu: 512m该字段会透传到 scripts/helmcharts/databases/charts/minio/values.yaml 的resources定义默认limits: {}为空即不设限制。修改后重新运行bash -x init.sh或仅对 databases Chart 执行helm upgrade --install databases ./databases -n db -f ./vars.yaml使配置生效。同理若 ClickHouse 或 Kafka 等组件也因资源不足频繁重启可参照 scripts/helmcharts/vars.yaml 中 PostgreSQL 的注释示例requests/limits的cpu/memory写法为对应组件设置配额。部署后的日常管理查看与管理组件用k9s -n app/k9s -n db观察 Pod 状态stern -n app聚合查看微服务日志重启组件仓库提供了 scripts/helmcharts/local_deploy.sh支持bash local_deploy.sh app单独重编并滚动重启某个组件frontend、api、http、sink、storage等对本地迭代开发非常有用例如bash local_deploy.sh frontend配置文件初始化脚本会把最终的 scripts/helmcharts/vars.yaml 备份到/var/lib/openreplay/vars.yaml同时安装了openreplayCLI可执行openreplay -h查看版本升级等管理命令停止环境colima stop -p openreplay可整体暂停虚拟机需要时colima start -p openreplay再次拉起。小结在 Apple Silicon Mac 上通过 Colima 本地运行 OpenReplay 的完整链路是brew安装 Colima 与 K8s 工具链 → 以--with-kubernetes启动命名 profile → 用SKIP_K8S_INSTALL1 SKIP_K8S_TOOLS1 DOMAIN_NAMEopenreplay.local执行 scripts/helmcharts/init.sh → 绑定/etc/hosts→ 浏览器注册账号 → Tracker 开启__DISABLE_SECURE_MODE接入录制。期间若遇到 kubeconfig 导出失败通过colima ssh手动导出配置即可绕开若 MinIO 崩溃循环则在 scripts/helmcharts/vars.yaml 中收紧其资源上限。掌握这套流程后你便拥有了一套完全本地、可随时重启的 OpenReplay 开发与验证环境。赞分享可观测性开发工具前端后端【免费下载链接】openreplaySession replay, cobrowsing and product analytics you can self-host. Best for reproducing issues and iterating on your product.项目地址https://gitcode.com/gh_mirrors/op/openreplay点击查看免费下载相关推荐在Apple Silicon Mac上快速搭建Android开发环境的完整指南在Apple Silicon Mac上快速搭建Android开发环境的完整指南 Android Emulator M1 Preview是Google专为ApplApple Silicon Mac上的Vivado完整部署指南Apple Silicon Mac上的Vivado完整部署指南 在基于Arm架构的Apple Silicon Mac上运行Xilinx Vivado设计套件曾经在 Apple Silicon Mac 上使用 Apple Containers 部署 Manifest 网关完整实战指南在 Apple Silicon Mac 上使用 Apple Containers 部署 Manifest 网关完整实战指南 本指南讲解如何在 Apple siAI 应用LLMOps可观测性创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考