企业官网建设流程全解析

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

在金融、军工、医疗这类对数据安全要求极高的行业里，开发环境往往被物理隔离成一张独立的内网，没有外网出口，没有公共镜像源，甚至连 pip install 都要走内部私有仓库。这种环境下想跑通一套 AI Agent 工程，难度和公网环境完全不是一个量级。我最近刚在一个完全隔离的内网环境里交付了一套基于 MCP 协议的 AI Agent 系统，从环境准备到最终上线踩了不下二十个坑，这篇文章就把整个工程实战过程完整拆解一遍。

先说清楚这套系统是干什么的：它要在一个没有外网的内网服务器集群上，运行一个能调用内部工具、读取内部知识库、执行自动化任务的 AI Agent。核心依赖包括 MCP 协议做工具调用、Skills 机制做能力扩展、本地部署的大模型做推理引擎。适合谁看？如果你正在内网环境里折腾 AI Agent，或者准备把公网验证过的方案迁移到隔离环境，这篇内容能帮你省掉大量试错时间。

整个工程的核心矛盾就一个：公网生态的便利性在内网完全失效。你不能 pip install，不能 docker pull，不能调 OpenAI API，甚至不能访问 HuggingFace 下载模型权重。所有东西都得提前准备好，通过物理介质或内部通道搬进去。这个约束条件决定了整个工程的设计思路和公网方案有本质区别。

2. 内网 AI Agent 工程的整体架构设计

2.1 为什么选择 MCP + Skills 的组合方案

在内网环境里做 AI Agent，第一个要决策的就是工具调用协议怎么选。公网环境下可选方案很多，Function Calling、ReAct、MCP 都能用，但在内网里选择标准完全变了。

我最终选了 MCP 协议作为核心工具调用层，原因有三点。第一，MCP 是标准化协议，工具定义和 Agent 逻辑解耦，内网环境里工具经常需要替换或增减，解耦设计能大幅降低维护成本。第二，MCP Server 可以独立部署和测试，在内网这种调试困难的环境里，能单独验证每个组件太重要了。第三，Skills 机制天然适合内网场景，每个 Skill 就是一个独立的能力包，可以单独打包、单独搬运、单独部署。

对比一下其他方案：Function Calling 把工具定义硬编码在 Agent 里，改一个工具就要重新部署整个 Agent，内网部署成本太高。ReAct 模式虽然灵活，但推理链路长，在内网有限算力下响应速度堪忧。MCP + Skills 的组合在标准化、可维护性、部署灵活性上都是最优解。

2.2 内网环境的特殊约束与应对策略

内网环境和公网环境的差异，不是简单的"不能上网"，而是一系列连锁约束。我把实际遇到的约束和应对策略整理成了一张表：

这张表里的每一条都是血泪教训。比如依赖获取这一条，我第一次部署时以为把 requirements.txt 搬进去就行，结果发现很多包在安装时还要下载编译依赖，内网直接卡死。后来改成在公网环境用 pip download 把所有 wheel 包和源码包全部下载下来，包括编译依赖，才解决这个问题。

2.3 组件选型与部署拓扑

整套系统的组件选型和部署拓扑是这样的：

• 推理引擎：本地部署的开源大模型，通过量化适配内网 GPU 资源。选型时重点考虑模型对中文的支持能力和工具调用的准确率。
• Agent 框架：自研轻量级 Agent 调度器，核心逻辑不超过 2000 行代码，方便内网调试和修改。
• MCP Server 集群：每个工具一个独立 MCP Server，通过内网 HTTP 通信，支持热插拔。
• Skills 仓库：内部搭建的 Skills 管理服务，支持 Skill 的注册、发现、加载和版本管理。
• 知识库：本地向量数据库，存储内部文档和知识，支持 RAG 检索。
• 日志与监控：完整的链路追踪系统，每个 Agent 调用都有详细日志，方便内网排错。

部署拓扑上，推理引擎和向量数据库部署在高配 GPU 服务器上，MCP Server 集群部署在普通应用服务器上，Agent 调度器作为入口服务部署在网关层。所有组件通过内网 HTTP 通信，不依赖任何外部服务。

3. 内网环境准备与依赖搬运实操

3.1 公网环境依赖打包的完整流程

依赖搬运是整个工程里最繁琐但也最关键的环节。我的做法是在公网环境搭建一个和内网完全一致的"镜像环境"，在这里完成所有依赖的下载和打包。

具体操作流程是这样的。首先在公网机器上创建一个干净的 Python 虚拟环境，版本要和内网服务器完全一致。然后安装所有依赖，但不要直接 pip install，而是用 pip download 把所有包下载到本地目录：

pip download -r requirements.txt -d ./offline_packages --platform manylinux2014_x86_64 --python-version 310 --only-binary=:all:

这个命令的关键参数是 --platform 和 --python-version，必须和内网服务器的环境完全匹配，否则下载的 wheel 包在内网装不上。如果有些包没有预编译的 wheel，就要加上 --no-binary 参数下载源码包，同时确保内网服务器有对应的编译工具链。

下载完成后，还要处理依赖的依赖。pip download 会自动解析依赖树，但有时候会有遗漏。我的做法是下载完成后，在内网环境实际安装一遍，把报错的包再单独下载补充。这个过程可能要反复两三次才能完整。

注意：pip download 下载的包不包含系统级依赖，比如某些 Python 包依赖的 C 库。这些系统级依赖要单独处理，在内网服务器上提前安装好。

3.2 模型权重的搬运与量化处理

模型权重搬运是另一个大工程。内网环境无法访问 HuggingFace，所有模型权重都要提前下载好搬运进去。但原始模型权重动辄几十 GB，搬运成本很高，而且内网 GPU 资源有限，原始精度模型可能跑不起来。

我的做法是分两步走。第一步在公网环境下载原始模型权重，然后用量化工具做量化处理。量化后的模型体积能缩小到原来的四分之一甚至更小，推理速度也能提升两到三倍。常用的量化方案有 GPTQ、AWQ、GGUF 等，选择哪种要看内网推理引擎的支持情况。

第二步是把量化后的模型权重打包搬运。如果模型还是太大，可以进一步做分片处理，搬运到内网后再合并。搬运介质根据内网安全要求选择，可能是加密移动硬盘，也可能是内部文件交换系统。

模型搬运进去后，还要做一次完整性校验，确保文件没有损坏。我一般用 SHA256 校验和，在公网环境生成校验文件，内网环境校验一遍。

3.3 内网制品库的搭建与使用

依赖搬运是一次性的，但后续还会有新的依赖需求。所以在内网搭建一个私有制品库是必要的。我选的是轻量级的方案，支持 PyPI 和 npm 两种格式，部署在内网服务器上。

制品库搭建好后，把所有搬运进来的包上传上去，内网服务器就可以通过制品库安装依赖了。配置方式很简单，修改 pip 的配置文件指向内网制品库地址：

[global] index-url = http://internal-pypi.local/simple/ trusted-host = internal-pypi.local

这样内网服务器 pip install 时就会从内部制品库拉取，不再需要外网。制品库还要做好版本管理，新版本的包上传后要保留旧版本，方便回滚。

4. MCP Server 与 Skills 的内网部署实战

4.1 MCP Server 的本地化实现与部署

MCP Server 是整套系统的工具调用层，每个工具对应一个独立的 MCP Server。在内网环境里，MCP Server 的实现和公网没有本质区别，但部署方式要调整。

我用的 MCP Server 框架支持 stdio 和 HTTP 两种通信方式。内网环境里推荐用 HTTP 方式，因为 stdio 方式要求 Agent 和 MCP Server 在同一台机器上，部署灵活性差。HTTP 方式下，MCP Server 可以独立部署在内网任意服务器上，Agent 通过内网 HTTP 调用。

每个 MCP Server 的部署流程是这样的：先把代码和依赖搬运到内网，然后在目标服务器上创建虚拟环境，从内网制品库安装依赖，最后用 systemd 或者 supervisor 做进程管理。MCP Server 的配置文件里要指定监听地址和端口，以及工具的具体实现参数。

部署完成后要做连通性测试。我一般用 curl 直接调 MCP Server 的接口，确认工具能正常调用。测试通过后再接入 Agent 调度器。

提示：MCP Server 的日志要配置得足够详细，内网排错时日志是唯一的线索。建议每个请求都记录完整的输入输出和耗时。

4.2 Skills 机制的设计与内网适配

Skills 机制是 Agent 能力扩展的核心。每个 Skill 是一个独立的能力包，包含 Skill 的描述、参数定义、执行逻辑。在内网环境里，Skills 的设计要考虑几个特殊点。

第一，Skill 的依赖要自包含。公网环境里 Skill 可以动态安装依赖，内网不行。所以每个 Skill 打包时要把所有依赖都包含进去，或者确保依赖已经在内网制品库里。

第二，Skill 的发现机制要本地化。公网环境可以用在线的 Skill 市场，内网要搭建本地的 Skill 注册中心。我用的方案是一个简单的 HTTP 服务，Skill 启动时向注册中心注册，Agent 从注册中心获取可用 Skill 列表。

第三，Skill 的版本管理要严格。内网环境里 Skill 更新不方便，所以每个 Skill 都要有明确的版本号，Agent 调用时指定版本，避免不兼容问题。

Skill 的开发流程和公网基本一致，但测试环节要加强。我一般会在公网环境完成 Skill 的开发和初步测试，然后搬运到内网做集成测试。集成测试要覆盖 Skill 的所有参数组合和边界情况。

4.3 Agent 调度器的内网部署与配置

Agent 调度器是整套系统的入口，负责接收用户请求、调用推理引擎、调度 MCP Server 和 Skills、返回结果。内网部署时，调度器的配置要针对内网环境做优化。

推理引擎的配置要指定内网地址和端口，以及模型名称和推理参数。MCP Server 的配置要列出所有可用的 Server 地址和工具列表。Skills 的配置要指定注册中心地址和加载策略。

调度器的并发处理能力在内网环境里要特别注意。内网 GPU 资源有限，推理引擎的并发能力有上限，调度器要做好请求排队和限流。我的做法是在调度器里加一个请求队列，根据推理引擎的实际处理能力动态调整并发数。

调度器的日志要记录每个请求的完整链路，包括推理引擎的调用、MCP Server 的调用、Skills 的执行。这样出问题时能快速定位是哪个环节出了问题。

5. 内网 AI Agent 的调试与排错实录

5.1 依赖问题的排查与解决

内网环境里依赖问题是最常见的。我遇到过的典型问题包括：wheel 包平台不匹配、系统级依赖缺失、Python 版本不兼容、依赖冲突等。

排查依赖问题的第一步是看报错信息。pip 的报错信息通常很详细，会告诉你哪个包出了问题、什么原因。如果是 wheel 包平台不匹配，报错会提示 "not a supported wheel on this platform"，这时候要检查下载时的 --platform 参数是否和内网服务器一致。

如果是系统级依赖缺失，报错通常是编译错误或者链接错误。这时候要检查内网服务器是否安装了对应的开发库。比如 psycopg2 需要 libpq-dev，Pillow 需要 libjpeg-dev 等。

依赖冲突的排查比较麻烦。我的做法是用 pip check 命令检查依赖冲突，然后手动调整版本。如果冲突太复杂，就创建一个新的虚拟环境，从头安装依赖，逐个排查。

5.2 模型推理的常见故障与优化

模型推理在内网环境里也会遇到各种问题。最常见的是显存不足，尤其是量化后的模型，如果量化配置不当，显存占用可能比预期高很多。

显存不足的排查方法是看推理时的显存占用。可以用 nvidia-smi 命令实时监控。如果显存占用接近上限，就要调整量化参数或者减小 batch size。我遇到过一种情况是模型加载时显存够用，但推理时显存暴涨，原因是 KV Cache 占用太大。解决办法是限制最大序列长度，或者启用 PagedAttention 等显存优化技术。

推理速度慢是另一个常见问题。内网 GPU 资源有限，如果模型太大或者并发太高，推理速度会明显下降。优化方向包括：进一步量化模型、减少推理精度、优化推理引擎配置、增加 GPU 资源等。

推理结果不准确也可能出现。内网环境里模型是本地部署的，如果模型权重搬运过程中损坏，或者量化过程中精度损失太大，都会导致推理结果异常。排查方法是先用简单的测试用例验证模型基本功能，再逐步增加复杂度。

5.3 MCP 工具调用的链路追踪

MCP 工具调用涉及多个组件，出问题时排查链路比较长。我建立了一套完整的链路追踪机制，每个请求都有唯一的 trace ID，从 Agent 调度器开始，到推理引擎、MCP Server、Skills，每个环节都记录 trace ID 和耗时。

排查工具调用问题时，先看 Agent 调度器的日志，确认请求是否正常发出。然后看 MCP Server 的日志，确认请求是否收到、处理是否正常。如果 MCP Server 处理正常但 Agent 没收到结果，就要检查网络通信。

常见的工具调用问题包括：MCP Server 未启动、端口不通、工具参数不匹配、工具执行超时等。我整理了一张常见问题速查表：

5.4 内网环境特有的坑与规避方法

内网环境有一些特有的坑，公网环境里根本遇不到。我踩过的几个典型的坑：

第一个是时间同步问题。内网服务器可能没有配置 NTP，各服务器时间不一致，导致日志时间错乱，排查问题时对不上。解决办法是在内网搭建 NTP 服务，所有服务器统一时间。

第二个是 DNS 解析问题。内网可能没有 DNS 服务，或者 DNS 配置不完整，导致服务之间用域名访问不通。解决办法是用 IP 直连，或者在 /etc/hosts 里配置静态解析。

第三个是防火墙问题。内网服务器可能有防火墙规则，某些端口默认不通。部署新服务时要提前确认端口是否开放，或者申请开通。

第四个是磁盘空间问题。内网服务器磁盘空间可能有限，模型权重和日志文件很容易把磁盘占满。要提前规划磁盘空间，日志要做轮转和清理。

6. 工程实战中的经验总结与扩展思考

6.1 内网 AI Agent 工程的checklist

经过这个项目的实战，我整理了一份内网 AI Agent 工程的 checklist，每次部署新环境时都对照检查：

• 公网环境依赖是否完整打包，包括系统级依赖
• 模型权重是否完成量化，体积和精度是否平衡
• 内网制品库是否搭建完成，依赖是否能正常安装
• MCP Server 是否全部部署并注册，连通性是否验证
• Skills 是否全部加载，版本是否匹配
• Agent 调度器配置是否正确，并发和限流是否合理
• 日志系统是否完整，链路追踪是否可用
• 时间同步、DNS 解析、防火墙规则是否配置
• 磁盘空间是否充足，日志轮转是否配置
• 备份和回滚方案是否准备

这份 checklist 看起来简单，但每一条背后都是踩过的坑。比如系统级依赖这一条，我第一次部署时就是漏了 libpq-dev，导致 psycopg2 装不上，排查了半天。

6.2 性能优化的几个关键点

内网环境资源有限，性能优化尤为重要。我总结的几个关键优化点：

推理引擎的批处理优化。内网 GPU 资源有限，单条推理效率低，要尽量做批处理。但批处理会增加延迟，要根据实际场景平衡。我的做法是设置一个批处理窗口，窗口内的请求合并处理，窗口外的请求单独处理。

MCP Server 的连接池优化。MCP Server 和 Agent 之间的 HTTP 连接要复用，避免频繁建立连接。我用的 HTTP 客户端支持连接池，配置好最大连接数和空闲超时即可。

Skills 的缓存优化。有些 Skill 的执行结果可以缓存，避免重复计算。我在 Skill 框架里加了缓存层，支持内存缓存和 Redis 缓存两种方式。

Agent 调度器的异步优化。调度器要支持异步处理，避免阻塞。我用的异步框架，推理引擎调用、MCP Server 调用、Skills 执行都是异步的，整体吞吐量提升明显。

6.3 后续扩展方向

这套系统上线后运行稳定，后续还有几个扩展方向可以考虑。

第一个方向是增加更多 Skills。目前系统里的 Skills 覆盖了内部工具调用和知识库检索，后续可以增加数据分析、报表生成、自动化流程等 Skills，扩展 Agent 的能力边界。

第二个方向是优化推理引擎。目前用的是量化后的开源模型，后续可以尝试模型蒸馏、模型剪枝等技术，进一步降低模型体积和推理成本。

第三个方向是完善监控告警。目前日志系统比较完善，但监控告警还不够。后续可以接入内网的监控系统，对 Agent 的调用量、成功率、响应时间等指标做实时监控和告警。

第四个方向是支持多租户。目前系统是单租户的，后续可以改造成多租户架构，支持不同部门或团队独立使用，资源隔离和权限控制要做好。

我在这个项目里最大的体会是：内网环境做 AI Agent，技术难度不是最大的挑战，工程化能力才是。公网环境里很多理所当然的事情，在内网里都要重新设计。依赖管理、模型部署、工具调用、调试排错，每个环节都要考虑内网的特殊性。但反过来，内网环境也逼着你把工程做得更扎实，因为任何偷懒都会在部署时暴露出来。这套系统上线后，我又在另一个内网环境里复制了一遍，第二次只用了第一次三分之一的时间，因为 checklist 和制品库都复用了。如果你也在内网环境里折腾 AI Agent，希望这篇内容能帮你少走一些弯路。