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 Harnessdsh是 DeepSeek AI 官方开源的 agent harness主打“一切皆插件”的架构底层由 Cordis 驱动采用 MIT 协议。它目前处于开发者预览阶段版本迭代很快官方明确提示后续会有破坏兼容性的变更。这篇文章按四条路径写npx快速体验、源码部署、无头任务模式、Linux 服务器上线最后给部署清单和常见问题。一、部署前准备先确认本机环境项目要求Node.js^22.19.0或24.0.0包管理器快速体验只需 npm源码部署需要pnpm11.7.0DeepSeek API KeyDeepSeek 开放平台生成运行目录建议用独立 workspace不要让 agent 直接操作系统根目录检查版本node-vnpm-v如果你要跑源码或开发插件再检查corepackenablecorepack prepare pnpm11.7.0--activatepnpm-v二、最快路径npx 启动 Web UI官方推荐的第一条命令npx deepseek-ai/dsh web首次运行会通过 npm 下载deepseek-ai/dsh并自动初始化webprofile。默认监听地址是http://127.0.0.1:3080浏览器打开后完成三步即可跑第一个任务打开“设置 → 模型”填入 DeepSeek API Key 并保存。点击“选择工作区”添加你启动dsh时所在的目录。新建会话发一条任务例如“Summarize this repository and identify its main packages”。模型密钥保存在$DSH_HOME/.credentials.yaml中Web UI 只展示脱敏描述符不会回显明文。密钥保存后不需要重启服务。如果 3080 端口被占用换一个端口npx deepseek-ai/dsh web--port8080长期使用建议全局安装避免每次走 npxnpminstall-gdeepseek-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 退出适合接 CIexportDEEPSEEK_API_KEYsk-your-key-here dsh--profileheadlessrun the tests任务文本必须作为位置参数直接跟在命令后面headless profile 不接受 Web UI 的--port等参数dsh--profileheadlessInspect the repository and fix the failing tests.排查组合配置时不启动服务可以打印配置树dsh--profileweb --dump-default-config dsh--profileweb--patch./extra.yml --dump-config安装第三方插件也走 CLIdsh plugin--profilewebaddpackage-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/dsh2. 安装并配置环境变量sudonpminstall-gdeepseek-ai/dshwhichdsh把密钥和配置目录写进 environment file权限收紧sudotee/etc/dsh.env/dev/nullEOF DSH_HOME/var/lib/dsh DEEPSEEK_API_KEYsk-your-key-here EOFsudochmod600/etc/dsh.env如果走 OpenAI 兼容网关再加DEEPSEEK_BASE_URLhttps://your-gateway.example/v13. systemd 托管假设dsh安装在/usr/local/bin/dsh--trusted-host填你的访问域名[Unit] DescriptionDeepSeek Harness Web Afternetwork-online.target [Service] Userdsh Groupdsh WorkingDirectory/srv/dsh-workspace EnvironmentFile/etc/dsh.env ExecStart/usr/local/bin/dsh web --port 3080 --trusted-host dsh.example.com Restarton-failure RestartSec5 TimeoutStopSec10 NoNewPrivilegestrue PrivateTmptrue [Install] WantedBymulti-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.0CLI 会拒绝这是安全设计。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-gdeepseek-ai/dshsudosystemctl restart dsh-web源码部署则执行gitpullpnpminstallpnpmrun buildsudosystemctl restart dsh-web因为当前是开发者预览升级前先看官方发布说明和 Discussions确认没有破坏性变更后再更新更新前先备份。七、常用环境变量变量作用DEEPSEEK_API_KEYDeepSeek API 密钥DEEPSEEK_BASE_URL可选覆盖默认https://api.deepseek.comDSH_HOMEHarness 配置根目录默认~/.dshDSH_MODELPython SDK 的默认模型DSH_PERMISSION_MODE进程级权限预设默认新会话为workspace-writeDSH_TELEMETRY_MODE遥测模式默认本地保留不主动上报NODE_USE_ENV_PROXY1需要走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.0CLI 有意拒绝因为 Web UI 会执行代码、改文件、跑命令直接绑全网卡等于把远程代码执行暴露到网络。生产环境应保持回环监听用反向代理转发。参考资料官方仓库https://github.com/deepseek-ai/deepseek-harness中文 READMEhttps://github.com/deepseek-ai/deepseek-harness/blob/master/README.zh.mdWeb 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.mdCLI 行为参考https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/reference/README.zh.md本文基于 DeepSeek Harness0.1.0-rc.x官方文档整理整理日期 2026-08-15。项目处于开发者预览命令和配置可能随版本变化。