1. 项目缘起与整体部署思路1.1 为什么要在云服务器上跑 Deepseek HarnessDeepseek Harness 这套东西第一次接触的人容易把它想复杂。说白了它就是一个把大模型能力“挂”到你本地或服务器环境里的运行框架核心价值在于让模型能读写文件、执行命令、调用插件、串联工作流。你在自己电脑上跑爽是爽但一旦离开那台机器就断了团队里其他人也用不上。把它放到云服务器上等于给它安了一个 7×24 小时不关机的家随时随地都能连上去干活。我自己的使用场景比较典型白天在办公室用台式机晚上回家用笔记本偶尔出差用平板。如果 Harness 只装在某一台机器上切换设备就得重新配环境插件、skill、会话记录全对不上。放到云服务器之后所有设备访问的是同一个实例上下文一致插件一致连代码回退的历史都在同一个地方。这是最直接的动机。另一个动机是算力。云服务器可以按需选配 CPU、内存和磁盘跑 Harness 本身不需要 GPU但如果要接本地模型或者做大量文件索引内存和磁盘 IO 就很关键。我试过在 2C2G 的小机器上跑光加载 skill 就卡半天后来换成 4C8G流畅度完全不一样。所以云服务器的规格选择不是随便买一台就行后面会细说。1.2 公网鉴权访问到底解决什么问题把 Harness 暴露到公网很多人第一反应是“不安全”。这个担心是对的但问题不在“公网”本身而在于你有没有做鉴权。公网鉴权访问的核心目标就一个让合法用户从任何网络都能连上同时把未授权访问挡在门外。具体到 Deepseek Harness它本身可能带一个 Web 界面或者 API 端口。如果你直接把它绑到 0.0.0.0 并且防火墙全开那等于把家门钥匙插在锁上。正确的做法是在它前面加一层反向代理由代理来处理 TLS 终止、身份验证、访问控制Harness 本身只监听本地回环地址。这样即使 Harness 有漏洞攻击面也被限制在代理这一层。我见过有人图省事直接用云服务商的安全组开放端口然后 Harness 设一个弱密码。结果第二天日志里全是扫描记录。所以公网鉴权不是可选项是必选项。Nginx 和 Caddy 都能做这件事选哪个后面会对比。1.3 整体架构长什么样整个部署的架构可以拆成四层。最底层是云服务器本身负责提供计算和存储资源。往上是运行环境包括系统依赖、Python 运行时、Harness 本体。再往上是反向代理层Nginx 或 Caddy 在这里做 TLS、鉴权、限流、日志。最外层是访问入口可以是域名也可以是 IP 加端口。数据流向是这样的用户从浏览器或客户端发起请求先到反向代理代理验证身份后转发给本地的 Harness 服务Harness 处理完把结果原路返回。整个过程 Harness 不直接接触公网所有外部流量都经过代理过滤。这个设计的好处是职责清晰代理只管安全和转发Harness 只管业务逻辑互不干扰。我自己的机器上还加了一层用 systemd 管理 Harness 进程挂了自动重启。这样即使 Harness 因为某个插件崩溃也不会导致整个服务不可用。这个细节后面会展开。1.4 方案选型Nginx 还是 Caddy这个问题我被问过很多次。直接说结论如果你追求配置简单、自动 HTTPS、不想折腾证书选 Caddy。如果你需要精细控制、复杂路由规则、成熟生态选 Nginx。Caddy 的最大优势是配置文件极短。一个典型的 Caddyfile 可能就五六行自动申请和续期 Lets Encrypt 证书你什么都不用管。对于个人项目或者小团队这能省掉大量时间。我实测下来Caddy 从零到跑起来 HTTPS十分钟以内搞定。Nginx 的优势在于灵活性和资料丰富。你想做基于路径的路由、基于 Header 的转发、复杂的限流规则Nginx 的配置表达能力更强。而且网上关于 Nginx 的教程、排错案例多得多遇到问题更容易找到答案。缺点是证书要自己配通常是 certbot 配合多了一步。我的建议是第一次部署、以快速可用为目标用 Caddy。需要长期维护、有复杂需求用 Nginx。两者不冲突你甚至可以先用 Caddy 跑起来后面再换 Nginx。下面我会以 Nginx 为主线讲因为它的配置细节更能说明原理Caddy 的对应配置也会给出来。2. 云服务器环境准备与 Harness 安装2.1 服务器规格怎么选选服务器这件事我的经验是“宁大勿小”。Harness 本身不重但它依赖的东西多Python 环境、各种 skill 的依赖库、可能还有本地向量数据库。这些东西加起来2G 内存很容易爆。我整理了一个规格对照表基于实际使用体验使用场景CPU内存磁盘说明个人试用、少量插件2 核4G40G SSD勉强够用加载 skill 偏慢日常使用、多插件4 核8G80G SSD推荐配置流畅团队共用、大量索引8 核16G160G SSD需要跑本地模型或大索引时选磁盘一定要选 SSDHarness 读写文件频繁机械盘会拖慢整体响应。系统盘 40G 起步如果你要装很多 skill 或者存大量文档建议单独挂一块数据盘。操作系统我推荐 Ubuntu 22.04 或 24.04 LTS。CentOS 9 也能用但软件源和包管理跟 Ubuntu 有差异新手容易踩坑。如果你习惯 CentOS记得用 dnf 代替 apt防火墙用 firewalld 而不是 ufw。2.2 系统初始化与安全基线拿到服务器第一件事不是装 Harness而是把基础安全做好。我踩过的坑是装完 Harness 才想起来改 SSH 端口结果改完把自己锁在外面只能重装系统。正确的顺序是这样的。先更新系统包然后创建普通用户禁用 root 远程登录改 SSH 端口配置防火墙。这几步做完再动 Harness。# 更新系统 apt update apt upgrade -y # 创建普通用户 adduser deploy usermod -aG sudo deploy # 配置 SSH 密钥登录在本地生成密钥后上传公钥 mkdir -p /home/deploy/.ssh cp ~/.ssh/authorized_keys /home/deploy/.ssh/ chown -R deploy:deploy /home/deploy/.ssh chmod 700 /home/deploy/.ssh chmod 600 /home/deploy/.ssh/authorized_keys # 修改 SSH 配置 sed -i s/#Port 22/Port 2222/ /etc/ssh/sshd_config sed -i s/PermitRootLogin yes/PermitRootLogin no/ /etc/ssh/sshd_config sed -i s/#PasswordAuthentication yes/PasswordAuthentication no/ /etc/ssh/sshd_config systemctl restart sshd注意改 SSH 端口之前先在云服务商的安全组里放行新端口否则重启 sshd 后你就连不上了。这个顺序不能反。防火墙用 ufw 配置只放行 SSH 新端口、HTTP、HTTPSufw default deny incoming ufw default allow outgoing ufw allow 2222/tcp ufw allow 80/tcp ufw allow 443/tcp ufw enable2.3 安装 Harness 本体Deepseek Harness 的安装方式取决于你拿到的分发包形式。常见的有三种pip 安装、源码安装、Docker 镜像。我三种都试过个人推荐源码安装因为可控性最强出问题好排查。先装基础依赖sudo apt install -y python3 python3-pip python3-venv git curl build-essential然后创建虚拟环境把 Harness 装进去。用虚拟环境的好处是隔离依赖不会污染系统 Pythonpython3 -m venv /opt/harness/venv source /opt/harness/venv/bin/activate pip install --upgrade pip接下来根据你拿到的包来装。如果是 pip 包pip install deepseek-harness如果是源码cd /opt/harness git clone 仓库地址 src cd src pip install -r requirements.txt pip install -e .安装完成后验证一下harness --version如果提示命令找不到检查虚拟环境的 bin 目录是否在 PATH 里。我习惯在 systemd 服务里写绝对路径避免这个问题。2.4 配置 Harness 监听本地端口Harness 默认可能监听 0.0.0.0这不行。我们要让它只监听 127.0.0.1把公网入口交给反向代理。配置文件通常在/opt/harness/config.yaml或类似位置。关键配置项server: host: 127.0.0.1 port: 8765 # 不要在这里配 TLS交给反向代理 auth: # 如果 Harness 自带鉴权可以在这里配 # 但建议在反向代理层做双重保险 enabled: false端口选 8765 是因为不常用避免跟其他服务冲突。你可以用ss -tlnp查看端口占用情况。配置好后先手动启动测试source /opt/harness/venv/bin/activate harness serve --config /opt/harness/config.yaml然后在服务器上用 curl 测试curl http://127.0.0.1:8765/health返回正常就说明 Harness 本身跑起来了。这时候从外网还访问不了因为只监听了本地。2.5 用 systemd 托管 Harness 进程手动启动的进程一关终端就没了必须用 systemd 托管。创建服务文件/etc/systemd/system/harness.service[Unit] DescriptionDeepseek Harness Service Afternetwork.target [Service] Typesimple Userdeploy Groupdeploy WorkingDirectory/opt/harness EnvironmentPATH/opt/harness/venv/bin:/usr/local/bin:/usr/bin:/bin ExecStart/opt/harness/venv/bin/harness serve --config /opt/harness/config.yaml Restartalways RestartSec5 StandardOutputjournal StandardErrorjournal [Install] WantedBymulti-user.target几个关键点解释一下。Userdeploy表示用普通用户跑不用 root降低风险。Restartalways保证崩溃后自动拉起。Environment里把虚拟环境的 bin 目录放最前面确保用的是虚拟环境里的 Python 和依赖。启用并启动sudo systemctl daemon-reload sudo systemctl enable harness sudo systemctl start harness sudo systemctl status harness看状态是 active (running) 就对了。日志用journalctl -u harness -f实时查看。3. 反向代理与公网鉴权配置3.1 Nginx 安装与基础配置Ubuntu 上装 Nginx 很简单sudo apt install -y nginx sudo systemctl enable nginx sudo systemctl start nginx装完后默认站点监听 80 端口。我们要做的是新建一个站点配置把流量转发给 Harness。先理解 Nginx 的配置结构。主配置在/etc/nginx/nginx.conf站点配置通常放在/etc/nginx/sites-available/然后软链接到/etc/nginx/sites-enabled/。这种设计方便你随时启用或禁用某个站点。创建/etc/nginx/sites-available/harnessserver { listen 80; server_name harness.example.com; location / { proxy_pass http://127.0.0.1:8765; 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; } }这里proxy_pass指向本地 Harnessproxy_set_header那几行是把原始请求信息传给后端Harness 如果需要记录客户端 IP 或者判断协议就靠这些头。启用站点sudo ln -s /etc/nginx/sites-available/harness /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginxnginx -t是语法检查每次改完配置都要跑一遍。我踩过的坑是改完直接 reload结果配置有错导致 Nginx 起不来整个站点全挂。先测试再 reload这个习惯能救命。3.2 配置 HTTPS 证书HTTP 明文传输不安全必须上 HTTPS。用 certbot 申请 Lets Encrypt 证书sudo apt install -y certbot python3-certbot-nginx sudo certbot --nginx -d harness.example.comcertbot 会自动修改你的 Nginx 配置加上 443 监听和证书路径还会配置 HTTP 自动跳转 HTTPS。申请完成后证书会自动续期不用手动管。如果你用的是 Caddy这一步完全不用做。Caddyfile 里写个域名它自己就把证书搞定了harness.example.com { reverse_proxy 127.0.0.1:8765 }就这么简单。Caddy 会自动申请证书、配置 HTTPS、处理续期。这也是我推荐新手用 Caddy 的原因。3.3 加一层 HTTP Basic 鉴权HTTPS 解决了传输加密但没解决“谁能访问”。如果 Harness 本身没有登录界面任何人都能打开你的域名直接用。这时候加一层 Basic 鉴权是最快的方法。先生成密码文件sudo apt install -y apache2-utils sudo htpasswd -c /etc/nginx/.htpasswd yourusername然后修改 Nginx 配置在 location 块里加两行location / { auth_basic Restricted Access; auth_basic_user_file /etc/nginx/.htpasswd; proxy_pass http://127.0.0.1:8765; 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; }reload 之后访问域名就会弹出浏览器原生的登录框。输入用户名密码才能进。注意Basic 鉴权的密码是 base64 编码传输的不是加密。所以必须配合 HTTPS 使用否则密码等于裸奔。这也是为什么先配 HTTPS 再加鉴权。3.4 更细粒度的访问控制Basic 鉴权够用但不够灵活。如果你想做基于 IP 的白名单、基于路径的权限、或者 API Key 鉴权Nginx 也能做。IP 白名单location / { allow 203.0.113.0/24; allow 198.51.100.5; deny all; proxy_pass http://127.0.0.1:8765; }这段配置只允许特定 IP 段访问其他全部拒绝。适合固定办公场景。基于路径的鉴权比如只保护管理接口location /admin/ { auth_basic Admin Area; auth_basic_user_file /etc/nginx/.htpasswd; proxy_pass http://127.0.0.1:8765; } location / { proxy_pass http://127.0.0.1:8765; }这样/admin/需要密码其他路径开放。具体怎么配取决于 Harness 的路由结构。3.5 限流与防暴力破解公网服务一定会被扫描Basic 鉴权会被暴力尝试。加限流能有效缓解limit_req_zone $binary_remote_addr zoneharness_limit:10m rate10r/s; server { location / { limit_req zoneharness_limit burst20 nodelay; auth_basic Restricted Access; auth_basic_user_file /etc/nginx/.htpasswd; proxy_pass http://127.0.0.1:8765; } }limit_req_zone定义了一个限流区域按客户端 IP 限制每秒 10 个请求突发允许 20 个。超过的请求返回 503。这能挡住大部分暴力破解脚本。limit_req_zone必须放在 http 块里不能放在 server 块里。通常写在/etc/nginx/nginx.conf的 http 段或者单独的 conf 文件被 include 进来。4. 实操过程中的坑与排查技巧4.1 常见问题速查表部署过程中遇到的问题我整理成了一张表方便对照排查现象可能原因排查方法解决方案502 Bad GatewayHarness 没启动或端口不对systemctl status harness、ss -tlnp启动服务检查端口配置404 Not FoundNginx 路由配置错误看 Nginx error log检查 location 和 proxy_pass403 Forbidden权限或 IP 限制看 Nginx access log检查 allow/deny 和文件权限证书错误证书未申请或过期certbot certificates重新申请或续期连接超时防火墙或安全组未放行ufw status、云控制台放行 80/443 端口鉴权失败密码文件路径或权限错误ls -la /etc/nginx/.htpasswd修正路径和权限4.2 502 错误的排查思路502 是部署中最常见的错误意思是 Nginx 连不上后端。排查顺序是这样的。第一步确认 Harness 进程在跑systemctl status harness如果是 failed 或者 inactive先把它启动起来。看日志找原因journalctl -u harness -n 50 --no-pager第二步确认端口监听正确ss -tlnp | grep 8765应该看到127.0.0.1:8765。如果看到的是0.0.0.0:8765说明 Harness 配置没生效还在监听所有地址。如果什么都没看到说明 Harness 没起来。第三步从服务器本地测试curl -v http://127.0.0.1:8765/health如果本地能通但外网 502问题在 Nginx 配置。如果本地也不通问题在 Harness 本身。第四步看 Nginx 错误日志tail -f /var/log/nginx/error.log日志里会写具体原因比如connect() failed (111: Connection refused)说明后端没监听upstream timed out说明后端响应太慢。4.3 权限问题的处理Harness 跑在 deploy 用户下但它要读写的文件可能属于 root。这时候会报权限错误。我遇到过 skill 读取文件失败日志里写Permission denied。解决方法是把相关目录的属主改成 deploysudo chown -R deploy:deploy /opt/harness sudo chown -R deploy:deploy /path/to/workspace如果 Harness 需要访问系统某个目录不要直接给 deploy 用户 root 权限而是用 ACL 精细授权sudo setfacl -R -m u:deploy:rwx /path/to/directory这样只给 deploy 用户特定目录的权限不影响系统安全。4.4 日志管理与轮转Nginx 和 Harness 的日志会一直增长时间长了占满磁盘。配置 logrotate 自动轮转。Nginx 自带 logrotate 配置通常在/etc/logrotate.d/nginx。Harness 的日志如果输出到文件需要自己配/var/log/harness/*.log { daily rotate 14 compress delaycompress missingok notifempty create 0640 deploy deploy sharedscripts postrotate systemctl reload harness /dev/null 21 || true endscript }这段配置表示每天轮转一次保留 14 天压缩旧日志。postrotate里的命令在轮转后执行让 Harness 重新打开日志文件。4.5 性能调优的几个参数Nginx 默认配置对高并发场景不够用可以调几个参数。在nginx.conf的 http 块里worker_processes auto; worker_connections 4096; keepalive_timeout 65; client_max_body_size 100m;worker_processes auto让 Nginx 根据 CPU 核数自动设置工作进程数。worker_connections是每个进程的最大连接数。client_max_body_size控制上传文件大小如果 Harness 要处理大文件这个值要调大。Harness 这边如果响应慢可以看它的日志里有没有耗时统计。有些 skill 加载慢是因为依赖没装好或者索引没建。我遇到过一次 skill 加载要 30 秒后来发现是某个依赖库版本不对换版本后降到 2 秒。5. 进阶玩法与扩展方向5.1 用 Docker 简化部署如果你不想手动配环境Docker 是更省心的选择。把 Harness 和依赖打包成镜像一条命令跑起来。Dockerfile 大概长这样FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . EXPOSE 8765 CMD [harness, serve, --config, /app/config.yaml]构建并运行docker build -t harness:latest . docker run -d --name harness -p 127.0.0.1:8765:8765 -v /opt/harness/data:/app/data harness:latest注意端口映射写127.0.0.1:8765:8765只绑定本地不暴露到公网。数据目录用 volume 挂载容器删了数据还在。Docker 的好处是环境隔离彻底换服务器直接搬镜像。缺点是调试稍微麻烦要看容器日志。5.2 多实例与负载均衡如果团队人多单个 Harness 实例扛不住可以跑多个实例用 Nginx 做负载均衡。upstream harness_backend { server 127.0.0.1:8765; server 127.0.0.1:8766; server 127.0.0.1:8767; } server { location / { proxy_pass http://harness_backend; } }每个实例用不同的配置文件和端口数据目录分开。Nginx 默认轮询转发也可以配权重或 IP hash。注意多实例模式下会话状态要共享否则用户请求打到不同实例会丢上下文。Harness 如果支持外部存储会话就配上去不支持的话用 IP hash 让同一用户固定打到同一实例。5.3 监控与告警服务跑起来之后要知道它是不是健康。最简单的监控是用 UptimeRobot 之类的服务定时探测你的域名挂了发邮件。更专业的做法是部署 Prometheus Grafana采集 Nginx 和 Harness 的指标。Nginx 有nginx-prometheus-exporterHarness 如果有 metrics 接口也可以接进去。我自己的做法比较简单写个脚本定时 curl 健康检查接口失败就发通知。#!/bin/bash if ! curl -sf http://127.0.0.1:8765/health /dev/null; then echo Harness is down | mail -s Alert youremail.com systemctl restart harness fi放到 crontab 里每分钟跑一次。这样即使服务挂了也能自动重启并通知你。5.4 备份策略Harness 的数据包括配置、skill、会话记录、索引文件。这些丢了很麻烦要定期备份。我用的方案是每天凌晨打包数据目录上传到对象存储#!/bin/bash DATE$(date %Y%m%d) tar -czf /tmp/harness-$DATE.tar.gz /opt/harness/data # 上传到对象存储具体命令取决于你用的服务保留最近 7 天的备份旧的自动删除。备份文件要加密因为里面可能有敏感数据。5.5 从 Caddy 切换到 Nginx 的注意事项如果你先用 Caddy 跑起来后来想换 Nginx有几个地方要注意。Caddy 的自动 HTTPS 在 Nginx 里要手动配 certbot。Caddy 的reverse_proxy对应 Nginx 的proxy_pass加一堆 header。Caddy 的basicauth对应 Nginx 的auth_basic。切换的时候先把 Nginx 配好用不同端口测试确认没问题再停 Caddy改 DNS 或端口映射。不要直接停 Caddy 再配 Nginx中间会有服务中断。我自己的经验是如果 Caddy 跑得好好的没必要换。除非你有 Nginx 特有的需求比如复杂的 rewrite 规则或者第三方模块。工具是拿来用的不是拿来折腾的。5.6 关于离线局域网使用的说明有人问 Harness 能不能在离线局域网用。答案是能但有限制。Harness 本体和大部分 skill 可以离线运行但涉及调用外部 API 的功能比如某些模型接口需要网络。如果你完全离线要确保所有依赖都本地化模型也本地部署。离线环境的部署流程跟公网差不多区别是不需要配 HTTPS 证书和公网鉴权直接用 HTTP 加内网 IP 访问就行。但内网也要做基本的访问控制防止内部人员误操作。6. 一些实操心得部署这件事配置本身不难难的是遇到问题时的排查思路。我踩过的坑里大部分不是技术难题而是顺序问题。比如先改 SSH 端口再放行安全组先 reload 再测试配置先暴露公网再加鉴权。这些顺序错了轻则服务不可用重则把自己锁在外面。另一个心得是日志要看全。很多人只看 Nginx 的 access log看到 502 就懵了。其实 error log 里写得清清楚楚是连接被拒还是超时是权限问题还是配置错误。养成看 error log 的习惯能省一半排查时间。还有就是不要过度设计。个人用的话Caddy 加 Basic 鉴权就够了不需要上 Kubernetes 或者复杂的微服务架构。工具是为人服务的够用就行。等真的遇到瓶颈了再升级那时候你也有足够的经验来判断该怎么升。最后说一个细节Harness 的 skill 加载顺序会影响启动速度。如果你装了很多 skill可以把不常用的禁用掉需要时再开。我在配置里加了一个enabled_skills列表只加载当前需要的启动时间从 40 秒降到 8 秒。这个优化对日常使用体验提升很明显。