obs-agent フォワードプロキシの設定¶
このガイドでは、セルフホスト型 obs-agent のトラフィックを HTTP フォワードプロキシ経由で Beak、LLM および AI Hub サービス、リモート MCP サーバー、Agent リリースサービスにルーティングする方法を説明します。
プロキシ情報の準備¶
プロキシ URL とバイパスリストを準備します。
export HTTP_PROXY='http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>'
export HTTPS_PROXY="$HTTP_PROXY"
export NO_PROXY='localhost,127.0.0.1,::1,<INTERNAL-DOMAIN>'
現在のバージョンでは、認証なし HTTP プロキシ、URL ユーザー情報での Basic Auth、HTTP_PROXY・HTTPS_PROXY・NO_PROXY の大文字・小文字両形式、および SSL_CERT_FILE または SSL_CERT_DIR で選択するエンタープライズ CA をサポートしています。
プロキシエンドポイントは http:// を使用する必要があります。HTTPS および WSS ターゲットの場合、Agent は HTTP CONNECT トンネルを確立し、ターゲットの TLS 証明書を検証します。同じ変数の大文字形式と小文字形式の両方が設定されている場合、値は一致している必要があります。インストーラーはもう一方の形式を自動補完し、NO_PROXY には常に localhost,127.0.0.1,::1 を保持します。
プロキシ認証情報の保護
プロキシURLにはユーザー名やパスワードが含まれている可能性があります。チケット、公開ログ、チャット、スクリーンショットには、完全なURLを含めないでください。/etc/obs-agent/config.tomlには機密情報が含まれており、その内容は管理者やobs-agentグループのみが閲覧可能です。
Linux インストール時のプロキシ使用¶
プロキシ変数をエクスポートした後、Beakのインストールページからインストールコマンドを実行してください。sudoを使用する場合は、これらの変数を明確に保持してください。
export HTTP_PROXY='http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>'
export HTTPS_PROXY="$HTTP_PROXY"
export NO_PROXY='localhost,127.0.0.1,::1,<INTERNAL-DOMAIN>'
curl -fsSL https://static.guance.com/obs-agent/install.sh \
-o /tmp/obs-agent-install.sh
sudo --preserve-env=HTTP_PROXY,http_proxy,HTTPS_PROXY,https_proxy,NO_PROXY,no_proxy,SSL_CERT_FILE,SSL_CERT_DIR \
bash /tmp/obs-agent-install.sh <INSTALL-OPTIONS-FROM-BEAK>
最初のcurlコマンドは、現在のシェル内で実行され、エクスポートされたプロキシ変数を使用します。インストールプログラムは、正規化された設定を次の場所に記録します:
インストール後、互換性ファイルを同期し、サービスを再起動して確認してください:
sudo obs-agent --config-tool agent-export --input /etc/obs-agent/config.toml --output /etc/obs-agent/agent.env
sudo systemctl restart obs-agent
systemctl status obs-agent
journalctl -u obs-agent -n 100
これらのログメッセージによると、Agentがプロキシの設定を読み込み、Beakに接続したことがわかります。
スタートアップのログには、プロキシのURLにユーザー名やパスワードが隠されています。
既存の Linux インストールへのプロキシ追加¶
設定をバックアップする:
/etc/obs-agent/config.tomlを編集し、プロキシグループを設定します:
[proxy]
http = "http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>"
https = "http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>"
no_proxy = ["localhost", "127.0.0.1", "::1", "<INTERNAL-DOMAIN>"]
ファイルの所有権と権限を確認し、互換性ファイルをエクスポートし、再起動してください。
sudo chown root:obs-agent /etc/obs-agent/config.toml
sudo chmod 0640 /etc/obs-agent/config.toml
sudo obs-agent --config-tool agent-export --input /etc/obs-agent/config.toml --output /etc/obs-agent/agent.env
sudo systemctl restart obs-agent
以前の設定に戻すために:
sudo cp /etc/obs-agent/config.toml.bak /etc/obs-agent/config.toml
sudo obs-agent --config-tool agent-export --input /etc/obs-agent/config.toml --output /etc/obs-agent/agent.env
sudo systemctl restart obs-agent
自動更新のプロキシ維持¶
Linuxのアップデートサービスや、以前のアップデートツールは、依然として/etc/obs-agent/agent.envを読み取っています。TOMLを編集した後、上記のエクスポートコマンドを実行して、このファイルを同期させてください。直接、生成されたファイルを編集しないでください。同じプロキシが、latest-version.jsonの取得、install.shのダウンロード、アーカイブのリリースやチェックサムの計算、Beakへのアップグレードステータスの報告、そしてOwlやCLIの更新に使用されます。
systemctl status obs-agent-update-check.timer
systemctl list-timers obs-agent-update-check.timer
journalctl -u obs-agent-update-check.service -n 100
sudo systemctl start obs-agent-update-check.service
journalctl -u obs-agent-update-check.service -n 100
sudo /usr/local/bin/obs-agent-updater
プロキシが利用不可またはプロキシ認証が失敗した場合、更新は失敗しますがインストール済みバージョンは変更されません。直接インターネットアクセスへの暗黙のフォールバックは行われません。
Docker でのプロキシ使用¶
プロキシ変数を保護された env ファイルに保存します。
cat > obs-agent-proxy.env <<'EOF'
HTTP_PROXY=http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>
http_proxy=http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>
HTTPS_PROXY=http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>
https_proxy=http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>
NO_PROXY=localhost,127.0.0.1,::1,<INTERNAL-DOMAIN>
no_proxy=localhost,127.0.0.1,::1,<INTERNAL-DOMAIN>
EOF
chmod 0600 obs-agent-proxy.env
docker run -d \
--name obs-agent \
--restart unless-stopped \
--env-file ./obs-agent.env \
--env-file ./obs-agent-proxy.env \
-v obs-agent-work:/app \
-v obs-agent-profile-cache:/var/lib/obs-agent/profile-cache \
"${OBS_AGENT_IMAGE}"
エントリーポイントは Beak 設定を要求する前にプロキシ変数を検証します。docker logs obs-agent 2>&1 | tail -n 100 で確認してください。
Kubernetes または Helm でのプロキシ使用¶
Agent 認証情報と合わせて、認証情報付きのプロキシ URL を Kubernetes Secret に保存します。
kubectl -n obs-agent create secret generic obs-agent-secret \
--from-literal=AGENT_ID='<AGENT-ID>' \
--from-literal=AGENT_API_KEY='<AGENT-API-KEY>' \
--from-literal=HTTP_PROXY='http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>' \
--from-literal=HTTPS_PROXY='http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>'
Deployment で Secret を参照し、NO_PROXY を別途設定します。Helm の場合、secret.keys に HTTP_PROXY と HTTPS_PROXY を含めてからアップグレードします。
helm upgrade obs-agent obs-agent/obs-agent \
--namespace obs-agent \
--reuse-values \
--set 'secret.keys={AGENT_API_KEY,AGENT_ID,HTTP_PROXY,HTTPS_PROXY}'
Secret または values を変更した後、Pod が再作成されるのを待ち、kubectl -n obs-agent logs deploy/obs-agent --tail=100 で確認してください。
エンタープライズ CA の設定¶
HTTP CONNECTトンネルでは、通常は対象の証明書に代わるものではないため、追加のCAは必要ありません。もしプロキシがTLSを監視し、企業のCAで証明書を署名する場合は、そのCAをシステムの信頼ストアにインストールするか、以下の設定を行ってください:
Linuxのインストーラーは、明示的に設定されたSSL_CERT_FILEまたはSSL_CERT_DIRの値をconfig.tomlに書き込み、古いアップデート用のagent.envを生成します。コンテナ内では、CAファイルを読み取り専用にマウントし、そのコンテナパスを使用します。
docker run -d \
--name obs-agent \
--env-file ./obs-agent.env \
--env-file ./obs-agent-proxy.env \
-e SSL_CERT_FILE=/etc/ssl/certs/corporate-ca.pem \
-v /etc/obs-agent/corporate-ca.pem:/etc/ssl/certs/corporate-ca.pem:ro \
"${OBS_AGENT_IMAGE}"
証明書のエラーを回避するために、TLS検証を無効にしないでください。
プロキシを使用するリクエストの確認¶
プロキシは、Beak 設定 API および WebSocket トラフィック、LLM および AI Hub リクエスト、リモート MCP HTTP トラフィック、リリースメタデータとダウンロード、インストーラーおよびアップデーターリクエスト、Owl 更新リクエストに適用されます。ローカルファイルシステムおよびプロセスツールはプロキシを使用しません。NO_PROXY に一致するターゲットは直接接続されます。
プロキシ接続のトラブルシューティング¶
Agent がプロキシ変数の競合を報告する¶
TOML を互換ファイルにエクスポートし、大文字と小文字の変数の値が一致することを確認します。設定の変更は config.toml の [proxy] で行ってください。生成された agent.env を直接編集しないでください。
sudo obs-agent --config-tool agent-export --input /etc/obs-agent/config.toml --output /etc/obs-agent/agent.env
sudo grep -E '^(HTTP_PROXY|http_proxy|HTTPS_PROXY|https_proxy|NO_PROXY|no_proxy)=' \
/etc/obs-agent/agent.env
TOMLを修正した後、エクスポートして再起動してください:
sudo obs-agent --config-tool agent-export --input /etc/obs-agent/config.toml --output /etc/obs-agent/agent.env
sudo systemctl restart obs-agent
プロキシが 407 Proxy Authentication Required を返す¶
ユーザー名、パスワード、およびプロキシ認可ポリシーを確認してください。認証情報内の特殊文字は URL エンコードしてください。トラブルシューティング中に完全なプロキシ URL を表示しないでください。
HTTPS リクエストで証明書エラーが報告される¶
企業のCAファイルが存在することを確認し、Agentがそのファイルを読み取れることを確認してください。設定をエクスポートし、CAの設定を確認してください。
sudo test -r /etc/ssl/certs/<CORPORATE-CA-FILE>
sudo obs-agent --config-tool agent-export --input /etc/obs-agent/config.toml --output /etc/obs-agent/agent.env
sudo grep -E '^(SSL_CERT_FILE|SSL_CERT_DIR)=' /etc/obs-agent/agent.env
CAを修正した後、Agentを再起動し、自動更新のチェックを行ってください。
sudo obs-agent --config-tool agent-export --input /etc/obs-agent/config.toml --output /etc/obs-agent/agent.env
sudo systemctl restart obs-agent
sudo systemctl start obs-agent-update-check.service
内部アドレスが誤ってプロキシを使用する¶
内部ドメイン、IP、または CIDR を NO_PROXY と no_proxy の両方に追加してください。NO_PROXY=* はすべてのターゲットのプロキシをバイパスするため、恒久的な設定として使用しないでください。
Agent は接続するが自動更新が失敗する¶
アップデートサービスで使用されている設定やログを確認してください:
sudo systemctl cat obs-agent-update-check.service
sudo journalctl -u obs-agent-update-check.service -n 100
sudo obs-agent --config-tool agent-export --input /etc/obs-agent/config.toml --output /etc/obs-agent/agent.env
sudo grep '^AGENT_UPDATE_BASE_URL=' /etc/obs-agent/agent.env
AGENT_UPDATE_BASE_URLに登録されているドメインが、NO_PROXYに誤って登録されていないことを確認してください。プロキシは、latest-version.json、install.sh、Agentのアーカイブやチェックサムのダウンロードを許可する必要があります。