1. 为什么要把 Agent 平台搬进局域网
先讲一个我自己的经历。前阵子团队里几个人都想让 AI 帮自己跑点自动化任务，结果各干各的——有人注册了云端账号，有人自己写了脚本调模型接口，也有人直接在用网页版聊天。表面看大家都很积极，实际上问题一堆：每个人的 API Key 都是自己管，月底账单对不上；脚本写得很随意，人走了就没人维护；更麻烦的是，有些内部数据要喂给模型做分析，绕了一圈外部服务，心里始终不踏实。
后来我调整了思路：与其让每个人各自为战，不如在一台内网服务器上用 Docker 部署一套统一的 AI Agent 平台，所有人都走同一个入口，模型接入统一配置，任务记录和工具调用都集中在同一个地方。这篇文章要讲的就是这个方案——用 DeepSeek Harness 这套平台，把 Agent 的编排、调度、工具管理全部收拢到局域网里，几分钟就能起一套能用的服务。
这里需要先解释一下 "Harness" 这个词。它不是测试领域里那个 "测试夹具"，而是"给 Agent 套上缰绳"的意思。你可以定义 Agent 用什么模型、挂载哪些工具、负责哪类任务，平台负责跑任务循环、调度并发、追踪过程、回收结果。它解决的不只是"有一台机器能跑模型"，而是"整个团队能规范、稳定、安全地用上 Agent 这件事"。
这篇文章适合谁看？如果你在做团队的 AI 基础设施，想把个人实验环境从云上迁回本地，或者只是想知道 Docker 部署 AI 平台的完整链路，下面的内容应该能直接落地。我尽量不写口号，只讲我实际跑过的过程、调过的参数和踩过的坑。
2. 先把 DeepSeek Harness 的工作方式拆明白
2.1 平台核心到底有哪几块
上手之前，先建立整体认知。DeepSeek Harness 这套系统，从功能上可以拆成五块：
- 模型网关：统一封装 DeepSeek 模型的接口调用，负责鉴权、超时、重试和用量统计。有了它，你不必在每个 Agent 里各写一套 API 逻辑。
- Agent 运行时：真正执行 Agent 循环的地方。Agent 接收任务、判断下一步、调用工具、观察工具结果、继续推理，直到任务完成。
- 工具注册中心：把可用的工具注册进平台，比如执行命令行、查询数据库、调用内部接口、读写文件等。Agent 在需要时按名称调用。
- 任务调度与队列：处理并发请求、控制任务优先级，避免多个 Agent 同时把模型服务或服务器资源打满。
- Web 控制台：人机交互的入口，在浏览器里创建 Agent、发起任务、查看执行日志和结果。
这五个模块在 Docker 部署时会被打包成几个容器，容器之间通过内部网络通信。把"编排逻辑"和"模型调用"分开，是这类平台最核心的设计思路，理解了这个分层，后面看配置就不晕。
2.2 Harness 和直接调模型接口有什么区别
很多人第一反应是：我手里有 API Key，直接写个 Python 脚本调接口不就行了，为什么还要多一层平台？
区别主要在"多步任务"和"工具使用"。直接调模型接口适合一问一答，但 Agent 的典型场景是"先查一下库存、再算一下补货量、然后生成采购建议"这种多步骤流程。Harness 管的是这个循环本身：Agent 需要信息，平台帮它取；Agent 想调工具，平台做鉴权；Agent 中途报错，平台记录现场并决定重试还是终止。
拿开车来类比：模型接口只是发动机，Harness 是驾驶舱。发动机提供动力，但方向盘、仪表盘、刹车、导航都在驾驶舱里。你要跑的不是一条直路，而是带路口、带停靠点的复杂路线，光有发动机是到不了目的地的。
3. 部署前的准备：硬件、系统和容器规划
3.1 一台能跑得动的服务器
先把硬件需求说清楚，避免一上来就买高配。DeepSeek Harness 本身是编排平台，CPU 的占用大头通常在任务并发和日志处理上，真正的算力开销取决于模型怎么接：
- 走云端模型接口：模型在外部跑，本机只需要 4 核 8G 内存就能带得动整套平台，多的内存给日志和缓存。
- 本地跑模型：这才吃配置。7B 左右的量化模型，16G 内存加一张 8G 显存的显卡可以玩得很舒服；再大的模型就别硬撑了，要么换云接口，要么上专用卡。
我自己用的是一台旧工作站，8 核 CPU、32G 内存、带一块中等显存的显卡。部署完成后实测，日常三五个任务并发、日志保留一周的情况下，CPU 占用在 30% 上下，内存稳定在 6G 左右，完全在可接受范围。
3.2 Docker 环境安装与目录规划
系统我用的是 Ubuntu Server。装好 Docker 和 Compose 插件之后，最重要的一件事是把目录规划清楚，不要随便找个地方就 clone 项目。下面是我用的目录结构：
/opt/deepseek-harness/ ├── config/ # 全局配置和模型接入配置 ├── data/ # 持久化数据，包括任务记录和结果 ├── tools/ # 自定义工具脚本挂载目录 └── docker-compose.yml目录先建好，后面所有容器的挂载卷都指向这套结构。这样升级版本、迁移机器、备份数据都只操作一个目录，成本非常低。官方仓库里一般带着示例配置，先把仓库 clone 下来，照着目录结构调整一遍，比手动一个个创建目录要省事。
提示：安装 Docker 后记得把当前用户加入 docker 组，不然每条命令前都要加 sudo。组变更之后要重新登录终端才会生效，这一步特别容易忽略。
3.3 容器拓扑怎么设计
部署前先在脑子里过一遍容器关系。我用的是最小组合三容器方案，后面按需再扩展：
| 容器 | 职责 | 说明 |
|---|---|---|
| harness-web | Web 控制台 | 提供浏览器界面和 API 入口，对外暴露端口 |
| harness-runner | Agent 执行引擎 | 跑任务循环，与 web 通过内部网络通信 |
| harness-gateway | 模型网关 | 统一管理 DeepSeek 模型调用、超时与重试 |
数据卷分别挂载 config、data 和 logs，任何容器重建都不会丢数据。三个容器放在同一个自定义网络里，端口只让 web 对外开发，runner 和 gateway 不暴露到宿主机，减少被外部访问到的可能。
4. 用 Docker Compose 把整套服务拉起来
4.1 最小可用的 docker-compose.yml
下面这份配置是我实际用下来精简过的版本，去掉了花哨参数，保留核心。可以直接抄，再根据版本微调：
services: gateway: image: harness/gateway:latest container_name: harness-gateway env_file: .env volumes: - ./config:/app/config networks: - harness-net restart: unless-stopped runner: image: harness/runner:latest container_name: harness-runner depends_on: - gateway environment: - GATEWAY_URL=http://gateway:8080 volumes: - ./data:/app/data - ./tools:/app/tools networks: - harness-net restart: unless-stopped web: image: harness/web:latest container_name: harness-web depends_on: - runner ports: - "8080:8080" environment: - RUNNER_URL=http://runner:9000 volumes: - ./config:/app/config networks: - harness-net restart: unless-stopped networks: harness-net: driver: bridge这个配置有几个关键点：
- 网络：三个容器共享一个 bridge 网络，容器之间用服务名互相访问，这是 Compose 默认行为，不需要手动写死 IP。
- 依赖顺序：web 依赖 runner、runner 依赖 gateway，保证启动时模型网关先就绪。不过这个依赖只是"启动顺序"，不是"服务就绪"，真正的就绪判断要加健康检查，后面我会专门讲这个坑。
- 重启策略：全部用
restart: unless-stopped，服务器意外重启后服务能自动拉起来，不用人肉干预。
4.2 环境变量和模型接入配置
.env文件是配置核心，核心字段说明如下：
# DeepSeek 模型接口配置 DEEPSEEK_API_KEY=sk-你的密钥 DEEPSEEK_BASE_URL=https://api.deepseek.com DEEPSEEK_MODEL=deepseek-chat # 平台配置 HARNESS_PORT=8080 HARNESS_LOG_LEVEL=info HARNESS_MAX_CONCURRENCY=5HARNESS_MAX_CONCURRENCY值得多说一句。它控制同时执行的任务数，不是越大越好。我一开始直接设成 20，结果并发任务一多，模型接口超时率唰唰往上飙。后来调回 5，单个任务执行时间虽然稍长了一点，但整体稳定性明显改善。这个值要根据你接的模型服务能力和团队实际使用频率来调整，不能拍脑袋。
4.3 首次启动的完整步骤
配置准备好之后，启动过程非常短：
- 进入目录：
cd /opt/deepseek-harness - 拷贝示例配置：
cp .env.example .env，然后编辑填上模型接口密钥 - 拉起全部服务：
docker compose up -d - 查看启动日志：
docker compose logs -f - 确认三个容器都进入 healthy 状态后，浏览器访问
http://<服务器IP>:8080
首次启动要拉取镜像，网速慢的话会等一会儿。启动完成后打开控制台，第一件事是到系统设置里确认模型连通性。平台一般会提供"测试连接"之类的按钮，点一下能直接返回模型响应，这个验证步骤千万别跳过，不然后面排查问题会很难分清是平台问题还是模型接口问题。
5. 接本地模型还是云端接口：两条路怎么选
5.1 走云端接口的配置方式
云端接口的接入最省事，技术上只需要在网关配置里填上接口地址和密钥。优点很明显：模型能力强、维护成本低、不用管硬件。缺点是数据要经过第三方服务，而且局域网里做内部自动化时，每次请求都要走外网，延迟和稳定性不可控。
如果你只是想快速让团队用上 Agent，不涉及敏感数据，这条路最快。实测下来，一次简单任务的响应时间大约在 1 到 3 秒，取决于外网状况和模型服务的负载。
5.2 本地模型的接入思路
本地跑模型这件事，我在同一套平台上也验证过。思路很简单：再起一个模型服务容器，让网关把请求转发到本地地址。目前社区用得比较多的有 Ollama 和 vLLM 两条路线，取舍如下：
| 对比项 | Ollama | vLLM |
|---|---|---|
| 上手难度 | 低，一条命令拉起 | 中，需要写启动参数 |
| 并发能力 | 一般 | 高，适合多任务并发 |
| 硬件要求 | 相对低 | 需要较好 GPU 支持 |
| 适合场景 | 个人实验、小团队 | 高并发、生产化 |
我的做法是先用 Ollama 起一个小参数模型把流程跑通，再考虑要不要迁移到 vLLM。本地模型的价值不全在性能，而是"数据不出内网"和"请求延迟稳定"这两件事。对敏感业务来说，这两点比模型能力重要得多。
5.3 混合模式：按任务分路由
如果不想二选一，可以在网关里配置多套模型路由：普通任务走本地小模型，复杂推理走云端大模型。DeepSeek Harness 的任务定义里一般可以指定模型或模型分组，这样就同时保住了成本和能力上限。
这个混合设计，我觉得是局域网 Agent 平台最实用的一种形态。核心原则就一句话：高频、简单、敏感的任务放本地，低频、复杂、非敏感的任务放云端。按这个原则配路由，账单和体验都能兼顾。
6. 局域网访问、账号权限和数据持久化
6.1 端口暴露和访问方式
平台起来后，默认只开放 8080 给局域网用户。团队规模小的时候，直接浏览器输入http://IP:8080就够了，不用做任何额外配置。但如果想用得舒服，建议加一层反向代理，把 HTTP 请求转发到 Web 端口的服务上，顺便把 HTTPS 证书也配上。
我用的反向代理是 Nginx，配置很简单，核心就是一个 server 块把 80/443 转发到 8080。加了代理之后，团队成员访问一个干净的域名就能进控制台，不用记端口号。注意内网也需要一套 DNS 解析或者干净的 hosts 文件，这个细节在团队协作里非常影响体验，提前配好能少很多解释成本。
6.2 账号与权限的最小配置
DeepSeek Harness 自带简单的账号体系。部署时我建议至少做三件事：
- 第一时间改掉默认管理员密码，不要在新服务上保留默认凭据。
- 按角色分账号。管理员负责配置模型和工具，普通成员只发任务、看结果，权限边界要清晰。
- 关掉匿名访问。除非你的网络环境非常可信，否则匿名入口永远是风险点。
有人觉得内网部署就不用管权限，其实正好相反。内网攻击面确实小，但一旦出问题，暴露的就是内部数据。宁可开头多花十分钟配权限，也别等出事了再补。
6.3 数据卷和备份策略
平台跑久了，任务历史、日志、Agent 配置都会变成有价值的数据资产。我的备份方案很简单：每天凌晨用一条 tar 命令打包整个 data 目录到另一块磁盘：
tar czf /backup/harness-$(date +%Y%m%d).tar.gz -C /opt/deepseek-harness data恢复同样简单：解压回原目录，重启容器，数据就回来了。当初选择这种"目录即数据"的部署结构，就是看中它没有数据库导出导入的额外步骤，迁移和灾难恢复都特别直接。
7. 跑了一周之后：实测性能与资源占用
平台稳定运行一周后，我记录了一些基础数据，可以给准备部署的朋友一个参考。
资源占用方面，三个人日常使用、每天大约 40 个任务、其中一半是定时任务的负载下：网关容器内存约 300MB，runner 约 1.2GB，web 约 400MB。CPU 在任务高峰时能短暂冲到 70%，多数时间在 10% 到 30% 之间浮动。磁盘主要是日志，一周大约 800MB，我给日志卷配了 30 天的保留策略，定期自动清理。
任务稳定性方面，本地小模型的成功率更稳定。常规任务成功率在 99% 以上，偶尔失败也是工具执行超时引起的。云端接口在长任务上偶发网络抖动导致重试，但网关自带的重试机制能兜住大部分情况，用户侧基本无感。
这些数字说明一个事实：一个四五人的小团队，一台普通服务器就能稳稳跑起整套 Agent 平台，完全没必要为了"AI"两个字盲目堆配置。先把部署结构做好，后面再按需扩容。
8. 部署中最常见的四个坑和排查思路
8.1 启动顺序导致的连接失败
第一次部署时，我在日志里看到 runner 启动时报GATEWAY_URL连接失败。原因在于 Compose 的depends_on只能保证启动顺序，不能保证服务真正就绪。gateway 容器起来了，但进程还没开始监听端口，runner 就急着去连接了。
正确做法是给网关容器加健康检查：
gateway: image: harness/gateway:latest healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8080/healthz"] interval: 10s timeout: 3s retries: 5 restart: unless-stopped然后在依赖方加上就绪条件：
runner: depends_on: gateway: condition: service_healthy改完重启，这个问题就消失了。如果不想改配置，也有人用sleep 30 &&这种粗暴办法，但我不推荐，健康检查才是一劳永逸的干净方案。
8.2 端口冲突：8080 被占用
8080 是内网服务器上特别常见的端口，其他服务经常在用它。我第二次部署时就撞上了，日志里反复出现address already in use。
排查过程是这样：先用ss -tlnp | grep 8080找到占用端口的进程，确认不是平台自己的进程后，直接把 web 容器的端口映射改掉：
ports: - "18080:8080"改完记得把反向代理那边的 upstream 也同步更新。这种低级问题一旦出现，排查起来反而比部署更费劲，所以我建议在规划阶段就把端口定好，别等撞了再改。
8.3 密钥明文写在配置文件里
.env文件是明文存密钥的，这一点很多人会忽略。我第一版部署时，把模型接口密钥直接写进.env，后来整个目录被同步到了团队共享网盘，等于密钥裸奔了好几天，想起来都后怕。
后来改进的方式是：给.env加文件权限，只有特定用户能读；同时定期轮换密钥。更严谨的做法是引入密钥管理工具，但对小团队内部平台来说，权限收紧已经足够。别让配置文件随便进共享目录，这是最基本的底线。
8.4 任务队列堆积时模型响应变慢
还有一次是并发任务飙到 15 个，runner 等待队列里堆了 20 多个任务，单个任务响应时间从 2 秒涨到 30 秒。排查发现是本地小模型吞吐不够，加上网关没有做并发限制。
处理方案是同时做两件事：把HARNESS_MAX_CONCURRENCY从 20 降回 5，然后在网关配置里给模型接口设置 15 秒超时。效果立竿见影，队列虽然没完全清空，但响应时间回到了合理区间，任务之间也不再互相拖死。
9. 跑稳之后，平台还能怎么扩展
平台稳定运行后，能玩的方向其实很多。
第一类是自定义工具。我在tools目录下挂了一个内部汇报脚本，Agent 完成任务后会自动调用它，把结果整理成固定格式推到团队群。这完全是通过平台的"工具注册"功能实现的，不需要额外写服务，非常灵活。
第二类是定时任务。Harness 的任务调度支持 cron 表达式，我给运维同事配了一个每天早上 9 点跑的巡检任务，自动汇总服务器状态和日志异常，结果直接写进任务记录。这比人工每天查一遍省太多事。
第三类是观察与调优。跑上一两周后，去控制台看任务成功率、平均时长、工具调用次数这些指标。你会发现大量 Agent 失败的共性问题，比如某个工具的参数格式总出错。针对性地改提示词或工具定义，比盲目换模型有效得多。
最后说一句我的实际体会：把平台搬进局域网，最大的收益不是省了几块钱接口费用，而是整个团队对 AI 工具有了可控感。模型能力来自外部，但使用方式、权限边界、数据流向都掌握在自己手里。这种掌控感，才是这套部署方案真正值钱的地方。
