企业官网建设流程全解析

1. 为什么要在局域网里自建 AI Agent 平台

很多人第一次接触大模型，习惯性地打开网页版直接用。但只要你稍微深入一点，就会发现几个绕不开的痛点：对话记录散落在别人的服务器上、内网数据不敢往外传、多人协作时没有统一的入口、想接自己的知识库和工具链又处处受限。尤其是团队场景下，每个人各自开一个网页窗口，模型配置、提示词、工具权限全都不统一，用起来非常割裂。

我这次做的事情，就是用 Docker 把一套 AI Agent 平台部署到局域网里，让同一个网络下的所有设备——笔记本、台式机、平板——都能通过浏览器访问一个统一的入口。整套方案的核心思路是：用容器把运行环境和依赖全部打包，用局域网把访问范围收拢在可控边界内，用 Agent 框架把模型、工具、知识库串成一条完整的链路。

这里说的 AI Agent 平台，不是简单的聊天窗口。它至少包含四层能力：底层是模型推理服务，中间是 Agent 调度框架（负责拆解任务、调用工具、维护上下文），上层是会话管理和权限控制，最外面是浏览器可访问的 Web 界面。Docker 的价值在于把这四层里所有"装环境会出问题"的部分固化下来，你换一台机器，只要 Docker 在，一条命令就能拉起同样的服务。

适合读这篇内容的人有三类：一是想在团队内部搭一个统一 AI 入口的技术负责人；二是手里有一台闲置服务器或高性能主机，想物尽其用的折腾党；三是对 Agent 概念感兴趣、想亲手跑通一个完整链路的学习者。不管你属于哪一类，下面的内容都会从选型逻辑讲到实操细节，再讲到踩坑排查，尽量让你少走弯路。

需要提前说明的是，本文涉及的模型权重、镜像来源、端口配置等，都请以你自己实际获取的合规资源为准。局域网部署的核心诉求是"可控"，所以每一步都要想清楚：这个服务监听在哪个地址、谁能访问、数据落在哪里。

2. 部署前的选型与资源盘算

2.1 硬件底子决定了你能跑多大的模型

在动手之前，先算清楚硬件账。Agent 平台的性能瓶颈几乎全在模型推理上，而推理又吃两样东西：显存和内存带宽。如果你用的是带独立显卡的机器，显存大小直接决定能加载多大的模型；如果是纯 CPU 推理，那内存容量和内存频率就是关键。

我整理了一张常见的硬件档位对照表，方便你快速判断自己手里的设备适合什么规模的部署：

这张表不是绝对的，量化技术能把模型压缩到原来几分之一的大小，代价是精度略有下降。我的建议是：先用小模型把整条链路跑通，确认 Agent 调度、工具调用、Web 界面都正常，再逐步换大模型。一上来就追求最大参数，很容易卡在环境问题上，连平台长什么样都没看到就放弃了。

2.2 容器方案为什么比裸装更省心

有人会问：我直接在系统里装 Python 环境、拉模型、起服务不行吗？当然行，但你会在三个地方反复消耗时间。

第一是依赖冲突。Agent 框架通常依赖特定版本的推理库、向量数据库客户端、Web 框架，这些库之间经常互相打架。裸装环境下，你装 A 库可能把 B 库的依赖降级，导致 B 跑不起来。容器把每个服务的依赖隔离在各自的镜像里，互不干扰。

第二是迁移成本。裸装环境一旦换机器，你得把整套安装流程重来一遍，还得祈祷新机器的系统版本、驱动版本跟旧机器一致。容器镜像是一个自包含的包，换机器只要拉镜像、挂载数据卷，几分钟就能恢复。

第三是清理方便。实验性质的部署，跑完想删干净，裸装往往留下一堆配置文件、缓存目录、系统服务。容器删掉就没了，数据卷单独管理，干净利落。

提示：容器化不等于零配置。端口映射、数据卷挂载、环境变量这些还是得自己写，但相比裸装，出问题的范围小得多，排查也更有方向。

2.3 网络规划：局域网访问的几个关键决策

局域网部署最容易忽略的就是网络规划。你需要提前想清楚三件事。

第一，服务监听地址。容器里的服务默认可能只监听 127.0.0.1，这样局域网里其他设备是访问不到的。你需要在启动配置里把它改成监听 0.0.0.0，或者通过端口映射把容器端口暴露到宿主机。这一步不做，你会遇到"本机能开、别人打不开"的经典问题。

第二，端口选择。尽量避开系统常用端口，选一个不容易冲突的高位端口，比如 8xxx 或 9xxx 段。同时确认防火墙规则允许这个端口的入站流量，否则局域网内其他设备依然连不上。

第三，访问控制。局域网虽然相对封闭，但也不意味着可以完全裸奔。至少给 Web 界面加一层登录认证，避免同网络下任何设备都能直接操作你的 Agent 平台。如果平台支持多用户，还要规划好每个用户的权限边界。

这三件事在部署前想清楚，比部署后再回头改要省事得多。我见过太多人服务跑起来了，结果发现局域网访问不了，又回头折腾网络配置，白白浪费时间。

3. 镜像获取与容器编排的实操细节

3.1 镜像来源的合规确认与本地化处理

镜像获取是整个部署里最需要谨慎的一步。我的原则是：只从可信、合规的渠道获取镜像，并且在拉取后做一次本地校验。具体来说，先确认镜像的完整名称和标签，标签尽量用具体的版本号而不是 latest，因为 latest 会随时间变化，今天能跑的配置明天可能就变了。

拉取命令本身很简单：

docker pull <镜像名称>:<具体版本标签>

拉完之后，用下面的命令确认镜像信息：

docker images | grep <镜像名称> docker inspect <镜像ID> | head -50

docker inspect能看到镜像的架构、创建时间、暴露端口、默认环境变量等信息。重点看两个地方：一是 Architecture 是否和你的宿主机一致（比如宿主机是 arm64，镜像却是 amd64，跑起来会报格式错误）；二是 ExposedPorts 里列出的端口，这决定了你后面端口映射要写哪个。

如果镜像体积很大，拉取过程可能中断。这时候不要反复重试，先检查磁盘剩余空间。模型类镜像动辄几个 GB 到几十 GB，磁盘满了会报各种奇怪的错误，提前用df -h看一眼能省很多事。

3.2 数据卷设计：把模型和会话数据留在容器外

容器的一个核心特性是"无状态"——容器删了，里面的数据也没了。但模型权重、会话记录、知识库文件这些是需要持久保存的。所以必须用数据卷把它们挂载到宿主机上。

我一般会规划三个目录：

• 模型目录：存放模型权重文件，体积最大，单独挂载方便替换和备份。
• 数据目录：存放会话记录、用户配置、向量库索引等运行时数据。
• 配置目录：存放平台的配置文件，方便修改后重启生效，不用进容器内部改。

对应的启动参数大致是这样：

docker run -d \ --name ai-agent-platform \ -p 8080:8080 \ -v /your/path/models:/app/models \ -v /your/path/data:/app/data \ -v /your/path/config:/app/config \ <镜像名称>:<版本标签>

这里有个细节：宿主机目录的权限要和容器内运行用户的权限匹配。如果容器内以非 root 用户运行，而宿主机目录是 root 所有，容器就会因为没权限写入而启动失败。解决办法是提前用chown把宿主机目录的属主改成对应 UID，或者在启动时加--user参数指定用户。

注意：数据卷挂载路径不要用相对路径，一律用绝对路径。相对路径在不同工作目录下执行会指向不同位置，排查起来非常头疼。

3.3 用 compose 文件管理多服务依赖

一个完整的 Agent 平台往往不止一个容器：模型推理服务一个容器，Agent 调度框架一个容器，Web 前端一个容器，可能还有向量数据库一个容器。手动一个个docker run很容易乱，用 compose 文件统一管理是更稳妥的做法。

compose 文件的核心价值是声明式地描述服务之间的关系。你可以指定哪个服务先启动、哪个服务依赖哪个、它们之间怎么通信。下面是一个结构示意：

services: model-service: image: <模型镜像>:<版本> volumes: - /your/path/models:/app/models ports: - "8001:8001" agent-service: image: <Agent镜像>:<版本> depends_on: - model-service environment: - MODEL_ENDPOINT=http://model-service:8001 volumes: - /your/path/data:/app/data web-ui: image: <前端镜像>:<版本> depends_on: - agent-service ports: - "8080:8080"

这里的关键点是MODEL_ENDPOINT这个环境变量。在 compose 网络里，服务之间可以用服务名互相访问，所以 Agent 服务连模型服务时，地址写http://model-service:8001就行，不用写具体 IP。这是 compose 相比手动 run 的一大优势——服务发现自动完成。

depends_on只保证启动顺序，不保证服务真正就绪。模型服务加载权重可能要几十秒，Agent 服务如果启动太快去连它，会连接失败。稳妥的做法是在 Agent 服务里加一个重试逻辑，或者用健康检查配合depends_on的 condition 字段。

4. 平台跑通后的功能验证与调优

4.1 从浏览器访问到第一次对话的完整链路

服务全部起来之后，先在宿主机上用curl确认端口通不通：

curl -I http://localhost:8080

返回 200 或 302 说明 Web 服务正常。然后用局域网内另一台设备，把 localhost 换成宿主机的局域网 IP 再试一次。这一步能验证端口映射和防火墙是否配置正确。

浏览器打开界面后，第一次对话往往是最容易出问题的环节。因为这一次请求会走完整条链路：前端发请求给 Agent 服务，Agent 服务调用模型服务，模型服务加载权重并推理，结果再原路返回。任何一环出问题，你看到的都是转圈或者报错。

我的排查顺序是：先看模型服务日志，确认它有没有收到请求、有没有开始推理；再看 Agent 服务日志，确认它有没有成功把请求转发出去、有没有正确解析模型返回；最后看前端控制台，确认请求有没有发出去、返回的状态码是什么。这个顺序能帮你快速定位问题出在哪一层。

4.2 推理速度与并发能力的实测观察

平台跑通之后，接下来关心的就是快不快、能扛多少人。这两个指标其实是一体两面，都受模型规模和硬件资源制约。

我实测下来的经验是：首次请求永远是最慢的，因为模型要加载权重、初始化推理引擎。后续请求会快很多，因为权重已经在内存里了。所以评估性能时，要区分冷启动和热运行两个阶段，别拿第一次的耗时去判断整体性能。

并发方面，纯 CPU 推理的并发能力很有限，两三个人同时提问就可能排队。有独立显卡的话，并发能力会好很多，但也要看显存够不够同时容纳多个请求的中间状态。如果平台支持请求队列，可以配置一个合理的队列长度，超出就返回"繁忙"提示，而不是让请求无限堆积导致超时。

调优的方向主要有三个：一是换更小的量化模型，牺牲一点精度换速度；二是调整推理服务的批处理参数，让多个请求合并推理；三是给模型服务分配更多资源，比如限制其他容器的 CPU 占用，把资源让给推理。

4.3 会话数据与知识库的持久化管理

Agent 平台用起来之后，会话记录和知识库会不断增长。这些数据如果管理不好，轻则占用大量磁盘，重则拖慢检索速度。

会话数据我建议定期归档。把超过一定时间的会话导出成文件保存，从活跃数据库里删掉。这样既保留了历史记录，又不会让数据库无限膨胀。导出格式用通用的 JSON 或 Markdown 都行，方便以后查阅。

知识库数据要关注索引的更新策略。如果你往知识库里加了新文档，需要触发一次索引重建，否则新内容检索不到。索引重建可能比较耗时，建议放在低峰期做，或者做成增量更新，只处理新增的部分。

提示：数据卷所在的磁盘最好留出充足余量。模型文件、会话数据、索引文件加起来可能比你预想的大得多，磁盘写满会导致服务异常，而且这种异常往往报错信息很隐晦，不容易第一时间想到是磁盘问题。

5. 那些让我折腾半天的坑与排查思路

5.1 容器起来了但局域网访问不了的排查链路

这是最高频的问题，我完整走一遍排查过程。

第一步，确认容器本身在跑：docker ps看状态是不是 Up。如果是 Exited，先docker logs看退出原因。

第二步，确认宿主机本机能访问：curl http://localhost:端口。本机都不通，说明端口映射或服务监听有问题。

第三步，确认服务监听地址：进容器执行netstat -tlnp或ss -tlnp，看服务监听的是 127.0.0.1 还是 0.0.0.0。如果是 127.0.0.1，那局域网肯定访问不了，需要改服务配置。

第四步，确认宿主机防火墙：检查防火墙规则有没有放行对应端口。不同系统命令不一样，但思路都是先看规则列表，再决定是加规则还是临时关闭测试。

第五步，从局域网另一台设备测试：用ping确认网络连通，再用curl或浏览器访问。如果 ping 通但端口不通，基本就是防火墙或端口映射的问题。

这个链路走下来，九成以上的访问问题都能定位。关键是要一层一层排除，不要跳步。

5.2 模型加载失败的几种典型表现

模型加载失败的表现五花八门，但原因往往集中在几个点上。

显存不足：日志里会出现 out of memory 相关的字样。解决办法是换更小的模型，或者用量化版本，或者减少同时加载的模型数量。

文件损坏或不完整：日志提示无法读取某个权重文件，或者校验失败。这通常是下载中断导致的，重新获取完整文件即可。建议下载完后做一次校验，确认文件大小和哈希值符合预期。

路径配置错误：日志提示找不到模型文件。检查数据卷挂载路径和配置文件里的模型路径是否一致。容器内的路径和宿主机的路径是两套体系，很容易搞混。

版本不匹配：模型格式和推理引擎版本对不上。这种情况日志通常会提示不支持的格式或版本，解决办法是换匹配的推理引擎版本，或者换匹配的模型格式。

排查这类问题，最有效的办法就是认真读日志。日志里通常已经写清楚了失败原因，只是很多人习惯性地跳过日志直接猜。我自己的习惯是，服务起不来先docker logs --tail 100看最后一百行，八成问题一眼就能看出来。

5.3 端口冲突与资源争抢的处理经验

端口冲突的典型表现是容器启动时报 "address already in use"。解决办法有两个：换一个宿主机端口映射，或者找到占用该端口的进程把它停掉。

# 查看端口占用 lsof -i :8080 # 或 netstat -tlnp | grep 8080

资源争抢则更隐蔽。多个容器同时跑，CPU 和内存互相抢，表现是服务响应变慢、偶尔超时，但没有明显报错。这时候可以用docker stats实时看各容器的资源占用，找出那个吃资源最多的。

如果模型服务和别的服务挤在一台机器上，建议给模型服务设置资源上限，同时保证它的优先级。compose 文件里可以用deploy.resources字段限制每个容器的 CPU 和内存，避免一个服务把整台机器拖垮。

6. 把这套平台用起来的几个进阶方向

平台跑通只是起点，真正体现价值的是怎么把它用起来。我分享几个自己实践过的方向。

接内部知识库：把团队内部的文档、手册、常见问题整理成结构化数据，灌进向量库，让 Agent 在回答时优先检索内部资料。这样得到的答案比通用模型更贴合实际业务场景。

封装常用工具：Agent 框架一般支持自定义工具调用。你可以把日常重复性的操作封装成工具，比如查询某个内部系统的状态、生成固定格式的报表、执行标准化的数据处理流程。Agent 接到指令后自动调用这些工具，省去人工操作。

多用户权限隔离：如果团队多人使用，建议给每个人分配独立账号，会话记录互相隔离。管理账号可以查看使用统计，了解平台的使用情况，为后续扩容提供依据。

定期备份与版本管理：配置文件、会话数据、知识库索引都要定期备份。尤其是配置文件，改坏了能快速回滚。我习惯每次修改配置前先复制一份带日期的备份，出问题直接换回来。

最后分享一个我自己的体会：局域网自建 AI Agent 平台，最大的价值不是省了多少钱，而是数据边界清晰、配置完全可控、能按自己的需求定制。这套东西一旦跑顺，团队内部的协作效率会有明显提升。但前提是你要愿意花时间把基础打牢，把网络、存储、权限这些看似琐碎的事情规划清楚。基础打好了，后面加功能、扩规模都是水到渠成的事。