Platypus

Linux 시스템 플릿을 위한 호스트 관리 허브입니다. 소유한 모든 호스트에 Platypus 에이전트를 설치하세요. 에이전트는 TLS + protobuf를 통해 Platypus 서버로 다시 연결됩니다. 서버에서 모든 관리 호스트에 대한 대화형 셸, 파일 관리, 네트워크 터널링을 하나의 중앙 제어판을 통해 얻을 수 있습니다.

스크린샷

Vercel 스타일의 플랫 네비게이션 UI로 프로젝트 대시보드, 호스트/리스너/세션 브라우저, 멀티 호스트 디스패치 콘솔, 관리 사용자 관리자를 제공합니다. 전체 갤러리는 docs/screenshots/에서 확인하세요. make screenshots를 다시 실행하여 라이브 앱에서 스크린샷을 재생성할 수 있습니다.

아키텍처

Platypus는 두 개의 백엔드 바이너리와 독립 실행형 데스크톱 클라이언트로 제공됩니다:

서버는 순수 API입니다 — 내장 웹 UI가 없습니다. 여러 데스크톱이 동시에 동일한 서버에 연결할 수 있습니다.

기능

• 에이전트와 서버 간 TLS + protobuf 채널
• 여러 인그레스 포트를 통해 서로 다른 네트워크의 플릿이 하나의 허브를 공유
• 호스트당 대화형 셸, WebSocket으로 스트리밍
• 청크 전송을 통한 파일 읽기/쓰기/업로드/다운로드
• 네트워크 터널: 로컬 포트 포워드, 원격 포트 포워드, 동적 SOCKS5
• Bearer 토큰 인증 REST API
• Python SDK
• config.yml에서 자동 시작 리스너
• 정상 종료 (SIGINT/SIGTERM 수신 시 30초 내 연결 드레인)

문서

• Chinese | 中文文档

빠른 시작

원클릭 배포 (권장)

전체 Platypus 시스템(서버, 웹 UI, MinIO 기반 에이전트 배포기 포함)을 가장 빠르게 실행하는 방법은 Docker Compose를 사용하는 것입니다:

git clone https://github.com/WangYihang/Platypus
cd Platypus
docker-compose up -d

• 웹 UI: 브라우저에서 https://localhost:9443을 엽니다. (컨테이너에는 자체 서명 인증서가 포함되어 있으며, 처음 방문 시 브라우저에서 이를 수락하라는 메시지가 표시됩니다.)
• 로그인: bootstrap_secret은 첫 부팅 시 컨테이너 내 /app/data/bootstrap.secret에 기록됩니다 (모드 0600). docker compose exec platypus-server cat /app/data/bootstrap.secret로 읽고, 이를 한 번 사용하여 첫 번째 관리자를 생성한 후 파일을 삭제하세요. 부트스트랩이 완료되면 시크릿은 더 이상 허용되지 않습니다.
• 에이전트 추가: UI에서 "Add Agent"를 클릭하여 프로젝트 CA에 서명되고 고정된 한 줄 curl ... | sh 명령을 받아 플릿에 에이전트를 배포할 수 있습니다.

소스에서 빌드

Go 1.24+ 및 protoc 필요 (protobuf 코드를 재생성하는 경우에만).

git clone https://github.com/WangYihang/Platypus
cd Platypus
make build              # → ./build/{platypus-server,platypus-agent}

기타 유용한 대상: make test, make lint, make snapshot (goreleaser를 통한 크로스 플랫폼), make help.

개발 (pre-commit 훅)

기여자는 각 커밋 전에 gofmt / goimports / go vet / golangci-lint가 실행되도록 git 훅을 설치해야 합니다:

pip install pre-commit   # 또는: pipx install pre-commit
make hooks               # 일회성: .git/hooks/pre-commit 연결
make pre-commit          # 선택 사항: 지금 모든 파일에 대해 모든 훅 실행

데스크톱 앱 빌드

Node 22+, Wails CLI 의존성 (wails doctor), 플랫폼의 WebView 라이브러리 필요 (Linux: webkit2gtk-4.1, Windows: WebView2, macOS: WKWebView).

make desktop-deps       # 일회성: Wails CLI + pnpm 패키지 설치
make desktop-build      # → desktop/build/bin/platypus-desktop
make desktop-dev        # 핫 리로드 개발 모드

또는: 독립 실행형 웹 UI 사용 (설치 불필요)

동일한 페이지, 동일한 기능 (실시간 이벤트 푸시 제외), 모든 브라우저에서 실행:

make web-ui             # → desktop/frontend/dist-web/ (정적 번들)
make web-ui-serve       # http://localhost:8080에서 미리보기

dist-web/는 완전히 정적입니다. GitHub Pages / S3 / nginx에 배포하세요. 로그인 양식을 통해 모든 platypus-server를 가리키도록 설정하세요.

전체 노트는 desktop/README.md를 참조하세요.

릴리스 바이너리에서 설치

Releases 페이지에서 OS/아키텍처에 맞는 아카이브를 다운로드하고 압축을 풀어 실행하세요.

Docker로 실행

docker build -t platypus-server .
docker run --rm -p 9443:9443 \
  -e PLATYPUS_DEV=1 \
  -v $(pwd)/config.yml:/config.yml \
  platypus-server

PLATYPUS_DEV=1은 디스크 기반 KEK 폴백을 활성화하여 새 시작이 "그냥 작동"하도록 합니다. 프로덕션의 경우 해당 환경 변수를 제거하고 PLATYPUS_CA_KEK (32바이트 16진수; openssl rand -hex 32)를 설정하여 CA 개인 키 암호화 키가 암호화된 데이터베이스 옆에 기록되지 않도록 하세요.

실행

./build/platypus-server                # 포그라운드; Ctrl-C로 정상 종료

프로덕션의 경우 서버를 수동으로 백그라운드로 실행하는 대신 systemd 아래에서 실행하세요.

프로덕션 주의사항

• 단일 인스턴스만. 불투명 토큰 검증기는 검증된 토큰을 프로세스별 LRU에 캐시합니다. 철회(로그아웃, 비밀번호 변경, AAT 철회, 사용자 삭제)는 동일한 프로세스에서 동기적으로 항목을 제거합니다. 그러나 멀티 레플리카 배포의 경우 현재 교차 프로세스 무효화 채널이 없으므로 철회된 토큰이 캐시 TTL(30초) 동안 다른 레플리카에서 계속 작동할 수 있습니다. 교차 프로세스 철회가 구현될 때까지 동일한 DB에 대해 둘 이상의 platypus-server를 실행하지 마세요. 수직 확장 + HA 대기가 지원되는 구성입니다. 수평 로드 밸런싱 레플리카는 지원되지 않습니다.
• 환경 변수 내 PLATYPUS_CA_KEK. CA 개인 키는 이 32바이트 16진수 값으로 AES-256-GCM을 사용하여 봉인됩니다. 이 값이 설정되지 않으면 PLATYPUS_DEV=1도 존재하지 않는 한 서버가 시작을 거부합니다 (이는 개발 전용 디스크 기반 폴백을 <data-dir>/ca.kek에 활성화합니다 — 암호문과 키가 동일한 볼륨에 있으므로 프로덕션에 안전하지 않습니다).
• 데스크톱급 뷰포트, 모바일 레이아웃 없음 (현재). 웹 UI는 ≥ 1280px 뷰포트를 대상으로 합니다. 레일/사이드바/상태 표시줄 크롬이 약 300px를 차지하므로 콘텐츠 본문은 80–100자 읽기 적정 영역에 남습니다. 현재 좁은 창에 대한 반응형 축소가 없습니다 — 1024px 미만 뷰포트는 테이블에 가로 스크롤러를 표시합니다. 태블릿/휴대폰 지원은 백로그에 있습니다 (UX 감사에서 P4) 그러나 차단되지는 않습니다. 관리 작업은 데스크 작업입니다.
• 객체 스토어 자격 증명. 배포기가 활성화된 경우 (distributor.store.endpoint 설정됨), config.yml에 포함하는 대신 PLATYPUS_DISTRIBUTOR_STORE_ACCESS_KEY_ID 및 PLATYPUS_DISTRIBUTOR_STORE_SECRET_ACCESS_KEY를 설정하세요. 번들된 config.docker.yml은 해당 이유로 YAML 필드가 비어 있습니다.

사용법

토폴로지

• 서버: 192.168.88.129
  • 통합 TLS 인그레스 (REST API + 에이전트 링크 + 설치 관리자): 0.0.0.0:9443
• 관리 호스트: 192.168.88.130 (platypus-agent 실행)

빠른 둘러보기

먼저 ./platypus-server를 실행하세요. config.yml이 없으면 assets/config.example.yml에서 생성됩니다. 기본값은 적절합니다.

새 관리 호스트를 등록하려면:

1. 웹 UI / 데스크톱 앱을 열고 프로젝트로 이동한 후 Add Agent를 클릭하세요.
2. 대상 OS/아키텍처 및 TTL을 선택하고 Generate를 클릭하세요.
3. UI에 표시된 한 줄 명령을 복사하여 관리 호스트에서 실행하세요.

서버에서 렌더링된 한 줄 명령은 다음과 같습니다:

curl -fsSL https://<server>:9443/api/v1/install/<one-shot-token> | sh

일회용 설치 토큰은 발행 후 곧 만료되며 첫 번째 성공적인 히트에서 소진됩니다. 서버가 반환하는 스크립트는:

• 프로젝트 CA를 포함하여 에이전트 바이너리 다운로드가 curl --cacert로 검증되도록 합니다 (-k 또는 TOFU 없음).
• 일회용 PAT를 주입하여 에이전트가 등록을 완료하고 mTLS 클라이언트 인증서를 얻을 수 있도록 합니다.
• 서버에 프로젝트 CA가 구성되지 않은 경우 실행을 거부합니다 (운영자가 명시적으로 PLATYPUS_INSECURE_DOWNLOAD=1을 설정하지 않는 한).

수동으로 curl http://... URL을 레거시 /agent/<host>:<port> 경로에 대해 작성하지 마세요 — 해당 흐름은 제거되었습니다. 항상 UI를 통해 설치 명령을 렌더링하여 신뢰 앵커를 전달하세요.

데스크톱 / 웹

데스크톱 앱 (platypus-desktop) 또는 웹 UI (make web-ui-serve)를 열고 서버 URL과 시크릿을 입력하면 바로 사용할 수 있습니다. 탭: 세션 (들어온 모든 에이전트), 터미널, 파일, 터널, 리스너.

고급 사용법

• REST API
• Python SDK

기타 자료

• KCon 2019 발표 자료
• GCSIS 2021 발표 자료

기여자

이 프로젝트는 기여해 주신 모든 분들 덕분에 존재합니다.

후원자

모든 후원자님께 감사드립니다! 🙏 [후원자가 되기]

스폰서

스폰서가 되어 이 프로젝트를 지원해 주세요. 귀하의 로고가 여기에 귀하의 웹사이트 링크와 함께 표시됩니다. [스폰서가 되기]