Cài đặt, chạy và xây dựng bản desktop DeepSeek Harness trên Linux

Giới thiệu dự án

DeepSeek Harness Linux là một fork downstream của DeepSeek Harness chính thức, nhằm cung cấp cho người dùng Linux phiên bản desktop có thể tải xuống, cài đặt và cập nhật trực tiếp. Dự án giữ lại agent, skill, khả năng kết nối mạng, frontend, hệ thống plugin và giao thức giao tiếp của bản desktop upstream, chỉ bổ sung hỗ trợ đóng gói, kiểm thử và phân phối trên Linux.

Lưu ý: Dự án này không phải là bản phân phối chính thức của DeepSeek và không chỉnh sửa nhân agent. Bản upstream vẫn đang ở giai đoạn developer preview, nên có thể thường xuyên cập nhật hoặc xuất hiện các thay đổi gây ảnh hưởng.

Dự án hỗ trợ cả x64 và arm64. Kiến trúc đầu tiên phù hợp với các máy tính AMD và Intel phổ biến, còn kiến trúc thứ hai phù hợp với Raspberry Pi 5, máy chủ ARM và Linux chạy trên thiết bị Apple Silicon.

Tính năng chính

• Ba định dạng phát hành: Cung cấp AppImage, .deb và .tar.gz.
• Hỗ trợ hai kiến trúc: Đồng thời xây dựng phiên bản x64 và arm64.
• Tự động cập nhật AppImage: Hoạt động thông qua electron-updater và kênh cập nhật nightly-linux.yml.
• CI nguyên bản: Sử dụng lần lượt runner ubuntu-24.04 và ubuntu-24.04-arm để xây dựng từng kiến trúc tương ứng.
• Theo sát upstream: Nhân agent và các khả năng desktop chính được đồng bộ với dự án chính thức.
• Giấy phép MIT: Mã nguồn upstream và lớp đóng gói Linux bổ sung đều được phân phối theo giấy phép MIT.

Chọn gói cài đặt phù hợp

AppImage: lựa chọn ưu tiên của hầu hết người dùng

AppImage là chương trình dạng một tệp, không cần cài đặt theo cách truyền thống và hỗ trợ kênh cập nhật tự động do dự án cung cấp. Định dạng này phù hợp với người muốn trải nghiệm nhanh hoặc tránh thay đổi trạng thái của trình quản lý gói hệ thống.

DEB: phù hợp với Debian và Ubuntu

Tệp .deb có thể được cài đặt bằng công cụ quản lý gói của hệ thống Debian và khởi chạy từ menu ứng dụng hoặc terminal. Định dạng này phù hợp với người muốn tích hợp ứng dụng vào môi trường desktop của hệ thống.

tar.gz: chạy di động

Giải nén .tar.gz là có thể chạy ngay, không cần cài đặt. Định dạng này phù hợp với thư mục di động, môi trường kiểm thử hoặc các trường hợp không thể cài gói phần mềm hệ thống.

Kiểm tra kiến trúc trước khi cài đặt

Trước tiên, xem kiến trúc hệ thống hiện tại trong terminal:

uname -m

• Nếu kết quả là x86_64, hãy tải phiên bản có linux-x64 trong tên tệp.
• Nếu kết quả là aarch64 hoặc arm64, hãy tải phiên bản có linux-arm64 trong tên tệp.

Có thể tải các gói cài đặt từ trang Releases của dự án. Chỉ tải các bản build cộng đồng từ Release của kho lưu trữ này.

Cách một: chạy AppImage

AppImage là phương thức cài đặt được README khuyến nghị. AppImage phụ thuộc vào FUSE 2, vì vậy trước tiên cần cài runtime tương ứng với bản phân phối.

Người dùng Debian hoặc Ubuntu chạy:

sudo apt install libfuse2

Người dùng Fedora hoặc RHEL chạy:

sudo dnf install fuse2

Sau khi tải AppImage phù hợp với kiến trúc, cấp quyền thực thi cho tệp. Ví dụ dưới đây dùng tệp x64:

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

Người dùng arm64 cần thay linux-x64 trong lệnh bằng linux-arm64, hoặc sử dụng trực tiếp tên tệp đã tải.

Cách hai: cài gói DEB

Trên Debian, Ubuntu và các bản phân phối phái sinh, có thể dùng dpkg để cài gói đã tải xuống:

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

Sau khi cài đặt, có thể khởi chạy từ menu ứng dụng desktop hoặc chạy trong terminal:

deepseek-harness

Trên hệ thống arm64, hãy cài gói DEB có linux-arm64 trong tên tệp.

Cách ba: chạy gói nén di động

Nếu không muốn cài gói phần mềm hệ thống, hãy giải nén .tar.gz rồi chạy trực tiếp tệp khởi động trong thư mục:

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

Người dùng arm64 cũng cần chọn và giải nén tệp đúng kiến trúc.

Sử dụng cơ bản

Sau khi chương trình khởi động, bạn có thể sử dụng các khả năng desktop kế thừa từ upstream, bao gồm agent, skill, chức năng kết nối mạng và frontend. Fork Linux này không thay đổi nhân agent, hệ thống plugin hay giao thức giao tiếp, vì vậy hành vi liên quan sẽ tuân theo cách triển khai của DeepSeek Harness chính thức.

Nếu dùng AppImage, có thể giữ lại tệp đơn đã tải và chạy lại trực tiếp; nếu đã cài gói DEB, có thể khởi chạy bằng lệnh deepseek-harness hoặc từ menu ứng dụng; với bản di động, hãy chạy ./deepseek-harness trong thư mục đã giải nén.

Chạy trên desktop từ xa hoặc môi trường không có màn hình

Đây là ứng dụng desktop. Khi sử dụng VNC trên máy chủ từ xa, cần đảm bảo DISPLAY được thiết lập chính xác. Ví dụ, trong môi trường xfce4 và TigerVNC, số màn hình có thể là :1:

export DISPLAY=:1
./deepseek-harness

Khi môi trường hiển thị khả dụng, chương trình desktop sẽ tự động khởi chạy. Số màn hình thực tế phụ thuộc vào cấu hình VNC hoặc phiên đồ họa hiện tại.

Xây dựng từ mã nguồn

Chuẩn bị phụ thuộc

Việc xây dựng từ mã nguồn cần Node.js 24 trở lên, pnpm và libfuse2 trên máy chủ build. libfuse2 được dùng để tạo AppImage.

Sao chép kho lưu trữ và cài đặt phụ thuộc

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

Chuẩn bị tệp môi trường Linux

Sao chép tệp mẫu do dự án cung cấp và điền các thiết lập phát hành nếu cần:

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

Xây dựng theo kiến trúc mục tiêu

Xây dựng gói cài đặt x64:

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

Xây dựng gói cài đặt arm64:

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

Mỗi kiến trúc sẽ tạo ra ba định dạng AppImage, DEB và tar.gz. Workflow Desktop (Linux) của dự án cũng xây dựng theo nhu cầu trên runner nguyên bản; sản phẩm có thể được tải từ GitHub Actions Artifacts hoặc Release được tạo tự động.

Cập nhật tự động và kiểm tra bảo mật

AppImage sử dụng kênh cập nhật AppImage thông qua electron-updater, với mô tả cập nhật là nightly-linux.yml; quá trình truyền tải sử dụng HTTPS.

Quan trọng: Bản build Linux hiện tại chưa được ký mã. Cập nhật tự động chỉ dựa vào truyền tải HTTPS và kiểm tra metadata của feed, không bao gồm xác minh chữ ký mã, nên không phù hợp để sử dụng trực tiếp trong các môi trường yêu cầu mức độ tin cậy cao.

Sau khi tải xuống hoặc cập nhật, nên đối chiếu SHA256 của tệp với checksum được cung cấp trên trang Release. Có thể dùng lệnh sau để tính giá trị băm:

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

Hãy đảm bảo kết quả hoàn toàn trùng khớp với giá trị được công bố trong Release. Tệp DEB, tar.gz và arm64 cũng có thể được kiểm tra theo cách tương tự.

Giới hạn đã biết

1. Bản build chưa được ký: Tệp nhị phân Linux không có chữ ký mã và cũng không có chứng thực cấp hệ thống.
2. Chưa thể chuyển đổi tài liệu Office: Việc chuyển DOCX, XLSX và PPTX sang PDF phụ thuộc vào liên kết native Linux của LibreOffice Kit, hiện chưa được phân phối kèm gói cài đặt.
3. Upstream vẫn đang ở giai đoạn preview: Dự án chính thức đang ở giai đoạn developer preview, nên có thể xảy ra các thay đổi thường xuyên hoặc gây ảnh hưởng.
4. Không có phiên bản trên cửa hàng ứng dụng: Dự án không được phát hành thông qua quy trình của cửa hàng ứng dụng.

Giới hạn chuyển đổi Office không ảnh hưởng đến các khả năng desktop khác được README nêu rõ, bao gồm agent, skill, chức năng kết nối mạng và frontend.

Khuyến nghị nâng cao

• Ưu tiên chọn đúng kiến trúc: Không tải gói arm64 trên hệ thống x64 và ngược lại.
• Chọn AppImage khi cần khả năng cập nhật: README của DEB và tar.gz không tuyên bố sử dụng kênh cập nhật AppImage.
• Duy trì quy trình kiểm tra: Dù tải lần đầu hay cập nhật, vẫn nên đối chiếu SHA256 trong Release.
• Theo dõi thay đổi upstream: Fork này sẽ liên tục rebase các commit upstream, vì vậy nên đọc ghi chú Release trước khi nâng cấp.
• Nhà phát triển nên tận dụng CI nguyên bản: Khi cần xác minh đồng thời hai kiến trúc, có thể sử dụng workflow Desktop (Linux) hiện có của dự án thay vì giả định kết quả xây dựng chéo tương đương với bản build nguyên bản.

Trước khi chạy, cũng nên đọc SAFETY.md của upstream. Dự án upstream chính thức nằm tại deepseek-ai/deepseek-harness.

Tóm tắt

DeepSeek Harness Linux bổ sung khả năng phân phối Linux cho desktop chính thức trên x64 và arm64. Người dùng thông thường có thể ưu tiên AppImage với hỗ trợ cập nhật tự động; người dùng Debian hoặc Ubuntu cũng có thể cài DEB; nếu cần chạy di động, có thể chọn tar.gz. Vì bản build hiện tại chưa được ký, hãy luôn đối chiếu SHA256 khi tải xuống, cập nhật và triển khai, đồng thời lưu ý các thay đổi tương thích trong giai đoạn developer preview.