Apache代理后Docker部署的TeamCity服务器WebSocket连接异常排查

环境配置 #

Apache虚拟主机配置 #

HTTP配置

<VirtualHost *:80> 
    ServerName teamcity.example.com
    ServerAlias www.teamcity.example.com
    Redirect / https://teamcity.example.com/
</VirtualHost>

HTTPS配置

<IfModule mod_ssl.c>
<VirtualHost *:443> 
 
    ProxyPreserveHost On

    ProxyPreserveHost On
    ProxyRequests Off
    ServerName www.teamcity.example.com
    ServerAlias teamcity.example.com

    ProxyPass / http://localhost:8111/
    ProxyPassReverse / http://localhost:8111/

    # 此配置无效
    ProxyPass           /app/subscriptions ws://localhost:8111/app/subscriptions connectiontimeout=240 timeout=1200
    ProxyPassReverse    /app/subscriptions ws://localhost:8111/app/subscriptions

    # 此配置无效         
    ProxyPass           / http://localhost:8111/ connectiontimeout=5 timeout=300
    ProxyPassReverse    / http://localhost:8111/

    SSLCertificateFile /etc/letsencrypt/live/teamcity.example.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/teamcity.example.com/privkey.pem
    Include /etc/letsencrypt/options-ssl-apache.conf

</VirtualHost>
</IfModule>

已启用的Apache模块 #

sudo apachectl -M | grep proxy
 proxy_module (shared)
 proxy_http_module (shared)
 proxy_wstunnel_module (shared)

Docker Compose配置 #

version: "3.5"
services:
  server:
    image: jetbrains/teamcity-server:latest
    container_name: teamcity_server
    networks:
      - teamcity_network
    ports:
      - "8111:8111"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - datadir:/data/teamcity_server/datadir
      - logs:/opt/teamcity/logs
    environment:
      - TEAMCITY_HTTPS_PROXY_ENABLED=true
  agent:
    image: jetbrains/teamcity-agent:2022.10.1-linux-sudo 
    container_name: teamcity_agent
    volumes:
      - agent_conf:/data/teamcity_agent/conf
    environment:
      - SERVER_URL=https://teamcity.example.com
networks:
  teamcity_network:
volumes:
  datadir:
  logs:
  agent_conf: 

错误信息 #

TeamCity界面提示 #

WebSocket连接问题 部分用户无法通过WebSocket协议使用优化的Web UI更新。受影响会话使用的地址：https://teamcity.example.com 很可能客户端浏览器与TeamCity服务器之间的代理服务器配置不当。

Chrome控制台错误 #

WebSocket连接到 'wss://teamcity.example.com/app/subscriptions?browserLocationHost=https%3A%2F%2Fteamcity.example.com' 失败: openSocket @ 6942286895631677648.js?v=1671191552738:648 open @ 6942286895631677648.js?v=1671191552738:742 start @ 6942286895631677648.js?v=1671191552738:907 (anonymous) @ projects?mode=builds:391

问题诊断与修复 #

核心问题：Apache ProxyPass规则顺序错误 #

Apache的ProxyPass规则按从上到下顺序匹配，先匹配到的规则优先生效。当前配置中，根路径ProxyPass / http://localhost:8111/会匹配所有请求，包括/app/subscriptions，导致后续WebSocket代理规则完全无法触发。同时存在重复的ProxyPreserveHost On和根路径代理配置，属于冗余且易引发冲突的设置。

修正后的Apache HTTPS配置 #

<IfModule mod_ssl.c>
<VirtualHost *:443> 
    ProxyPreserveHost On
    ProxyRequests Off
    ServerName www.teamcity.example.com
    ServerAlias teamcity.example.com

    # 优先匹配WebSocket路径
    ProxyPass           /app/subscriptions ws://localhost:8111/app/subscriptions connectiontimeout=240 timeout=1200
    ProxyPassReverse    /app/subscriptions ws://localhost:8111/app/subscriptions

    # 再匹配所有其他HTTP请求
    ProxyPass           / http://localhost:8111/ connectiontimeout=5 timeout=300
    ProxyPassReverse    / http://localhost:8111/

    SSLCertificateFile /etc/letsencrypt/live/teamcity.example.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/teamcity.example.com/privkey.pem
    Include /etc/letsencrypt/options-ssl-apache.conf

</VirtualHost>
</IfModule>

Docker配置注意事项 #

• TEAMCITY_HTTPS_PROXY_ENABLED=true环境变量配置正确，它会让TeamCity识别自身处于HTTPS代理之后，生成正确的WebSocket连接地址（wss://协议）。
• 确认TeamCity容器的8111端口正常监听，且Apache所在主机可访问localhost:8111（同一主机下当前端口映射配置有效）。

验证步骤 #

1. 重启Apache服务：sudo systemctl restart apache2
2. 清除浏览器缓存后重新访问TeamCity
3. 检查Chrome控制台是否仍存在WebSocket连接错误

内容的提问来源于stack exchange，提问作者jnemecz