Docker 部署 Harness 到服务器，持久化与端口冲突处理

为什么选 Docker 部署 Harness在团队服务器或 CI 环境里跑 DeepSeek HarnessDocker 几乎是首选方案。它把 Node.js 运行时、依赖和 Harness 本身打包成一个整体避免了我本地能跑的经典困境。更重要的是服务器场景通常需要多实例共存、数据持久化、快速回滚这些正是容器化的强项。官方提供了源码安装、npx 快速体验等多种方式但在服务器上长期运行直接拉镜像最省心。目前社区维护的镜像ghcr.io/huoxue1/deepseek-harness:latest已经比较成熟下文以此为基础展开。官方镜像与社区镜像的选择DeepSeek 官方仓库目前主要提供源码和 npm 包没有直接维护 Docker 镜像。社区镜像填补了这个空白基于官方源码构建核心功能一致。选择社区镜像时建议关注两点镜像更新频率是否与官方版本同步以及是否暴露了必要的持久化目录。当前可用的快速启动命令如下docker run -d \ --name dsh \ -p 3080:3080 \ -v dsh-data:/root/.dsh \ ghcr.io/huoxue1/deepseek-harness:latest这条命令能跑起来但离生产环境的要求还差得远。下面逐层拆解。docker run 完整参数详解端口映射与多实例分配Harness 默认监听3080端口。单台服务器部署多个实例时需要规划端口池。建议按项目或团队划分避免冲突实例用途宿主机端口容器端口命名开发环境30803080dsh-dev测试环境30813080dsh-testCI 专用30823080dsh-ci启动第二个实例时只需改映射端口docker run -d \ --name dsh-test \ -p 3081:3080 \ -v dsh-test-data:/root/.dsh \ ghcr.io/huoxue1/deepseek-harness:latest注意Harness 容器内端口固定为3080修改需要传入环境变量或改配置不如直接映射宿主机端口来得直接。数据卷挂载路径规划Harness 的运行数据默认存放在容器内的/root/.dsh目录包含.credentials.yaml—— API Key 等敏感配置会话日志与 Trajectory 数据插件缓存与运行时状态推荐做法使用命名卷而非 bind mount便于备份和迁移。# 创建独立卷 docker volume create dsh-prod-data # 启动时挂载 docker run -d \ --name dsh-prod \ -p 3080:3080 \ -v dsh-prod-data:/root/.dsh \ ghcr.io/huoxue1/deepseek-harness:latest如果需要将数据落盘到指定路径如挂载到 NAS改用 bind mount-v /mnt/nas/dsh-data:/root/.dsh容器内 Node.js 版本锁定社区镜像基于特定 Node.js 版本构建。若对版本有严格要求可以在启动时覆盖但更稳妥的做法是自建镜像FROM node:22.19-slim # 基于官方要求的 v22.19 版本 COPY --fromghcr.io/huoxue1/deepseek-harness:latest /app /app WORKDIR /app CMD [node, apps/cli/src/bin.ts, web]不过多数情况下直接使用社区镜像即可其内部已锁定兼容版本。docker-compose 生产示例单机多实例场景下docker-compose 比裸写docker run更易维护。以下是一个完整示例version: 3.8 services: dsh-dev: image: ghcr.io/huoxue1/deepseek-harness:latest container_name: dsh-dev ports: - 3080:3080 volumes: - dsh-dev-data:/root/.dsh environment: - NODE_ENVdevelopment restart: unless-stopped healthcheck: test: [CMD, curl, -f, http://localhost:3080/health] interval: 30s timeout: 10s retries: 3 start_period: 40s dsh-test: image: ghcr.io/huoxue1/deepseek-harness:latest container_name: dsh-test ports: - 3081:3080 volumes: - dsh-test-data:/root/.dsh environment: - NODE_ENVproduction restart: unless-stopped healthcheck: test: [CMD, curl, -f, http://localhost:3080/health] interval: 30s timeout: 10s retries: 3 start_period: 40s volumes: dsh-dev-data: dsh-test-data:几点设计考量命名卷隔离每个实例独立存储避免数据串扰健康检查Harness 启动需要一定时间start_period给足 40 秒缓冲自动重启unless-stopped策略适合长期运行的服务健康检查探针配置Harness 启动后Web UI 可用并不代表服务完全就绪。建议配置多层健康检查容器层面docker-compose 已示例healthcheck: test: [CMD, curl, -f, http://localhost:3080/health] interval: 30s timeout: 10s retries: 3应用层面首次启动后访问http://host:port确认能加载界面再进入 Settings → Models 配置 API Key。如果页面能打开但输入框灰色通常是工作区未选择这不是容器问题。监控层面可以写一个简单的外部探针脚本定期验证 API 响应#!/bin/bash # check-harness.sh for port in 3080 3081 3082; do status$(curl -s -o /dev/null -w %{http_code} http://localhost:$port 2/dev/null) if [ $status ! 200 ]; then echo $(date): Harness on port $port unhealthy /var/log/harness-health.log fi done加入 crontab 每分钟执行就能实现基础监控。与宿主机 pnpm 缓存共享的取舍这是一个容易踩坑的点。有些同学为了加速依赖安装想把宿主机的 pnpm store 挂进容器# 不推荐的做法 -v ~/.pnpm-store:/root/.pnpm-store问题Harness 镜像是预构建的运行时不需要再安装依赖。挂载 pnpm 缓存不仅无收益还可能因为权限问题导致启动失败。Node.js 的node_modules已在镜像构建阶段固化运行时只读写/root/.dsh下的配置和数据。唯一需要缓存的场景你基于源码自行构建镜像时可以在 Dockerfile 的多阶段构建中利用 pnpm 缓存层。运行容器时保持简单只挂数据卷即可。一键启动脚本把上述实践封装成脚本方便团队快速部署#!/bin/bash # deploy-harness.sh # Usage: ./deploy-harness.sh instance-name host-port INSTANCE_NAME${1:-dsh} HOST_PORT${2:-3080} docker volume create ${INSTANCE_NAME}-data 2/dev/null || true docker run -d \ --name ${INSTANCE_NAME} \ -p ${HOST_PORT}:3080 \ -v ${INSTANCE_NAME}-data:/root/.dsh \ --restart unless-stopped \ --health-cmd curl -f http://localhost:3080/health || exit 1 \ --health-interval 30s \ --health-timeout 10s \ --health-retries 3 \ ghcr.io/huoxue1/deepseek-harness:latest echo Harness deployed: http://localhost:${HOST_PORT} echo Data volume: ${INSTANCE_NAME}-data保存后赋予执行权限chmod x deploy-harness.sh然后# 部署开发实例 ./deploy-harness.sh dsh-dev 3080 # 部署测试实例 ./deploy-harness.sh dsh-test 3081常见问题排查清单现象可能原因排查步骤容器启动后立即退出端口被占用或权限不足docker logs name查看检查端口占用lsof -i :3080Web 页面打不开防火墙或绑定地址问题确认docker ps状态为 Up尝试curl localhost:3080输入框灰色无法使用未选择工作区点击界面选择工作区指定一个目录API Key 保存后消失正常脱敏显示检查~/.dsh/.credentials.yaml是否存在多实例数据混乱卷挂载冲突docker inspect name确认Mounts指向不同卷健康检查一直失败启动时间不足或探针地址错调大start_period确认 Harness 实际监听地址遇到启动问题时先抓日志总是没错的docker logs -f dsh-dev --tail 100如果日志显示Server running at http://127.0.0.1:3080但外部无法访问检查是否绑定了127.0.0.1而非0.0.0.0。社区镜像通常已处理这个问题但自定义构建时需要留意。最后的一点建议服务器部署 Harness核心就三件事端口规划好、数据持久化、健康检查到位。Docker 降低了环境一致性问题的复杂度但容器化不等于免维护。建议把 docker-compose 文件纳入版本管理配合简单的监控脚本就能在团队内部署一套稳定可用的 Harness 服务。如果后续需要扩展多机部署这套配置也能平滑迁移到 Kubernetes只需把卷换成 PVC、健康检查换成 Probe 资源即可。