排障指南

遇到问题先来对着症状查。大部分常见问题都能快速定位。

只读连通性检查

在运行规则的 Agent 主机上执行（单机部署就是 VPS）：

curl -fsSL https://raw.githubusercontent.com/sakullla/nginx-reverse-emby/main/scripts/check-proxy.sh -o check-proxy.sh
sh check-proxy.sh --upstream https://origin.example.net --frontend https://app.example.com

替换为自己的首页地址；也可只传 --upstream 或 --frontend。需要 sh 和 curl，不需要 root 或面板令牌。URL 不接受凭据、查询参数和片段，请勿传入播放链接。

工具只发送 HEAD，不跟随跳转、不下载正文、不修改配置、不读取 .env。每个目标最多等待 10 秒，并保留 TLS 证书校验。它忽略 curl 配置文件和环境代理，测试的是当前主机直连，不模拟规则中的出口 Profile、Relay、插件后端和自定义请求头。

• 通过：收到 2xx/3xx；3xx 只代表收到跳转，没有验证跳转目标。
• 需检查：按提示区分 DNS、连接、超时、TLS 和 HTTP 响应。401/403 表示访问限制，405/501 可能是不支持 HEAD，均需进一步验证。
• 退出码 0：所有目标返回 2xx/3xx；1：至少一个目标需检查；2：参数或依赖错误。

输出不包含目标 URL、响应头、正文和原始 curl 错误，可作为反馈线索，但分享前仍请检查。服务器上通过不代表公网客户端能访问，也不代表响应来自预期服务；最后务必用实际客户端验收。

访问入口域名没反应

症状： 浏览器输入域名后一直加载，最后超时。

按顺序检查：

1. DNS 是否生效 — 在本地执行 nslookup app.example.com，看返回的 IP 是不是你的 VPS。刚添加的 DNS 记录可能需要几分钟到几小时才能全球生效。
2. 端口是否放行 — 检查云服务商的安全组和 VPS 系统防火墙，确认监听端口已放行。HTTP 默认 80，HTTPS 默认 443。
3. 规则是否启用 — 在面板里确认规则开关是开启状态。
4. 规则选了正确的 Agent 吗 — 入口规则必须选实际在监听的那台机器的 Agent。

规则保存了但访问不到后端

症状： 浏览器显示 502 或连接被拒绝。

1. 节点能不能访问后端 — SSH 到运行规则的节点上执行：

   curl -I https://原站地址

   如果不通，说明节点到后端的网络有问题。先把网络搞通再继续。

2. 后端协议和端口填对了吗 — 检查规则里的后端地址：协议是 http:// 还是 https://？端口号是不是对的？

3. 后端是否限制了反代 — 有些后端会检查 Host 头、IP 地区或 User-Agent，可能需要在规则的高级设置里调整请求头。

HTTPS 访问失败

症状： https:// 打不开，但 http:// 可以。

1. 先用 HTTP 验证链路是通的，再启用 HTTPS。
2. 去面板的 基础设施 → 证书管理 查看证书状态。如果签发失败，点重试。
3. 确认 443 端口已在防火墙放行。
4. ACME 验证要求域名解析到运行规则的 Agent 节点，确认 DNS 没问题。

HTTP 规则和 L4 规则怎么选？

场景	选哪个
反代 Web 服务、Emby/Jellyfin、网站	HTTP 规则
转发 TCP/UDP 端口、游戏服务器、数据库	L4 规则
需要 Relay 隧道中转	HTTP 规则 + Relay 或 L4 规则 + Relay

HTTP 规则理解域名、路径、HTTP 头，适合浏览器访问。L4 规则只转发端口流量，适合非 Web 协议。

何时关闭 302/307 重定向改写？

HTTP 规则默认把后端的跳转地址改写为你的入口域名，大多数情况下这是对的。以下场景需要关掉：

• CDN 回源需要保留原始地址
• OAuth 回调需要原样传递
• 多跳转链接需要客户端直接访问中间地址

关闭位置：HTTP 规则编辑页的「代理 302/307 重定向」选项。

证书要手动申请吗？

不需要。HTTP 规则保存后，Agent 会自动用 HTTP-01 方式申请证书，全程无需人工干预。

以下情况才需要手动处理：

• VPS 无法开放 80 端口 → 配置 Cloudflare DNS-01
• 需要通配符证书（*.example.com）→ DNS-01
• 已有商业证书 → 手动上传

详见 证书与 HTTPS。

local Agent 和远程 Agent 的区别？

local Agent 是 Docker Compose 自带的，和控制面跑在同一个容器里。一台 VPS 做反代时所有规则选 local 就行。

远程 Agent 用在多台服务器的场景——分散代理负载、不同地区提供入口、暴露内网服务。远程 Agent 主动连接控制面拉配置，不需要控制面向 Agent 开放入站端口。

流量额度超了怎么办？

流量策略中开启「超额阻断」后，节点达到月度额度会被阻断。被阻断的节点在下个计费周期自动恢复。你也可以手动调高额度或关闭超额阻断。

详见 流量额度。

数据库可以换吗？

可以。默认 SQLite 适合个人和小团队。数据量大了可以切换到 PostgreSQL 或 MySQL：

1. 设置 NRE_DATABASE_DRIVER 和 NRE_DATABASE_DSN 环境变量
2. 用 migrate-storage 命令迁移数据

详见 数据迁移。

为什么默认用 host 网络？

Docker bridge 网络在容器启动后不能动态新增端口映射，而 Agent 需要根据规则动态创建监听端口。host 网络让容器直接共享宿主机网络栈，端口管理完全灵活。代价是规则配置的端口直接占用宿主机端口，需要注意端口冲突。

面板数据存在哪里？

默认在 Compose 文件同级的 ./data 目录。所有配置、证书、Agent 信息都在里面。请定期备份这个目录。

远程 Agent 需要开放入站端口吗？

不需要。Agent 主动连接控制面（心跳拉取），控制面不会主动连 Agent。即使 Agent 在 NAT 或内网后面也能工作。

但代理规则本身的监听端口（80、443 或你指定的端口）仍需放行，否则访客进不来。