最近把 DeepSeek Harness 迁到了腾讯云上顺手把 dsh-market 插件市场也搭了起来整个过程比我想象中顺利但中间也踩了好几个坑。如果你正准备在云服务器上本地部署 DeepSeek Harness或者想用 dsh-market 统一管理智能体插件这篇教程应该能帮你省下不少时间。我会把从选服务器、装环境、初始化插件市场到跑通第一个插件的完整过程都写出来包括我在实操里遇到的各种问题。DeepSeek Harness 是一个面向 DeepSeek 模型的智能体运行框架说直白点它不是一个单纯的聊天开关而是一个可以同时管理多个智能体、编排复杂任务、动态加载插件的“工作台”。dsh-market 就是它的插件市场类似你在 Node 生态里用 npm、在 Python 生态里用 pip所有插件都能通过命令行统一搜索、安装、升级和卸载。下面我按实操顺序来拆解。1. 为什么要在腾讯云上折腾 DeepSeek Harness1.1 DeepSeek Harness 是什么它和普通客户端有什么区别我最早接触 DeepSeek Harness 的时候以为它就是个带好看的界面的 AI 客户端后来真正跑起来才发现完全不是一回事。它的核心能力在“编排”这个词上你可以同时启动多个智能体让它们各自处理不同的子任务然后由一个主流程统一汇总结果。这套机制配合插件系统能把原本需要在代码里硬编码的工具调用全部变成可插拔的模块。举个例子我在这台腾讯云服务器上跑了一个“定时资讯收集”的编排一个智能体负责抓取指定站点内容一个负责做摘要还有一个负责整理成结构化报告。三个智能体由 DeepSeek Harness 统一调度整个流程通过一份配置描述清楚不需要为每个子任务各写一套脚本。这种模式比普通客户端强在两点一是智能体会共享上下文前后任务能衔接起来二是所有能力都能被插件替换你不用把工具函数写死在程序里。也正因为如此插件管理就变成了一个绕不开的基础设施。如果你只有三五个插件手动解压、复制、改配置还能接受但插件一旦多起来版本冲突、依赖缺失、更新不及时这些问题会直接拖垮你的使用心情。dsh-market 解决的就是这个管理问题。1.2 插件市场解决了什么痛点dsh-market 这个插件市场的定位跟 VSCode 插件市场很像。它提供了一个统一注册源所有插件都有固定的包格式、版本号、依赖声明和入口文件。你要装一个新插件只需要一条 dsh market install 命令它会自动把插件下载到指定目录、检查依赖、把可执行文件或脚本注册到 PATH 里。我最早没用市场的时候是从仓库一个个 clone 源码再手动 build耗时不说最烦的是每个插件配置方式还不一样。有的要改环境变量有的要改 YAML 配置有的直接要求重编译。装了 dsh-market 之后插件安装路径、配置模板、版本元信息都由市场统一管理彻底告别“装个插件像搬家一样”的尴尬。另外dsh-market 还可以把插件源从官方公共源切换到自己的私有源。这个能力对企业内网或者像我这种在腾讯云上折腾私有部署的人来说非常关键后面我会专门讲怎么基于腾讯云对象存储搭一个私有插件源。1.3 为什么选腾讯云部署而不是本地电脑我在本地 Mac 上其实已经跑过一版 DeepSeek Harness迁移到腾讯云主要是三个原因。第一是 7x24 小时在线。本地电脑不可能一直不关机而云服务器可以一直挂着配合 systemd 守护进程所有的定时任务都能稳定跑。第二是公网访问。我在外面用手机或公司电脑也能通过 Web 面板或者 API 访问到这台服务器上的 DeepSeek Harness相当于给自己搭了一个随时可用的 AI 工作台。第三是资源弹性。DeepSeek Harness 本体占用资源不高2C4G 的机器就能跑得很稳但如果以后想接本地模型还可以随时升级到带 GPU 的实例不用重新部署一套环境。腾讯云在众多云厂商里属于上手门槛比较低的新用户有试用活动轻量应用服务器的价格也不贵对个人开发者比较友好。而且它的安全组策略和对象存储 COS 都是现成的正好配合插件市场做私有源。2. 部署前的准备工作2.1 腾讯云服务器选型与系统镜像如果只是跑 DeepSeek Harness 本体加一些常用插件腾讯云的轻量应用服务器 2C4G 就够了。我自己的机器就是 2C4G系统镜像选的 Ubuntu 22.04 LTS日常同时跑五六个插件没有压力。如果你打算把本地模型也跑在这台机器上那就不能按这个配置选了CPU 推理大模型基本不现实建议直接上带 GPU 的实例或者把模型服务单独部署在另一台 GPU 机器上DeepSeek Harness 通过 API 去连它。地域选择上我建议优先选离你经常访问的区域近的节点。国内用的话北京、上海、广州、成都这几个地域都行内网延迟差异在正常业务里几乎感知不到。选系统镜像有个小原则Ubuntu 和 Debian 这类系统软件源更新快碰到缺依赖的情况能用 apt 直接解决比 CentOS 省心很多。实例类型可以在下面这两种之间选场景推荐配置适用情况轻量应用服务器2C4G / 50G SSD只跑 DeepSeek Harness 插件编排、Web 面板云服务器 CVM2C4G 起步可后续升配需要自定义网络、快照、安全组更细粒度控制GPU 实例按需选择型号需要在本机跑开源模型并用 DeepSeek Harness 接入2.2 安全组与防火墙开放拿到服务器之后第一件事不是急着装软件而是把安全组配好。腾讯云的控制台里有“防火墙”或者“安全组”的入口你需要在里面放行 SSH 端口。如果你打算开 Web 面板还要放行对应的 Web 端口。我用的端口规划是这样的22 端口SSH 登录仅允许自己本机 IP 访问别向全网开放。8080 端口DeepSeek Harness Web 面板如果你需要。9000 端口本地模型服务端口如果你单独部署模型。这里有一个我踩过的坑修改安全组之后有些配置需要几秒钟才生效如果连不上不要立刻怀疑系统先看一眼安全组规则有没有保存成功。另外所有管理类接口尽量不要绑定在 0.0.0.0 上绑定到 127.0.0.1 然后通过 SSH 隧道访问更安全。2.3 基础依赖安装系统装好之后我习惯先把基础工具链补齐避免后面装插件时才发现连 git 都没有。以 Ubuntu 22.04 为例我用的是下面这一套sudo apt update sudo apt upgrade -y sudo apt install -y curl wget git vim unzip tar如果 DeepSeek Harness 需要从源码方式安装那还需要 Node.js 和 Python 环境。官方二进制安装方式对依赖要求会低很多但有些插件会在运行时调用 Node 脚本或者 Python 脚本所以建议顺手把这两个运行时也装上。# 安装 Node.js 18这里用 NodeSource 或腾讯云镜像都行 curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - sudo apt install -y nodejs # 检查版本 node -v npm -vPython 方面 Ubuntu 22.04 自带的是 Python 3.10一般够用只需要确认 pip 存在python3 --version python3 -m pip --version2.4 初始化系统基础配置不建议直接在 root 用户下跑服务我新建了一个普通用户 dsh所有服务都用这个用户运行。这样即使某个插件被攻破影响范围也受限于普通用户权限。sudo useradd -m -s /bin/bash dsh sudo passwd dsh sudo usermod -aG sudo dsh然后把 SSH 改成密钥登录关闭密码登录。这个步骤主要靠腾讯云控制台的“密钥对”功能创建好密钥后绑定实例即可。设置时区也很重要因为后面做定时任务时系统时区错了任务执行时间会跟着乱sudo timedatectl set-timezone Asia/Shanghai timedatectl3. dsh-market 安装实操全流程3.1 安装 DeepSeek Harness CLI 本体DeepSeek Harness 的安装方式有两种一种是直接跑官方安装脚本另一种是下载离线包自己解压。在线环境我推荐脚本方式curl -fsSL https://raw.githubusercontent.com/deepseek-harness/dsh/main/install.sh | bash这条命令会下载对应架构的二进制文件并放到 /usr/local/bin 下。安装完成后验证版本dsh --version如果输出类似 dsh/v0.3.2 (linux/amd64) 这样的信息就说明本体已经装好了。注意这里有一个在国内腾讯云上非常现实的问题直接从 GitHub 拉取 Release 文件速度有时候非常慢甚至直接超时。我遇到这种情况不会反复重试而是直接用离线包方案在自己电脑上下载好 tar.gz 包再通过 scp 传到服务器上解压。# 在本地下载后执行 scp dsh-linux-amd64.tar.gz dshyour-server-ip:/tmp/ # 在服务器上执行 cd /opt sudo tar -xzf /tmp/dsh-linux-amd64.tar.gz sudo ln -s /opt/dsh/bin/dsh /usr/local/bin/dsh3.2 初始化 dsh-market 插件市场CLI 装好之后插件市场默认是未初始化的。你需要执行下面的命令来初始化本地插件市场目录dsh market init这条命令会做几件事创建 ~/.dsh/market 目录作为插件存放目录生成一份配置文件 ~/.dsh/config.yaml把默认的官方插件注册源写入配置。初始化完之后你可以手动检查一下配置内容cat ~/.dsh/config.yaml核心配置项大概是这样的格式market: registry: https://market.deepseek-harness.com plugin_dir: ~/.dsh/market auto_update: true如果 auto_update 设置为 truedsh 在每次运行命令时会自动检查插件市场索引是否有更新方便是方便但在国内网络环境下会增加一次网络请求。我通常把它改成 false需要检查更新时手动执行 dsh market update。3.3 搜索并安装第一个插件插件市场初始化好之后可以先搜索一下目前有什么插件可用dsh market search codex搜索输出会列出插件全名、版本、简介等。找到想要的插件之后安装命令非常直接dsh market install codex安装过程会自动下载插件包、校验完整性、把可执行文件链接到 ~/.dsh/bin并更新本地插件索引。装完之后查看已安装插件列表dsh market list如果想升级某个插件可以这样dsh market update codex不想用了就直接卸载dsh market uninstall codex这一套命令用起来和 npm/pip 几乎一个逻辑学习成本很低。3.4 配置 DeepSeek 模型连接插件装好了还得让 DeepSeek Harness 能连上模型服务才能跑起来。这里分两种情况。第一种是走 DeepSeek 官方 API。你需要在环境变量里配置 API Keyexport DEEPSEEK_API_KEY你的key为了让配置持久化我习惯在 ~/.bashrc 里加这一行然后 source 一下。除了 API Key还可以配置基础地址方便后续切换网关export DEEPSEEK_BASE_URLhttps://api.deepseek.com第二种情况是接本地模型服务也就是热词里提到的“配置连接本地模型思考模式”。如果你本机或者另一台机器跑了一个 OpenAI 兼容的服务比如 Ollama、vLLM、llama.cpp那么只需要把 base URL 指过去export DEEPSEEK_BASE_URLhttp://127.0.0.1:11434/v1配好之后先跑一个最简单的命令验证连通性dsh run hello正常的话会返回模型的回复内容这串链路就算是通了。3.5 用 systemd 把服务跑起来云服务器上跑服务最忌讳的就是 SSH 一断开进程就跟着没了。我在部署完第一版的时候吃过这个亏后来直接用 systemd 管起来一劳永逸。先创建 service 文件sudo vim /etc/systemd/system/dsh.service内容如下[Unit] DescriptionDeepSeek Harness Service Afternetwork.target [Service] Userdsh EnvironmentFile/home/dsh/.dsh/env ExecStart/usr/local/bin/dsh serve --host 0.0.0.0 --port 8080 Restarton-failure RestartSec5 [Install] WantedBymulti-user.target这里我用了一个 EnvironmentFile专门用来存放 DEEPSEEK_API_KEY 这类敏感变量这样不会把密钥直接暴露在 service 文件里。启动并设置开机自启sudo systemctl daemon-reload sudo systemctl enable dsh sudo systemctl start dsh查看运行状态和日志sudo systemctl status dsh journalctl -u dsh -f4. 插件市场使用进阶与场景扩展4.1 插件包结构与管理机制如果你想写一个插件或者纯粹想搞清楚装进来的插件到底做了什么就有必要了解一下插件的目录结构。dsh-market 的插件包是一个统一格式的压缩包解压开后大概是这样的my-plugin/ ├── plugin.yaml # 插件声明文件 ├── bin/ │ └── my-plugin # 插件可执行文件 ├── scripts/ │ └── pre-install.sh # 安装前脚本可选 └── assets/ └── ... # 插件附带资源plugin.yaml 是插件的“身份证”里面至少包含 name、version、description 和 entrypoint 几个关键字段。entrypoint 指定了 dsh 调用这个插件时执行哪个可执行文件。dsh market install 在安装时会解析 plugin.yaml然后把 bin 目录下的可执行文件软链到 ~/.dsh/bin这样插件就可以直接通过命令调用了。理解了这个机制你在排查“插件明明装上了但命令不存在”这类问题时会快很多八成是软链没建成功或者 ~/.dsh/bin 不在 PATH 里。4.2 离线安装与内网发布如果你所在的服务器环境访问不了外网插件源离线安装是唯一的办法。dsh-market 支持从本地文件直接安装dsh market install ./my-plugin.dshx.dshx 就是插件市场的标准压缩包格式。你可以在一台能访问外网的机器上通过 dsh market pack 将插件打成本地包dsh market pack ./my-plugin -o ./my-plugin.dshx打包完成后把这个 .dshx 传到目标服务器再执行安装即可。这非常适合腾讯云上的新实例迁移场景在源服务器用 dsh market list 查看当前装的插件逐个 pack 出来拷到新机器上批量安装。4.3 基于腾讯云对象存储搭建私有插件源离线包适合一次性迁移但如果你的插件数量会持续增长或者你有团队要协作我建议直接把 dsh-market 的注册源切到腾讯云对象存储 COS 上做成一个私有插件市场。搭建思路其实不复杂dsh-market 的 registry 本质上是一个 JSON 索引文件里面记录了插件名、版本号、下载地址。你只需要把插件包上传到 COS 桶然后把索引文件的地址配置成 COS 的访问域名即可。具体做法分三步走。第一步创建一个 COS 存储桶设置为公有读私有写然后专门用来放插件包。第二步把打包好的 .dshx 文件上传到这个桶里。第三步在桶根目录放一份 index.json里面是插件清单{ name: my-private-market, plugins: [ { name: codex, version: 1.2.0, url: https://your-bucket.cos.ap-guangzhou.myqcloud.com/packages/codex-1.2.0.dshx, description: Codex workflow plugin } ] }上传完成后在服务器上修改 ~/.dsh/config.yamlmarket: registry: https://your-bucket.cos.ap-guangzhou.myqcloud.com/index.json然后执行 dsh market update 强制刷新索引再 install 插件。这里有一个非常实用的点COS 支持 CDN 加速如果你的团队成员分布在不同地域给存储桶绑上 CDN 域名后插件下载速度会稳定很多。4.4 定时任务与多智能体编排插件市场本身不解决编排问题但它是编排的基石。我在腾讯云这台机器上跑的最典型的编排任务是一个定时资讯收集工作流。配置文件大概长这样workflow: name: daily_news trigger: type: cron expression: 0 8 * * * agents: - name: collector plugin: web_fetcher args: targets: [url1, url2] - name: summarizer plugin: deepseek_summary args: max_tokens: 800 output: type: markdown path: /home/dsh/reports/daily_news.md用 systemd 启动一个 dsh service 之后DeepSeek Harness 会在每天早上 8 点自动触发这个工作流先让 collector 插件抓取页面再把内容交给 summarizer 插件做摘要最后落盘到指定目录。整个过程都不需要人工介入。这里我强烈推荐一个配置习惯把所有插件的参数写在 workflow 配置而不是命令行里。这样每个任务用了什么插件、传了什么参数都有据可查复现和排错都方便很多。5. 常见问题与排查技巧实录5.1 curl 安装脚本执行报错我遇到过最普遍的问题是在腾讯云上首次执行官方安装脚本时下载到一半就断掉或者直接报 403。原因大多是出网环境对 GitHub 资源的访问不稳定不是脚本写错了。我的处理方案很简单不要死磕在线脚本改走离线包。本地或跳板机下载好 tar.gz通过 scp 传到服务器。整个过程不依赖外网速度还快。另外要注意如果你用了代理工具反而可能导致证书不匹配的问题我后来干脆不在服务器上配置任何代理专心用离线包方案。5.2 插件市场 registry 连不上或超时这个问题基本都出在第一次执行 dsh market search 的时候命令卡住几十秒然后报 timeout。原因就是默认 registry 域名在国内访问速度慢。解决办法是把 registry 换成国内可达的地址或者直接用自建 COS 私有源。如果是个人玩我建议直接用 COS一劳永逸。5.3 插件装好了但命令找不到dsh market list 能看到插件已经安装但执行插件的命令却提示 command not found。这个问题的根源通常是 ~/.dsh/bin 没有加入 PATH。在 ~/.bashrc 里加上这一行export PATH$HOME/.dsh/bin:$PATH然后 source ~/.bashrc再试一次。如果是 systemd 启动的服务还需要在 service 文件里指定完整的 PATH 环境变量因为 systemd 环境默认不会读取用户级 .bashrc。5.4 日志出现 missing credential 或 authentication failed这个报错几乎都是 DEEPSEEK_API_KEY 没有正确设置。我用 systemd 托管之后就曾经因为忘记写 EnvironmentFile 而导致服务起得来但调用模型时报鉴权错误。排查顺序是先手动执行 dsh run hello 确认 key 在终端环境可用再确认 systemd 服务里是否指定了 EnvironmentFile最后检查 key 是不是有额外的空格或者换行这个问题非常隐蔽。5.5 systemd 服务启动失败且无详细错误如果你发现 systemd 启动失败但 status 里的信息不够定位先用下面的命令把具体错误打出来journalctl -u dsh -n 50 --no-pager如果日志里指向权限问题通常是你用了 root 创建了某些目录而 systemd 服务是以普通用户运行导致没有读写权限。解决办法是把 ~/.dsh 下的目录属主改成运行用户sudo chown -R dsh:dsh /home/dsh/.dsh5.6 端口被占用如果提示 bind: address already in use说明 8080 端口已经被其他程序占用。先查是谁占的sudo lsof -i :8080找到进程后根据情况处理或者直接修改 systemd 服务里的 --port 参数换一个端口。我建议在腾讯云安全组里把端口规则同时改掉不然客户端访问会无响应。常见症状可能原因解决办法安装脚本下载慢/失败GitHub 资源访问不稳定改用离线包 scp 上传后解压market search 卡住超时默认 registry 网络访问慢切换 COS 私有源或国内镜像插件装好但命令不存在~/.dsh/bin 不在 PATHexport PATH 并刷新 shell模型调用报鉴权错误API Key 未注入或包含空白字符检查环境变量和 systemd EnvironmentFilesystemd 启动失败目录权限不对chown 给运行用户端口 bind 失败端口被其他服务占用lsof 查占用进程并处理我个人在实际操作中最大的体会是不要在部署阶段同时处理太多事先把 DeepSeek Harness 本体跑起来再初始化插件市场最后才做编排和系统服务托管。这个顺序能帮你把问题域隔离开出问题时定位会快很多。最后再分享一个技巧如果你在腾讯云上跑的是多台服务器想把插件环境保持一致可以先把一台机器配置好然后把 ~/.dsh 整个目录打包传到其他机器解压覆盖。这样迁移一台机器只需要几分钟比一台台装插件高效得多。
