Docker 部署 DeepSeek Harness：搭建局域网 AI Agent 私有平台全攻略

最近把一套 DeepSeek Harness 用 Docker 部署到了公司内网，前后折腾了小一周，过程中踩了不少坑，也把整体思路彻底理清了。这篇就围绕“Docker 部署 DeepSeek Harness，搭建局域网 AI Agent 平台”这个主题，把从需求分析、架构设计到具体部署配置、Agent 管理和安全加固的完整过程写出来。如果你正打算在团队内部或者实验室里搞一套私有化的 AI Agent 服务，这篇文章应该能帮你省下不少试错时间。

先说清楚这套东西是什么：DeepSeek Harness 是一个围绕大模型能力构建的 Agent 服务平台，它把模型推理、工具调用（MCP）、角色管理、会话记忆、多 Agent 编排等能力打包在一起对外提供服务。用 Docker 把它跑起来之后，局域网内任何设备通过浏览器就能访问，相当于在办公室里搭了一个自己的“AI 应用中心”。适合的对象很明确：想脱离公网 API 限制做私有部署的技术负责人、需要用开源模型做内部工具研发的工程师、以及高校实验室里需要多人共用大模型能力的课题组。

1. 整体设计思路：为什么是 Docker、为什么是局域网私有部署

1.1 先想清楚这个平台到底要解决什么问题

在动手部署之前，我建议你先花十分钟想清楚一件事：你需要的到底是一个“能聊天的大模型网页”，还是一个“能执行任务的 Agent 平台”？这两个需求导向的架构完全不同。

如果只是想要一个聊天界面，直接用现成的网页应用就行，部署难度很低。但 Harness 这类平台的核心价值在于“编排”——它能把大模型的推理能力、外部工具（比如数据库查询、API 调用、文件处理）、多轮会话上下文、角色人设这些组件统一管理起来。我当时的真实场景是：某公司内部有多个小组需要用大模型处理数据分析、文档生成和信息检索，每个人都在自己的电脑上装客户端、各自去申请公网 API，不仅成本高、数据容易外泄，而且没法统一维护权限。DeepSeek Harness 正好能解决这个多头管理的问题：一个平台、多个用户、权限分明、模型统一。

局域网部署的意义，恰恰在于“不把数据送出去”。公司内部文档、业务数据这些敏感内容，如果走公网 API 存在合规和泄露风险，私有化部署是最稳妥的解决路径。而且局域网带宽大、延迟低，多人同时使用时的体验比公网好太多。

1.2 为什么用 Docker 而不是直接在服务器上装进程

这一点我想多说几句。第一次搭建的时候，我图省事直接在一台 Linux 服务器上装了 Python 环境，然后手动拉取项目代码、装依赖、配置数据库。结果折腾了整整一个下午，中间出现了 Python 版本不兼容、依赖包冲突、系统环境变量被改乱等问题，最后不得不把服务器重装系统才恢复。

Docker 方案的核心优势是“环境隔离”和“开箱即用”。Harness 平台自带的依赖非常多——模型推理库、数据库客户端、Web 框架、消息队列组件，这些依赖之间的版本兼容关系极其复杂。Docker 镜像把整个运行时环境固化成不可变快照，任何一台装有 Docker 的机器，不管底层系统是 CentOS 还是 Ubuntu，都能以完全相同的方式运行。这就是为什么我后来转向 Docker Compose 方案——其实才是我最后推荐的路径。

用 Docker 还有个隐性好处：升级和回滚容易。我部署的这套平台，模型版本升级时只需要拉新镜像、重建容器，切换回旧版本也就是一条命令的事。如果直接装在物理环境里，升级失败后想回退几乎等于重装系统。

1.3 Harness 在整套链路中扮演的位置

把 DeepSeek Harness 拆开来看，它可以分成四层：

• 模型层：这是推理能力来源。可以接 DeepSeek 官方的 API，也可以接入本地部署的开源模型服务（比如通过 Ollama 或 vLLM 跑起来的模型）。
• 推理网关层：负责把 Agent 的请求路由到不同的后端模型，处理超时重试、并发控制、令牌配额这些逻辑。
• Agent 编排层：这是 Harness 的核心。它管理每个 Agent 的身份设定、工具列表、记忆存储、任务分解逻辑。Agent 本质上被定义成一组完整的“人格 + 技能 + 记忆”的数据结构。
• 应用层：Web 界面、API 接口、管理后台、用户认证这些对外交互的部分。

Docker 部署的核心任务，就是把上面这四层按依赖关系装配成一组容器编排。模型层和后端服务可能分布在多个容器里，Agent 编排层和 Web 应用在另一个容器里，数据层用独立容器存储。通过 Docker Compose 可以一键启动整个集群。

注意：有些人会把“Harness”理解成某个具体的开源项目名。其实更准确地说，Harness 在这里是指一种“Agent 治理框架/承载平台”的统称。具体部署时你可以选择开源项目，也可以基于主流技术栈自研，本质思路是一样的：Docker 容器化 + 服务编排 + 配置化管理。

2. 部署前的准备工作：硬件评估、Docker 环境与镜像选型

2.1 硬件资源估算：先算账再动手

部署 AI 平台不是无中生有，硬件资源直接决定你能跑多大的模型、支持多少并发用户。我的建议是先做一个简单的资源估算，再决定用什么型号的服务器。

如果接入的是云端 API（DeepSeek 官方接口），对本地硬件要求并不高——4 核 CPU、8G 内存就能跑得很流畅，因为推理计算都在远端完成。但如果你打算在本地跑开源模型（比如通过 Ollama 托管），那就要认真算一笔账：

• 7B 级别的量化模型：建议 GPU 显存不低于 6G，或者 16G 内存纯 CPU 推理（速度较慢但能用）。
• 14B 级别的量化模型：GPU 显存 12G 起步，16G 以上体验较好。
• 32B 级别：非专业人士不推荐本地跑，需要 24G 以上显存，成本太高。

我部署的环境是一台 8 核 32G 内存的工作站加一块 24G 显存的 GPU，运行量化版模型很顺畅，同时支持大约 20 个内部用户并发使用。如果你没有 GPU，纯 CPU 模式也不是不能用，只是响应速度会慢很多——实测一个 7B 量级的模型，生成 200 字左右的回复，CPU 模式大约需要 2 到 4 分钟，GPU 模式下只需要 5 到 8 秒。

磁盘空间也要规划好：模型文件动辄十几 GB，加上容器镜像、向量数据库、日志文件，建议预留至少 100G 空间。生产环境最好用单独的磁盘挂载数据目录，避免容器重建时数据丢失。

2.2 Docker 安装与环境配置三步走

Docker 本身安装不复杂，但有几个细节值得单独强调。

第一步是安装 Docker Engine 和 Compose 插件。Linux 服务器上现在推荐用官方源直接安装，安装完成后用docker version验证客户端和服务端都正常。启动 Docker 服务并设置开机自启，这两步别漏掉，否则服务器重启后容器不会自动拉起。

第二步处理镜像加速问题。国内直接拉取 Docker Hub 的镜像经常超时，解决方法是配置镜像加速地址。编辑/etc/docker/daemon.json文件，添加 registry-mirrors 配置后重启 Docker。实测配置加速后，拉取镜像的速度可以从原来的几 KB 提升到几 MB 甚至几十 MB。

第三步是配置普通用户免 sudo 执行 docker 命令。把当前用户加入 docker 用户组，然后用newgrp docker激活。这一步虽然不是必需，但每次敲sudo docker真的会让人崩溃，建议一开始就配好。

2.3 镜像选型：干净、精简、可复现

镜像选型是整个部署过程中最容易被忽视、却最影响长期维护体验的环节。我总结三个原则：

• 优先选择官方或社区维护活跃的镜像。查看镜像的更新频率和 star 数量，长期不更新的镜像往往存在安全漏洞和依赖版本过旧的问题。
• 尽量选 alpine 或 slim 版本的基础镜像，运行时镜像比开发镜像小很多，能减少磁盘占用和攻击面。
• 确认镜像的架构和宿主一致。绝大多数服务器是 x86_64，但如果你的机器是 ARM 架构，一定要拉着明确标注 arm64 的镜像。

我当时的做法是先在本机拉取目标镜像，用docker image inspect查看镜像详细信息和配置，确认没有异常后再部署。部署完成后用docker commit把配置好的环境固化成自定义镜像，这样团队里其他人就能直接加载，完全复现同一套环境。

3. 核心部署流程：Compose 编排、环境变量、首次启动

3.1 用 Docker Compose 描述整套服务编排

手工执行一条条docker run命令管理多容器方案，效率太低而且容易遗漏参数。我强烈推荐用 Docker Compose，通过一个 YAML 文件描述全部容器、网络、卷、环境变量，然后一条docker compose up -d搞定全部服务。

下面是一个典型的 Compose 编排文件结构，核心服务划分成三个：模型服务、Agent 平台本体和数据库：

version: "3.8" services: # 模型服务端，通过 Ollama 托管开源模型 ollama: image: ollama/ollama:latest container_name: ollama restart: unless-stopped volumes: - ./data/ollama:/root/.ollama ports: - "11434:11434" deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] networks: - ai-platform # DeepSeek Harness 核心服务 harness: image: your-registry/deepseek-harness:latest container_name: harness restart: unless-stopped depends_on: - ollama environment: - OLLAMA_BASE_URL=http://ollama:11434 - DATABASE_URL=postgresql://harness:secret@postgres:5432/harness - SECRET_KEY=change-me-in-production - DEFAULT_MODEL=deepseek-r1:14b - ENABLE_MCP_TOOLS=true ports: - "8080:8080" volumes: - ./data/harness:/app/data networks: - ai-platform # PostgreSQL 数据库，存储会话和用户数据 postgres: image: postgres:16-alpine container_name: harness-db restart: unless-stopped environment: - POSTGRES_USER=harness - POSTGRES_PASSWORD=secret - POSTGRES_DB=harness volumes: - ./data/postgres:/var/lib/postgresql/data networks: - ai-platform networks: ai-platform: driver: bridge

这个编排文件的逻辑很简单：harness 服务依赖 ollama 和 postgres，三个服务通过同一个 bridge 网络互相通信。harness 对外暴露 8080 端口，用户浏览器访问服务器 IP 的 8080 端口进入平台。

3.2 环境变量配置的常见坑

环境变量是 Compose 部署最容易出错的地方，我逐个解释关键配置项。

OLLAMA_BASE_URL必须写容器间的服务名而不是 IP。因为 Docker 容器每次重建 IP 可能变化，但同一网络内服务名是不变的。我第一次部署时写了http://localhost:11434，结果容器内访问不到，后来改成http://ollama:11434立刻正常。

DATABASE_URL里的主机名同样要写数据库容器名postgres。数据库密码这类敏感信息，在开发环境可以直接写在 compose 文件里，但生产环境建议改用.env文件存储，并在.gitignore中排除，避免凭证泄露。

SECRET_KEY是平台内部的签名密钥，用来加密会话 Cookie 和 API Token，绝对不能用默认值。可以用命令生成随机字符串，比如openssl rand -hex 32，然后把结果填进去。

还有一个容易忽略的配置：DEFAULT_MODEL设置默认使用的模型名称。这个名称必须和 Ollama 里实际拉取的模型标签完全一致，否则会提示模型不存在。我建议在部署前先手工执行ollama pull deepseek-r1:14b确认模型已下载，再启动 harness。

3.3 首次启动：从日志判断服务是否正常

配置完成后执行docker compose up -d，首次启动会拉取所有镜像，这个过程可能需要几分钟。启动完成后用docker compose ps查看状态。

如果一切正常，三个服务都应该是Up状态。然后用docker compose logs -f harness跟踪核心服务的启动日志，正常情况会看到类似这样的输出：数据库连接成功、模型服务检测通过、Web 服务监听 0.0.0.0:8080。

常见的问题藏在日志尾部：如果出现“cannot connect to database”的报错，多半是数据库还没初始化完成，等待几十秒后重启 harness 服务即可。如果提示“model not found”，去 Ollama 容器里执行ollama list看看模型是否存在。

启动完成后，浏览器访问http://服务器IP:8080。如果页面能正常加载并出现登录界面，说明整套环境部署成功。

4. Agent 平台的使用与工具生态扩展

4.1 创建多个 Agent：角色、模型、技能的绑定

平台跑起来只是第一步，真正发挥 Harness 价值的是创建和管理多个 Agent。我强烈建议不要只建一个“通用助手”，而是根据团队的实际任务拆成多个专用 Agent。

举例来说，我的部署里创建了三个 Agent：

• 数据分析助手：绑定读数据库的工具，能够执行 SQL 查询并生成分析结论。
• 文档助手：绑定文档解析工具，能处理上传的 PDF、Word 文件并提取关键内容。
• 日常问答助手：不绑定任何外部工具，只做通用信息检索和对话。

每个 Agent 的配置项包括：角色人设（System Prompt）、绑定的工具清单、使用的模型、上下文窗口大小、是否允许多轮记忆。这几个配置项里，人设是决定输出风格的关键，写成“你是一位资深数据分析师，回答必须包含数据来源和限制条件”和写成“你是一个友好的助手”得到的输出质量天差地别。

绑定工具时要注意工具的权限边界。我不建议一开始就给所有 Agent 全部工具权限，因为工具越多，模型在任务规划时越容易出现混乱。基本原则是“按需分配”，让每个 Agent 掌握与职责匹配的最小工具集，既提升任务完成率，也降低安全风险。

4.2 通过 MCP 接入外部工具链

MCP（Model Context Protocol）是 Harness 平台用来对接外部工具的标准协议。简单理解，它就是一套让大模型能够调用外部系统接口的标准化通信协议。通过 MCP，Agent 可以执行文件操作、查数据库、发 HTTP 请求、操作浏览器，理论上能接入任何你想让模型操控的系统。

在配置 MCP 工具时，我最想提醒的是“描述信息决定调用成功率”这一条。MCP 服务器的配置里有个关键字段“工具描述”，模型会根据这个描述来判断什么时候调用该工具。比如你接入一个查询订单的工具，把描述写成“查询订单状态”，模型只在用户问订单时考虑调用；但如果写成“用于查询订单状态、物流信息、退换货进度，输入订单号或手机号均可查询”，模型就能更精准地匹配用户意图。

平台容器内的网络环境和宿主机不同，MCP 服务地址如果是局域网内的某个接口，要确保容器网络能够访问到该地址。当时我接入内部知识库接口时，发现容器内访问不通，排查半天才发现是防火墙规则只放行了宿主机 IP。解决办法是把 MCP 服务跑在 Docker 网络内，或者调整防火墙规则。

关于 MCP 工具的编排，我建议做一份工具与 Agent 的映射表，方便后续维护。工具粒度不要太细，如果一个功能被拆成 10 个细粒度工具，模型在做调用决策时会非常困难。把相关操作合并成一个工具函数，每个函数支持参数配置，能有效降低模型的决策压力。

4.3 会话记忆与私有知识库的挂载

Agent 的上下文记忆机制同样值得重视。默认情况下，大模型只能看到当前对话窗口内内容，一旦超出窗口长度，早期信息就会被截断。Harness 平台会在后端维护用户会话的历史消息，并在每次请求时动态拼装上下文，这既让 Agent 具备“记住你说过什么”的能力，也考验上下文管理的策略。

我遇到的典型问题是“记忆污染”：当会话延续特别长之后，早期无关紧要的闲聊内容占满了上下文窗口，导致模型忽略了最新也是最重要的指令。解决办法是开启系统的“记忆压缩”功能，把早期对话内容摘要成几条核心结论，替换掉原始对话记录，释放上下文空间。

私有知识库是另一个高频需求。内部文档、产品手册、客户反馈这些数据如果直接塞进 Prompt，既不现实也浪费令牌。正确做法是把知识库文档切片、向量化后存入向量数据库，检索时通过语义匹配找到最相关的片段，再拼进 Prompt。Harness 平台支持配置知识库来源，每种来源对应一类数据接入方式。

我在实践里踩过的坑是：文档切片太大会导致检索精度下降，切片太小又会让上下文碎片化。经过反复测试，中文文档建议 300 到 500 字为一个切片，相邻切片重叠 50 字左右，配合语义向量模型，检索效果比较理想。

5. 局域网访问、安全加固与性能调优

5.1 局域网访问的三种方式与选型建议

部署完成后，团队成员的访问方式有几种选择，各有优缺点。

最简单的方式是直接通过http://服务器IP:8080访问。搭建成本最低，但端口暴露在局域网内，任何能连到该网络的人都可以访问。如果只是临时测试问题不大，但正式使用不建议裸奔。

更好的方式是用反向代理统一入口。可以用 Nginx 在 80 端口挂一个域名，比如ai.internal.company.com，再把请求转发到 8080。这样团队成员只需要记住一个域名，不用记端口。在 Nginx 层还可以额外配置访问控制、请求频率限制和 TLS 证书，安全性和可用性都提升一个档次。

第三种方式是把 Harness 接入公司统一身份认证体系（比如 LDAP 或 OAuth2）。这个方案实施成本最高，但对于几十人以上的团队来说最合适，账号生命周期管理完全和人事系统同步，不用在平台里单独管理账号。

我当时选的是反向代理方案，单独申请一套内部域名和 TLS 证书，同时关闭服务器上不必要的对外端口，防火墙只放行 80、443 和 22（管理端口）。

5.2 安全加固清单：默认配置千万别直接上生产

我列一份自检清单，部署完照着检查，能挡掉大多数低级安全风险：

1. 修改所有默认密码。平台管理员的初始密码，数据库密码、API 密钥全部换成强随机值。
2. 关闭调试模式。Harness 平台默认可能开启 debug 模式，生产环境必须关闭，否则错误堆栈会泄露源码路径和内部网络结构。
3. 启用访问日志和审计日志。记录每个用户的登录行为、Agent 调用记录、工具执行记录，为问题追踪留底。
4. 对出站流量做限制。容器默认网络可以访问外网，如果条件允许，建议限制特定 Agent 只能访问白名单内的地址，防止模型被诱导调用任意 HTTP 请求引发安全问题。
5. 敏感数据加密存储。会话记录里如果可能包含业务敏感数据，数据库需要启用加密或者定期清理过期会话。

局域网不等于绝对安全。内部网络的信任边界通常比较模糊，很多攻击都来自内网渗透。所以平台自身的安全措施一点都不能少，用户权限要看牢——普通用户和平台管理员权限要严格分离，能不给用户的权限就不给。

5.3 性能调优：并发、缓存与资源限制

跑起来之后，性能调优是个持续迭代的过程。先看几个关键参数。

并发能力方面，Harness 平台本身是 Web 服务，默认配置能撑住几十个用户同时在线，但真正决定瓶颈的是模型服务的吞吐。如果走本地 Ollama 推理，GPU 同时只能处理有限的请求队列，当多个用户同时发起请求时，后面的请求要排队等待。为此平台侧提供了请求队列配置，超出并发阈值的请求可以进入队列排队，而不是直接报错，这个配置对体验提升非常明显。

响应时间方面，我在使用中发现文本生成速度是最大的瓶颈。解决方案之一是开启“流式输出”模式，让用户看到文字逐字生成。虽然总耗时没变，但体感响应时间从十几秒降到一两秒，团队反馈好很多。

缓存策略上，对于高频的固定问题可以开启答案缓存。平台会为相同输入返回缓存结果，跳过模型调用环节。这个功能适合知识库问答场景，但要注意对需要实时数据的 Agent 关闭缓存，否则会返回过期信息。

最后是资源限制。生产环境建议在 Compose 文件里为每个容器配上 CPU 和内存上限，防止单个失控任务把整台服务器拖垮。比如限制 Ollama 容器最多使用 24G 内存，harness 容器最多 8G，超出阈值会被系统杀掉而不是拖垮其他服务。

6. 常见问题与排查实录

6.1 高频问题速查表

我把部署和运行中实际遇到过的问题整理成了一张表，方便你对照排查：

6.2 排查思路：先看日志，再看网络，最后查配置

排查这类部署问题，我的固定流程是先看日志，再看网络，最后查配置，按这个顺序能少走很多弯路。

日志是最直接的信息来源。每个容器都要启动日志记录，用docker compose logs -f可以实时观察。日志里出现ERROR、Traceback这样的关键词，直接定位到对应服务。

网络排查主要确认容器之间的连通性。进入任意一个容器，用curl http://其他服务名:端口测试是否能通。注意容器内不一定自带 curl，可以先apt-get安装或者换成wget。

配置排查最隐秘。环境变量写错、端口映射配错、模型名不一致，这些错误表面症状五花八门，通常要回到编排文件和配置项逐一比对才找得到。实践中最实用的技巧是：把整个 Compose 文件里所有从外部传入的值都用简单、确定性的测试值替换，逐项验证，定位问题就会快很多。

6.3 几个容易后悔的操作教训

最后分享几个我实际踩过、后来总结成经验教训的操作。

第一个是在数据目录结构上吃过亏。刚开始我把所有数据都放在容器内部，升级镜像时容器重建，数据直接没了。后来强制规定所有持久化数据必须走 volume 挂载，对外暴露成宿主目录，现在升级、迁移、备份都非常方便。

第二个是在升级镜像时没有先看兼容性说明。有一次我看到新版本就着急升级，结果平台代码和数据模型变更，旧数据库结构无法兼容，导致整个服务不可用。教训是升级前先看项目文档里的迁移指南，备份数据库后再动手，同一大版本内的升级一般都平滑，但跨大版本一定要谨慎。

第三个是忘了限制容器日志的大小。高并发时容器的 stdout 日志快速增长，几天就把磁盘空间打满，导致服务异常。在 Compose 文件里全局配置日志轮转，限制单个日志文件大小和保留数量，这个操作成本极低，长期收益非常大。

第四个是在调整模型参数时过分追求“大”。一开始我总想跑更大的模型，觉得效果一定更好。实际上，在业务场景中更聪明的做法是匹配“任务复杂度”。简单归纳总结用小模型就够了，复杂推演才用大模型，在平台里配置多档模型供不同 Agent 选择，能显著提升整体资源利用率。

部署这套局域网 AI Agent 平台给我最大的体感变化是，团队里每个人都开始接触 Agent 能力，整个工作流被重构了，而不只是多了一个“能聊天的工具”。数据在内部流转，模型能力按需分配，工具按角色挂载，团队协作效率提升非常明显。后续还可以扩展的方向包括接入语音输入、自动化定时任务、与其他内部系统深度集成。如果你在部署过程中遇到问题，多看看项目文档，多翻日志，多拆配置——这套方法论能帮你解决绝大多数问题。