🚀 Ubuntu 26.04 LTS 源码安装 DeepSeek Harness 完整教程

本教程将指导你在 Ubuntu 26.04 系统上，通过官方 GitHub 仓库源码编译并运行 DeepSeek Harness —— 一个基于 Node.js 的 AI 智能体框架。同时，我们还会创建桌面快捷方式，并将本地已运行的 Qwen3.8-27B 模型接入 Harness，实现完全本地化的 AI 开发环境。

1. 前提准备

更新系统并安装必要的基础工具：

sudo apt update
sudo apt install -y git curl

2. 安装 Node.js

DeepSeek Harness 要求 Node.js ≥ v22.19。Ubuntu 26.04 官方源已提供 v22.x，直接安装即可：

sudo apt install -y nodejs npm

若官方源版本过低，可使用 NodeSource 安装最新 LTS：

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

验证安装：

node --version   # 应显示 v22.x.x 或更高

3. 安装 pnpm

DeepSeek Harness 使用 pnpm 作为包管理器，要求版本 ≥ 11。通过 npm 全局安装：

sudo npm install -g pnpm
pnpm --version   # 应显示 11.x.x 或更高

4. 克隆官方仓库并安装依赖

# 克隆仓库（带 .git 或不带均可）
git clone https://github.com/deepseek-ai/deepseek-harness.git

# 进入项目目录
cd deepseek-harness

# 安装项目依赖
pnpm install

5. 构建并启动服务

# 构建项目（这一步不可省略）
pnpm run build

# 启动 Web UI
pnpm dsh web

启动成功后，终端会显示访问地址（默认 http://127.0.0.1:3080）。
⚠️ 注意： 此终端窗口需要保持打开，关闭会导致服务终止。

6. 首次配置（可选：云端 API Key）

如果你需要使用 DeepSeek 云端模型（付费 API），可按以下步骤填写 Key。若你只打算使用本地模型（如 Qwen），可以跳过本节，直接进入第 8 节。

1. 获取 API Key： 前往 DeepSeek 开放平台 注册并创建 API Key。
2. 填写 Key： 在浏览器访问 http://127.0.0.1:3080，进入 Settings → Models，在 DeepSeek 卡片中填入 API Key 并保存。
3. 选择工作区： 点击 Choose workspace，授予 Harness 访问指定文件夹的权限。

7. 创建桌面快捷方式（一键启动）

为了免去每次打开终端并输入命令的麻烦，我们创建一个桌面快捷方式，双击即可启动 Harness Web UI。

在桌面空白处右键，选择 “在终端中打开”（Open in Terminal），然后执行：

nano dsh-web.desktop

粘贴以下内容（请根据你的实际用户名修改 /home/ai 路径）：

[Desktop Entry]
Version=1.0
Type=Application
Name=DeepSeek Harness
Comment=Launch DeepSeek Harness Web UI
Exec=bash -c "cd /home/ai/deepseek-harness && pnpm dsh web"
Icon=web-browser
Terminal=true
Categories=Development;

保存并退出： 按 Ctrl+O，回车，再按 Ctrl+X。

接着赋予执行权限：

chmod +x dsh-web.desktop

之后，右键点击桌面上的 dsh-web.desktop 文件，选择 “允许启动”（Allow Launching）。以后双击此图标即可启动 Harness 服务（终端窗口会打开，保持运行即可）。

8. 配置本地 Qwen 模型（接入 Harness）

如果你已经按照本站之前的教程成功运行了 llama.cpp + Qwen3.8-27B（服务地址为 http://127.0.0.1:8080），可以将其作为本地模型添加到 DeepSeek Harness 中，实现完全离线使用。

1. 确保 llama.cpp 服务正在运行（双击桌面上的 QwenServer.desktop 或手动启动）。
2. 打开浏览器访问 http://127.0.0.1:3080，进入 Harness 的 Web UI。
   • 首次打开时，会弹出一个要求输入 DeepSeek API Key 的对话框（因为 Harness 默认使用云端服务）。
   • 直接点击对话框右上角的 × 或 Cancel 将其关闭，我们稍后会配置本地模型，无需填写。
3. 点击左下角的 Settings（齿轮图标），然后选择 Models 选项卡。
4. 点击 Add Custom Model（或类似按钮），填写以下信息：
   • Name： 随意填写，如 Qwen3.8-27B (Local)
   • API Base URL： http://127.0.0.1:8080/v1（注意末尾的 /v1）
   • API Key： 留空或输入任意占位符（如 dummy）
   • Model ID： 与 llama.cpp 中的模型名一致，此处为 qwen3.8-27b-q4_k_m
5. 点击 Save 保存。之后在聊天界面选择该模型即可使用本地 Qwen 进行对话。

其他安装方式（备选）

除了源码编译，还有两种更简便的方式：

• npx 一键启动： 无需克隆代码，直接运行 npx @deepseek-ai/dsh web（推荐新手使用）。
• 桌面应用： 社区封装的 .deb 或 .AppImage 文件，双击安装即可（非官方出品）。

至此，DeepSeek Harness 已在你的 Ubuntu 26.04 上成功运行，并配置好本地 Qwen 模型。如有问题，欢迎在评论区交流！