★ FEATURED ARTICLE 想把 AI Agent 真正落到团队内部使用Docker 部署 DeepSeek Harness 是我试过最快的一条路。以前用公共接口总担心数据外传请求一多费用也压不住后来干脆在办公室的服务器上自己搭一套模型、知识库、对话界面全放进内网大家通过浏览器访问就行。这篇文章就把我搭这套局域网 AI Agent 平台的完整过程、配置细节和踩过的坑一次性讲清楚适合有一定 Docker 基础、想把 AI 能力私有化落到团队或家庭网络里的朋友。我会从设计思路讲到具体文件再到问题排查尽量让基础一般的读者也能照着复现。1. 为什么要在局域网里自建 AI Agent 平台1.1 自建要解决什么问题先说痛点。团队或者个人一旦开始认真用 AI Agent很快就会发现几个绕不开的问题第一是数据边界业务资料、内部文档、对话记录反复经过外部接口合规和信任都过不去第二是成本Agent 类任务通常要多次调用模型一个复杂任务可能产生几十轮对话按次计费根本扛不住第三是可用性公网服务偶尔抽风、限流、延迟波动都会让自动化流程变得不可靠。自建局域网平台的意义就在这里。把模型服务、Agent 调度逻辑、对话界面、知识库全部装进自己的内网服务器请求不出网费用变成一次性的硬件成本延迟也稳定得多。更重要的是Agent 的行为可以对齐团队内部流程比如让它走自己的审批工具、查自己的数据库、按自己的知识库回答这是公共接口很难做到的。我之前也试过在单机上直接跑脚本但很快发现环境管理是灾难Python 版本冲突、依赖库升级、显卡驱动一变就崩、同事想试用还得各自配环境。后来把 DeepSeek Harness 整体容器化所有组件都封装成镜像一台服务器上docker compose up 就能拉起一整套环境迁移和备份也方便。这套方案我用下来最顺手的地方在于模型、编排、前端、存储各自独立可以分开升级出问题也能单独重启互不拖累。1.2 DeepSeek Harness 的基本组成DeepSeek Harness 这个名字听起来很“框架”我的理解是它把 AI Agent 平台要用的几块拼图统一了起来。拆开看整套系统大概有四层最底下是模型推理服务负责加载 DeepSeek 系列的开源模型提供对话和补全接口往上一层是 Agent 编排服务负责拆解用户目标、管理工具调用、拼接上下文再往上是 Web 前端给使用者一个直观的聊天式交互界面最后还有支撑数据包括存放用户会话的关系型数据库、保存临时状态的缓存服务。用生活化类比模型推理服务像一个“大脑”Agent 编排是“大脑皮层”负责思考怎么一步步做事工具调用是“手和脚”用来查数据库、发请求、读写文件前端是“脸和嘴”让普通用户能直接对话数据库和缓存则是“记忆”保证对话不会丢状态不会乱。在局域网环境里这套结构最大的优势是模块清晰每个部分都可以单独扩容。比如模型推理挤爆显存多开一个实例分摊数据库压力大单独迁移到性能更好的机器上。容器化的部署方式让这些操作变得非常简单不需要在服务器上手动配一堆依赖。2. 环境准备与整体方案设计2.1 硬件要求与服务拆分动手之前最怕的是什么都不规划直接装完才发现显存不够或者端口冲突。我给出的方案来自实际部署中的配置适合中小型团队起步后续可以根据压力横向扩展。服务作用资源建议模型推理服务加载并运行 DeepSeek 系列模型GPU 8~16G 显存起步CPU 给 4 核Agent 编排服务任务拆解、工具调用、上下文管理2 核 4G 内存Web 前端用户对话界面1 核 1G 内存关系型数据库保存用户、会话、任务记录2 核 4G 内存缓存服务会话缓存、限流、临时状态1 核 2G 内存这个表格是参考值不是说少了就跑不起来。如果只是自己玩模型精度调低、量化开大8G 显存也能跑如果团队并发高数据库和编排服务要给更多资源。关键是在开始之前想清楚多少人用、主要做什么任务、模型要多大。模型选择上我建议先跑量化版本体验一下效果和速度再慢慢尝试完整精度。DeepSeek 系列开源模型在对话、推理和工具调用上都有不错的表现用在 Agent 场景下天然合适。所谓工具调用简单说就是模型不只是生成文本它还能输出一个结构化的“调用意图”比如“调用查天气函数”、“调用搜索数据库函数”编排服务会真的去执行这些函数然后把结果返回给模型继续推理。2.2 网络拓扑与端口规划局域网部署最怕端口规划混乱。我通常把所有服务放在同一个自定义网络中端口映射只在最外层做一次内部服务之间用服务名互相访问避免写死 IP。文字描述一下整体拓扑浏览器访问 Web 前端的 3000 端口Web 前端把请求转发给编排服务的 8080 端口编排服务再通过内部网络访问模型推理服务的 11434 端口。数据库和缓存不对外暴露只允许编排服务访问。注意我这里说的端口是参考值实际请以你的服务配置为准。这样的好处是对外只有一两个端口需要开防火墙减小攻击面内部服务名在容器网络中固定不变即使服务器 IP 换了只要重新拉起容器服务间通信不会断。对于办公室这种经常性改网的场景这个设计能省掉很多麻烦。2.3 准备工作清单在正式部署前把该准备的材料列好能避免一半的踩坑时间。一台 Linux 服务器推荐 Ubuntu 22.04 及以上内核版本不要太老否则容器网络和 GPU 透传会出问题。已经安装好 Docker 引擎和 Compose 插件。确认docker compose version能正常输出而不是只有旧的docker-compose命令。如果服务器有 NVIDIA 显卡需要提前装好驱动并确认容器能识别 GPU 设备。启动容器时若看到could not select device driver多半是驱动或者运行时没配好。下载好 DeepSeek 模型的权重文件。模型文件通常较大建议放到独立磁盘或大分区上避免撑爆系统盘。规划好数据目录比如/opt/harness下面再分models、data、logs三个子目录。目录结构清晰后面备份和排错会很舒服。准备工作的核心原则是“先验证再铺开”。我每次部署新环境都会花 10 分钟做一个最小验证先单独启动模型推理服务确认接口能返回正常结果再叠加其他服务。这样一旦出问题定位范围会小很多。3. 容器编排与核心配置实操3.1 编写 Compose 编排文件所有服务通过一个 Compose 文件管理是我最推荐的做法。下面是一份精简但完整的示例你可以直接复制到/opt/harness/docker-compose.yml里version: 3.8 services: model-service: image: harness-model:latest container_name: harness-model ports: - 11434:11434 volumes: - ./models:/data/models environment: - MODEL_PATH/data/models/deepseek-chat.gguf - CONTEXT_LENGTH8192 - GPU_LAYERS32 deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] restart: unless-stopped agent-service: image: harness-agent:latest container_name: harness-agent ports: - 8080:8080 environment: - MODEL_BASE_URLhttp://model-service:11434 - DB_HOSTharness-db - CACHE_HOSTharness-cache - AGENT_TIMEOUT120 volumes: - ./data/agent:/app/data depends_on: - model-service restart: unless-stopped web: image: harness-web:latest container_name: harness-web ports: - 3000:3000 environment: - API_BASE_URLhttp://agent-service:8080 depends_on: - agent-service restart: unless-stopped harness-db: image: harness-postgres:16 container_name: harness-db volumes: - dbdata:/var/lib/postgresql/data environment: - POSTGRES_USERharness - POSTGRES_PASSWORDchange_me - POSTGRES_DBagent restart: unless-stopped harness-cache: image: harness-redis:7 container_name: harness-cache volumes: - cachedata:/data restart: unless-stopped volumes: dbdata: cachedata:注意我把image字段写成了内部镜像仓库里的名字实际部署时你需要替换成你环境里可用的镜像地址。如果你的网络环境能访问公共镜像仓库也可以直接用公共镜像名但一定要提前验证镜像是否可拉取避免部署到一半卡在下载上。这份文件里有几个细节值得展开说restart: unless-stopped保证机器重启后服务能自动恢复局域网服务器很少配置看门狗这个字段就是最简单的看门狗。depends_on只保证启动顺序不保证服务就绪。比如编排服务依赖模型服务但模型加载可能要几十秒编排服务启动时接口还没起来这种情况要靠编排服务内部的重试机制解决而不是盲目调整启动顺序。数据库和缓存没有映射端口到宿主机这是刻意的。它们只需要在容器互通网络里被访问暴露到宿主机反而增加风险。3.2 模型服务与 Agent 服务的闭环Compose 文件只是骨架真正决定这套平台能不能用起来的是模型服务和 Agent 服务之间的配合。模型服务加载 DeepSeek 模型之后会暴露一个接口。Agent 服务通过MODEL_BASE_URL这个环境变量告诉它我该去哪里调用模型。这个值我写的是http://model-service:11434注意这里用的是服务名而不是 IP因为 Docker 自带的 DNS 会帮我们把服务名解析到对应容器的内部 IP。这个特性非常重要它让服务发现变成零配置。再说上下文长度。CONTEXT_LENGTH8192表示模型能一次性处理的上下文 token 数量。Agent 场景下工具调用的历史、多轮对话、检索到的知识都要挤进上下文里太短容易“失忆”太长又会显著拉高显存占用和推理耗时。我建议 8K 起步如果显存充足、延迟可接受再往上加。还有一个关键参数是AGENT_TIMEOUT。Agent 的复杂任务经常要多次调用模型中间还穿插工具调用总耗时很容易超过普通接口的默认超时时间。如果这个值设短了用户经常会看到“任务超时”的报错但实际模型还在后台跑。我一般设成 120 秒甚至更长。3.3 数据持久化与备份策略容器是无状态的重启之后文件系统里的改动会全部丢失所以数据必须挂在宿主机目录或者数据卷上。上面 Compose 文件里我用了几种挂载方式模型文件放在宿主机目录./modelsAgent 的运行时数据放在./data/agent数据库用了命名数据卷dbdata。为什么不统一用目录挂载主要是权限和性能考虑。数据库这类对文件 IO 要求高的服务用数据卷更加稳定模型文件是只读的放在目录里方便直接替换模型Agent 产生的日志和任务记录放目录里方便用编辑器查看和备份。备份这件事我吃过亏。早期有一版部署把数据库装在容器里没有挂任何卷一次docker compose down再配合清理命令所有用户和会话数据全没了只能从头再来。后来我设置了每天凌晨自动备份先把数据库数据导出成一个压缩文件然后保留最近 7 天版本同时把日志目录定期清理。模型文件不用频繁备份下载一次存好就行。4. 局域网访问、安全与性能调优4.1 把服务安全地开放到局域网部署完成之后最自然的想法是把服务地址发给同事http://服务器IP:3000。但要真正在局域网里稳定使用还有几个动作要做。首先固定服务器的内网 IP。如果服务器用 DHCP 自动获取地址哪天路由重启或者租约到期IP 变了所有人收藏的链接就全失效了。我建议在路由器里做 IP 和 MAC 绑定给服务器一个固定地址比如192.168.1.10。其次确认防火墙放行相关端口。很多 Linux 发行版默认防火墙是开启的即使容器映射了端口宿主机防火墙不放行局域网其他机器依然访问不了。我一般是执行sudo ufw allow 3000/tcp sudo ufw allow 8080/tcp只放行真正需要访问的端口。模型服务的 11434 端口数据量大原则上只服务内部容器不映射到宿主机如果已经映射出来了为了安全还是把它从防火墙里关掉。第三给服务加一层反向代理。我习惯在前面放一个轻量的反向代理容器统一管理入口。它的作用包括把 80 端口转发到 Web 前端、合并静态资源请求、限制单 IP 请求速率、记录访问日志。这样做的好处是以后要加 HTTPS 也只要改代理一层配置不需要动业务容器。4.2 安全加固的几道防线局域网并不是绝对安全的尤其是办公室网络办公电脑、打印机、各种设备混在同一张网里一旦有设备中招整个网段都会被探测。我的安全思路是“纵深防御”不指望单点拦住攻击而是层层设卡。第一道防线是账号认证。Web 前端默认可能有开放注册必须关掉改成管理员创建用户或者邀请码注册。所有账号强制使用强密码。第二道防线是接口鉴权。Agent 服务暴露的接口不要裸奔最好支持 API Key 校验。前端在请求里带上 Key服务端校验不通过直接拒绝。内部服务之间通信也可以加简单的共享密钥防止其他容器或者局域网设备伪造请求。第三道防线是网络隔离。数据库和缓存服务不要映射端口到宿主机只留在容器网络中。如果你对网络安全要求特别高可以把模型服务也建一个单独的网络只允许特定服务访问。第四道防线是数据泄露风险。对话记录和知识库内容可能包含敏感信息数据库文件需要定期加密备份日志里注意不要让模型输出完整脱敏前的数据。我还习惯在上线前把默认的管理员密码、数据库密码全部改掉使用随机生成的强密码存到专门的密码管理工具里。4.3 性能瓶颈与资源调优局域网环境下并发量一般不会特别夸张但一旦团队开始依赖这套平台性能问题很快会暴露。最常见的瓶颈有三个显存、上下文长度、数据库连接。显存问题是最好判断的模型推理时 GPU 显存报错或者容器被系统杀死多半是显存爆了。处理方式有两种一是换更小的量化模型二是调低上下文长度和并发数。我实际测试下来8G 显存在跑 7B 级别模型时会比较紧张建议控制在 4 并发以下。上下文长度对性能的影响比很多人想的大。长度翻倍显存占用和推理延迟都不是线性增长的。如果你的 Agent 主要做简单问答不需要挂载太多工具和检索结果可以适当缩短上下文换取更快的响应。数据库连接数也要提前预留。Agent 服务每处理一个任务可能需要多次读写数据库如果连接池默认值太小并发一上来就会出现连接超时。我在编排服务里会把数据库连接池上限调高并加上连接复用同时在数据库配置里提高最大连接数两边匹配才不会报错。最后说一个容易被忽略的点日志。日志写太多会拖慢磁盘 IO尤其是模型服务的请求日志每个 token 都打印的话几十个并发就能把磁盘打满。我把模型服务日志级别调成 WARNAgent 服务保留 INFO 但开启日志轮转限制单个文件大小和保留数量这样磁盘占用能稳定住。5. 部署实录与常见问题排查表5.1 一次实际部署的时间线我把一次典型的部署过程梳理成时间线供参考。这里省去具体时间重点说明每个阶段要完成什么阶段一基础环境。服务器装好系统、Docker、Compose确认 GPU 驱动和容器 GPU 透传正常。这一步如果能跑通一个最小的 GPU 容器后面会顺利很多。阶段二模型准备。把模型文件放到/opt/harness/models目录先手动拉起模型服务用命令行请求一次对话接口确认模型能正常加载和生成。这一步要特别注意显存占用模型加载后立即看一眼显存余量判断后续还能不能加上下文。阶段三核心服务。启动数据库、缓存、编排服务确认编排服务日志里没有连接错误。然后用配置文件里的环境变量逐一验证比如模型接口是否可达、数据库表是否自动创建。阶段四前端接入。启动 Web 前端登录后台创建第一个测试用户然后发起一轮包含工具调用的任务观察整个链路是否走通。如果任务能正确返回结果核心部署就算完成了。阶段五安全与收尾。改默认密码、关开放注册、配防火墙、设置定时备份最后做一个重启测试docker compose restart之后所有服务能自动恢复才算是可以交付的状态。这套流程走下来顺利的话小半天能结束慢的话大多卡在阶段二主要是模型下载和显存调优。我建议第一次部署留足时间每个阶段之间多验证不要一口气把全部服务都拉起来再慢慢排错。5.2 高频问题速查表这些问题是群里反馈和实际运维中反复出现的我整理成了一张速查表按“现象、原因、解决办法”的方式对号入座现象最可能的原因解决办法容器启动提示找不到 GPU显卡驱动未装或权限不足验证驱动安装结果确认容器运行时支持 GPU 透传模型加载后很快就内存溢出量化等级太高或上下文过长换更低的量化版本缩短上下文长度降低并发数局域网其他电脑无法访问前端防火墙没放行端口放行 3000 端口确认服务监听在所有网卡而非仅回环地址修改 Compose 后重启配置不生效没有重新创建容器使用docker compose up -d --force-recreate重新创建任务执行到一半提示超时Agent 超时时间过短调大AGENT_TIMEOUT环境变量对话记录偶尔丢失数据库没有持久化卷检查数据库是否挂载了数据卷定时导出备份请求量一大响应明显变慢数据库连接池耗尽或磁盘 IO 瓶颈调大连接池、开启日志轮转、把模型文件放到 SSD 上接口返回乱码或空内容模型量化版兼容问题切换模型版本确认接口返回的文本编码格式排查思路很重要的一点是“从外往里查”。前端报错优先看浏览器开发者工具的请求状态确认请求到了哪一层网络没问题再看容器日志确认是代理层有问题还是服务内部异常。日志默认是英文的反而好搜遇到没见过的报错拿关键词搜一下一般都能找到方向。5.3 最后几点实操心得再分享几个不太容易被文档写进去的细节。第一环境变量尽量集中维护。每个服务的配置如果有十几个环境变量建议放在.env文件里Compose 会自动读取。不要在多个文件里散落用户名和密码否则排查和修改都容易漏。第二服务日志要尽早接入集中方案。规模小的时候docker compose logs -f够用但等日志一多定位问题会变得非常痛苦。可以先用简单的方案把日志输出到固定目录按天切分后面再迁到分析平台成本很低收益很高。第三模型文件的下载和备份真的是个大工程。一次完整模型的体积可能超过十几 GB拿 U 盘拷都比在线下载快对于内网环境尤其重要。我在离线环境部署过几次提前把模型放在一块移动硬盘里能省下好几个小时。我在实际部署中体会最深的一点是这套平台的价值不在“跑通”而在“稳定地跑着”。花时间把备份、重启策略、防火墙规则都完善好远比第一次启动惊艳更重要。局域网里的 AI Agent 做得越顺手团队依赖就会越深这时候稳定性就是第一位的。愿这几次部署的折腾能帮你少走一些弯路也欢迎你把踩到的坑再补充进来。
阅读完成 · 觉得有帮助？
