【免费下载链接】ess-helmElement Server Suite Community Edition项目地址https://gitcode.com/gh_mirrors/es/ess-helm点击查看免费下载Element Server Suite Communityess-helm简称 ESS Helm是一个基于 Helm Chart 在 Kubernetes 上部署完整 Matrix 服务栈的开源项目内置 Synapse、Element Web、Matrix RTC 等组件。本文是面向新手运维者的 ESS Helm 故障排查宝典将视频通话失败、SFU CrashLoopBackOff 等 8 个常见错误整理成一份可直接照做的排查清单并附上关键配置参数与官方文档路径帮助你在遇到问题时快速定位根因。在开始排查之前先了解各组件如何协同工作会有很大帮助请求经由 Ingress 进入集群后由 HAProxy 分发到 Synapse 与 Matrix Authentication ServiceMAS视频通话则由 Element CallMatrix RTCAuthorisation Service SFU负责。完整的组件关系可参考 docs/architecture.md 与架构图 docs/assets/images/Architecture.png。 8 大常见错误速查表#故障现象一句话根因排查入口1发起视频通话报MISSING_MATRIX_RTC_FOCUSwell-known 文件缺失或 RTC 组件被禁用检查matrixRTC.enabled、.well-known/matrix/client2SFU Pod 反复重启且无任何日志STUN 解析公网 IP 失败改用手动 IP 或更换 STUN 服务器3Authoriser 日志报Failed to look up user infoPod 无法访问联邦 API检查synapse.ingress.host与 hostAliases4信令通了但画面/声音连不上UDP 媒体通道未打通用netcat与浏览器 WebRTC 工具验证5启动报Address family not supported by protocol集群内核不支持 IPv6设置networking.ipFamily: ipv46K3s 上大文件上传超时Traefik 默认超时时间过短调大 Traefik 的 read/write 超时7helm install/upgrade中途失败check-config 钩子拦截了非法配置修正synapse.additional配置8装完服务器却无法创建账号注册默认关闭用mas-cli manage register-user建用户所有条目均可在 docs/troubleshooting.md 中找到详细说明下文逐条展开。1️⃣ 视频通话无法接通MISSING_MATRIX_RTC_FOCUS错误现象在 Element Web 或 Element X 中发起视频通话客户端弹出错误码MISSING_MATRIX_RTC_FOCUS。原理Matrix RTC 在建立通话前必须通过https://server name/.well-known/matrix/client这个 well-known 文件且必须是浏览器信任的 HTTPS获取 SFU 与 Authorisation Service 的部署位置。任何一环断了通话就无法建立。排查清单按顺序逐项确认确认你的 values 中没有matrixRTC.enabled: false默认启用确认没有wellKnownDelegation.enabled: false默认启用用浏览器访问https://server name/.well-known/matrix/client应返回 JSON且其中包含org.matrix.msc4143.rtc_foci字段核对该字段中livekit_service_url的值是否等于https://matrixRTC.ingress.host访问https://matrixRTC.ingress.host/sfu/get正常应返回 HTTP 405 状态码说明 SFU 服务在监听。 如果你的 serverName 已做公网 DNS 解析可以先用联邦测试工具验证域名可达性与 TLS 证书是否被信任——很多通话失败其实是证书链不完整导致的。2️⃣ SFU 陷入CrashLoopBackOff且没有任何日志现象kubectl get pods中 Matrix RTC SFU 的 Pod 反复重启状态显示CrashLoopBackOff但kubectl logs空空如也。根因SFU 启动时会先做一次 STUN 请求来解析自己的公网 IP默认使用 Google STUN 服务器若请求失败进程直接退出来不及打印日志。解决方法三选一确保集群能访问外部 STUN 服务器常见于防火墙/NAT 限制出口流量更换 STUN 服务器通过matrixRTC.sfu.additional注入stun.yaml配置rtc.stun_servers绕过 STUN设置matrixRTC.sfu.useStunToDiscoverPublicIP: false并可选地用matrixRTC.sfu.manualIP指定一个能被客户端 UDP 包路由到的公网 IP。三种 IP 宣告模式Host IP / Manual IP / STUN的适用场景在 docs/advanced.md 的 Networking 一节有详细对比例如 Manual IP 模式适合 SFU 位于 LoadBalancer 之后的场景。3️⃣ Authoriser 日志出现Failed to look up user info现象Matrix RTC Authorisation Service 的日志中反复出现Failed to look up user info或提示无法连接8448端口。原理Authoriser 收到通话请求时需要通过 Matrix 联邦 API/.well-known/matrix/server与/_matrix/federation/v1/openid/userinfo等端点查询谁在尝试加入会议集群内外链路任一不通都会失败。排查清单确认wellKnownDelegation未被禁用在集群外访问https://server name/.well-known/matrix/server确认返回的m.server值等于synapse.ingress.host加:443访问https://synapse.ingress.host/_matrix/key/v2/server应返回 JSON若集群外全部正常、仅 Pod 内访问失败可为 Authoriser 配置matrixRTC.hostAliases把相关主机名直接指向 Ingress Controller Service 的 ClusterIP若你使用的是自签证书不在系统默认信任库中需通过matrixRTC.extraEnv注入LIVEKIT_INSECURE_SKIP_VERIFY_TLS环境变量以跳过 TLS 校验。4️⃣ 信令通了但媒体不通WebRTC / UDP 调试方法现象通话能建立信令通道正常但对方看不到画面、听不到声音或延迟极高。原理SFU 的媒体流量分两段——客户端先经 HTTPS/Websocket 打开通道建立信令随后客户端与 SFU 各自宣告访问 IP走UDP建立真正的媒体连接。UDP 链路常被防火墙、NAT 配置挡住。调试三板斧先看客户端是否开启 ElementCall房间设置 → VoIP → 确认Enable ElementCall已打开用浏览器 WebRTC 工具看连接状态Chrome 打开chrome://webrtc-internalsFirefox 打开about:webrtc。重点看 ICE Connection State应为new → completed与 Signaling state应最终回到stable若某条连接卡在failed对照候选 IP 判断是 STUN 解析错了还是 SFU 宣告的 IP 不可达用 netcat 验证 UDP/TCP 端口可达客户端侧执行nc -vnzu SFU IP 30002 # UDP mux 端口 nc -vnz SFU IP 30001 # TCP 端口若端口测试失败问题通常在集群节点端口NodePort或云上安全组可参考 charts/matrix-stack/ci/fragments/matrix-rtc-exposed-services.yaml 调整暴露方式。5️⃣Address family not supported by protocolIPv6 报错现象某个组件 Pod 启动失败容器日志中出现Address family not supported by protocol。根因ESS Helm 默认让各组件同时监听 IPv4 与 IPv6。在 IPv6 被禁用如系统启动时关闭或被内核编译裁剪掉的集群上双栈绑定会直接报错。解决在 values 中显式指定单栈即可networking: ipFamily: ipv46️⃣ K3s 上大文件上传超时Traefik 调优现象使用 K3s 单节点部署时向 ESS 上传较大的媒体文件总是中途超时失败。根因K3s 自带的 Traefik 默认的 read/write/idle 超时时间偏短扛不住大文件传输。解决在/var/lib/rancher/k3s/server/manifests下创建或补充traefik-config.yaml通过HelmChartConfig调大web与websecure两个入口的respondingTimeouts.readTimeout、writeTimeout、idleTimeout。完整的 YAML 示例见 docs/advanced.md 的 Configuring Traefik ingress timeouts when using K3s 一节照抄替换数值即可K3s 会自动应用该清单。7️⃣helm install/upgrade中途失败check-config 钩子拦截现象执行helm upgrade --install时命令失败输出里能看到 Synapse 配置校验check-config相关的报错而非 Pod 启动失败。原理Chart 内置了 Synapse Check Config Hook——在应用变更前先运行 Synapse 的synapse.config校验命令确保配置合法。你通过synapse.additional注入的自定义 YAML 若缩进错误、字段名拼错就会被这一步拦下。这其实是保护机制在配置生效前发现错误好过线上起不来。解决步骤仔细阅读 helm 报错信息定位到synapse.additional中具体哪个文件、哪一行出错特别注意max_upload_size这类参数——它由 Chart 统一管理应改synapse.media.maxUploadSize而非直接写进 Synapse 配置否则 Ingress 的注解不会同步调整修正后重新执行 helm 命令。另外如果报错与启用/禁用某组件相关那是 deployment-markers 机制在工作Chart 通过 ConfigMap 记录安装状态防止组件状态被改成会导致数据损坏的组合机制说明见 docs/maintenance.md。8️⃣ 装完服务器却无法创建账号注册默认关闭现象所有组件 Running、Element Web 能打开但登录页没有注册入口无从创建第一个用户。根因ESS Community默认关闭开放注册这是出于安全考虑不是故障。解决进入 MAS 的 Pod 用官方 CLI 交互式创建用户kubectl exec -n ess -it deploy/ess-matrix-authentication-service -- mas-cli manage register-user按提示输入用户名并设置密码即可详细输出示例见 README.md 的 Creating an initial user 一节。若后续希望用户能自助注册需为 MAS 配置 SMTP 邮件服务并调整注册策略方法在 docs/advanced.md 的 MAS 配置章节有说明公网部署请务必保留registration_token_required: true之类的限制防止被刷注册。 排查小工具箱日常排障时高频用到的几个命令建议收藏# 查看各组件 Pod 状态 kubectl get pods -n ess # 查看某组件日志以 SFU 为例 kubectl logs -n ess -l app.kubernetes.io/componentrtc-sfu # 检查 well-known 文件 curl -s https://server name/.well-known/matrix/client | jq配置项的完整说明可查阅 charts/matrix-stack/values.yaml 与 Chart 的 charts/matrix-stack/README.md视频通话相关的网络细节SFU 三种 IP 宣告模式、Turn-TLS 等在 docs/advanced.md 中展开得最细。写在最后掌握 ESS Helm 故障排查的关键在于理清请求链路DNS → Ingress → HAProxy → Synapse/MAS而视频通话额外依赖一条 UDP 媒体通道。按本文的 8 条清单自上而下核对绝大多数问题都能定位到具体的 values 参数或网络配置上。祝你的 Matrix 服务器运行顺畅赞分享【免费下载链接】ess-helmElement Server Suite Community Edition项目地址https://gitcode.com/gh_mirrors/es/ess-helm点击查看免费下载相关推荐GrapeRoot常见问题排查清单MCP连接失败、端口冲突等8个高频故障一次搞定GrapeRoot常见问题排查清单MCP连接失败、端口冲突等8个高频故障一次搞定 使用 GrapeRoot 这类 AI 编程上下文引擎时新手最常卡住的MOSS-Audio-Tokenizer-v2-bf16 常见问题排查清单下载失败、采样率错误等 8 个坑一次讲清MOSS Audio Tokenizer v2 bf16 常见问题排查清单下载失败、采样率错误等 8 个坑一次讲清 MOSS Audio TokenizerCreamInstaller故障排查清单无法启动、DLC不解锁、steam_api签名错误等8大常见问题CreamInstaller故障排查清单无法启动、DLC不解锁、steam_api签名错误等8大常见问题 CreamInstaller 是一款图形化的 DLC上一篇静态站点生成器对比beautiful-docs推荐的MkDocs vs VuePress下一篇MEV-template-rs事件监听系统实时捕获PairCreated事件的终极方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考