我们直接进入主题讲讲在 Linux 服务器上从零开始源码部署 DeepSeek Harness 的 Web 版。我默认你已经有一台能联网、能 SSH 登录的 Linux 机器无论是阿里云、腾讯云这类云主机还是家里的老电脑、树莓派本文的方法都适用。就像标题说的这是一个保姆级教程从系统准备到最终远程访问我会把每一步的命令、原理和踩坑点都交代清楚。先说清楚 DeepSeek Harness Web 到底是个什么。它本质上是一个把 DeepSeek 系列模型以及其他兼容 OpenAI 接口的模型封装成带 Web 界面的私有部署工具核心价值在于用浏览器对话的方式调模型能力不用懂后端代码也不用装桌面客户端。对于想在团队内共享、远程调用、或者嵌入到自己的小项目里的场景这个 Web 版非常方便。整个过程走完你会得到一个能运行在 Linux 上、可通过 IP 或域名远程访问的 Web 服务。这篇教程适合谁一个是刚接触 Linux 部署的新手照着抄就能完成一个是有一定经验、想搞明白部署原理和远程访问排障的老手。我会把“为什么这样做”也讲清楚遇到问题不至于抓瞎。1. 部署前的准备工作先把底子摸清楚1.1 硬件要求与系统选择大家最关心的是服务器配置。DeepSeek Harness Web 本身是个前后端应用纯部署双 1 核 2G 内存的机器就能跑起来系统占用就能控制在 300MB 左右。如果你要在本地加载deepseek-r1:1.5b甚至7b这类模型就必须上得了台面的配置模型规模最低内存推荐配置磁盘占用模型依赖1.5B 量化版4GB 内存4核 8G约 3GB7B 量化版8GB 内存8核 16G约 8GB14B 及以上16GB 起步32G20GB 以上这里说句实在话不是你内存大就能硬扛大模型的CPU 推理慢得出奇所以如果你预算有限又刚入门先用 1.5B 或 3B 的量化模型跑通流程之后再考虑升级或接入云端 API。操作系统方面我的建议是Ubuntu 22.04 LTS 或 Debian 12。为什么不用 CentOSCentOS 7 已经停止维护且自带 Python 版本太旧源码部署时你会因为依赖编译失败折腾到怀疑人生。Ubuntu 22.04 自带 Python 3.10正好符合项目依赖要求。如果你正在用国产 Linux 发行版如 openEuler、麒麟命令基本通用只有包管理器可能从apt换成yum或dnf。1.2 依赖环境安装顺序有讲究刚接触 Linux 的人最常见的错误什么都不装就开始git clone然后跑pip install时疯狂报错。正确的依赖安装顺序应该是# 更新系统包索引 sudo apt update sudo apt upgrade -y # 安装基础工具链 sudo apt install -y git curl wget build-essential python3 python3-pip python3-venv nginx # 验证版本 python3 --version # 确认 3.10 以上 git --version这里的build-essential非常重要。项目依赖里有些 Python 包比如pydantic-core、tokenizers在安装时需要编译 C 扩展如果没有 GCC 编译器你会在终端看到一堆error: command gcc failed。我见过太多人卡在这一步以为要装什么特殊的东西其实build-essential就是那个一直默默无闻却拖了整栋楼的“水电工”。1.3 换源操作国内服务器的生存之道如果你用的是国内云服务器或者家里网络访问 GitHub / PyPI 很慢先别急着部署把下面这一步做了能省下你人生中的几小时。pip 换源清华源pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simpleapt 换源Ubuntu 22.04sudo sed -i s//.*archive.ubuntu.com//mirrors.tuna.tsinghua.edu.cng /etc/apt/sources.list sudo apt updateGitee 上有官方仓库镜像GitHub 拉不下来就用 Gitee拉模型用 HuggingFace 太慢就用hf-mirror.com镜像站环境变量配置在后面的模型下载部分会提到。这些操作不影响项目本身但都是真正部署时躲不开的暗坑提前搞定它们。2. 源码拉取与 Python 虚拟环境配置2.1 克隆代码官方仓库与镜像仓库怎么选进到你想放代码的目录我习惯放在/opt或/srv下这样既和家目录分开也能让普通用户只读执行、管理员专门维护sudo mkdir -p /opt/deepseek-harness sudo chown $USER:$USER /opt/deepseek-harness cd /opt/deepseek-harness git clone https://github.com/deepseek-ai/DeepSeek-Harness.git如果 GitHub 超时换成镜像git clone https://gitee.com/mirrors/DeepSeek-Harness.git克隆完成后进入项目目录先别急着装东西看两样东西README.md里的 Python 版本要求、requirements.txt里的依赖清单。为什么不让你们直接看不见就跑了因为有些版本的项目用了pyproject.toml管理依赖直接pip install -r requirements.txt会漏装。2.2 创建虚拟环境隔离依赖这条我必须单独拉出来做重点敲黑板不要用全局 Python 环境直接装依赖。一个常见场景你在服务器上本来跑着一个 Django 项目因为要装 DeepSeek Harness 用pip install升级了一些包回头发现旧项目挂了。这就是依赖冲突的经典“事故”。虚拟环境的作用相当于给每个项目一个独立的文件夹放 Python 库彼此老死不相往来cd DeepSeek-Harness python3 -m venv venv source venv/bin/activate激活后终端提示符前面会出现(venv)说明当前已经进入独立环境。之后使用python、pip都在这个封闭空间内不会污染系统。如果你想退出虚拟环境随时用deactivate。我为什么坚持这一步有一次我帮朋友排查一个报错发现他部署脚本里没有建虚拟环境43 个依赖包散落在系统全局目录里有两个包新旧版本冲突硬是让他删了系统 Python 才解决。虚拟环境五秒钟的事儿别贪图不用激活的一时方便。2.3 安装依赖的实操要点pip install --upgrade pip pip install -r requirements.txt如果你的机器内存小于 2G编译某些包可能直接 OOM内存耗尽被杀这时建议加一个 swap 文件或者手动安装预编译版本# 创建 4G swap解决编译内存不足 sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile安装完成并不是终点验证一下关键依赖能否被正确导入python -c import fastapi, uvicorn, pydantic; print(deps ok)能输出deps ok就说明基础环境没问题后面启动时的报错基本只可能是配置或模型问题。2.4 模型文件与接口配置DeepSeek Harness 有两种使用模型的路径本地加载模型需要下载权重文件接入云端 API比如 DeepSeek OpenPlatform 或 Ollama 中转的本地模型服务如果你是离线局域网环境热搜里有个“deepseek harness 可以在离线局域网使用吗”答案是完全可以就必须走本地加载路线但这需要在部署前先设置好镜像环境变量export HF_ENDPOINThttps://hf-mirror.com python scripts/download_model.py --model deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B下载耗时取决于你的网络1.5B 量化模型大概 1GB 多7B 则要 4GB 以上。如果你用的不是蒸馏版的 R1而是新版的 V3 系列要注意模型格式是否适配一般用 GGUF 或 safetensors 版本。如果是本地 Ollama 接管模型就要先ollama pull deepseek-r1:1.5b然后在 Harness 的.env文件里写清楚MODEL_BASE_URLhttp://127.0.0.1:11434/v1 MODEL_API_KEYollama MODEL_NAMEdeepseek-r1:1.5b配置文件写法不算唯一但核心思想就一点Harness Web 只负责对话管理与前端展示模型推理的活儿全交给了另一个服务。这就像餐厅的菜单和点餐系统分明后厨可能是自己做的也可能是外包的。3. Web 服务启动与本地回环验证3.1 启动 Harness Web 服务环境就绪后下一步就是把服务跑起来。我用这组命令示范一下source /opt/deepseek-harness/DeepSeek-Harness/venv/bin/activate cd /opt/deepseek-harness/DeepSeek-Harness python main.py --host 127.0.0.1 --port 8080看启动参数里用127.0.0.1这是因为我不希望你直接向公网暴露端口而是先在服务器本地验证服务能不能跑起来。访问不到是你配置写错访问到了就说明代码层面没问题。等待一两分钟看到日志输出Uvicorn running on http://127.0.0.1:8080就成功了一大半。新版本可能改用了python -m deepseek_harness.web或者dsh-web入口命令细节以 README 为准但原理一致让 Web 服务监听一个端口提供 HTTP 接口。3.2 本地验证的必要性在服务器上用 curl 验证接口响应这步其实很多人以为没必要直接浏览器访问结果发现打不开又手忙脚乱查原因curl -I http://127.0.0.1:8080正确响应大致类似HTTP/1.1 200 OK。如果返回连接失败基本就是服务没起来先看日志排查journalctl -u deepseek-harness -f # 如果用了 systemd 托管本地验证通过了再走下一步。本地验证的最大作用是隔离网络环境问题与应用代码问题它告诉你问题在代码还是在你家路由器。3.3 用 systemd 托管实现开机自启与后台稳定运行如果你直接在终端跑python main.py一旦 SSH 断开会话服务就被系统杀掉了显然不可控。成熟的 Linux 部署有三大看家本领systemd 服务守护、日志集中管理、进程崩溃自动拉起。我们需要创建一个 systemd 服务文件sudo tee /etc/systemd/system/deepseek-harness.service /dev/null EOF [Unit] DescriptionDeepSeek Harness Web Service Afternetwork.target [Service] Typesimple Userwww-data WorkingDirectory/opt/deepseek-harness/DeepSeek-Harness ExecStart/opt/deepseek-harness/DeepSeek-Harness/venv/bin/python main.py --host 0.0.0.0 --port 8080 Restartalways RestartSec5 EnvironmentHF_ENDPOINThttps://hf-mirror.com [Install] WantedBymulti-user.target EOF sudo systemctl daemon-reload sudo systemctl enable --now deepseek-harness sudo systemctl status deepseek-harness你问为什么绑定地址从127.0.0.1变成0.0.0.0这是为了让它监听所有网卡接口局域网其他机器和公网方向的流量才能进来。设置Userwww-data是安全考虑这个用户权限受限万一应用被攻破也没法掀翻整台服务器绝不要用root跑服务。此时查看日志journalctl -u deepseek-harness -n 50 --no-pager如果你看到Application startup complete意味着服务已经正常托管在系统里了。4. 远程访问实战从局域网到公网4.1 局域网远程访问这一步很简单在你的笔记本电脑或手机上访问http://服务器局域网IP:8080即可。怎么查 IPip addr show | grep inet但这里有个最容易踩的坑云服务器厂商的安全组和Linux 防火墙都可能挡掉入站请求。Ubuntu 默认ufw不启用但云平台的安全组默认只放行 22 端口。所以做完端口监听还不够你要到阿里云/腾讯云控制台的“安全组”里放行 8080 的 TCP 入方向规则如果是本机防火墙就用sudo ufw allow 8080/tcp sudo ufw reload局域网不通时90% 的可能是这两处没有放行。剩下 10% 是路由器开了 AP 隔离。4.2 路由器端口映射家庭公网 IP 方案如果你在家里部署有公网 IP宽带拨号获得的是公网地址不是 10.0.0.x 开头想在外面访问就要在路由器做端口映射登录路由器管理页找到“端口映射”或“虚拟服务器”内部端口填 8080内部 IP 填服务器的局域网 IP例如 192.168.1.100外部端口填 8080 或任意不冲突的端口这样在外面访问http://你家公网IP:8080就能连上。但家用宽带的公网 IP 会变每次重新拨号都会换地址所以通常配合 DDNS 服务比如花生壳、阿里云解析把域名动态绑定到当前公网 IP 上这样你只需要记一个固定的域名就行。4.3 frp 内网穿透没有公网 IP 的优雅解法很多人的家庭宽带实际上没有公网 IPv4或者光猫在深层 NAT 后面路由器映射方案直接失效。此时又想在外网访问怎么办自建内网穿透是通用方案frp 就是最常用的一类典型架构是有一台带公网 IP 的轻量云服务器作为中转家里的服务器通过 frpc 主动连出去把本地 8080 端口“租”到公网 VPS 的某个端口上。frpc 配置示例放在家里服务器上# frpc.toml serverAddr 你的云服务器公网IP serverPort 7000 [[proxies]] name deepseek-harness type tcp localIP 127.0.0.1 localPort 8080 remotePort 8080云服务器上则跑 frps./frps -c frps.toml这样从公网访问http://云服务器IP:8080流量路径就是浏览器 - 云服务器 8080 - frp隧道 - 家里服务器 8080 - Harness Web。反向代理 内网穿透的组合纯内网隔离的多台服务器也可以通过类似方式互相调用。4.4 用 Nginx 反向代理和 HTTPS 加固访问前面直接通过 IP 和端口访问能跑但有两个缺点一是暴露了后端框架特征二是明文传输对话内容可能被中间人截获。一个正规的做法是在前面加一层 Nginx 反向代理server { listen 80; server_name ai.example.com; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; 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; } }Nginx 和 Harness Web 之间的通讯走127.0.0.1回环地址意味着公网流量永远打不到应用端口本身。之后再用 certbot 签免费 TLS 证书sudo apt install -y certbot python3-certbot-nginx sudo certbot --nginx -d ai.example.com到此为止你拥有了一个带 HTTPS 加密的域名访问。很多人会关心同时要上一个安全认证尤其是有多人在线用的场景。DeepSeek Harness 本身可能没有内置的用户鉴权此时你在 Nginx 层再加一层 Basic Auth 是最省事的做法sudo apt install -y apache2-utils sudo htpasswd -c /etc/nginx/.htpasswd your_username然后在 Nginx server 块里加上auth_basic Restricted Access; auth_basic_user_file /etc/nginx/.htpasswd;这样即使 IP 被人扫出来没有用户名密码的人连对话页面都看不到。5. 常见问题与排查技巧实录我把自己在部署这个项目以及其他类似源码部署项目时踩过的坑集中整理一下做成一张速查表你遇到报错直接对照着来查。常见现象可能原因排查命令/操作pip install极慢或超时PyPI 默认源在境外pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple依赖编译报错gcc failed缺少build-essentialsudo apt install -y build-essential服务启动即崩溃Address already in use8080 端口被占用sudo lsof -i:8080找到进程换端口或杀进程Web 页面打开模型不回复Harness 无法连接 Ollama 或 API先curl http://127.0.0.1:11434/v1/models验证 Ollama检查.env的MODEL_BASE_URL模型下载到一半失败HuggingFace 国内连接不稳定设置export HF_ENDPOINThttps://hf-mirror.com局域网能访问但外网不行安全组/防火墙/路由器未放行依次检查三个点安全组入方向、ufw状态、路由器端口映射域名访问一直转圈HTTPS 证书或 Nginx 配置问题sudo nginx -t验证配置sudo systemctl status nginx看服务状态再挑三个最有价值的细节展开讲一下。细节一Ollama 连接超时。Harness 接到你的消息后会向MODEL_BASE_URL发请求。Ollama 默认监听127.0.0.1:11434如果 Harness 跑在 Docker 或别的容器里127.0.0.1指向的是容器自身不是宿主机。解决办法宿主机执行ollama serve --host 0.0.0.0并把 Harness 地址改成http://宿主机IP:11434/v1。细节二访问一大段对话后内存爆掉。这个不是 Bug而是模型上下文变长导致显存/内存占用线性上升。解决方案在 Harness 配置里限制最大上下文长度或使用num_ctx参数。部署时只图能跑通不考虑资源上限是很多新手把服务器搞死的原因。细节三SSH 一关服务就断。这个很典型说明你还在用前台方式跑服务。按我前面说的 systemd 托管或者用tmux/screen挂后台也行只是 systemd 更标准。热搜里那个“linux 让后台运行指令 不因界面退出而退出”问的就是这个直接给结论nohup python main.py 能应应急但不建议长期这样搞看日志、自动重启都不方便。最后再分享一个小技巧。如果你在部署时想临时用浏览器测试但服务器在无头环境没有桌面里别干瞪眼干着急用 SSH 本地端口转发最省事ssh -L 8080:127.0.0.1:8080 user你的服务器IP然后在你本地电脑访问http://127.0.0.1:8080流量是走 SSH 加密隧道转发的。当然这只是调试不是长期方案但它的好处是绑定在127.0.0.1的安全姿势不用改。按照我上面这套流程一台全新的 Ubuntu 服务器从装系统到跑起来大概需要半小时到一个小时其中大把时间花在等待依赖安装和模型下载上。部署完成之后你再去调整外部访问方式、加 HTTPS、接 Ollama 或接入更多模型都是水到渠成的小事了。如果部署过程中哪一步日志报错看不懂优先把完整报错贴给 AI 问但注意把日志中可能暴露的密钥信息先处理掉。希望这篇教程能帮你少踩点坑把自己模型服务稳定跑起来。 
长河君 · 2026/10/8 20:35:21 · 阅读 1.2k Linux源码部署DeepSeek Harness Web保姆级教程
我们直接进入主题讲讲在 Linux 服务器上从零开始源码部署 DeepSeek Harness 的 Web 版。我默认你已经有一台能联网、能 SSH 登录的 Linux 机器无论是阿里云、腾讯云这类云主机还是家里的老电脑、树莓派本文的方法都适用。就像标题说的这是一个保姆级教程从系统准备到最终远程访问我会把每一步的命令、原理和踩坑点都交代清楚。先说清楚 DeepSeek Harness Web 到底是个什么。它本质上是一个把 DeepSeek 系列模型以及其他兼容 OpenAI 接口的模型封装成带 Web 界面的私有部署工具核心价值在于用浏览器对话的方式调模型能力不用懂后端代码也不用装桌面客户端。对于想在团队内共享、远程调用、或者嵌入到自己的小项目里的场景这个 Web 版非常方便。整个过程走完你会得到一个能运行在 Linux 上、可通过 IP 或域名远程访问的 Web 服务。这篇教程适合谁一个是刚接触 Linux 部署的新手照着抄就能完成一个是有一定经验、想搞明白部署原理和远程访问排障的老手。我会把“为什么这样做”也讲清楚遇到问题不至于抓瞎。1. 部署前的准备工作先把底子摸清楚1.1 硬件要求与系统选择大家最关心的是服务器配置。DeepSeek Harness Web 本身是个前后端应用纯部署双 1 核 2G 内存的机器就能跑起来系统占用就能控制在 300MB 左右。如果你要在本地加载deepseek-r1:1.5b甚至7b这类模型就必须上得了台面的配置模型规模最低内存推荐配置磁盘占用模型依赖1.5B 量化版4GB 内存4核 8G约 3GB7B 量化版8GB 内存8核 16G约 8GB14B 及以上16GB 起步32G20GB 以上这里说句实在话不是你内存大就能硬扛大模型的CPU 推理慢得出奇所以如果你预算有限又刚入门先用 1.5B 或 3B 的量化模型跑通流程之后再考虑升级或接入云端 API。操作系统方面我的建议是Ubuntu 22.04 LTS 或 Debian 12。为什么不用 CentOSCentOS 7 已经停止维护且自带 Python 版本太旧源码部署时你会因为依赖编译失败折腾到怀疑人生。Ubuntu 22.04 自带 Python 3.10正好符合项目依赖要求。如果你正在用国产 Linux 发行版如 openEuler、麒麟命令基本通用只有包管理器可能从apt换成yum或dnf。1.2 依赖环境安装顺序有讲究刚接触 Linux 的人最常见的错误什么都不装就开始git clone然后跑pip install时疯狂报错。正确的依赖安装顺序应该是# 更新系统包索引 sudo apt update sudo apt upgrade -y # 安装基础工具链 sudo apt install -y git curl wget build-essential python3 python3-pip python3-venv nginx # 验证版本 python3 --version # 确认 3.10 以上 git --version这里的build-essential非常重要。项目依赖里有些 Python 包比如pydantic-core、tokenizers在安装时需要编译 C 扩展如果没有 GCC 编译器你会在终端看到一堆error: command gcc failed。我见过太多人卡在这一步以为要装什么特殊的东西其实build-essential就是那个一直默默无闻却拖了整栋楼的“水电工”。1.3 换源操作国内服务器的生存之道如果你用的是国内云服务器或者家里网络访问 GitHub / PyPI 很慢先别急着部署把下面这一步做了能省下你人生中的几小时。pip 换源清华源pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simpleapt 换源Ubuntu 22.04sudo sed -i s//.*archive.ubuntu.com//mirrors.tuna.tsinghua.edu.cng /etc/apt/sources.list sudo apt updateGitee 上有官方仓库镜像GitHub 拉不下来就用 Gitee拉模型用 HuggingFace 太慢就用hf-mirror.com镜像站环境变量配置在后面的模型下载部分会提到。这些操作不影响项目本身但都是真正部署时躲不开的暗坑提前搞定它们。2. 源码拉取与 Python 虚拟环境配置2.1 克隆代码官方仓库与镜像仓库怎么选进到你想放代码的目录我习惯放在/opt或/srv下这样既和家目录分开也能让普通用户只读执行、管理员专门维护sudo mkdir -p /opt/deepseek-harness sudo chown $USER:$USER /opt/deepseek-harness cd /opt/deepseek-harness git clone https://github.com/deepseek-ai/DeepSeek-Harness.git如果 GitHub 超时换成镜像git clone https://gitee.com/mirrors/DeepSeek-Harness.git克隆完成后进入项目目录先别急着装东西看两样东西README.md里的 Python 版本要求、requirements.txt里的依赖清单。为什么不让你们直接看不见就跑了因为有些版本的项目用了pyproject.toml管理依赖直接pip install -r requirements.txt会漏装。2.2 创建虚拟环境隔离依赖这条我必须单独拉出来做重点敲黑板不要用全局 Python 环境直接装依赖。一个常见场景你在服务器上本来跑着一个 Django 项目因为要装 DeepSeek Harness 用pip install升级了一些包回头发现旧项目挂了。这就是依赖冲突的经典“事故”。虚拟环境的作用相当于给每个项目一个独立的文件夹放 Python 库彼此老死不相往来cd DeepSeek-Harness python3 -m venv venv source venv/bin/activate激活后终端提示符前面会出现(venv)说明当前已经进入独立环境。之后使用python、pip都在这个封闭空间内不会污染系统。如果你想退出虚拟环境随时用deactivate。我为什么坚持这一步有一次我帮朋友排查一个报错发现他部署脚本里没有建虚拟环境43 个依赖包散落在系统全局目录里有两个包新旧版本冲突硬是让他删了系统 Python 才解决。虚拟环境五秒钟的事儿别贪图不用激活的一时方便。2.3 安装依赖的实操要点pip install --upgrade pip pip install -r requirements.txt如果你的机器内存小于 2G编译某些包可能直接 OOM内存耗尽被杀这时建议加一个 swap 文件或者手动安装预编译版本# 创建 4G swap解决编译内存不足 sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile安装完成并不是终点验证一下关键依赖能否被正确导入python -c import fastapi, uvicorn, pydantic; print(deps ok)能输出deps ok就说明基础环境没问题后面启动时的报错基本只可能是配置或模型问题。2.4 模型文件与接口配置DeepSeek Harness 有两种使用模型的路径本地加载模型需要下载权重文件接入云端 API比如 DeepSeek OpenPlatform 或 Ollama 中转的本地模型服务如果你是离线局域网环境热搜里有个“deepseek harness 可以在离线局域网使用吗”答案是完全可以就必须走本地加载路线但这需要在部署前先设置好镜像环境变量export HF_ENDPOINThttps://hf-mirror.com python scripts/download_model.py --model deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B下载耗时取决于你的网络1.5B 量化模型大概 1GB 多7B 则要 4GB 以上。如果你用的不是蒸馏版的 R1而是新版的 V3 系列要注意模型格式是否适配一般用 GGUF 或 safetensors 版本。如果是本地 Ollama 接管模型就要先ollama pull deepseek-r1:1.5b然后在 Harness 的.env文件里写清楚MODEL_BASE_URLhttp://127.0.0.1:11434/v1 MODEL_API_KEYollama MODEL_NAMEdeepseek-r1:1.5b配置文件写法不算唯一但核心思想就一点Harness Web 只负责对话管理与前端展示模型推理的活儿全交给了另一个服务。这就像餐厅的菜单和点餐系统分明后厨可能是自己做的也可能是外包的。3. Web 服务启动与本地回环验证3.1 启动 Harness Web 服务环境就绪后下一步就是把服务跑起来。我用这组命令示范一下source /opt/deepseek-harness/DeepSeek-Harness/venv/bin/activate cd /opt/deepseek-harness/DeepSeek-Harness python main.py --host 127.0.0.1 --port 8080看启动参数里用127.0.0.1这是因为我不希望你直接向公网暴露端口而是先在服务器本地验证服务能不能跑起来。访问不到是你配置写错访问到了就说明代码层面没问题。等待一两分钟看到日志输出Uvicorn running on http://127.0.0.1:8080就成功了一大半。新版本可能改用了python -m deepseek_harness.web或者dsh-web入口命令细节以 README 为准但原理一致让 Web 服务监听一个端口提供 HTTP 接口。3.2 本地验证的必要性在服务器上用 curl 验证接口响应这步其实很多人以为没必要直接浏览器访问结果发现打不开又手忙脚乱查原因curl -I http://127.0.0.1:8080正确响应大致类似HTTP/1.1 200 OK。如果返回连接失败基本就是服务没起来先看日志排查journalctl -u deepseek-harness -f # 如果用了 systemd 托管本地验证通过了再走下一步。本地验证的最大作用是隔离网络环境问题与应用代码问题它告诉你问题在代码还是在你家路由器。3.3 用 systemd 托管实现开机自启与后台稳定运行如果你直接在终端跑python main.py一旦 SSH 断开会话服务就被系统杀掉了显然不可控。成熟的 Linux 部署有三大看家本领systemd 服务守护、日志集中管理、进程崩溃自动拉起。我们需要创建一个 systemd 服务文件sudo tee /etc/systemd/system/deepseek-harness.service /dev/null EOF [Unit] DescriptionDeepSeek Harness Web Service Afternetwork.target [Service] Typesimple Userwww-data WorkingDirectory/opt/deepseek-harness/DeepSeek-Harness ExecStart/opt/deepseek-harness/DeepSeek-Harness/venv/bin/python main.py --host 0.0.0.0 --port 8080 Restartalways RestartSec5 EnvironmentHF_ENDPOINThttps://hf-mirror.com [Install] WantedBymulti-user.target EOF sudo systemctl daemon-reload sudo systemctl enable --now deepseek-harness sudo systemctl status deepseek-harness你问为什么绑定地址从127.0.0.1变成0.0.0.0这是为了让它监听所有网卡接口局域网其他机器和公网方向的流量才能进来。设置Userwww-data是安全考虑这个用户权限受限万一应用被攻破也没法掀翻整台服务器绝不要用root跑服务。此时查看日志journalctl -u deepseek-harness -n 50 --no-pager如果你看到Application startup complete意味着服务已经正常托管在系统里了。4. 远程访问实战从局域网到公网4.1 局域网远程访问这一步很简单在你的笔记本电脑或手机上访问http://服务器局域网IP:8080即可。怎么查 IPip addr show | grep inet但这里有个最容易踩的坑云服务器厂商的安全组和Linux 防火墙都可能挡掉入站请求。Ubuntu 默认ufw不启用但云平台的安全组默认只放行 22 端口。所以做完端口监听还不够你要到阿里云/腾讯云控制台的“安全组”里放行 8080 的 TCP 入方向规则如果是本机防火墙就用sudo ufw allow 8080/tcp sudo ufw reload局域网不通时90% 的可能是这两处没有放行。剩下 10% 是路由器开了 AP 隔离。4.2 路由器端口映射家庭公网 IP 方案如果你在家里部署有公网 IP宽带拨号获得的是公网地址不是 10.0.0.x 开头想在外面访问就要在路由器做端口映射登录路由器管理页找到“端口映射”或“虚拟服务器”内部端口填 8080内部 IP 填服务器的局域网 IP例如 192.168.1.100外部端口填 8080 或任意不冲突的端口这样在外面访问http://你家公网IP:8080就能连上。但家用宽带的公网 IP 会变每次重新拨号都会换地址所以通常配合 DDNS 服务比如花生壳、阿里云解析把域名动态绑定到当前公网 IP 上这样你只需要记一个固定的域名就行。4.3 frp 内网穿透没有公网 IP 的优雅解法很多人的家庭宽带实际上没有公网 IPv4或者光猫在深层 NAT 后面路由器映射方案直接失效。此时又想在外网访问怎么办自建内网穿透是通用方案frp 就是最常用的一类典型架构是有一台带公网 IP 的轻量云服务器作为中转家里的服务器通过 frpc 主动连出去把本地 8080 端口“租”到公网 VPS 的某个端口上。frpc 配置示例放在家里服务器上# frpc.toml serverAddr 你的云服务器公网IP serverPort 7000 [[proxies]] name deepseek-harness type tcp localIP 127.0.0.1 localPort 8080 remotePort 8080云服务器上则跑 frps./frps -c frps.toml这样从公网访问http://云服务器IP:8080流量路径就是浏览器 - 云服务器 8080 - frp隧道 - 家里服务器 8080 - Harness Web。反向代理 内网穿透的组合纯内网隔离的多台服务器也可以通过类似方式互相调用。4.4 用 Nginx 反向代理和 HTTPS 加固访问前面直接通过 IP 和端口访问能跑但有两个缺点一是暴露了后端框架特征二是明文传输对话内容可能被中间人截获。一个正规的做法是在前面加一层 Nginx 反向代理server { listen 80; server_name ai.example.com; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; 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; } }Nginx 和 Harness Web 之间的通讯走127.0.0.1回环地址意味着公网流量永远打不到应用端口本身。之后再用 certbot 签免费 TLS 证书sudo apt install -y certbot python3-certbot-nginx sudo certbot --nginx -d ai.example.com到此为止你拥有了一个带 HTTPS 加密的域名访问。很多人会关心同时要上一个安全认证尤其是有多人在线用的场景。DeepSeek Harness 本身可能没有内置的用户鉴权此时你在 Nginx 层再加一层 Basic Auth 是最省事的做法sudo apt install -y apache2-utils sudo htpasswd -c /etc/nginx/.htpasswd your_username然后在 Nginx server 块里加上auth_basic Restricted Access; auth_basic_user_file /etc/nginx/.htpasswd;这样即使 IP 被人扫出来没有用户名密码的人连对话页面都看不到。5. 常见问题与排查技巧实录我把自己在部署这个项目以及其他类似源码部署项目时踩过的坑集中整理一下做成一张速查表你遇到报错直接对照着来查。常见现象可能原因排查命令/操作pip install极慢或超时PyPI 默认源在境外pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple依赖编译报错gcc failed缺少build-essentialsudo apt install -y build-essential服务启动即崩溃Address already in use8080 端口被占用sudo lsof -i:8080找到进程换端口或杀进程Web 页面打开模型不回复Harness 无法连接 Ollama 或 API先curl http://127.0.0.1:11434/v1/models验证 Ollama检查.env的MODEL_BASE_URL模型下载到一半失败HuggingFace 国内连接不稳定设置export HF_ENDPOINThttps://hf-mirror.com局域网能访问但外网不行安全组/防火墙/路由器未放行依次检查三个点安全组入方向、ufw状态、路由器端口映射域名访问一直转圈HTTPS 证书或 Nginx 配置问题sudo nginx -t验证配置sudo systemctl status nginx看服务状态再挑三个最有价值的细节展开讲一下。细节一Ollama 连接超时。Harness 接到你的消息后会向MODEL_BASE_URL发请求。Ollama 默认监听127.0.0.1:11434如果 Harness 跑在 Docker 或别的容器里127.0.0.1指向的是容器自身不是宿主机。解决办法宿主机执行ollama serve --host 0.0.0.0并把 Harness 地址改成http://宿主机IP:11434/v1。细节二访问一大段对话后内存爆掉。这个不是 Bug而是模型上下文变长导致显存/内存占用线性上升。解决方案在 Harness 配置里限制最大上下文长度或使用num_ctx参数。部署时只图能跑通不考虑资源上限是很多新手把服务器搞死的原因。细节三SSH 一关服务就断。这个很典型说明你还在用前台方式跑服务。按我前面说的 systemd 托管或者用tmux/screen挂后台也行只是 systemd 更标准。热搜里那个“linux 让后台运行指令 不因界面退出而退出”问的就是这个直接给结论nohup python main.py 能应应急但不建议长期这样搞看日志、自动重启都不方便。最后再分享一个小技巧。如果你在部署时想临时用浏览器测试但服务器在无头环境没有桌面里别干瞪眼干着急用 SSH 本地端口转发最省事ssh -L 8080:127.0.0.1:8080 user你的服务器IP然后在你本地电脑访问http://127.0.0.1:8080流量是走 SSH 加密隧道转发的。当然这只是调试不是长期方案但它的好处是绑定在127.0.0.1的安全姿势不用改。按照我上面这套流程一台全新的 Ubuntu 服务器从装系统到跑起来大概需要半小时到一个小时其中大把时间花在等待依赖安装和模型下载上。部署完成之后你再去调整外部访问方式、加 HTTPS、接 Ollama 或接入更多模型都是水到渠成的小事了。如果部署过程中哪一步日志报错看不懂优先把完整报错贴给 AI 问但注意把日志中可能暴露的密钥信息先处理掉。希望这篇教程能帮你少踩点坑把自己模型服务稳定跑起来。