企业官网建设流程全解析

1. 为什么是 Docker + AI Agent 这个组合

我这两年接触 AI Agent 相关项目比较多，发现一个特别普遍的现象：很多人把基于大模型的 Agent 跑在本机，代码调得好好的，一旦想给局域网里的同事、同学、或者自己另外一台电脑用，立刻就陷入依赖地狱。Python 版本冲突、CUDA 版本对不上、Pytorch 装完报错、缺 so 文件……一套环境折腾下来，往往比写功能本身还耗时。

这个标题里的Docker 部署 DeepSeek Harness，本质上就是为了解决这个痛点：把 Agent 平台连同推理引擎、Web 交互界面、任务调度模块，一起打包成标准化的镜像，在任何一台装了 Docker 的机器上拉起来就能跑。我在实际使用中最大的感受是：容器化带来的确定性，比环境搭建的灵活性要重要得多。

DeepSeek Harness 这个名字你可以理解为“基于开源推理模型的自托管 Agent 工作台”，它的核心逻辑很简单：通过 Docker 容器把一个轻量级的 Agent 运行时封装起来，对外提供 Web 操作界面和标准化 API 接口。部署完成之后，你在浏览器里打开一个地址，就能和 Agent 对话、给它布置任务、让它调用工具链处理文件，整个过程完全跑在你自己控制的局域网内部。

适合什么人参考这篇文章？三类人最对口：一类是折腾过本地大模型但被环境配置劝退的朋友，一类是实验室或小团队里想共享 AI 能力的组织者，还有一类是做 AI 应用开发、想快速测试 Agent 框架的工程师。下面我会把完整的部署思路、Compose 编排细节、以及我实测中踩过的坑都摊开来讲。

2. 整体架构拆解：这个平台到底由哪几部分组成

2.1 Harness 的本质：不只是“套壳”

很多人第一次听到“Agent 平台”这个概念，会以为就是一个聊天界面加一个模型 API。但如果拆开来看，一个可用的 Harness 至少要包含四个模块：

• 推理引擎：负责加载模型、处理 Token、生成回复。在 DeepSeek Harness 的场景里，这一步可以调用本地部署的模型服务，也可以对接外部兼容 API，但既然标题强调“局域网”，默认就是完全自托管。
• Agent 调度器：负责解析用户意图、拆解任务、编排工具调用流程。这是 Agent 和普通聊天机器人的本质区别——它不只是回答问题，而是通过“思考-行动-观察”的循环完成多步骤任务。
• 工具链插件：比如文件读写、知识库检索、定时任务、HTTP 请求等能力。这些是 Agent 能干活的根本原因。
• Web 交互层：供人类用户访问的前端页面和 WebSocket 通信接口。

这四个模块如果全部直接装在宿主机上，相互之间的依赖和版本耦合会让人非常头疼。用 Docker 之后，每个模块独立成容器，通过内部网络互相通信，谁挂了重启谁，互不影响。比如推理引擎吃显存崩溃了，Web 界面层还在，等待引擎恢复即可。

2.2 为什么是 DeepSeek 这个方向

这里补充一下我的选型逻辑。DeepSeek 走的是开源权重路线，也就是说模型权重文件可以直接下载，然后在自己服务器上跑推理，完全不需要把数据提交给第三方 API 接口。对于部署到局域网内部的场景，这是刚需：你总不想让内部会议纪要、业务文档之类的东西经过外部服务转一手吧？

DeepSeek Harness 的 Docker 化还有一个特别实在的理由：镜像分层缓存。第一次构建推理镜像确实耗时，但构建完成后，团队里其他成员或者另一台服务器直接从私有镜像仓库拉取，几秒钟就能把几百 GB 的环境准备完毕。对比一下，如果用裸机方式给十台机器逐一配置 CUDA + PyTorch + 依赖库，那是灾难级别的体验。

2.3 局域网部署的核心优势

局域网部署和公网部署最大的差别在于网络边界可控。平台只监听内网网卡端口，所有访问都发生在物理隔离或逻辑隔离的网络内部，不需要考虑公网 DDoS、端口扫描、恶意爬虫等问题。从成本角度讲，局域网内部的机器通常不受公网带宽限制，模型文件几 GB 的传输走内网交换机，速度是公网下载的几十倍。

其次，算力集中化在局域网内特别划算。一个团队通常只有一两台高端 GPU 服务器，其他人用着普通工作站。正常情况下，没有 GPU 的机器根本跑不动大模型。而 Docker 部署可以把 GPU 算力池化——有显卡的机器跑推理容器，没显卡的机器装个轻量客户端，浏览器访问 Web 服务就行。这不就是“瘦客户端 + 胖服务器”模式在 AI 时代的新翻版嘛。

3. 部署前准备：硬件要求、系统环境与镜像选择

3.1 硬件门槛到底有多高

先说结论：如果你只是跑轻量模型供小团队内部使用，一台 8GB 显存的显卡足够；如果要追求流畅对话和高并发，建议 24GB 显存起步。我实测下来，推理引擎加载模型参数所需显存大约是模型体量的 1.2 到 1.5 倍，也就是说 7B 级别模型大约要 10GB 显存，14B 级别则要 18GB 以上。这也意味着，并不是非顶级显卡不可，但显存确实是第一瓶颈。

内存方面，机器建议 32GB 起步。为什么这么高？因为推理引擎加载模型权重时，会先把权重文件读入物理内存，再转入显存。如果内存只有 16GB，加载大模型时会频繁触发 Swap，部署成功但推理速度会让人崩溃。我踩过的教训是：不要只看显存，内存不够照样卡成幻灯片。

磁盘空间建议预留 50GB 以上。模型权重文件本身可能占到 15GB 到 30GB，再加上 Docker 镜像、容器日志、Agent 工具链产生的临时文件，空间不够的话，跑到一半日志把磁盘写满，容器直接挂掉，排查起来还一头雾水。

3.2 操作系统与 Docker 环境要求

这里特别强调一下：宿主机的操作系统版本不重要，重要的是内核支持。Docker 依赖 Linux 内核特性，比如 cgroups、namespaces、OverlayFS。如果你用的是长期支持版的常见 Linux 发行版，内核版本都比较新，问题不大；但如果还在跑老古董内核版本，建议先升级系统再继续。

GPU 机器需要额外安装两个组件：显卡驱动本身，以及 NVIDIA Container Toolkit。前者我默认读者已经装好，后者是容器访问 GPU 的关键。很多新手在这步栽跟头——驱动装了、Docker 也装好了，但容器里nvidia-smi就是执行不了，原因就是 Container Toolkit 没有装。

安装 NVIDIA Container Toolkit 非常简单，以常见方式为例：

# 添加软件源（具体命令因发行版而异，这里是 Debian/Ubuntu 系） curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg # 安装 sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit # 重启 Docker 守护进程 sudo systemctl restart docker

装完之后做一个验证：运行一个临时容器，执行nvidia-smi，能看到显卡信息说明容器和 GPU 之间的通道已经打通了。这一步的值特别大——后续所有跟 GPU 相关的坑，百分之八十都能在这里提前排除。

3.3 镜像拉取策略与版本锁定

Docker 镜像的版本管理是部署中容易出问题但又最容易被忽略的环节。很多人写 Compose 文件时不加版本号，直接写latest，这对生产环境来说是定时炸弹。今天拉到的镜像可能和下周拉到的完全不是同一个版本，升级的不可控性会让你排查问题像大海捞针。

我的做法是在 Compose 里固定到具体的标签，比如v0.3.1这样的版本号。拉取时优先测试跑通默认参数，再调整环境变量。如果是在中国大陆网络环境，镜像拉取时间可能较长，我的经验是提前泡杯茶，别干等，或者配置好镜像加速器，把拉取速度提升一个量级。遇到反复拉取超时的，可以先检查 DNS 配置，再尝试更换镜像源。

另外，强烈建议：部署成功之后立刻给镜像打上本地标签，比如deepseek-harness:local-v1。这样即使原始镜像源出了问题，你也能从本地镜像缓存恢复部署，不用大海捞针重新解决依赖问题。

4. Docker Compose 编排：核心配置文件逐行解析

4.1 Compose 文件的整体结构规划

DeepSeek Harness 的 Docker 化部署，我推荐以 Docker Compose 作为编排工具，而不是手动一个个docker run。原因有两点：其一，Compose 文件是声明式配置，整个平台的容器数量、网络拓扑、卷目录、资源限制全都白纸黑字写在文件里，换机器部署时直接把文件拷过去修改少量参数即可；其二，Compose 把容器生命周期的管理统一起来了，一条命令启动、停止、查看状态，这对于后续维护非常重要。

下面是一个我打磨过多次的 Compose 文件骨架，剥茧抽丝地看各个 service 的职责：

version: "3.8" services: deepseek-api: image: deepseek-harness/inference:v0.3.1 container_name: deepseek-api ports: - "127.0.0.1:8000:8000" volumes: - /data/models:/models - model_cache:/root/.cache environment: - MODEL_NAME=deepseek-7b-chat - GPU_ID=0 deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8000/health"] interval: 30s timeout: 10s retries: 3 restart: unless-stopped networks: - harness-net harness-web: image: deepseek-harness/web:v0.3.1 container_name: harness-web ports: - "0.0.0.0:8080:80" volumes: - /data/workspace:/workspace - /data/logs:/logs environment: - API_BASE_URL=http://deepseek-api:8000 - ENABLE_TOOL_SANDBOX=true depends_on: deepseek-api: condition: service_healthy restart: unless-stopped networks: - harness-net volumes: model_cache: networks: harness-net: driver: bridge

这个文件不长，但里面有几个细节决定了平台能否稳定运行。我一个个拆开讲。

4.2 网络配置的讲究：内外有别的端口映射

在deepseek-api这个推理服务上，我用了127.0.0.1:8000:8000这种映射方式，只允许本机访问 API 端口。为什么要这么做？因为推理引擎的 API 是内部组件，正常情况下不需要暴露给局域网内其他普通用户——他们要访问的是 Web 界面。如果把 API 直接暴露到0.0.0.0:8000，等于给别人绕过认证直接调用模型能力开了一个口子，资源会被滥用。

而harness-web则用0.0.0.0:8080:80，这个端口就是实实在在给局域网内其他用户访问的。内部端口选 80 是因为 Nginx 镜像默认听他，反正容器内是隔离的，不会和宿主机冲突；宿主机上其他服务占用 8080 的情况也不少见，改这个映射端口是最方便的。我强烈建议先把 Web 端口映射到高位端口比如 8080、8090 之类的，别直接绑 80，免得和水发生的出问题无法确认是容器的问题还是端口被占用。

4.3 GPU 资源预留：Compose 的 Device 语法

deploy.resources.reservations.devices部分是 NVIDIA 设备访问的标准写法。这里的count: 1表示向容器分配一块 GPU。有多个显卡时，你可以通过device_ids或者环境变量里的 CUDA_VISIBLE_DEVICES 来精确指定用哪一张卡，这是一个细粒度控制的好办法——比如把推理服务固定在 GPU 0 上，其他训练任务跑在 GPU 1 和 2 上，互不干扰。

一个容易踩的坑：deploy层级的关键字在 Docker Compose 中通常只在 Swarm 模式下完全生效，但在本地docker compose up下，resources.reservations.devices这种 GPU 保留配置是 Docker 引擎直接支持的，没有问题。如果你发现 GPU 没有正确传给容器，先检查 Docker 版本是否太旧——我建议至少得是支持 Compose v2 的版本。

4.4 目录挂载：模型、工作区与日志分离

三种卷的设计各有讲究。第一，/data/models挂载到/models，这个不用多解释——模型权重文件体积巨大，不可能打进镜像里，也不应该在每次容器重建时重新下载。宿主机上放模型，容器按需加载，这是一个标准姿势。

第二，/data/workspace挂载到/workspace，这是 Agent 的工作目录。Agent 执行任务时产生的中间文件、结果文件、缓存数据都往这里写。把工作目录挂载出来的好处很直接：即使容器整个删掉重建，Agent 的“劳动成果”还在宿主机上，不会因为容器生命周期结束就消失。

第三，/data/logs挂载到/logs，日志是排查问题最直接的信息源。容器是易失的，日志必须落在宿主机持久化目录里。否则容器一崩，docker logs能看到一些输出，但 Agent 框架写进文件的结构化日志就全没了。

4.5 健康检查与启动依赖

depends_on在 Compose 文件里默认只控制启动顺序，不保证服务真的就绪。如果没有健康检查，Web 容器可能先启动，然后因为连不上 API 直接报错退出，虽然restart: unless-stopped会拉起它，但这个过程会产生一些令人困惑的报错日志。这里用的是带condition: service_healthy的写法，这样 Web 服务必须等到推理 API 健康检查通过之后才会启动。

健康检查命令用的是curl -f，如果/health接口返回任何非 200 状态码，curl 会以非零退出码表示失败，Docker 就会判定容器不健康。这个接口逻辑很简单，但它在整个部署中承担了“判官”的角色——API 加载模型是分钟级的耗时，如果没有健康检查，Web 容器去连一个正在冷启动的 API，连接超时会一直刷屏。

5. 实操部署全流程：从拉取镜像到跑通第一个对话

5.1 模型权重文件的放置

启动容器前，模型得先就位。以 7B 模型为例，量化后的权重文件大概 4GB 左右，放到/data/models目录下。如果你是第一次部署，需要先确认模型文件的存放路径和文件名要和 Compose 里的MODEL_NAME环境变量对应上。这一步出错，推理容器会启动失败或者报模型文件找不到，白白浪费等待时间。

我验证过一种最稳妥的安排：/data/models下建一个以模型名命名的子目录，比如/data/models/deepseek-7b-chat/，里面放config.json、model.safetensors等文件。环境变量MODEL_NAME=deepseek-7b-chat就准确指向这个子目录。这种命名规范看起来多此一举，但当你机器上同时存在三四个模型版本时，反而是救命的整理方式。

5.2 启动与日志观察的正确姿势

执行docker compose up -d启动全部服务。这里我建议你暂时压制住急切的心情，不要立刻打开浏览器，先观察一轮日志：

docker compose logs -f deepseek-api

日志里你会看到模型加载过程的输出。正常的情况下，应该能看到权重文件加载完成、模型 warmup 完成、API 监听端口就绪等标志性信息。这个过程可能耗时 30 秒到数分钟不等，取决于磁盘速度和模型大小。

有个非常实用的经验：大量使用-f跟随日志输出，等推理服务的日志中出现“Application startup complete”或类似字样后，再启动 Web 容器。虽然 Compose 里有 healthcheck 机制可以自动等待，但人眼看着日志确认一遍，总比盲目等待要踏实。

5.3 首次访问与 Agent 能力验证

等容器全部进入 running 状态后，在宿主机浏览器里访问http://127.0.0.1:8080。看到 Web 界面后，先不要急着提复杂需求，我建议按下面这个顺序验证平台可用性：

• 第一步，在界面上发一条简单的消息，比如“你好”，确认对话链路通畅。
• 第二步，让 Agent 执行一个轻量级工具任务，比如“列出当前工作目录下的文件”。这能验证工具链是否正常注册。
• 第三步，验证知识库检索能力，如果配置了文档索引，可以问一个和文档内容相关的问题，看看 Agent 能否准确引用。

这三步走完，基本可以确定平台的推理引擎、Agent 调度、工具链三层都是通的。我见过不少部署完了界面能开、但 Agent 一执行工具就静默失败的情况，多半是工具沙箱权限配置不对，或者工作目录挂载有问题。

5.4 配置持久化的隐藏价值

部署完成后，我强烈建议你把当前这套 Compose 文件和对应镜像的标签记录存档。用一段时间后发现效果满意，就把整套方案写成一个部署说明文档。这样做的好处是，当需要扩容时——比如第二台机器也要跑同样的平台——你只要把存档的 Compose 文件和模型文件复制过去，一条命令就能拉起一套一模一样的环境，而不是从头摸索一遍。

这里也涉及版本回滚的便利。如果某次更新镜像后平台行为异常，只要 Compose 文件里还记录着上一个可用版本号，回滚就是改一行配置再加docker compose up -d的事。对比裸机方式的环境重搭，这种回滚速度快到几乎没有感知。

6. 局域网访问配置：让其他设备连上你的 Agent

6.1 防火墙与端口放行

宿主机上的 Web 端口默认绑定到了0.0.0.0:8080，理论上局域网内的其他设备已经可以通过http://宿主机IP:8080访问了。但实际中你会发现打不开——大概率是宿主机防火墙把端口挡了。

Linux 上我用得最多的防火墙管理工具是ufw或者firewalld，看发行版而定。放行端口示例：

sudo ufw allow 8080/tcp sudo ufw reload

验证端口已在监听：

ss -tlnp | grep 8080

如果看到0.0.0.0:8080的监听记录，说明 Docker 的端口映射已经生效；如果你看到的是类似127.0.0.1:8080，那说明 Compose 文件里的映射写错了，回到 4.2 节的配置改掉。

6.2 局域网 IP 速查与设备连通性测试

在宿主机上执行ip addr或hostname -I找到内网 IP，然后在另一台设备上先ping一下这个 IP，确认网络层可达。接着在浏览器打开http://IP:8080。如果页面迟迟不加载，我建议按这个顺序排查：

1. 浏览器所在的设备和宿主机是否在同一网段？跨 VLAN 的情况下需要网关路由放行。
2. 宿主机防火墙是否拦截了 8080 端口？这个最常见，检查办法上面已经说了。
3. Web 容器日志有没有报错信息？比如是否因为连接不到 API 容器而在启动后反复重启。

还有一个细节值得提：手机的移动网络是不在局域网内的，用手机访问时请务必连接到同一个 Wi-Fi，否则走的还是公网，访问自然不通。

6.3 是否要套一层反向代理

当前架构里harness-web直接用 80 端口对外服务，其实在小型局域网里已经够用了。如果将来用户数量多了，或者你想把 Agent 平台和其他 Web 服务放在同一台机器上，我建议在容器前面加一层反向代理，比如 Nginx 或 Caddy，做域名转发和 TLS 终结。这样做的好处是：

• 统一入口：所有 Web 服务都通过一个反向代理转发，不用记忆各种端口号。
• 集中管理证书：如果以后想从外网访问，TLS 配置只需在代理层做一次。
• 访问控制：可以在代理层加一层简单的 IP 白名单或者基本认证，比在应用层做要省事得多。

在纯局域网场景下，我一般把基本认证写在反向代理里。做法并不复杂：在 Nginx 配置里开启 auth_basic，生成一个密码文件，用户在浏览器访问时先弹窗输入用户名密码，认证通过才看到 Web 界面。这样就算局域网内部有人扫端口扫到了你这个服务，没有账号也进不去。

7. 常见问题与排查技巧实录

7.1 容器一直处于重启状态

这个问题的现场往往是：docker ps看到 Web 容器 STATUS 显示Restarting，Restart 计数不断跳动。先把日志拉出来看看，docker logs harness-web如果看到类似连接拒绝、超时之类的关键字，那基本都是 API 容器还没就绪或者 API 地址写错了。

如果你用的是 Compose 里的 service 名做网络通信，比如http://deepseek-api:8000，要确认两个容器确实加入到了同一个自定义网络harness-net。我遇到过一种情况：之前用docker-compose旧版本创建过默认网络，后来改成自定义网络名，Web 容器配置没更新，导致俩容器在鸡同鸭讲。

另一种常见情况是 API 容器根本没成功启动。登录宿主机手动试一下docker start deepseek-api并查看日志，重点看模型加载那一段是否报错。很多模型推理框架在加载失败时不会立刻崩溃，而是挂在初始化阶段，从外部看好像一直在启动中，其实卡死了。这时候logs加--tail 100能快速定位问题。

7.2 容器启动了但 GPU 不可见

进入推理容器执行验证：

docker exec deepseek-api nvidia-smi

如果报错找不到命令或无法访问显卡，先确认宿主机本身nvidia-smi是否正常，再确认 NVIDIA Container Toolkit 是否安装完成。宿主机正常但容器不正常的场景下，十有八九是 toolkit 没装或者是 Docker 守护进程没有重启。

# 重启 Docker 让 toolkit 配置生效 sudo systemctl restart docker

重启完再测试一下容器内nvidia-smi，通常问题解决。另外提醒一点：有些虚拟化平台的“GPU 直通”模式需要额外的宿主机配置，容器里看到的显卡信息可能不完整，这种情况建议在宿主机上跑一个简单的 PyTorch 测试脚本验证计算能力，排除框架层面的问题。

7.3 推理速度慢得离谱

显存占用也不高，但回复一句话要等一两分钟。这类问题大多是加载位置不对或者精度设置太保守。排查路径从系统监控开始：nvidia-smi看显存占用和 GPU 利用率，free -h看物理内存是否被打满。

如果显存使用率低但内存居高不下，说明模型权重根本没扛进显存，推理引擎正在用 CPU 硬算。检查一下模型加载时有没有启用半精度或量化，配置不对时整个平台会退化成纯 CPU 推理，体验当然差到难以忍受。另一个容易被忽视的点是：Swap 空间使用率太高时，即使显存够了，内存换页也会拖慢推理速度。检查你的swappiness参数，在 16GB 内存的机器上跑大模型，建议调低 swap 倾向。

7.4 局域网其他设备访问不了

这种问题我排查过太多次了，原因排序大概是：防火墙拦住了端口 > 端口映射只绑了回环地址 > 设备不在同一网段 > Web 容器崩了。

我最快的定位路线是：先在宿主机上curl http://127.0.0.1:8080看是否通，再在另一台设备上telnet 宿主机IP 8080看端口是否可达。宿主机通、其他设备不通的，十有八九是防火墙。两端都不通的，看看容器是不是又重启了。

另外，Windows 宿主机的话别忘了检查专用网络配置——有些公共网络配置默认开启防火墙阻止一切入站连接，需要给 Docker 放行。简单粗暴的办法是把网络的配置文件改成专用网络，让防火墙放行规则生效。

7.5 Agent 工具执行失败但没报错

这个比较隐蔽。界面里 Agent 答应执行任务，但结果返回空或者显示执行超时，日志里也没有 Python 异常堆栈。这个问题绝大多数和工具沙箱的工作目录权限相关：容器内运行工具服务的用户，对挂载进来的/workspace目录没有写权限。

解决方式分两步：先检查宿主机目录属主，ls -ld /data/workspace，确保 UID 和容器内 uid 匹配或至少有权写入；再检查容器里默认用户身份，如果是 root 跑服务，那基本不会有权限问题，如果是以非 root 用户运行，则必须保证挂载目录的属主一致。

注意：不要在非 root 容器里偷懒用chmod -R 777解决问题。这是能跑但埋雷的做法，后续如果有其他服务也挂载同一个目录，权限风险会放大。正确做法是chown到容器实际用户 UID。

7.6 常用排查指令速查

这个表格我建议保存下来，贴在部署记录的文档开头。每次环境异常时按这个顺序过一遍，绝大多数问题都能在五分钟内定位到具体原因，比打开某度搜“Docker AI Agent 部署失败”要有用得多。

8. 一点个人实践心得

我自己跑这个方案的时候，前后给机房里的另外三台机器也部署了同样的环境。最深的感受是：Docker 化部署的价值不在于“一次成功”，而在于反复失败后的低成本重建。裸机部署时，环境坏了你可能要花半天重装；有了 Compose 和命名卷，删掉容器重建一套也就一两分钟的事情，模型文件和数据都还在宿主机上。这种“折腾不坏”的安全感，才是容器化最大的收益。

另外，我建议你在部署完成后，把docker compose config的输出完整存一份，它会把所有环境变量、挂载点、默认值的最终解析结果明确展开一遍。这东西在你三个月后回来看，比任何文档都好用——它就是当时实际生效配置的唯一真相。

整个方案跑起来之后，局域网里每个人打开浏览器就能使用 AI Agent 平台，这在没有 Docker 的裸机时代是难以想象的。如果你也有闲置的 GPU 机器，不妨按着这个思路试试，前半小时可能都在拉镜像和等模型加载，但等第一次对话回复出现在浏览器里的那一刻，你会觉得一切都是值得的。