企业官网建设流程全解析

1. 项目缘起与整体设计思路

1.1 为什么要在隔离内网里折腾 AI Agent

先说清楚这个项目的背景。我所在的团队负责一套企业级业务系统的研发与运维，开发环境是完全物理隔离的内网——没有外网出口，没有公网 DNS，连 pip install 都得走内部镜像源。这种环境下想用上 AI Agent 来提效，听起来像是天方夜谭，但实际做下来，路子是通的。

核心痛点很明确：内网里有大量重复性的工程任务，比如代码审查、日志分析、接口文档生成、数据库表结构比对、工单自动分类。这些活儿人来做费时费力，但交给 AI Agent 就很合适。问题在于，主流 AI Agent 方案几乎都默认你有公网访问能力——模型 API 要联网调，MCP 服务要联网拉，Skills 市场要联网装。隔离内网把这些路全堵死了。

所以这个项目的核心目标就一句话：在完全隔离的内网环境中，搭建一套可运行、可扩展、可维护的 AI Agent 工程体系。涉及的关键技术点包括 AI Agent 架构选型、MCP 协议的内网适配、Skills 的离线部署、模型推理服务的本地化，以及整套工程的并发扛压能力。

适合谁来参考？三类人：一是内网开发环境的工程师，想引入 AI 能力但被网络限制卡住的；二是对 AI Agent 工程化落地感兴趣，想了解 MCP、Skills 这些概念怎么在实际项目里用的；三是需要在内网部署 AI 服务的运维同学，关心部署方案和并发性能的。

1.2 整体架构怎么定：三层解耦

内网环境做 AI Agent，最大的约束不是技术本身，而是资源获取的物理隔离。你不能像在公网那样随手 pip install 一个包、随手调一个 API。所有依赖必须提前准备好，所有服务必须本地化部署。基于这个约束，我把架构拆成三层：

• 推理层：本地部署的大模型推理服务，负责所有自然语言理解和生成。选型上考虑过几种方案，最终用的是量化后的开源模型配合本地推理框架，单卡就能跑起来，延迟可控。
• 编排层：AI Agent 的核心逻辑层，负责任务拆解、工具调用、上下文管理。这一层用 MCP 协议做工具标准化接入，用 Skills 做能力扩展。
• 接入层：面向最终用户的交互界面，包括 Web 控制台、CLI 工具、以及和企业内部系统的 API 对接。

三层之间通过内网 HTTP 服务通信，完全不走外网。这个解耦设计的好处是，任何一层出问题都不影响其他层，而且每层都可以独立扩容。

1.3 方案选型的几个关键取舍

选型阶段踩了不少坑，这里把关键决策点列出来，方便你参考。

推理框架的选择：试过几种本地推理方案，最后选定的方案主要看三个指标——首 token 延迟、吞吐量、显存占用。实测下来，量化到 4bit 的模型在单张消费级显卡上能跑到可用的程度，首 token 延迟控制在 500ms 以内，并发 8 路的时候吞吐还能接受。

Agent 编排框架的选择：没有直接用某个现成的 Agent 框架，而是基于 MCP 协议自己搭了一套轻量编排层。原因很简单——现成框架大多假设你有公网，内部依赖了一堆在线服务，在内网里跑不起来。自己搭虽然工作量大，但可控性强，出了问题能定位。

Skills 的管理方式：Skills 本质上是给 Agent 用的“技能包”，可以是提示词模板、工具封装、或者工作流定义。内网环境下没法从在线市场拉取，所以建了一个内部 Skills 仓库，用 Git 管理，版本化发布。

提示：内网环境做技术选型，第一原则是“依赖可离线获取”。任何需要运行时联网的组件，不管多好用，直接排除。

2. 核心细节解析与实操要点

2.1 MCP 协议在内网环境怎么落地

MCP 是 Model Context Protocol 的缩写，简单理解就是一套让 AI 模型和外部工具对话的标准协议。你可以把它想象成 USB 接口——不管什么设备，只要符合 USB 标准就能插上用。MCP 做的就是类似的事，让 Agent 能标准化地调用各种工具。

在内网环境里落地 MCP，核心要解决三个问题：

第一个问题是 MCP Server 的部署。公网环境下，很多 MCP Server 是托管服务，直接连就行。内网里必须自己部署。我的做法是把常用的 MCP Server 全部容器化，用内部镜像仓库管理。每个 Server 就是一个独立的容器，通过内网服务发现互相通信。

第二个问题是工具注册与发现。MCP 协议本身有工具发现机制，但内网环境没有中心化的注册中心。我的方案是建一个轻量的服务注册表，用配置文件维护所有 MCP Server 的地址和能力描述。Agent 启动时加载这个配置，就知道有哪些工具可用。

第三个问题是通信安全。内网虽然物理隔离，但内部服务之间的通信还是要做基本的认证和鉴权。我用的是内网自签证书加 Token 认证的方式，每个 MCP Server 有独立的访问凭证。

具体配置上，一个典型的 MCP Server 配置长这样：

mcp_servers: - name: code-review endpoint: http://mcp-code-review.internal:8080 token: ${CODE_REVIEW_TOKEN} capabilities: - review_pull_request - analyze_code_quality - name: db-tools endpoint: http://mcp-db.internal:8081 token: ${DB_TOOLS_TOKEN} capabilities: - query_schema - compare_tables

这个配置文件放在 Agent 编排层的配置目录里，启动时加载。新增工具只需要改配置加重启，不用改代码。

2.2 Skills 的离线部署与管理

Skills 这个概念最近很火，但很多人理解得比较模糊。我的理解是：Skills 是 Agent 的能力扩展单元，一个 Skill 封装了一类特定任务的完整处理逻辑。比如“代码审查 Skill”封装了从拉取 diff 到生成审查意见的全流程；“日志分析 Skill”封装了日志解析、异常检测、根因分析的完整链路。

内网环境部署 Skills，关键在离线管理。我的做法是：

• 建立内部 Skills 仓库：用 Git 管理所有 Skill 的定义文件，每个 Skill 一个目录，包含提示词模板、工具依赖声明、参数 schema、测试用例。
• 版本化发布：Skill 的每次变更都走 Git 流程，打 tag 发布。Agent 加载 Skill 时指定版本号，保证可复现。
• 依赖检查：Skill 声明它依赖哪些 MCP 工具，加载时自动检查这些工具是否可用，不可用就报错而不是静默失败。

一个 Skill 的定义文件示例：

name: code-review version: 1.2.0 description: 对代码变更进行自动化审查 dependencies: mcp_tools: - code-review/review_pull_request - code-review/analyze_code_quality prompt_template: | 你是一个资深代码审查员。请对以下代码变更进行审查： {diff_content} 重点关注： 1. 潜在的 bug 和边界条件 2. 性能问题 3. 代码风格一致性 4. 安全隐患 parameters: - name: diff_content type: string required: true - name: language type: string default: auto

这个定义文件放在 Git 仓库里，Agent 启动时从本地克隆的仓库加载。更新 Skill 就是 git pull 加重启，非常简单。

2.3 本地模型推理服务的性能调优

内网环境用不了在线模型 API，必须本地部署推理服务。这一步是整个项目里最吃资源的环节，也是性能瓶颈所在。

模型选型上，我选的是参数量在 7B 到 14B 之间的开源模型，量化到 4bit 后部署。为什么不上更大的模型？因为内网服务器的显卡资源有限，大模型跑不动，而且 Agent 场景对模型能力的要求没有通用对话那么高，中等规模的模型配合好的提示词工程，效果够用。

推理框架的调优主要围绕几个参数：

这些参数不是拍脑袋定的，是压测出来的。压测方法很简单：用一组典型的 Agent 请求做负载，逐步增加并发数，观察延迟和吞吐的变化曲线，找到拐点。

注意：本地推理服务的显存管理很关键。如果 Agent 编排层和推理层部署在同一台机器上，要预留足够的显存给编排层，否则会出现 OOM。我的做法是推理层独占一张卡，编排层跑在 CPU 上。

2.4 并发扛压的设计要点

“AI Agent 怎么扛并发”是个高频问题。内网环境的并发压力主要来自两个方面：一是多个用户同时使用 Agent，二是单个 Agent 任务内部可能并发调用多个工具。

我的并发设计分三层：

请求队列层：所有进入 Agent 的请求先入队，用优先级队列管理。高优先级的任务（比如线上故障排查）优先处理，低优先级的任务（比如批量文档生成）排队等待。队列长度可配置，满了就拒绝新请求，避免雪崩。

推理批处理层：推理服务支持动态批处理，多个请求的输入拼成一个 batch 一起推理，显著提升 GPU 利用率。批处理的大小和时间窗口可配置，需要在延迟和吞吐之间找平衡。

工具调用并发层：Agent 在执行任务时可能需要调用多个 MCP 工具，这些调用可以并发执行。我用的是异步 IO 加信号量控制并发度，避免同时打开太多连接把内网服务打挂。

实测下来，这套设计在单卡环境下能稳定支撑 20 路左右的并发请求，平均响应时间在 2 秒以内。对于内网内部使用的场景，这个性能足够了。

3. 实操过程与核心环节实现

3.1 环境准备：从零搭建内网 AI 基础设施

环境准备是整个项目最繁琐的部分，因为内网环境什么都得自己来。我把步骤拆解成几个阶段，按顺序执行。

第一阶段：硬件与系统准备。需要一台带 GPU 的服务器作为推理节点，配置建议至少 24GB 显存。操作系统用主流的 Linux 发行版，内核版本不要太老。系统装好后，先配好内网 IP、DNS、NTP 这些基础服务，确保内网通信正常。

第二阶段：依赖离线化。这是内网部署的核心难点。所有需要的软件包、Python 库、Docker 镜像，都必须提前在外网环境下载好，然后通过安全的方式导入内网。我的做法是：

1. 在外网环境用 pip download 把所有 Python 依赖下载到本地目录
2. 用 docker save 把需要的镜像导出成 tar 文件
3. 通过内部的文件摆渡流程把文件导入内网
4. 在内网环境用 pip install --no-index --find-links 安装 Python 依赖
5. 用 docker load 导入镜像

这个过程听起来简单，但实际操作中坑很多。最常见的问题是依赖版本冲突——外网下载时用的 Python 版本和内网不一致，导致装不上。解决办法是在外网环境用和内网完全一致的 Python 版本和操作系统做依赖下载。

第三阶段：推理服务部署。把量化好的模型文件放到推理节点上，启动推理服务。模型文件通常有几个 GB 到十几个 GB，传输是个问题。我的做法是用内网的文件共享服务传输，或者直接拷贝到移动存储再导入。

推理服务启动后，用 curl 测试一下基本功能：

curl -X POST http://localhost:8000/v1/completions \ -H "Content-Type: application/json" \ -d '{ "prompt": "你好，请介绍一下你自己", "max_tokens": 100, "temperature": 0.7 }'

能正常返回结果，说明推理服务跑起来了。

3.2 Agent 编排层的搭建与配置

编排层是 Agent 的大脑，负责接收任务、拆解步骤、调用工具、生成结果。我用 Python 写的，核心是一个异步任务处理器。

核心流程是这样的：

1. 接收任务请求，解析出任务类型和参数
2. 根据任务类型加载对应的 Skill
3. Skill 定义了一个处理流程，编排层按流程执行
4. 流程中的每一步可能调用 MCP 工具或推理服务
5. 所有步骤完成后，汇总结果返回

代码结构上，我分了几个模块：

• agent/core.py：核心调度逻辑
• agent/skills.py：Skill 加载与管理
• agent/mcp_client.py：MCP 工具调用客户端
• agent/inference.py：推理服务客户端
• agent/queue.py：请求队列管理

关键代码片段，展示一下 Skill 加载的逻辑：

import yaml from pathlib import Path class SkillLoader: def __init__(self, skills_dir: str): self.skills_dir = Path(skills_dir) self.skills = {} def load_all(self): for skill_file in self.skills_dir.glob("*/skill.yaml"): with open(skill_file) as f: skill_def = yaml.safe_load(f) self._validate_dependencies(skill_def) self.skills[skill_def["name"]] = skill_def def _validate_dependencies(self, skill_def): required_tools = skill_def.get("dependencies", {}).get("mcp_tools", []) for tool in required_tools: if not self._tool_available(tool): raise RuntimeError(f"Skill {skill_def['name']} 依赖的工具 {tool} 不可用")

这段代码的逻辑是：加载所有 Skill 定义，检查每个 Skill 声明的 MCP 工具依赖是否可用，不可用就报错。这样能在启动阶段就发现问题，而不是等到运行时才报错。

3.3 MCP 工具服务的开发与接入

MCP 工具服务是 Agent 和外部系统之间的桥梁。每个工具服务封装一类操作，对外暴露标准的 MCP 接口。

以代码审查工具为例，它的职责是：接收代码 diff，调用静态分析工具，返回分析结果。实现上是一个 HTTP 服务，接收 POST 请求，处理完后返回 JSON。

from fastapi import FastAPI, HTTPException from pydantic import BaseModel app = FastAPI() class ReviewRequest(BaseModel): diff_content: str language: str = "auto" class ReviewResponse(BaseModel): issues: list summary: str @app.post("/review_pull_request") async def review_pull_request(req: ReviewRequest): try: issues = analyze_diff(req.diff_content, req.language) summary = generate_summary(issues) return ReviewResponse(issues=issues, summary=summary) except Exception as e: raise HTTPException(status_code=500, detail=str(e))

这个服务部署在内网，Agent 通过内网地址调用。工具服务的开发要点是：接口要稳定，错误处理要完善，返回格式要统一。因为 Agent 依赖这些工具的输出做后续决策，工具服务不稳定会直接影响 Agent 的可靠性。

3.4 完整任务流程的串联与测试

所有组件都部署好后，需要做端到端的测试。我设计了一个典型的测试场景：提交一个代码变更，让 Agent 自动完成审查并生成报告。

流程是这样的：

1. 用户通过 Web 控制台提交代码 diff
2. 编排层接收请求，加载 code-review Skill
3. Skill 流程第一步：调用 code-review MCP 工具做静态分析
4. Skill 流程第二步：把分析结果和 diff 一起送给推理服务，生成自然语言的审查意见
5. 编排层汇总结果，返回给用户

测试时重点关注几个指标：端到端延迟、各环节耗时占比、错误率。实测下来，一个中等规模的 diff（约 200 行变更），端到端耗时在 3 到 5 秒之间，其中推理服务占了大约 60% 的时间，工具调用占 30%，编排层开销占 10%。

这个耗时分布说明推理服务是主要瓶颈。优化方向有两个：一是用更小的模型或更激进的量化，二是优化提示词减少 token 数量。我试过把提示词精简 30%，端到端延迟降了大约 15%。

4. 常见问题与排查技巧实录

4.1 内网部署高频问题速查

内网环境做 AI Agent，遇到的问题和公网环境很不一样。我把踩过的坑整理成一张速查表：

这张表里的每一条都是实际踩过的坑。比如“Skill 加载失败”这个问题，一开始没做依赖检查，Skill 加载成功了但运行时才发现工具不可用，排查了半天。后来加了启动时的依赖检查，问题一目了然。

4.2 推理服务的性能问题排查

推理服务的性能问题是最难排查的，因为它涉及 GPU、内存、网络多个层面。我总结了一套排查流程：

第一步：确认瓶颈在哪。用监控工具看 GPU 利用率、显存占用、请求队列长度。如果 GPU 利用率低但队列长，说明是批处理没配好；如果 GPU 利用率高但吞吐上不去，说明模型太大或量化不够。

第二步：看请求特征。统计请求的输入长度和输出长度分布。如果输入长度差异很大，动态批处理的效果会打折扣，因为要等最长的那个请求。解决办法是按长度分桶，相似长度的请求放一起批处理。

第三步：调参验证。每次只调一个参数，观察指标变化。比如先把 max_batch_size 从 4 调到 8，看吞吐和延迟的变化。如果吞吐提升明显且延迟可接受，就保留；如果延迟飙升，就调回去。

提示：推理服务调优是个反复迭代的过程，不要指望一次调好。建议建一个压测脚本，每次调参后跑一遍，用数据说话。

4.3 MCP 工具调用的稳定性保障

MCP 工具调用是 Agent 流程中最容易出问题的环节，因为涉及网络通信和外部服务。我做了几层保障：

超时控制：每个工具调用设置合理的超时时间，默认 30 秒。超时后不阻塞整个流程，而是返回一个错误标记，让 Agent 决定是重试还是跳过。

重试机制：对于幂等的工具调用，失败后自动重试，最多重试 2 次，重试间隔指数退避。非幂等的调用不自动重试，避免重复执行。

熔断降级：如果某个工具连续失败超过阈值，暂时熔断该工具，后续请求直接返回降级结果，避免拖垮整个系统。熔断后定期探测，恢复后自动重新启用。

结果校验：工具返回的结果做 schema 校验，格式不对就当作失败处理。这样能避免脏数据污染 Agent 的上下文。

这几层保障加上后，工具调用的成功率从最初的 85% 提升到了 99% 以上。剩下的 1% 主要是工具服务本身的 bug，需要单独修复。

4.4 内网环境特有的坑与应对

内网环境有一些特有的坑，公网环境遇不到，但一旦遇到就很头疼。

时间同步问题：内网如果没有配好 NTP，各台机器的时间可能不一致。这会导致日志时间戳混乱，排查问题时对不上。更严重的是，如果 Agent 的 Token 认证依赖时间戳，时间偏差会导致认证失败。解决办法是内网必须配一个可靠的 NTP 服务，所有机器定期同步。

DNS 解析问题：内网的 DNS 服务可能不稳定或者配置不全，导致服务之间互相访问失败。我的做法是在 /etc/hosts 里写死关键服务的 IP 和主机名映射，绕过 DNS。虽然不够优雅，但稳定可靠。

证书管理问题：内网服务之间的 HTTPS 通信需要证书。自签证书虽然能用，但管理起来麻烦，过期了容易忘。我建了一个内部的证书管理流程，证书到期前自动提醒，续期后自动分发。

磁盘空间问题：模型文件、日志、镜像占用的磁盘空间很大，内网服务器如果磁盘规划不好，很容易满。我的做法是给不同用途划分独立的磁盘分区，模型和镜像放一个区，日志放另一个区，互不影响。

这些坑看起来都是小事，但在内网环境里，小事往往变成大事。因为内网排查问题的手段有限，不能像公网那样随手 Google 或者找在线工具。所以内网做工程，预防比排查重要，提前把能想到的问题都规避掉，比出了问题再解决要高效得多。

5. 工程化扩展与持续维护

5.1 监控体系的搭建

内网 AI Agent 系统上线后，必须有一套监控体系，否则出了问题两眼一抹黑。我搭的监控分三个层面：

基础设施监控：CPU、内存、GPU、磁盘、网络这些基础指标，用 Prometheus 加 Grafana 展示。重点是 GPU 显存和利用率的监控，这是推理服务的生命线。

服务层监控：每个服务的请求量、延迟、错误率。MCP 工具服务、推理服务、编排层都要埋点。我用的是 OpenTelemetry 做链路追踪，能看到一个请求在各个服务之间的流转情况。

业务层监控：Agent 任务的成功率、平均耗时、各 Skill 的使用频率。这些指标能反映系统的实际使用情况，指导后续优化方向。

监控告警的阈值设置要合理。太敏感会天天报警，麻木了就不看了；太迟钝会漏掉真问题。我的经验是，先设一个宽松的阈值，运行一周后根据实际情况调整。

5.2 Skills 的迭代与版本管理

Skills 不是一次性的，需要持续迭代。我建立了一套迭代流程：

• 需求收集：定期和 Agent 的使用者沟通，了解哪些任务处理得不好，需要新增或改进哪些 Skill。
• 开发测试：新 Skill 在开发环境开发，用测试用例验证。测试用例覆盖正常流程和边界情况。
• 灰度发布：新版本 Skill 先给部分用户使用，观察效果。没问题再全量发布。
• 版本回滚：如果新版本出问题，能快速回滚到上一个稳定版本。Git tag 加配置切换就能实现。

版本管理上，每个 Skill 的版本号遵循语义化版本规范。主版本号变更表示不兼容的改动，次版本号表示新增功能，修订号表示 bug 修复。Agent 加载 Skill 时可以指定版本范围，比如^1.2.0表示兼容 1.2.0 及以上的 1.x 版本。

5.3 后续扩展方向

这套系统跑稳定后，可以往几个方向扩展：

多模型支持：目前只用了一个模型，后续可以接入多个模型，根据任务类型选择最合适的。比如代码任务用代码能力强的模型，文档任务用写作能力强的模型。

Agent 协作：单个 Agent 能力有限，可以让多个 Agent 协作完成复杂任务。一个负责规划，一个负责执行，一个负责检查。这需要设计 Agent 之间的通信协议和协作机制。

知识库集成：把企业内部的知识库接入 Agent，让 Agent 能基于内部知识回答问题。这需要做知识库的向量化和检索，以及和 Agent 上下文的集成。

自动化工作流：把 Agent 嵌入到企业的自动化工作流中，比如代码提交后自动触发审查，工单创建后自动分类和分配。这需要和现有的 DevOps 工具链集成。

这些扩展方向不是都要做，而是根据实际需求选择。我的建议是先把核心场景做深做透，再考虑扩展。贪多嚼不烂，内网环境的资源有限，聚焦才能出效果。

我个人在实际操作中的体会是，内网做 AI Agent 工程，技术难度其实不是最大的，最大的挑战是资源约束下的取舍。你不能什么都想要，必须在模型大小、推理速度、并发能力、功能丰富度之间做权衡。想清楚哪些是必须的，哪些是锦上添花的，然后集中资源把必须的做好。这套系统从零到能用，我花了大约三周时间，其中一半时间花在环境准备和依赖离线化上，真正写 Agent 逻辑的时间反而不多。所以如果你也要做类似的事，建议先把环境摸清楚，把依赖准备好，后面的开发会顺畅很多。