vrr/g3

mirror of https://github.com/bytedance/g3.git synced 2026-04-28 11:40:54 +00:00

onin 8c11d5b4cd username-params: gate mapping + no default override; HTTP 400 on unresolved mapping; dedup; docs/tests

- Behavior: do not override when username has no recognized keys; fall back to escaper proxy_addr.
  - HTTP error: username-derived NXDOMAIN returns 400 Bad Request with “Proxy targeting didn't find a
  match” (CONNECT and Forward); other failures keep existing mappings (e.g., 530).
  - Config/compute: allow empty separator; rename suffix_for_host → to_fqdn; add
  username_has_known_key(..); keep global_label for compatibility but stop using it.
  - Server config: use UsernameParamsToEscaperConfig directly; call
  UsernameParamsToEscaperConfig::parse(..).
  - Integration: HTTP writer gates mapping with username_has_known_key(..); 400 on invalid params; no
  override otherwise. SOCKS negotiation gates similarly; uses Option<UpstreamAddr>; standard error on
  invalid params.
  - Escapers: divert_tcp ignores per-connection override (internal/transparent); remove unnecessary clones;
  dedup connect logic via local connect_via_peer(..) helpers (no cross-module macro).
  - Logging: restore SOCKS log_client_shutdown() parity with HTTP connect.
  - Docs/examples: EN/ZH guides note “no recognized keys → use proxy_addr”; remove global_label from
  examples.
  - Tests: update for to_fqdn; remove “no params → global” test; adjust unknown-keys case; fix duplicate
  #[test].
  - Cleanup: remove unused imports and small style nits.

2025-09-09 11:42:18 +08:00

33 KiB

Raw Blame History

g3proxy用户指南

如何安装
基础概念
基础用法
进阶用法
场景设计
- 多区域加速
- 双出口容灾

如何安装

目前只支持Linux系统，并对Debian、RHEL等发行版提供了打包安装支持，参考发行&打包步骤完成打包后直接在目标系统上安装即可。

基础概念

服务管理

单机可以部署多个g3proxy服务，通过systemd实例服务进行管理，每个实例对应为为一个g3proxy进程组（daemon_group），每个进程组都有一个unix socket文件进行本地RPC管理。

每个服务有一个入口配置文件，yaml格式，后缀可更改，但需要保持所有引用的配置文件均具有相同的后缀。下文将使用main.yml 指代入口配置文件。

使用发行版原生安装包安装的，已经安装了systemd参数化服务配置文件，参数就是进程组名称，对应的入口配置文件存放路径为/etc/g3proxy/<daemon_group>/main.yml。

未使用安装包安装的，可以参考g3proxy@.service自行设计服务化使用方式。

热升级

默认的systemd服务配置支持热升级，执行步骤如下：

安装新版本包
执行systemctl daemon-reload加载新版本服务配置
执行systemctl restart g3proxy@<daemon_group>，启动新进程，并通知老进程离线

老进程离线后会等待原有任务退出，或等待一段时间（默认10小时）后强制下线。

热升级机制类似nginx reload，受操作系统限制socket释放时会有一定几率导致新连接请求被丢弃，Linux 5.14及以后的版本引入 tcp_migrate_req选项，打开后可确保连接不丢失。

配置结构

g3proxy采用模块化方式进行功能设计，主要包含以下功能模块：

入口 | Server

负责接受客户端请求并进行处理，会调用出口&用户&审计模块的功能。 Port类型的入口可以放在非端口类型入口前面进行串联。
出口 | Escaper

负责对目标地址进行连接及控制，会调用解析模块的功能。 Route类型的出口可放在其他出口前进行串联。
解析 | Resolver

提供域名解析功能。 Failover解析可以放在其他解析前面进行串联。
用户组 | UserGroup

提供用户认证&授权功能
审计 | Auditor

提供流量审计功能

这些模块的配置可以跟main.yml写在一起，也可以使用独立的配置文件进行管理，后者可以进行独立的重载（reload）操作。

除了以上模块的配置，包括线程/日志/监控等，均需要写在main.yml中。

单一文件配置可参考examples/inspect_http_proxy，拆分文件配置可参考examples/hybrid_https_proxy。

下文示例将不展示完整配置文件，仅对相关涉及的部分进行展示，完整示例参考examples。

监控

为方便接入各种监控解决方案，G3项目统一使用StatsD作为监控打点输出协议，用户可以根据自己的实际情况选择合适的StatsD实现（例如gostatsd），配置好然后接入自己的监控系统。

g3proxy的监控配置在主配置文件main.yml中进行配置，示例如下：

stat:
  target:
    udp: 127.0.0.1:8125 # StatsD的UDP套接字地址
    # unix: /run/statsd.sock
  prefix: g3proxy       # 打点名称前缀，比如 server.task.total 会转变为 g3proxy.server.task.total
  emit_duration: 200ms  # 打点间隔

具体metrics定义在 metrics 文件夹下，建议生成sphinx html文档后查看。

基础用法

HTTP代理

入口启用HTTP代理，需要添加HttpProxy类型入口，示例如下：

server:
  - name: http       # 名称需要唯一，不跟其他入口冲突，日志&监控需要使用该字段
    escaper: default # 必填，可以是任意类型出口
    type: http_proxy
    listen:
      address: "[::]:8080"
    tls_client: { }   # 打开7层https forward转发支持

SOCKS代理

入口启用Socks代理，需要添加SocksProxy类型入口，示例如下：

server:
  - name: socks        # 名称需要唯一，不跟其他入口冲突，日志&监控需要使用该字段
    escaper: default   # 必填，可以是任意类型出口
    type: socks_proxy
    listen:
      address: "[::]:10086"
    enable_udp_associate: true # 使用标准UDP Associate功能，否则使用简化UDP Connect功能（Peer限制唯一）
    udp_socket_buffer: 512K    # 配置客户端侧双向UDP Socket Buffer Size

TCP映射

本地TCP端口映射到目标机器的特定端口，需要添加TcpStream类型入口，示例如下：

server:
  - name: tcp           # 名称需要唯一，不跟其他入口冲突，日志&监控需要使用该字段
    escaper: default    # 必填，可以是任意类型出口
    type: tcp_stream
    listen:
      address: "[::1]:10086"
    proxy_pass: # 目标地址，可以单条/多条
      - "127.0.0.1:5201"
      - "127.0.0.1:5202"
    upstream_pick_policy: rr # 负载均衡算法，默认random

TLS卸载

本地TCP端口映射到目标机器的TLS端口。需要添加TcpStream类型入口，示例如下：

server:
  - name: tcp           # 名称需要唯一，不跟其他入口冲突，日志&监控需要使用该字段
    escaper: default    # 必填，可以是任意类型出口
    type: tcp_stream
    listen: "[::1]:80"
    proxy_pass: "127.0.0.1:443"
    tls_client: { }      # 使用TLS连接目标端口，配置TLS参数，如CA证书、客户端证书(mTLS)等

TLS封装

本地TLS端口映射到目标机器的特定端口。

可添加TlsStream类型入口，示例如下：

server:
  - name: tls           # 名称需要唯一，不跟其他入口冲突，日志&监控需要使用该字段
    escaper: default    # 必填，可以是任意类型出口
    type: tls_stream
    listen:
      address: "[::1]:10443"
    tls_server: # 配置TLS参数
      cert_pairs:
        certificate: /path/to/cert
        private_key: /path/to/key
      enable_client_auth: true    # 可选启用mTLS
    proxy_pass: # 目标地址，可以单条/多条
      - "127.0.0.1:5201"
      - "127.0.0.1:5202"
    upstream_pick_policy: rr # 负载均衡算法，默认random

或使用PlainTlsPort串联TcpStream，示例如下：

server:
  - name: tcp
    escaper: default
    type: tcp_stream
    proxy_pass: # 目标地址，可以单条/多条
      - "127.0.0.1:5201"
      - "127.0.0.1:5202"
    upstream_pick_policy: rr # 负载均衡算法，默认random
  - name: tls
    type: plain_tls_port
    listen:
      address: "[::1]:10443"
    tls_server: # 配置TLS参数
      cert_pairs:
        certificate: /path/to/cert
        private_key: /path/to/key
      enable_client_auth: true    # 可选启用mTLS
    server: tcp    # 指向tcp stream服务

SNI代理

自动识别TLS SNI / HTTP Host头中的目标地址，并转发，需要添加SniProxy类型入口，示例如下：

server:
  - name: sni          # 名称需要唯一，不跟其他入口冲突，日志&监控需要使用该字段
    escaper: default   # 必填，可以是任意类型出口
    type: sni_proxy
    listen:
      address: "[::]:443" # 监听443端口，但可以同时支持发往该端口的TLS & HTTP协议流量

透明代理

在网关设备上，可以配置将需要代理的TCP连接，转发给TcpTProxy入口，由代理进行透明中转，示例如下：

server:
  - name: transparent
    escaper: default
    auditor: default  # 如果需要进行协议识别及TLS劫持等
    type: tcp_tproxy
    listen: "127.0.0.1:1234"

需要使用的系统配置取决于系统类型：

Linux TPROXY。
FreeBSD ipfw fwd。
OpenBSD pf divert-to。

线路绑定

机器上具有多条网络线路，需要绑定其中一条访问目标网站时，需要在出口指定Bind的IP,以DirectFixed出口为例：

escaper:
  - name: default        # 名称需要唯一，不跟其他入口冲突，日志&监控需要使用该字段
    type: direct_fixed
    resolver: default
    resolve_strategy: IPv4First # 出口支持HappyEyeballs算法，解析目标地址时v4优先
    bind_ip: 192.168.10.1   # 可以使用list设置多个地址
resolver:
  - name: default
    type: c-ares
    server: 223.5.5.5
    bind_ipv4: 192.168.10.1 # 解析也需要绑定同一条线路，确保就近解析

代理串联

需要使用其他代理进行串联时，需要使用Proxy类型的出口，以ProxyHttps为例：

escaper:
  - name: next_proxy    # 名称需要唯一，不跟其他入口冲突，日志&监控需要使用该字段
    type: proxy_https
    resolver: default   # 代理地址包含域名时必须设置
    proxy_addr: next-proxy.example.net:8443 # 也可以列表填写多个代理地址
    http_forward_capability:
      forward_ftp: true   # 直接转发FTP over HTTP请求给下一级代理处理，若否则在本地进行FTP请求
      forward_https: true # 直接转发https forward请求给下一级代理处理，若否则在本地进行TLS握手
    tls_client:
      ca_certificate: rootCA.pem # 用于验证下一级代理的CA证书，不设置时默认用系统默认安装的CA证书
    tls_name: example.com # 代理地址不包含域名时，如果需要用DNS Name验证证书，则需要设置

用户名参数 → 串联下一跳地址

对于 HTTP 和 SOCKS5 代理入口，可以通过在用户名后追加有序的键值对，动态计算串联下一跳的地址：base+key1=val1+key2=val2+...。

在对应入口下启用 username_params_to_escaper_addr 即可生效。
计算主机名：按配置的键顺序取值并用分隔符拼接；若用户名中未包含任意已配置的键，则不进行覆盖，继续使用 escaper 的默认 proxy_addr。
端口：根据入站协议选择（HTTP / SOCKS5），均可配置。
可配置是否拒绝未知键、是否强制层级（例如子键必须有父键）。

示例配置：

server:
  - name: http-in
    type: http_proxy
    escaper: chain
    username_params_to_escaper_addr:
      keys_for_host: [label1, label2, label3]
      require_hierarchy: true
      reject_unknown_keys: true
      reject_duplicate_keys: true
      separator: "-"
      # 可选后缀（例如本地测试）：
      # domain_suffix: ".localhost"
      http_port: 10000
      socks5_port: 10001
      strip_suffix_for_auth: true

行为说明：

用户名 user+label1=foo+label2=bar → 主机 foo-bar，HTTP 入站端口 10000。
若用户名中未包含任意已配置的键，则不进行覆盖，继续使用 escaper 的 proxy_addr。
非法参数（未知键或层级违例）会导致 HTTP 返回 400 Bad Request；SOCKS5 返回标准错误码并拒绝请求。

出口回退说明：

代理串联出口（proxy_http / proxy_socks5 / …）在初始化时必须配置至少一个 proxy_addr。
当用户名参数存在且认证成功时，计算得到的 host:port 会覆盖该连接的 proxy_addr。
当用户名中没有任何已配置的键时，不进行覆盖，直接使用 proxy_addr 作为回退。

连接限速

server、escaper、user维度均支持设置单连接限速，配置key相同，在对应的server & escaper & user里设置：

tcp_sock_speed_limit: 10M/s
udp_sock_speed_limit: 10M/s

server及user配置针对的是Client-Proxy的连接，escaper配置针对的是Proxy-Target的连接。

进程全局限速

用户配置支持设置进程全局限速：

tcp_all_download_speed_limit: 100M/s
tcp_all_upload_speed_limit: 100M/s
udp_all_download_speed_limit: 100M/s
udp_all_upload_speed_limit: 100M/s

域名解析

使用系统默认/etc/resolv.conf配置：

resolver:
  - name: default
    type: c-ares

使用自定义DNS服务器地址：

resolver:
  - name: c-ares
    type: c-ares
    server:
      - 1.1.1.1
      - 1.0.0.1
  - name: hickory
    type: hickory
    server:
      - 8.8.8.8
      - 8.8.4.4

安全解析

需要使用非明文的方式访问DNS递归解析服务器时，需要使用hickory解析，示例如下：

resolver:
  - name: default
    type: hickory
    server: 1.1.1.1
    encryption: dns-over-https # 此外也支持 dns-over-tls、dns-over-quic, dns-over-h3

容灾解析

单一DNS递归解析服务器不稳定时，可以使用Failover类型解析，示例如下：

resolver:
  - name: virtual
    type: fail_over
    primary: alidns
    standby: dnspod
  - name: alidns
    type: c-ares
    server: 223.5.5.5 223.6.6.6
  - name: dnspod
    type: c-ares
    server: 119.29.29.29

用户认证授权

Http代理&Socks5代理都支持进行用户验证，需要搭配UserGroup进行配置，整体配置参考examples/simple_user_auth ，用户组示例如下：

user_group:
  - name: default
    static_users:
      - name: root
        # password: toor
        token: # 认证token
          salt: 113323bdab6fd2cc
          md5: 5c81f2becadde7fa5fde9026652ccc84
          sha1: ff9d5c1a14328dd85ee95d4e574bd0558a1dfa96
        dst_port_filter: # 放行端口
          - 80
          - 443
        dst_host_filter_set: # 放行地址
          exact:
            - ipinfo.io           # 允许访问ipinfo.io
            - 1.1.1.1
          child:
            - "ipip.net"          # 允许访问 myip.ipip.net
          regex:
            - "lum[a-z]*[.]com$"  # 允许访问 lumtest.com
    source: # 动态用户，静态用户优先匹配，无静态用户时匹配动态用户
      type: file                  # 从文件定期加载，此外支持通过lua/python脚本加载并缓存
      path: dynamic_users.json

用户验证token生成需要使用scripts/passphrase_hash.py脚本。

用户限流限速

用户维度支持单连接限速、RPS限制、并发任务总数限制：

tcp_sock_speed_limit: 10M/s # TCP单连接双向分别限速10M/s
udp_sock_speed_limit: 10M/s # UDP单连接双向分别限速10M/s
tcp_conn_rate_limit: 1000/s # Client-Proxy新建连接速率限制
request_rate_limit: 2000/s  # 新增代理请求数速率限制
request_max_alive: 2000     # 存活任务总数限制

用户封禁

用户删除之后，默认不会清理该用户已存在的任务，如果需要终止这些任务，需要将用户设置为封禁状态，在最多2个任务空闲检测间隔内，存活任务将会被清理终止。

需要封禁的用户配置如下：

- name: foo
  block_and_delay: 1s # 封禁该用户，并对新请求按照指定的值进行延迟响应返回
  # 其他配置可保留不动

进阶用法

mTLS客户端

本文若干处涉及到TLS Client的配置，如果需要作为TLS客户端启用mTLS双向认证，示例配置如下：

tls_client:
  certificate: /path/to/cert.crt  # 客户端证书
  private_key: /path/to/pkey.key  # 客户端私钥
  ca_certificate: /path/to/ca/cert.crt # CA证书，用于验证服务端证书（默认用系统CA证书）

国密TLCP协议卸载

此功能需要编译时启用feature vendored-tongsuo。

有些场景可能要求使用国密协议访问，很多客户端不支持国密协议，可使用g3proxy进行协议转换：

TLCP转4层TCP

server:
  - name: l4tcp
    type: tcp_stream
    listen: "[::1]:10086"
    upstream: "127.0.0.1:443" # 对方国密服务器地址，支持域名
    tls_client:
      protocol: tlcp
      ca_certificate: /path/to/ca.cert # CA证书路径
      # 可继续配置mTLS等参数
    upstream_tls_name: target.host.domain # 对方域名，用于验证对方身份（如果upstream url带域名，可省略）

TLCP转4层TLS

server:
  - name: l4tls
    type: tls_stream
    tls_server:
      cert_pairs:
        - certificate: /path/to/cert
          private_key: /path/to/key
    # 其他配置同上面 tcp_stream

TLCP转7层HTTP

server:
  - name: l7http
    type: http_rproxy
    listen: "[::1]:80"
    hosts:
      - set_default: true
        upstream: "127.0.0.1:443"
        tls_client:
          protocol: tlcp
          ca_certificate: /path/to/ca.cert # CA证书路径
          # 可继续配置mTLS等参数
        tls_name: target.host.domain # 对方域名，用于验证对方身份（如果upstream url带域名，可省略）

TLCP转7层HTTPS

server:
  - name: l7http
    type: http_rproxy
    listen: "[::1]:443"
    hosts:
      - set_default: true
        upstream: "127.0.0.1:443"
        tls_client:
          protocol: tlcp
          ca_certificate: /path/to/ca.cert # CA证书路径
          # 可继续配置mTLS等参数
        tls_name: target.host.domain # 对方域名，用于验证对方身份（如果upstream url带域名，可省略）
        tls_server: # 配置该host对应的tls服务配置
          cert_pairs:
            - certificate: /path/to/cert
              private_key: /path/to/key
    enable_tls_server: true
    # 可使用global_tls_server参数设置默认tls服务配置，对未设置tls_server参数的host生效

多协议入口复用

如果需要单个端口同时用于HttpProxy & SocksProxy，可以使用IntelliProxy Port入口：

server:
  - name: intelli
    type: intelli_proxy
    listen: "[::]:8080"
    http_server: http        # 对HTTP请求直接发送给http server处理
    socks_server: socks      # 对socks请求直接发送给socks server处理
  - name: http
    type: HttpProxy
    listen: "127.0.0.1:2001" # 监听本地地址防止滥用，本身不会被使用
  - name: socks
    type: SocksProxy
    listen: "127.0.0.1:2002" # 监听本地地址防止滥用，本身不会被使用

监听多个端口

相同的服务配置需要监听多个端口时，可以在Server前串联Port类型的入口。

SNI Proxy监听多个端口示例如下：

server:
  - name: sni          # 名称需要唯一，不跟其他入口冲突，日志&监控需要使用该字段
    escaper: default   # 必填，可以是任意类型出口
    type: sni_proxy
    listen:
      address: "[::]:443" # 监听443端口，但可以同时支持发往该端口的TLS & HTTP协议流量
  - name: port80
    type: plain_tcp_port
    listen: "[::]:80"  # 监听80端口
    server: sni_proxy  # 所有连接给到sni_proxy server处理

HTTP Proxy同时开放明文端口及TLS端口示例如下：

server:
  - name: http       # 名称需要唯一，不跟其他入口冲突，日志&监控需要使用该字段
    escaper: default # 必填，可以是任意类型出口
    type: http_proxy
    listen: "[::]:8080"
    tls_client: { }   # 打开7层https forward转发支持
  - name: tls
    type: plain_tls_port
    listen: "[::]:8443"
    server: http
    tls_server:
      cert_pairs:
        certificate: /path/to/certificate
        private_key: /path/to/private_key
      enable_client_auth: true            # 可选开启mTLS

Port类型入口仅有独立的Listen监控，流量监控、日志都是在下一跳Server处理的，在规划时需要考虑清楚是串联Port还是拆分Server更合适。

监听端口启用PROXY Protocol

串联场景，如果需要透传Client地址信息，可以使用PROXY Protocol。可以使用PlainTcpPort或PlainTlsPort来配置单独的支持PROXY Protocol的端口。

示例如下：

server:
  - name: real_http
    listen: "[127.0.0.1]:1234" # 可省略
    type: http_proxy
    ingress_network_filter: { } # 配置针对PROXY Protocol提取来源地址的过滤规则
    # ... 其他配置
  - name: pp_for_http
    type: plain_tcp_port
    listen: "[::]:8080"
    server: real_http
    proxy_protocol: v2
    ingress_network_filter: { } # 配置针对套接字原始来源地址的过滤规则

国密TLCP协议封装

此功能需要编译时启用feature vendored-tongsuo。

可使用NativeTlsPort实现国密TLCP协议封装：

server:
  - name: real_http
    listen: "[127.0.0.1]:1234" # 可省略
    type: http_proxy
    # ... 其他配置
  - name: tlcp
    type: native_tls_port
    listen: "[::]:443"
    tls_server:
      tlcp_cert_pairs: # 启用国密TLCP协议
        sign_certificate: /path/to/sign.crt
        sign_private_key: /path/to/sign.key
        enc_certificate: /path/to/enc.crt
        enc_private_key: /path/to/enc.key
      enable_client_auth: true # 可选启用mTLS
    server: real_http
    proxy_protocol: v2         # 可选启用PROXY Protocol

Socks5 UDP IP映射

Socks5 UDP处理时需要给客户端发送UDP数据连接的地址，一般是发送本地的IP:Port，有些情况下Client无法直接访问代理本地的IP地址，这时候需要在socks server中配置映射表：

transmute_udp_echo_ip:
  "192.168.10.2": "192.168.30.2"

安全反向代理

很多软件会暴露HTTP API或者metrics接口出去，他们本身的安全防护策略都比较简单，可以使用如下配置进行加固：

server:
  - name: plain
    escaper: default
    user-group: default                     # 启用用户认证
    type: http_rproxy
    listen:
      address: "[::]:80"
    no_early_error_reply: true              # 请求确认合法前禁止错误返回，端口防扫描
    hosts:
      - exact_match: service1.example.net   # 匹配该域名
        upstream: 127.0.0.1:8081            # 路径/全部转发
      - exact_match: service2.example.net   # 匹配该域名
        set_default: true                   # 若域名没有匹配的，作为默认站点
        upstream: 127.0.0.1:8082            # 路径/全部转发
    # 可通过tls_server启用TLS,或通过前置plain_tls_port添加独立的TLS端口

域名解析劫持

有很多情况会希望绕过正常的DNS解析流程使用特殊域名解析规则，在用户配置中可做如下配置：

resolve_redirection:
  - exact: t1.example.net # 固定到具体IP
    to: 192.168.10.1
  - exact: t2.example.net # CNAME
    to: t1.example.net
  - child: example.com    # *.example.com 替换为 *.example.net
    to: example.net

动态线路绑定

有些机器的IP是动态获取的，比如通过DHCP或PPP拨号，这些IP可以动态绑定到DirectFloat出口中：

代理配置：

escaper:
  - name: float
    type: direct_float
    resolver: default

使用如下指令进行更新：

g3proxy-ctl -G <daemon_group> -p <pid> escaper float publish "{\"ipv4\": \"192.168.10.1\"}"

动态代理串联

在爬虫场景，很多获取的代理地址都是动态带有效期的，可以封装一层中转代理，通过辅助程序自动处理过期代理替换，这样客户端只需要设置固定的代理地址：

代理配置：

escaper:
  - name: float
    type: proxy_float
    source:
      type: passive   # 接受推送，也可以配置为定期从redis获取

使用如下指令进行更新：

g3proxy-ctl -G <daemon_group> -p <pid> escaper float publish '{"type":"socks5","addr":"127.0.0.1:11080", "expire": "<rfc3339 datetime>"}'

其中type还可以支持http、https。

用户特定站点监控

在用户配置中，可以继续对站点进行维度划分，添加单独的监控或单独的配置：

explicit_sites:
  - id: example-net
    child_match: example.net
    emit_stats: true           # 建立独立的监控，id字段会作为监控条目名称的一部分
    resolve_strategy: # 可配置单独的解析策略
      query: ipv4only          # 仅解析ipv4地址

用户站点TLS劫持自定义配置

在用户-站点配置中，可对TLS劫持时的TLS Client行为进行设置：

explicit_sites:
  - id: example-net
    child_match: example.net
    tls_client:
      ca_certificate: xxx      # PEM格式CA证书
      cert_pairs:
        certificate: xxx       # PEM格式客户端证书
        private_key: xxx       # PEM格式客户端私钥
      # 其他TLS客户端配置

流量审计

开启流量审计功能完整配置参考examples/inspect_http_proxy，审计模块配置示例如下：

auditor:
  - name: default
    protocol_inspection: { } # 开启协议识别，使用默认参数
    tls_cert_generator: { }  # 开启TLS劫持，使用默认参数，Peer地址为127.0.0.1:2999
    tls_interception_client: { } # 可配置代理对目标地址TLS连接参数
    h1_interception: { }         # HTTP/1.0 解析参数
    h2_interception: { }         # HTTP/2 解析参数
    icap_reqmod_service: icap://xxx  # ICAP REQMOD服务配置
    icap_respmod_service: icap://xxx # ICAP RESPMOD服务配置
    application_audit_ratio: 1.0     # 应用流量审计比例，按客户端代理请求匹配，若审计则进行协议识别及TLS劫持

注意该功能需搭配tls cert generator使用，参考实现为g3fcgen ，示例配置参考g3fcgen simple conf。

TLS解密流量导出

开启流量审计功能，并启用TLS劫持后，可配置导出TLS解密流量至udpdump。

具体配置参考examples/inspect_http_proxy。

任务空闲检测

所有成功的任务，在执行过程中均有空闲检测退出的能力。空闲检测的设置主要包括2个，一是空闲检测间隔，二是允许的空闲计数。二者均可在server中配置，配置示例如下：

- name: foo
  type: xxx                    # 对任意server类型生效
  task_idle_check_interval: 1m # 默认为1分钟
  task_idle_max_count: 5       # 默认为最大5次计数，到达该值后，对应的任务终止

另外，允许的空闲计数可在user配置中单独配置，会覆盖server配置，示例如下：

- name: foo
  task_idle_max_count: 5

性能优化

默认配置，代理会使用所有CPU核，并进行跨核任务调度，有些场景下绑CPU核会提升性能，可以如下配置：

在main.yml中配置worker：

worker:
  thread_number: 8      # 不设置时，默认按所有CPU核数
  sched_affinity: true  # 开启绑核，默认按线程次序一一绑定，也可展开设置 Worker ID - CPU ID映射关系

server配置监听时，可以配置按worker数目监听，并分散到各worker中：

listen: "[::]:8080"
listen_in_worker: true

场景设计

多区域加速

可以使用g3proxy现有模块实现区域间加速功能。

以3个区域为例，整体拓扑如下：

flowchart LR
%% Paste to https://mermaid.live/ to see the graph
    subgraph Area1
        a1_client[Client]
        a1_site[Site]
        subgraph Proxy1
            a1_proxy[GW]
            a1_relay[relay]
            a1_route[route]
            a1_proxy -.-> a1_route
        end
        a1_client --> a1_proxy
        a1_route -- local --> a1_site
        a1_relay -- local --> a1_site
    end
    subgraph Area2
        a2_client[Client]
        a2_site[Site]
        subgraph Proxy2
            a2_proxy[GW]
            a2_relay[relay]
            a2_route[route]
            a2_proxy -.-> a2_route
        end
        a2_client --> a2_proxy
        a2_route -- local --> a2_site
        a2_relay -- local --> a2_site
    end
    subgraph Area3
        a3_client[Client]
        a3_site[Site]
        subgraph Proxy3
            a3_proxy[GW]
            a3_relay[relay]
            a3_route[route]
            a3_proxy -.-> a3_route
        end
        a3_client --> a3_proxy
        a3_route -- local --> a3_site
        a3_relay -- local --> a3_site
    end
    a1_route -- mTLS to a2 ----> a2_relay
    a1_route -- mTLS to a3 ----> a3_relay
    a2_route -- mTLS to a1 ----> a1_relay
    a2_route -- mTLS to a3 ----> a3_relay
    a3_route -- mTLS to a1 ----> a1_relay
    a3_route -- mTLS to a2 ----> a2_relay

每个节点的Proxy分别配置以下功能：

处理当地的用户请求，可使用SNI Proxy进行4层加速，或使用HTTP反向代理进行7层加速。

简化配置如下：

server:
  - name: port443
    type: sni_proxy
    escaper: route
  - name: port80
    type: http_rproxy
    escaper: route

relay

处理其他区域节点的请求，使用内部协议，例如使用mTLS通道。

简要配置如下：

server:
  - name: relay
    type: http_proxy
    escaper: local
    tls_server: {} # 配置TLS参数

route

对当地的用户请求进行选路分流，需要配置 >=1 个route类型出口，一个本地出口，另外对每个区域配置一个Proxy出口。

简化配置如下：

escaper:
  - name: route
    type: route_query  # 该模块可向外部agent查询选路规则，也可以用其他route出口模块
    query_allowed_next:
      - a1_proxy
      - a2_proxy
      - local
    fallback_node: local
    # ... agent配置
  - name: local
    type: direct_fixed
    # ... 出口配置
  - name: a1_proxy
    type: proxy_https
    tls_client: {} # 配置TLS参数
    # ... 配置代理参数 指向a1区域的 relay代理地址
  - name: a2_proxy
    type: proxy_https
    tls_client: {} # 配置TLS参数
    # ... 配置代理参数 指向a2区域的 relay代理地址

双出口容灾

单IDC有多个POP点公网出口时，或其他类似对目标站点的访问具有至少2条非本机线路可供选择的情况下，如果希望在2条线路进行主备切换自动容灾，可做如下设计：

拓扑图如下：

flowchart LR
%% Paste to https://mermaid.live/ to see the graph
    subgraph IDC
        i1_client[Client]
        subgraph Proxy
            i1_proxy[GW]
            i1_route[route]
            i1_proxy -.-> i1_route
        end
        i1_client --> i1_proxy
    end
    subgraph POP1
        p1_proxy[relay]
    end
    subgraph POP2
        p2_proxy[relay]
    end
    internet[Internet]
    i1_route -- proxy to pop1 --> p1_proxy
    i1_route -- proxy to pop2 --> p2_proxy
    p1_proxy -- local ---> internet
    p2_proxy -- local ---> internet

每个节点的Proxy分别配置以下功能：

GW

处理客户端请求，可配置成任意一种Server类型，如正向代理、反向代理、TCP映射等。
relay

处理其他区域节点的请求，使用内部协议，例如使用mTLS通道。

简要配置如下：
```
server:
  - name: relay
    type: http_proxy
    escaper: local
    tls_server: {} # 配置TLS参数
```
注意，如果IDC内GW需要支持Socks5 UDP协议，则relay应该配置成UDP代理，需要使用SOCKS 代理。

route

对当地的用户请求进行选路分流，需要配置 >=1 个route类型出口，对每个区域配置一个Proxy出口。

简化配置如下：

escaper:
  - name: route
    type: route_failover
    primary_next: p1_proxy
    standby_next: p2_proxy
    fallback_delay: 100ms  # fallback尝试等待时间（超时后同步对standby出口发起请求）
  - name: p1_proxy
    type: proxy_https # 注意，需适配POP1的relay server类型
    tls_client: {} # 配置TLS参数
    # ... 配置代理参数 指向POP1区域的 relay代理地址
  - name: p2_proxy
    type: proxy_https # 注意，需适配POP2的relay server类型
    tls_client: {} # 配置TLS参数
    # ... 配置代理参数 指向POP2区域的 relay代理地址

33 KiB Raw Blame History Unescape Escape

g3proxy用户指南

如何安装

基础概念

服务管理

热升级

配置结构

监控

基础用法

HTTP代理

SOCKS代理

TCP映射

TLS卸载

TLS封装

SNI代理

透明代理

线路绑定

代理串联

用户名参数 → 串联下一跳地址

连接限速

进程全局限速

域名解析

安全解析

容灾解析

用户认证授权

用户限流限速

用户封禁

进阶用法

mTLS客户端

国密TLCP协议卸载

多协议入口复用

监听多个端口

监听端口启用PROXY Protocol

国密TLCP协议封装

Socks5 UDP IP映射

安全反向代理

域名解析劫持

动态线路绑定

动态代理串联

用户特定站点监控

用户站点TLS劫持自定义配置

流量审计

TLS解密流量导出

任务空闲检测

性能优化

场景设计

多区域加速

双出口容灾

33 KiB

Raw Blame History