ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

首页/资讯中心/资讯详情

DeepSeek Harness 部署指南：从一行命令到 Linux 服务器上线

发布时间：2026/8/16 2:57:12 拓冰企业网站定制
DeepSeek Harness 部署指南：从一行命令到 Linux 服务器上线

文章目录

  • DeepSeek Harness 部署指南：从一行命令到 Linux 服务器上线
    • 一、部署前准备
    • 二、最快路径：npx 启动 Web UI
    • 三、源码部署：适合二次开发和插件开发
    • 四、无头模式：一条命令跑任务
    • 五、Linux 服务器上线
      • 1. 创建专用用户和目录
      • 2. 安装并配置环境变量
      • 3. systemd 托管
      • 4. Nginx 反向代理
    • 六、上线前的备份和更新
    • 七、常用环境变量
    • 八、部署清单
    • 九、常见问题
      • 启动后打不开页面？
      • 模型提示 `MISSING_CREDENTIAL`？
      • 提示 `UNKNOWN_MODEL`？
      • 能用其他模型吗？
      • 为什么不能 `--host 0.0.0.0`？
    • 参考资料

DeepSeek Harness 部署指南：从一行命令到 Linux 服务器上线

DeepSeek Harness（dsh）是 DeepSeek AI 官方开源的 agent harness，主打“一切皆插件”的架构，底层由 Cordis 驱动，采用 MIT 协议。它目前处于开发者预览阶段，版本迭代很快，官方明确提示后续会有破坏兼容性的变更。

这篇文章按四条路径写：npx快速体验、源码部署、无头任务模式、Linux 服务器上线，最后给部署清单和常见问题。

一、部署前准备

先确认本机环境：

项目要求
Node.js^22.19.0或>=24.0.0
包管理器快速体验只需 npm；源码部署需要pnpm@11.7.0
DeepSeek API KeyDeepSeek 开放平台生成
运行目录建议用独立 workspace，不要让 agent 直接操作系统根目录

检查版本：

node-vnpm-v

如果你要跑源码或开发插件，再检查：

corepackenablecorepack prepare pnpm@11.7.0--activatepnpm-v

二、最快路径：npx 启动 Web UI

官方推荐的第一条命令：

npx @deepseek-ai/dsh web

首次运行会通过 npm 下载@deepseek-ai/dsh，并自动初始化webprofile。默认监听地址是：

http://127.0.0.1:3080

浏览器打开后，完成三步即可跑第一个任务：

  1. 打开“设置 → 模型”，填入 DeepSeek API Key 并保存。
  2. 点击“选择工作区”，添加你启动dsh时所在的目录。
  3. 新建会话，发一条任务，例如“Summarize this repository and identify its main packages”。

模型密钥保存在$DSH_HOME/.credentials.yaml中，Web UI 只展示脱敏描述符，不会回显明文。密钥保存后不需要重启服务。

如果 3080 端口被占用，换一个端口：

npx @deepseek-ai/dsh web--port8080

长期使用建议全局安装，避免每次走 npx：

npminstall-g@deepseek-ai/dsh dsh--versiondsh web

三、源码部署：适合二次开发和插件开发

如果你要读源码、改插件或调试，从仓库运行：

gitclone https://github.com/deepseek-ai/deepseek-harness.gitcddeepseek-harnesspnpminstallpnpmrun buildpnpmdsh web

注意两点：

  • 源码运行必须先执行pnpm run build，仓库不会在启动时自动构建前端产物。
  • package.json里的pnpm dsh是源码入口，不是编译后的二进制。

源码部署后同样可以指定端口：

pnpmdsh web--port8080

查看 Web UI 支持哪些启动参数：

pnpmdsh web--help

四、无头模式：一条命令跑任务

不需要浏览器时，用headlessprofile 跑一次性任务。它不会监听端口，把最终答案打到 stdout，任务正常完成以 0 退出，否则以 1 退出，适合接 CI：

exportDEEPSEEK_API_KEY=sk-your-key-here dsh--profileheadless"run the tests"

任务文本必须作为位置参数直接跟在命令后面，headless profile 不接受 Web UI 的--port等参数：

dsh--profileheadless"Inspect the repository and fix the failing tests."

排查组合配置时不启动服务，可以打印配置树：

dsh--profileweb --dump-default-config dsh--profileweb--patch./extra.yml --dump-config

安装第三方插件也走 CLI：

dsh plugin--profilewebadd<package-or-git-spec>

插件管理命令会把参数转发给 pnpm，因此机器上需要安装 pnpm。Git 托管的插件如果带prepare构建脚本，第一次安装可能需要按提示在pnpm-workspace.yaml中允许对应构建脚本。

五、Linux 服务器上线

DeepSeek Harness 的 Web 服务器本身不提供 TLS、认证或来源策略。官方在 CLI 层故意拒绝--host 0.0.0.0，就是为了避免把远程代码执行能力直接暴露到网络。生产部署的正确姿势是：服务只监听回环地址，前面放 HTTPS 反向代理，再加一层认证。

1. 创建专用用户和目录

sudouseradd--system--create-home --home-dir /var/lib/dsh dshsudomkdir-p/srv/dsh-workspacesudochown-Rdsh:dsh /srv/dsh-workspace /var/lib/dsh

2. 安装并配置环境变量

sudonpminstall-g@deepseek-ai/dshwhichdsh

把密钥和配置目录写进 environment file，权限收紧：

sudotee/etc/dsh.env>/dev/null<<'EOF' DSH_HOME=/var/lib/dsh DEEPSEEK_API_KEY=sk-your-key-here EOFsudochmod600/etc/dsh.env

如果走 OpenAI 兼容网关，再加：

DEEPSEEK_BASE_URL=https://your-gateway.example/v1

3. systemd 托管

假设dsh安装在/usr/local/bin/dsh，--trusted-host填你的访问域名：

[Unit] Description=DeepSeek Harness Web After=network-online.target [Service] User=dsh Group=dsh WorkingDirectory=/srv/dsh-workspace EnvironmentFile=/etc/dsh.env ExecStart=/usr/local/bin/dsh web --port 3080 --trusted-host dsh.example.com Restart=on-failure RestartSec=5 TimeoutStopSec=10 NoNewPrivileges=true PrivateTmp=true [Install] WantedBy=multi-user.target

写入并启动：

sudonano/etc/systemd/system/dsh-web.service# 保存上面的 systemd 配置后执行：sudosystemctl daemon-reloadsudosystemctlenable--nowdsh-websudosystemctl status dsh-web

说明：

  • --trusted-host用于把浏览器访问的域名加入/api信任围栏，可重复传入，例如--trusted-host dsh.example.com。
  • 不要改成--host 0.0.0.0，CLI 会拒绝，这是安全设计。
  • WorkingDirectory是 agent 的默认 workspace，务必是专门目录。

4. Nginx 反向代理

server { listen 443 ssl http2; server_name dsh.example.com; ssl_certificate /etc/letsencrypt/live/dsh.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/dsh.example.com/privkey.pem; auth_basic "dsh"; auth_basic_user_file /etc/nginx/.dsh_htpasswd; location / { proxy_pass http://127.0.0.1:3080; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header X-Forwarded-Proto $scheme; } }

要点：

  • Web UI 需要 WebSocket/Upgrade，反向代理必须转发Upgrade和Connection。
  • 没有内置认证，务必在代理层加 Basic Auth、SSO 或只允许内网 IP。
  • 证书申请推荐 certbot，这里只展示 Nginx 配置骨架。

六、上线前的备份和更新

至少备份整个$DSH_HOME，里面包含密钥文件、settings、profiles 和会话数据：

sudotarczf /backup/dsh-$(date+%F).tar.gz /var/lib/dsh

更新策略：

sudonpmupdate-g@deepseek-ai/dshsudosystemctl restart dsh-web

源码部署则执行：

gitpullpnpminstallpnpmrun buildsudosystemctl restart dsh-web

因为当前是开发者预览，升级前先看官方发布说明和 Discussions，确认没有破坏性变更后再更新；更新前先备份。

七、常用环境变量

变量作用
DEEPSEEK_API_KEYDeepSeek API 密钥
DEEPSEEK_BASE_URL可选，覆盖默认https://api.deepseek.com
DSH_HOMEHarness 配置根目录，默认~/.dsh
DSH_MODELPython SDK 的默认模型
DSH_PERMISSION_MODE进程级权限预设，默认新会话为workspace-write
DSH_TELEMETRY_MODE遥测模式，默认本地保留，不主动上报
NODE_USE_ENV_PROXY=1需要走HTTP_PROXY/HTTPS_PROXY时设置

八、部署清单

  • Node.js 版本符合^22.19.0或>=24.0.0
  • 有 DeepSeek API Key
  • 使用独立 workspace 目录
  • dsh web能启动，默认地址可访问
  • 模型密钥已配置，能跑通一个任务
  • 生产环境只监听127.0.0.1
  • 反向代理已启用 HTTPS
  • 代理层有认证或访问限制
  • --trusted-host已配置访问域名
  • systemd 开机自启和失败重启正常
  • $DSH_HOME已加入备份
  • 升级前阅读发布说明

九、常见问题

启动后打不开页面？

默认地址是http://127.0.0.1:3080。确认进程还在运行，端口没被占用；端口冲突时用dsh web --port 8080。

模型提示MISSING_CREDENTIAL？

到“设置 → 模型”保存 API Key，或确认DEEPSEEK_API_KEY环境变量已设置。密钥解析顺序是环境变量、$DSH_HOME/.credentials.yaml、调用目录.env、$DSH_HOME/.env。

提示UNKNOWN_MODEL？

在模型设置里选择已配置的模型；自定义 OpenAI 兼容端点需要手动补上模型 id。

能用其他模型吗？

可以。Web UI 的“添加提供方”支持 Anthropic、OpenAI 等已安装目录，“添加自定义提供方”支持任意 OpenAI 兼容端点。Bedrock、Vertex、Azure、Codex 需要各自的原生凭据。

为什么不能--host 0.0.0.0？

CLI 有意拒绝，因为 Web UI 会执行代码、改文件、跑命令，直接绑全网卡等于把远程代码执行暴露到网络。生产环境应保持回环监听，用反向代理转发。

参考资料

  • 官方仓库：https://github.com/deepseek-ai/deepseek-harness
  • 中文 README：https://github.com/deepseek-ai/deepseek-harness/blob/master/README.zh.md
  • Web UI 指南：https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/index.zh.md
  • 模型配置指南：https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/providers.zh.md
  • CLI 行为参考：https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/reference/README.zh.md

本文基于 DeepSeek Harness0.1.0-rc.x官方文档整理，整理日期 2026-08-15。项目处于开发者预览，命令和配置可能随版本变化。

网站建设 企业官网 运营推广
返回列表