Node.js 없이 DeepSeek Harness를 Windows 단일 파일 설치 프로그램으로 패키징하기

프로젝트 소개

DeepSeek Harness Easy-Setup은 Windows용 패키징 프로젝트입니다. @deepseek-ai/dsh 명령줄 프로그램, 포터블 Node.js 런타임, 실행기와 종료기를 하나의 설치 프로그램으로 통합합니다.

최종 사용자는 Node.js, npm 또는 기타 종속성을 미리 설치할 필요가 없습니다. 설치 후 바탕 화면이나 시작 메뉴의 바로 가기를 통해 dsh web을 실행할 수 있으며, 서비스가 준비되면 브라우저가 자동으로 열립니다.

설치 후 기능

• 바탕 화면과 시작 메뉴에 각각 “DeepSeek Harness” 바로 가기를 만듭니다.
• 실행 중인 서비스를 종료하는 “DeepSeek Harness 종료” 바로 가기를 만듭니다.
• 실행기는 dsh web을 실행하고 서비스가 시작되면 브라우저를 자동으로 엽니다.
• 시작 메뉴에 제거 항목을 제공하며 Windows “앱” 목록에도 프로그램이 표시됩니다.
• dsh 프런트엔드에 포함된 고래 favicon을 애플리케이션 아이콘으로 사용합니다.
• 현재 사용자 기준으로 설치되므로 UAC 권한 상승을 요청하지 않습니다.

기본 설치 디렉터리는 다음과 같습니다.

%LOCALAPPDATA%\Programs\DeepSeekHarness

설치 마법사에서 다른 디렉터리를 선택할 수도 있습니다.

프로젝트 디렉터리 이해하기

빌드를 시작하기 전에 주요 디렉터리의 용도를 확인할 수 있습니다.

• build\build.ps1: 전체 빌드 진입점입니다. dsh 가져오기, 포터블 Node.js 다운로드, 아이콘 생성, 실행기와 종료기 컴파일 및 설치 패키지 생성을 담당합니다.
• build\fetch-nsis.ps1: 포터블 NSIS 3.11을 다운로드하며 SourceForge 미러를 사용할 수 없을 때 다른 미러를 시도합니다.
• src\Launcher.cs: 실행기 소스이며 컴파일 후 DeepSeekHarness.exe가 생성됩니다.
• src\Stopper.cs: 종료기 소스이며 컴파일 후 DeepSeekHarnessStop.exe가 생성됩니다.
• src\installer.nsi: NSIS 설치 스크립트입니다.
• src\icon\build-icon.js: dsh에 포함된 sharp를 사용해 고래 SVG를 여러 크기의 ICO로 변환합니다.
• test\test-install.ps1: 무인 설치, 파일 확인, 실행, 중지, HTTP 확인 및 제거 테스트를 수행합니다.
• work\: Node.js 압축 파일, NSIS 및 staging 등의 중간 파일을 저장합니다. 삭제해도 되지만 후속 빌드 속도를 높이기 위해 보관할 수 있습니다.
• out\: 최종 단일 파일 설치 프로그램을 저장합니다.

빌드 환경 준비

빌드 컴퓨터는 다음 조건을 충족해야 합니다.

• Windows 10 또는 Windows 11 x64.
• PowerShell 5.1.
• .NET Framework 4.x.
• Node.js가 설치되어 있고 node.exe를 PATH에서 찾을 수 있거나, 빌드 시 경로를 명시해야 합니다.
• nodejs.org 및 SourceForge에 접속할 수 있어야 합니다.

프로젝트는 시스템에 포함된 C# 컴파일러를 사용해 두 실행 파일을 컴파일합니다. 기본 경로는 다음과 같습니다.

C:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc.exe

시스템에 NSIS 3.x가 설치되어 있지 않으면 빌드 스크립트가 포터블 버전을 work\nsis에 자동으로 다운로드합니다.

중요: makensis의 명령줄 정의 매개 변수는 공백이 포함된 경로를 올바르게 처리하지 못하므로 프로젝트 경로에 공백을 포함하지 마세요.

1단계: dsh 설치

빌드 스크립트는 기본적으로 전역 npm 디렉터리에서 @deepseek-ai/dsh를 읽습니다. 먼저 빌드 컴퓨터에서 다음을 실행합니다.

npm i -g @deepseek-ai/dsh

기본 패키지 디렉터리는 다음과 같습니다.

%APPDATA%\npm\node_modules\@deepseek-ai\dsh

dsh가 다른 위치에 있으면 나중에 -DshSource 매개 변수로 지정할 수 있습니다.

2단계: 단일 파일 설치 프로그램 빌드

프로젝트 루트 디렉터리로 이동한 후 다음을 실행합니다.

powershell -ExecutionPolicy Bypass -File build\build.ps1

스크립트는 dsh 파일, 포터블 Node.js, 애플리케이션 아이콘, C# 실행기, 종료기 및 NSIS 설치 패키지를 순서대로 준비합니다. 기본 결과물은 다음과 같습니다.

out\DeepSeekHarness-Setup-0.1.1.exe

README에 따르면 예시 설치 패키지의 크기는 약 44 MB입니다.

자주 사용하는 빌드 매개 변수

• -DshSource <디렉터리>: dsh 패키지 디렉터리를 지정합니다.
• -NodeExe <경로>: 빌드 컴퓨터의 node.exe를 지정합니다.
• -AppVersion <버전>: 설치 패키지 버전 번호를 덮어씁니다.
• -WorkDir <디렉터리>: 중간 파일 디렉터리를 변경합니다.
• -OutDir <디렉터리>: 설치 패키지 출력 디렉터리를 변경합니다.

사용자 지정 dsh 경로, Node.js 경로 및 버전 번호를 사용하는 예시는 다음과 같습니다.

powershell -ExecutionPolicy Bypass -File build\build.ps1 -DshSource C:\dev\dsh -NodeExe C:\nodejs\node.exe -AppVersion 0.1.1 -OutDir C:\dsh-output

기본적으로 버전 번호는 dsh의 package.json에서 가져옵니다. 시험판 버전은 기본 버전으로 변환됩니다. 예를 들어 0.1.1-rc.2는 0.1.1을 생성합니다.

work\의 파일은 보존되고 재사용됩니다. Node.js 압축 파일은 다운로드가 완료된 후 다시 다운로드되지 않으며, 압축을 푼 NSIS 디렉터리도 계속 사용됩니다.

3단계: 설치 및 기본 사용

빌드가 완료되면 out\ 디렉터리의 설치 프로그램을 두 번 클릭하고 마법사의 안내에 따라 설치합니다. 현재 사용자 설치 모드를 사용하므로 기본적으로 UAC 권한 상승 메시지가 표시되지 않습니다.

1. 바탕 화면이나 시작 메뉴의 “DeepSeek Harness”를 두 번 클릭합니다.
2. 실행기가 dsh web을 실행합니다.
3. 서비스를 사용할 수 있게 되면 기본 브라우저가 해당 페이지를 자동으로 엽니다.
4. 서비스를 중지하려면 “DeepSeek Harness 종료”를 실행합니다.
5. 프로그램을 제거하려면 시작 메뉴의 제거 항목이나 Windows “앱” 목록에서 제거를 실행합니다.

무인 모드를 사용해 기본 디렉터리에 설치할 수도 있습니다.

out\DeepSeekHarness-Setup-0.1.1.exe /S

4단계: 자동화된 테스트 실행

프로젝트는 전체 설치 과정을 테스트하는 스크립트를 제공합니다.

powershell -ExecutionPolicy Bypass -File test\test-install.ps1

테스트 스크립트는 다음 작업을 수행합니다.

1. 프로젝트 아래의 testinstall\에 무인 설치합니다.
2. 설치 파일과 바로 가기를 하나씩 확인합니다.
3. 모의 진입점을 사용해 실행기와 종료기의 동작을 검증합니다.
4. 설치 디렉터리의 포터블 Node.js를 사용해 dsh web을 실제로 한 번 실행합니다.
5. 기본 테스트 포트 3999를 통해 HTTP 200 응답을 확인하여 일반적으로 사용되는 3080 포트의 점유를 피합니다.
6. 제거를 실행하고 결과를 확인합니다.

출력에는 ###로 시작하는 확인 정보가 여러 줄 표시됩니다. 마지막 줄은 다음과 같아야 합니다.

ALL CHECKS PASSED

테스트가 실패하면 마지막에 실패한 항목 수가 표시됩니다.

참고: 테스트에서 생성되는 바로 가기의 이름은 정식 설치와 완전히 동일합니다. 따라서 테스트를 실행하는 동안 현재 사용자의 바탕 화면과 시작 메뉴의 바로 가기는 일시적으로 testinstall\을 가리키며 제거 단계에서 삭제됩니다. 테스트가 완료된 후 정식 설치를 복원하려면 설치 프로그램의 무인 설치 명령을 다시 실행하세요.

실행 로그 및 문제 해결

실행 중 주요 상태 파일은 다음 위치에 저장됩니다.

%LOCALAPPDATA%\DeepSeekHarness\pid.txt
%LOCALAPPDATA%\DeepSeekHarness\run.log

• pid.txt에는 실행 중인 dsh 프로세스 ID가 저장되며, 종료기는 이를 사용해 대상 프로세스를 찾습니다.
• run.log에는 dsh의 표준 출력과 표준 오류가 저장됩니다.

시작에 실패하면 실행기가 팝업으로 run.log의 위치를 알립니다. 문제를 해결할 때는 먼저 해당 로그를 확인하여 포트 점유, 종속성 로드 또는 서비스 시작 오류를 확인해야 합니다.

고급 팁 및 구현 시 주의 사항

Node.js 버전과 네이티브 모듈의 호환성 확인

dsh의 종속성에는 node-pty, sharp 및 koffi 등의 네이티브 모듈이 포함되어 있습니다. 포터블 Node.js는 이러한 모듈과 호환되어야 하므로 빌드 스크립트는 기본적으로 빌드 컴퓨터와 동일한 Node.js 버전을 선택합니다. -NodeExe를 변경할 때는 설치 패키지가 정상적으로 시작되는지 다시 확인해야 합니다.

서비스 중복 실행 방지

기본 3080 포트에서 dsh가 이미 실행 중일 때 실행기를 다시 두 번 클릭해도 두 번째 인스턴스가 생성되지 않습니다. 실행기는 pid 파일의 프로세스가 아직 실행 중인지 확인한 후 기존 서비스 페이지를 바로 엽니다.

실행기가 너무 일찍 종료되지 않도록 하기

실행기는 dsh를 시작한 후에도 호스트 프로세스로 백그라운드에 계속 남아 dsh가 종료될 때까지 표준 출력과 표준 오류를 run.log에 계속 기록합니다. 실행기가 즉시 종료되면 출력 파이프가 끊어져 dsh가 이후 로그를 기록할 때 EPIPE가 발생할 수 있습니다.

NSIS 제거 완료를 올바르게 기다리기

NSIS 제거 프로그램은 먼저 자신을 %TEMP%에 복사한 다음 임시 디렉터리에서 계속 실행하며, 원래 제거 프로세스는 곧 종료됩니다. 따라서 자동화 스크립트는 원래 프로세스의 종료만 기다려서는 안 되고 설치 디렉터리가 사라졌는지 폴링해야 합니다. 프로젝트의 test-install.ps1에 해당 구현이 이미 포함되어 있습니다.

설치 스크립트 인코딩에 주의하기

installer.nsi는 UTF-8 BOM 또는 UTF-16LE를 사용해야 합니다. 그렇지 않으면 NSIS가 Bad text encoding을 보고합니다. 저장소의 원본 파일은 BOM이 없는 UTF-8이며, build.ps1은 makensis를 호출하기 전에 이를 UTF-16LE로 변환합니다.

설치 패키지 크기 관리

패키징 과정에서는 Windows x64 환경에서 로드되지 않는 파일을 제거합니다. 여기에는 node-pty의 Darwin, Linux, ARM64 사전 컴파일 파일과 sharp의 WASM 버전이 포함됩니다. README에 따르면 이 처리로 약 30 MB를 절약할 수 있습니다.

라이선스 안내

dsh 본체는 MIT 라이선스를 사용하며 자세한 내용은 dsh 패키지의 LICENSE에서 확인할 수 있습니다. 이 프로젝트의 설치 패키지 스크립트도 MIT 라이선스로 배포됩니다. 고래 아이콘은 dsh 프런트엔드 리소스에서 가져왔으며 저작권은 DeepSeek에 있습니다.

요약

DeepSeek Harness Easy-Setup은 dsh, 포터블 Node.js, Windows 시작 및 중지 프로그램, NSIS 설치 과정을 하나로 통합합니다. 환경을 준비한 후 dsh를 전역으로 설치하고 build\build.ps1을 실행하기만 하면 대상 컴퓨터에 Node.js를 미리 설치하지 않아도 되는 단일 파일 설치 프로그램을 생성할 수 있습니다. 배포 전에 전체 테스트 스크립트를 실행하고 로그, Node.js 버전 호환성 및 바로 가기 복원 상태를 중점적으로 확인하는 것이 좋습니다.