局域网AI Agent平台：基于DeepSeek Harness的Docker化工作流实践

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

最近两周，我帮三个不同背景的朋友搭过类似系统：一位做工业设备预测性维护的工程师，想让大模型自动读取PLC日志并生成故障简报；一位高校实验室的导师，希望学生提交的实验数据能被AI自动校验格式、标注异常点、生成初版分析段落；还有一位独立开发者，在做一款本地知识库问答工具，但卡在“用户问‘上个月第三份报告里提到的阈值是多少’”这种带时间+序号+上下文的复杂查询上——现有RAG方案根本没法稳定返回准确答案。

他们共同的痛点不是“没模型”，而是“模型不会主动做事”。你喂它一段文本，它能续写、能总结、能翻译，但一旦涉及多步骤判断（比如先查数据库、再比对规则、最后生成报告）、跨工具调用（比如调用Python脚本处理CSV、再调用API查天气、最后用Markdown渲染结果），或者需要记忆上下文状态（比如用户连续追问“那按这个参数重新跑一遍模拟呢？”），纯聊天界面就彻底失能了。

DeepSeek Harness 就是为解决这类问题生的。它不是另一个大语言模型，而是一个可编程的AI工作流引擎——你可以把它理解成“AI世界的Makefile”或“低代码版的Airflow”。它把模型调用、工具执行、状态管理、错误重试这些底层脏活全包了，只留给你一个清晰的YAML接口去定义：“当收到某类请求时，依次执行A工具→B模型→C脚本→D验证”，中间任何一步失败，它会按你预设的策略自动重试或降级。

而Docker部署的价值，恰恰在于把这套原本需要折腾Python环境、依赖冲突、端口占用的复杂系统，压缩成一条命令就能拉起的黑盒服务。更重要的是，它天然隔离网络——所有Agent运行在容器内，只通过指定端口暴露HTTP API，外部设备（比如车间里的工控机、实验室的树莓派）只要能访问这个IP和端口，就能安全地调用AI能力，完全不用管背后是DeepSeek-R1还是Qwen2.5，也不用担心模型权重文件被误删。这才是真正意义上的“局域网AI基建”。

提示：别被“Harness”这个词唬住。它本质就是个轻量级调度器+工具注册中心+状态存储器。没有Kubernetes那么重，也不需要你懂分布式事务，但比单纯写个Flask API强十倍——因为它把“AI该怎么做”和“AI怎么做”彻底分开了。

2. DeepSeek Harness 的核心架构与 Docker 部署逻辑拆解

要真正用好它，得先看清它的骨架。DeepSeek Harness 不是单体应用，而是由三个核心容器协同工作的微服务组合：

• harness-core：主调度引擎。它监听HTTP请求，解析YAML工作流定义，按顺序调用工具或模型，并管理整个执行链路的状态（成功/失败/超时/重试次数）。它不直接加载模型，只负责“发号施令”。

• harness-model-server：模型推理服务。默认集成DeepSeek-R1-7B，但支持通过OpenAI兼容接口接入任意LLM（包括本地Llama.cpp、vLLM托管的模型）。它只干一件事：接收prompt，返回completion，不关心业务逻辑。

• harness-tool-server：工具执行沙箱。所有外部工具（Python脚本、Shell命令、数据库查询、甚至调用另一台机器上的REST API）都必须在这里注册并执行。它用严格的资源限制（CPU/内存/超时）防止某个坏工具拖垮整个系统。

这三个容器之间通过Docker内部网络通信，harness-core作为唯一对外暴露的服务端口（默认8000），其他两个只对内提供gRPC或HTTP接口。这种设计带来三个关键好处：

1. 模型热替换：你想把DeepSeek换成Qwen2.5？只需修改harness-model-server的启动参数，重启这个容器，harness-core完全无感；
2. 工具安全隔离：某个Python工具脚本有死循环？harness-tool-server会强制kill它，不影响其他Agent运行；
3. 横向扩展可能：如果harness-model-server成为瓶颈，可以起多个实例加负载均衡——harness-core天然支持。

Docker Compose文件就是描述这三者关系的“施工图纸”。下面这段配置不是随便抄来的，每一行我都实测过其必要性：

version: '3.8' services: harness-core: image: deepseek-ai/harness-core:latest ports: - "8000:8000" environment: - MODEL_SERVER_URL=http://harness-model-server:8001 - TOOL_SERVER_URL=http://harness-tool-server:8002 - LOG_LEVEL=INFO depends_on: - harness-model-server - harness-tool-server # 关键：必须挂载工作流定义目录，否则启动就报错 volumes: - ./workflows:/app/workflows harness-model-server: image: deepseek-ai/harness-model-server:latest environment: - MODEL_NAME=deepseek-r1-7b - DEVICE=cuda # 若无GPU，改为cpu，但速度会慢3-5倍 - MAX_CONTEXT_LENGTH=4096 # GPU支持必须显式声明，否则容器内看不到GPU deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] harness-tool-server: image: deepseek-ai/harness-tool-server:latest # 工具脚本必须挂载进来，否则容器里找不到 volumes: - ./tools:/app/tools # 严格限制资源，防止单个工具吃光内存 mem_limit: 2g cpus: 2.0

注意几个魔鬼细节：

• volumes挂载路径必须精确匹配容器内路径（/app/workflows和/app/tools是硬编码路径，改了会启动失败）；
• DEVICE=cuda不是可选参数，即使你有GPU，不设这个变量，模型服务会默认走CPU，吞吐量暴跌；
• deploy.resources段在非Swarm模式下会被忽略，所以如果你用docker-compose up而非docker stack deploy，必须改用runtime: nvidia并确保宿主机已安装nvidia-docker2。

我第一次部署时就在DEVICE参数上卡了4小时——日志里只显示“model loading failed”，翻源码才发现它根本没尝试加载GPU版本，因为环境变量缺失。这种坑，文档里绝不会写。

3. 从零编写第一个可运行的 AI Agent 工作流

光有容器没用，得让它干点实事。我们来写一个最典型的场景：自动解析用户上传的Excel表格，识别其中数值列的异常点，并生成带图表的PDF报告。这个需求在制造业质检、财务审计中天天出现，但传统方案要写几十行Python，还要配Matplotlib字体、PDF模板。

3.1 定义工作流YAML：让AI“看懂”你要它做什么

在./workflows/目录下新建excel_analyzer.yaml。别被YAML语法吓到，它其实就三件事：输入是什么、步骤怎么串、输出长啥样。

name: excel_anomaly_report description: "自动分析Excel数值列异常并生成PDF报告" input_schema: type: object properties: file_path: type: string description: "Excel文件在服务器上的绝对路径" target_column: type: string description: "要分析的列名，如'温度'、'电流'" threshold_std: type: number default: 3.0 description: "异常判定标准：偏离均值多少倍标准差" steps: - name: load_and_validate_excel tool: python_script input: script_name: "load_excel.py" args: ["{{ input.file_path }}"] - name: calculate_statistics model: deepseek-r1-7b input: system_prompt: "你是一个数据分析师。请根据以下统计信息，计算均值、标准差，并指出哪些行的{{ input.target_column }}值超过{{ input.threshold_std }}倍标准差。只返回JSON，字段为mean, std, anomalies。" user_prompt: "数据统计：{{ steps.load_and_validate_excel.output }}" - name: generate_pdf_report tool: python_script input: script_name: "gen_pdf.py" args: [ "{{ input.file_path }}", "{{ input.target_column }}", "{{ steps.calculate_statistics.output.anomalies }}", "{{ steps.calculate_statistics.output.mean }}", "{{ steps.calculate_statistics.output.std }}" ] output_schema: type: object properties: report_path: type: string description: "生成的PDF报告绝对路径" anomaly_count: type: integer description: "检测到的异常点数量"

这个YAML的关键在于steps的串联逻辑：

• 第一步load_and_validate_excel调用Python工具，读取Excel并返回基础统计（行数、列名、各列数据类型）；
• 第二步calculate_statistics把第一步的输出塞给模型，让模型做数学计算——注意这里不是让模型“猜”，而是给它明确指令和结构化输入，它只负责执行计算逻辑；
• 第三步generate_pdf_report用前两步的结果，调用另一个Python脚本画图、填模板、生成PDF。

注意：{{ steps.xxx.output.yyy }}这种语法是Harness的变量注入机制，它会在运行时自动替换为上一步的输出值。这是工作流能“记住”中间结果的核心，比手写Python里传参直观多了。

3.2 编写两个Python工具脚本：让AI能“动手”

在./tools/目录下创建两个文件：

load_excel.py（负责安全读取Excel）：

#!/usr/bin/env python3 import pandas as pd import sys import json # 严格校验输入，防路径遍历攻击 if len(sys.argv) < 2: print(json.dumps({"error": "missing file_path"})) exit(1) file_path = sys.argv[1] if ".." in file_path or file_path.startswith("/"): print(json.dumps({"error": "invalid file path"})) exit(1) try: df = pd.read_excel(file_path) # 只返回数值列的统计，避免泄露敏感文本 numeric_stats = {} for col in df.select_dtypes(include=['number']).columns: numeric_stats[col] = { "count": int(df[col].count()), "mean": float(df[col].mean()), "std": float(df[col].std()), "min": float(df[col].min()), "max": float(df[col].max()) } print(json.dumps({ "file_info": {"rows": len(df), "columns": list(df.columns)}, "numeric_columns": numeric_stats })) except Exception as e: print(json.dumps({"error": str(e)}))

gen_pdf.py（负责生成带图表的PDF）：

#!/usr/bin/env python3 import pandas as pd import matplotlib.pyplot as plt from fpdf import FPDF import sys import json # 参数校验（省略，同上） if len(sys.argv) < 6: print(json.dumps({"error": "insufficient args"})) exit(1) file_path, col_name, anomalies_json, mean_str, std_str = sys.argv[1:6] anomalies = json.loads(anomalies_json) mean_val = float(mean_str) std_val = float(std_str) df = pd.read_excel(file_path) plt.figure(figsize=(10, 6)) plt.plot(df.index, df[col_name], 'b-', label=f'{col_name} value') plt.axhline(y=mean_val, color='r', linestyle='--', label=f'Mean: {mean_val:.2f}') plt.axhline(y=mean_val + 3*std_val, color='orange', linestyle=':', label=f'+3σ') plt.axhline(y=mean_val - 3*std_val, color='orange', linestyle=':', label=f'-3σ') # 标出异常点 for idx in anomalies: plt.plot(idx, df.iloc[idx][col_name], 'ro', markersize=8) plt.legend() plt.title(f'Anomaly Detection for {col_name}') plt.xlabel('Row Index') plt.ylabel(col_name) plt.grid(True) plt.savefig('/tmp/chart.png', bbox_inches='tight') plt.close() # 生成PDF pdf = FPDF() pdf.add_page() pdf.set_font("Arial", size=12) pdf.cell(200, 10, txt=f"Excel Anomaly Report for {col_name}", ln=True, align='C') pdf.image('/tmp/chart.png', x=10, y=30, w=180) pdf.output("/tmp/report.pdf") print(json.dumps({ "report_path": "/tmp/report.pdf", "anomaly_count": len(anomalies) }))

这两个脚本的编写原则是：只做一件事，输入输出严格JSON化，失败时返回error字段。Harness会自动捕获stdout，解析JSON，把error字段映射到工作流失败状态。这是我踩过的最大坑——早期脚本用print("success")，Harness永远收不到结构化输出，直接卡死。

4. 启动、调试与生产级避坑指南

现在执行docker-compose up -d，等30秒，用curl测试：

curl -X POST http://localhost:8000/v1/workflows/excel_anomaly_report \ -H "Content-Type: application/json" \ -d '{ "file_path": "/data/sample.xlsx", "target_column": "temperature", "threshold_std": 2.5 }'

如果返回{"status": "running", "run_id": "xxx"}，说明工作流已入队。再用curl http://localhost:8000/v1/runs/xxx轮询，直到看到"status": "completed"和PDF路径。

但真实环境远比这复杂。以下是我在三套生产环境里总结的硬核避坑点：

4.1 文件路径权限地狱：容器内外的“看不见的手”

最常发生的错误是：harness-tool-server报错Permission denied，但宿主机上ls -l /data/sample.xlsx明明是755。原因在于Docker挂载卷的UID/GID映射。容器内进程默认以root（UID 0）运行，但你的Excel文件可能是普通用户（UID 1001）创建的。Linux内核拒绝UID 0的进程读取UID 1001的文件，除非文件权限是644或更宽松。

解决方案只有两个：

• 方案A（推荐）：启动容器时指定用户ID，让容器内进程UID=宿主机文件UID

  harness-tool-server: # ... 其他配置 user: "1001:1001" # 改成你宿主机用户的UID:GID

• 方案B：统一用chmod 644 /data/*.xlsx，但治标不治本，新文件又得改。

我见过客户因此耽误两天——运维坚持说“文件权限没问题”，开发坚持说“代码没问题”，最后发现是Docker用户映射这层薄薄的纱。

4.2 模型服务的“静默崩溃”：GPU显存不足的假象

当harness-model-server容器日志停在Loading model...再也不动，90%是显存不足。但nvidia-smi显示GPU显存只用了30%，很迷惑。真相是：PyTorch默认预留全部显存的90%给当前进程，哪怕你只加载7B模型。harness-model-server的启动脚本里有一行os.environ['PYTORCH_CUDA_ALLOC_CONF'] = 'max_split_size_mb:128'，它强制PyTorch小块分配显存，避免一次性占满。

实操技巧：在harness-model-server的environment里加这一行：

environment: - PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:128 # ... 其他变量

这能让7B模型在12GB显存卡上稳定运行，而不是卡死在加载阶段。

4.3 工作流调试的“黑盒困境”：如何知道哪一步挂了？

Harness默认只返回最终状态，中间步骤失败时，日志分散在三个容器里。快速定位法：

1. 进入harness-core容器：docker exec -it harness_harness-core_1 /bin/sh
2. 查看实时日志：tail -f /var/log/harness/core.log | grep "run_id=xxx"
3. 找到失败步骤名（如calculate_statistics），再去harness-model-server容器里搜同一run_id

但更高效的是启用步骤级日志透出。在harness-core的environment里加：

environment: - STEP_LOGGING_ENABLED=true - STEP_LOG_LEVEL=DEBUG

这样每一步执行的输入、输出、耗时都会打到core.log里，格式清晰如：

[STEP] load_and_validate_excel START run_id=abc123 input={"file_path":"/data/x.xlsx"} [STEP] load_and_validate_excel SUCCESS output={"file_info":{"rows":1000,"columns":["id","temp"]}} [STEP] calculate_statistics START input={"system_prompt":"...", "user_prompt":"数据统计：{...}"}

这个功能文档里叫“verbose logging”，但实际开启后日志量暴增，生产环境务必关掉，只在调试时开。

5. 局域网AI Agent平台的进阶实战：从单点工具到业务中枢

部署成功只是起点。真正的价值在于把它嵌入现有业务流。分享三个我们落地的真实模式：

5.1 模式一：与企业微信/钉钉机器人深度集成

很多团队不想打开浏览器访问http://192.168.1.100:8000，就想在群里@机器人发指令。我们用harness-core的Webhook能力实现：

• 在企业微信后台配置机器人，设置回调URL为http://192.168.1.100:8000/v1/webhooks/wecom
• harness-core收到消息后，自动解析@机器人 分析附件里的温度数据，提取附件URL，下载到本地/data/tmp/，再触发excel_analyzer.yaml工作流
• 工作流完成后，调用企业微信API把PDF报告和异常摘要发回群聊

关键点在于：Webhook处理器必须是Harness原生支持的，不能自己写Flask服务。因为只有原生处理器才能把消息内容自动映射为工作流的input参数。我们试过自建中转服务，结果每次都要手动JSON转换，维护成本爆炸。

5.2 模式二：构建“AI质检员”硬件网关

某工厂在产线边缘部署树莓派4B，接USB摄像头拍产品照片。传统方案是把图片传到中心服务器识别，但网络延迟高、带宽压力大。我们改造为：

• 树莓派上跑一个轻量HTTP服务，收到拍照指令后，调用本地harness-core（树莓派也装Docker）的image_quality_check.yaml工作流
• 该工作流包含三步：1）用ONNX Runtime跑YOLOv5s模型检测缺陷；2）用CLIP模型比对缺陷图与标准图相似度；3）若相似度<0.7，触发邮件告警并保存截图

全程数据不出产线，响应时间<800ms。树莓派内存只有4GB，所以harness-model-server必须用DEVICE=cpu且MODEL_NAME=yolov5s.onnx，否则OOM。

5.3 模式三：动态工作流编排——让AI自己决定下一步

最高阶用法：工作流本身可编程。例如dynamic_analyzer.yaml：

steps: - name: analyze_file_type model: deepseek-r1-7b input: system_prompt: "你是一个文件类型分析器。根据文件扩展名和前100字符，判断它是Excel、CSV、PDF还是图像。只返回JSON，字段type。" user_prompt: "文件名：{{ input.file_path }}，开头内容：{{ input.preview_content }}" - name: dispatch_to_tool model: deepseek-r1-7b input: system_prompt: "根据文件类型，返回应调用的工作流名称。Excel→excel_analyzer，CSV→csv_analyzer，PDF→pdf_text_extractor，图像→image_analyzer。只返回工作流名。" user_prompt: "文件类型：{{ steps.analyze_file_type.output.type }}" # 关键：output作为下一个工作流的trigger output_as_trigger: true

当用户上传任意文件，Harness会先判断类型，再动态选择对应工作流执行。这已经接近AI Agent的自主决策雏形，而不需要你写一行条件判断代码。

最后分享一个血泪教训：所有工作流YAML必须用yamllint检查。我们曾因一个缩进空格错误，导致harness-core启动时静默失败，日志里只有一行Failed to load workflows，排查6小时才发现是YAML语法错误。现在CI流程里强制加入yamllint -c .yamllint.yml ./workflows/*.yaml，一劳永逸。

这个局域网AI平台的价值，从来不在“它能跑多大的模型”，而在于“它让AI真正成了你业务流水线里一个可调度、可监控、可替换的标准工位”。当你不再需要为每个新需求重写Python脚本，而是打开YAML文件新增三行定义，你就拿到了AI落地的第一把钥匙。