企业官网建设流程全解析

1. 为什么局域网里需要一个“能自己干活”的AI Agent平台

最近两周，我帮某高校实验室部署了三套本地AI服务系统，其中两套用的是传统API调用模式——前端发请求，后端模型推理，返回结果。第三套，我换成了DeepSeek Harness的Docker化Agent架构。结果很直观：前两套在处理“连续多步任务”时频繁卡顿、超时、状态丢失；而第三套跑通了一个典型场景：自动读取实验室设备日志PDF → 提取温度/压力异常段落 → 对比历史阈值 → 生成带截图标注的预警邮件 → 同步存入内部知识库。整个流程无人干预，耗时47秒，失败率为0。

这不是模型更强，而是架构变了。DeepSeek Harness不是单纯把大模型当“问答机”用，它把模型变成一个可调度、可编排、有记忆、能调用工具的执行体。而Docker，恰恰是让这个执行体在局域网里“稳住身形”的关键——它不依赖宿主机Python环境、不和同事的Jupyter Notebook抢CUDA显存、不因pip install某个包就崩掉整个推理服务。你不需要懂Kubernetes，但必须理解：Agent不是跑一次就完的事，它是持续在线、响应触发、调用真实接口、产生真实动作的服务进程。Docker镜像就是它的“数字工装”，封装了运行时、依赖、配置、甚至预加载的向量库和工具插件。

很多人卡在第一步：以为部署Harness就是git clone + pip install。实测发现，光是llama-cpp-python的CUDA编译，在不同NVIDIA驱动版本下就有7种报错路径；transformers和vllm共存时的tokenizer冲突，能让你调试一整天；更别说playwright在无GUI容器里启动浏览器的权限问题。这些不是“环境问题”，而是Agent平台对运行确定性的刚性要求——它必须知道自己的工具在哪、参数怎么传、失败后如何重试、状态存在哪。Docker通过分层镜像+明确ENTRYPOINT+健康检查探针，把这种确定性从“靠人肉记忆”变成了“靠配置固化”。

所以，这篇不是教你怎么“跑通一个Demo”，而是带你建一条局域网AI Agent产线：输入是自然语言指令，输出是数据库写入、邮件发送、文件生成等真实动作。它不连公网，不传数据，所有模型权重、知识库、工具脚本全在内网服务器上。你同事用浏览器打开http://192.168.1.100:8000就能提交任务，IT管理员用docker ps就能看到所有Agent实例的实时状态。这才是“轻松搭建”的真实含义：轻松在运维层面管理，轻松在业务层面调用，轻松在安全层面审计。

2. DeepSeek Harness的核心机制：它到底在“代理”什么

要真正用好Harness，得先拆开它的执行引擎。它不是简单的“Prompt + LLM API”封装，而是一个三层协同结构：规划层（Planner）→ 工具调用层（Tool Executor）→ 状态管理层（State Manager）。这三层全部运行在单个Docker容器内，彼此通过内存队列通信，不依赖外部消息中间件。

2.1 规划层：把模糊指令拆成可执行步骤

当你输入“帮我查一下上周三服务器A的CPU使用率峰值，并对比阈值发邮件”，Harness不会直接扔给模型去“想”。它先用轻量级规划模型（默认是deepseek-r1-distill-qwen-1.5b）做任务分解：

1. 步骤1：调用server_monitor_api工具，查询服务器A、时间范围为“2024-04-10 00:00:00至2024-04-10 23:59:59”的CPU指标
2. 步骤2：调用threshold_checker工具，将返回的峰值数值与预设阈值（如85%）比较
3. 步骤3：若超阈值，调用email_sender工具，生成含图表的HTML邮件并发送

这个过程的关键在于：每一步都对应一个明确定义的工具函数签名。Harness的tools/目录下，每个Python文件就是一个工具模块，例如server_monitor_api.py必须包含：

from typing import Dict, Any def execute(params: Dict[str, Any]) -> Dict[str, Any]: """查询服务器监控指标 params: { "server_id": "A", "start_time": "2024-04-10T00:00:00Z", "end_time": "2024-04-10T23:59:59Z", "metric": "cpu_usage_percent" } returns: {"peak_value": 92.3, "timestamp": "2024-04-10T14:22:18Z"} """ # 实际调用Prometheus API或Zabbix接口的代码 pass

提示：工具函数的params字典必须严格匹配OpenAPI Schema定义，Harness会用Pydantic做运行时校验。如果传入"server_id": 123（整数而非字符串），规划层会直接报错中止，而不是让下游工具崩溃。这是Agent鲁棒性的第一道防线。

2.2 工具调用层：让大模型“动手”而不是“动嘴”

很多团队失败的原因，是把工具调用写成os.system("curl ...")。Harness强制要求所有工具必须是纯Python函数，且满足三个条件：

• 无副作用：函数内不能修改全局变量、不能写临时文件到/tmp（除非指定/app/tmp挂载卷）
• 可序列化：返回值只能是dict/list/str/int/float/bool/None，不能返回requests.Response对象
• 有超时控制：每个工具调用默认15秒超时，超时后自动重试2次，重试间隔指数退避

实测发现，playwright自动化浏览器操作最容易超时。解决方案不是加长超时时间，而是重构工具：

• 在Dockerfile中预装chromium并设置--no-sandbox --disable-dev-shm-usage
• 工具函数内用sync_playwright().start()创建独立上下文，用完立即context.close()
• 关键操作（如截图）加page.wait_for_timeout(2000)而非time.sleep()，避免阻塞事件循环

这样，即使网页加载慢，工具也能在15秒内优雅退出，规划层会收到{"error": "TimeoutError", "tool": "web_scraper"}，从而触发备用方案（如降级为调用静态API）。

2.3 状态管理层：让Agent记住“刚才干了什么”

传统LLM服务是无状态的，每次请求都是全新对话。而Agent必须记住：

• 当前任务ID（用于日志追踪和失败恢复）
• 已执行步骤列表（防止循环调用同一工具）
• 工具返回的中间数据（如步骤1查到的CPU峰值92.3，步骤2要用它做比较）
• 用户原始指令的语义锚点（避免后续步骤偏离目标）

Harness用Redis作为状态存储后端（Docker Compose中默认启用），但关键设计在于：状态只存必要字段，且全部经过哈希脱敏。例如，用户指令“查张三的工资单”不会存原文，而是存{"task_id": "t-8a3f", "intent_hash": "sha256:ab12...", "step_history": ["server_monitor_api", "threshold_checker"]}。这样既保证了多实例间状态同步，又规避了敏感信息落盘风险。

注意：如果你的局域网不允许Redis，Harness支持InMemoryStateBackend，但仅限单实例部署。多节点时必须用Redis，否则Agent在节点A规划的步骤，节点B无法执行。

3. Docker镜像构建：从零开始定制你的Agent工装

官方提供的Docker镜像（deepseek-ai/harness:latest）是个很好的起点，但直接使用会踩三个深坑：CUDA版本不匹配、工具依赖缺失、模型加载路径错误。我推荐采用“分阶段构建+多阶段缓存”策略，全程可控。

3.1 基础镜像选择：为什么不用Ubuntu 22.04而选20.04

NVIDIA官方CUDA Toolkit 12.1的长期支持（LTS）版本，其二进制兼容性最佳的Linux发行版是Ubuntu 20.04。虽然22.04更新，但nvidia-container-toolkit在22.04上的GPU设备映射偶发失效（表现为nvidia-smi能查到GPU，但容器内torch.cuda.is_available()返回False）。我们实测对比了5种基础镜像：

最终选定nvidia/cuda:12.1.1-devel-ubuntu20.04，并在Dockerfile开头显式声明：

# syntax=docker/dockerfile:1 FROM nvidia/cuda:12.1.1-devel-ubuntu20.04 # 设置CUDA环境变量，避免torch编译时找不到nvcc ENV CUDA_HOME=/usr/local/cuda ENV PATH=$PATH:$CUDA_HOME/bin ENV LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$CUDA_HOME/lib64

3.2 依赖安装：用requirements.txt分层隔离风险

Harness的依赖树极深，transformers、vllm、llama-cpp-python三者对pydantic、numpy、protobuf的版本要求互相冲突。硬性指定版本号会导致pip install失败。我们的解法是：用pip-tools生成锁定文件，分三阶段安装。

首先，创建requirements.in，只写核心依赖：

# requirements.in deepseek-harness==0.4.2 vllm==0.4.2 llama-cpp-python[server]==0.2.72 playwright==1.42.0 redis==4.6.0

然后用pip-compile生成精确版本的requirements.txt：

pip install pip-tools pip-compile requirements.in --output-file requirements.txt

Dockerfile中分阶段安装：

# 阶段1：安装系统级依赖（apt） RUN apt-get update && apt-get install -y \ build-essential \ libsm6 libxext6 libxrender-dev libglib2.0-0 \ chromium-browser \ && rm -rf /var/lib/apt/lists/* # 阶段2：安装Python依赖（pip） COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # 阶段3：安装Playwright浏览器（必须在apt之后） RUN playwright install chromium --with-deps

关键经验：playwright install必须放在pip install之后，且必须用--with-deps。否则容器内chromium缺少libnss3等系统库，启动时静默失败。我们曾因此浪费12小时排查，最终在strace -f playwright install日志里发现openat(AT_FDCWD, "/usr/lib/x86_64-linux-gnu/libnss3.so", O_RDONLY|O_CLOEXEC) = -1 ENOENT。

3.3 模型与工具配置：用Docker Volume实现热更新

Harness默认从/app/models/加载模型，从/app/tools/加载工具。但硬编码路径会导致每次改工具都要重打镜像。我们用Docker Volume解耦：

# docker-compose.yml 片段 services: harness: image: my-harness:1.0 volumes: - ./models:/app/models:ro # 只读挂载，防误删 - ./tools:/app/tools:rw # 可写挂载，支持热更新 - ./config:/app/config:ro environment: - HARNES_MODEL_PATH=/app/models/deepseek-r1-distill-qwen-1.5b - HARNES_TOOL_DIR=/app/tools

这样，当你新增一个tools/email_sender.py，只需touch ./tools/__init__.py触发Harness自动重载，无需重启容器。实测热更新平均耗时1.3秒，比容器重启快27倍。

4. 局域网部署实战：从单机验证到多节点协同

部署不是终点，而是日常运维的起点。我们按“单机验证→安全加固→多节点扩展”三步走，每步都有可落地的检查清单。

4.1 单机验证：用5分钟确认Agent心跳正常

不要一上来就跑复杂任务。先验证最底层的“Agent心跳”：

1. 启动容器：docker run -p 8000:8000 -v $(pwd)/models:/app/models:ro -v $(pwd)/tools:/app/tools:rw my-harness:1.0
2. 访问http://localhost:8000/docs，Swagger UI应正常加载
3. 调用/health端点：返回{"status": "healthy", "model_loaded": true, "tools_count": 7}
4. 调用/plan端点，输入简单指令：{"query": "你好"}，应返回{"steps": [{"tool": "echo", "params": {"text": "你好"}}]}

这四步通过，说明Harness核心引擎、模型加载、工具注册全部就绪。如果第3步失败，90%是模型路径错误；如果第4步返回空steps，则是规划模型未正确加载（检查HARNES_MODEL_PATH环境变量是否指向含config.json和pytorch_model.bin的目录）。

4.2 安全加固：局域网不等于零防护

局域网常被误认为“天然安全”，但Harness暴露的HTTP端口可能被内网扫描器捕获。我们实施三层加固：

• 网络层：用Docker自定义网络隔离

  docker network create --driver bridge --subnet=172.20.0.0/16 harness-net docker run --network=harness-net -p 8000:8000 my-harness:1.0

  这样，只有同属harness-net的容器（如Redis、PostgreSQL）能访问Harness，宿主机其他服务无法直连。

• 应用层：启用JWT令牌认证
  在config/settings.yaml中开启：

  auth: enabled: true jwt_secret: "your-32-byte-secret-here" # 必须32字节 jwt_expires_in: "24h"

  所有API调用需在Header中携带Authorization: Bearer <token>。Token由/auth/login颁发，用户名密码存于config/users.yaml（加密存储）。

• 数据层：工具返回值自动脱敏
  Harness内置DataSanitizer中间件，对工具返回的dict自动扫描关键词：

  # config/sanitizer_rules.py RULES = [ {"field": "content", "pattern": r"\b\d{17,19}\b", "replace": "[REDACTED_BANKCARD]"}, {"field": "body", "pattern": r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}", "replace": "[REDACTED_EMAIL]"} ]

  这样，即使email_sender工具返回含邮箱的原始HTML，日志和API响应中也会被替换。

4.3 多节点扩展：用Redis实现跨容器状态同步

单容器适合验证，生产必须多实例。Harness本身无状态，但状态管理依赖Redis。扩展步骤：

1. 启动Redis集群（非必须，单Redis实例即可）：

   docker run -d --name redis -p 6379:6379 -v $(pwd)/redis-data:/data redis:7-alpine

2. 修改docker-compose.yml，添加redis_url环境变量：

   environment: - REDIS_URL=redis://redis:6379/0 - HARNES_STATE_BACKEND=redis

3. 启动多个Harness实例：

   docker-compose up -d --scale harness=3

此时，三个容器共享同一Redis DB，任务ID、步骤历史、中间数据全部同步。我们压测发现：当并发任务达200QPS时，Redis CPU占用率仅12%，瓶颈在模型推理GPU。此时可横向扩展GPU节点，Harness自动负载均衡。

实操心得：不要用docker-compose scale动态扩缩容。实测发现，新实例加入时，Redis中的task_lock键未及时清理，导致部分任务被重复执行。正确做法是：预设好实例数，用nginx做反向代理+IP Hash负载均衡，确保同一用户请求始终路由到同一实例，降低Redis锁竞争。

5. 故障排查手册：那些文档里不会写的“血泪教训”

再完美的部署也会出问题。我把三年来处理的Harness故障归为五类，每类给出可复现的诊断命令和修复方案。

5.1 GPU显存爆满：CUDA out of memory的真凶不是模型

现象：容器日志出现RuntimeError: CUDA out of memory. Tried to allocate 2.00 GiB (GPU 0; 24.00 GiB total capacity)，但nvidia-smi显示显存占用仅60%。

根因：vllm的PagedAttention机制会预分配显存块，而llama-cpp-python的GGUF加载器也占用显存，两者叠加超过GPU总容量。不是模型太大，而是两个推理引擎在抢显存。

诊断：进入容器，运行：

# 查看vLLM实际显存分配 python -c "from vllm import LLM; print(LLM('dummy').kv_cache_blocks)" # 查看llama-cpp-python显存占用 python -c "from llama_cpp import Llama; l = Llama(model_path='dummy'); print(l.n_ctx())"

修复：在config/settings.yaml中强制分离GPU资源：

vllm: tensor_parallel_size: 1 gpu_memory_utilization: 0.5 # vLLM只用50%显存 llama_cpp: n_gpu_layers: 33 # GGUF模型总层数，设为实际值 main_gpu: 0 # 指定主GPU索引

5.2 工具调用超时：playwright在容器里“假装加载完成”

现象：web_scraper工具返回{"error": "TimeoutError"}，但手动在容器内执行playwright open https://example.com却秒开。

根因：容器内DNS解析慢。playwright默认用系统DNS，而Docker的/etc/resolv.conf指向127.0.0.11（Docker内置DNS），该DNS在高并发时响应延迟达2秒。

诊断：在容器内执行：

time nslookup google.com # 若耗时>1s，则确认DNS问题

修复：在Dockerfile中覆盖DNS：

# 在Dockerfile末尾添加 RUN echo "nameserver 8.8.8.8" > /etc/resolv.conf && \ echo "nameserver 114.114.114.114" >> /etc/resolv.conf

5.3 状态丢失：Redis连接闪断导致任务“人间蒸发”

现象：用户提交任务后，/status/{task_id}返回{"status": "not_found"}，但Redis中task:t-xxx键存在。

根因：Harness的状态获取逻辑是“先查Redis，再查本地缓存”，但Redis连接闪断时，本地缓存未及时失效，导致返回过期状态。

诊断：监控Redis连接数：

redis-cli info clients | grep "connected_clients" # 若数值剧烈波动（如10→0→10），则存在连接闪断

修复：在config/settings.yaml中启用连接池保活：

redis: connection_pool: max_connections: 20 retry_on_timeout: true health_check_interval: 30 # 每30秒发PING检测

5.4 模型加载失败：OSError: Unable to load weights的隐藏路径

现象：容器启动时报错OSError: Unable to load weights from pytorch checkpoint for...，但模型文件明明存在。

根因：模型文件权限问题。Docker默认以root用户运行，但llama-cpp-python加载GGUF时，要求模型文件所有者为root且权限为644。若模型由Mac或Windows拷贝而来，可能带@扩展属性或权限错误。

诊断：进入容器，检查：

ls -la /app/models/deepseek-r1-distill-qwen-1.5b/ # 若显示 `-rwxr-xr-x@` 或 `?`，则权限异常

修复：在宿主机上修复权限：

chmod 644 ./models/deepseek-r1-distill-qwen-1.5b/*.bin xattr -c ./models/deepseek-r1-distill-qwen-1.5b/*.bin # 清除Mac扩展属性

5.5 日志混乱：多实例下stdout日志无法区分来源

现象：docker logs harness-1和docker logs harness-2输出混在一起，无法定位哪个实例处理了哪个任务。

根因：Harness默认日志不打实例标签。Docker的json-file驱动按行分割日志，但同一毫秒内多个实例写日志，顺序错乱。

修复：在Dockerfile中重定向日志到带标签的文件：

# 添加日志标签 ENV LOG_TAG="harness-$(hostname | cut -d'-' -f2)" CMD ["sh", "-c", "exec harness-server --host 0.0.0.0:8000 --log-file /app/logs/${LOG_TAG}.log"]

然后用docker logs -f harness-1 | grep "t-abc123"精准过滤。

6. 生产就绪 checklist：上线前必须核对的12项

部署完成不等于生产就绪。我们总结了一份上线前必检清单，每项都关联具体命令和预期输出：

最后提醒：第12项“备份策略”常被忽略。Harness的/app/config目录必须每日备份，因为users.yaml（用户账号）、sanitizer_rules.py（脱敏规则）、tools/（自定义工具）全部在此。我们用cron定时执行：

0 2 * * * cd /app && tar -czf /backup/harness-config-$(date +\%Y\%m\%d).tar.gz config/

这样，哪怕整个Docker环境崩溃，30秒内就能从备份恢复全部业务逻辑。