如何将Synapse的Nginx Map配置转换为Apache2.4等效配置？

需求背景 #

需要把Matrix Synapse工作节点的Nginx配置（含URL路由map规则）转换为Apache 2.4配置，用于集成Shibboleth。已了解Nginx upstream对应Apache Proxy Balancer，但不清楚如何实现map的URL路由逻辑。

第一步：配置Apache负载均衡器（对应Nginx upstream） #

将Nginx的各个upstream转换为Apache的Balancer配置，其中generic-worker的ip_hash策略对应Apache的lbmethod=iphash：

# 对应Nginx的upstream synapse
<Proxy balancer://synapse>
    BalancerMember http://127.0.0.1:8008
</Proxy>

# 对应Nginx的upstream generic-worker（基于客户端IP哈希分配请求）
<Proxy balancer://generic-worker>
    BalancerMember http://127.0.0.1:8008
    BalancerMember http://127.0.0.1:8081
    ProxySet lbmethod=iphash
</Proxy>

# 对应Nginx的upstream media_repository
<Proxy balancer://media_repository>
    BalancerMember http://127.0.0.1:8085
</Proxy>

第二步：实现URL路由规则（对应Nginx的map） #

Apache没有直接等价的map指令，但可以通过两种方式实现相同的URL路由逻辑：

方式一：优先级匹配的ProxyPassMatch规则 #

利用Apache规则从上到下匹配的特性，将特定URL的路由规则放在默认规则之前，优先生效：

<VirtualHost *:80>
    # 基础配置（替换为你的ServerName等）
    ServerName your-matrix-domain.tld
    [...]

    # 配置代理请求头，对应Nginx的proxy_set_header
    RequestHeader set X-Forwarded-For "%{REMOTE_ADDR}s"
    RequestHeader set X-Forwarded-Proto "%{REQUEST_SCHEME}s"
    RequestHeader set Host "%{HTTP_HOST}s"

    # 设置最大请求体大小（50MB），对应Nginx的client_max_body_size 50M
    LimitRequestBody 52428800

    # 开启HTTP/1.1代理，对应Nginx的proxy_http_version 1.1
    ProxyPass / balancer://synapse/ disablereuse=On
    ProxyPassReverse / balancer://synapse/

    # 匹配generic-worker对应的URL规则，优先级高于默认路由
    ProxyPassMatch "^/_matrix/client/(r0|v3)/sync$" balancer://generic-worker/ disablereuse=On
    ProxyPassReverse "^/_matrix/client/(r0|v3)/sync$" balancer://generic-worker/

    ProxyPassMatch "^/_matrix/client/(api/v1|r0|v3)/events$" balancer://generic-worker/ disablereuse=On
    ProxyPassReverse "^/_matrix/client/(api/v1|r0|v3)/events$" balancer://generic-worker/

    ProxyPassMatch "^/_matrix/client/(api/v1|r0|v3)/initialSync$" balancer://generic-worker/ disablereuse=On
    ProxyPassReverse "^/_matrix/client/(api/v1|r0|v3)/initialSync$" balancer://generic-worker/

    ProxyPassMatch "^/_matrix/client/(api/v1|r0|v3)/rooms/[^/]+/initialSync$" balancer://generic-worker/ disablereuse=On
    ProxyPassReverse "^/_matrix/client/(api/v1|r0|v3)/rooms/[^/]+/initialSync$" balancer://generic-worker/

    # 若有media_repository的URL规则，添加类似规则即可
    # ProxyPassMatch "^/_matrix/media/..." balancer://media_repository/ disablereuse=On
    # ProxyPassReverse "^/_matrix/media/..." balancer://media_repository/

    # 只代理/_matrix和/_synapse路径，排除其他请求
    <LocationMatch "^/(?!_matrix|_synapse)">
        ProxyPass !
    </LocationMatch>
</VirtualHost>

方式二：环境变量路由（更接近Nginx map逻辑） #

通过RewriteRule设置环境变量，再根据变量值路由到对应Balancer，逻辑更紧凑：

<VirtualHost *:80>
    ServerName your-matrix-domain.tld
    [...]

    # 开启重写引擎
    RewriteEngine On

    # 匹配generic-worker的URL，设置环境变量
    RewriteRule "^/_matrix/client/(r0|v3)/sync$" "-" [E=BALANCER:generic-worker]
    RewriteRule "^/_matrix/client/(api/v1|r0|v3)/events$" "-" [E=BALANCER:generic-worker]
    RewriteRule "^/_matrix/client/(api/v1|r0|v3)/initialSync$" "-" [E=BALANCER:generic-worker]
    RewriteRule "^/_matrix/client/(api/v1|r0|v3)/rooms/[^/]+/initialSync$" "-" [E=BALANCER:generic-worker]

    # 默认路由到synapse（仅匹配/_matrix和/_synapse路径）
    RewriteRule "^/(?:_matrix|_synapse)" "-" [E=BALANCER:synapse]

    # 代理请求头与参数配置
    RequestHeader set X-Forwarded-For "%{REMOTE_ADDR}s"
    RequestHeader set X-Forwarded-Proto "%{REQUEST_SCHEME}s"
    RequestHeader set Host "%{HTTP_HOST}s"
    LimitRequestBody 52428800

    # 根据环境变量路由到对应Balancer
    ProxyPass / balancer://%{ENV:BALANCER}/ disablereuse=On
    ProxyPassReverse / balancer://%{ENV:BALANCER}/

    # 排除非/_matrix和/_synapse的请求
    <LocationMatch "^/(?!_matrix|_synapse)">
        ProxyPass !
    </LocationMatch>
</VirtualHost>

关键配置说明 #

• disablereuse=On：确保HTTP/1.1连接行为与Nginx一致，避免连接复用导致的问题。
• LimitRequestBody 52428800：对应50MB的最大请求体，数值单位为字节。
• lbmethod=iphash：实现与Nginx ip_hash相同的会话粘性，基于客户端IP分配请求到固定工作节点。

内容的提问来源于stack exchange，提问作者Aurélien Grimpard