故障排查¶
先区分问题发生在面板、站点入口、Emby 登录还是媒体播放。不要一次改变入口、UA、Header 和播放模式，否则难以判断哪一步起效。
面板无法打开¶
- 检查服务或容器是否运行。
- 确认当前监听地址与端口，而不是只查看环境变量中的旧值。
- 检查域名解析、HTTPS 证书、网关和防火墙。
- 默认绑定
127.0.0.1的面板不能从远程直接访问，需 SSH 隧道或反向代理。
# 标准 Linux
sudo systemctl status meridian --no-pager
sudo journalctl -u meridian -n 100 --no-pager
# Docker
docker compose ps
docker compose logs --tail 100 meridian
容器报 Operation not permitted 时，核对 官方镜像的能力配置，特别是 NET_BIND_SERVICE；报数据目录错误时再检查挂载与 UID/GID。
无法创建管理员¶
确认数据库尚未初始化，并使用当前部署的 SETUP_TOKEN。服务不通过公开 API 返回令牌；安装器将其写入受保护的环境文件，官方容器新生成时显示一次。
状态检查失败时，不把它当作可以直接创建管理员的未初始化状态。先恢复面板连接。
忘记密码或反复登录失败¶
- 区分 Meridian 管理员与 Emby 账户。
- 检查输入与浏览器访问域名，不使用初始化令牌作为登录密码。
- 连续失败可能触发短时限制，按界面倒计时或
Retry-After等待。 - 忘记管理员密码时用 离线重置，不要删除数据库重建。
站点入口无法连接¶
| 模式 | 首先检查 |
|---|---|
| 路径 | 地址是否包含完整前缀，网关是否保留路径，站点是否启用。 |
| 独立端口 | 实际监听协议、端口占用、权限、防火墙、Docker 映射和 CDN 支持。 |
| 域名前缀 | DNS、证书覆盖、原生 TLS 能力、网关 Host 与公开端口。 |
可从客户端网络测试无需登录的服务器发现接口：
确认返回的是预期的 Emby 服务器信息，而不是 Meridian 登录页、网关错误页或另一个站点。
这个接口成功只证明对应发现请求可达，不证明账户或视频播放成功。
可以登录但不能播放¶
按顺序检查：
- 在“请求日志”选择该站点，包含播放与视频类别。
- 看播放信息请求是否成功，再看实际视频、清单与分片请求。
- 自动发现时查看 观察记录，区分 DNS、地址拒绝、证书或解析错误。
- 手动模式确认回源 URL 与额外节点包含正确协议和端口。
- 直连模式在客户端网络中确认媒体域名可达，并满足认证与证书要求。
- 核对站点配额、限速、UA 与上游账户状态。
服务器连接检测成功，仍可能出现客户端网络受限、上游拒绝用户、转码失败或特殊清单不兼容。最终用真实账户验证播放、拖动进度和字幕。
完全没有请求日志¶
先检查日志开关、ERROR 模式、请求类别、过滤条件和写入延迟。直连媒体不经过代理，也不会产生相同的代理请求记录。
确认配置无误后，再检查请求是否到达服务器。特别留意错误协议、未开放的高端口和被 CDN 拦截的端口。
403 traffic quota exceeded¶
这是代理配额限制。检查当期用量、计费方向、重置周期与站点额度，见 流量与配额。
它与上游 Emby 用户认证失败不是同一个问题。
421 或 Host 不匹配¶
检查浏览器 / 客户端填写的域名是否为配置的面板或站点 Host，反向代理是否转发原 Host。经 CDN 或网关转发时不要替换成内部 IP Host。
TLS 申请或导入失败¶
核对完整域名、节点泛域名、Cloudflare Token 权限、证书链、私钥配对、有效期和服务账户读取权限。详见 TLS 证书。
更换监听端口或 TLS 状态后，同步检查反向代理配置；原内部 HTTP 上游不能继续代理到已改成 HTTPS 的同一端口。
Telegram 没反应¶
检查 Bot 管理开关、管理员数字用户 ID、私聊、Token 和连接状态。日报 Chat ID 不授予管理权限，同一 Token 的其他接收程序可能造成冲突。
完整配置见 Telegram Bot。
更新按钮不可用¶
Docker、手工和自定义部署不使用标准更新代理，按原部署方式更新。标准 Linux 安装检查更新服务是否已配置，见 更新与维护。
提交 Issue 前¶
提供以下信息即可帮助定位：
- Meridian 版本、平台和部署方式。
- 使用的入口模式、播放模式和客户端版本。
- 可复现步骤与实际状态码。
- 已脱敏的相关请求日志或自动发现原因码。
- 同一账户直连原 Emby 时是否正常。
删除 Token、初始化令牌、密钥、真实用户 ID、私人域名、IP、媒体 URL 和备份文件。安全漏洞使用 私下报告渠道。