企业官网建设流程全解析

• 可观测性
• 开发工具
• 前端
• 后端

本文以仓库 scripts/dev_env/colima/README.md 为核心骨架，讲解如何在 Mac M1/M2（Apple Silicon）上通过 Colima 容器运行时本地运行 OpenReplay 全栈（含 Kubernetes 与 Ingress），涵盖 Colima 安装与启动、Helm 图表初始化、本地 DNS 配置、无 SSL 环境下的 Tracker 接入，以及两个高频故障（kubeconfig 复制失败、MinIO 崩溃循环）的解决方案。读完本文，你将掌握在 macOS 上零云依赖地拉起一套可复现会话录制的 OpenReplay 开发环境，并能独立处理本地部署中最常见的两类问题。

为什么本地部署需要 Colima

OpenReplay 是支持自托管的会话回放（Session Replay）、协同浏览（Cobrowsing）与产品分析平台。它的后端由 Go 微服务、Chalice API、ClickHouse、Kafka、Redis、MinIO 等组件构成，官方推荐的本地开发路径是将其部署进一个 Kubernetes 集群（仓库通过 Helm 图表编排，见 scripts/helmcharts）。

问题在于：Apple Silicon（M1/M2）Mac 的 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。这里要注意：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_INSTALL=1 SKIP_K8S_TOOLS=1 DOMAIN_NAME=openreplay.local bash -x init.sh

bash -x会打印脚本每一步执行过程，便于观察 helm 安装进度与报错点。

脚本内部发生了什么

结合 init.sh 源码，SKIP_*之外的步骤依次为：

1. 生成动态密码与写入域名（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；

2. 准备共享目录（set_permissions）：创建/openreplay/storage/nfs并chown 1001:1001，供各存储类 Pod 挂载；

3. 按序 Helm 安装三大 Chart（install_openreplay，init.sh）：

   • helm 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 目录。

4. 备份与 CLI 注册：脚本会把仓库与vars.yaml拷贝到/var/lib/openreplay，并安装openreplayCLI（init.sh），用于后续的版本管理与组件操作。

注意：vars.yaml是整个部署的配置中枢。部署完成后，如需修改域名、存储、资源配额等，编辑仓库内的 scripts/helmcharts/vars.yaml 后重新执行 init 脚本即可。

第三步：绑定本地 DNS

OpenReplay 的所有服务通过 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.ts：

if (!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_INSTALL=1 SKIP_K8S_TOOLS=1 DOMAIN_NAME=openreplay.local执行 scripts/helmcharts/init.sh → 绑定/etc/hosts→ 浏览器注册账号 → Tracker 开启__DISABLE_SECURE_MODE接入录制。期间若遇到 kubeconfig 导出失败，通过colima ssh手动导出配置即可绕开；若 MinIO 崩溃循环，则在 scripts/helmcharts/vars.yaml 中收紧其资源上限。掌握这套流程后，你便拥有了一套完全本地、可随时重启的 OpenReplay 开发与验证环境。

• 可观测性
• 开发工具
• 前端
• 后端