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/agent.env には機密設定が含まれており、管理者と obs-agent グループのみが読み取り可能な状態を維持してください。

Linux インストール時のプロキシ使用¶

プロキシ変数をエクスポートし、インストーラーをダウンロードして、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>

インストーラーは正規化されたプロキシ設定を /etc/obs-agent/agent.env に書き込みます。サービスを再起動して確認します。

sudo systemctl restart obs-agent
systemctl status obs-agent
journalctl -u obs-agent -n 100

obs-agent forward proxy configured に続いて obs-agent websocket connected が表示されれば、プロキシが読み込まれ Beak への接続が成功したことを示します。認証情報は起動ログでマスクされます。

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

設定をバックアップして編集します。

sudo cp /etc/obs-agent/agent.env /etc/obs-agent/agent.env.bak

大文字・小文字の両方を一貫して設定します。

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>"

ファイルを保護して再起動します。

sudo chown root:obs-agent /etc/obs-agent/agent.env
sudo chmod 0640 /etc/obs-agent/agent.env
sudo systemctl restart obs-agent

ロールバックが必要な場合は sudo cp /etc/obs-agent/agent.env.bak /etc/obs-agent/agent.env でバックアップを復元します。

自動更新のプロキシ維持¶

Linux の更新サービスおよび手動アップデーターは /etc/obs-agent/agent.env を読み取ります。同じプロキシが 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 の設定¶

プロキシが TLS 証明書を再署名する場合、CA バンドルをマウントして SSL_CERT_FILE または SSL_CERT_DIR を設定します。Linux では、CA を root 所有のディレクトリに保存し、変数を /etc/obs-agent/agent.env に追加します。Docker または Kubernetes では、CA を読み取り専用でマウントし、SSL_CERT_FILE をコンテナ内のパスに設定します。TLS 検証を無効にしないでください。

SSL_CERT_FILE=/etc/obs-agent/certs/enterprise-ca.pem

プロキシを使用するリクエストの確認¶

プロキシは、Beak 設定 API および WebSocket トラフィック、LLM および AI Hub リクエスト、リモート MCP HTTP トラフィック、リリースメタデータとダウンロード、インストーラーおよびアップデーターリクエスト、Owl 更新リクエストに適用されます。ローカルファイルシステムおよびプロセスツールはプロキシを使用しません。NO_PROXY に一致するターゲットは直接接続されます。

プロキシ接続のトラブルシューティング¶

Agent がプロキシ変数の競合を報告する¶

大文字・小文字の両方を確認し、値を一致させます。

sudo grep -E '^(HTTP_PROXY|http_proxy|HTTPS_PROXY|https_proxy|NO_PROXY|no_proxy)=' \
  /etc/obs-agent/agent.env

プロキシが 407 Proxy Authentication Required を返す¶

ユーザー名、パスワード、およびプロキシ認可ポリシーを確認してください。認証情報内の特殊文字は URL エンコードしてください。トラブルシューティング中に完全なプロキシ URL を表示しないでください。

HTTPS リクエストで証明書エラーが報告される¶

エンタープライズ CA がマウントされ、obs-agent が読み取り可能であり、SSL_CERT_FILE または SSL_CERT_DIR で選択されていることを確認してください。プロキシエンドポイントは http:// のままにしてください。HTTPS ターゲットは CONNECT トンネル内で保護されます。

内部アドレスが誤ってプロキシを使用する¶

内部ドメイン、IP、または CIDR を NO_PROXY と no_proxy の両方に追加してください。NO_PROXY=* はすべてのターゲットのプロキシをバイパスするため、恒久的な設定として使用しないでください。

Agent は接続するが自動更新が失敗する¶

journalctl -u obs-agent-update-check.service -n 100 と journalctl -u obs-agent -n 100 を確認してください。AGENT_UPDATE_BASE_URL のドメインが NO_PROXY に誤って記載されていないこと、およびプロキシが latest-version.json、install.sh、リリースアーカイブ、チェックサムへのアクセスを許可していることを確認してください。