前阵子要给我们团队内部搭一个AI Agent平台试过直接调云端API也试过裸机部署模型服务折腾一圈最后还是落在了Docker上。用DeepSeek Harness这套方案docker compose 一条命令就能把模型服务、Agent调度、知识库、管理界面全部拉起来局域网里谁都能访问数据不用出内网成本也就几度电的事。这篇把我从选型到跑通的完整过程都梳理了一遍包括架构设计、配置参数、调优经验还有几个我查资料查了半天才解决的坑。想自己搭一个内网AI Agent平台的朋友可以直接照着操作少走弯路。1. 为什么要用 Docker 部署 DeepSeek Harness 搭建局域网 AI Agent 平台1.1 本地化部署解决的真实痛点先说需求背景。我们团队想把手头一堆重复性事务交给AI Agent处理包括文档摘要、工单分类、周报整理、会议纪要提炼等。一开始直接使用线上API确实方便但用起来有几个问题始终绕不过去。第一个是数据安全问题。团队内部文档涉及客户信息、项目方案、内部评审意见把这些内容发到外部API哪怕只是临时处理合规上始终不踏实。第二个是成本问题。To B场景下每天几十号人高频使用Token消耗是持续性的月底账单下来相当可观。第三个是依赖问题外网服务一旦波动整个平台的可用性就跟着遭殃这对内部生产力工具来说是不能接受的。所以“局域网里跑一套自己的AI Agent平台”就成了自然的选择。而DeepSeek Harness正好就是围绕这个场景设计的一套容器化平台它把模型推理、Agent运行时、向量知识库、网关认证等拆分成了独立的容器通过Docker Compose统一编排。这样做的价值在于不用手动去装推理框架、配Python环境、管理依赖冲突一条命令拉起整个环境任何一台装了Docker的服务器都能复现。Docker在这里解决的本质问题是“环境一致性和可移植性”。你在一台服务器上调试好的配置打包成镜像后换一台机器部署结果是一模一样的不会出现“明明在我机器上能跑”的尴尬。1.2 Harness 的整体架构容器分工与协作方式DeepSeek Harness 的架构并不复杂核心思想是“各容器只做一件事通过内部网络协作”。我实际部署后归纳下来平台由5类容器组成分别承担不同的职责。网关容器是整个平台的统一入口负责接收来自浏览器、客户端或API的请求做路由转发、基础鉴权、限流控制。所有外部流量先打到网关再由网关分发给后端的Agent服务或管理服务避免了直接暴露内部组件。模型服务容器是平台的心脏负责加载DeepSeek系列模型权重对外部提供一个兼容OpenAI格式的API接口。Agent运行时通过这个接口来调用模型的对话能力完成意图识别、指令理解、文本生成等任务。这个容器对显存和内存的要求最高也是性能调优的重点对象。Agent核心容器是平台的大脑负责任务拆解、工具调用编排、多轮对话管理和上下文记忆。它接收到用户的复杂指令后会把任务拆分成若干步骤按需调用内置工具比如搜索、计算、文档处理再汇总结果返回给用户。知识库容器负责向量数据的存储和检索。它的作用是把团队内部的文档切分成片段、生成向量索引当Agent需要参考相关知识时通过相似度检索获取最相关的内容从而做出更准确的回答。管理端容器提供可视化的Web管理界面可以配置模型参数、管理用户权限、查看运行日志、创建知识库索引等。日常运维中大部分操作都可以在这个界面完成不需要频繁地去改配置文件。这5类容器通过一个自定义的Docker网络连接在一起互相之间用服务名访问。比如Agent容器只需要配置MODEL_ENDPOINThttp://model-service:8000就能找到模型服务完全不需要关心后端的IP和端口。这种“服务发现”机制是容器编排的核心便利之一容器重启IP变了也不影响内部调用。2. 部署前的准备工作与环境规划2.1 硬件需求评估不要被“大模型”三个字吓到在动手部署之前最关键的一件事是先搞清楚自己的硬件能不能扛得住。很多人一说跑大模型就觉得需要一堆卡实际上DeepSeek Harness对硬件的要求是比较宽容的选择多大尺寸的模型、什么精度的量化取决于你的目标硬件配置。我按使用规模给出了一个参考表方便你快速判断场景规模CPU内存显卡显存硬盘可用模型规模个人试用4核16GB无/8GB20GB小尺寸量化模型小团队(5-10人)8核32GB16GB100GB中等尺寸量化模型中型团队(20人)16核64GB24GB以上200GB完整精度模型长上下文这个表的判断依据主要有几个。一是模型参数量直接决定权重文件的大小一个几十亿参数量的模型FP16精度光权重就要占几十GB的显存如果用INT8或更低的量化精度显存占用能再压缩一半。二是上下文长度决定KV Cache的开销上下文窗口越长单位并发下占用的显存就越高。三是并发数量决定推理吞吐并发越高对显存和算力的要求也成倍增长。实测下来如果团队只有十几个人日常使用一张显存16GB的显卡配合量化模型跑得相当流畅日常对话、文档分析、知识库问答都能稳定应对。如果是无显卡的纯CPU环境也并非不能用但响应速度会明显变慢适合低频测试或个人体验。2.2 Docker 环境准备先把地基打牢DeepSeek Harness 要求宿主机具备Docker引擎和Docker Compose插件。我建议直接安装当前最新的稳定版本无论是Linux服务器还是本机调试这一步都非常成熟。# 以 Debian/Ubuntu 系列为例 curl -fsSL https://get.docker.com | sh sudo systemctl enable --now docker # 确认 Docker Compose 插件可用 docker compose version装好之后有一个容易被忽略的环节把当前用户加入docker组否则每次执行docker命令都要加sudo。这一步能省掉后面无数次输密码的麻烦但要注意安全边界——加入docker组的用户相当于拥有了宿主机的高权限生产环境要严格控制能够登录这台机器的账号。sudo usermod -aG docker $USER newgrp docker还要检查一下系统防火墙和内网网络环境。如果服务器本身在防火墙后面需要提前确认要放行的端口如果机器在内网VLAN里要确认目标用户能从自己的网络段访问到这个端口。这些问题提前规划好比部署完了再排查要省事得多。2.3 局域网访问规划IP、端口与网络边界局域网部署和公网部署有一个很大的区别服务的访问范围是可控制的。规划阶段建议把下面几件事确定下来。一是为服务器绑定固定IP。虽然Docker容器内部的IP可以随便变但宿主机在局域网里的IP最好固定下来否则客户端配置的地址失效排查起来很折腾。可以在路由器或DHCP服务器里做MAC地址绑定也可以在网卡配置里直接静态设置。二是规划端口使用。DeepSeek Harness通常提供两个访问入口一个是面向用户的管理界面我习惯用9090端口另一个是兼容API的网关端口比如8080。这两个端口在局域网里不能和现有服务冲突提前检查一下其他服务器的端口占用情况。三是想清楚网络边界。如果你担心内网其他非相关人员访问到这个平台就需要在防火墙或交换机层面限制允许访问的IP网段而不仅仅是依赖服务本身的认证。这些都是Docker层面无法完全替代的问题需要在网络规划时同步考虑。3. 核心实操Docker Compose 完整部署流程3.1 目录结构设计先把数据落点规划好跑Docker容器最怕的就是“数据在容器里”因为容器一删数据全没了。所以部署DeepSeek Harness的第一步不是写配置而是先把宿主机上的目录结构规划好。我在实际部署中使用的目录结构是这样的harness/ ├── config/ │ ├── gateway/ # 网关配置 │ ├── model/ # 模型服务参数配置 │ ├── agent/ # Agent 编排规则与提示词 │ └── web/ # 管理端配置 ├── models/ # 模型权重文件 ├── data/ │ ├── agent/ # Agent 会话数据与缓存 │ ├── kb/ # 知识库向量数据 │ └── logs/ # 容器日志持久化 └── docker-compose.yml # 编排文件为什么一定要把模型权重放到宿主机独立目录因为模型权重文件通常有几十GB如果放在容器镜像里不仅镜像会变得极其臃肿每次更新镜像都得重新下载一遍整个模型网络和时间成本都不可接受。通过volume目录挂载模型文件只需要下载一次多个容器可以共享升级时也可以重用。日志和会话数据放到宿主机目录的目的更直白——排错要用。容器一旦重启内部的临时日志就没了只有持久化到宿主机才能在出问题的时候翻出历史记录来定位原因。3.2 docker-compose.yml 关键配置文件解析核心编排文件是基于DeepSeek Harness的官方模板改出来的我把我最终使用的版本贴出来并逐段解释关键配置的含义。services: gateway: image: harness/gateway:2.1 container_name: harness-gateway ports: - 8080:80 - 9090:80 environment: AUTH_MODE: basic ADMIN_USER: admin volumes: - ./config/gateway:/etc/harness/gateway networks: - harness-net restart: unless-stopped model-service: image: harness/model-service:2.1 container_name: harness-model ports: - 8000:8000 environment: MODEL_PATH: /models/harness-model-14b-q4 CONTEXT_LENGTH: 8192 GPU_LAYERS: 35 MAX_CONCURRENCY: 8 volumes: - ./models:/models - ./data/logs:/logs deploy: resources: reservations: memory: 24G networks: - harness-net restart: unless-stopped agent-core: image: harness/agent-core:2.1 container_name: harness-agent depends_on: - model-service environment: MODEL_ENDPOINT: http://model-service:8000 TOOL_ENABLED: search,python,doc_parser MAX_ITERATIONS: 8 VECTOR_ENDPOINT: http://knowledge-base:8340 volumes: - ./config/agent:/etc/harness/agent - ./data/agent:/data/agent networks: - harness-net restart: unless-stopped knowledge-base: image: harness/knowledge-base:2.1 container_name: harness-kb ports: - 8340:8340 volumes: - ./data/kb:/var/lib/harness/kb networks: - harness-net restart: unless-stopped web: image: harness/web:2.1 container_name: harness-web depends_on: - agent-core - gateway volumes: - ./config/web:/etc/harness/web networks: - harness-net restart: unless-stopped networks: harness-net: driver: bridge几个关键点我要单独拉出来讲。第一是端口映射。gateway容器把宿主机8080和9090都映射到容器内的80端口这是为了让两种访问方式API调用和管理界面都走同一个网关容器实际上内部的路由规则会区分API请求和页面请求。而model-service暴露8000端口其实是给宿主机做本地调试用的方便直接用curl检查模型状态。容器间通信完全走内部网络不需要经过宿主机端口转发。第二是GPU_LAYERS这个参数。它的含义是将模型的多少层加载到GPU上剩余层放在CPU上计算。这个参数对于显卡显存不足以完全放下整个模型时特别有用。我的显卡是16GB显存14B模型完全放不下通过把35层放GPU、其余层放CPU达到了显存和速度的最佳平衡。如果你的显存更大可以直接把这个值调高如果没有显卡把它设为0即可全部走CPU推理。第三是MAX_ITERATIONS参数。它限制Agent执行任务时最多循环调用工具多少次默认值8对大多数场景都够用。这个数字太大会导致Agent在复杂任务上无限折腾浪费时间太小则复杂任务容易中途失败。8是一个比较稳妥的中间值。第四是资源限制。deploy.resources.reservations.memory: 24G的作用是告诉Docker这个容器需要多少内存保底。这个配置还有一个隐藏价值它会迫使Docker在内存不足时优先杀死占用超标的容器而不是让整个宿主机卡死。这是个很好的保护机制建议一定要写上。3.3 模型权重准备与首次启动配置写好后下一步是准备模型权重文件。DeepSeek Harness启动时会从你指定的目录加载模型所以需要先把对应尺寸的模型权重放到./models/目录下。这里有一个容易踩坑的地方模型文件不是只有权重本身通常还包含分词器、配置文件、量化参数等若干个子文件。第一次部署时我发现模型服务反复崩溃最后看了日志才发现是某个配置文件缺失导致推理框架加载失败。下载模型时建议把整个目录都拉下来不要只挑大文件。# 进入models目录后确认关键文件是否存在 ls -lh /data/harness/models/harness-model-14b-q4/ # 预期看到模型权重、分词器、配置等文件总大小约8-9GB确认文件完整后在docker-compose.yml中设置MODEL_PATH指向对应的模型子目录如/models/harness-model-14b-q4。由于容器内的/models目录挂载自宿主机./models目录这个路径映射是唯一的。首次启动模型服务会有一个模型加载过程根据模型大小和磁盘读取速度耗时从几十秒到几分钟不等。我见过很多新手在启动后立刻调用接口发现“连接不上”就怀疑部署失败其实只是模型还在加载。等到模型服务日志中出现“加载完成”或“启动就绪”之类的标识再继续下一步操作。3.4 启动与功能验证跑通全流程所有准备就绪后在harness目录下执行启动命令。docker compose up -d使用-d参数让容器后台运行这样关闭终端也不会影响服务。启动后先看一下容器状态docker compose ps如果所有服务都处于Up状态说明容器启动没有问题。接下来需要确认模型服务真的能正常响应。在宿主机上直接调用一下模型APIcurl -X POST http://127.0.0.1:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: harness-model-14b-q4, messages: [{role: user, content: 你好简单介绍一下你自己}], max_tokens: 256 }如果返回了包含content的JSON响应说明模型服务已经正常工作。此时再打开浏览器访问http://服务器局域网IP:9090就能看到DeepSeek Harness的管理界面。在界面里创建一个测试用户新建一个对话输入一个需要调用工具的任务比如“帮我总结这段文档的内容”验证Agent的完整链路是否正常。这里还有个小细节容器之间的启动顺序。agent-core容器配置了depends_on: model-service这保证了Agent容器一定会在模型服务之后启动。但depends_on只保证启动顺序不保证模型已经加载完成。如果启动顺序上预感到模型加载比较慢可以在Agent容器里加一个简单的健康检查脚本或者手动等待模型日志就绪后再重启agent-core容器。4. 配置细节与性能调优4.1 显存与内存调优策略平台跑起来只是第一步跑得流畅才是真正考验人的地方。DeepSeek Harness的性能瓶颈通常集中在模型服务容器上合理调整几个参数效果立竿见影。先说GPU_LAYERS。这个参数我在前文提到过它是显存不足时最重要的调优旋钮。我的16GB显卡最初设置全部层走GPU结果容器启动后直接报了显存溢出错误。后来把GPU_LAYERS降到35模型成功加载单次推理的耗时大约增加了30%但总体可用性得到保证。如果你的显存有24GB以上建议把这个值尽量调高因为GPU层的比例越高推理速度越快。再说MAX_CONCURRENCY。这个参数控制模型服务同时处理的请求数不是越大越好。并发过高时推理框架会在显存中同时为多个请求分配KV Cache显存占用会成倍增加并发过低又在多用户场景下排队明显。我的建议是先从4开始用几十个测试请求观察显存峰值然后逐步上调找到一个稳定区间。内存方面的关键点是给模型服务容器预留足够的内存。对于14B量化模型8到16GB的CPU内存池是合理的再加上系统本身的开销预留24G比较稳妥。不要舍不得给内存模型推理时CPU内存的用途不仅仅是缓存还包括KV Cache在CPU与GPU之间的交换缓冲、并发请求的临时存储等。如果部署后发现响应速度慢建议优先检查是不是上下文窗口设置过大。CONTEXT_LENGTH从4096提高到8192显存占用会显著增加但在大部分团队内部场景下4096或8192已经足够日常使用。强行追求大上下文而不考虑显存性价比是一种很常见的自找麻烦。4.2 局域网访问与安全基线在局域网内部署不等于不需要关注安全。DeepSeek Harness默认不会开启复杂的鉴权机制生产使用前建议至少做以下几件事。第一是限制监听地址。默认情况下容器的端口映射会把服务暴露到宿主机所有网络接口上包括可能存在的其他网卡。如果这台服务器还有别的网络可达路径建议在端口映射时明确绑定到内网IP例如192.168.1.10:8080:80避免服务被意外的网络路径访问到。第二是启用网关鉴权。DeepSeek Harness的网关容器支持基础认证模式在docker-compose.yml里配置AUTH_MODE: basic并设置ADMIN_USER和管理密码即可。这个机制虽然比较简单但能挡住绝大多数“随手扫一下端口”的访问行为至少不做裸奔。第三是网络隔离。如果是在一个较大的办公网络里建议把部署服务器放到单独的VLAN只允许办公网特定网段访问。这个操作在Docker层面做不到但可以在交换机或云防火墙规则中配置。容器内部网络只是一个逻辑隔离物理网络边界的控制同样重要。第四是定期备份数据目录。./data/kb目录是知识库的向量数据./data/agent目录是Agent的会话数据和状态缓存。这些数据一旦丢失知识库要重新灌入、会话记录要全部丢失损失远大于重新部署本身。我习惯用系统定时任务每天凌晨打包这两个目录到另一台机器或存储设备上。4.3 日志与监控让容器工作状态可见Docker容器是黑盒运行不主动去看日志很难知道内部发生了什么。DeepSeek Harness的日志分为两类一类是容器运行时输出的标准日志一类是写入挂载目录的应用日志。查看所有服务的实时日志docker compose logs -f只看指定服务docker compose logs -f model-service日志的用处不只是排错。我通过观察模型服务日志里的请求统计能够隐约感知平台的使用频率通过Agent日志里的工具调用记录能发现哪些工具有效、哪些工具频繁报错进而调整TOOL_ENABLED列表。Docker本身也提供了基础的资源监控命令可以快速查看容器的CPU和内存占用情况docker stats建议在调度任务中做一个最简单的日志清理日志文件超过一定体积时自动清空或归档。否则运行时间一长日志目录会被撑满磁盘告警把平台搞崩的情况我也见过。日志定期清理、数据定期备份这两个习惯能省掉很多应急救火的麻烦。5. 常见问题与排查技巧实录DeepSeek Harness部署和运行过程中有几个问题是我自己踩过、后台也经常有朋友来问的。把这些高频问题整理成一个速查表按着顺序排查通常几分钟就能定位到根因。现象可能原因快速处理方式访问9090管理界面打不开防火墙未放行放行/检查容器映射端口模型服务容器反复退出显存不足 / 模型路径错误调低GPU_LAYERS / 确认挂载路径Agent调用模型一直超时并发过高 / 上下文过长调低MAX_CONCURRENCY缩短上下文局域网其他电脑无法访问服务只绑定了127.0.0.1端口映射改成0.0.0.0或内网IP重启后知识库内容丢失data目录未挂载检查volume映射恢复备份模型加载特别慢权重文件在机械硬盘上迁到SSD或者换更高读取速度的位置网关返回401鉴权密码配置错误查看环境变量AUTH_MODE和账号配置除了表格里的标准答案我单独把几个处理过程拿出来聊聊。模型服务反复重启。这个问题最常见的两个原因是显存不足和模型路径错误。显存不足的日志里通常会出现“CUDA out of memory”或类似信息这时把GPU_LAYERS下调到0试试如果能启动说明就是显存不够再二分法上调找到一个稳定值。模型路径错误的日志通常会出现“file not found”或“cannot load model”这时检查挂载目录和容器内的实际路径是否对应。注意容器内路径和宿主机路径不是一回事./models挂载到/models之后容器里访问的是/models/...。局域网其他人访问不了。这个问题在笔记本上用Docker部署的场景里尤其常见。Windows电脑上的Docker默认把端口映射到虚拟机网络里局域网的同事访问宿主机的IP并不一定等于能访问到容器内的服务。确认方法是在宿主机上先访问http://127.0.0.1:9090看看通不通再换局域网IP访问。如果是局域网内其他机器不通优先排查防火墙其次排查端口映射的绑定地址。Agent调用工具失效。有时候模型正常运行对话框里回复也很顺畅但一让它调用文档解析工具就报错。排查看Agent容器日志时发现报错信息是“cannot connect to tool service”这说明工具的端口没有暴露到Agent容器可访问的地址。容器之间通过内部网络访问时要确保工具服务的端口没有被限制在127.0.0.1且Agent容器的环境变量里指向的地址是容器服务名而不是宿主机IP。知识库数据丢失。有朋友在升级容器镜像时忘了检查挂载配置直接跑了一次docker compose down -v。这个命令会把未挂载的命名卷一起删掉如果知识库数据没有被挂载到宿主机目录就会跟着容器一起消失。血的教训是down -v这个命令在生产环境要么不用要么在维护窗里慎重使用。所有重要数据提前挂载到宿主机目录并定期备份才是正解。还有一个小技巧要分享遇到任何诡异现象第一件事不是改配置、重启容器而是看日志。docker compose logs --tail50 agent-core这种命令几乎每次都能直接告诉你问题出在哪一步。很多看起来复杂的问题本质就是把日志看少了。排查问题保持“从日志找证据再去改配置验证”的习惯整个排错过程会变得顺畅很多也少依赖无脑重启这种碰运气的思路。这套DeepSeek Harness平台跑起来之后我最大的感受是把AI能力变成一项团队内部的基础设施比想象中来得简单。Docker容器化把复杂的依赖关系和数据管理问题收敛到了一套可复制的配置里而DeepSeek Harness把模型服务和Agent能力贯通成了一条完整的链路。后续我还打算在这个基础上接入更多内部数据源、扩充知识库的领域范围让Agent对团队业务的适配度再上一个台阶。如果有朋友在部署过程中碰到了文档里没有覆盖到的问题也欢迎交流踩坑心得。