Linux에서 DeepSeek Harness 데스크톱 버전 설치, 실행 및 빌드

프로젝트 소개

DeepSeek Harness Linux는 공식 DeepSeek Harness의 다운스트림 fork로, Linux 사용자에게 바로 다운로드하고 설치 및 업데이트할 수 있는 데스크톱 버전을 제공하는 것을 목표로 합니다. 업스트림 데스크톱의 agent, skill, 네트워크 기능, 프런트엔드, 플러그인 시스템 및 통신 프로토콜을 유지하면서 Linux 패키징, 테스트 및 배포 지원만 추가합니다.

주의: 이 프로젝트는 DeepSeek 공식 배포판이 아니며 agent 코어를 수정하지 않았습니다. 업스트림은 여전히 developer preview 단계이므로 잦은 업데이트나 호환성을 깨뜨리는 변경이 발생할 수 있습니다.

프로젝트는 x64와 arm64를 모두 지원합니다. x64는 일반적인 AMD 및 Intel 컴퓨터에 적합하고, arm64는 Raspberry Pi 5, ARM 서버 및 Apple Silicon 기기에서 실행되는 Linux에 적합합니다.

주요 기능

• 세 가지 배포 형식: AppImage, .deb 및 .tar.gz를 제공합니다.
• 이중 아키텍처 지원: x64와 arm64 버전을 모두 빌드합니다.
• AppImage 자동 업데이트: electron-updater와 nightly-linux.yml 업데이트 채널을 통해 작동합니다.
• 네이티브 CI: ubuntu-24.04와 ubuntu-24.04-arm runner를 각각 사용해 해당 아키텍처를 빌드합니다.
• 업스트림 동기화: agent 코어와 주요 데스크톱 기능을 공식 프로젝트와 동기화합니다.
• MIT 라이선스: 업스트림 코드와 새로 추가된 Linux 패키징 계층 모두 MIT 라이선스로 배포됩니다.

적합한 설치 패키지 선택

AppImage: 대부분의 사용자를 위한 권장 방식

AppImage는 기존 설치가 필요 없는 단일 파일 프로그램이며, 프로젝트에서 제공하는 자동 업데이트 채널을 지원합니다. 빠르게 사용해 보거나 시스템 패키지 관리 상태를 변경하고 싶지 않은 사용자에게 적합합니다.

DEB: Debian 및 Ubuntu에 적합

.deb 파일은 Debian 시스템의 패키지 관리 도구로 설치할 수 있으며, 애플리케이션 메뉴나 터미널에서 실행할 수 있습니다. 애플리케이션을 시스템 데스크톱 환경에 통합하고 싶은 사용자에게 적합합니다.

tar.gz: 포터블 실행

.tar.gz는 압축을 푼 후 바로 실행할 수 있어 설치가 필요하지 않습니다. 포터블 디렉터리, 테스트 환경 또는 시스템 소프트웨어 패키지를 설치할 수 없는 상황에 적합합니다.

설치 전 아키텍처 확인

먼저 터미널에서 현재 시스템 아키텍처를 확인합니다.

uname -m

• 출력이 x86_64이면 파일 이름에 linux-x64가 포함된 버전을 다운로드합니다.
• 출력이 aarch64 또는 arm64이면 파일 이름에 linux-arm64가 포함된 버전을 다운로드합니다.

설치 패키지는 프로젝트의 Releases 페이지에서 받을 수 있습니다. 커뮤니티 빌드는 해당 저장소의 Release에서만 다운로드하십시오.

방법 1: AppImage 실행

AppImage는 README에서 권장하는 설치 방식입니다. FUSE 2에 의존하므로 먼저 배포판에 맞는 런타임을 설치해야 합니다.

Debian 또는 Ubuntu 사용자는 다음을 실행합니다.

sudo apt install libfuse2

Fedora 또는 RHEL 계열 사용자는 다음을 실행합니다.

sudo dnf install fuse2

아키텍처에 맞는 AppImage를 다운로드한 후 파일에 실행 권한을 추가합니다. 다음은 x64 파일을 사용하는 예입니다.

chmod +x deepseek-harness-*-linux-x64.AppImage
./deepseek-harness-*-linux-x64.AppImage

arm64 사용자는 명령의 linux-x64를 linux-arm64로 바꾸거나 실제로 다운로드한 파일 이름을 직접 사용해야 합니다.

방법 2: DEB 패키지 설치

Debian, Ubuntu 및 파생 배포판에서는 dpkg를 사용해 다운로드한 패키지를 설치할 수 있습니다.

sudo dpkg -i deepseek-harness-*-linux-x64.deb

설치가 완료되면 데스크톱 애플리케이션 메뉴에서 실행하거나 터미널에서 다음을 실행할 수 있습니다.

deepseek-harness

arm64 시스템에서는 파일 이름에 linux-arm64가 포함된 DEB 패키지를 설치해야 합니다.

방법 3: 포터블 압축 패키지 실행

시스템 소프트웨어 패키지를 설치하지 않으려면 .tar.gz를 압축 해제한 후 디렉터리의 실행 파일을 직접 실행할 수 있습니다.

tar -xzf deepseek-harness-*-linux-x64.tar.gz
cd deepseek-harness-*-linux-x64
./deepseek-harness

arm64 사용자는 동일하게 해당 아키텍처의 파일을 선택해 압축을 해제해야 합니다.

기본 사용법

프로그램이 시작되면 agent, skill, 네트워크 기능 및 데스크톱 프런트엔드를 포함해 업스트림에서 상속된 데스크톱 기능을 사용할 수 있습니다. 이 Linux fork는 agent 코어, 플러그인 시스템 또는 통신 프로토콜을 변경하지 않았으므로 관련 동작은 공식 DeepSeek Harness의 구현을 따릅니다.

AppImage를 사용하는 경우 다운로드한 단일 파일을 보관하고 반복해서 직접 실행할 수 있습니다. DEB 패키지를 설치한 경우 deepseek-harness 명령이나 애플리케이션 메뉴에서 실행할 수 있으며, 포터블 버전은 압축 해제한 디렉터리에서 ./deepseek-harness를 실행해야 합니다.

원격 데스크톱 또는 디스플레이가 없는 환경에서 실행

이 프로그램은 데스크톱 애플리케이션입니다. 원격 서버에서 VNC와 함께 사용할 때는 DISPLAY가 올바르게 설정되어 있는지 확인해야 합니다. 예를 들어 xfce4와 TigerVNC 환경에서는 디스플레이 번호가 :1일 수 있습니다.

export DISPLAY=:1
./deepseek-harness

디스플레이 환경을 사용할 수 있으면 데스크톱 프로그램이 자동으로 실행됩니다. 실제 디스플레이 번호는 현재 VNC 또는 그래픽 세션 설정을 기준으로 해야 합니다.

소스에서 빌드

종속성 준비

소스 빌드에는 Node.js 24 이상, pnpm 및 빌드 호스트의 libfuse2가 필요합니다. 이 중 libfuse2는 AppImage를 패키징하는 데 사용됩니다.

복제 및 종속성 설치

git clone https://github.com/Zhou-Yujing114514/deepseek-harness-linux.git
cd deepseek-harness-linux
pnpm install

Linux 환경 파일 준비

프로젝트에서 제공하는 예시 파일을 복사하고 필요에 따라 릴리스 설정을 입력합니다.

cp apps/desktop/.env.linux.example apps/desktop/.env.linux

대상 아키텍처 빌드

x64 설치 패키지를 빌드합니다.

pnpm --dir apps/desktop run package:linux:x64

arm64 설치 패키지를 빌드합니다.

pnpm --dir apps/desktop run package:linux:arm64

각 아키텍처에 대해 AppImage, DEB 및 tar.gz의 세 가지 형식이 생성됩니다. 프로젝트의 Desktop (Linux) 워크플로도 필요에 따라 네이티브 runner에서 빌드하며, 결과물은 GitHub Actions Artifacts 또는 자동 생성된 Release에서 받을 수 있습니다.

자동 업데이트 및 보안 검증

AppImage는 electron-updater를 통해 AppImage 업데이트 채널을 사용하며, 업데이트 설명자는 nightly-linux.yml이고 전송에는 HTTPS가 사용됩니다.

중요: 현재 Linux 빌드에는 코드 서명이 없습니다. 자동 업데이트는 HTTPS 전송과 feed 메타데이터 검증에만 의존하며 코드 서명 검증은 포함하지 않으므로 높은 신뢰도가 필요한 환경에서 직접 사용하기에는 적합하지 않습니다.

다운로드 또는 업데이트 후에는 파일의 SHA256을 Release 페이지에서 제공하는 체크섬과 비교해야 합니다. 다음 명령으로 요약값을 계산할 수 있습니다.

sha256sum deepseek-harness-*-linux-x64.AppImage

출력이 Release에 게시된 값과 완전히 일치하는지 확인하십시오. DEB, tar.gz 및 arm64 파일도 같은 방식으로 검증할 수 있습니다.

알려진 제한 사항

1. 빌드에 서명되지 않음: Linux 바이너리에는 코드 서명이 없으며 시스템 수준의 공증도 없습니다.
2. Office 문서 변환을 현재 사용할 수 없음: DOCX, XLSX, PPTX를 PDF로 변환하려면 LibreOffice Kit의 Linux 네이티브 바인딩이 필요하지만, 현재 버전에는 설치 패키지로 배포되지 않습니다.
3. 업스트림이 여전히 미리 보기 단계: 공식 프로젝트는 developer preview 단계이므로 잦거나 호환성을 깨뜨리는 변경이 발생할 수 있습니다.
4. 애플리케이션 스토어 버전 없음: 이 프로젝트는 애플리케이션 스토어 배포 절차를 거치지 않습니다.

Office 변환 제한은 README에 명시된 다른 데스크톱 기능인 agent, skill, 네트워크 기능 및 프런트엔드에는 영향을 주지 않습니다.

고급 권장 사항

• 아키텍처를 우선 일치: x64 시스템에서 arm64 패키지를 다운로드하거나 그 반대로 하지 마십시오.
• 업데이트 기능이 필요하면 AppImage 선택: DEB와 tar.gz의 README에는 AppImage 업데이트 채널 사용이 명시되어 있지 않습니다.
• 검증 절차 유지: 최초 다운로드와 업데이트 모두 Release의 SHA256을 확인해야 합니다.
• 업스트림 변경 사항 확인: 이 fork는 업스트림 커밋을 지속적으로 rebase하므로 업그레이드 전에 Release 설명을 확인해야 합니다.
• 개발자는 네이티브 CI 활용: 두 아키텍처를 동시에 검증해야 할 때는 교차 빌드 결과가 네이티브 빌드와 같다고 가정하지 말고 프로젝트의 기존 Desktop (Linux) 워크플로를 사용하십시오.

실행하기 전에 업스트림의 SAFETY.md도 읽어야 합니다. 공식 업스트림 프로젝트는 deepseek-ai/deepseek-harness에 있습니다.

요약

DeepSeek Harness Linux는 공식 데스크톱 버전에 x64 및 arm64 Linux 배포 기능을 추가합니다. 일반 사용자는 자동 업데이트를 지원하는 AppImage를 우선 선택할 수 있으며, Debian 또는 Ubuntu 사용자는 DEB를 설치할 수도 있습니다. 포터블 실행이 필요하다면 tar.gz를 선택하면 됩니다. 현재 빌드에는 서명이 없으므로 다운로드, 업데이트 및 배포 시 반드시 SHA256을 확인하고 developer preview 단계에서 발생할 수 있는 호환성 변경에 유의해야 합니다.