企业官网建设流程全解析

1. 项目概述：当AI Agent被关进“玻璃房”，我们怎么让它干活还不出错？

“隔离内网下 AI Agent 工程实战”——这标题一出来，我就知道不是在讲概念Demo，而是真刀真枪的落地现场。我干了十多年系统集成、智能体平台交付和政企级AI工程化落地，最常听到的一句话是：“你们那个AI Agent很酷，但我们网络是物理隔离的，连DNS都不通，能跑吗？”——不是不能跑，是得重新设计整套呼吸系统。

所谓“隔离内网”，不是指开了防火墙规则就叫隔离，而是物理层面断开与公网的所有数据通道：没有网关出口、没有NAT映射、没有DNS解析服务、甚至没有时间同步源（NTP服务器不可达）。它像一座建在孤岛上的自动化工厂，所有原料、工具、质检标准、操作手册都必须提前运进去，连螺丝钉型号都要登记备案。而AI Agent，在这里不是个会聊天的玩具，它是要调度PLC读取产线传感器、调用本地OCR识别质检单据、根据规则引擎生成工单并推送到内网IM系统的执行体。它不联网，但必须“懂业务、守规矩、可审计、零外泄”。

关键词里反复出现的AI Agent、内网、MCP Tools、engineering、isolated network，已经勾勒出完整画像：这不是LLM API调用练习，而是面向工业控制、金融核心、电力调度、医疗影像等强合规场景的可信智能体工程体系构建。你不会在这里看到OpenAI Key填在哪一行，但会花两小时校准本地模型的token截断逻辑；你也不会配置ngrok隧道，但要手写一套基于Unix Domain Socket的跨进程Agent通信协议；更不会用HuggingFace Hub下载模型，而是把Qwen2-7B-Int4量化包、RAG向量索引、技能函数签名表，全部打包进一个离线部署镜像，用sha256sum逐字节校验。

适合谁看？如果你正面临以下任一情况，这篇就是为你写的：

• 你刚接手一个“国产化替代”项目，客户明确要求所有AI模块运行在无外网连接的信创服务器集群上；
• 你在做某大型制造企业的预测性维护系统，设备数据严禁出域，但又要让Agent自动分析振动频谱并触发维修流程；
• 你团队刚用LangChain搭了个Demo，领导问“能不能部署到我们DMZ区那台麒麟V10服务器上？”，你发现连pip install都报SSL证书错误；
• 你正在评估MCP（Model Control Protocol）Tools在离线环境下的可行性，但官方文档只写了“支持本地模式”，没告诉你本地模式下如何绕过OAuth2.0鉴权链路。

这不是教你怎么“让AI上网”，而是教你怎么给AI造一套不依赖互联网的生存操作系统。下面每一部分，都是我在三个不同行业（电力调度中心、三甲医院影像科、军工研究所）踩坑后，用胶带、Python脚本和一份手写checklist拼出来的实操路径。

2. 整体架构设计：放弃“云原生思维”，拥抱“嵌入式工程范式”

2.1 为什么不能照搬公有云AI Agent架构？

很多团队拿到需求第一反应是：“把LlamaIndex+LangGraph+FastAPI这套搬进去，加个反向代理就行。”——这是最危险的起点。我见过某省电网项目，直接把开源Agent框架部署到内网K8s集群，结果上线第三天因时钟漂移导致JWT token过期，整个故障诊断Agent集体失能，因为它的身份认证依赖外部NTP和公有云密钥分发服务。问题不在代码，而在默认假设（assumption）的崩塌。

公有云Agent架构隐含五大外部依赖，隔离内网中全部失效：

提示：别试图“打补丁式兼容”。我试过给LangChain加一层Mock HTTP Client拦截所有requests调用，结果发现它底层依赖urllib3的connection pool管理，而pool初始化又触发了系统DNS查询——哪怕你根本没发请求。真正的隔离工程，是从requirements.txt第一行开始重写依赖树。

2.2 我们采用的“三平面四层”离线架构

经过六个项目的迭代，我们固化了一套“三平面四层”架构，它不追求技术炫技，只确保一件事：任何组件崩溃，都不导致Agent整体不可用。

三平面定义：

• 控制平面（Control Plane）：纯Python实现的轻量级调度器，不依赖任何外部服务。它只做三件事：加载Agent配置、启动Skill进程、维护心跳健康检查。核心是用multiprocessing.Manager实现跨进程状态共享，避免引入Redis或数据库。
• 数据平面（Data Plane）：所有数据流动严格限定在本地文件系统+内存映射。向量库用chromadb的PersistentClient模式（底层SQLite），RAG索引构建在部署前完成；结构化数据走sqlite3WAL模式，保证高并发写入；非结构化文件（PDF/图片）存于/opt/agent/data/raw/，按哈希分目录存储防inode耗尽。
• 安全平面（Security Plane）：不是加防火墙，而是默认拒绝所有未声明的交互。每个Skill启动时，由控制平面注入一个CapabilityToken对象，该对象硬编码了它被允许访问的文件路径前缀、可执行的系统命令白名单、最大内存占用阈值。越权操作直接触发os.kill()终止进程。

四层堆栈：

1. 硬件抽象层（HAL）：封装GPU/CPU/NPU设备访问。例如，同一份代码在海光DCU上走ROCm，在昇腾上走CANN，在Intel CPU上走OpenVINO。通过import agent.hal as hal统一调用，底层自动探测设备并加载对应runtime。
2. 模型服务层（MSL）：vLLM的离线精简版。我们删掉了所有HTTP API、model registry、multi-tenant logic，只保留LLMEngine核心，用multiprocessing.Pipe接收prompt，返回logprobs和token ids。模型权重文件用llama.cpp格式预量化，启动时mmap加载，内存占用降低60%。
3. 技能编排层（SOL）：替代LangGraph的轻量级DAG引擎。所有Node定义为Python类，Edge通过装饰器@depends_on("node_a")声明，运行时由控制平面静态解析依赖图并拓扑排序。无动态分支，所有条件判断在Node内部完成，避免运行时图重构开销。
4. 应用接口层（AIL）：仅提供两种接入方式：① 内网HTTP Server（用hypercorn而非FastAPI，因后者依赖pydantic v2的URL验证，而URL验证需要DNS解析）；② Unix Domain Socket（用于与本地Java/Go服务通信，如对接SCADA系统）。

这个架构的代价是牺牲了部分灵活性——比如不能在线热插拔Skill，也不能动态调整RAG检索top_k。但换来的是：

• 单节点部署时间从47分钟（含pip install和模型下载）压缩到3分12秒（纯文件解压+权限设置）；
• Agent进程崩溃恢复时间≤800ms（控制平面watchdog检测到子进程退出，立即fork新实例并restore state from disk）；
• 全链路trace ID贯穿所有日志，无需ELK，用grep -r "trace-abc123" /var/log/agent/即可定位问题。

2.3 MCP Tools的离线适配关键点

MCP（Model Control Protocol）Tools作为新兴的Agent互操作标准，在隔离内网中反而展现出独特优势——它的设计哲学天然排斥中心化服务。但官方实现仍存在三处必须修改：

1. Discovery Mechanism替换：
   原版MCP使用.well-known/mcp端点做服务发现，这依赖HTTP GET。我们改为本地服务注册表文件：/etc/mcp/services.json，格式如下：

   { "document-retriever": { "type": "tool", "endpoint": "unix:///run/mcp/doc_retriever.sock", "capabilities": ["read_pdf", "search_text"] }, "equipment-monitor": { "type": "server", "endpoint": "tcp://127.0.0.1:8081", "capabilities": ["get_vibration_data", "trigger_alert"] } }

   控制平面启动时读取此文件，构建本地服务目录。所有Agent通过mcp_client.get_tool("document-retriever")获取句柄，实际调用转为UDS连接。

2. Tool Schema Validation离线化：
   原版验证依赖JSON Schema Draft 2020-12，需联网下载meta-schema。我们预编译所有常用Schema为Python字节码（.pyc），存于/opt/agent/mcp/schemas/，验证时直接import执行，速度提升3倍。

3. Session Management无状态化：
   公有云版MCP Session依赖Redis存储上下文。我们改用内存+磁盘双备份：Session对象序列化为MessagePack，主存于multiprocessing.Manager.dict()，每5分钟dump到/var/lib/mcp/sessions/。即使Agent进程重启，也能从磁盘恢复最近一次Session状态。

实操心得：MCP Tools最大的价值不是标准化，而是强制你把Skill契约写清楚。在隔离环境下，模糊的API文档会导致整条流水线停摆。我们要求每个Skill提交时，必须附带tool_spec.yaml，包含input/output字段的精确类型、单位、取值范围（如temperature: {type: number, unit: "°C", min: -40, max: 85}）。这比写代码花的时间多一倍，但上线后故障率下降70%。

3. 核心模块实现：从模型加载到技能调度的全链路细节

3.1 离线模型加载与推理优化：不只是“把模型放进来”

把一个7B参数的模型放进内网，不等于它就能跑。我见过太多团队卡在第一步：模型加载失败。原因往往不是显存不够，而是文件系统和Python生态的隐式依赖冲突。

第一步：模型格式选择——为什么坚持用GGUF？
有人推荐用Safetensors，理由是加载快。但在麒麟V10（基于Linux 4.19内核）上，Safetensors的torch.load()会触发mmap系统调用，而某些国产OS内核对大文件mmap有页表限制，导致OSError: Cannot allocate memory。GGUF格式则完全不同：它把权重、metadata、tensor数据分块存储，加载时按需mmap小块（通常64KB），规避了大页表压力。我们实测Qwen2-7B-Int4在24GB显存卡上，GGUF加载耗时1.8秒，Safetensors报错率37%。

第二步：量化策略——Int4不是万能解药
Int4量化看似节省显存，但在隔离内网中可能引入精度灾难。某次电力设备缺陷识别项目，用llama.cpp默认Int4量化，模型对“绝缘子裂纹”的召回率从92%暴跌至61%。根源在于：llama.cpp的Int4量化对激活值（activation）不做校准，而电力图像文本描述中高频词（如“corona discharge”、“tracking”）的embedding向量分布尖锐，Int4的8-bit scale无法覆盖。解决方案：

• 对领域专用词表做per-token quantization scale微调：用1000条标注样本，统计每个token在attention输出层的max/min值，生成custom scale table；
• 在GGUF构建时注入该table，用llama.cpp的--quantize参数指定；
• 最终模型体积仅增加2.3MB，但F1-score回升至89.4%。

第三步：推理引擎定制——砍掉所有“优雅”功能
vLLM的AsyncLLMEngine虽好，但其engine_use_ray、enable_chunked_prefill等特性在单机离线环境全是累赘。我们fork了vLLM 0.6.3，做了三处手术：

• 删除所有Ray相关代码（约12000行），替换为concurrent.futures.ProcessPoolExecutor；
• 关闭PagedAttention，改用flash_attn的fused_attention内核（需预编译CUDA 11.8版本）；
• 将generate接口简化为同步阻塞调用，返回List[CompletionOutput]而非AsyncGenerator。

改造后，单卡吞吐从18 tokens/sec提升至27 tokens/sec，内存峰值下降35%，更重要的是——不再依赖任何外部服务发现机制。

第四步：Prompt Engineering的离线约束
在隔离内网，你无法用LangChain的PromptTemplate动态渲染，因为它的jinja2引擎会尝试加载jinja2/runtime.py，而该文件又依赖pkg_resources查询包元数据——在无网络环境下，pkg_resources会遍历/usr/lib/python3.9/site-packages/所有目录，耗时可达12秒。我们的解法是：

• 所有Prompt预编译为Python函数：

  def build_diagnosis_prompt(fault_code: str, sensor_data: dict) -> str: return f"""你是一名资深电力工程师。设备故障码{fault_code}，传感器读数：{json.dumps(sensor_data)}。请用中文分三点说明可能原因，每点不超过20字。"""

• 编译时用ast.parse()校验语法，部署时直接import调用，毫秒级响应。

注意：不要迷信“通用Prompt模板”。在隔离场景，每个Prompt必须绑定具体Skill。例如，文档摘要Skill的Prompt开头必须写明“你只能处理PDF文件，输入路径格式为/opt/agent/data/raw/{hash}.pdf”，否则Agent可能误将日志文件当作PDF解析，触发崩溃。

3.2 MCP Skill开发规范：让每个技能都成为可插拔的“乐高积木”

在隔离内网，Skill不是代码片段，而是带数字签名的二进制合约。我们制定了严格的开发规范，违反任一条，控制平面拒绝加载。

Skill包结构强制约定：

my_skill/ ├── __init__.py # 必须定义Skill类，继承agent.skill.BaseSkill ├── spec.yaml # MCP Tool Spec，含name/version/capabilities ├── requirements.txt # 仅允许纯Python包，禁止含C扩展（除非提供预编译wheel） ├── assets/ # 静态资源，如OCR模型、正则规则库 └── tests/ # 单元测试，必须覆盖所有capability边界条件

Spec.yaml核心字段详解：

name: "equipment-diagnostic" version: "1.2.0" description: "基于振动频谱分析设备健康状态" capabilities: - name: "analyze_spectrum" input_schema: type: "object" properties: file_path: type: "string" pattern: "^/opt/agent/data/raw/[0-9a-f]{32}\\.csv$" # 严格路径白名单 sampling_rate: type: "number" minimum: 1000 maximum: 10000 output_schema: type: "object" properties: health_score: type: "number" minimum: 0 maximum: 100 fault_type: type: "string" enum: ["bearing", "gear", "motor"]

最关键的Capability Token注入机制：
控制平面启动Skill进程时，会生成一个临时Token文件/tmp/mcp_token_XXXXXX，内容为：

{ "allowed_paths": ["/opt/agent/data/raw/", "/var/log/my_skill/"], "allowed_commands": ["ffmpeg -i", "sox -r 44100"], "memory_limit_mb": 1024, "cpu_quota_percent": 30 }

Skill代码中必须调用agent.security.validate_capability()校验该Token，否则os.getpid()返回0（模拟失败）。这比Linux cgroups更轻量，且100% Python实现。

实操避坑清单：

• ❌ 禁止在Skill中调用subprocess.Popen不加shell=False，否则可能绕过命令白名单；
• ❌ 禁止用open()直接读取绝对路径，必须通过agent.fs.safe_open(file_path)，该函数会校验path是否在allowed_paths内；
• ✅ 推荐用concurrent.futures.ThreadPoolExecutor(max_workers=1)做I/O密集型操作，避免GIL争用；
• ✅ 所有异常必须捕获并转换为MCP标准Error格式，包含error_code（如E_FILE_NOT_FOUND）和retryable: false字段，控制平面据此决定是否重试。

3.3 控制平面核心调度逻辑：没有ETCD，我们怎么“找得到人”？

控制平面是整个系统的“心脏起搏器”，它必须满足：

• 启动时间<500ms；
• 内存占用<15MB；
• 进程崩溃后，能在200ms内被systemd拉起；
• 不依赖任何外部存储。

服务注册与发现的极简实现：
我们放弃所有分布式协调算法，采用文件锁+心跳文件方案：

• 每个Skill启动时，在/run/mcp/skills/下创建以PID命名的文件（如12345）；
• 文件内容为JSON：{"name":"doc_retriever","port":8080,"last_heartbeat":1717023456}；
• 控制平面每200ms扫描该目录，读取所有文件，删除last_heartbeat超过3秒的文件（视为宕机）；
• 用fcntl.flock()对目录加锁，避免并发写入冲突。

实测在200个Skill并发时，扫描耗时稳定在12ms以内。

DAG调度器的确定性执行：
Skill间的依赖关系在部署时已静态解析，运行时不做动态决策。调度器核心逻辑：

def execute_dag(dag_nodes: List[Node], inputs: Dict): # Step 1: 拓扑排序，生成执行序列 sorted_nodes = topological_sort(dag_nodes) # Step 2: 串行执行，每个Node超时强制kill for node in sorted_nodes: try: result = node.run(inputs) inputs.update(result) # 传递输出到后续Node except TimeoutError: # 记录告警，但不停止整个DAG logger.warning(f"Node {node.name} timeout, skipping") continue except Exception as e: # 记录详细traceback，但继续执行 logger.error(f"Node {node.name} failed: {e}") continue return inputs

关键点：不回滚、不事务、不重试。在隔离环境，事务一致性成本远高于数据丢失风险。我们用“最终一致性”理念：故障Node的结果缺失，由下游Skill的容错逻辑补偿（如文档摘要失败，则跳过摘要，直接用原始文本做关键词提取）。

健康检查的务实设计：
不搞复杂的TCP探活，每个Skill必须暴露一个/health端点（HTTP或UDS），返回：

{"status":"ok","uptime_sec":3210,"memory_mb":428,"queue_length":0}

控制平面只检查status=="ok"和queue_length<100。超过阈值则触发kill -USR2 <pid>发送信号，Skill进程收到后主动dump当前状态到/var/log/mcp/debug/并退出。

实操心得：控制平面代码行数必须控制在2000行以内。我曾参与一个项目，控制平面写了8000行，结果因一个time.sleep(0.1)导致整个Agent链路延迟飙升。后来我们把它拆成三个独立进程：scheduler（DAG执行）、watchdog（健康检查）、logger（日志聚合），每个<1000行，问题定位效率提升5倍。

4. 部署与运维实战：从麒麟V10到飞腾D2000的全栈适配

4.1 离线部署包制作：一个tar.gz解决所有依赖

公有云时代，我们习惯docker build。但在隔离内网，“容器”可能是个奢侈品——某军工客户禁用Docker Daemon，只允许systemd管理进程。我们的部署包设计原则：解压即运行，不依赖任何包管理器。

部署包结构：

agent-offline-v2.3.1/ ├── deploy.sh # 主入口脚本，校验环境、解压、设权限、启动 ├── bin/ │ ├── agent-control # 控制平面二进制（PyInstaller打包） │ └── llama-server # GGUF推理服务（llama.cpp编译版） ├── lib/ │ ├── python3.9/ # 完整Python 3.9.18嵌入式环境（含pip） │ └── wheels/ # 所有依赖wheel包（含numpy-1.23.5-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl） ├── models/ │ └── qwen2-7b-int4.gguf # 量化模型 ├── skills/ │ └── equipment-diagnostic/ # Skill包 ├── config/ │ ├── agent.yaml # 全局配置 │ └── mcp-services.json # MCP服务注册表 └── systemd/ └── agent-control.service # systemd单元文件

deploy.sh核心逻辑：

# 1. 校验CPU架构（防止x86_64包装到ARM服务器） if ! grep -q "aarch64" /proc/cpuinfo; then echo "ERROR: This package is for ARM64 only" >&2 exit 1 fi # 2. 校验内核版本（麒麟V10需>=4.19.90） if [ $(uname -r | cut -d'-' -f1 | awk -F. '{print $1*10000+$2*100+$3}') -lt 41990 ]; then echo "ERROR: Kernel too old" >&2 exit 1 fi # 3. 创建符号链接，避免硬编码路径 ln -sf /opt/agent-offline-v2.3.1 /opt/agent # 4. 启动systemd服务 systemctl daemon-reload systemctl enable agent-control.service systemctl start agent-control.service

Wheel包预编译策略：

• 所有C扩展包（如numpy、scipy）必须提供manylinux_2_17或manylinux2014wheel；
• 对国产OS特供包（如龙芯版numpy），从龙芯官网下载源码，用build-wheel.sh脚本交叉编译；
• pip install --find-links ./lib/wheels --no-index --no-deps安装，彻底断绝网络依赖。

4.2 国产化平台适配要点：麒麟、统信、中科方德的真实坑

麒麟V10 SP1（海光CPU）：

• 问题：llama.cpp默认编译启用AVX2指令，但海光CPU的AVX2实现有bug，导致矩阵乘法结果随机错误。
• 解法：编译时加-march=x86-64 -mtune=generic，禁用所有高级指令集；
• 验证：用./llama-bench -m models/qwen2-7b-int4.gguf -p "Hello"输出应稳定一致。

统信UOS V20（飞腾D2000）：

• 问题：Python的multiprocessing在ARM64上默认用fork方式，但飞腾内核对fork后内存映射处理异常，导致子进程segmentation fault。
• 解法：在agent/control.py开头强制设置：

  import multiprocessing multiprocessing.set_start_method('spawn') # 改用spawn方式

• 补充：所有Skill进程必须用spawn启动，否则llama.cpp的GPU context无法继承。

中科方德（申威SW64）：

• 问题：申威CPU无x86指令集，所有Python包需重新编译。llama.cpp官方不支持SW64。
• 解法：用sw64-linux-gcc交叉编译，关键修改：
  • 替换ggml.c中的__builtin_ia32_clflush为__builtin_arm_clflush；
  • 关闭所有CUDA/ROCm相关代码，只保留ggml纯CPU backend；
• 性能妥协：推理速度降为x86的1/3，但稳定性100%。

注意：国产化适配不是“一次编译，到处运行”。我们为每个平台建立独立CI流水线，用真实物理机（非QEMU模拟）跑回归测试。每次模型更新，必须在麒麟、统信、中科方德三台机器上各跑100次/bin/agent-control --test，全部通过才发布。

4.3 日志与监控：没有Prometheus，我们怎么“看见”Agent？

在隔离内网，监控不是锦上添花，而是故障定位的唯一线索。我们放弃所有可视化前端，专注可grep、可归档、可审计的日志设计。

日志分级策略：

• DEBUG：仅记录Skill输入输出（脱敏后），存于/var/log/agent/debug/，滚动保留7天；
• INFO：记录DAG执行轨迹（Node名称、耗时、状态），存于/var/log/agent/info/，永久保留；
• WARNING：记录Capability Token校验失败、超时、内存超限，存于/var/log/agent/warn/，滚动保留30天；
• ERROR：记录进程崩溃、模型加载失败、文件系统错误，存于/var/log/agent/error/，永久保留，并触发logger -t "AGENT_CRASH"写入syslog。

关键日志字段强制规范：
每行日志必须包含：

• trace_id：UUID4，贯穿整个DAG执行；
• skill_name：Skill包名；
• node_id：DAG中Node唯一标识；
• duration_ms：执行耗时（整数毫秒）；
• memory_mb：执行结束时RSS内存（整数MB）；

示例：

2024-05-30T08:23:41.123Z INFO trace_id=abc123 skill_name=equipment-diagnostic node_id=fft_analysis duration_ms=428 memory_mb=382 message="FFT completed, dominant frequency: 1250Hz"

无网络监控的替代方案：

• 用inotifywait监听/var/log/agent/error/目录，发现新文件立即mail -s "AGENT ERROR" admin@localhost < /var/log/agent/error/latest.log；
• 用logrotate配置每日归档，归档文件用gpg --symmetric --cipher-algo AES256加密，密钥由运维人员离线保管；
• 用awk '$4=="ERROR"{print}' /var/log/agent/error/*.log | sort | uniq -c | sort -nr快速统计高频错误。

实操心得：日志不是写给机器看的，是写给半夜被call起来的工程师看的。我们规定：任何ERROR日志必须包含可执行的修复指令。例如：
ERROR trace_id=xyz789 skill_name=doc_retriever ... message="PDF parse failed: invalid xref table. Run 'pdfrepair /opt/agent/data/raw/abc.pdf' to fix"
这样工程师不用查文档，直接复制粘贴命令就能救火。

5. 常见问题与排查技巧：那些让你凌晨三点还在机房的坑

5.1 模型加载失败：90%的问题出在“看不见”的依赖上

现象：agent-control启动后立即退出，journalctl -u agent-control显示ImportError: libcuda.so.1: cannot open shared object file。
真相：不是CUDA驱动没装，而是llama.cpp编译时链接了/usr/local/cuda/lib64/libcuda.so.1，但麒麟V10的NVIDIA驱动库在/opt/nvidia/lib64/。
排查步骤：

1. ldd /opt/agent/bin/llama-server | grep "not found"—— 找出缺失库；
2. find /opt/nvidia/ -name "libcuda.so.*"—— 定位实际路径；
3. sudo ln -sf /opt/nvidia/lib64/libcuda.so.1 /usr/lib64/libcuda.so.1—— 创建软链；
4. sudo ldconfig—— 刷新缓存。

注意：不要用LD_LIBRARY_PATH，它在systemd服务中会被重置。必须用ldconfig。

现象：模型加载成功，但首次推理耗时2分钟，之后正常。
真相：llama.cpp的ggml_cuda_init()在第一次调用时会初始化CUDA context，而某些国产GPU驱动初始化慢。
解法：在控制平面启动后，立即用curl -X POST http://127.0.0.1:8080/health触发一次空推理，预热GPU。

5.2 MCP Skill调用超时：不是网络问题，是文件锁竞争

现象：document-retrieverSkill偶尔超时，日志显示Connection refused，但netstat -tuln | grep 8080确认端口监听正常。
真相：多个Agent进程同时调用该Skill，bind()到同一端口失败，但Skill进程未正确处理Address already in use错误，导致监听socket未关闭。
排查技巧：

• lsof -i :8080查看哪个PID占用了端口；
• strace -p <pid> -e trace=bind,listen,accept观察socket系统调用；
• 发现bind()返回-98 (Address already in use)后，进程未exit，而是继续listen()，导致后续accept()阻塞。

修复：在Skill启动代码中加入：

import socket s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) # 关键！ s.bind(('127.0.0.1', 8080))

5.3 DAG执行中断：你以为是代码bug，其实是磁盘满了

现象：Agent运行几天后，DAG执行突然卡在某个Node，ps aux | grep agent显示进程还在，但/var/log/agent/info/无新日志。
真相：/var/log/agent/debug/目录占满/var分区（默认5GB），agent-control尝试写日志时write()系统调用阻塞，整个事件循环挂起。
速查命令：

df -h /var # 查看磁盘使用率 ls -laSh /var/log/agent/debug/ | head -20 # 找出最大日志文件 journalctl -u agent-control --since "1 hour ago" | grep "No space left" # 检查内核OOM日志

根治方案：

• logrotate配置强制压缩：compresscmd /usr/bin/xz；
• 控制平面启动时，用shutil.disk_usage("/var/log")检查剩余空间，<1GB则自动清理最旧debug日志；
• 所有Skill的临时文件必须写入/tmp/agent-skill-XXXXX/，并在atexit.register()中清理。

5.4 时间不同步导致JWT失效：最隐蔽的“幽灵故障”

现象：Agent运行正常，但某天突然所有MCP调用返回401 Unauthorized，重启无效。
真相：内网NTP服务器宕机，主机时钟漂移超过5分钟，而JWT的exp字段校验失败。
排查铁律：

• 第一步永远执行：timedatectl status—— 查看System clock synchronized: no；
• ntpq -p—— 查看NTP服务器状态；
• `date -d @$(cat /proc/uptime | awk '{print