コンテンツにスキップ

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コマンドは、現在のシェル内で実行され、エクスポートされたプロキシ変数を使用します。インストールプログラムは、正規化された設定を次の場所に記録します:

/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
systemctl status obs-agent
journalctl -u obs-agent -n 100

これらのログメッセージによると、Agentがプロキシの設定を読み込み、Beakに接続したことがわかります。

obs-agent forward proxy configured
obs-agent websocket connected

スタートアップのログには、プロキシのURLにユーザー名やパスワードが隠されています。

既存の Linux インストールへのプロキシ追加

設定をバックアップする:

sudo cp /etc/obs-agent/config.toml /etc/obs-agent/config.toml.bak

/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をシステムの信頼ストアにインストールするか、以下の設定を行ってください:

export SSL_CERT_FILE='/etc/ssl/certs/<CORPORATE-CA-FILE>'

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のアーカイブやチェックサムのダウンロードを許可する必要があります。

フィードバック

このページは役に立ちましたか?