본문으로 이동

문서

Docker로 OpenConnector 자체 호스팅

로컬 runtime을 시작하고 첫 Action을 호출하며, 계정을 연결하고 배포용 영구 저장소와 인증을 준비하세요.

유지 관리: OOMOL·

소스 확인일: 2026-09-09. 예제는 링크된 소스 리비전과 대조했습니다. 실제 외부 API 검증을 의미하지 않으며, 배포된 버전과 다를 수 있습니다.

런타임 시작

Git과 Docker Compose가 포함된 Docker 환경이 필요합니다. 앱 계정을 설정하기 전에 인증이 필요 없는 Action부터 호출하세요. 저장소를 복제하고 배포된 이미지를 실행하세요. 이 체험 과정은 자신의 컴퓨터에서 로컬로 진행하세요.

Docker
git clone https://github.com/oomol-lab/open-connector.git
cd open-connector
docker compose up

첫 Action 호출

다른 터미널에서 Hacker News 인기 기사를 가져오세요. 이 읽기 전용 Action에는 제공업체 계정이 필요하지 않습니다.

HTTP · Hacker News
curl -s -X POST \
  http://localhost:3000/v1/actions/hackernews.get_top_stories \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

로컬 런타임에서 제공업체 인증이 필요 없는 이 읽기 전용 Action을 실행하세요. 런타임 인증을 활성화했다면 Bearer 토큰을 추가하세요.

계정 연결

로컬 콘솔에서 제공업체를 선택하고 인증 정보를 설정하세요. OAuth 제공업체를 사용하려면 해당 서비스에 직접 OAuth 앱을 등록해야 합니다.

인증 정보 및 OAuth →

자격 증명 보존과 보호

Docker 이미지는 로컬 runtime 데이터를 /app/data에 저장합니다. 영구 볼륨을 연결하세요. OOMOL_CONNECT_ENCRYPTION_KEY로 저장된 자격 증명을 암호화하고 복구에 필요한 키를 보관하세요. 공개 배포 전에 배포 가이드를 확인하세요.

런타임을 외부에 공개하기 전에 관리자 인증, 런타임 토큰, 인증 정보 암호화, 공개 OAuth 오리진을 설정하세요. 프로덕션 설정은 배포 가이드를 따르세요.

전체 배포 가이드 ↗

외부 공개 전 준비

프로젝트 Compose 파일은 connector-data를 /app/data에 마운트합니다. 원격 접근을 허용하기 전에 OOMOL_CONNECT_ADMIN_TOKEN과 OOMOL_CONNECT_RUNTIME_TOKEN을 각각 설정하고 OOMOL_CONNECT_ENCRYPTION_KEY도 설정하세요. 공개 origin과 배포 진입점의 HTTPS를 구성하고 비밀 정보를 버전 관리에 포함하지 마세요.

업그레이드 및 복구 준비

배포 이미지 버전을 기록하고 런타임 데이터베이스를 백업하며 암호화 키 사본을 안전하게 보관하세요. 업그레이드 전에 격리된 환경에서 복원을 검증하세요. 키를 잃으면 암호화된 레코드를 복구할 수 없으며 데이터 볼륨을 삭제하면 로컬 데이터베이스가 사라집니다.

결과 읽기

HTTP 런타임 응답에는 success, message, data, meta가 포함됩니다. HTTP 상태만 보지 말고 success와 Action 출력 스키마를 확인하세요. 실행 메타데이터에 executionId가 있으면 해당 식별자로 민감 정보가 가려진 로그를 찾을 수 있습니다. 아래는 응답 구조 예시이며 실제 API 실행 결과가 아닙니다.

응답 구조 예시
{
  "success": true,
  "message": "OK",
  "data": {},
  "meta": {}
}

호출 실패 시 확인 사항

  • 인증 실패 시 엔드포인트와 자격 증명 유형을 확인하세요. 관리자 자격 증명은 /api를 보호하고 런타임 Bearer 토큰은 /v1과 /mcp에 사용됩니다. 공급자 API 키는 런타임 토큰을 대체하지 못합니다.
  • 권한 거부 시 Action의 필수 scopes, 런타임 Action 규칙과 연결 권한을 확인하세요. 유효한 토큰이라도 선택한 계정에 접근하지 못할 수 있습니다.
  • 결과가 비어 있거나 리소스가 없다면 연결 계정과 해당 리소스 접근 권한을 확인하세요. 인증 성공이 모든 워크스페이스, 채널, 문서의 접근을 보장하지는 않습니다.
  • 재시도 전에 오류와 실행 로그를 확인하세요. 공급자 데이터를 변경하는 Action은 이미 완료되었는지 확인하고 무조건 반복 요청하지 마세요.
Markdown으로 읽기