故障排除

本指南覆盖 RelayCore 使用中的常见问题，按场景分组提供诊断步骤和解决方案。

证书与 TLS

浏览器显示证书不安全

  • 原因：RelayCore 生成自签名 CA，未被系统信任
  • 解决：生成并安装 CA 
    relay-core-cli ca generate
relay-core-cli ca install   # macOS

# 或手动（示例）
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/.relay-core/ca_cert.pem

curl 报 SSL 错误

  • 临时跳过：curl --cacert ~/.relay-core/ca_cert.pem https://example.com
  • 环境变量：export CURL_CA_BUNDLE=~/.relay-core/ca_cert.pem

"Failed to initialize ScriptInterceptor"

  • 原因：Deno/V8 运行时初始化失败（通常是内存不足）
  • 解决：释放系统内存后重试；若持续失败可不启用脚本功能

连接问题

代理无法启动（端口被占用）

  • 检查端口占用：lsof -i :8080 或 netstat -an | grep 8080
  • 更换监听端口：relay-core-cli run --listen 127.0.0.1:9090

客户端连接后无响应

  • 确认代理地址和端口正确
  • 检查系统代理设置（macOS: 系统偏好设置 → 网络 → 高级 → 代理）
  • 检查是否有安全软件阻止连接
  • 查看代理日志：RELAY_LOG=info relay-core-cli run

上游请求超时

  • 增大超时：--request-timeout-ms 30000
  • 检查上游可达性：curl -v http://upstream-host/path
  • 查看 Flow 详情中的错误字段

规则引擎

规则不生效

  • 检查 "active": true
  • 确认 stage 匹配流量阶段（例如 ResponseBody filter 不能用于 RequestHeaders 阶段）
  • 确认 filter 模式正确——Contains 区分大小写
  • 确认没有被更高 priority 的规则以 Stop 终止
  • 通过脚本查看命中的规则：console.log(flow.matched_rules)

RateLimit 未按预期工作

  • 确认 window_ms 足够大（最小 1000ms）
  • 确认 key 中的 Mustache 变量正确（{{ip}} 而非 {{clientip}}）
  • RateLimit 不自动拒绝请求——需配合脚本或后续规则处理

WebSocket

WebSocket 连接立即断开

  • 检查 onConnect hook 是否返回了 {drop: true}
  • 检查是否有规则在 Connect 阶段执行了 Drop

WebSocket 消息未显示

  • 确认 TUI 或前端处于正确的 WS 标签页
  • 检查 DropWebSocketMessage 动作是否误删了消息

透明代理

透明代理不拦截流量（macOS）

  • 确认 PF 规则已加载：sudo pfctl -s nat
  • 确认 RelayCore 以 root 权限运行
  • macOS PF UDP 透明代理目前标记为实验性

透明代理不拦截流量（Linux）

  • 确认 iptables TPROXY 规则正确
  • 确认 SO_ORIGINAL_DST 可用（内核 > 2.6）
  • 检查 /proc/sys/net/ipv4/conf/*/route_localnet 设置

性能

代理后请求变慢

  • 检查规则数量——每条规则在每个匹配的 flow 上都会执行
  • 检查 ResponseBody filter——会缓存完整响应体
  • 检查脚本执行时间——script_hook_duration_us 指标
  • 关闭不必要的日志：RUST_LOG=warn relay-core-cli run

内存持续增长

  • 检查 Flow 内存上限配置（默认 10000 条）
  • 检查脚本 sharedState 是否及时清理（> 10k key 触发 warning）
  • 检查 WebSocket 消息缓冲上限（默认 2000 条）

日志与调试

# 完整日志
RUST_LOG=debug relay-core-cli run

# 只看脚本
RUST_LOG=relay_core_script=debug relay-core-cli run

# 只看代理
RUST_LOG=relay_core_lib=debug relay-core-cli run

# 查看实时流事件
curl -N http://127.0.0.1:8082/api/v1/events

# 查看指标
curl http://127.0.0.1:8082/api/v1/metrics
curl http://127.0.0.1:8082/api/v1/metrics/prometheus

获取帮助

  • 运行 relay-core-cli --help 查看所有命令
  • 运行 relay-core-cli run --help 查看启动参数
  • 查看版本：relay-core-cli --version
  • GitHub Issues：github.com/relaycraft/relay-core/issues