一、DeepSeek Harness 介绍1.1 什么是 DeepSeek HarnessDeepSeek Harness(简称 DSH)是 DeepSeek 开源的一款 AI 智能体开发平台:提供网页界面、会话管理以及代码执行、文件操作、任务看板、SSH 运维等工具能力让开发者像使用集成开发环境(IDE)一样与 AI 智能体协作。1.2 仓库与资源资源地址官方仓库https://github.com/deepseek-ai/deepseek-harnessnpm 包https://www.npmjs.com/package/deepseek-ai/dsh国内 npm 镜像https://registry.npmmirror.com/deepseek-ai/dshNode 下载镜像https://npmmirror.com/mirrors/node/1.3 功能特性会话式协作像聊天一样与 AI 协作,支持多会话、历史记录与流式输出会话中可切换不同的智能体预设与已装插件能力工具系统:让 AI 真正「动手」代码执行在授权范围内调用终端实际运行命令文件操作浏览目录、读取/编辑文件插件生态:按需扩展能力插件能力任务看板多列看板管理任务,支持定时任务(cron),关闭浏览器后仍由宿主机执行SSH 运维远程命令执行、文件传输、端口隧道、集群并发操作桌面启动器一键启动 DSH 网页版、创建快捷方式无界面模式dsh --profile headless 任务命令行直接跑任务,便于脚本化与 CI/CD 集成多模型支持「设置」中可配置 DeepSeek 等多家模型服务商随时切换二、DeepSeek Harness 安装2.1 安装 Node.jsDeepSeek Harness 依赖Node.js 22(官方要求 ≥ 22.12)需要先装好 Node.js, 同时运行环境还需满足glibc ≥ 2.28(macOS 无此限制;这一要求同时保证了 DSH 用到的 zstd 压缩接口可用)。⚠️CentOS 7 用户请注意CentOS 7 的 glibc 停留在 2.17,不支持 Node.js 22, 直接安装会报GLIBC_2.28 not found。可参考第三章的 Docker 安装方式用容器绕开系统限制。安装 Node.js 有两种方式直接安装适合只用一个版本、用 nvm 安装推荐方便多版本切换。方式一直接安装Windows去 nodejs.org 下载22.x LTS(长期支持版)安装包一路下一步安装即可。https://nodejs.org国内下载慢可改用 npmmirror 镜像下载安装包(msi).https://npmmirror.com/mirrors/node/macOS:去 nodejs.org 或 npmmirror 镜像下载22.x LTS(长期支持版)安装包Apple 芯片选 arm64 版Intel 选 x64 版双击安装或用 Homebrewbrew install node22。macOS 没有 glibc 概念不存在 glibc 版本限制原生安装即可。Linux(Ubuntu / Debian 等):# NodeSource 官方源curl-fsSLhttps://deb.nodesource.com/setup_22.x|sudo-Ebash-sudoapt-getinstall-ynodejs方式二使用 nvm 安装(推荐)nvm 是 Node.js 版本管理器可以在多个 Node 版本间自由切换还能配合国内镜像加速下载开发环境强烈推荐。第 1 步安装 nvmLinux / macOS国内网络推荐 gitee 上的nvm-cn一键脚本下载源已自动指向国内bash-c$(curl-fsSLhttps://gitee.com/RubyMetric/nvm-cn/raw/main/install.sh)source~/.bashrc# 或 source ~/.zshrc能访问 GitHub 的话也可用官方脚本curl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh|bashWindows安装 nvm-windows官网下载安装包用法与 Linux/macOS 一致只是安装命令需写完整版本号如nvm install 22.14.0.第 2 步配置国内下载源可选国内网络建议exportNVM_NODEJS_ORG_MIRRORhttps://npmmirror.com/mirrors/node/# 想永久生效把上面这行追加到 ~/.bashrc 或 ~/.zshrc第 3 步安装并切换 Node 22nvminstall22nvm use22nvmaliasdefault22# 设为默认版本nvm 常用命令速查命令作用nvm install 22安装 22.x 最新版nvm use 22切换当前终端使用的版本nvm alias default 22设为默认版本(新终端生效)nvm ls查看已安装版本nvm install --lts安装最新 LTS 版本装完 Node.js 统一验证node-v# 期望 v22.x2.2 安装 DeepSeek Harness运行环境就绪后直接全局安装 DeepSeek Harness:npminstall-g--registryhttps://registry.npmmirror.com deepseek-ai/dsh安装成功后可通过查看 DeepSeek Harness 版本验证dsh--version2.3 启动与访问直接在终端中输入并运行dsh web启动成功后本地浏览器输入访问http://127.0.0.1:3080首次启动会提示需要添加一个 DeepSeek 的 API Key.也可以稍后配置到「设置」页面配置 AI 模型。模型配置好添加一个本地目录下的工作空间后即可开始使用。三、DeepSeek Harness Docker 安装3.1 安装 Docker以 CentOS 7 为例Docker 20.10 是最后一个支持 CentOS 7 的版本yuminstall-yyum-utils yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo yuminstall-ydocker-ce docker-ce-cli containerd.io systemctlenable--nowdockerdocker--version# 确认 20.10.x命令说明命令作用yum install -y yum-utils安装 yum-config-manager 工具yum-config-manager --add-repo ...添加 Docker 官方 yum 源yum install -y docker-ce docker-ce-cli containerd.io安装 Docker 引擎、命令行工具与 containerdsystemctl enable --now docker设置开机自启并立即启动docker --version验证版本CentOS 7 应为 20.10.x国内网络提示官方 yum 源在download.docker.com, 添加源或下载超时的话,改用国内镜像源阿里云 / 清华yum-config-manager --add-repo https://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo yum clean all yuminstall-ydocker-ce docker-ce-cli containerd.io建议顺手配置国内镜像加速mkdir-p/etc/dockercat/etc/docker/daemon.jsonEOF { registry-mirrors: [https://docker.m.daocloud.io] } EOFsystemctl restartdocker3.2 Dockerfile下面这份 Dockerfile 集成了全部踩坑修复一句话概括Node 22 Nginx 反代 浏览器兼容补丁 内置 pnpm 一条命令部署。# syntaxdocker/dockerfile:1 # DeepSeek Harness (DSH) 网页版 — 内置 Nginx 反向代理 # 国内源:基础镜像 DaoCloud / apt 阿里云 / npm npmmirror ARG NODE_IMAGEdocker.m.daocloud.io/library/node:22-slim FROM ${NODE_IMAGE} ARG APT_MIRRORmirrors.aliyun.com ARG NPM_REGISTRYhttps://registry.npmmirror.com ARG DSH_VERSION0.1.0-rc.7 ENV DSH_HOME/data/dsh \ NODE_ENVproduction \ npm_config_registry${NPM_REGISTRY} # 1. 创建非 root 用户,安装 DSH pnpm(npm 包,无需编译源码) RUN groupadd --system dsh \ useradd --system --gid dsh --home-dir /home/dsh --create-home dsh \ npm config set registry ${NPM_REGISTRY} \ npm install -g --no-fund --no-audit --loglevelerror \ --registry${NPM_REGISTRY} deepseek-ai/dsh${DSH_VERSION} \ npm install -g --no-fund --no-audit --loglevelerror \ --registry${NPM_REGISTRY} pnpm \ printf registry%s\n ${NPM_REGISTRY} /usr/local/etc/npmrc \ mkdir -p ${DSH_HOME} \ chown -R dsh:dsh ${DSH_HOME} /home/dsh # 2. 安装 Nginx 浏览器兼容补丁 反代配置 入口脚本 RUN sed -i s|deb.debian.org|${APT_MIRROR}|g \ /etc/apt/sources.list.d/debian.sources /etc/apt/sources.list 2/dev/null || true \ apt-get update \ apt-get install -y --no-install-recommends nginx-full \ rm -rf /var/lib/apt/lists/* \ mkdir -p /usr/share/nginx/html \ printf %s\n \ /* DSH 浏览器兼容补丁 */ \ if (!crypto.randomUUID) { \ crypto.randomUUID function () { \ var b crypto.getRandomValues(new Uint8Array(16)); \ b[6] (b[6] 0x0f) | 0x40; \ b[8] (b[8] 0x3f) | 0x80; \ var h Array.prototype.map.call(b, function (v) { return (0 v.toString(16)).slice(-2); }); \ return h.slice(0, 4).join() - h.slice(4, 6).join() - h.slice(6, 8).join() - h.slice(8, 10).join() - h.slice(10).join(); \ }; \ } \ if (!AbortSignal.any) { \ AbortSignal.any function (signals) { \ var controller new AbortController(); \ var list Array.prototype.slice.call(signals || []); \ if (list.length 0) { return controller.signal; } \ var aborted false; \ var onAbort function (ev) { \ if (aborted) { return; } \ aborted true; \ var src ev ev.target ? ev.target : null; \ var reason src src.reason ! undefined ? src.reason : new DOMException(Aborted, AbortError); \ controller.abort(reason); \ }; \ for (var i 0; i list.length; i) { \ var s list[i]; \ if (s s.aborted) { controller.abort(s.reason || new DOMException(Aborted, AbortError)); return controller.signal; } \ if (s typeof s.addEventListener function) { s.addEventListener(abort, onAbort, { once: true }); } \ } \ return controller.signal; \ }; \ } \ /usr/share/nginx/html/polyfills.js \ printf %s\n \ server { \ listen 3080; \ server_name _; \ client_max_body_size 200m; \ location /polyfills.js { \ root /usr/share/nginx/html; \ } \ location / { \ proxy_pass http://127.0.0.1:3081; \ proxy_http_version 1.1; \ proxy_set_header Upgrade $http_upgrade; \ proxy_set_header Connection upgrade; \ proxy_set_header Host 127.0.0.1:3081; \ proxy_set_header Origin ; \ proxy_set_header X-Real-IP $remote_addr; \ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; \ proxy_set_header X-Forwarded-Proto $scheme; \ proxy_read_timeout 3600s; \ proxy_send_timeout 3600s; \ proxy_set_header Accept-Encoding ; \ sub_filter_once off; \ sub_filter /head script src\/polyfills.js\/script/head; \ } \ } \ /etc/nginx/conf.d/dsh.conf \ rm -f /etc/nginx/sites-enabled/default \ printf %s\n \ #!/bin/sh \ set -e \ # 自动修正数据目录属主:命名卷/本地目录挂载都适用(bind mount 会保留宿主属主) \ if [ $(stat -c %u $DSH_HOME) ! $(id -u dsh) ]; then chown -R dsh:dsh $DSH_HOME; fi \ nginx -g daemon off; \ exec su -s /bin/sh dsh -c exec /usr/local/bin/dsh web --port 3081 \ /usr/local/bin/dsh-entrypoint.sh \ chmod x /usr/local/bin/dsh-entrypoint.sh USER root WORKDIR /home/dsh VOLUME [/data/dsh] EXPOSE 3080 HEALTHCHECK --interval30s --timeout5s --start-period20s --retries3 \ CMD node -e require(net).connect(3081,127.0.0.1).on(connect,()process.exit(0)).on(error,()process.exit(1)) ENTRYPOINT [/usr/local/bin/dsh-entrypoint.sh]几个关键设计设计解决什么问题基础镜像node:22-slimNode ≥ 22.12 自带新 glibc, 与 CentOS 7 无关npm 安装而非源码编译deepseek-ai/dsh是成品包无需 pnpm 构建内置 pnpm容器内直接dsh plugin装插件非 root 用户运行DSH 能执行代码禁止以 root 运行Nginx 反代0.0.0.0:3080 → 127.0.0.1:3081DSH 只监听回环地址需要对外入口端口错开(DSH 用 3081)Linux 上同端口通配/回环绑定会冲突(EADDRINUSE)Host 改写 Origin 剥离通过 DSH 的「浏览器信任围栏」否则 API 返回 403兼容补丁注入老浏览器 / 明文 HTTP 下补齐crypto.randomUUID和AbortSignal.any3.3 构建与启动# 把上面的 Dockerfile 保存到目录里然后mkdir-p/opt/dshcd/opt/dsh# 构建(首次几分钟)dockerbuild-tdsh:0.1.0-rc.7.# 运行容器dockerrun-d--namedsh\-p3080:3080\-vdsh-data:/data/dsh\--restartunless-stopped\dsh:0.1.0-rc.7# 验证curl-shttp://127.0.0.1:3080/-o/dev/null-w%{http_code}\n# 期望 200挂载方式说明-v dsh-data:/data/dsh命名卷推荐首次创建自动继承镜像内属主-v /opt/dsh/data:/data/dsh本地目录(bind mount), 宿主机目录属主通常是 root——镜像入口脚本每次启动会自动检查并修正/data/dsh属主两种方式都不会再遇到 EACCES 权限问题容器启动成功后浏览器访问http://服务器IP:3080到「设置」配置模型 API 密钥数据持久化在dsh-data卷中重启容器不会丢失。3.4 安装插件# 进入容器装插件(务必用 dsh 用户不要用 root, 否则会改乱卷内文件属主)dockerexec-it-udsh dshsh-cdsh plugin --profile web add linxin666/dsh-web-ui-alldockerrestart dsh插件装在数据卷里(/data/dsh/profiles/web/node_modules), 容器重建后仍然保留;而pnpm 是构建镜像时装进镜像的如果你的镜像是没有内置 pnpm 的旧版重建容器后 pnpm 会丢失需要先补装一次(npm install -g pnpm)。用本文 Dockerfile 构建的最新镜像已内置 pnpm, 重建后无需补装。安装插件遇到的问题⚠️报EACCES: permission denied时说明卷里有 root 属主文件多半是之前用 root 身份跑过容器命令重建镜像不会清空数据卷旧权限会保留先修属主再安装dockerexec-uroot dshchown-Rdsh:dsh /data/dsh# 容器已退出的用docker run --rm -it -v dsh-data:/data/dsh --entrypoint sh -u root dsh:0.1.0-rc.7 -c chown -R dsh:dsh /data/dsh# 数据不重要想彻底重来docker rm -f dsh docker volume rm dsh-data, 再重新 docker run⚠️报ERR_PNPM_IGNORED_BUILDS(pnpm 拦截构建脚本)时这是 pnpm 10 的安全机制交互式批准即可空格勾选 → 回车确认再重装dockerexec-it-udsh dshsh-ccd /data/dsh/profiles/web pnpm approve-buildsdockerexec-it-udsh dshsh-cdsh plugin --profile web add 插件包名非交互备选把被拦的包名写进 profile 的pnpm-workspace.yaml再重装dockerexec-it-udsh dshsh-ccat /data/dsh/profiles/web/pnpm-workspace.yaml EOF onlyBuiltDependencies: - node-pty - ssh2 EOFdockerexec-it-udsh dshsh-cdsh plugin --profile web add 插件包名3.5 遇到的问题与解决问题 1在 CentOS 7 中安装 Node.js 后运行出现GLIBC / CXXABI not foundnode: /lib64/libc.so.6: version GLIBC_2.28 not found原因CentOS 7 的 glibc 2.17 跑不动新版 Node (要求 ≥ 2.28)解决改用 Docker 部署临时方案可用官方为 glibc 2.17 编译的x64-glibc-217构建但版本上限 Node 22 且无 zstd, 不满足 DeepSeek Harness 的使用需求问题 2createZstdDecompress not foundThe requested module node:zlib does not provide an export named createZstdDecompress原因zstd 压缩接口是Node 22.4.0才加入的旧版 Node 或 glibc-217 老构建没有解决使用最新的node:22-slim镜像问题 3EADDRINUSE 端口被占Error: listen EADDRINUSE: address already in use 127.0.0.1:3080原因Linux 下先监听0.0.0.0:3080后再绑定127.0.0.1:3080会冲突防端口劫持机制解决Nginx 占对外 3080, DeepSeek Harness 改绑内部端口 3081问题 4crypto.randomUUID is not a function原因浏览器只在「安全上下文」(HTTPS 或 localhost)提供该接口明文 HTTP 访问局域网 IP 时没有解决Nginx 注入兼容补丁(polyfill), 用同样允许的crypto.getRandomValues实现 UUID v4问题 5AbortSignal.any is not a function原因AbortSignal.any是较新的网页接口(Web API), Chrome/Edge 116 之前、Firefox 123 之前不支持解决兼容补丁(polyfill)补齐或直接升级浏览器问题 6/api/host.listDirectory: HTTP 403原因DSH 的「浏览器信任围栏」要求接口请求的Host 必须是回环地址且 Origin 的 host 必须等于 Host——这是防 DNS 重绑定(DNS rebinding)和跨站请求的安全设计反代透传了Host: IP:3080, 被判不可信解决Nginx 反代改写Host 127.0.0.1:3081、剥离Origin头四、DeepSeek Harness 使用4.1 快速上手第一步配置模型 API 密钥打开网页界面后,进入「设置」页面选择模型服务商(如 DeepSeek)、填入 API 密钥保存后即可开始对话。配置保存在$DSH_HOME(Docker 部署时即/data/dsh, 位于dsh-data卷)重启容器/进程不会丢失之后随时可在设置里更换模型或补充其他服务商。第二步新建会话开始对话在左侧会话列表点「新建会话」,输入框支持多行回车或点发送即可开始会话支持选择不同的智能体预设(preset)与已装插件能力回复流式输出可随时停止、继续历史会话左侧随时切换回来会话记录持久化在$DSH_HOME下的sessions/、storages/等目录。工具系统让 AI 真正「动手」DSH 的核心价值是工具调用——会话中 AI 不只是给建议还会在授权范围内执行代码、读写文件代码执行把任务交给 DeepSeek Harness, 它会调用终端工具实际运行而不是只给一段代码文件操作浏览目录、读取/编辑文件即文中提到的host.listDirectory等接口能力⚠️ 这些能力意味着 AI 能操作宿主机的文件系统务必只在可信环境使用。4.2 插件模块按需扩展能力DeepSeek Harness 具有强大的插件生态 —— 可以说只有你想不到没有它装不了无论是任务看板、SSH 运维还是定时自动化一条dsh plugin命令搞定能力无限扩展装完重启即用。安装插件插件本质是 npm 包统一用dsh plugin --profile web pnpm参数管理需要先装 pnpm.# 安装 pnpmnpminstall-gpnpm# 安装插件自动加入层列表dsh plugin--profilewebadd插件包名# 卸载插件dsh plugin--profileweb remove插件包名# 装完重启 dsh web 生效dsh web找插件包名npm search --registryhttps://registry.npmmirror.com 关键词;Docker 部署时用第三章的方式docker exec -it -u dsh dsh sh -c dsh plugin --profile web add 插件包名, 装完重启容器。例如安装linxin666/dsh-web-ui-all插件dsh plugin--profilewebaddlinxin666/dsh-web-ui-alldockerexec-it-udsh dshsh-cdsh plugin --profile web add linxin666/dsh-web-ui-all安装成功后侧边栏会出现插件入口常用的有插件模块能做什么任务看板多列看板管理任务支持定时任务(cron),关闭浏览器后仍由宿主机继续执行SSH 运维配置远程主机执行命令、传输文件、端口隧道、集群并发操作桌面启动器一键启动 DSH 网页版、创建快捷方式4.3 常用命令速查操作命令启动网页界面dsh web无界面直接跑任务dsh --profile headless 写一个 hello world安装插件dsh plugin --profile web add 包名卸载插件dsh plugin --profile web remove 包名查看帮助dsh --help五、结语本文从 DeepSeek Harness 是什么讲起带你走完了 Windows、macOS、Linux 的常规安装、老系统的 Docker 部署再到部署后的简单使用并把实际踩过的 6 个坑和对应解法全部附上希望能帮你少走弯路。DeepSeek Harness 的价值在于把「和 AI 对话」变成「让 AI 动手」——安装只是开始把日常的开发、运维任务交给智能体才是真正的生产力。最后再提醒一句DeepSeek Harness 能执行代码,请只在可信环境使用,不要暴露到公网如果你在安装或使用中遇到问题欢迎留言交流我们一起排查。