TeamCity On-Premises 2026.2 Help

プロキシサーバーの構成者対象設定タイトル

この記事では、次のプロキシタイプの構成に関する一般的な推奨事項を示します。

プロキシ背後での TeamCity サーバーの設定

例を考えてみます:
TeamCity サーバーは ローカル URL http://teamcity.local:8111/tc にインストールされています。
外部からは 公開 URL http://teamcity.public:400/tc として見えます。

クライアントがリソースへのアクセスに使用する実際の絶対 URL を TeamCity が「認識」していることを確認するには、次の操作が必要です:

  • 以下の説明に従って、リバースプロキシを設定します。

  • TeamCity にバンドルされている Tomcat サーバーを構成します。

これらの URL は、クライアントのリダイレクトやその他の応答で絶対 URL を生成するために使用されます。

プロキシを設定した後、 サーバー URL の値も、TeamCity グローバル設定 でプロキシ URL に変更する必要があります。

注: 内部 TeamCity サーバーは、外部アドレスによって外部から見えるため、 同じコンテキスト (ホストお名前の後にある URL の一部) で動作する必要があります。 TeamCity サーバーの コンテキスト変更手順も参照してください。
サーバーを別のコンテキストで実行する必要がある場合は、コンテキストを変更するプロキシが TeamCity からこの事実を隠す必要があることに注意してください。たとえば、サーバーのリダイレクト URL と Cookie 設定パスを元の (外部) コンテキストにマッピングする必要があります。

プロキシは、一般的な Web セキュリティを念頭に置いて構成する必要があります。 リファラー や オリジン などのヘッダー、およびすべての不明なヘッダーは、変更されていない形式で TeamCity Web アプリケーションに渡す必要があります。 たとえば、TeamCity はクライアントによって追加された X-TC-CSRF-Token ヘッダーに依存しています。

Apache

バージョン 2.4.5 以降を推奨します。 以前のバージョンは WebSocket プロトコルをサポートしていません。

Apache を使用する場合は、TeamCity サーバーの構成に 専用の "Connector" ノード方式を必ず使用してください。

LoadModule proxy_module /usr/lib/apache2/modules/mod_proxy.so LoadModule proxy_http_module /usr/lib/apache2/modules/mod_proxy_http.so LoadModule headers_module /usr/lib/apache2/modules/mod_headers.so LoadModule proxy_wstunnel_module /usr/lib/apache2/modules/mod_proxy_wstunnel.so ProxyRequests Off ProxyPreserveHost On ProxyPass /tc/app/subscriptions ws://teamcity.local:8111/tc/app/subscriptions connectiontimeout=240 timeout=1200 ProxyPassReverse /tc/app/subscriptions ws://teamcity.local:8111/tc/app/subscriptions ProxyPass /tc http://teamcity.local:8111/tc connectiontimeout=240 timeout=1200 ProxyPassReverse /tc http://teamcity.local:8111/tc ## The following entries are required to allow the Agent Terminal feature to function with websockets ProxyPass /tc/plugins/teamcity-agent-terminal/ ws://teamcity.local:8111/tc/plugins/teamcity-agent-terminal/ connectiontimeout=240 timeout=1200 ProxyPassReverse /tc/plugins/teamcity-agent-terminal/ ws://teamcity.local:8111/tc/plugins/teamcity-agent-terminal/ ProxyPass /tc/app/agentTerminal/ ws://teamcity.local:8111/tc/app/agentTerminal/ connectiontimeout=240 timeout=1200 ProxyPassReverse /tc/app/agentTerminal/ ws://teamcity.local:8111/tc/app/agentTerminal/

ProxyPass ルールの順序に注意してください: 競合する ProxyPass ルールは、最も長い URL から順に並べ替える必要があります。

デフォルトでは、Apache は限られた数の並列接続のみを許可しますが、WebSocket プロトコルを使用する場合は不十分な場合があります。 たとえば、多くのクライアントが Web UI を開くと、TeamCity サーバーが応答しなくなる可能性があります。 これを修正するには、Apache 構成を微調整する必要がある場合があります。

たとえば、Unix では mpm_worker に切り替えて、同時接続の最大数を構成します:

<IfModule mpm_worker_module> ServerLimit 100 StartServers 3 MinSpareThreads 25 MaxSpareThreads 75 ThreadLimit 64 ThreadsPerChild 25 MaxClients 2500 MaxRequestsPerChild 0 </IfModule>

Windows では、 Apache ドキュメント(英語)に従って、 ThreadsPerChild(英語) 値を増やす必要がある場合があります。

NGINX

バージョン 1.3 以降を推奨します。 以前のバージョンは WebSocket プロトコルをサポートしていません。

http { ... default settings here proxy_read_timeout 1200; proxy_connect_timeout 240; client_max_body_size 0; # maximum size of an HTTP request. 0 allows uploading large artifacts to TeamCity map $http_upgrade $connection_upgrade { # WebSocket support default upgrade; '' ''; } server { listen 400; # public server port server_name teamcity.public; # public server host name location / { # public context (should be the same as internal context) proxy_pass http://teamcity.local:8111; # full internal address proxy_http_version 1.1; proxy_set_header Host $server_name:$server_port; proxy_set_header X-Forwarded-Host $http_host; # necessary for proper absolute redirects and TeamCity CSRF check proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header Upgrade $http_upgrade; # WebSocket support proxy_set_header Connection $connection_upgrade; # WebSocket support } } }

IIS

IIS リバースプロキシの背後に TeamCity サーバーを構成するには:

  1. TeamCity サーバーの正規名 (CNAME) レコードを作成します。

  2. TeamCity サーバーと外部ユーザー間の安全な接続を保証する証明書を発行します。 証明書がよく知られた認証局によって発行されたものでない場合は、TeamCity に接続するすべてのマシン上の Java 証明書ストアに証明書を手動で追加する必要がある場合があります:

    keytool -importcert -file <cert file> -keystore <path to JRE installation>/lib/security/cacerts

  3. サーバー URL をプロキシ URL に変更します。

  4. <TeamCity_ホームディレクトリ>/conf/server.xml ファイルを編集し、 TeamCity Tomcat 構成 セクションの説明に従って、必要な TeamCity Tomcat サーバープロパティを設定します。

  5. 手順 5 ～ 8 は Powershell で実行します。 Get-IISConfigSection および Set-IISConfigAttributeValue コマンドレットを使用して、SSL フラグを有効にします。

    $ConfigSectionTC = Get-IISConfigSection -SectionPath "system.webServer/security/access" -Location "<IIS Website name>"; Set-IISConfigAttributeValue -AttributeName sslFlags -AttributeValue Ssl -ConfigElement $ConfigSectionTC;

  6. Set-WebConfigurationProperty コマンドレットを使用して、HTTP 転送された IP が Web 要求から渡されるようにするサーバー変数を追加します。

    Set-WebConfigurationProperty -pspath "IIS:/" -Location "<IIS Website name>" -filter "system.webServer/rewrite/allowedServerVariables" -name "." -value @{name="HTTP_FORWARDED"} -FORCE

  7. プロキシ設定を有効にする:

    Set-WebConfigurationProperty -pspath "MACHINE/WEBROOT/APPHOST" -filter "system.webServer/proxy" -name "." -value @{ enabled="true" } -FORCE

  8. TeamCity アーティファクトに外部ストレージを使用している場合は、 レスポンスヘッダー内のホストを逆書き換え パラメーターを無効にします:

    Set-WebConfigurationProperty -pspath "MACHINE/WEBROOT/APPHOST" -filter "system.webServer/proxy" -name "." -value @{ reverseRewriteHostInResponseHeaders="false" } -FORCE

  9. IIS web.config ファイルを次のように変更します。

    <?xml version="1.0" encoding="UTF-8"?> <configuration> <system.web> <httpRuntime requestPathInvalidCharacters="" /> </system.web> <system.webServer> <rewrite> <rules useOriginalURLEncoding="true"> <rule name="teamcity" enabled="true" patternSyntax="Wildcard" stopProcessing="true"> <match url="*" /> <action type="Rewrite" url="http://localhost:80/{R:0}" /> <serverVariables> <set name="HTTP_FORWARDED" value="for={REMOTE_ADDR};by={LOCAL_ADDR};host=&quot;{HTTP_HOST}&quot;;proto=&quot;https&quot;" /> </serverVariables> </rule> </rules> </rewrite> <security> <requestFiltering allowDoubleEscaping="true"> <fileExtensions> <remove fileExtension=".config" /> </fileExtensions> <hiddenSegments> <remove segment="bin" /> </hiddenSegments> </requestFiltering> </security> </system.webServer> </configuration>

その他のサーバー

リクエスト（アップロード）およびレスポンス（ダウンロード）のサイズとタイムアウト（コードベースとアーティファクトのサイズに応じて少なくとも数十分とギガバイト）に対して適切な（高い）制限を設定して、パフォーマンスの高いプロキシを必ず使用してください。

UI をすばやくリフレッシュするのに役立つため、WebSocket プロトコルで動作できるプロキシを使用することをお勧めします。

一般に、クライアントが使用する元の URL を「認識」し、クライアントがアクセスできる正しい絶対 URL を生成できるように、TeamCity サーバーを構成する必要があります。 これを実現するには、元の ホスト ヘッダーを TeamCity に渡すのが望ましい方法です。 別の方法としては、 X-Forwarded-Host ヘッダーを元の ホスト ヘッダーの値に設定する方法があります。

ホスト ヘッダーの値がプロキシによって変更される場合 (元の ホスト ヘッダー値を保持することが推奨されます)、かつ元の ホスト 値を持つ X-Forwarded-Host ヘッダーが提供されていない場合は、 オリジン ヘッダーと リファラー ヘッダーの値に元の ホスト ヘッダー値が含まれているなら、それに応じてマッピングする必要があります (含まれていない場合、TeamCity の CSRF 保護を回避しないように、これらの値を設定しないでください)。

以下のセクションから適切な方法を選択し、それに応じてプロキシを設定してください。

よくある誤設定

リバースプロキシ（または同様のツール）が以下の要件に準拠していることを確認してください。

  • ドットで始まるパス（。 ）を持つ URL がサポートされています（非表示のアーティファクトへのパスには .teamcity ディレクトリが含まれています）。

  • コロン (：) を含む URL がサポートされています (多くの TeamCity リソースでコロンが使用されます)。 関連する IIS の設定。 症状: アーティファクトがあっても、ビルドに「このビルドにはユーザー定義のアーティファクトはありません 」テキストを含むアーティファクトがありません。

  • 最大リクエスト名、応答長、応答時間を制限する設定は、それほど制限的ではありません。 詳細については、こちらの記事を参照してください: IIS 関連の課題。

  • gzip コンテンツエンコーディングは完全にサポートされています。 例: 特定の IIS 構成では、UI に「データを読み込んでいます ...」と表示され、500 HTTP 応答が返されることがあります (関連する 問題(英語)を参照)。

IIS 関連の問題:

  • "PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target" エラーが発生した場合は、TeamCity が使用しているものと同じ Java キーストアに証明書を追加します。

  • HTTP 404 または 50x エラーで間違ったサーバー名が返された場合は、リダイレクトルールと転送されたヘッダーを確認してください。

TeamCity Tomcat 構成

TeamCity Tomcat 構成では、パブリック URL の詳細をハードコードしたサーバー構成で 専用の "Connector" ノード を使用し、コネクターで構成されたポートが、構成されたパブリック URL へのリクエストでのみ使用されるようにしてください。

設定されたポートが設定されたパブリック URL にのみ要求を受信している場合、このアプローチは任意のプロキシ設定で使用できます。

<TeamCity ホーム>/conf/server.xml ファイル内の「コネクター」ノードを以下のように変更する必要があります。

<Connector port="8111" protocol="org.apache.coyote.http11.Http11NioProtocol" connectionTimeout="60000" useBodyEncodingForURI="true" socket.txBufSize="64000" socket.rxBufSize="64000" tcpNoDelay="1" secure="false" scheme="http" />

パブリックサーバーアドレスが HTTPS の場合は、 セキュア="true" 属性と スキーム="https" 属性を使用します。 これらの属性が欠落している場合、TeamCity は対応するヘルスレポートを表示します。

TeamCity サーバーが IIS リバースプロキシの背後に構成されている場合:

<Connector port="80" protocol="org.apache.coyote.http11.Http11NioProtocol" connectionTimeout="60000" redirectPort="8543" useBodyEncodingForURI="true" socket.txBufSize="64000" socket.rxBufSize="64000" tcpNoDelay="1" proxyName="<your_CNAME_value>" proxyPort="443" secure="true" scheme="https" /> <Valve className="org.apache.catalina.valves.RemoteIpValve" remoteIpHeader="x-forwarded-for" protocolHeader="x-forwarded-proto" portHeader="x-forwarded-port" internalProxies="<internal_proxy_ip>" />

発信 TeamCity サーバー接続にプロキシを使用する

このセクションでは、TeamCity が発信 HTTP 接続にプロキシサーバーを使用するように構成する方法について説明します。

TeamCity サーバーは、課題トラッカーなどの他のサービスへの特定の発信 HTTP 接続にプロキシサーバーを使用できます。

TeamCity をプロキシサーバーに向けるには、次の 内部プロパティを設定します:

# For HTTP protocol ## The domain name or the IP address of the proxy host and the port: teamcity.http.proxyHost=proxy.domain.com teamcity.http.proxyPort=8080   ## The hosts that should be accessed without going through the proxy, usually internal hosts. Provide a list of hosts, separated by the '|' character. The wildcard '*' can be used: teamcity.http.nonProxyHosts=localhost|*.mydomain.com   ## For an authenticated proxy add the following properties: ### Authentication type. "basic" and "ntlm" values are supported. The default is "basic". teamcity.http.proxyAuthenticationType=basic ### Login and Password for the proxy. Used only with the "basic" auth type teamcity.http.proxyLogin=login teamcity.http.proxyPassword=password ### Windows NT credentials for NTLM authentication. Used only with the "ntlm" auth type teamcity.http.proxyAuthentication=NT_credentials   # For HTTPS protocol ## The domain name or the IP address of the proxy host and the port: teamcity.https.proxyHost=proxy.domain.com teamcity.https.proxyPort=8080   ## The hosts that should be accessed without going through the proxy, usually internal hosts. Provide a list of hosts, separated by the '|' character. The wildcard '*' can be used: teamcity.https.nonProxyHosts=localhost|*.mydomain.com   ## For an authenticated proxy add the following properties: ### Authentication type. "basic" and "ntlm" values are supported. The default is "basic". teamcity.https.proxyAuthenticationType=basic ### Login and Password for the proxy. Used only with the "basic" auth type teamcity.https.proxyLogin=login teamcity.https.proxyPassword=password ### Windows NT credentials for NTLM authentication. Used only with the "ntlm" auth type teamcity.https.proxyAuthentication=NT_credentials

発信ビルドエージェント接続にプロキシを使用する

通常、ビルドエージェントはさまざまなアウトバウンド接続を行う必要があります: TeamCity サーバー、S3 アーティファクトストレージ、VCS ホストなどへの接続です。 このセクションでは、ビルドエージェントがプロキシの背後にデプロイされた後も送信接続が機能し続けるように、ビルドエージェントを構成する方法について説明します。

TeamCity エージェント側で、 ビルドエージェント.プロパティ ファイルの次のプロパティを使用して、TeamCity サーバーに接続するためのプロキシを指定します：

## The domain name or the IP address of the proxy host and the port teamcity.http.proxyHost=123.45.678.9 teamcity.http.proxyPort=8080   ## If the proxy requires authentication, specify the login and password teamcity.http.proxyLogin=login teamcity.http.proxyPassword=password

HTTPS エンドポイント (GitHub でホストされるリポジトリなど) にアクセスするには、 teamcity.https.* プロパティも構成します。

マルチノードセットアップ用のプロキシサーバー

TeamCity サーバーは、高可用性と柔軟な負荷分散のために複数のノード (またはサーバー) を使用するように構成できます。 NGINX および HAProxy 構成の例については、この記事 (高可用性のためのマルチノードセットアップ) を参照してください。

2026 年 9 月 11 日
TeamCity のコンテンツセキュリティポリシーサーバー上のユーザーセッションの終了