1. 为什么要在云服务器上折腾 Deepseek Harness先把话说在前头Deepseek Harness 不是一个“下载完双击就能跑”的桌面软件它更像是一套围绕大模型能力构建的工作台把提示词编排、技能Skill加载、文件读写、代码回退、插件扩展这些能力串成一条链。你在本地跑图的是方便你把它搬到云服务器上图的是随时随地能访问、算力集中、多人协作、数据不丢。这两件事的诉求完全不一样。我自己最早是在一台旧笔记本上跑 Harness结果遇到三个绕不过去的坎第一笔记本一合盖服务就断远程根本连不上第二本地模型和插件一多内存直接吃满风扇狂转第三换台电脑就得重新配一遍环境提示词和技能文件还得手动拷。后来我把整套东西迁到云服务器用 Nginx 或 Caddy 做反向代理加上一层公网鉴权才算真正稳定下来。这套流程跑通之后我在任何一台设备上打开浏览器就能用体验完全是两个档次。这篇文章要解决的核心问题就一个怎么把 Deepseek Harness 部署到云服务器上并且通过公网安全地访问它。我会把选型逻辑、环境准备、反向代理配置、鉴权方案、常见报错排查全部拆开讲。适合两类人看一类是有点 Linux 基础、想自己搭一套私有 AI 工作台的开发者另一类是已经在本地用过 Harness、想把它搬到公网但卡在鉴权和反代上的朋友。哪怕你之前只会在宝塔面板里点按钮跟着走也能落地。需要提前说明的是Harness 这类工具的版本迭代比较快具体的安装命令和插件市场入口可能随版本变化。我下面给出的是一套通用性最强、经过验证的部署骨架核心思路进程托管 反向代理 鉴权 HTTPS不会过时你把这套骨架搭好具体版本差异只是换几个参数的事。2. 部署前的整体设计与选型思路2.1 为什么是“云服务器 反向代理 鉴权”这套组合很多人第一反应是Harness 自己不是带 Web 界面吗直接开放端口不就行了理论上可以但实操中非常危险。Harness 的 Web 服务默认监听在某个端口常见是 3000、8080 这类它本身不带强鉴权一旦你把端口直接暴露到公网等于把工作台大门敞开。扫描器几分钟就能发现你然后就是各种探测请求。所以正确的架构是三层第一层Harness 本体跑在服务器本地只监听127.0.0.1不对外。第二层反向代理Nginx 或 Caddy对外监听 80/443负责转发请求、处理 HTTPS、做访问控制。第三层鉴权在反向代理层加 Basic Auth 或者更细的访问策略把未授权请求挡在门外。这样做的逻辑很清晰Harness 只管干活代理只管守门职责分离。就算 Harness 本身有漏洞攻击面也被压缩到最小。2.2 Nginx 还是 Caddy到底怎么选这是被问得最多的问题。我的结论是新手和追求省事的选 Caddy需要精细控制和复杂规则的选 Nginx。对比维度NginxCaddyHTTPS 证书需手动配 certbot 或 acme.sh自动申请续期零配置配置文件语法灵活但略繁琐极简几行搞定反向代理成熟稳定生态大同样稳定配置更短鉴权支持 Basic Auth、auth_request支持 Basic Auth插件丰富适用场景复杂路由、多站点、高并发单站点、快速上线、自动 HTTPS如果你只是部署一个 HarnessCaddy 的配置文件可能就五六行证书自动搞定省心到离谱。但如果你后面还要在同一台服务器上跑别的服务、做多域名分流、配复杂的 location 规则Nginx 的灵活性会更占优。我自己的做法是单服务用 Caddy多服务混布用 Nginx。下面两套配置我都会给。2.3 鉴权方案的选择逻辑公网访问必须鉴权这点没有商量余地。常见方案有三种Basic Auth最简单浏览器弹窗输入账号密码。缺点是密码明文传输靠 HTTPS 保护体验一般但胜在零依赖、配置快。Token / API Key适合程序调用浏览器访问不友好。统一身份认证如 OAuth最安全但配置复杂个人项目没必要。对个人和小团队来说Basic Auth HTTPS是性价比最高的组合。HTTPS 保证传输加密Basic Auth 保证访问控制两层叠加足够挡住 99% 的未授权访问。下面实操部分我会重点讲这个。3. 云服务器环境准备与 Harness 安装3.1 服务器规格与系统选择Harness 本身对 CPU 要求不高但如果要接本地模型或者跑重插件内存和磁盘才是瓶颈。我的建议配置CPU2 核起步4 核更稳内存4GB 是底线8GB 推荐插件和缓存很吃内存磁盘40GB 起步模型文件大的话按需加系统Ubuntu 22.04 LTS 或 CentOS 9 都行我个人更推荐 Ubuntu社区资料多踩坑少系统装好后第一件事是更新源并装基础工具sudo apt update sudo apt upgrade -y sudo apt install -y curl wget git unzip build-essential注意不要用 root 直接跑 Harness 服务后面我们会创建一个专用用户这是安全底线。3.2 创建专用运行用户用 root 跑服务是很多人的坏习惯一旦服务被攻破整台机器就沦陷了。正确做法是建一个低权限用户sudo useradd -m -s /bin/bash harness sudo passwd harness然后把 Harness 的安装目录放在这个用户的家目录下比如/home/harness/app。这样即使服务出问题影响范围也被限制在这个用户内。3.3 安装 Node 运行环境如 Harness 依赖 NodeHarness 的很多版本是基于 Node 生态的所以先装 Node。推荐用 nvm 管理版本避免系统自带 Node 版本太老curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 node -v装完确认版本Node 20 是目前兼容性最好的 LTS 版本。如果你用的是别的运行时比如 Python 或 Go 版本对应替换即可逻辑一样装运行时 → 装依赖 → 拉代码 → 配环境变量。3.4 拉取并初始化 Harness这一步的具体命令取决于你拿到的 Harness 分发形式。常见有两种一种是 git 仓库直接 clone一种是压缩包解压。以 git 为例su - harness git clone harness-repo-url app cd app npm install安装过程中如果遇到setnamedsecurityinfo failed这类权限报错Windows 上常见Linux 上偶发本质是文件权限不对。Linux 下用chown -R harness:harness /home/harness/app修正归属即可。装完后先别急着启动把配置文件里的监听地址改成127.0.0.1端口记下来比如3000。实操心得Harness 首次启动会生成一堆缓存和索引文件第一次启动慢是正常的别以为卡死了。给它两三分钟看日志有没有报错再判断。4. 用 systemd 托管 Harness 进程4.1 为什么不用 nohup 或 screen很多人图省事用nohup npm start 或者 screen 挂后台。短期能用但服务器一重启就没了而且日志管理混乱。systemd 是 Linux 下托管服务的标准方案能开机自启、崩溃自动重启、日志统一管理没有理由不用。4.2 编写 systemd 服务单元创建服务文件sudo nano /etc/systemd/system/harness.service内容如下[Unit] DescriptionDeepseek Harness Service Afternetwork.target [Service] Typesimple Userharness WorkingDirectory/home/harness/app ExecStart/home/harness/.nvm/versions/node/v20.11.0/bin/node /home/harness/app/server.js Restarton-failure RestartSec5 EnvironmentNODE_ENVproduction EnvironmentPORT3000 EnvironmentHOST127.0.0.1 [Install] WantedBymulti-user.target几个关键点解释一下Userharness用专用用户跑不用 root。ExecStart路径要写绝对路径nvm 装的 node 路径每个人不一样用which node查一下。EnvironmentHOST127.0.0.1这是安全核心只监听本地公网访问不到。Restarton-failure崩溃自动拉起配合RestartSec5避免频繁重启。4.3 启动并验证sudo systemctl daemon-reload sudo systemctl enable harness sudo systemctl start harness sudo systemctl status harness看到active (running)就对了。再用curl http://127.0.0.1:3000本地测一下能返回内容说明 Harness 本体正常。如果这里就报错先别往下走看journalctl -u harness -n 50的日志定位问题。5. 反向代理配置Nginx 与 Caddy 双方案5.1 Nginx 方案精细可控先装 Nginxsudo apt install -y nginx创建站点配置/etc/nginx/sites-available/harnessserver { listen 80; server_name your-domain.com; location / { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; 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_read_timeout 300s; } }这里有几个容易踩坑的地方Upgrade和Connection头Harness 如果有 WebSocket 实时通信不加这两行会连不上。proxy_read_timeout大模型响应慢默认 60 秒容易超时调到 300 秒。location /的匹配逻辑Nginx 的 location 有优先级精确匹配 ^~前缀 正则 普通前缀。单站点用/就够多站点分流时才需要精细设计。启用配置sudo ln -s /etc/nginx/sites-available/harness /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginxnginx -t是必做步骤配置语法错误会直接导致 Nginx 起不来。5.2 Caddy 方案省心到极致Caddy 的配置短得让人感动。装好 Caddy 后编辑/etc/caddy/Caddyfileyour-domain.com { reverse_proxy 127.0.0.1:3000 }就这四行。Caddy 会自动申请 Lets Encrypt 证书、自动续期、自动配 HTTPS、自动处理 WebSocket 升级。你唯一要做的就是把域名解析到服务器 IP然后sudo systemctl reload caddy。注意Caddy 自动 HTTPS 需要 80 和 443 端口都开放且域名能正确解析。如果证书申请失败先检查这两点再看journalctl -u caddy的日志。5.3 加一层 Basic Auth 鉴权不管用 Nginx 还是 Caddy都要加鉴权。先装工具生成密码文件sudo apt install -y apache2-utils sudo htpasswd -c /etc/nginx/.htpasswd youruser输入密码后生成文件。Nginx 里加两行auth_basic Restricted; auth_basic_user_file /etc/nginx/.htpasswd;Caddy 里加your-domain.com { basicauth { youruser $2a$14$...生成的哈希... } reverse_proxy 127.0.0.1:3000 }Caddy 的密码哈希用caddy hash-password命令生成。配好后重载服务再访问域名就会弹窗要账号密码输入正确才能进 Harness。6. 常见问题排查与避坑实录6.1 访问报 404 Not Found (nginx)这是最经典的报错。原因通常是location没匹配上或者proxy_pass路径写错。排查顺序确认server_name和你的域名一致。确认location /存在且没被其他规则覆盖。确认proxy_pass指向的端口和 Harness 实际监听端口一致。sudo nginx -t看语法sudo tail -f /var/log/nginx/error.log看实时错误。6.2 HTTPS 证书报 net::err_cert_common_name_invalid这个错误说明证书的域名和你访问的域名不匹配。常见于证书是给a.com签的你却用b.com访问。解决方法是确保证书域名和访问域名完全一致Caddy 用户检查 Caddyfile 里的域名拼写Nginx 用户检查 certbot 申请时填的域名。6.3 Harness 无法安装或启动即退出先看日志journalctl -u harness -n 100。常见原因Node 版本不匹配换到推荐版本。依赖没装全重新npm install。端口被占用ss -tlnp | grep 3000查一下谁占了。权限问题确认文件和目录归属harness用户。6.4 离线局域网能不能用可以。Harness 本体和大部分插件都是本地运行的只要不依赖外部 API纯离线环境完全能跑。但要注意离线环境下自动 HTTPS 用不了Caddy 的证书申请会失败这时候要么用自签证书要么干脆内网用 HTTP内网风险可控。6.5 常见问题速查表现象可能原因解决方向404 Not Foundlocation 未匹配 / 端口错检查 Nginx 配置和端口502 Bad GatewayHarness 没起来查 systemd 状态和日志证书域名不匹配证书与访问域名不一致重新签发对应域名证书连接超时防火墙未放行 / 超时太短开端口调大 timeout弹窗鉴权失败密码文件路径错检查 htpasswd 路径和权限WebSocket 连不上缺 Upgrade 头补 proxy_set_header7. 上线后的维护与安全加固7.1 日志与监控Nginx 的访问日志在/var/log/nginx/access.log错误日志在error.log。Windows 下想看 Nginx 日志可以用文本工具直接开Linux 下我习惯tail -f实时盯。Harness 自己的日志走 systemdjournalctl -u harness -f就能实时看。7.2 定期更新与备份Harness 更新频繁建议每月检查一次。更新前先备份配置和技能文件tar -czf backup.tar.gz /home/harness/app/config。更新流程停服务 → 拉新代码 → 装依赖 → 起服务 → 验证。7.3 安全加固清单关闭不必要的端口只留 80、443 和 SSH。SSH 禁用密码登录改用密钥。定期更新系统和依赖。Basic Auth 密码用强密码别用生日。有条件的话加一层 fail2ban防暴力破解。8. 我踩过的几个真实坑第一个坑是端口监听地址。我一开始图省事让 Harness 监听0.0.0.0结果有次配置失误服务直接裸奔在公网被扫描器扫到疯狂请求。后来改成127.0.0.1只让代理转发世界清净了。第二个坑是超时设置。Harness 处理长任务时响应很慢Nginx 默认 60 秒超时导致我经常看到 504。把proxy_read_timeout调到 300 秒后解决。这个参数没有标准答案看你任务复杂度宁可调大别调小。第三个坑是Caddy 证书申请失败。折腾半天发现是域名解析还没生效就急着 reloadCaddy 申请证书失败后会有冷却期。正确做法是等 DNS 生效dig your-domain.com确认再启动 Caddy。第四个坑是权限问题。Harness 读写技能文件时如果权限不对会报各种莫名其妙的错误。统一用chown -R harness:harness修正归属比一个个改权限靠谱得多。这套流程我从头到尾搭过三遍每遍都会发现新的细节。核心就一句话Harness 只监听本地代理负责对外鉴权必须加HTTPS 不能省。把这四点做到位剩下的就是按日志排错。你要是卡在某一步先别怀疑方案八成是某个参数或路径写错了对着日志一行行看基本都能定位。
1. 为什么要在云服务器上折腾 Deepseek Harness先把话说在前头Deepseek Harness 不是一个“下载完双击就能跑”的桌面软件它更像是一套围绕大模型能力构建的工作台把提示词编排、技能Skill加载、文件读写、代码回退、插件扩展这些能力串成一条链。你在本地跑图的是方便你把它搬到云服务器上图的是随时随地能访问、算力集中、多人协作、数据不丢。这两件事的诉求完全不一样。我自己最早是在一台旧笔记本上跑 Harness结果遇到三个绕不过去的坎第一笔记本一合盖服务就断远程根本连不上第二本地模型和插件一多内存直接吃满风扇狂转第三换台电脑就得重新配一遍环境提示词和技能文件还得手动拷。后来我把整套东西迁到云服务器用 Nginx 或 Caddy 做反向代理加上一层公网鉴权才算真正稳定下来。这套流程跑通之后我在任何一台设备上打开浏览器就能用体验完全是两个档次。这篇文章要解决的核心问题就一个怎么把 Deepseek Harness 部署到云服务器上并且通过公网安全地访问它。我会把选型逻辑、环境准备、反向代理配置、鉴权方案、常见报错排查全部拆开讲。适合两类人看一类是有点 Linux 基础、想自己搭一套私有 AI 工作台的开发者另一类是已经在本地用过 Harness、想把它搬到公网但卡在鉴权和反代上的朋友。哪怕你之前只会在宝塔面板里点按钮跟着走也能落地。需要提前说明的是Harness 这类工具的版本迭代比较快具体的安装命令和插件市场入口可能随版本变化。我下面给出的是一套通用性最强、经过验证的部署骨架核心思路进程托管 反向代理 鉴权 HTTPS不会过时你把这套骨架搭好具体版本差异只是换几个参数的事。2. 部署前的整体设计与选型思路2.1 为什么是“云服务器 反向代理 鉴权”这套组合很多人第一反应是Harness 自己不是带 Web 界面吗直接开放端口不就行了理论上可以但实操中非常危险。Harness 的 Web 服务默认监听在某个端口常见是 3000、8080 这类它本身不带强鉴权一旦你把端口直接暴露到公网等于把工作台大门敞开。扫描器几分钟就能发现你然后就是各种探测请求。所以正确的架构是三层第一层Harness 本体跑在服务器本地只监听127.0.0.1不对外。第二层反向代理Nginx 或 Caddy对外监听 80/443负责转发请求、处理 HTTPS、做访问控制。第三层鉴权在反向代理层加 Basic Auth 或者更细的访问策略把未授权请求挡在门外。这样做的逻辑很清晰Harness 只管干活代理只管守门职责分离。就算 Harness 本身有漏洞攻击面也被压缩到最小。2.2 Nginx 还是 Caddy到底怎么选这是被问得最多的问题。我的结论是新手和追求省事的选 Caddy需要精细控制和复杂规则的选 Nginx。对比维度NginxCaddyHTTPS 证书需手动配 certbot 或 acme.sh自动申请续期零配置配置文件语法灵活但略繁琐极简几行搞定反向代理成熟稳定生态大同样稳定配置更短鉴权支持 Basic Auth、auth_request支持 Basic Auth插件丰富适用场景复杂路由、多站点、高并发单站点、快速上线、自动 HTTPS如果你只是部署一个 HarnessCaddy 的配置文件可能就五六行证书自动搞定省心到离谱。但如果你后面还要在同一台服务器上跑别的服务、做多域名分流、配复杂的 location 规则Nginx 的灵活性会更占优。我自己的做法是单服务用 Caddy多服务混布用 Nginx。下面两套配置我都会给。2.3 鉴权方案的选择逻辑公网访问必须鉴权这点没有商量余地。常见方案有三种Basic Auth最简单浏览器弹窗输入账号密码。缺点是密码明文传输靠 HTTPS 保护体验一般但胜在零依赖、配置快。Token / API Key适合程序调用浏览器访问不友好。统一身份认证如 OAuth最安全但配置复杂个人项目没必要。对个人和小团队来说Basic Auth HTTPS是性价比最高的组合。HTTPS 保证传输加密Basic Auth 保证访问控制两层叠加足够挡住 99% 的未授权访问。下面实操部分我会重点讲这个。3. 云服务器环境准备与 Harness 安装3.1 服务器规格与系统选择Harness 本身对 CPU 要求不高但如果要接本地模型或者跑重插件内存和磁盘才是瓶颈。我的建议配置CPU2 核起步4 核更稳内存4GB 是底线8GB 推荐插件和缓存很吃内存磁盘40GB 起步模型文件大的话按需加系统Ubuntu 22.04 LTS 或 CentOS 9 都行我个人更推荐 Ubuntu社区资料多踩坑少系统装好后第一件事是更新源并装基础工具sudo apt update sudo apt upgrade -y sudo apt install -y curl wget git unzip build-essential注意不要用 root 直接跑 Harness 服务后面我们会创建一个专用用户这是安全底线。3.2 创建专用运行用户用 root 跑服务是很多人的坏习惯一旦服务被攻破整台机器就沦陷了。正确做法是建一个低权限用户sudo useradd -m -s /bin/bash harness sudo passwd harness然后把 Harness 的安装目录放在这个用户的家目录下比如/home/harness/app。这样即使服务出问题影响范围也被限制在这个用户内。3.3 安装 Node 运行环境如 Harness 依赖 NodeHarness 的很多版本是基于 Node 生态的所以先装 Node。推荐用 nvm 管理版本避免系统自带 Node 版本太老curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 node -v装完确认版本Node 20 是目前兼容性最好的 LTS 版本。如果你用的是别的运行时比如 Python 或 Go 版本对应替换即可逻辑一样装运行时 → 装依赖 → 拉代码 → 配环境变量。3.4 拉取并初始化 Harness这一步的具体命令取决于你拿到的 Harness 分发形式。常见有两种一种是 git 仓库直接 clone一种是压缩包解压。以 git 为例su - harness git clone harness-repo-url app cd app npm install安装过程中如果遇到setnamedsecurityinfo failed这类权限报错Windows 上常见Linux 上偶发本质是文件权限不对。Linux 下用chown -R harness:harness /home/harness/app修正归属即可。装完后先别急着启动把配置文件里的监听地址改成127.0.0.1端口记下来比如3000。实操心得Harness 首次启动会生成一堆缓存和索引文件第一次启动慢是正常的别以为卡死了。给它两三分钟看日志有没有报错再判断。4. 用 systemd 托管 Harness 进程4.1 为什么不用 nohup 或 screen很多人图省事用nohup npm start 或者 screen 挂后台。短期能用但服务器一重启就没了而且日志管理混乱。systemd 是 Linux 下托管服务的标准方案能开机自启、崩溃自动重启、日志统一管理没有理由不用。4.2 编写 systemd 服务单元创建服务文件sudo nano /etc/systemd/system/harness.service内容如下[Unit] DescriptionDeepseek Harness Service Afternetwork.target [Service] Typesimple Userharness WorkingDirectory/home/harness/app ExecStart/home/harness/.nvm/versions/node/v20.11.0/bin/node /home/harness/app/server.js Restarton-failure RestartSec5 EnvironmentNODE_ENVproduction EnvironmentPORT3000 EnvironmentHOST127.0.0.1 [Install] WantedBymulti-user.target几个关键点解释一下Userharness用专用用户跑不用 root。ExecStart路径要写绝对路径nvm 装的 node 路径每个人不一样用which node查一下。EnvironmentHOST127.0.0.1这是安全核心只监听本地公网访问不到。Restarton-failure崩溃自动拉起配合RestartSec5避免频繁重启。4.3 启动并验证sudo systemctl daemon-reload sudo systemctl enable harness sudo systemctl start harness sudo systemctl status harness看到active (running)就对了。再用curl http://127.0.0.1:3000本地测一下能返回内容说明 Harness 本体正常。如果这里就报错先别往下走看journalctl -u harness -n 50的日志定位问题。5. 反向代理配置Nginx 与 Caddy 双方案5.1 Nginx 方案精细可控先装 Nginxsudo apt install -y nginx创建站点配置/etc/nginx/sites-available/harnessserver { listen 80; server_name your-domain.com; location / { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; 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_read_timeout 300s; } }这里有几个容易踩坑的地方Upgrade和Connection头Harness 如果有 WebSocket 实时通信不加这两行会连不上。proxy_read_timeout大模型响应慢默认 60 秒容易超时调到 300 秒。location /的匹配逻辑Nginx 的 location 有优先级精确匹配 ^~前缀 正则 普通前缀。单站点用/就够多站点分流时才需要精细设计。启用配置sudo ln -s /etc/nginx/sites-available/harness /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginxnginx -t是必做步骤配置语法错误会直接导致 Nginx 起不来。5.2 Caddy 方案省心到极致Caddy 的配置短得让人感动。装好 Caddy 后编辑/etc/caddy/Caddyfileyour-domain.com { reverse_proxy 127.0.0.1:3000 }就这四行。Caddy 会自动申请 Lets Encrypt 证书、自动续期、自动配 HTTPS、自动处理 WebSocket 升级。你唯一要做的就是把域名解析到服务器 IP然后sudo systemctl reload caddy。注意Caddy 自动 HTTPS 需要 80 和 443 端口都开放且域名能正确解析。如果证书申请失败先检查这两点再看journalctl -u caddy的日志。5.3 加一层 Basic Auth 鉴权不管用 Nginx 还是 Caddy都要加鉴权。先装工具生成密码文件sudo apt install -y apache2-utils sudo htpasswd -c /etc/nginx/.htpasswd youruser输入密码后生成文件。Nginx 里加两行auth_basic Restricted; auth_basic_user_file /etc/nginx/.htpasswd;Caddy 里加your-domain.com { basicauth { youruser $2a$14$...生成的哈希... } reverse_proxy 127.0.0.1:3000 }Caddy 的密码哈希用caddy hash-password命令生成。配好后重载服务再访问域名就会弹窗要账号密码输入正确才能进 Harness。6. 常见问题排查与避坑实录6.1 访问报 404 Not Found (nginx)这是最经典的报错。原因通常是location没匹配上或者proxy_pass路径写错。排查顺序确认server_name和你的域名一致。确认location /存在且没被其他规则覆盖。确认proxy_pass指向的端口和 Harness 实际监听端口一致。sudo nginx -t看语法sudo tail -f /var/log/nginx/error.log看实时错误。6.2 HTTPS 证书报 net::err_cert_common_name_invalid这个错误说明证书的域名和你访问的域名不匹配。常见于证书是给a.com签的你却用b.com访问。解决方法是确保证书域名和访问域名完全一致Caddy 用户检查 Caddyfile 里的域名拼写Nginx 用户检查 certbot 申请时填的域名。6.3 Harness 无法安装或启动即退出先看日志journalctl -u harness -n 100。常见原因Node 版本不匹配换到推荐版本。依赖没装全重新npm install。端口被占用ss -tlnp | grep 3000查一下谁占了。权限问题确认文件和目录归属harness用户。6.4 离线局域网能不能用可以。Harness 本体和大部分插件都是本地运行的只要不依赖外部 API纯离线环境完全能跑。但要注意离线环境下自动 HTTPS 用不了Caddy 的证书申请会失败这时候要么用自签证书要么干脆内网用 HTTP内网风险可控。6.5 常见问题速查表现象可能原因解决方向404 Not Foundlocation 未匹配 / 端口错检查 Nginx 配置和端口502 Bad GatewayHarness 没起来查 systemd 状态和日志证书域名不匹配证书与访问域名不一致重新签发对应域名证书连接超时防火墙未放行 / 超时太短开端口调大 timeout弹窗鉴权失败密码文件路径错检查 htpasswd 路径和权限WebSocket 连不上缺 Upgrade 头补 proxy_set_header7. 上线后的维护与安全加固7.1 日志与监控Nginx 的访问日志在/var/log/nginx/access.log错误日志在error.log。Windows 下想看 Nginx 日志可以用文本工具直接开Linux 下我习惯tail -f实时盯。Harness 自己的日志走 systemdjournalctl -u harness -f就能实时看。7.2 定期更新与备份Harness 更新频繁建议每月检查一次。更新前先备份配置和技能文件tar -czf backup.tar.gz /home/harness/app/config。更新流程停服务 → 拉新代码 → 装依赖 → 起服务 → 验证。7.3 安全加固清单关闭不必要的端口只留 80、443 和 SSH。SSH 禁用密码登录改用密钥。定期更新系统和依赖。Basic Auth 密码用强密码别用生日。有条件的话加一层 fail2ban防暴力破解。8. 我踩过的几个真实坑第一个坑是端口监听地址。我一开始图省事让 Harness 监听0.0.0.0结果有次配置失误服务直接裸奔在公网被扫描器扫到疯狂请求。后来改成127.0.0.1只让代理转发世界清净了。第二个坑是超时设置。Harness 处理长任务时响应很慢Nginx 默认 60 秒超时导致我经常看到 504。把proxy_read_timeout调到 300 秒后解决。这个参数没有标准答案看你任务复杂度宁可调大别调小。第三个坑是Caddy 证书申请失败。折腾半天发现是域名解析还没生效就急着 reloadCaddy 申请证书失败后会有冷却期。正确做法是等 DNS 生效dig your-domain.com确认再启动 Caddy。第四个坑是权限问题。Harness 读写技能文件时如果权限不对会报各种莫名其妙的错误。统一用chown -R harness:harness修正归属比一个个改权限靠谱得多。这套流程我从头到尾搭过三遍每遍都会发现新的细节。核心就一句话Harness 只监听本地代理负责对外鉴权必须加HTTPS 不能省。把这四点做到位剩下的就是按日志排错。你要是卡在某一步先别怀疑方案八成是某个参数或路径写错了对着日志一行行看基本都能定位。
