企业官网建设流程全解析

1. 隔离内网下 AI Agent 工程实战：从零搭建到落地的完整复盘

隔离内网这四个字，做过企业级交付的兄弟应该都懂——不是"网络不太好"，而是物理隔离、协议受限、外网依赖全部切断。你手里只有一台能连内网的跳板机，一个离线的包管理源，以及一堆需要"想办法"搞进去的依赖。在这种环境下搞 AI Agent 工程，跟在公网环境里完全是两码事。公网环境下你pip install一把梭，docker pull随便拉，MCP 服务想连哪个连哪个；到了内网，每一个依赖包、每一个模型权重、每一个 MCP Server 的二进制文件，都得提前规划好怎么进去、怎么部署、怎么在断网状态下跑起来。

这篇文章要聊的，就是我在几个隔离内网项目里踩过的坑和总结出来的工程方法。核心关键词：AI Agent、MCP、Skills、内网、工程实战。适合谁看？如果你正在做企业内网的 AI Agent 落地，或者你所在的环境有网络隔离要求，又或者你单纯想搞清楚"在内网里怎么把 Agent 跑起来"，那这篇内容应该能帮你省掉不少试错时间。

先说清楚一个前提：内网环境下的 AI Agent 工程，核心矛盾不是"模型够不够聪明"，而是"工程链路能不能通"。模型可以用内网部署的开源模型，也可以用提前导出的推理服务，但 Agent 的编排层、工具调用层、状态管理层，这些才是真正卡脖子的地方。下面我按实际项目的推进顺序，把整个工程拆开来讲。

2. 内网 AI Agent 的整体架构设计与选型逻辑

2.1 为什么不能照搬公网那套架构

公网环境下搭 AI Agent，大多数人习惯的套路是：LangChain 或 LangGraph 做编排，OpenAI 或 Claude 做推理，MCP 协议做工具调用，再配一堆 SaaS 化的可观测性工具。这套东西在内网里基本跑不通，原因有三：

第一，外部 API 全部不可达。你没法调用任何公网的模型推理接口，所有推理必须在内网完成。这意味着你要么在内网部署开源模型（比如 Qwen、DeepSeek 的蒸馏版本），要么用提前申请好的内网推理服务。

第二，依赖安装链路断裂。内网的 pip 源、npm 源、Docker Registry 通常都是私有化的，很多包不一定有。你需要的 Python 依赖、Node 依赖、系统级库，都得提前确认私有源里有没有，没有的话要走离线导入流程。

第三，MCP Server 的部署方式完全不同。公网环境下 MCP Server 很多是远程服务，直接配个 URL 就能用。内网里你必须把 MCP Server 本地化部署，而且要考虑它依赖的外部资源怎么解决。

所以内网 AI Agent 的架构设计，核心思路是：全链路本地化、依赖提前化、通信内网化。

2.2 推荐的分层架构

我在实际项目里用的架构大致分四层：

这个分层的好处是每一层都可以独立验证。推理层通了再搞编排层，编排层通了再接工具层，出问题的时候排查范围可控。我见过有人一上来就把四层全串起来调，结果一个环节不通，整条链路都卡住，排查起来非常痛苦。

2.3 模型选型的现实考量

内网环境下选模型，不要追求"最强"，要追求"最稳"。我一般按这几个维度来筛：

• 显存占用：内网 GPU 资源通常紧张，7B 到 14B 的模型是甜点区，量化后能在单卡上跑起来
• 推理框架兼容性：vLLM、SGLang 这些框架在内网的部署难度要提前评估
• 工具调用能力：Agent 场景下模型必须支持 Function Calling 或类似的工具调用格式，不然 MCP 接不上
• 中文能力：如果业务场景是中文的，模型的中文指令遵循能力要重点测

实测下来，Qwen 系列和 DeepSeek 系列在内网部署的性价比比较高，工具调用的稳定性也够用。具体选哪个版本，取决于你的显存和延迟要求。

3. MCP 与 Skills 在内网环境下的落地细节

3.1 MCP Server 的本地化部署

MCP 协议本身是标准化的，问题在于 MCP Server 的实现。公网上很多 MCP Server 是 Node 写的，通过 npx 直接跑，内网里 npx 拉不到包就废了。我的做法是：

1. 提前在公网环境把 MCP Server 的依赖全部装好，包括 node_modules 或 Python 的 site-packages
2. 把整个目录打包，通过内网允许的文件传输方式导入
3. 在内网机器上直接跑本地入口文件，不走 npx 或 pip 的在线安装

举个例子，一个典型的文件系统 MCP Server，公网上的用法是npx -y @modelcontextprotocol/server-filesystem /path。内网里你要做的是：

# 公网环境准备 mkdir mcp-fs-server && cd mcp-fs-server npm init -y npm install @modelcontextprotocol/server-filesystem # 打包整个目录 tar czf mcp-fs-server.tar.gz . # 内网环境部署 tar xzf mcp-fs-server.tar.gz -C /opt/mcp/ # 直接跑本地入口 node /opt/mcp/mcp-fs-server/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js /data

这样就不依赖任何在线拉取。其他 MCP Server 同理，核心思路就是"公网准备、离线打包、内网直跑"。

3.2 Skills 的工程化管理

Skills 这个概念在 Agent 工程里越来越重要，本质上是把 Agent 的能力模块化、可配置化。内网环境下管理 Skills，我建议用一套统一的目录规范：

/opt/agent-skills/ ├── registry.json # Skills 注册表 ├── file-ops/ # 文件操作类 │ ├── skill.yaml │ └── handler.py ├── db-query/ # 数据库查询类 │ ├── skill.yaml │ └── handler.py └── http-call/ # 内网 HTTP 调用类 ├── skill.yaml └── handler.py

registry.json里记录每个 Skill 的元信息，Agent 启动时加载这个注册表，运行时按需调用。这样做的好处是新增 Skill 不需要改 Agent 核心代码，只需要在目录里加文件、更新注册表就行。

skill.yaml的典型结构：

name: file-ops description: 内网文件读写操作 version: 1.0.0 entry: handler.py functions: - name: read_file description: 读取指定路径的文件内容 parameters: path: type: string required: true - name: write_file description: 写入内容到指定路径 parameters: path: type: string required: true content: type: string required: true

这套规范看起来简单，但实际项目里非常管用。尤其是当你有几十个 Skill 的时候，没有统一规范会乱成一锅粥。

3.3 MCP 和 Skills 的关系怎么理

很多人搞不清楚 MCP 和 Skills 的区别。我的理解是：MCP 是通信协议，Skills 是能力封装。MCP 解决的是"Agent 怎么和外部工具通信"的问题，Skills 解决的是"Agent 有哪些能力、怎么组织这些能力"的问题。

在实际工程里，两者可以结合使用：用 MCP 协议对接外部的工具服务，用 Skills 管理 Agent 内部的能力模块。也可以只用其中一种，取决于你的架构复杂度。内网环境下，如果工具服务不多，直接用 Skills 管理就够了；如果工具服务很多、需要标准化对接，那就上 MCP。

注意：内网环境下 MCP Server 的通信方式优先选 stdio，比 HTTP 更稳定，不依赖端口和网络配置。如果必须用 HTTP，确保内网防火墙策略提前开通。

4. 内网 Agent 工程的实操流程与关键环节

4.1 环境准备：离线依赖的完整清单

内网部署最耗时的环节就是环境准备。我的经验是，提前列一份完整的依赖清单，逐项确认内网私有源里有没有。清单至少包含：

• Python 依赖：Agent 框架、模型推理客户端、数据库驱动、HTTP 库等
• Node 依赖：如果 MCP Server 是 Node 写的，node_modules 要完整打包
• 系统级依赖：CUDA 驱动、cuDNN、特定版本的 glibc 等
• 模型权重：提前下载好，通过内网允许的方式导入
• 配置文件：所有服务的配置文件模板，提前准备好

我一般会写一个check_deps.sh脚本，在内网机器上跑一遍，逐项检查依赖是否就位：

#!/bin/bash echo "=== Python 依赖检查 ===" python3 -c "import langgraph; print('langgraph OK')" 2>/dev/null || echo "langgraph MISSING" python3 -c "import mcp; print('mcp OK')" 2>/dev/null || echo "mcp MISSING" echo "=== Node 依赖检查 ===" node -e "require('@modelcontextprotocol/sdk'); console.log('mcp-sdk OK')" 2>/dev/null || echo "mcp-sdk MISSING" echo "=== 模型服务检查 ===" curl -s http://localhost:8000/v1/models > /dev/null && echo "model service OK" || echo "model service DOWN"

这个脚本看起来简单，但能帮你快速定位环境问题，避免部署到一半才发现缺东西。

4.2 Agent 编排层的实现

编排层我用 LangGraph 比较多，原因是它的状态管理比较清晰，适合内网这种需要精细控制的场景。一个典型的 Agent 编排流程：

from langgraph.graph import StateGraph, END from typing import TypedDict, Annotated import operator class AgentState(TypedDict): messages: Annotated[list, operator.add] next_action: str def planner_node(state: AgentState): # 调用内网模型服务做规划 response = call_internal_model(state["messages"]) return {"next_action": response.action, "messages": [response]} def executor_node(state: AgentState): # 执行 Skill 或 MCP 调用 result = execute_skill(state["next_action"]) return {"messages": [result]} def should_continue(state: AgentState): if state["next_action"] == "finish": return END return "executor" graph = StateGraph(AgentState) graph.add_node("planner", planner_node) graph.add_node("executor", executor_node) graph.set_entry_point("planner") graph.add_conditional_edges("planner", should_continue) graph.add_edge("executor", "planner") agent = graph.compile()

这段代码的关键点在于：call_internal_model走的是内网推理服务，execute_skill走的是本地 Skills 目录。整个链路不依赖任何外部网络。

4.3 并发处理的实际方案

内网 Agent 的并发问题，跟公网不太一样。公网环境下你可以靠弹性扩容来解决，内网里资源是固定的，只能靠工程手段来扛。我的做法是：

• 推理层做请求队列：模型推理服务前面加一层队列，控制并发数，避免 GPU OOM
• Agent 层做异步编排：用 asyncio 或线程池处理多个 Agent 实例的并发请求
• 工具层做连接池：数据库查询、HTTP 调用这些操作，用连接池复用资源

实测下来，单张 A100 跑 7B 模型，推理并发控制在 4 到 8 之间比较稳。超过这个数，延迟会明显上升。Agent 层的并发可以更高，因为大部分时间在等推理结果，用异步就能扛住。

4.4 日志与可观测性

内网环境下没有公网那套 SaaS 化的可观测性工具，得自己搭。我的方案是：

• 结构化日志：所有 Agent 操作输出 JSON 格式日志，方便后续分析
• 本地日志聚合：用 Loki 或简单的文件聚合方案，把多台机器的日志收集到一起
• 关键指标埋点：推理延迟、工具调用成功率、Agent 任务完成率，这些指标必须埋

import logging import json from datetime import datetime def log_agent_event(event_type, payload): log_entry = { "timestamp": datetime.utcnow().isoformat(), "event_type": event_type, "payload": payload } logging.info(json.dumps(log_entry, ensure_ascii=False))

这套东西看起来朴素，但实际排查问题的时候非常管用。尤其是 Agent 这种多步骤、多工具调用的场景，没有详细日志根本没法定位问题。

5. 内网 Agent 工程的常见问题与排查实录

5.1 依赖缺失类问题

这是内网部署最高频的问题。典型表现是：Agent 启动时报ModuleNotFoundError，或者 MCP Server 跑不起来报Cannot find module。

排查思路：

1. 先确认内网私有源里有没有这个包
2. 没有的话，在公网环境下载 whl 或 tgz 文件，离线导入
3. 导入后确认版本兼容性，尤其是 Python 包的依赖树

我踩过的一个坑：某个 MCP Server 依赖的 Node 包版本和 Agent 框架依赖的版本冲突，导致两边都跑不起来。最后的解决方案是用独立的 Node 环境隔离，MCP Server 用自己的 node_modules，Agent 框架用另一套。

5.2 模型服务连接问题

内网模型服务跑起来了，但 Agent 连不上，常见原因有：

提示：内网模型服务的地址建议用环境变量注入，不要硬编码在代码里。不同环境切换的时候会方便很多。

5.3 Agent 任务执行异常

Agent 跑着跑着卡住或者报错，这类问题最难排查。我的经验是分三步走：

第一步，看日志。Agent 的每一步操作都要有日志，从 planner 到 executor 到最终输出，每一步的输入输出都记下来。

第二步，复现问题。把出问题的输入单独拿出来，手动跑一遍 Agent 流程，看在哪一步卡住。

第三步，隔离验证。如果是工具调用的问题，单独测那个 Skill 或 MCP Server；如果是推理的问题，单独测模型服务。

我遇到过一个典型案例：Agent 在执行文件操作 Skill 时一直超时，日志显示 Skill 调用发出去了但没返回。最后发现是 Skill 里的文件路径写的是相对路径，Agent 的工作目录和预期不一致，导致文件找不到一直重试。改成绝对路径后问题解决。

5.4 性能瓶颈定位

内网 Agent 的性能瓶颈通常出现在三个地方：推理、工具调用、状态管理。

• 推理瓶颈：表现为 Agent 响应慢，但工具调用正常。解决方法是优化模型推理参数，或者换更小的模型
• 工具调用瓶颈：表现为某个 Skill 或 MCP 调用特别慢。解决方法是优化工具实现，或者加缓存
• 状态管理瓶颈：表现为 Agent 步骤多了之后越来越慢。解决方法是优化状态存储，避免每次全量读写

我一般会用 cProfile 或 py-spy 做性能分析，定位到具体的热点函数再优化。

6. 几个实战中总结的避坑经验

6.1 离线包管理要建立版本台账

内网环境最怕的就是"这个包是谁导进来的、什么版本、什么时候导的"没人知道。我的做法是维护一个offline_packages.md，记录每个离线包的名称、版本、导入时间、导入人、用途。看起来是个笨办法，但实际项目里能省掉大量沟通成本。

6.2 MCP Server 优先选 stdio 模式

内网环境下，MCP Server 的通信方式优先选 stdio。原因是 stdio 不依赖网络配置，不需要开端口，不需要考虑防火墙策略。HTTP 模式虽然更灵活，但内网里网络策略往往很严格，开通端口要走流程，能省则省。

6.3 Skills 的粒度要适中

Skills 拆得太细，Agent 编排会变得很复杂；拆得太粗，复用性又差。我的经验是：一个 Skill 对应一个明确的业务能力，比如"查询数据库"是一个 Skill，"发送内网消息"是一个 Skill。不要把多个不相关的操作塞进一个 Skill 里。

6.4 提前做压力测试

内网环境的资源是固定的，上线前一定要做压力测试。我一般会模拟 10 到 50 个并发 Agent 任务，观察推理延迟、工具调用成功率、内存占用这些指标。测试中发现的问题，比上线后发现的成本低得多。

6.5 配置文件与代码分离

所有环境相关的配置——模型服务地址、数据库连接、MCP Server 路径——全部放到配置文件或环境变量里，不要硬编码。内网环境经常需要在不同机器之间迁移，配置分离能省掉大量改代码的时间。

# config.yaml model: base_url: "http://internal-model:8000/v1" api_key: "${MODEL_API_KEY}" model_name: "qwen-7b-chat" mcp: servers: - name: "filesystem" transport: "stdio" command: "node" args: ["/opt/mcp/filesystem/dist/index.js", "/data"] skills: registry_path: "/opt/agent-skills/registry.json"

这套配置结构在实际项目里用了好几个版本，基本没怎么大改过，说明抽象层次是合理的。

6.6 建立内网专属的调试工具链

公网环境下调试 Agent 有很多现成工具，内网里得自己搭。我一般会准备几个小工具：

• 模型服务健康检查脚本：定时 ping 模型服务，确认可用性
• MCP Server 连通性测试工具：单独测试每个 MCP Server 是否能正常调用
• Skill 单元测试框架：每个 Skill 写独立的测试用例，不依赖 Agent 整体运行
• Agent 回放工具：把历史任务的输入输出录下来，出问题时可以回放复现

这些工具单个看起来都不复杂，但组合起来能大幅提升排查效率。尤其是 Agent 回放工具，在排查偶发问题时特别有用。

6.7 关于内网穿透的说明

有些场景下需要从外部访问内网服务做调试，这时候会用到内网穿透工具。但要注意，内网穿透的使用必须严格遵守所在组织的安全规范，不能随意开通通道。我的建议是：优先用内网跳板机做调试，确实需要穿透的，走正规审批流程，并且只开放必要的端口和服务。安全合规永远是第一位的，不要为了图方便留下隐患。

6.8 模型输出的稳定性处理

内网部署的开源模型，输出稳定性通常不如公网的商业模型。Agent 场景下，模型输出的格式错误会导致整个流程失败。我的处理方式是：

• 输出格式校验：模型返回后先校验格式，不符合的重试
• 重试机制：设置合理的重试次数和退避策略
• 降级方案：重试多次仍失败的，走降级逻辑，比如返回默认值或转人工

import time from tenacity import retry, stop_after_attempt, wait_exponential @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=1, max=10)) def call_model_with_retry(messages): response = call_internal_model(messages) if not validate_response_format(response): raise ValueError("Invalid response format") return response

这套重试机制在实际项目里救过很多次场。开源模型的输出偶尔会抽风，有了重试和校验，整体稳定性会好很多。

6.9 关于 Agent 并发扛量的实际数据

回到热词里提到的"AI Agent 怎么扛并发"，我分享一组实测数据供参考。在单张 A100 80G 上部署 7B 量化模型，配置如下：

• 推理框架：vLLM，tensor_parallel_size=1
• 最大并发请求数：8
• 平均单次推理延迟：1.2s
• Agent 层并发：32（异步等待推理结果）
• 工具调用并发：16（连接池大小）

在这个配置下，系统能稳定处理约 6 到 8 QPS 的 Agent 任务。超过这个量，推理延迟会明显上升，任务完成时间变长。如果要扛更高的并发，要么加 GPU，要么换更小的模型，要么优化 Agent 编排逻辑减少推理调用次数。

这个数据不是绝对的，不同模型、不同任务复杂度下会有差异。但大致的量级可以参考，帮助你在内网资源规划时有个底。

6.10 内网 Agent 项目的交付清单

最后分享一份我常用的交付清单，确保项目移交时不会漏东西：

• Agent 核心代码及依赖清单
• 模型权重及推理服务部署文档
• MCP Server 离线包及部署脚本
• Skills 目录及注册表
• 配置文件模板及环境变量说明
• 数据库初始化脚本
• 日志采集配置
• 健康检查脚本
• 压力测试报告
• 常见问题排查手册

这份清单看起来繁琐，但内网项目移交时，少任何一项都可能导致接手的人卡住。我吃过亏，后来每次都按这个清单逐项确认，省了很多事。

内网 AI Agent 工程这件事，技术难度其实不算特别高，难的是工程细节的把控。每一个依赖、每一个配置、每一个通信链路，都需要提前想到、提前验证。公网环境下可以"先跑起来再说"，内网环境下必须"想清楚了再动手"。希望这些经验能帮到正在做类似项目的兄弟，少踩几个坑，早点把 Agent 在内网里跑起来。