这套“Linux 服务器源码部署 DeepSeek Harness Web”的流程我前后在几台不同配置的服务器上折腾过从最开始的一脸懵到现在闭着眼睛能把环境搭起来中间踩过的坑不算少。这篇就把整个部署链路从头到尾捋一遍从拿到一台干净服务器开始一直到外网能正常访问 Web 界面全程不绕弯子尽量做到每一步你都能照着敲。先说 DeepSeek Harness Web 是什么。简单讲它是一个自托管的 Web 控制台用来统一管理 DeepSeek 模型的对话请求、API 密钥、上下文参数这些核心配置相当于给你常用的模型能力套了一个可视化操作界面。相比直接在终端里调接口它更适合把模型能力开放给团队协作、日常演示或者自己多端使用。整篇教程不需要你有很深的运维底子但至少要对 Linux 基本命令不陌生知道cd、ls、vim是干嘛的就行。1. 项目部署思路拆解先弄明白要做什么1.1 这个项目到底解决什么问题很多人拿到一个开源项目第一步就是git clone然后开始无脑装依赖结果装到一半发现缺这个缺那个最后系统一片混乱。这里我建议先花五分钟想想这个项目跑起来需要哪几个核心部件针对 DeepSeek Harness Web 这类前后端分离的 Web 应用核心无非是三层后端服务处理 API 转发、密钥管理、对话历史存储一般用 Python 系的 Web 框架居多常见的是 FastAPI 或者 Flask。前端页面提供浏览器里的操作界面Vue 或 React 写的单页应用构建后是一堆静态文件。数据存储保存配置信息、对话记录通常用 SQLite 起步人多了再换 PostgreSQL。搞清楚这三点之后整个部署思路就清晰了先把后端跑起来再把前端构建产物让后端能访问到最后用 Nginx 做统一入口把流量转发过去顺便把 HTTPS 加上。1.2 为什么选择源码部署而不是直接跑 Docker我知道肯定会有人问官方不是提供 Docker 镜像吗直接docker run不香吗香但不适合所有人。源码部署看起来步骤多可它有几点是 Docker 方案给不了的可定制性强。这类 Harness 工具经常需要改配置、加插件源码部署可以直接改代码目录里的文件改完立即生效不用重新构建镜像。资源占用更低。一台 2G 内存的小机器跑 Docker 容器要预留系统开销源码部署省掉一层尤其对于学生机和低配云主机来说差别挺明显。排查问题更直接。服务起不来源码部署可以直接看进程输出、翻日志、打断点Docker 里查问题得进容器多一层周转。学习价值完全不同。源码部署一遍你对整个项目的依赖关系、启动流程、配置文件结构会有很直观的理解这是运维技能的一部分。如果你只是临时体验一把那用 Docker 没问题。但如果你想长期用、想改造成自己的工具源码部署才是正经路子。本教程就按源码部署讲。2. 环境准备从一台干净服务器开始2.1 服务器选型与系统要求我用的是 Ubuntu 22.04 LTS这是目前最稳妥的服务器系统选择软件源里的包版本都比较新官方文档里的命令也基本以 Debian 系为准。如果你用的是 CentOS 或者 Rocky Linux命令要对应换成yum/dnf组的思路完全一样。硬件配置方面我给个最低参考项目最低要求推荐配置CPU1 核2 核及以上内存1GB2GB 以上磁盘10GB20GB SSD操作系统Ubuntu 20.04Ubuntu 22.04 LTS这个项目本身不重不会像跑大模型推理那样吃显存它的作用是管理模型 API 的调用真正的计算压力在 DeepSeek 服务端那边。所以 1G 内存的小机器也能跑只是编译前端依赖的时候会有点紧张我建议至少 2G省得 npm 构建到一半被 OOM 干掉。还有一个必须确认的服务器的 Python 和 Node 版本。DeepSeek Harness Web 这类新项目通常会要求 Python 3.10 和 Node.js 18。python3 --version node --version npm --version如果版本太老先升级。这也是我第一次部署时栽过的跟头机器自带的 Python 是 3.8结果pip install一堆包直接报版本不满足排查了半天才发现是解释器版本的问题。2.2 基础依赖安装先把编译工具链备齐拿到一台新服务器先别急着拉代码先把系统基础工具装好。很多依赖包在安装过程中需要编译缺了编译工具链会报各种奇怪的错比方说gcc: command not found或者No module named wheel。sudo apt update sudo apt upgrade -y sudo apt install -y build-essential git curl wget python3-dev python3-venv python3-pip libssl-dev libffi-dev nginx ufw解释一下这几个包为什么必须build-essential包含 gcc/g 和 make编译 Python C 扩展的必需品。python3-dev提供 Python 头文件某些 pip 包比如uvloop、cryptography需要它才能编译安装。libssl-dev和libffi-dev这是两个很容易被忽略的依赖。cryptography、OpenSSL绑定、部分数据库驱动都依赖它们缺了就是在 pip 安装时报openssl/opensslv.h: No such file or directory。python3-venv创建虚拟环境的工具后面要用。nginx反向代理服务器远程访问的关键一环。既然要远程访问直接在这里装好后面少一次安装。ufw防火墙管理工具Ubuntu 自带的用起来简单。装完之后建议顺手重启一次或者至少刷新一下系统环境避免 PATH 不生效。3. 源码获取与应用配置把项目跑起来的第一步3.1 拉取源码并看懂目录结构环境就绪之后就可以拉代码了。先建一个普通用户来干这活别用 root 跑项目服务这是安全底线。我习惯创建一个叫harness的用户专门跑这个应用。sudo useradd -m -s /bin/bash harness sudo usermod -aG sudo harness su - harness然后进入用户目录拉取代码cd ~ git clone https://github.com/your-project/deepseek-harness-web.git cd deepseek-harness-web拉下来之后先别急着操作花两分钟看看目录结构。一个标准的这类项目一般会有这些目录目录/文件作用backend/后端 Python 代码frontend/前端源码requirements.txtPython 依赖清单.env.example环境变量模板package.json前端构建配置docs/官方文档这一步相当于你先拿到地图再出发。很多小白拉完代码就往里冲最后根本不知道哪个文件是配置文件、哪个命令是启动入口全靠猜。我个人的习惯是先把.env.example打开看一眼把README.md的 Quick Start 部分读一遍再动手。这一步能省掉后面 80% 的困惑。3.2 后端环境虚拟环境与 Python 依赖安装后端是 FastAPI 写的所以需要单独建一个 Python 虚拟环境。为什么要用虚拟环境而不是直接用系统的 Python因为系统环境是干净的一旦装坏了全局的 Python 包可能会影响系统自带工具。虚拟环境把项目依赖隔离在自己的小天地里随便折腾都不会影响系统。cd ~/deepseek-harness-web/backend python3 -m venv venv source venv/bin/activate激活之后命令行前面会出现(venv)的标识说明已经在虚拟环境里了。接着安装依赖pip install --upgrade pip pip install -r requirements.txt这个过程可能会有些慢因为像pydantic、uvicorn这些包需要下载安装。如果你在网络环境一般的情况下安装失败可以换成国内镜像源pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple这里要注意不要为了省事直接用pip install -r requirements.txt加--system-site-packages也不要绕过虚拟环境直接往系统里装后面维护会很难受。3.3 配置文件与数据库初始化依赖装完之后就该配置环境变量了。这个项目通过.env文件来管理配置模板文件是.env.example。cp .env.example .env vim .env打开这个文件重点看几个核心配置项# 服务监听端口 PORT8000 # 数据库连接 DATABASE_URLsqlite:///./data/app.db # 模型 API 密钥 DEEPSEEK_API_KEY你的密钥 # 会话密钥用于加密 Cookie SECRET_KEY一串随机字符 # Web 服务基础地址 BASE_URLhttp://localhost:8000密钥建议用openssl rand -hex 32生成别用你随手敲的一段字符串。数据库这块如果是单机自用SQLite 完全够用一个文件搞定备份也简单。如果后面要给一个团队用建议换成 PostgreSQL连接串变成DATABASE_URLpostgresql://harness:passwordlocalhost:5432/harness_db配好.env之后初始化数据库。不同的项目命令不一样如果是上面提到的 FastAPI Alembic 的组合一般是alembic upgrade head如果是 Django 项目则是python manage.py migrate跑完这条命令data/目录下会出现数据库文件。这一步的作用是让项目代码里定义的数据表真正落到数据库里没有这张“表结构”服务启动会报错后端也无法保存任何数据。4. 前端构建与本地联调前后端打通4.1 Node.js 环境与前端依赖安装后端准备就绪现在处理前端。前端源码在frontend/目录下这是一个标准的 Vite Vue/React 项目。首先确保 Node.js 版本在 18 以上否则构建时会报错。cd ~/deepseek-harness-web/frontend npm installnpm install跑完后项目会多出一个node_modules目录里面全是依赖包这个目录很大不用关心它是什么它只是构建工具的“材料库”。然后执行构建npm run build构建完成后frontend/dist目录下会出现一堆静态文件包括index.html和assets/目录。这些文件就是浏览器里看到的界面。4.2 本地启动与自测后端和前端都准备好了现在先把服务跑起来看看能不能在本机访问。回到后端目录用 uvicorn 启动开发模式cd ~/deepseek-harness-web/backend source venv/bin/activate python -m uvicorn app.main:app --host 127.0.0.1 --port 8000启动成功后终端会显示类似Uvicorn running on http://127.0.0.1:8000的信息。在服务器本机测试一下curl -I http://127.0.0.1:8000如果返回 HTTP/1.1 200 OK说明后端已经活了。再打开另一个 SSH 窗口试一下前端资源能否正常加载。这类项目通常会在后端里直接挂载前端静态文件所以如果一切正常直接curl http://127.0.0.1:8000应该能看到 HTML 页面。提示这里有一个很容易踩的坑。启动时--host 127.0.0.1只能本机访问如果你想立刻从自己电脑浏览器访问可以先用--host 0.0.0.0 --port 8000临时试一下。但生产环境不要直接暴露 8000 端口后面我会用 Nginx 接一个更安全的入口。5. 生产化部署让服务稳定跑在后台5.1 为什么要用 systemd 管理开发模式下服务是挂在当前 SSH 会话里的一关终端服务就死了这在生产环境显然不能用。Linux 下管理后台服务最标准的方式是 systemd。它的作用相当于给你这个服务装了一个“自动管家”开机自动启动、崩溃自动重启、日志集中管理。5.2 编写 systemd 服务单元文件先停掉刚才手动启动的 uvicornCtrl C然后创建一个服务配置文件sudo vim /etc/systemd/system/deepseek-harness.service内容如下[Unit] DescriptionDeepSeek Harness Web Service Afternetwork.target [Service] Typesimple Userharness Groupharness WorkingDirectory/home/harness/deepseek-harness-web/backend EnvironmentFile/home/harness/deepseek-harness-web/backend/.env ExecStart/home/harness/deepseek-harness-web/backend/venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --workers 2 Restartalways RestartSec3 [Install] WantedBymulti-user.target这里有几个细节需要展开Userharness很关键。用普通用户跑服务即使程序被攻击攻击者拿到的权限也有限。如果图省事用 root相当于把自家大门钥匙挂在门口。EnvironmentFile的作用是让 systemd 启动服务时自动读取.env文件里的环境变量。ExecStart里用的是虚拟环境里的 Python 绝对路径不要用python因为 systemd 启动时不一定加载了你的虚拟环境。--workers 2表示启动两个 worker 进程够用且稳定。1G 内存的小机器建议改成 1内存充足 2-3 没问题。设置好之后让 systemd 重新识别配置并启动服务sudo systemctl daemon-reload sudo systemctl enable deepseek-harness sudo systemctl start deepseek-harness sudo systemctl status deepseek-harness看到active (running)就说明服务被系统接管了。之后不管怎么关终端服务都会在后台跑着服务器重启也会自动拉起来。查看日志随时用这个命令journalctl -u deepseek-harness -f这里记个教训我最初部署时没加Restartalways结果有一次后端进程因为内存不足被系统杀掉整个服务瘫了一晚上没人发现。加了这个参数之后就算进程异常退出三秒后就会自动拉起来这才是真正能让你睡安稳觉的配置。6. 远程访问与安全加固从只能本地到外网可用6.1 防火墙与安全组放行服务已经跑在 127.0.0.1:8000 上了但现在外网还访问不到。要开放访问需要做两层放行。第一层是系统防火墙 UFW。放行 SSH、HTTP、HTTPSsudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable第二层是云服务器的安全组。去你买服务器的云控制台找到“安全组”或“防火墙”配置放行 80 和 443 端口。这一步很多人会忽略结果在服务器里折腾半天外网就是死活不通一查是安全组没放行。注意不要为了省事把 8000 端口的入站规则也放出去。生产环境应该用 Nginx 监听 80/443再由 Nginx 转发到内部 8000这是惯例做法。直接把应用端口暴露出去既不利于日志集中管理也少了一道防护。6.2 Nginx 反向代理与 WebSocket 支持现在开始配置 Nginx。这里的重要作用Nginx 监听公网 80/443 端口接收到请求后转发给后端的 127.0.0.1:8000。同时 Nginx 还负责处理前端静态文件转发因为这个项目前端和后端都在同一个服务里配置可以保持简洁。创建站点配置sudo vim /etc/nginx/sites-available/deepseek-harness内容如下server { listen 80; server_name your-domain.com; # 如果没有域名用服务器公网 IP location / { proxy_pass http://127.0.0.1:8000; 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; # WebSocket 支持这个必须加上 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; } # 静态资源缓存策略 location /assets/ { proxy_pass http://127.0.0.1:8000; proxy_cache_valid 200 30d; add_header Cache-Control public, max-age2592000; } }启用站点并重载 Nginxsudo ln -s /etc/nginx/sites-available/deepseek-harness /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginxnginx -t是检查配置语法没问题再reload把改动加载进去。这里为什么要强调 WebSocket 支持因为这类 Harness 工具的对话功能很多都把实时流式输出建立在 WebSocket 或 SSE 上。如果 Nginx 配置里没有那两行Upgrade和Connection你会发现页面能打开但一问会话框就卡住或者消息发不出去体验很诡异。配置完成后直接用浏览器访问你的服务器 IP 或域名就能看到登录页面了。如果显示不出来先确认http://127.0.0.1:8000在服务器本机 curl 是否正常再顺 Nginx 一层层往外排查。6.3 HTTPS 证书与安全加固HTTP 访问通了但这还不够。如果这个工具要配置 DeepSeek API 密钥那么 API 密钥会在你每次登录和操作时经过浏览器与服务器之间的传输。没有 HTTPS这些信息就等于明文在网络上跑太危险了。如果有域名用 Lets Encrypt 申请免费证书就很方便sudo apt install -y certbot python3-certbot-nginx sudo certbot --nginx -d your-domain.comCertbot 会自动帮你改 Nginx 配置、签发证书、配置自动续期。整个流程基本上是交互式的跟着提示走就行。如果没有域名只有公网 IP那很多 CA 机构不提供纯 IP 证书这时候有两个选择接受 HTTP IP 访问但只在受信任网络内使用。用自签名证书走 HTTPS浏览器会提示不受信任需要自己手动信任。我的建议是如果只是个人短暂使用用 HTTP IP 先顶着问题不大但只要你打算长期使用、并在里面填真实 API Key域名 Lets Encrypt 的 HTTPS 就是底线配置。再补几个安全加固的操作这些是顺手就能做的# 禁用 root 密码登录 sudo vim /etc/ssh/sshd_config # 设置 PermitRootLogin no # 设置 PasswordAuthentication no前提是你已经配好 SSH 密钥 sudo systemctl restart sshd # 安装 fail2ban 防暴力破解 sudo apt install -y fail2ban sudo systemctl enable fail2ban sudo systemctl start fail2ban另外建议给这个 Web 应用本身加一层访问控制。如果项目自带登录功能那就把初始管理员密码立刻改掉如果不带前端套一层 Nginx Basic Auth 是成本最低的方案sudo apt install -y apache2-utils sudo htpasswd -c /etc/nginx/.htpasswd admin然后在 Nginx 的站点配置里加两行location / { auth_basic Restricted Access; auth_basic_user_file /etc/nginx/.htpasswd; ... }这样就算应用本身有漏洞外面也还有一层密码保护。7. 常见问题排查与避坑实录7.1 依赖安装阶段的高频报错报错error: command gcc failed with exit status 1这是最典型的编译错误原因基本都是缺系统依赖。先执行sudo apt install -y build-essential python3-dev libssl-dev libffi-dev再重新安装。如果还报错看错误信息里具体缺哪个头文件缺啥装啥。绝大多数情况是libssl-dev少了装完立刻好。报错ModuleNotFoundError: No module named xxx这说明依赖装得不全。先pip install -r requirements.txt重新装一遍确认没有跳过某些包。如果用了镜像源有可能某个包没成功拉到切换回默认源再试一次。npm install 碰到 ETIMEDOUT网络环境波动导致的。可以直接用靠谱的 npm 镜像源npm config set registry https://registry.npmmirror.com npm install装完后npm run build如果构建过程中出现内存溢出heap out of memory把 Node 内存限制调大NODE_OPTIONS--max-old-space-size2048 npm run build7.2 服务启动与端口问题提示Address already in use说明 8000 端口已经被占用了。端口被占用先看是谁占的sudo lsof -i :8000如果是残留的 uvicorn 进程直接sudo kill -9 pid。生产环境不建议手动 kill改掉服务配置重启更干净。外网无法访问但服务器本地 curl 正常这是最经典的“两层防火墙问题”。先去 UFW 查端口是否放行sudo ufw status再去云控制台安全组确认入站规则有没有加 80/443。这两个地方缺一不可大厂控制台的“快速放行”功能别偷懒要手动确认端口确实开了。systemd 启动失败日志显示Exec format error或python: not found大概率是 ExecStart 里用了相对路径或者错误的 Python 路径。确认venv/bin/python存在并把路径写成绝对路径。7.3 Nginx 代理与证书问题访问出现 502 Bad Gateway说明 Nginx 能连到你服务器但没连上后端进程。先确认 systemd 服务是否在跑再用curl http://127.0.0.1:8000验证后端。如果后端正常检查 Nginx 里proxy_pass的地址和端口是不是写错了。页面能打开但对话功能一直转圈十有八九是 WebSocket 没通。检查 Nginx 配置里有没有proxy_set_header Upgrade $http_upgrade;和proxy_set_header Connection upgrade;这两行缺一不可。另外确认你用的代理协议是不是 HTTP/1.12.0 版本对 WebSocket 有些限制。浏览器提示证书不受信任如果是自签名证书这是正常的如果是 Lets Encrypt 证书检查域名解析是否到这台服务器证书签发的域名和你访问的域名必须一致。7.4 日常维护技巧服务跑稳定之后日常维护主要靠几条命令# 查看最近日志 sudo journalctl -u deepseek-harness -n 100 --no-pager # 跟踪日志输出 sudo journalctl -u deepseek-harness -f # 重启服务 sudo systemctl restart deepseek-harness # 查看 Nginx 日志 sudo tail -f /var/log/nginx/access.log /var/log/nginx/error.log日志是最好的老师。遇到问题先翻日志不要重启大法一顿乱按。你大概率会从日志里看到明确的错误线索比如某个模块导入失败、数据库锁表、请求超时对症下药比盲猜快得多。我个人实际部署过几次之后的体会是这个项目最折磨人的从来不是技术难点本身而是各种“看起来不起眼”的配置遗漏——忘记放行 UFW 端口、Nginx 漏了双斜杠结尾、systemd 路径写错、虚拟环境没用绝对路径。这些坑你踩过一次就长记性了。所以这篇教程里凡是能明确的细节我都写了照着来应该能少走很多弯路。最后再分享一个实用小技巧在.env文件里我建议把日志级别调成DEBUG跑通之后再改成INFO。调试阶段能看到完整的请求转发链路和 SQL 语句查问题会快很多。稳定运行后改回INFO日志干净也少一些噪音。整个部署流程到这里就完整了剩下的就是去体验一下这个 Web 界面把模型用起来。 
长河君 · 2026/10/11 4:27:15 · 阅读 1.2k Linux服务器源码部署DeepSeek Harness Web全攻略
这套“Linux 服务器源码部署 DeepSeek Harness Web”的流程我前后在几台不同配置的服务器上折腾过从最开始的一脸懵到现在闭着眼睛能把环境搭起来中间踩过的坑不算少。这篇就把整个部署链路从头到尾捋一遍从拿到一台干净服务器开始一直到外网能正常访问 Web 界面全程不绕弯子尽量做到每一步你都能照着敲。先说 DeepSeek Harness Web 是什么。简单讲它是一个自托管的 Web 控制台用来统一管理 DeepSeek 模型的对话请求、API 密钥、上下文参数这些核心配置相当于给你常用的模型能力套了一个可视化操作界面。相比直接在终端里调接口它更适合把模型能力开放给团队协作、日常演示或者自己多端使用。整篇教程不需要你有很深的运维底子但至少要对 Linux 基本命令不陌生知道cd、ls、vim是干嘛的就行。1. 项目部署思路拆解先弄明白要做什么1.1 这个项目到底解决什么问题很多人拿到一个开源项目第一步就是git clone然后开始无脑装依赖结果装到一半发现缺这个缺那个最后系统一片混乱。这里我建议先花五分钟想想这个项目跑起来需要哪几个核心部件针对 DeepSeek Harness Web 这类前后端分离的 Web 应用核心无非是三层后端服务处理 API 转发、密钥管理、对话历史存储一般用 Python 系的 Web 框架居多常见的是 FastAPI 或者 Flask。前端页面提供浏览器里的操作界面Vue 或 React 写的单页应用构建后是一堆静态文件。数据存储保存配置信息、对话记录通常用 SQLite 起步人多了再换 PostgreSQL。搞清楚这三点之后整个部署思路就清晰了先把后端跑起来再把前端构建产物让后端能访问到最后用 Nginx 做统一入口把流量转发过去顺便把 HTTPS 加上。1.2 为什么选择源码部署而不是直接跑 Docker我知道肯定会有人问官方不是提供 Docker 镜像吗直接docker run不香吗香但不适合所有人。源码部署看起来步骤多可它有几点是 Docker 方案给不了的可定制性强。这类 Harness 工具经常需要改配置、加插件源码部署可以直接改代码目录里的文件改完立即生效不用重新构建镜像。资源占用更低。一台 2G 内存的小机器跑 Docker 容器要预留系统开销源码部署省掉一层尤其对于学生机和低配云主机来说差别挺明显。排查问题更直接。服务起不来源码部署可以直接看进程输出、翻日志、打断点Docker 里查问题得进容器多一层周转。学习价值完全不同。源码部署一遍你对整个项目的依赖关系、启动流程、配置文件结构会有很直观的理解这是运维技能的一部分。如果你只是临时体验一把那用 Docker 没问题。但如果你想长期用、想改造成自己的工具源码部署才是正经路子。本教程就按源码部署讲。2. 环境准备从一台干净服务器开始2.1 服务器选型与系统要求我用的是 Ubuntu 22.04 LTS这是目前最稳妥的服务器系统选择软件源里的包版本都比较新官方文档里的命令也基本以 Debian 系为准。如果你用的是 CentOS 或者 Rocky Linux命令要对应换成yum/dnf组的思路完全一样。硬件配置方面我给个最低参考项目最低要求推荐配置CPU1 核2 核及以上内存1GB2GB 以上磁盘10GB20GB SSD操作系统Ubuntu 20.04Ubuntu 22.04 LTS这个项目本身不重不会像跑大模型推理那样吃显存它的作用是管理模型 API 的调用真正的计算压力在 DeepSeek 服务端那边。所以 1G 内存的小机器也能跑只是编译前端依赖的时候会有点紧张我建议至少 2G省得 npm 构建到一半被 OOM 干掉。还有一个必须确认的服务器的 Python 和 Node 版本。DeepSeek Harness Web 这类新项目通常会要求 Python 3.10 和 Node.js 18。python3 --version node --version npm --version如果版本太老先升级。这也是我第一次部署时栽过的跟头机器自带的 Python 是 3.8结果pip install一堆包直接报版本不满足排查了半天才发现是解释器版本的问题。2.2 基础依赖安装先把编译工具链备齐拿到一台新服务器先别急着拉代码先把系统基础工具装好。很多依赖包在安装过程中需要编译缺了编译工具链会报各种奇怪的错比方说gcc: command not found或者No module named wheel。sudo apt update sudo apt upgrade -y sudo apt install -y build-essential git curl wget python3-dev python3-venv python3-pip libssl-dev libffi-dev nginx ufw解释一下这几个包为什么必须build-essential包含 gcc/g 和 make编译 Python C 扩展的必需品。python3-dev提供 Python 头文件某些 pip 包比如uvloop、cryptography需要它才能编译安装。libssl-dev和libffi-dev这是两个很容易被忽略的依赖。cryptography、OpenSSL绑定、部分数据库驱动都依赖它们缺了就是在 pip 安装时报openssl/opensslv.h: No such file or directory。python3-venv创建虚拟环境的工具后面要用。nginx反向代理服务器远程访问的关键一环。既然要远程访问直接在这里装好后面少一次安装。ufw防火墙管理工具Ubuntu 自带的用起来简单。装完之后建议顺手重启一次或者至少刷新一下系统环境避免 PATH 不生效。3. 源码获取与应用配置把项目跑起来的第一步3.1 拉取源码并看懂目录结构环境就绪之后就可以拉代码了。先建一个普通用户来干这活别用 root 跑项目服务这是安全底线。我习惯创建一个叫harness的用户专门跑这个应用。sudo useradd -m -s /bin/bash harness sudo usermod -aG sudo harness su - harness然后进入用户目录拉取代码cd ~ git clone https://github.com/your-project/deepseek-harness-web.git cd deepseek-harness-web拉下来之后先别急着操作花两分钟看看目录结构。一个标准的这类项目一般会有这些目录目录/文件作用backend/后端 Python 代码frontend/前端源码requirements.txtPython 依赖清单.env.example环境变量模板package.json前端构建配置docs/官方文档这一步相当于你先拿到地图再出发。很多小白拉完代码就往里冲最后根本不知道哪个文件是配置文件、哪个命令是启动入口全靠猜。我个人的习惯是先把.env.example打开看一眼把README.md的 Quick Start 部分读一遍再动手。这一步能省掉后面 80% 的困惑。3.2 后端环境虚拟环境与 Python 依赖安装后端是 FastAPI 写的所以需要单独建一个 Python 虚拟环境。为什么要用虚拟环境而不是直接用系统的 Python因为系统环境是干净的一旦装坏了全局的 Python 包可能会影响系统自带工具。虚拟环境把项目依赖隔离在自己的小天地里随便折腾都不会影响系统。cd ~/deepseek-harness-web/backend python3 -m venv venv source venv/bin/activate激活之后命令行前面会出现(venv)的标识说明已经在虚拟环境里了。接着安装依赖pip install --upgrade pip pip install -r requirements.txt这个过程可能会有些慢因为像pydantic、uvicorn这些包需要下载安装。如果你在网络环境一般的情况下安装失败可以换成国内镜像源pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple这里要注意不要为了省事直接用pip install -r requirements.txt加--system-site-packages也不要绕过虚拟环境直接往系统里装后面维护会很难受。3.3 配置文件与数据库初始化依赖装完之后就该配置环境变量了。这个项目通过.env文件来管理配置模板文件是.env.example。cp .env.example .env vim .env打开这个文件重点看几个核心配置项# 服务监听端口 PORT8000 # 数据库连接 DATABASE_URLsqlite:///./data/app.db # 模型 API 密钥 DEEPSEEK_API_KEY你的密钥 # 会话密钥用于加密 Cookie SECRET_KEY一串随机字符 # Web 服务基础地址 BASE_URLhttp://localhost:8000密钥建议用openssl rand -hex 32生成别用你随手敲的一段字符串。数据库这块如果是单机自用SQLite 完全够用一个文件搞定备份也简单。如果后面要给一个团队用建议换成 PostgreSQL连接串变成DATABASE_URLpostgresql://harness:passwordlocalhost:5432/harness_db配好.env之后初始化数据库。不同的项目命令不一样如果是上面提到的 FastAPI Alembic 的组合一般是alembic upgrade head如果是 Django 项目则是python manage.py migrate跑完这条命令data/目录下会出现数据库文件。这一步的作用是让项目代码里定义的数据表真正落到数据库里没有这张“表结构”服务启动会报错后端也无法保存任何数据。4. 前端构建与本地联调前后端打通4.1 Node.js 环境与前端依赖安装后端准备就绪现在处理前端。前端源码在frontend/目录下这是一个标准的 Vite Vue/React 项目。首先确保 Node.js 版本在 18 以上否则构建时会报错。cd ~/deepseek-harness-web/frontend npm installnpm install跑完后项目会多出一个node_modules目录里面全是依赖包这个目录很大不用关心它是什么它只是构建工具的“材料库”。然后执行构建npm run build构建完成后frontend/dist目录下会出现一堆静态文件包括index.html和assets/目录。这些文件就是浏览器里看到的界面。4.2 本地启动与自测后端和前端都准备好了现在先把服务跑起来看看能不能在本机访问。回到后端目录用 uvicorn 启动开发模式cd ~/deepseek-harness-web/backend source venv/bin/activate python -m uvicorn app.main:app --host 127.0.0.1 --port 8000启动成功后终端会显示类似Uvicorn running on http://127.0.0.1:8000的信息。在服务器本机测试一下curl -I http://127.0.0.1:8000如果返回 HTTP/1.1 200 OK说明后端已经活了。再打开另一个 SSH 窗口试一下前端资源能否正常加载。这类项目通常会在后端里直接挂载前端静态文件所以如果一切正常直接curl http://127.0.0.1:8000应该能看到 HTML 页面。提示这里有一个很容易踩的坑。启动时--host 127.0.0.1只能本机访问如果你想立刻从自己电脑浏览器访问可以先用--host 0.0.0.0 --port 8000临时试一下。但生产环境不要直接暴露 8000 端口后面我会用 Nginx 接一个更安全的入口。5. 生产化部署让服务稳定跑在后台5.1 为什么要用 systemd 管理开发模式下服务是挂在当前 SSH 会话里的一关终端服务就死了这在生产环境显然不能用。Linux 下管理后台服务最标准的方式是 systemd。它的作用相当于给你这个服务装了一个“自动管家”开机自动启动、崩溃自动重启、日志集中管理。5.2 编写 systemd 服务单元文件先停掉刚才手动启动的 uvicornCtrl C然后创建一个服务配置文件sudo vim /etc/systemd/system/deepseek-harness.service内容如下[Unit] DescriptionDeepSeek Harness Web Service Afternetwork.target [Service] Typesimple Userharness Groupharness WorkingDirectory/home/harness/deepseek-harness-web/backend EnvironmentFile/home/harness/deepseek-harness-web/backend/.env ExecStart/home/harness/deepseek-harness-web/backend/venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --workers 2 Restartalways RestartSec3 [Install] WantedBymulti-user.target这里有几个细节需要展开Userharness很关键。用普通用户跑服务即使程序被攻击攻击者拿到的权限也有限。如果图省事用 root相当于把自家大门钥匙挂在门口。EnvironmentFile的作用是让 systemd 启动服务时自动读取.env文件里的环境变量。ExecStart里用的是虚拟环境里的 Python 绝对路径不要用python因为 systemd 启动时不一定加载了你的虚拟环境。--workers 2表示启动两个 worker 进程够用且稳定。1G 内存的小机器建议改成 1内存充足 2-3 没问题。设置好之后让 systemd 重新识别配置并启动服务sudo systemctl daemon-reload sudo systemctl enable deepseek-harness sudo systemctl start deepseek-harness sudo systemctl status deepseek-harness看到active (running)就说明服务被系统接管了。之后不管怎么关终端服务都会在后台跑着服务器重启也会自动拉起来。查看日志随时用这个命令journalctl -u deepseek-harness -f这里记个教训我最初部署时没加Restartalways结果有一次后端进程因为内存不足被系统杀掉整个服务瘫了一晚上没人发现。加了这个参数之后就算进程异常退出三秒后就会自动拉起来这才是真正能让你睡安稳觉的配置。6. 远程访问与安全加固从只能本地到外网可用6.1 防火墙与安全组放行服务已经跑在 127.0.0.1:8000 上了但现在外网还访问不到。要开放访问需要做两层放行。第一层是系统防火墙 UFW。放行 SSH、HTTP、HTTPSsudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable第二层是云服务器的安全组。去你买服务器的云控制台找到“安全组”或“防火墙”配置放行 80 和 443 端口。这一步很多人会忽略结果在服务器里折腾半天外网就是死活不通一查是安全组没放行。注意不要为了省事把 8000 端口的入站规则也放出去。生产环境应该用 Nginx 监听 80/443再由 Nginx 转发到内部 8000这是惯例做法。直接把应用端口暴露出去既不利于日志集中管理也少了一道防护。6.2 Nginx 反向代理与 WebSocket 支持现在开始配置 Nginx。这里的重要作用Nginx 监听公网 80/443 端口接收到请求后转发给后端的 127.0.0.1:8000。同时 Nginx 还负责处理前端静态文件转发因为这个项目前端和后端都在同一个服务里配置可以保持简洁。创建站点配置sudo vim /etc/nginx/sites-available/deepseek-harness内容如下server { listen 80; server_name your-domain.com; # 如果没有域名用服务器公网 IP location / { proxy_pass http://127.0.0.1:8000; 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; # WebSocket 支持这个必须加上 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; } # 静态资源缓存策略 location /assets/ { proxy_pass http://127.0.0.1:8000; proxy_cache_valid 200 30d; add_header Cache-Control public, max-age2592000; } }启用站点并重载 Nginxsudo ln -s /etc/nginx/sites-available/deepseek-harness /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginxnginx -t是检查配置语法没问题再reload把改动加载进去。这里为什么要强调 WebSocket 支持因为这类 Harness 工具的对话功能很多都把实时流式输出建立在 WebSocket 或 SSE 上。如果 Nginx 配置里没有那两行Upgrade和Connection你会发现页面能打开但一问会话框就卡住或者消息发不出去体验很诡异。配置完成后直接用浏览器访问你的服务器 IP 或域名就能看到登录页面了。如果显示不出来先确认http://127.0.0.1:8000在服务器本机 curl 是否正常再顺 Nginx 一层层往外排查。6.3 HTTPS 证书与安全加固HTTP 访问通了但这还不够。如果这个工具要配置 DeepSeek API 密钥那么 API 密钥会在你每次登录和操作时经过浏览器与服务器之间的传输。没有 HTTPS这些信息就等于明文在网络上跑太危险了。如果有域名用 Lets Encrypt 申请免费证书就很方便sudo apt install -y certbot python3-certbot-nginx sudo certbot --nginx -d your-domain.comCertbot 会自动帮你改 Nginx 配置、签发证书、配置自动续期。整个流程基本上是交互式的跟着提示走就行。如果没有域名只有公网 IP那很多 CA 机构不提供纯 IP 证书这时候有两个选择接受 HTTP IP 访问但只在受信任网络内使用。用自签名证书走 HTTPS浏览器会提示不受信任需要自己手动信任。我的建议是如果只是个人短暂使用用 HTTP IP 先顶着问题不大但只要你打算长期使用、并在里面填真实 API Key域名 Lets Encrypt 的 HTTPS 就是底线配置。再补几个安全加固的操作这些是顺手就能做的# 禁用 root 密码登录 sudo vim /etc/ssh/sshd_config # 设置 PermitRootLogin no # 设置 PasswordAuthentication no前提是你已经配好 SSH 密钥 sudo systemctl restart sshd # 安装 fail2ban 防暴力破解 sudo apt install -y fail2ban sudo systemctl enable fail2ban sudo systemctl start fail2ban另外建议给这个 Web 应用本身加一层访问控制。如果项目自带登录功能那就把初始管理员密码立刻改掉如果不带前端套一层 Nginx Basic Auth 是成本最低的方案sudo apt install -y apache2-utils sudo htpasswd -c /etc/nginx/.htpasswd admin然后在 Nginx 的站点配置里加两行location / { auth_basic Restricted Access; auth_basic_user_file /etc/nginx/.htpasswd; ... }这样就算应用本身有漏洞外面也还有一层密码保护。7. 常见问题排查与避坑实录7.1 依赖安装阶段的高频报错报错error: command gcc failed with exit status 1这是最典型的编译错误原因基本都是缺系统依赖。先执行sudo apt install -y build-essential python3-dev libssl-dev libffi-dev再重新安装。如果还报错看错误信息里具体缺哪个头文件缺啥装啥。绝大多数情况是libssl-dev少了装完立刻好。报错ModuleNotFoundError: No module named xxx这说明依赖装得不全。先pip install -r requirements.txt重新装一遍确认没有跳过某些包。如果用了镜像源有可能某个包没成功拉到切换回默认源再试一次。npm install 碰到 ETIMEDOUT网络环境波动导致的。可以直接用靠谱的 npm 镜像源npm config set registry https://registry.npmmirror.com npm install装完后npm run build如果构建过程中出现内存溢出heap out of memory把 Node 内存限制调大NODE_OPTIONS--max-old-space-size2048 npm run build7.2 服务启动与端口问题提示Address already in use说明 8000 端口已经被占用了。端口被占用先看是谁占的sudo lsof -i :8000如果是残留的 uvicorn 进程直接sudo kill -9 pid。生产环境不建议手动 kill改掉服务配置重启更干净。外网无法访问但服务器本地 curl 正常这是最经典的“两层防火墙问题”。先去 UFW 查端口是否放行sudo ufw status再去云控制台安全组确认入站规则有没有加 80/443。这两个地方缺一不可大厂控制台的“快速放行”功能别偷懒要手动确认端口确实开了。systemd 启动失败日志显示Exec format error或python: not found大概率是 ExecStart 里用了相对路径或者错误的 Python 路径。确认venv/bin/python存在并把路径写成绝对路径。7.3 Nginx 代理与证书问题访问出现 502 Bad Gateway说明 Nginx 能连到你服务器但没连上后端进程。先确认 systemd 服务是否在跑再用curl http://127.0.0.1:8000验证后端。如果后端正常检查 Nginx 里proxy_pass的地址和端口是不是写错了。页面能打开但对话功能一直转圈十有八九是 WebSocket 没通。检查 Nginx 配置里有没有proxy_set_header Upgrade $http_upgrade;和proxy_set_header Connection upgrade;这两行缺一不可。另外确认你用的代理协议是不是 HTTP/1.12.0 版本对 WebSocket 有些限制。浏览器提示证书不受信任如果是自签名证书这是正常的如果是 Lets Encrypt 证书检查域名解析是否到这台服务器证书签发的域名和你访问的域名必须一致。7.4 日常维护技巧服务跑稳定之后日常维护主要靠几条命令# 查看最近日志 sudo journalctl -u deepseek-harness -n 100 --no-pager # 跟踪日志输出 sudo journalctl -u deepseek-harness -f # 重启服务 sudo systemctl restart deepseek-harness # 查看 Nginx 日志 sudo tail -f /var/log/nginx/access.log /var/log/nginx/error.log日志是最好的老师。遇到问题先翻日志不要重启大法一顿乱按。你大概率会从日志里看到明确的错误线索比如某个模块导入失败、数据库锁表、请求超时对症下药比盲猜快得多。我个人实际部署过几次之后的体会是这个项目最折磨人的从来不是技术难点本身而是各种“看起来不起眼”的配置遗漏——忘记放行 UFW 端口、Nginx 漏了双斜杠结尾、systemd 路径写错、虚拟环境没用绝对路径。这些坑你踩过一次就长记性了。所以这篇教程里凡是能明确的细节我都写了照着来应该能少走很多弯路。最后再分享一个实用小技巧在.env文件里我建议把日志级别调成DEBUG跑通之后再改成INFO。调试阶段能看到完整的请求转发链路和 SQL 语句查问题会快很多。稳定运行后改回INFO日志干净也少一些噪音。整个部署流程到这里就完整了剩下的就是去体验一下这个 Web 界面把模型用起来。