代理模式

RelayCore 支持三种代理运行模式，覆盖从"开发机本地代理"到"作为企业网关"的各种部署形态。

普通代理（默认）

客户端显式地把 RelayCore 设为 HTTP/HTTPS 代理。这是开发与调试最常用的模式，对操作系统与客户端配置零侵入。

# 启动
relay-core-cli run

# 在浏览器或系统设置中将 HTTP/HTTPS 代理指向
# 127.0.0.1:8080（默认监听地址）

配置完成后所有请求都会经过 RelayCore；HTTPS 流量由动态签发的证书解密（需要先安装 CA，见 证书与 HTTPS 拦截）。

透明代理

客户端不感知代理存在，操作系统或网络设备把流量强制重定向到 RelayCore。适合设备调试、移动设备、嵌入式设备和不需要修改客户端配置的场景。

relay-core-cli run --transparent

macOS（PF）

使用 relay-core-cli proxy 子命令管理 PF 规则：

# 生成 PF 配置（默认 en0，可通过 --interface 改）
relay-core-cli proxy generate --port 8080

# 加载并启用规则（需要 sudo）
sudo relay-core-cli proxy load --port 8080 --interface en0

# 查看当前状态
relay-core-cli proxy status

# 关闭
sudo relay-core-cli proxy unload

生成的 PF 规则会重定向 80/443 端口的 TCP 流量到本地代理端口。仅在 macOS 上受支持。

Linux（TPROXY）

通过 --transparent 启动。Linux 透明代理需要 iptables/nftables 与路由表配合，RelayCore 不直接管理这些规则；请参考 故障排除 中的 Linux 段。

UDP TPROXY

relay-core-cli run --transparent --udp-tproxy-port 8080

启用 UDP 透明代理。仅 Linux，需要内核支持 IP_TRANSPARENT。

上游代理（Chained Proxy）

把 RelayCore 放在另一个代理之后。所有出站请求先到 RelayCore，再由 RelayCore 通过父级代理转发。常用于企业代理环境、VPN 集中器、TLS 检查中间盒后面。

# 纯 HTTP 上级代理
relay-core-cli run --upstream http://corp-proxy.internal:8080

# HTTPS 上级代理（先与代理建立 TLS）
relay-core-cli run --upstream https://secure-proxy.internal:8443

# 带 Basic 认证
export RELAYCORE_UPSTREAM_PASSWORD='s3cret'
relay-core-cli run --upstream http://corp-proxy.internal:8080 --upstream-auth-user alice

# 上级不可达时回落到直连（默认 fail-closed）
relay-core-cli run --upstream http://corp-proxy.internal:8080 --upstream-fail-open

绕过列表

通过 --upstream-bypass 指定不走上级代理的目标，三种规则可混用：

--upstream-bypass "127.0.0.1,::1,localhost,*.internal,cidr:10.0.0.0/8,cidr:192.168.0.0/16"

透明代理模式下还会将原始目的 IP 与绕过列表比对，确保到本地服务的回环与 RFC1918 流量始终直连。

HTTP vs HTTPS 上级

URL 以 https:// 开头时，RelayCore 先与代理完成 TLS 握手再发送 CONNECT。代理证书使用系统信任库校验。在使用私有 CA 的环境中请将 CA 导入系统信任库。

运行时变更

上游配置是 ProxyPolicy 的一部分，可通过 REST API 局部更新：

# 查看当前策略
curl -s http://127.0.0.1:8082/api/v1/policy

# 仅更新 upstream 段
curl -s -X PATCH http://127.0.0.1:8082/api/v1/policy \
  -H 'Content-Type: application/json' \
  -d '{
    "upstream": {
      "proxy_url": "http://corp-proxy.internal:8080",
      "bypass_hosts": ["*.internal", "127.0.0.1"],
      "fail_open": false
    }
  }'

运行时切换 proxy_url 会返回 409 Conflict，因为已有连接绑定在旧路径上，需要重启代理才能生效。

安全提示

• 密码字段使用 secrecy::SecretString 包装；Debug、API 响应、JSON 序列化器都掩码为 ***。
• 当上级是策略强制的，保持 --upstream-fail-open=false（默认）—— 静默回落会失去保护。
• 策略变更会写入 /api/v1/audit，kind=policy_updated，并记录触发者（actor）。