企业官网建设流程全解析

1. 项目概述：为什么“隔离内网下的 AI Agent 工程实战”不是纸上谈兵，而是真刀真枪的落地刚需

你有没有遇到过这样的场景：某大型制造企业的IT系统运行在完全物理隔离的内网环境中，所有设备不连外网、无公网IP、无DNS解析能力，连U盘拷贝都要经过三重审批；但业务部门却急着要一个能自动解析产线日志、识别异常停机模式、并生成维修建议的智能体——不是演示Demo，是要嵌入到现有MES系统里，每天处理20万条日志，7×24小时稳定运行。这时候，“AI Agent”四个字就从技术热词变成了工程考卷：它不再关乎模型多大、参数多炫，而在于——在没有互联网、没有云服务、没有预装生态的前提下，如何让一个具备感知-决策-执行闭环能力的智能体，在零外部依赖的封闭环境里真正下地干活。

这正是“隔离内网下 AI Agent 工程实战”的核心命题。它绕不开三个硬骨头：第一，模型必须本地化部署且轻量可控——不能调用OpenAI或Claude API，得用量化后的Qwen2-1.5B或Phi-3-mini，推理引擎得是llama.cpp或ollama本地实例；第二，工具链（Tools）必须可审计、可裁剪、可离线安装——所谓MCP Tools（Management, Control, Planning Tools），不是GitHub上随手clone的Python脚本，而是经过安全加固、签名验证、适配国产OS内核的二进制模块；第三，Skills不是插件市场下载的黑盒包，而是可编译、可调试、可与现有Java/Go后端系统直连的标准化能力单元——比如一个“查询Oracle数据库状态”的Skill，其底层必须封装成gRPC接口，输入是JSON Schema定义的参数，输出是结构化Result对象，中间不经过任何第三方中间件。

我过去三年在能源、轨交、军工类客户现场落地的7个AI Agent项目里，有5个卡在“最后一公里”：模型跑通了，Prompt调优了，但一进客户机房，发现防火墙策略禁止所有出向连接，Docker镜像仓库被禁用，pip源不可达，甚至连curl命令都被策略拦截。最后活下来的方案，无一例外都放弃了“云原生范式”，转而采用“裸金属+静态链接+配置驱动”的极简架构。这不是技术倒退，而是对真实生产环境的尊重。所以这篇内容不讲LLM原理，不堆Transformer公式，只聚焦一件事：当你面对一台贴着“严禁联网”封条的服务器时，怎么把AI Agent从PPT变成可交付、可运维、可审计的工程制品。适合正在做信创替代、等保三级改造、工业互联网平台建设的架构师、后端开发和运维工程师，也适合想跳出Demo陷阱、真正用AI解决业务问题的一线开发者。

2. 整体架构设计：放弃“云上思维”，构建四层离线可信栈

隔离内网环境下的AI Agent，本质是“在无网络的沙漠里建一座自循环绿洲”。我们不能照搬LangChain/LangGraph那种依赖PyPI生态、动态加载Tool、在线注册Function Calling的模式——那套逻辑在内网里就像要求沙漠居民用5G信号点外卖。必须重构整个技术栈，按“可信、可控、可验”三原则，划分为四个物理隔离又逻辑贯通的层级：

2.1 基础设施层：裸金属优先，容器次选，彻底告别K8s集群依赖

客户机房里最常见的是一台8核32G内存、CentOS 7.9或麒麟V10 SP3的物理服务器，上面跑着Oracle 11g和Java WebLogic。这时候强行上Kubernetes，不仅增加运维复杂度，更带来新的攻击面（etcd、kubelet证书管理）。我们实测下来，最稳的方案是：

• 操作系统层直接部署：用systemd管理llama.cpp服务（监听127.0.0.1:8080）、FastAPI应用（监听127.0.0.1:8000）、PostgreSQL（本地存储Agent执行日志和Skill元数据）；
• 若必须容器化，则限定为单机Docker Compose：所有镜像提前下载、扫描漏洞、签名存档，通过内网Nexus私库分发；禁止使用docker build动态构建，所有镜像必须是“构建-测试-归档”三步完成的不可变制品；
• 关键规避点：绝不使用任何需要外网校验License的商业软件（如某些LLM推理加速库），所有依赖库必须提供源码或静态链接库（.a文件），确保编译时可审计。

举个真实案例：某核电站监控系统升级项目，客户明确要求“所有二进制文件需提供SHA256哈希值及上游开源项目Commit ID”。我们最终交付的llama.cpp可执行文件，是基于commita1b2c3d手动打patch（修复ARM64平台内存泄漏）后，用GCC 11.2全静态编译生成，附带完整的build.sh脚本和依赖树清单。这种“笨功夫”，恰恰是隔离环境里最聪明的选择。

2.2 模型服务层：小模型+量化+本地推理引擎，拒绝“大而全”幻觉

很多团队一上来就想部署Llama3-70B，结果在48G显存的A100上跑起来都卡顿，更别说客户只有两块RTX 3090的内网服务器。我们坚持“够用即最优”原则：

• 选型标准：参数量≤3B、激活显存占用≤6GB、推理延迟≤800ms（输入512token，输出256token）；
• 量化方案：必须支持GGUF格式，优先选用Q4_K_M（平衡精度与速度），禁用Q2_K（精度损失过大，影响Skills调用准确率）；
• 推理引擎：llama.cpp是唯一选择——它不依赖CUDA驱动（可CPU纯推理）、支持Windows/Linux/macOS、二进制体积小（<15MB）、API极简（仅需HTTP POST /completion）；

提示：别迷信“模型越大越好”。我们在某电网调度Agent中对比测试：Qwen2-1.5B-Q4_K_M在“解析SCADA告警文本→提取设备ID→匹配检修规程”任务上，准确率92.3%；而Qwen2-7B-Q4_K_M因上下文理解过载，反而出现设备ID错位，准确率降至86.1%。小模型的确定性，恰是生产环境的生命线。

2.3 Agent运行时层：去中心化调度，用配置文件驱动行为

LangGraph的State Graph在内网里最大的问题是“状态持久化难”——Redis被禁、PostgreSQL又不想暴露给Agent进程。我们的解法是：用YAML配置文件定义Agent工作流，用本地SQLite做状态快照。

• 每个Agent实例对应一个agent_config.yaml，包含：

  name: "power_substation_monitor" description: "监控变电站实时数据，触发告警处置流程" entry_point: "analyze_alarm" skills: - name: "query_scada_db" endpoint: "http://127.0.0.1:8000/skills/scada_query" input_schema: {"substation_id": "string", "time_range_hours": "integer"} - name: "generate_maintenance_plan" endpoint: "http://127.0.0.1:8000/skills/maint_plan" input_schema: {"alarm_code": "string", "device_list": "array"}

• Agent Core（Python编写）启动时加载此配置，将Skills注册为本地HTTP客户端；每次执行完一个Skill，自动将当前state（含输入参数、输出结果、耗时）写入agent_state.db的SQLite表；
• 这种“配置即代码+文件即状态”的模式，让运维人员无需懂Python，只需修改YAML就能调整Agent行为，审计时直接查SQLite文件即可还原完整执行链路。

2.4 Skills能力层：不是插件，是可验证的微服务契约

这是最容易被误解的部分。“Skills”在隔离内网里绝不是用户从市场下载的zip包，而是：

• 每个Skill必须提供独立的gRPC服务（非HTTP），接口定义在skills.proto中：

  service ScadaQuery { rpc Execute(QueryRequest) returns (QueryResponse) {} } message QueryRequest { string substation_id = 1; int32 time_range_hours = 2; } message QueryResponse { repeated DeviceData devices = 1; string status = 2; // "success" or "error" }

• 所有Skills二进制文件需通过客户CA签发的证书签名，启动时校验签名有效性；
• 提供skill-tester命令行工具，输入JSON样例自动调用gRPC并输出耗时、内存峰值、返回结构校验结果——这才是真正的“Skills可测试性”。

这种设计让Skills彻底脱离Python生态束缚：Java写的数据库查询Skill、Rust写的文件解析Skill、C++写的图像识别Skill，只要实现同一份proto契约，就能被Agent Core无缝调用。我们在某高铁信号系统项目中，就用C++ Skill调用国产兆芯CPU上的OpenCV库做轨道异物检测，Python Agent Core只负责编排，不碰底层计算。

3. 核心细节拆解：MCP Tools、Skills开发与管理台落地要点

“MCP Tools”这个热词背后，其实是隔离环境下AI Agent的三大生存能力：Management（资源管控）、Control（流程干预）、Planning（动态决策）。它们不是抽象概念，而是必须具象为可部署、可审计、可灰度发布的工程模块。

3.1 MCP Tools的工程化实现：从概念到二进制

注意：所有MCP Tools必须满足“零外网依赖”——比如Management Tool的CPU监控，不能调用psutil（需pip install），而要用/proc/stat原始数据自己解析；Control Tool的信号发送，不能依赖第三方IPC库，直接用Linux原生signal.h。我们曾因psutil版本兼容问题，在某国产OS上导致Agent监控失效长达48小时，教训深刻。

3.2 Skills开发规范：让每个Skill都成为可交付的“能力原子”

Skills不是功能函数，而是具备完整生命周期的工程制品。我们制定了一套硬性规范，所有团队成员必须遵守：

• 命名规范：[领域]_[动词]_[名词]，如scada_query_device、mes_update_order_status、iot_parse_modbus_frame；禁止模糊命名如data_tool、helper_v2；
• 输入输出契约：必须提供OpenAPI 3.0 JSON Schema，且Schema中每个字段标注x-audit-required: true（表示该字段变更需走变更评审）；
• 错误处理：禁止抛出Python Exception，必须返回标准Error Object：

  { "code": "DB_CONNECTION_TIMEOUT", "message": "Oracle连接超时", "details": { "host": "10.1.2.3", "port": 1521 } }

• 性能基线：每个Skill必须通过skill-benchmark工具测试，要求P95响应时间≤300ms，内存泄漏率<0.1MB/小时；

我们用一个真实Skills开发案例说明：scada_query_device。它要连接客户内网Oracle数据库，执行如下SQL：

SELECT device_id, last_value, timestamp FROM scada_data WHERE station_id = :station AND timestamp > SYSDATE - INTERVAL '2' HOUR

• 开发步骤：
  1. 用Oracle Instant Client（静态链接版）编译C++ gRPC服务，避免依赖系统级Oracle库；
  2. SQL参数化处理，严格校验station_id为纯数字字符串，防SQL注入；
  3. 连接池大小固定为5，空闲连接30秒自动回收；
  4. 输出结果自动转换为JSON，字段名小驼峰（lastValue→last_value），保持与Agent Core约定一致；
• 交付物清单：
  • scada_query_device二进制文件（SHA256校验值）
  • scada_query_device.proto（gRPC接口定义）
  • input_schema.json&output_schema.json
  • benchmark_report.txt（含P95/P99/内存曲线）
  • security_audit.md（含OWASP Top 10自查表）

这套规范让Skills从“个人代码”变成“组织资产”，新成员入职三天就能独立开发合规Skills。

3.3 管理台设计：不是炫酷前端，而是运维指挥中枢

内网管理台常犯的错误是做成React/Vue单页应用，结果客户浏览器版本老旧（IE11），连ES6语法都报错。我们的方案是：

• 前端：纯HTML + Vanilla JS，用Bootstrap 4.6（兼容IE11），所有图表用Chart.js 2.x（非3.x）；
• 后端：FastAPI + SQLite，禁用任何ORM（如SQLModel），所有SQL手写，便于审计；
• 核心功能模块：
  • Agent看板：显示各Agent实例的CPU/内存/请求QPS/错误率，数据来自agent-monitor的本地socket；
  • Skills仓库：上传Skills二进制文件，自动校验签名、提取proto接口、生成调用文档；
  • 执行追溯：输入Agent ID和时间范围，查询SQLite中的execution_log表，展示完整调用链（含每个Skill的输入/输出/耗时）；
  • 灰度发布：选择10%流量路由到新版本Skills，通过execution_log中的version_tag字段统计成功率差异；

实操心得：管理台的“执行追溯”功能救过我们三次大忙。某次客户投诉“Agent生成的维修单设备ID全错”，我们用管理台查到第3个Skill（generate_maintenance_plan）的输入里device_list字段为空数组，顺藤摸瓜发现是前序Skill的SQL漏写了WHERE条件——整个排查过程不到15分钟。没有这个功能，靠日志grep可能要花半天。

4. 实操全流程：从零搭建一个可运行的隔离内网AI Agent

现在，我们以“某石化企业罐区液位监控Agent”为例，走一遍完整落地流程。目标：接入DCS系统OPC UA数据，当液位超阈值时，自动触发短信告警并生成工单。全程不依赖任何外网资源。

4.1 环境准备：30分钟完成基础环境初始化

客户提供的是一台4核16G内存、CentOS 7.9、无root权限的虚拟机。我们按以下步骤操作：

1. 创建专用用户与目录：

   sudo useradd -m -d /opt/ai-agent aiuser sudo chown aiuser:aiuser /opt/ai-agent sudo chmod 755 /opt/ai-agent

2. 安装必要工具链（离线包）：
   • 提前在办公网下载：gcc-11.2.0.tar.gz、cmake-3.25.2-Linux-x86_64.sh、python-3.11.8-embed-amd64.zip；
   • 上传至服务器，解压安装：

     # 编译gcc（耗时约25分钟） tar -xzf gcc-11.2.0.tar.gz && cd gcc-11.2.0 && ./contrib/download_prerequisites && cd .. && mkdir build-gcc && cd build-gcc && ../gcc-11.2.0/configure --prefix=/opt/gcc-11.2 --enable-languages=c,c++ --disable-multilib && make -j4 && sudo make install # 安装Python嵌入版（免sudo） unzip python-3.11.8-embed-amd64.zip -d /opt/ai-agent/python

3. 验证环境：

   /opt/gcc-11.2/bin/gcc --version # 应输出11.2.0 /opt/ai-agent/python/python.exe --version # 应输出3.11.8

注意：禁用yum install——客户yum源已关闭。所有依赖必须离线打包。我们维护了一个内部离线包仓库，包含200+常用库的RPM/源码包，按客户OS版本分类索引。

4.2 模型部署：用llama.cpp跑通Qwen2-1.5B

1. 获取模型文件：
   • 从魔搭（ModelScope）官网下载Qwen2-1.5B的GGUF格式（qwen2-1.5b-instruct-q4_k_m.gguf），注意选择cuda或cpu版本；
   • 上传至/opt/ai-agent/models/；
2. 编译llama.cpp（CPU版）：

   git clone https://github.com/ggerganov/llama.cpp.git cd llama.cpp && make clean && CC=/opt/gcc-11.2/bin/gcc CXX=/opt/gcc-11.2/bin/g++ make LLAMA_CURL=0 LLAMA_BLAS=0 LLAMA_CUDA=0 -j4

3. 启动模型服务：

   nohup ./main -m /opt/ai-agent/models/qwen2-1.5b-instruct-q4_k_m.gguf \ -c 2048 -ngl 0 -p "你是一个石化罐区监控专家，请根据输入数据判断是否需要告警" \ --port 8080 --host 127.0.0.1 > /opt/ai-agent/logs/llama.log 2>&1 &

   • -ngl 0：强制CPU推理（客户无NVIDIA GPU）；
   • -c 2048：上下文长度，足够处理长液位数据；
   • --host 127.0.0.1：禁止外网访问，符合安全策略；
4. 验证服务：

   curl -X POST "http://127.0.0.1:8080/completion" \ -H "Content-Type: application/json" \ -d '{"prompt":"液位数据：TANK_A=85%, TANK_B=92%, TANK_C=76%。阈值90%。请判断是否告警","n_predict":64}'

   返回JSON含content字段，证明模型服务就绪。

4.3 Skills开发：实现OPC UA数据采集与短信告警

我们开发两个Skills：opcua_read_tank_level（采集）和sms_send_alert（告警）。

• opcua_read_tank_level：
  • 用Python（pyopcu）实现，但pyopcu依赖openssl，故用静态链接版OpenSSL 1.1.1w编译；
  • 输入Schema：{"endpoint": "opc.tcp://10.1.1.100:4840", "node_ids": ["ns=2;s=TANK_A.Level", "ns=2;s=TANK_B.Level"]}；
  • 输出：{"tanks": [{"id": "TANK_A", "level": 85.2, "unit": "%"}, ...]}；
• sms_send_alert：
  • 调用客户内网短信网关（HTTP接口），输入含手机号、内容、签名；
  • 关键：短信内容经模型生成后，必须做敏感词过滤（内置词库，含“爆炸”、“泄漏”等），过滤后才发送；

Skills打包为独立gRPC服务，启动命令：

# opcua服务 /opt/ai-agent/python/python.exe /opt/ai-agent/skills/opcua_server.py --port 8001 # 短信服务 /opt/ai-agent/python/python.exe /opt/ai-agent/skills/sms_server.py --port 8002

4.4 Agent Core编排：用YAML定义工作流

创建/opt/ai-agent/config/tank_monitor.yaml：

name: "tank_level_monitor" description: "监控储罐液位，超阈值自动告警" entry_point: "check_level_and_alert" skills: - name: "opcua_read_tank_level" endpoint: "http://127.0.0.1:8001" input_schema: {"endpoint": "string", "node_ids": "array"} - name: "sms_send_alert" endpoint: "http://127.0.0.1:8002" input_schema: {"phone": "string", "content": "string", "signature": "string"} workflow: - step: "read_data" skill: "opcua_read_tank_level" input: {"endpoint": "opc.tcp://10.1.1.100:4840", "node_ids": ["ns=2;s=TANK_A.Level", "ns=2;s=TANK_B.Level"]} - step: "analyze" prompt_template: | 你是一个石化专家。以下储罐液位数据：{tanks}。阈值90%。请判断： - 是否有罐体超阈值？ - 若有，列出罐体ID和当前液位； - 生成一条不超过60字的告警短信，含罐体ID、液位、建议操作。 仅输出JSON，格式：{"alert": true, "tanks": ["TANK_B"], "sms_content": "TANK_B液位92%，超阈值！立即检查进料阀。"} - step: "send_sms" skill: "sms_send_alert" input: {"phone": "13800138000", "content": "{sms_content}", "signature": "石化安监"}

Agent Core启动：

/opt/ai-agent/python/python.exe /opt/ai-agent/core/agent_runner.py \ --config /opt/ai-agent/config/tank_monitor.yaml \ --model-url http://127.0.0.1:8080/completion \ --log-dir /opt/ai-agent/logs/

4.5 管理台部署与首次运行

1. 部署管理台：
   • 将预编译的HTML/JS/CSS上传至/opt/ai-agent/web/；
   • FastAPI后端用uvicorn启动：

     /opt/ai-agent/python/python.exe -m uvicorn web.main:app --host 0.0.0.0 --port 8000 --workers 1

2. 首次运行验证：
   • 浏览器访问http://客户服务器IP:8000，登录管理台；
   • 在“Agent看板”看到tank_level_monitor状态为running；
   • 在“执行追溯”中，手动触发一次执行（管理台提供Test按钮），查看日志：

     [2024-06-15 14:22:31] INFO: Step read_data completed in 124ms [2024-06-15 14:22:32] INFO: Step analyze completed in 387ms, output: {"alert":true,"tanks":["TANK_B"],"sms_content":"TANK_B液位92%，超阈值！立即检查进料阀。"} [2024-06-15 14:22:33] INFO: Step send_sms completed in 89ms

   • 同时，手机收到短信：“TANK_B液位92%，超阈值！立即检查进料阀。”

至此，一个完整的隔离内网AI Agent正式上线。整个过程耗时约4小时（含环境准备），所有组件均可审计、可回滚、可替换。

5. 常见问题与避坑指南：那些只有踩过才懂的“内网特供”坑

在12个隔离内网项目中，我们总结出一套高频问题速查表。这些问题在外网环境几乎不会出现，却是内网落地的“拦路虎”。

5.1 模型层典型问题

5.2 Skills层致命陷阱

5.3 Agent Core与管理台血泪教训

最后分享一个独家技巧：给所有二进制文件加“内网水印”。在编译时注入构建时间、Git Commit ID、操作员姓名到二进制段：

echo "BUILD_INFO: $(date +%Y%m%d_%H%M%S)_$(git rev-parse HEAD)_zhangsan" | xxd -i >> build_info.h

运维时用strings agent_core | grep BUILD_INFO即可快速定位问题版本。这个小动作，在某次跨部门协同排查中，帮我们3分钟锁定故障包来源，比翻Git记录快10倍。

我在实际交付中发现，隔离内网AI Agent项目的成败，往往不取决于模型多先进，而在于对“基础设施毛细血管”的掌控力——一个没处理好的SELinux策略，能让整个系统瘫痪；一个没校验的GGUF BOM头，会让中文输出全乱码。真正的工程能力，就藏在这些琐碎却致命的细节里。当你能把llama.cpp在CentOS 7.9上跑稳，能把gRPC服务在兆芯CPU上跑通，能把管理台在IE11里跑起来，你就已经超越了90%的AI从业者。剩下的，只是把一个个“不可能”，变成客户机房里稳定跳动的绿色状态灯。