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에서 프록시 사용¶

자격 증명이 포함된 프록시 URL을 Agent 자격 증명과 함께 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 또는 값을 변경한 후에는 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, 릴리스 아카이브, 체크섬을 허용하는지 확인합니다.