先说结论：这个方案我实测跑通了，而且比我预想的轻松不少。如果你手头有一台配置还行的机器，想在公司或家里局域网内搞一个私有 AI Agent 平台，用 Docker 部署 DeepSeek Harness 确实是一条非常顺的路。它能让你用自己的算力跑大模型，搭建一个可供多人访问的 Agent 服务，不依赖外部网络，数据也不出内网。这篇文章我会把整个部署链路拆开讲清楚，包括前置条件、编排文件撰写、模型接入、Agent 配置、局域网暴露，以及我实际踩过的坑和排查经验，尽量做到你照着操作就能复现。
1. 先理清楚：这个项目到底解决什么问题
1.1 什么是 DeepSeek Harness
DeepSeek 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_DEVICES=all - MODEL_PATH=/models/deepseek-7b-q4.gguf - CONTEXT_LENGTH=4096 - MAX_GPU_MEMORY=10GiB volumes: - ./models:/models ports: - "8001:8001" deploy: resources: limits: memory: 16G api-gateway: image: deepseek-harness/api-server:v0.6.2 environment: - MODEL_ENDPOINT=http://model-server:8001 - API_KEY=sk-local-xxxx depends_on: - model-server ports: - "8080:8080" agent-worker: image: deepseek-harness/agent-worker:v0.6.2 environment: - GATEWAY_ENDPOINT=http://api-gateway:8080 - TOOL_PLUGINS=code_interpreter,web_search,db_query depends_on: - api-gateway volumes: - ./data:/data web-ui: image: deepseek-harness/web-ui:v0.6.2 environment: - GATEWAY_ENDPOINT=http://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 模型接入：本地权重还是远程 API
DeepSeek 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 上没有放行对应端口是最大概率的原因。其次是确认服务监听的不是 localhost，Docker 端口映射默认绑在 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 里做路由，不同任务分给不同模型；再比如接上语音输入输出，让平台成为一个全屋智能的中枢。反正底层架构搭好了，上层怎么玩就看需求了。
