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에서 프록시 사용¶
자격 증명이 포함된 프록시 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 구성¶
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 파일을 호환성 파일로 내보낸 후, 대문자와 소문자 변수가 동일한 값을 가는지 확인하세요. 설정을 변경하기 위해 [proxy]을 config.toml로 수정하세요. 생성된 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 아카이브 및 체크섬의 다운로드를 허용해야 합니다.