最近在折腾 AI Agent，发现很多朋友都卡在“怎么把模型跑在自己家里/公司内网”这一步。这个项目标题虽然是“Docker 部署 DeepSeek Harness”，但拆开看其实是一条特别务实的路径：用 Docker 把一套能聊、能调用工具、能编排任务的大模型服务跑在局域网里，做成一个真正可控的 AI Agent 平台。这套方案对想搞私有化 AI 服务的人、小团队、还有那些不放心把数据传到公网的场景，都非常实用。
Docker 部署 DeepSeek Harness 这个组合，解决的核心问题是：大模型推理、Agent 编排、工具调用这些原本要依赖云端的东西，现在全部可以落到自己局域网内部。延迟更低，数据不出内网，权限自己定，断网了还能用。这篇文章把我实际部署过程中的思路、步骤、参数选择和踩过的坑都整理出来，看完基本可以照着自己搭一套。
1. 先想清楚：为什么要在局域网里搭一个 AI Agent 平台
这个章节其实是最容易被跳过、但最值得花时间想清楚的部分。很多人一上来就急着拉镜像跑容器，结果跑到一半发现资源不够、目录挂错、端口冲突，然后开始怀疑人生。所以我先把思路拆开说。
1.1 自己搭一套和直接用云端服务有什么本质区别
直接调用云端大模型 API 很方便，注册一下就有 Key，代码里填个 URL 就能跑。但用久了你会发现几个问题：一是数据全在外头，跟服务商之间存在一条看不见的边界，敏感内容根本不敢往里放；二是每次请求都有网络延迟，哪怕是几十毫秒的差距，在 Agent 多轮工具调用的时候会被数倍放大，实际体感就是“笨重”“慢半拍”；三是服务商接口升级、限流、收费调整都是不可控的，你连自己的业务稳定性都做不了主。
而用 Docker 在局域网部署 DeepSeek Harness，相当于把整套“大脑”搬进了自家机房。模型文件还在本地硬盘，推理进程在本地 GPU 上跑，Agent 编排和工具调用也在本地容器里完成。网络瓶颈没有了，隐私边界清晰了，依赖关系也简单了。对于一个小团队或者个人玩家来说，这种“自主可控”带来的踏实感，远比那点 API 调用成本重要。
1.2 Docker 在这里面解决了哪些具体问题
DeepSeek Harness 这种 AI Agent 平台，并不是单个程序，它是由模型推理服务、Agent 运行时、向量库、任务队列、前端管理界面等多个组件拼起来的。如果全部裸装在一台机器上，依赖冲突能让人疯掉——这个组件要 Python 3.10，那个组件要特定版本的 CUDA，还有的组件需要 Redis、需要 PostgreSQL。每装一个新依赖，都可能把系统环境搅成一锅粥。
Docker 的优势在于把每个组件连同它的运行环境一起封装成容器，互相隔离、按需启动、统一管理。“拆开来跑、合起来用”这种模式，简直是为这类多组件平台量身定做的。举个更直白的例子：就像搬家时你不用把每个房间的家具都拆了重新组装，而是每个房间打包成一个标准集装箱，搬过去之后按顺序码放好就能直接住人。Docker 就是那个集装箱系统，有它在你根本不用操心“这家具的螺丝和那房间的墙洞对不对得上”。
1.3 DeepSeek Harness 的定位：不是“聊天机器人”，是 Agent 平台
很多人第一次听到 “Harness” 这个词会愣一下，其实它在工程领域里的意思是“套件、集成框架”。DeepSeek Harness 可以理解成一套专门给大模型做“搭配”的工具集合：它把模型推理、提示词管理、工具注册、Agent 会话调度、知识库检索这些能力整合在一个统一的服务里。你通过它定义的配置方式，把模型接到 Agent 里，再给 Agent 挂上各类工具，它就能自己去规划任务、调工具、返回结果。
所以它解决的问题不是“给我一个聊天的窗口”，而是“给我一个能做事的 AI 员工”。它能根据你预设的工具清单决定每一步调什么工具，能把多轮对话里的上下文、中间结果、执行状态都记录清楚。为什么不直接用 LangChain 之类的框架写代码？因为 Harness 已经把底层的编排逻辑封装好了，你要做的只是配置，而不是从零造轮子，这对大多数非专业 AI 工程师来说是最降低门槛的一条路。
2. 部署前的准备：硬件、目录、网络，这三件事别偷懒
这部分是决定成败的关键。很多人喜欢先跑起来再说，等出了问题再补救，往往会浪费大量时间。我强烈建议你用十分钟把这三件事理清楚，后面会省下以小时计的时间。
2.1 硬件到底要多强：一个合理的算账公式
DeepSeek Harness 跑什么模型，决定了你需要多大的算力。如果是跑 1.5B 这种小参数模型，其实用 CPU 也勉强能跑，但体验很一般；真正想要流畅的 Agent 体验，还是得上 GPU。
一个非常关键的估算逻辑：模型加载占用的显存大约等于参数量的两倍（FP16 精度，1B 参数约占用 2GB 显存）。比如选择 7B 量化模型，通常需要 8GB 到 10GB 的显存；如果跑 14B 模型，至少要 16GB 以上显存；想跑 32B 甚至更大，那就是 24GB 往上走。这里还没算上 Agent 编排时的临时缓存开销，所以最安全的做法是比估算值再多留出 20% 的余量。
内存方面，除了显存还要有系统内存。推理时系统内存最好不低于 32GB，因为模型加载、上下文管理、容器运行时都会吃掉不少。硬盘建议用 NVMe SSD，模型文件动不动就几个 GB，Agent 的会话记录和向量索引也会持续增长，机械硬盘的 IO 延迟会明显拖慢加载速度和检索速度。哪怕没有 GPU 想先用 CPU 试跑，也建议把模型选小一档，别硬上大家伙。
2.2 网络规划：固定 IP 是第一步
既然是搭局域网里的平台，访问入口就是一个固定 IP。我见过不少人在这一步踩坑：服务器 IP 是 DHCP 自动分配的，过了几天路由器重启，IP 变了，所有客户端配置失效，然后一脸懵地以为服务坏了。所以部署前，建议你到路由器后台给这台服务器配一个 DHCP 静态保留，把 IP 固定下来。比如 192.168.1.100 这种，后续所有访问、Agent 回调、API 调用都以这个 IP 为准。
同时还要考虑端口规划。DeepSeek Harness 一般会有管理界面接口和模型服务接口，常见的是 8000 段到 9000 段。端口冲突是局域网部署最常见的问题，不建议让系统随机分配，而是在启动时通过参数显式指定。
2.3 目录规划：数据从容器里“走出来”
容器本身是“一次性”的。如果不做数据目录挂载，容器一删，你辛辛苦苦配置的 Agent、下载的模型、积累的会话记录全部灰飞烟灭。这是个非常容易忽略但又极其致命的问题。
我习惯在宿主机上建一个专门的数据目录，比如/data/deepseek-harness，下面再拆几个子目录：models放模型权重，data放应用数据，logs放日志。启动容器时用-v参数把这些目录挂载进容器。这样以后升级版本、重启容器，只需要重新拉镜像再启动一次，数据和模型都还在。这个习惯我大概在吃了一次“删容器丢数据”的大亏之后才养成，真心建议你直接学走。
3. 上手操作：从 Docker 安装到服务跑起来
现在进入真正的操作环节。我以一台 Ubuntu 22.04 服务器为例，一步一步来。如果你是 Windows 或 macOS，原理完全一样，只是安装 Docker 的方式略有差异。
3.1 安装 Docker 环境和配置镜像加速
先确认系统里有没有装过 Docker：
docker --version如果提示找不到命令，用官方推荐的方式装：
# 安装依赖 sudo apt update sudo apt install -y ca-certificates curl gnupg lsb-release # 添加 Docker 官方仓库 sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod a+r /etc/apt/keyrings/docker.gpg # 写入仓库信息 echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 安装 sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin装完之后把当前用户加进 docker 组，避免每次都要敲 sudo：
sudo usermod -aG docker $USER newgrp docker国内环境拉取镜像经常速度感人，建议配置一下镜像加速器。编辑/etc/docker/daemon.json，填入加速地址，然后重启 Docker：
{ "registry-mirrors": ["https://docker.m.daocloud.io"] }sudo systemctl restart docker这个加速地址自己多备几个，因为部分公共镜像站时好时坏，测一下哪个能通就用哪个。镜像加速配置好之后，拉取 Harness 相关镜像会快非常多。
3.2 准备 Compose 编排文件
虽然可以用一条docker run把容器拉起来，但 DeepSeek Harness 涉及多个服务，用 Compose 编排是更科学的方案。Compose 的好处是：配置一次，以后启动只需要一条命令，所有容器之间的关系、网络、挂载、端口都能在文件里一目了然。
我写了一个最小可用的docker-compose.yml作为参考：
version: "3.8" services: harness: image: harness-image:latest container_name: deepseek-harness restart: unless-stopped ports: - "8000:8000" # Agent 平台管理端口 - "8080:8080" # API 服务端口 volumes: - /data/deepseek-harness/models:/app/models - /data/deepseek-harness/data:/app/data - /data/deepseek-harness/logs:/app/logs environment: - MODEL_PATH=/app/models - CUDA_VISIBLE_DEVICES=0 - LISTEN_IP=0.0.0.0 - AUTH_TOKEN=change_me_to_a_strong_token deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] shm_size: "2gb"这里有几个关键点要展开说一下：
restart: unless-stopped表示容器意外退出时自动重启，服务器重启后也会自动拉起服务，这很重要。- 端口映射部分，宿主机 8000 对应容器 8000，宿主机 8080 对应容器 8080。如果你宿主机上已经有别的服务占了这些端口，可以改成别的宿主机端口，但容器内部端口不要改。
volumes部分把数据目录挂载出来，这是前面说的“容器删了数据还在”的核心保障。deploy.resources.reservations是给容器分配 GPU 的方式，需要提前装好 NVIDIA Container Toolkit。没有 GPU 的话可以删掉这一段。AUTH_TOKEN是我建议设置的管理认证 Token，局域网环境虽然有边界，但原则上不能裸奔。
启动之前记得执行一次docker compose config，这条命令会校验 Compose 文件格式是否正确。我之前因为 YAML 缩进错了，启动时报了一堆莫名其妙的错，后来养成先 validate 再 start 的习惯之后就再没烦过。
3.3 拉取镜像并启动服务
确认 Compose 文件没问题之后，就可以执行启动命令了：
docker compose pull docker compose up -d第一次拉取镜像可能要等一会儿，取决你的网络和镜像大小。启动之后先看容器状态：
docker compose ps再盯日志，确认服务是否正常初始化：
docker compose logs -f harness正常情况下你会看到一系列启动日志，比如模型加载路径检查、数据库初始化、API 服务监听地址。等日志里出现类似Application startup complete或者Server started on 0.0.0.0:8000的字样，服务就算起来了。
这里有一个常见的误区：启动日志刷了一堆，但你不知道啥时候算“好了”。我的判断标准很简单：用另外一个终端执行curl -I http://localhost:8000，如果能返回 HTTP 状态码，说明服务已经在正常监听，这时候再进下一步。如果 curl 一直不通，那说明容器没真正就绪，继续看日志才是最有效的排查方式。
3.4 首次登录、修改配置与加载模型
服务起来之后，浏览器访问http://localhost:8000，或者从局域网其他机器访问http://你的IP:8000，会看到管理界面。首次登录需要用到你刚才在 Compose 文件里设置的AUTH_TOKEN。
登录进去之后第一件事不是急着聊天，而是先把模型加载路径确认好。DeepSeek Harness 的管理界面里大概率有一个模型管理模块，你需要指定模型文件的存放位置和模型名称。这里我推荐提前把一个量化模型下载到models目录里，像 Qwen 系列或者 DeepSeek 系列中小体量的量化版，几 GB 到十几 GB，局域网内跑起来完全够用。
结合国内网络环境，下载模型时有一个很有效率的小技巧：很多模型站点的下载速度不稳定，用带断点续传的下载工具会稳很多。我习惯用aria2代替wget：
cd /data/deepseek-harness/models aria2c -c -x 16 -s 16 "模型下载链接"-c表示断点续传，-x 16表示开启 16 个连接。下载大文件基本不会中途失败重来。模型下载完成后，在管理界面里填好模型路径，保存配置。系统会先去校验文件完整性，然后做一次加载测试，这个过程会占满 GPU 一段时间，建议等它走完再继续配 Agent。
4. 让 Agent 真正“做事”：工具配置与场景实操
服务跑起来只是第一步，真正有意思的是配置 Agent 让它干活。这部分才是从“部署了个模型”到“拥有了一个 AI Agent 平台”的分水岭。
4.1 给 Agent 一把趁手的工具：工具注册与权限控制
Agent 平台和纯聊天窗口最大的区别就是工具调用。DeepSeek Harness 一般会内置一套工具注册机制，你可以通过 UI 或配置文件给 Agent 添加可用工具。比如 HTTP 请求工具可以让 Agent 去访问局域网里的其他服务；代码执行工具可以让 Agent 跑一段 Python 处理数据；有的版本还支持数据库查询接口。
我实际使用中的体会是：工具不在多，在于“够用且安全”。给 Agent 挂一大排工具看起来很厉害，但模型在推理时会面临更多选择分支，调用失误的概率也会上升。我建议一开始只挂两三个最核心的工具，跑顺了再逐渐加。
权限控制这块很容易被忽视。比如代码执行工具，本质上就是让 Agent 在服务端执行命令，如果不加限制，Agent 被注入了恶意指令或者调用逻辑出错，是有风险的。建议给工具配置白名单目录，限制执行路径；给 HTTP 请求工具配可访问域名列表，只允许它访问内网指定服务。这些限制措施加在配置里也就几行，意义却非常大。
4.2 创建第一个能用的 Agent：角色、背景与执行策略
在管理界面里新建一个 Agent，你需要给它起个名字、写好角色定义、选择模型。角色定义这块千万别敷衍，因为 Agent 的行为风格、回复方式、工具选择倾向都取决于这段描述。
我试过两种极端写法。一种是只写一句话“你是一个小助手”，这种 Agent 的表现非常飘忽，有时候答非所问，有时候工具调用路径莫名其妙。另一种是把背景写得特别详细，比如“你是一个智能运维助手，负责检查内网服务状态。当你发现服务异常时，先用 HTTP 工具请求状态接口，确认结果后再回复；如果接口返回异常码，建议先重试一次再报告”，这种 Agent 的行为稳定多了，基本不用怎么调。
还有一个关键配置是“执行策略”或者叫“最大迭代次数”。Agent 在处理复杂任务时是分多轮执行的——分析、调工具、看结果、再分析、再调工具。如果不设上限，一旦模型陷入逻辑循环，就会一直空转，白白消耗算力。我个人建议先设 5 到 8 轮，跑一些简单任务足够用了，复杂任务可以再往上调。
4.3 接一条局域网里的真实服务：HTTP 工具实战
部署好平台之后，我第一件正事儿是让 Agent 帮我看内网服务器状态。我的内网有一台文件服务器，只提供了 HTTP 状态接口，正好用这个场景来练手。
首先我在 HTTP 工具配置里加入白名单地址：
http_tool: allowed_hosts: - "192.168.1.50:8080" timeout: 5注意timeout我设置成了 5 秒，这是防止 Agent 调用远端接口时无限等待的保护措施。然后我在 Agent 的角色描述里加了一句：“你可以通过 HTTP 工具访问 http://192.168.1.50:8080/status 来获取服务器状态。”
然后我在对话框里问它：“帮我看看那台文件服务器现在状态怎么样。”Agent 的思考过程会拆成几步——先调用 HTTP 工具请求状态接口，拿到返回结果后从中提取关键词，再组织成一句通俗的话回复。整个过程在界面里是可见的，像看它“工作”一样。
如果你有自己的内网接口，样例就是直接模仿这个模式：把地址加入白名单，把使用方法写进角色描述，然后在对话里下达指令。Agent 平台的价值立刻就能体现出来——它不是你问一句它答一句的聊天框，而是你给它一个目标，它自己去想办法完成。
5. 常见问题与排查技巧实录
这部分是我最想写的，因为实际部署过程的问题，比官方文档里能预见的那些问题要花式得多。我把我在部署 DeepSeek Harness 过程中遇到的几个典型问题和排查思路整理一下。
5.1 容器起不来：端口冲突、权限、依赖三板斧
我遇到的第一个问题是端口被占。当时日志里能看到address already in use的明确报错，一查发现是之前某个历史进程占了 8000 端口。处理很简单，改宿主机映射端口，或者把旧的进程停掉。排查端口占用用这条命令：
sudo netstat -tlnp | grep 8000第二个问题是 GPU 权限。NVIDIA Container Toolkit 没装或者版本不匹配的时候，容器里看不到 GPU，日志里报错通常包含could not select device driver或insufficient permissions。解决方法是重新安装 toolkit，并且重启 Docker。这里我还有个经验：在 Compose 里写了 GPU 配置后，如果系统没有 NVIDIA GPU，反而会导致启动失败，所以没 GPU 的机器要么删掉那段配置，要么改用纯 CPU 部署模式。
第三个问题是目录权限。挂载目录如果宿主机用户和容器内用户不一致，容器写数据会碰到permission denied。这种情况最简单的办法是把目录的属主改成当前用户，而不要直接chmod 777一刀切。用 777 表面上解决了问题，但引入了安全风险，特别是日志和数据目录里藏了 Token 之类的敏感信息，权限一定要收紧。
5.2 局域网访问不了：防火墙优先，其次查 IP
服务在本机curl正常，但局域网里其他电脑访问不了，这是我见过最多的问题，搬出老办法解决：
第一查防火墙。Ubuntu 上默认可能开着 ufw：
sudo ufw status如果看到防火墙是 active，就要放行对应端口：
sudo ufw allow 8000/tcp sudo ufw allow 8080/tcp第二查监听地址。用netstat -tlnp看看你的服务是不是只监听在 127.0.0.1 上。如果是，那就是没设置LISTEN_IP=0.0.0.0，改一下 Compose 里的环境变量，重启容器就好。
第三查 IP 是否真的固定了。在服务器上执行hostname -I，看当前 IP 是否和你预期一致。不一致就去路由器后台做静态 DHCP 绑定。这三板斧下来，绝大部分局域网访问问题都能解决。
5.3 模型加载慢、内存暴涨：量化、加载参数和缓存策略
局域网里的机器配置往往不是顶配，模型加载慢是很常见的。有一次我加载一个大模型，等了十几分钟都没好，后来发现是模型文件放在机械硬盘上，而且没有做预热。换成 SSD 之后，加载时间直接降了一多半。
如果内存或显存经常爆掉，可以从两个方向调。一个是换更小尺寸的量化模型，比如从 14B 换到 7B，效果差距没有想象中那么大，但资源占用差了一个量级。另一个是调整加载参数，很多推理框架支持max_length或上下文窗口设置，Agent 场景其实用不到特别长的上下文，限制一下可以显著减少显存占用。
另外提一个容易被忽略的细节：容器内临时文件增长。Agent 连续跑了很多任务之后，临时数据可能会积累在容器内部而不是挂载的数据目录里，结果容器越来越大。我建议定期执行docker system prune清理无用的悬空镜像和缓存，同时留意 Compose 中挂载目录里是否有日志滚动配置，避免日志文件无限膨胀。
5.4 一个值得知道的技巧：Troubleshoot 要善用日志
最后分享一个别处不太会提的心得——出现问题先看日志，而不是先改配置。DeepSeek Harness 的日志非常详细，包含了请求链路、工具调用记录、模型推理耗时等关键信息。很多时候你以为的美术问题，在日志里其实写得清清楚楚。
用docker compose logs查看日志时，我习惯加--tail参数只显示最近的内容，避免刷屏。比如：
docker compose logs --tail=200 harness排查问题的时候我会按时间线去对比：我做了什么操作，日志里对应出现了什么输出。这种方式比瞎猜配置项要高效得多。还有日志里如果出现timeout字样，优先怀疑内外网通路，核对白名单和超时设置；出现CUDA out of memory，先看有没有其他进程占了显存，然后用nvidia-smi确认显存占用情况，再决定是换小模型还是调低并发。
6. 最后再聊两句
部署这套平台让我觉得自己不是在“租”一个 AI，而是真正“养”了一个 AI。云端 API 像是住酒店，拎包入住很方便，但房间不是你的；局域网部署 DeepSeek Harness 更像是装修自己的房子，前期工作量大一点，可一旦住进去，水电煤全部自己控制，想怎么折腾都行。
我的建议是你先跑通一个最小可用版本，挂一两个工具，让 Agent 处理一件真实的小任务，比如查个状态、整理个日志摘要。等摸清楚各个组件之间的关系之后，再考虑加大模型、加工具、接数据库、做知识库。这条路越走越宽，而且每一步都能看到实际效果。要是你在部署过程中碰到什么奇葩问题，回来看这篇文章的排查章节，大概率能找到方向。
