Docker部署DeepSeek Harness：搭建局域网私有AI Agent平台

先说结论这个方案我实测跑通了而且比我预想的轻松不少。如果你手头有一台配置还行的机器想在公司或家里局域网内搞一个私有 AI Agent 平台用 Docker 部署 DeepSeek Harness 确实是一条非常顺的路。它能让你用自己的算力跑大模型搭建一个可供多人访问的 Agent 服务不依赖外部网络数据也不出内网。这篇文章我会把整个部署链路拆开讲清楚包括前置条件、编排文件撰写、模型接入、Agent 配置、局域网暴露以及我实际踩过的坑和排查经验尽量做到你照着操作就能复现。1. 先理清楚这个项目到底解决什么问题1.1 什么是 DeepSeek HarnessDeepSeek Harness 这个名字听起来有点抽象说白了它就是一个围绕 DeepSeek 系列模型打造的部署与管理框架核心任务是把模型推理、API 服务、Agent 调度、Web 交互界面这些组件整合到一个统一环境里。传统做法是你要分别部署模型推理服务、写后端逻辑、搭前端页面再把 Agent 工具链接进去链路很长环境依赖也容易冲突。Harness 的思路就是把这一整套东西做成开箱即用的组合件配合 Docker 后你不用在自己系统里装一堆 Python 包和 CUDA 环境直接拉镜像、起容器就行。从实际使用来看它的定位更像是一个“AI Agent 平台”的底座底层接模型推理中间层提供 API 网关和会话管理上层提供可视化面板。很多开源项目会把这类功能拆成多个子项目而 Harness 类工具通常倾向于集成这对局域网内快速搭一套服务来说非常友好因为你不需要自己从头组装各个模块。1.2 为什么是 Docker 而不是裸机部署我在早期折腾大模型本地化的时候习惯直接在物理机上配环境装 Python 3.10、安装 CUDA toolkit、逐个 pip install 依赖还要手工管理模型权重文件的路径。这套流程偶尔能用但一旦要迁移到另一台机器或者帮同事部署一套副本问题就会集中爆发CUDA 版本对不上、依赖包互相冲突、系统环境被改得乱七八糟。Docker 最大的价值在于把环境本身也当作代码的一部分。PyTorch 版本、CUDA 运行时、模型推理框架、Web 服务这些全部固化在镜像里宿主机只需要有 NVIDIA 驱动和 Docker 运行时就能跑。docker-compose 可以把模型服务、Agent 服务、前端面板定义成一整套服务编排一条命令拉起全部组件。对于局域网这种场景团队里不同人的机器环境千奇百怪用 Docker 统一部署能省掉大量“在我机器上是好的”这种扯皮问题。另一个实际原因是资源隔离。模型推理尤其吃显存如果和其他应用混装在一台物理机上一个服务崩溃或者内存泄漏很容易拖垮整机。容器化之后模型服务的内存、显存分配都能限制在可控范围内其他服务不受连带影响。1.3 局域网部署的三个典型场景第一类是团队内部工具。比如一个几十人的技术团队不是每个人都有独立显卡或大内存机器通过局域网共享一个 AI Agent 平台大家可以在同一个服务上做代码解释、文档问答、SQL 生成这些任务。第二类是个人知识库与自动化助手把 Agent 接上内网的 Wiki、工单系统或者笔记库让它在私有数据范围内执行问答和归纳数据不用传到外部 API。第三类是开发测试环境工程师在本地写 Agent 应用需要一个兼容 OpenAI 协议的后端服务来调试局域网部署可以提供一个稳定的测试桩。这三种场景对基础设施的要求其实是一样的模型服务要稳定、接口协议要兼容、访问要足够快。DeepSeek Harness 配合 Docker 正好覆盖了这些需求这也是我推荐这个方案的根本原因。2. 部署前准备环境、镜像与网络规划2.1 硬件确实有门槛但没有想象中那么高很多人在本地部署 AI 模型时第一反应是“我的机器行不行”。我实测下来的感受是如果只是跑 7B 级别的量化模型一台 16GB 内存、6GB 显存的 GPU 机器就能比较流畅地跑如果没有独显纯 CPU 推理也能用只是响应速度会慢一些适合非实时场景。如果是 14B、32B 级别模型建议显存至少在 12GB 以上否则量化后效果和速度会明显受影响。需要注意的是Docker 本身不直接使用 GPU需要 NVIDIA Container Toolkit 的支持。这个工具让容器内能看到宿主的 GPU 设备从而调用 CUDA。所以硬件层面的门槛实际上是两块主机要有 NVIDIA 显卡且驱动装好同时要装好 nvidia-container-toolkit 这个中间层。内存方面除了模型权重占用的显存外加载模型时的临时内存开销也不小。运行 7B 模型建议系统内存不少于 16GB其中一部分会被页面缓存和推理框架占用。磁盘则建议预留至少 20GB 空间因为镜像本身就有好几个 GB模型权重文件又是 GB 级起步。2.2 安装 Docker 环境含 Compose宿主机系统我用的是 Ubuntu Server 22.04这也是社区里遇到问题最少的环境。安装 Docker 本身不算复杂先更新 apt 索引然后安装依赖包再添加 Docker 官方源的 GPG key 和仓库最后安装 docker-ce 和 docker-compose-plugin。如果你用的是桌面发行版可以直接用官方安装脚本但生产环境我更推荐手动走一遍仓库安装流程心里有底。装完之后确认一下 Docker 服务状态并把自己的用户加入 docker 组这样不用每次敲命令都加 sudo。这一步容易忽略但实际使用中非常影响体验。接着是 NVIDIA Container Toolkit。同样是走 apt 仓库安装装完后要重启 Docker 服务。验证方式很简单跑一个带 CUDA 的测试镜像执行nvidia-smi如果能正常显示 GPU 信息就说明透传没问题。这一步是整个部署链路里最容易出问题的地方也是很多“镜像能起但模型用不了”的根源。2.3 镜像选型与版本锁定策略DeepSeek Harness 的镜像仓库里通常会提供几种 tag带 CUDA 的完整版、纯 CPU 版、以及按模型尺寸区分的推理镜像。建议根据你本机 GPU 显存来选择不要无脑拉最新版因为新版镜像往往默认面向较新的硬件和驱动。一个重要的经验是版本锁定。docker-compose 文件里镜像 tag 不要写latest而要写明确的版本号。原因是 AI 领域的镜像更新非常频繁今天能跑通的编排下周可能因为底层依赖变化就启动失败。锁版本虽然会牺牲一些新功能但对稳定优先的局域网内部平台来说可控性比新特性重要得多。image: deepseek-harness/api-server:v0.6.2 image: deepseek-harness/web-ui:v0.6.2另外还需要考虑模型权重文件放在哪里。镜像里不可能内置几个 GB 的权重通常的做法是通过数据卷挂载宿主机目录把权重文件和镜像解耦。这样做的好处是升级镜像时不用重新下载模型数据坏处是如果没规划好挂载路径容器升级后找不到模型排查起来比较绕。3. 实操开始docker-compose 一键拉起平台3.1 目录结构与数据持久化设计动手前先把目录规划好。我的习惯是建一个deepseek-harness/目录下面区分models/、data/、config/、logs/几个子目录。models/存放下载的模型权重data/存放向量库、会话记录、Agent 日志等运行时数据config/放各类配置文件logs/则用于集中收集日志。这种规划在容器化部署里不是可有可无的优雅而是必需品。因为容器本身是无状态的重启后所有写入容器层的数据都会丢失只有挂载到宿主机目录的数据能保留。如果你跑了一段时间后才发现会话记录全部没保存那基本就是没做持久化的后果。在编排文件里每个服务都需要挂载对应的卷。比如模型服务挂载./models:/models向量数据库挂载./data/chroma:/data/chroma前端配置挂载./config:/app/config。这样无论容器怎么重建数据都安安稳稳待在宿主机上。3.2 编排文件怎么写docker-compose.yml 是这个方案的核心。我给出的结构分为四个服务模型推理服务、API 网关服务、Agent 调度服务、Web UI 服务。模型推理服务是底座它加载 DeepSeek 权重并暴露一个 OpenAI 兼容的接口API 网关负责鉴权、限流和路由Agent 调度服务利用函数调用能力去执行工具Web UI 则是用户直接操作的前端面板。services: model-server: image: deepseek-harness/model-server:v0.6.2 runtime: nvidia environment: - NVIDIA_VISIBLE_DEVICESall - MODEL_PATH/models/deepseek-7b-q4.gguf - CONTEXT_LENGTH4096 - MAX_GPU_MEMORY10GiB volumes: - ./models:/models ports: - 8001:8001 deploy: resources: limits: memory: 16G api-gateway: image: deepseek-harness/api-server:v0.6.2 environment: - MODEL_ENDPOINThttp://model-server:8001 - API_KEYsk-local-xxxx depends_on: - model-server ports: - 8080:8080 agent-worker: image: deepseek-harness/agent-worker:v0.6.2 environment: - GATEWAY_ENDPOINThttp://api-gateway:8080 - TOOL_PLUGINScode_interpreter,web_search,db_query depends_on: - api-gateway volumes: - ./data:/data web-ui: image: deepseek-harness/web-ui:v0.6.2 environment: - GATEWAY_ENDPOINThttp://api-gateway:8080 depends_on: - api-gateway ports: - 3000:3000注意几个关键点。runtime: nvidia让模型服务能访问 GPU但这依赖前面装的 NVIDIA Container Toolkit。MODEL_PATH指定容器内可见的模型文件路径对应宿主机挂载进去的权重。CONTEXT_LENGTH控制上下文窗口大小值越大模型可记忆的对话内容越多但显存消耗也越大初始阶段不建议直接拉满。API_KEY是网关的访问凭证局域网里虽然相对安全但认证这一层不能省。depends_on只控制启动顺序不保证依赖服务已经就绪。比如 API 网关启动了但模型服务还在加载权重网关去请求模型接口时还是会失败。解决这个问题有两个思路一是在应用层做重试二是用 healthcheck 让容器真正就绪后才开始依赖。完整的编排文件里建议加上健康检查否则首次启动经常出现 Web UI 连不上网关的情况。3.3 模型接入本地权重还是远程 APIDeepSeek Harness 支持两种模型接入方式。第一种是把模型文件下载到本地通过模型推理服务加载。这种方式适合内网环境断网也能跑数据不出内网但需要你有足够的磁盘下载权重文件且机器要有推理能力。第二种是接入 DeepSeek 官方 API也就是 Harness 本身只作为网关和管理层实际推理发生在远程服务端。这种方式几乎不占本地算力部署门槛低但数据会发送到外部服务不适合敏感数据场景。局域网私有化部署肯定是优先选本地权重。下载模型这一步我建议用专用于模型下载的工具比如从 Hugging Face 仓库拉取会自带断点续传和并发下载比浏览器直接下载靠谱得多。选择模型文件时注意看量化标记Q4_K_M 这种类型的文件在显存占用和效果之间比较平衡7B 模型大约 4.5GB显存 8GB 的机器就能跑得比较稳。放好权重后修改 model-server 的环境变量指向正确的路径即可。如果你的机器显存比较小可以调整MAX_GPU_MEMORY让部分层走 CPU offload速度会慢一些但至少能跑起来。3.4 Agent 怎么配置才真正能用起来Agent 不是简单地起一个服务就完事了关键在于工具插件的注册和提示词模板。Harness 框架内置了一个工具描述机制模型通过工具描述知道当前环境里有哪些可用的工具以及怎么调用它们。比如配置了code_interpreter用户让 Agent 算个数据分布Agent 就会生成一段 Python 代码交到代码解释器工具执行再把执行结果汇总回答。当你配置完TOOL_PLUGINS环境变量后还要在管理面板里逐个确认工具是否注册成功。提示词模板同样重要。如果你只是搭起来就丢给团队用Agent 大概率行为非常僵硬。Harness 管理界面的提示词编辑区域可以让管理员自定义系统级提示词。比如你的团队主要是数据分析用途可以把系统提示词写成“你是数据分析助手当用户提出数据处理请求时优先主动调用 code_interpreter 工具执行 Python 代码并解释结果”。这个设置会直接影响模型生成内容的风格和工具调用倾向。还要注意对话历史管理的设置。默认情况下 Harness 会把整个会话的历史全都发送给模型上下文窗口不设限的话对话超过一定轮数后请求体积会越来越大响应时长也会显著上升。建议在配置中开启“会话摘要”或者设置最大历史轮数比如只保留最近 10 轮完整消息更早的内容自动压缩为摘要这样能保持长时间对话的响应速度。4. 局域网暴露与日常使用4.1 让局域网设备访问平台docker-compose 里已经把端口映射出来了但这只是第一步。要让局域网里的其他设备访问还要确保防火墙规则没有拦掉这些端口。我用的是 UFW需要显式放行 3000、8080、8001 端口。如果没有做这一步服务在宿主机上看起来一切都正常但其他机器访问时就是超时非常容易让人误判问题出在容器上。如果你希望团队成员通过一个好记的地址访问比如ai.local而不是记忆 IP 加端口可以考虑在内网 DNS 服务器里加一条 A 记录或者在每个客户端上改 hosts。这个看团队规模人少时直接发一个带端口链接就够了人多起来还是建议上个内网 DNS。需要注意 Docker 默认的 bridge 网络映射在重启后 IP 可能变化好在端口映射本身绑定的是宿主机 IP只要通过宿主机地址加端口访问就不受容器 IP 变化影响。所以没有必要为了固定 IP 去折腾 Macvlan除非你有端口之外的网络隔离需求。4.2 日志与监控容器化部署的排查全靠日志所以日志策略要提前想清楚。Docker 默认的 json-file 日志驱动如果不加限制长期运行后会把宿主机的磁盘塞满。我强烈建议在 docker-compose 里给每个服务加上 logging 配置设置最大日志文件大小和文件数量。logging: driver: json-file options: max-size: 50m max-file: 3排查问题时先看容器状态再按服务名查日志这个顺序比直接翻面板日志高效得多。比如 Web UI 能打开但登录后看不到模型基本可以确定是 api-gateway 或 model-server 的问题直接查对应容器的输出会有线索。更进一步的定位手段是进容器内部用 curl 访问服务端口确认内部的 HTTP 接口是否响应正常。很多网络问题乍看是容器问题实际上宿主机和实体机之间已经通了但容器之间因为依赖或地址配置没通。监控方面不用一上来就上全家桶盯着几个指标即可显存占用、内存占用、容器状态。nvidia-smi可以看到显存会不会被撑爆Docker 的stats命令可以看到实时资源消耗。单机场景下这两个工具足够日常运维等规模大了再考虑上 Prometheus 这类监控系统。4.3 安全加固要点局域网部署不等于不需要安全措施只是威胁模型不同。首先网关 API Key 必须改掉默认值不要用镜像仓库文档里的示例。其次建议不要在局域网里裸奔暴露端口如果路由器或交换机支持 VLAN可以把 AI 平台划分到独立的 VLAN 里限制只有特定设备能访问。Web UI 侧的访问控制尽量做一层基础认证。Harness 的默认配置里未必有强制密码搭建完第一件事就是开启用户认证并设置强密码。如果有访客需要临时用一下可以开访客模式限制权限别把管理员账号共享出去。模型服务的端口尤其要注意它本身只需要给内网网关调用不要直接暴露给所有局域网客户端。最稳妥的做法是让 model-server 不映射宿主端口仅内网 Docker 网络可达。这样外部设备即使知道 IP 也没法直接访问模型服务所有请求都经过 API 网关这一层。5. 实测中踩过的坑和排查思路5.1 模型服务起不来这是最高频的问题。现象是容器启动后立即退出或者一直处于重启状态。先看日志最常见的是 CUDA 相关错误比如驱动版本不匹配或者容器内 CUDA 版本与宿主驱动不兼容。解决办法是先更新宿主 NVIDIA 驱动再装对应版本的 NVIDIA Container Toolkit最后用 CUDA 测试镜像验证透传。另一个常见原因是模型文件路径写错。MODEL_PATH指向容器内路径必须先确认挂载卷是否把宿主机目录正确映射到了容器内。可以用docker exec -it 容器名 ls /models查看容器内是否能看到权重文件避免路径问题反复试。显存不足也会导致启动失败尤其是加载模型时中间层需要额外显存。可以尝试降低上下文长度或者将部分层 offload 到 CPU这些参数在环境变量里都能调整。7B 模型的量化版在 8GB 显存机器上一般把 context length 设为 2048 就能稳定运行。5.2 局域网设备连接超时这个问题通常不在容器而在防火墙或网络配置。宿主机本机访问正常但局域网其他设备超时第一反应查防火墙。UFW 上没有放行对应端口是最大概率的原因。其次是确认服务监听的不是 localhostDocker 端口映射默认绑在 0.0.0.0但你如果手动改过端口映射需要再核对。还有一种隐蔽情况宿主机有多个网卡。比如机器同时连着有线网络和无线网络Docker 端口映射绑定的是默认网卡 IP其他网段设备访问时如果路由不通就表现为超时。在 docker-compose 里显式指定端口绑定的 IP比如192.168.1.100:3000:3000能避免这种歧义。5.3 内存或显存爆掉运行一段时间后服务变得很卡甚至被系统 OOM Kill。很多时候是上下文长度放得太大多用户并发后每个会话都要占显存累积起来非常可观。Harness 系统默认对每个会话分配独立的上下文空间并发一多显存消耗不是线性上涨而是近乎乘法级上涨。解决思路是给推理服务设置更高的资源限制但不是无限加大而是设置合理的并发数上限。如果同时使用的人不多可以限制最大并发请求数超出部分排队等待。同时可以把部分不太常用的 Agent 工作进程设置为按需启动空闲时自动回收资源。5.4 Agent 问答质量不稳定这个一般不是硬件或部署问题而是配置问题。先说工具调用失败表现为 Agent 反复尝试调用一个工具但结果异常。排查时打开 Agent 的详细日志看模型生成出的工具调用参数是否合法。例如调用代码解释器时通常需要模型具备很强的指令遵循能力量化后的模型在这点上确实会弱一些。另一个常见问题是“知识幻觉”。本地部署的模型本身不是全知的你问它特定项目代码或内部文档的细节它很可能一本正经地编答案。这个场景下不应该靠模型自身的参数记忆而应该接检索增强生成。DeepSeek Harness 里支持挂载向量库把团队知识库切成向量存下来Agent 在回答时会先检索相关内容再生成。这一步配置好后问答质量会有质的提升。最后提醒一下如果你把 context 长度设置得特别大模型在长上下文下的注意力会分散问答质量同样会下降。所以宁可把上下文控制在合理范围配合摘要和检索也不要把参数调到极端值。这个方案跑起来之后后面可以扩展的方向其实很多。比如接入团队内部的 GitLab 或工单系统让 Agent 能直接查代码和操作任务比如把多个模型放进同一个 Harness 里做路由不同任务分给不同模型再比如接上语音输入输出让平台成为一个全屋智能的中枢。反正底层架构搭好了上层怎么玩就看需求了。