Harness工程化实践：AI Native交付的可控性落地指南

1. 项目概述：从“小摊”到AI Native，不是换工具，是重构交付逻辑

得物“小摊”这个项目名字听起来很接地气——它不是什么高大上的中台系统，而是面向一线运营、内容编辑、商品审核人员的轻量级协作工具。我第一次接触它时，团队正被三类问题反复折磨：商品上架前的合规文案生成耗时太长，用户评论里埋着大量未识别的违禁词需要人工翻查，还有每天上百条客服咨询要靠复制粘贴模板来应付。当时用的是几个零散的API调用脚本+Excel表格管理规则，每次模型更新或策略调整，都得找开发改代码、测接口、发版本，平均响应周期72小时起步。直到我们决定把“小摊”真正变成AI Native——不是给旧系统加个AI按钮，而是让AI成为交付链路里的“第一公民”。

这里说的AI Native，核心就两点：一是所有业务逻辑默认以AI能力为原生构件，比如“生成商品标题”不再是一个功能点，而是一个可编排、可灰度、可回滚的服务单元；二是交付过程本身必须可控、可观、可审计，不能出现“模型一跑，结果不知从哪来、对错不知怎么判”的黑箱状态。Harness正是在这个背景下被选中的——它不是大模型推理框架，也不是Agent开发平台，而是一个专为AI服务交付设计的“工程化控制面”。你可以把它理解成AI时代的Kubernetes：不负责训练模型、不写Prompt、不搞RAG，但它管模型怎么上线、流量怎么切、效果怎么监控、故障怎么熔断。热搜词里反复出现的“deepseek harness怎么安装”“harness和agent区别”，恰恰说明很多人还没分清：Harness解决的是“如何稳稳地把AI能力交到业务手里”，而Agent解决的是“AI自己能干多少活”。我们用Harness重构“小摊”，本质是把AI交付从“手工作坊式发布”升级为“流水线式投产”。

这个项目适合三类人参考：一是正在落地AI应用但卡在“上线即失控”阶段的技术负责人，你需要看到一个真实场景下如何定义可控边界；二是想用开源模型但苦于缺乏工程化配套的算法工程师，这里会拆解Harness如何把DeepSeek、Qwen等模型封装成标准服务；三是业务侧同学，如果你常抱怨“AI功能总不稳定”“新策略上线要等一周”，你会明白为什么交付流程比模型本身更值得投入。全文不讲概念，只讲我们在得物小摊项目里踩过的坑、算过的账、写过的配置——所有内容均可直接复现，连Docker镜像Tag和Prometheus指标名都给你标清楚。

2. 整体架构设计：为什么放弃LangChain/LLamaIndex，选择Harness做控制中枢

2.1 架构演进的三次试错：从胶水代码到控制面觉醒

最开始我们尝试过三条路，每条都走了至少两周才推倒重来：

第一版是“胶水代码流”：用Python写一堆Flask接口，每个接口对应一个AI任务（比如/generate-title），内部硬编码调用DeepSeek-V2 API。问题很快暴露：当运营提出“标题要避开‘最’字但保留‘优选’”时，我得改Prompt、改后处理逻辑、重新打包镜像、走CI/CD流程。更糟的是，某次模型API返回格式微调，导致所有接口批量报错，而日志里只显示“HTTP 500”，根本不知道是模型层还是代码层的问题。

第二版转向LangChain：用Chain封装Prompt+LLM+OutputParser，看起来很优雅。但实际运行中发现两个致命缺陷：一是Chain的调试成本极高，一个标题生成失败，你要在RunnableSequence里逐层打印中间变量，而这些变量往往是Base64编码的二进制流；二是它完全不提供流量治理能力。当用户突然涌入，所有请求挤在同一个LLM调用上，超时率飙升到40%，而LangChain连最基本的请求限流都没有——你得自己写装饰器，再和Redis集成，最后发现这已经不是AI框架该干的事了。

第三版试了LlamaIndex的QueryEngine，本意是利用它的RAG能力做商品知识库检索。结果发现它把“索引构建”和“查询执行”耦合太紧：每次更新商品库，整个向量索引要全量重建，耗时3小时。而运营需要的是“新增一个SKU，10分钟内生效”，这种延迟根本不可接受。

这三次失败让我们意识到：AI应用的瓶颈从来不在模型能力，而在交付链路的“确定性”。我们需要的不是一个能写Prompt的框架，而是一个能让AI服务像数据库连接池一样被管理的系统。Harness的定位恰好击中这个痛点——它不碰模型内部，只管模型外部：怎么注册、怎么路由、怎么监控、怎么降级。它的核心抽象是Service（服务）、Route（路由）、Policy（策略）三层，和我们熟悉的微服务治理思路完全一致。比如把DeepSeek-Coder封装成一个Service，再通过Route定义“/title-gen”路径指向它，最后用Policy配置“错误率>5%自动切到备用Qwen模型”。这种设计让业务同学也能看懂架构图：左边是运营提需求，右边是Harness控制台点几下就生效，中间没有一行需要开发写的胶水代码。

2.2 Harness与Agent的本质区别：控制面 vs 执行面

网络热词里高频出现的“harness和agent区别”，必须掰开揉碎讲清楚。很多团队误以为装了Harness就能自动解决AI任务编排，结果发现它根本不生成任何文本——因为它压根不是执行引擎。

• Agent是执行者：像AutoGen、LangGraph这类框架，核心职责是协调多个LLM调用、调用工具、维护对话状态。它解决的是“AI怎么思考”，典型场景是客服机器人自主完成查订单→改地址→发短信全流程。但Agent的致命弱点是不可控：一个Step出错，整个Chain可能崩溃；不同Agent间状态无法共享；灰度发布？不存在的，要么全量上线要么全部回滚。

• Harness是控制器：它不参与任何推理过程，只做三件事：① 把模型API包装成标准化Service（比如统一返回JSON Schema）；② 根据业务规则动态路由请求（例如按用户等级分配不同模型）；③ 实时采集指标并触发策略（如检测到DeepSeek输出含违禁词，自动切换到规则引擎兜底）。它解决的是“AI怎么被安全交付”，就像Nginx之于Web服务——你不会说“Nginx帮我生成网页”，但没它，你的网站早被流量打垮了。

我们在小摊项目里严格划分了这两层：Agent层由业务团队用LangChain搭建（比如评论审核Agent，它会调用OCR识别图片、再调用LLM分析文本），而Harness层由平台团队维护，负责保障所有Agent调用的底层模型服务稳定。这种分离让算法同学专注Prompt优化，开发同学专注业务逻辑，平台同学专注稳定性——各司其职，互不干扰。热搜词里“agent harness可以发起工具调用，而不是自己就是工具”这句话非常精准：Harness就是那个“发起调用”的调度器，不是执行工具的工人。

2.3 为什么选Harness而非自研？一次真实的ROI计算

有同事提议“不如我们自己写个轻量版控制面”，我们花了三天做了可行性验证，最终用数据说服了所有人。对比维度如下：

最关键的是稳定性收益：Harness的熔断机制让我们避免了一次重大事故。某天DeepSeek服务端突发OOM，错误率飙升至35%。Harness在12秒内检测到异常，自动将90%流量切到Qwen备用模型，而用户无感知。如果靠人工盯监控+手动切流，按平均响应时间5分钟计算，至少损失200+条商品上架请求。这笔账算下来，Harness的License费用（我们选的是开源版Harness Core）不到一次线上事故损失的1/10。

3. 核心细节解析：Harness在小摊项目中的关键配置与实操要点

3.1 Service注册：如何把裸模型API变成可管理的服务单元

Harness的Service不是简单代理，而是通过Adapter层实现协议标准化。以DeepSeek-V2为例，它的原始API要求POST/v1/chat/completions，请求体是OpenAI格式，但响应里choices[0].message.content可能包含Markdown符号，而小摊前端需要纯文本。如果直接暴露给业务方，每个调用方都要写清洗逻辑，违背“一次封装，处处可用”原则。

我们创建了一个Custom Adapter，核心代码只有47行（已脱敏）：

# deepseek_adapter.py from harness.adapter import BaseAdapter import json class DeepSeekAdapter(BaseAdapter): def __init__(self, config): super().__init__(config) self.model_name = config.get("model", "deepseek-v2") def transform_request(self, request_data): # 将业务方传入的{title: "手机", category: "数码"}转为OpenAI格式 messages = [ {"role": "system", "content": "你是一个得物商品标题生成专家，输出纯文本，不要markdown"}, {"role": "user", "content": f"生成{request_data['category']}类商品标题，要求：{request_data.get('rules', '')}，商品名：{request_data['title']}"} ] return { "model": self.model_name, "messages": messages, "temperature": 0.3 } def transform_response(self, raw_response): # 清洗DeepSeek返回的多余符号 content = raw_response["choices"][0]["message"]["content"] # 移除可能的**加粗**、-列表符号、代码块 import re cleaned = re.sub(r'[\*\`\-\#]+', '', content).strip() return {"generated_title": cleaned, "model_used": self.model_name} # 注册到Harness harness adapter add --name deepseek-v2-adapter --file deepseek_adapter.py

注册Service时的关键参数：

harness service register \ --name title-gen-service \ --adapter deepseek-v2-adapter \ --endpoint http://deepseek-prod:8000/v1/chat/completions \ --health-check-path /health \ --timeout 30s \ --retry-attempts 2 \ --config '{"model": "deepseek-v2"}'

提示：--health-check-path必须指向模型服务的真实健康检查端点。我们曾因填错路径（填成/）导致Harness误判服务宕机，自动切流到备用模型。实测发现DeepSeek官方镜像的健康检查端点是/health，返回{"status":"ok"}，这个细节文档里没写，得自己curl探测。

Service注册后，业务方调用方式彻底简化：

# 以前（胶水代码时代） curl -X POST http://legacy-api:5000/generate-title \ -H "Content-Type: application/json" \ -d '{"title":"iPhone 15","category":"手机","rules":"禁用极限词"}' # 现在（Harness时代） curl -X POST http://harness-gateway:8080/title-gen-service \ -H "Content-Type: application/json" \ -d '{"title":"iPhone 15","category":"手机","rules":"禁用极限词"}' # 返回 {"generated_title":"得物严选 iPhone 15 全网通5G智能手机","model_used":"deepseek-v2"}

这种标准化带来两个隐性收益：一是前端SDK可以统一封装，iOS/Android/Web三端调用同一套接口；二是审计合规变得简单——所有AI调用都经过Harness网关，天然记录request_id、model_used、latency，满足得物内部的数据安全审计要求。

3.2 Route配置：用业务规则驱动流量分发，不止是A/B测试

Harness的Route远比传统网关的路由强大。它支持基于请求内容的动态路由，这才是小摊项目能实现“千人千模”的关键。

我们定义了三条核心Route：

1. 按用户等级路由：VIP用户走DeepSeek-V2（生成质量高但贵），普通用户走Qwen-7B（性价比高）

   # route-vip.yaml name: vip-title-route service: title-gen-service match: - condition: "request.headers['X-User-Level'] == 'VIP'" target: deepseek-v2-adapter - condition: "request.headers['X-User-Level'] == 'NORMAL'" target: qwen-7b-adapter

2. 按商品类目路由：美妆类目需强合规审查，强制走带RAG的DeepSeek+规则引擎组合

   # route-beauty.yaml name: beauty-title-route service: title-gen-service match: - condition: "request.body.category in ['美妆', '护肤', '香水']" target: deepseek-rag-adapter # 此Adapter先查知识库再调模型

3. 按实时指标路由：当DeepSeek错误率>3%时，自动降级到Qwen

   # route-fallback.yaml name: fallback-route service: title-gen-service fallback: target: qwen-7b-adapter condition: "metrics.error_rate > 0.03"

这些Route不是静态配置，而是通过Harness CLI动态加载：

harness route apply -f route-vip.yaml harness route apply -f route-beauty.yaml # 启用熔断路由（需单独开启Metrics Collector） harness policy enable --name fallback-policy

注意：条件表达式语法必须严格遵循Harness DSL。我们曾把request.body.category == '美妆'写成request.body.category is '美妆'，导致路由始终不匹配。正确写法是用==，且字符串必须用单引号包裹。这个细节在官方文档的“Expression Language”章节第7页才有说明，建议新手先用harness route test命令验证表达式。

最实用的技巧是Route的优先级机制：Harness按YAML文件名字母序加载，所以01-vip.yaml会比02-beauty.yaml优先匹配。我们故意用数字前缀确保VIP用户永远获得最高优先级，避免类目路由覆盖用户等级路由。

3.3 Policy策略：把“可控”二字落到每一行配置里

Harness的Policy是真正体现“AI Native可控性”的模块。它不像传统限流那样简单粗暴，而是针对AI服务特性设计的精细化治理。

我们配置了四类核心Policy：

1. 熔断策略（Circuit Breaker）
监控error_rate（5分钟窗口）和latency_p95，双指标同时触发才熔断：

# policy-circuit-breaker.yaml name: deepseek-circuit-breaker service: title-gen-service conditions: - metric: error_rate threshold: 0.05 window: 300s - metric: latency_p95 threshold: 8000 # ms window: 300s action: type: fallback target: qwen-7b-adapter cooldown: 60s # 熔断后60秒内不尝试恢复

2. 速率限制（Rate Limiting）
不是全局QPS限制，而是按用户ID维度限流，防薅羊毛：

# policy-rate-limit.yaml name: user-rate-limit service: title-gen-service limit: - key: "request.headers['X-User-ID']" rate: 10 # 每用户每分钟10次 burst: 5 # 允许突发5次

3. 内容安全策略（Content Safety）
这是小摊项目的独创设计：Harness不直接过滤内容，而是调用得物自研的违禁词检测服务，根据结果决定是否拦截：

# policy-content-safety.yaml name: content-safety-check service: title-gen-service pre-hook: - type: external-api url: http://content-guard:9000/check method: POST body: '{"text": "{{response.generated_title}}"}' success-condition: "response.status == 'clean'" on-failure: action: reject message: "检测到违禁词，请修改商品信息"

4. 成本优化策略（Cost Optimization）
当DeepSeek调用token数超过阈值，自动触发更便宜的模型：

# policy-cost-optimize.yaml name: cost-optimization service: title-gen-service post-hook: - type: token-consumption threshold: 2000 # 单次调用超2000 token action: switch-model target: qwen-7b-adapter

实操心得：Policy的pre-hook和post-hook是隐藏宝藏。我们曾用pre-hook在请求进入模型前做缓存查询——如果相同商品名+类目组合的历史结果存在且<1小时，则直接返回缓存，跳过模型调用。实测缓存命中率32%，每月节省DeepSeek API费用约1.7万元。这个技巧在Harness官方案例库里没提，是我们和平台团队一起摸索出来的。

4. 实操过程：从零部署Harness到小摊全量上线的完整流程

4.1 环境准备：为什么坚持用Ubuntu 22.04而非Docker Desktop

虽然Harness官方推荐Docker部署，但我们在线上环境坚持用Ubuntu 22.04物理机（非容器），原因有三：

1. GPU直通需求：DeepSeek-V2推理需要A10显卡，Docker容器对GPU支持复杂，而Ubuntu原生驱动更稳定。我们用nvidia-smi确认驱动版本为535.104.05，CUDA 12.2，与DeepSeek官方镜像要求完全匹配。

2. 内核参数调优：AI服务对网络延迟敏感，我们修改了/etc/sysctl.conf：

   # 减少TIME_WAIT连接占用 net.ipv4.tcp_fin_timeout = 30 net.ipv4.tcp_tw_reuse = 1 # 提升并发连接数 net.core.somaxconn = 65535 net.ipv4.ip_local_port_range = 1024 65535

   这些参数在Docker Desktop的WSL2环境下无法生效。

3. 日志审计合规：得物要求所有服务日志落盘且不可篡改。Ubuntu下直接配置rsyslog写入/var/log/harness/，而Docker日志需额外挂载卷，增加运维复杂度。

安装步骤精简为6步（全程可复制粘贴）：

# 1. 安装基础依赖 sudo apt update && sudo apt install -y curl gnupg2 software-properties-common # 2. 添加Harness仓库（注意：必须用https://repo.harness.io，不是官网下载页的链接） curl -fsSL https://repo.harness.io/harness-keyring.gpg | sudo gpg --dearmor -o /usr/share/keyrings/harness-archive-keyring.gpg echo "deb [arch=amd64 signed-by=/usr/share/keyrings/harness-archive-keyring.gpg] https://repo.harness.io stable main" | sudo tee /etc/apt/sources.list.d/harness.list # 3. 安装Harness Core（非Community版，因需Policy高级功能） sudo apt update && sudo apt install -y harness-core # 4. 初始化配置（生成默认harness.yaml） sudo harness init --admin-email admin@dev.dewu.com --admin-password 'StrongPass123!' # 5. 启动服务（自动启用systemd） sudo systemctl enable harness-core && sudo systemctl start harness-core # 6. 验证（等待2分钟，检查端口） curl -v http://localhost:8080/health # 应返回{"status":"ok"}

关键细节：harness init命令中的--admin-email必须是企业邮箱域名（@dev.dewu.com），否则后续SSO集成会失败。我们第一次用@gmail.com导致OAuth2配置异常，排查了4小时才发现是域名白名单问题。

4.2 模型服务部署：DeepSeek-V2的生产级部署实践

Harness本身不托管模型，需先部署模型服务。我们选择DeepSeek官方提供的Docker镜像，但做了三项关键改造：

1. 内存优化配置
原始镜像默认使用--max-total-tokens 8192，导致单卡A10只能并发2个请求。通过分析小摊实际请求长度（标题生成平均token数<500），我们调整为：

docker run -d \ --name deepseek-prod \ --gpus all \ --shm-size=2g \ -p 8000:8000 \ -e MODEL_NAME="deepseek-ai/deepseek-coder-33b-instruct" \ -e MAX_TOTAL_TOKENS=2048 \ -e MAX_INPUT_LENGTH=1024 \ deepseek-ai/deepseek-coder:latest \ --host 0.0.0.0:8000 \ --port 8000 \ --tensor-parallel-size 1 \ --pipeline-parallel-size 1

实测并发能力从2提升至8，QPS从3.2提高到12.7。

2. 健康检查增强
官方镜像的/health端点只检查进程存活，我们添加了模型加载状态检查。在容器启动后执行：

# 进入容器 docker exec -it deepseek-prod bash # 创建健康检查脚本 echo '#!/bin/bash if python3 -c "import torch; print(torch.cuda.memory_allocated())" 2>/dev/null | grep -q "0"; then exit 1 else exit 0 fi' > /app/health-check.sh chmod +x /app/health-check.sh

然后在Dockerfile中替换健康检查命令：HEALTHCHECK --interval=30s --timeout=3s --start-period=60s --retries=3 CMD /app/health-check.sh

3. 日志结构化
为方便Harness采集，我们将vLLM日志格式改为JSON：

# 启动时添加参数 --log-level INFO \ --log-format '{"time":"%(asctime)s","level":"%(levelname)s","msg":"%(message)s","req_id":"%(request_id)s"}'

这样Harness的Metrics Collector能自动提取req_id关联请求链路。

部署完成后，在Harness中注册Service：

harness service register \ --name deepseek-title-gen \ --adapter deepseek-v2-adapter \ --endpoint http://10.0.1.100:8000/v1/chat/completions \ --health-check-path /health \ --timeout 25s \ --retry-attempts 1 \ --config '{"model": "deepseek-coder-33b-instruct"}'

4.3 全链路联调：用真实业务场景验证每一个环节

联调不是简单ping通，而是模拟小摊的真实工作流。我们设计了三级验证：

Level 1：单点功能验证
用Harness CLI直接调用，确认Adapter转换正确：

harness service invoke \ --service title-gen-service \ --data '{"title":"MacBook Pro","category":"电脑","rules":"突出M2芯片优势"}' \ --verbose # 预期输出：{"generated_title":"得物严选 Apple MacBook Pro M2芯片16GB内存512GB SSD笔记本电脑","model_used":"deepseek-v2"}

Level 2：Route策略验证
构造不同Header的请求，验证VIP路由：

# 普通用户 curl -H "X-User-Level: NORMAL" http://harness-gw:8080/title-gen-service -d '{"title":"耳机"}' # 应返回 model_used: qwen-7b # VIP用户 curl -H "X-User-Level: VIP" http://harness-gw:8080/title-gen-service -d '{"title":"耳机"}' # 应返回 model_used: deepseek-v2

Level 3：Policy熔断验证
主动制造故障，测试熔断是否生效：

# 1. 先确认DeepSeek服务正常 curl http://deepseek-prod:8000/health # 返回ok # 2. 临时停掉DeepSeek服务 docker stop deepseek-prod # 3. 发起10次请求，观察第1次失败后，第2-10次是否自动切到Qwen for i in {1..10}; do curl -s http://harness-gw:8080/title-gen-service -d '{"title":"测试"}' | jq .model_used done # 预期：第1次报错，第2-10次返回"qwen-7b"

踩坑记录：第一次熔断测试失败，原因是cooldown时间设得太短（30秒）。Harness在熔断后立即尝试恢复，但DeepSeek服务还没起来，导致反复失败。我们最终将cooldown设为60秒，并配合health-check-interval: 10s，确保服务真正恢复后再切流。

4.4 全量上线与灰度发布：如何让业务方零感知地切换

上线不是一刀切，而是分五阶段推进：

1. Shadow Mode（影子模式）：Harness同时调用DeepSeek和Qwen，只把DeepSeek结果返回给前端，Qwen结果仅写入日志。持续7天，对比两模型输出质量（人工抽检1000条标题，DeepSeek优质率82% vs Qwen 76%）。

2. 1%流量（内部员工）：开放给得物内部运营同学使用，收集反馈。发现DeepSeek生成的标题偶尔带“🔥”符号，不符合得物UI规范。立刻更新Adapter的transform_response函数，增加emoji过滤。

3. 10%流量（新入驻商家）：这批用户对标题质量要求高，但数量少。监控显示错误率稳定在1.2%，低于阈值。

4. 50%流量（全量商家）：启用Route策略，VIP商家100%走DeepSeek，普通商家50%走DeepSeek。此时Harness Dashboard显示DeepSeek负载均衡，无单点过载。

5. 100%流量：关闭Qwen路由，所有流量走DeepSeek。但Policy仍保留，熔断开关始终开启。

整个过程历时18天，期间无一次线上事故。最关键的指标是“策略生效时间”：从运营提出“标题要增加‘正品保障’字样”，到全量生效，耗时22分钟（写Prompt→注册Adapter→配置Route→发布）。而之前胶水代码时代，平均需要3.5天。

5. 常见问题与排查技巧实录：那些没写在文档里的实战经验

5.1 Harness启动失败的三大元凶及速查表

最隐蔽的问题是SELinux：Ubuntu默认关闭，但某些云服务器镜像启用了SELinux。现象是Harness进程启动成功，但无法绑定8080端口。解决方案：

sudo setenforce 0 # 临时关闭 sudo sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/selinux/config

5.2 Adapter调试的黄金三步法

当Adapter转换结果不符合预期，按此顺序排查：

Step 1：绕过Harness直调模型
用curl模拟Adapter的transform_request输出：

# 假设Adapter生成的请求体是： { "model": "deepseek-v2", "messages": [{"role":"user","content":"生成手机标题"}], "temperature": 0.3 } # 直接调用模型 curl -X POST http://deepseek-prod:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"deepseek-v2","messages":[{"role":"user","content":"生成手机标题"}],"temperature":0.3}'

如果这步失败，问题在模型服务，与Harness无关。

Step 2：检查Harness日志中的Adapter调用链

sudo journalctl -u harness-core -n 200 \| grep -A 10 -B 5 "deepseek-v2-adapter" # 查看是否有"transform_request failed"或"transform_response error"

Step 3：在Adapter中加DEBUG日志
修改Adapter的transform_request函数：

def transform_request(self, request_data): self.logger.info(f"[DEBUG] Raw request: {request_data}") # 加这一行 # ...原有逻辑

重启Harness后，日志会输出原始请求数据，确认业务方传参是否符合预期。

5.3 Route不生效的五个致命细节

1. 条件表达式大小写敏感：request.headers['X-User-Level']必须完全匹配Header名，x-user-level会失败。

2. JSON Path语法错误：request.body.category正确，request.body['category']错误（Harness不支持方括号语法）。

3. Route未启用：harness route list显示STATUS: disabled，需执行harness route enable --name xxx。

4. Service名称拼写错误：Route中service: title-gen-service必须与harness service list输出的名称完全一致，包括连字符。

5. YAML缩进错误：match:下的- condition:必须顶格，若缩进2空格会导致解析失败，Harness静默忽略该Route。

我们曾因第5条浪费3小时：YAML文件用空格缩进，而Harness要求Tab缩进。解决方案是用yamllint校验：

pip install yamllint yamllint route-vip.yaml

5.4 Metrics Collector采集不到指标的终极排查

Harness的Metrics Collector依赖Prometheus，常见断点：

• Collector未启动：sudo systemctl status harness-metrics-collector，若未运行则sudo systemctl start harness-metrics-collector

• Prometheus抓取配置错误：检查/etc/prometheus/prometheus.yml中是否有：

  - job_name: 'harness' static_configs: - targets: ['localhost:9090'] # Harness Metrics端口

• 模型服务未暴露指标：DeepSeek镜像需添加--enable-metrics参数，否则不输出/metrics端点。

• 防火墙拦截：sudo ufw status确认9090端口开放：sudo ufw allow 9090

最有效的验证方法是直接访问Metrics端点：

curl http://localhost:9090/metrics \| grep "harness_service_latency_seconds" # 应返回类似：harness_service_latency_seconds{service="title-gen-service",quantile="0.95"} 1250.0

5.5 生产环境性能调优的三个实战技巧

技巧1：调整Harness Worker并发数
默认Worker数=CPU核心数，但AI服务I/O密集，需增加：

# 编辑 /etc/harness/core/config.yaml worker: pool_size: 32 # 原值为8，提升至32 max_connections: 1024

技巧2：启用Response缓存
对重复请求（如相同商品ID多次生成标题），在Route中添加：

cache: enabled: true ttl: 3600 # 缓存1小时 key: "request.body.title + request.body.category"

技巧3：分离Metrics采集负载
将Metrics Collector部署在独立机器，避免与Harness Core争抢资源：

# 在Metrics专用机上 harness metrics-collector start \