企业官网建设流程全解析

1. 项目拆解：为什么团队需要一个本地 AI Agent 平台

先说清楚这件事的源头。我去年听过某团队说过一句话：AI 能力不上内网，等于没有 AI 能力。当时觉得夸张，后来自己在交付一个跨平台系统时，天天把代码片段、日志分析、周报摘要丢给在线工具，才发现很多场景根本没法用——数据要出内网，审批流程长，响应速度看对方脸色，团队几个人同时用还要排队等额度。这就是这个项目最直接的痛点：把具备 Agent 能力的大模型服务，用 Docker 打包成一整套能跑在局域网内的平台。

标题里的 "DeepSeek Harness" 说白了是一个封装层。Harness 这个词在工程里意思是"夹具/缰绳/封装壳"，它把模型推理、工具调用、Agent 编排、API 网关、管理界面这些零零散散的组件全部收拢到一个统一的部署单位里。你不需要自己去 Git 上翻几十个仓库、手动装各种依赖，只要机器上有 Docker，一条命令拉起来，内网里几十号人就都能用一个稳定、私密、可控的 AI 平台。

做这个项目之前，我先列了一下需求清单，大家可以参考：

这几个需求背后是我自己踩过的坑。早期我们也试过直接在一台裸机上装 Python 环境、装模型、跑服务端，结果模型文件几十 GB，环境一乱就要从头折腾。后来换成 Docker 方案，所有依赖都固化在镜像里，开发环境和生产环境保持一致，团队新同学接手只需要会两条命令。所以我强烈建议：AI Agent 平台这类多组件系统，能容器化就尽量容器化。

这个内容适合谁？适合正在做私有化部署、需要为团队搭建 AI 工具的运维或后端工程师，也适合对本地部署大模型感兴趣但不想啃源码的技术爱好者。下面我把整个部署过程、关键参数、踩坑记录全部摊开讲，照着做基本能跑通。

2. 环境准备与部署形态选择

2.1 硬件底线与软件依赖

先说硬件。DeepSeek 模型有不同的尺寸，Harness 底层默认加载的是适合私有部署的量化版本。我实测的配置如下：

• CPU：8 核以上（建议 16 核，推理时多线程加速明显）
• 内存：32GB 起步，64GB 更舒服。量化版模型加载后大概占 16GB 左右，加上 KV Cache 和运行开销，一倍余量才不会 OOM
• 显卡：如果只是内网几个人用，CPU 推理能接受，但响应速度在 15~30 秒级别。有 NVIDIA 显卡（显存 16GB 以上）建议开启 CUDA 加速，单次响应能压到 3~8 秒
• 磁盘：至少预留 100GB。一个量化模型文件 40GB 左右，加上镜像和日志，100GB 比较稳妥
• 系统：Ubuntu 22.04 或 Debian 12 都行，内核只要支持 Docker 就行。Windows 用 Docker Desktop 也能跑，但推荐 Linux 服务器，性能和稳定性都好得多

我部署时用的是一台 32 核 128GB 内存 + 一张 24GB 显存显卡的工作站，Ubuntu 系统，Docker 版本是 24.0.7，Compose 插件也装了。这套配置跑起来非常从容，如果是 8 核 + 32GB 的机器，扛 3~5 个并发问题差不多到极限了。

软件层面只依赖两样：Docker Engine 和 Docker Compose Plugin。安装命令很常规：

# 安装 Docker Engine（以 Ubuntu 为例） curl -fsSL https://get.docker.com | bash sudo systemctl enable --now docker # 安装 Compose 插件 sudo apt-get install docker-compose-plugin

2.2 镜像选型：一体化 vs 模块化

这个项目提供的镜像有好几个 tag，我简单说一下选型逻辑：

我首选了一体化镜像，因为第一次部署不确定各部分之间怎么配合，一体化镜像把所有服务编排打包在一个 Compose 文件里，日志集中、网络互通、配置统一，排查问题最方便。等跑了几天稳定之后，再根据负载情况拆成独立服务。

这个选型思路大家可以参考：任何多组件系统，第一次跑通用一体化方案，跑通了再谈拆分——一上来就微服务化，只会让排查问题的半径变大。

3. 核心部署流程与关键配置解析

3.1 获取部署文件并调整端口

一体化的部署文件是一个 Docker Compose 编排文件。下载后用编辑器打开，能看到三个服务：server、worker、ui。我最关心的是端口映射和模型路径两个部分。

默认配置如下：

services: server: image: harness:all-in-one ports: - "8000:8000" - "8001:8001" volumes: - ./models:/app/models - ./data:/app/data environment: - MODEL_SIZE=14b-q4 - CUDA_VISIBLE_DEVICES=0 - TOKEN_LIMIT=8192 worker: image: harness:all-in-one # worker 不映射端口，只做内部任务处理 ui: image: harness:all-in-one ports: - "8080:80" depends_on: - server

我调整了端口映射，因为机器上 8000 被其他服务占了，我把 API 端口改成了 18000，Web UI 保持在 8080。端口规划很重要，部署之前先扫一遍端口占用，别等启动报错再手忙脚乱。用这条命令看一眼：

ss -tlnp | grep -E '8080|8000|8001'

3.2 模型文件准备与加载验证

Harness 启动后会自动下载模型，但这在无外网环境里就是个灾难。我踩过一次：内网机器拉模型，下载了几小时，最后直接超时。所以我强烈建议：在有网的机器上先把模型文件下载好，再拷到部署机的models目录下。

模型文件放置有讲究：

./models/ ├── config.json ├── model-00001-of-00004.safetensors ├── model-00002-of-00004.safetensors ├── model-00003-of-00004.safetensors └── model-00004-of-00004.safetensors

确认文件完整后，启动时在 Compose 文件的server服务里加一个环境变量指向本地模型：

environment: - MODEL_SOURCE=local - MODEL_PATH=/app/models/14b-q4

这样启动时会跳过下载步骤，直接加载本地文件。启动日志里看到Loading model from /app/models/14b-q4就说明路径对了。

还有个细节——模型加载需要几十分钟时间，期间服务端口可能已经处于监听状态，但请求会一直排队。别急着测试，先看日志，等日志出现Model loaded successfully再开始调接口，不然容易误判故障。

3.3 启动顺序与健康检查

Compose 文件里服务之间设置了依赖，但依赖只保证"服务进程起来了"，不保证"模型加载完了"。所以我在启动时用了一个多步骤的检查方法：

# 第一步：启动所有服务 docker compose up -d # 第二步：查看 server 日志 docker compose logs -f server

等待日志输出模型加载完毕的标志后，再用接口验证：

curl -X POST http://127.0.0.1:18000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek-harness", "messages": [{"role": "user", "content": "你好，请简单自我介绍"}], "stream": false }'

正常情况下 10~30 秒内会返回一段 JSON。如果返回 503，大概率是模型还没加载完，继续看日志等一会儿就好。

3.4 Web UI 与 API 网关的联通

Web UI 跑在 8080 端口，反向代理到后端的 server 服务。第一次打开页面会进入初始化向导，设置管理员账号、配置模型参数。我推荐把默认参数先跑起来，后面再慢慢调。Agent 平台有两层入口需要理解：

• 用户入口（Web UI）：团队成员打开浏览器访问http://服务器IP:8080，登录后在聊天界面里使用 Agent 功能
• 开发入口（API）：程序员通过http://服务器IP:18000/v1/...调用接口，把 Agent 能力集成到自己的脚本和系统里

这两个入口联通起来，平台才是真正"用起来"。我自己的做法是先通过 API 调用验证后端可行，再打开 Web UI 确认前端展示正常，两条链路都通，才算部署完成。

4. Agent 平台的工具配置与任务编排

4.1 内置工具注册与权限控制

DeepSeek Harness 的亮点在于它不是单纯一个聊天机器人，而是具备工具调用能力的 Agent 平台。内置了这些工具：

工具注册在管理后台完成，每个工具可以设置哪些用户组可用。我强烈建议收紧权限：给普通用户只开放web_search和api_caller，给开发组开放code_interpreter——后者有代码执行权限，万一模型幻觉生成危险命令，执行了会有风险。

4.2 自定义 Agent 的编排策略

Agent 平台上可以创建多个不同角色的 Agent。我自己配置了三个：一个是通用助手（负责问答、总结），一个是数据分析师（代码解释器 + 数据库查询），一个是运维助手（读取日志、调用 API 执行状态检查）。

创建 Agent 时需要注意几个配置项：

• System Prompt：这里写清楚 Agent 的角色、能力边界、输出风格。我踩过坑：Prompt 写得太泛，模型动不动就调用工具，反而不如不调。后来收敛成"先判断用户意图，非必要不调用工具"
• 工具选择：一个 Agent 不要挂太多工具。工具多了，模型推理时选择成本高，而且容易把本不相干的任务误路由到某个工具上
• 最大轮次（Max Iterations）：Agent 连续调用工具的最大次数。默认 5 次，我的经验是 3 次足够，超过这个数基本说明 Agent 在兜圈子，让它直接整理已有信息更合理
• 温度参数（Temperature）：建议 Agent 场景设置 0.2~0.4，越低越稳定。我之前用默认的 0.7，结果工具参数经常被模型"自由发挥"成奇奇怪怪的值

4.3 让 Agent 通过 API 对外提供能力

平台内置一个 OpenAI 兼容的 API 端点，方便现有系统接入。配置 API Key 后在管理后台生成一个密钥，然后在脚本里这样调用：

from openai import OpenAI client = OpenAI( base_url="http://192.168.1.100:18000/v1", api_key="sk-刚才生成的一长串密钥" ) response = client.chat.completions.create( model="code-analyst-agent", messages=[{"role": "user", "content": "帮我统计这个季度各项目的交付数量"}], temperature=0.3 ) print(response.choices[0].message.content)

这里唯一的坑是base_url 里路径必须带/v1，我之前漏掉直接报 404，排查了半天才发现。另一个经验是 API Key 要设置成"按 Agent 隔离"，别一个密钥通吃全部，否则后期做权限审计会很痛苦。

5. 局域网访问与多用户并发实战

5.1 网络规划：固定 IP 与防火墙策略

局域网访问要解决的关键问题是让团队成员都能顺利连上服务，而不是只有部署者自己能用。

第一步是把服务器的内网 IP 固定下来。DHCP 分配的地址重启会变，团队成员昨天收藏的访问地址可能今天就失效。我直接改网卡配置设成静态 IP192.168.1.100，然后在路由器管理页里也绑定了一次 MAC 与 IP，双保险。

第二步是防火墙放行端口。服务器上如果有ufw或firewalld，需要放行 8080 和 18000：

sudo ufw allow 8080/tcp sudo ufw allow 18000/tcp sudo ufw reload

如果局域网内有硬件防火墙，还需要在防火墙策略里放行这两个端口。这一步最容易被忽略：服务明明起来了，但同事一访问就超时，十次有八次是防火墙没放行。

第三步是确认Docker的网桥模式不会阻断外部流量。默认bridge模式已经做了端口映射，不需要额外配置，但要注意 Compose 文件里端口绑定写的是8080:80还是0.0.0.0:8080:80。默认8080:80会监听所有网卡，反而更方便。

5.2 多用户并发下的资源分配

团队里十几个人同时用，模型推理并发会直接把内存打满。我测过的几种并发策略：

我最后用的组合是：worker 数 3+TOKEN_LIMIT 4000+quantization 4bit。这个组合在 32 核 CPU 机器上能稳定支撑 10 人左右的团队日常使用。

另外要注意 Web UI 的会话超时设置。默认是 30 分钟无操作自动退出，如果团队内部常用，可以调到 8 小时，减少反复登录的烦躁感。这个在管理后台的会话配置里改。

5.3 HTTPS 与访问安全

局域网内虽然不直接暴露公网，但安全不能省。网上看到不少团队直接明文 HTTP 跑，一旦有人抓包，对话内容全裸奔。我建议在局域网内部署一个轻量级 HTTPS，用自签名证书就行。

用openssl生成证书后，配置反向代理（比如nginx或caddy）来终结 HTTPS：

sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ -keyout /etc/ssl/private/ai-platform.key \ -out /etc/ssl/certs/ai-platform.crt \ -subj "/CN=ai-platform.lan"

然后让平台（或反向代理）加载这套证书。团队成员第一次访问会有证书警告，选择信任即可。如果团队有内部的 CA 服务器，可以签正式一点的证书，体验会更好。

注意：生产环境如果要暴露到更大的网络，务必用正式证书，且加上访问控制层。自签名证书只适合边界可控的环境。

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

6.1 问题速查表

部署和运行中我整理了一张速查表，分享给大家：

6.2 模型加载超时的处理

这个问题我在第一次部署时几乎崩溃。模型文件有 40GB，服务器加载时显示进度条，但加载到 70% 就卡住，日志没有任何报错。

排查下来有两个原因：第一是磁盘 IO 速度太慢，机械硬盘读 40GB 的大文件要很久；第二是 Docker 的默认磁盘镜像格式overlay2在大目录读写时有额外开销。我的解决方案：

• 把模型文件放在独立的固态硬盘分区，挂载到容器的models目录
• 在 Compose 配置里给容器加device_cgroup_rules: - "c 10:200 rwm"加速缓存读取
• 如果系统内存够大，设置一个DATA_CACHE=32G环境变量，让模型加载时预读进页缓存

改完之后加载时间从 40 多分钟缩短到 8 分钟。大文件加载的性能瓶颈通常是磁盘 IO 而非 CPU，先排查存储层能省很多时间。

6.3 Agent 工具调用失败的调试方法

Agent 平台常见的一个问题是：Agent 明明看到了工具，但调用的时候不是参数格式错了，就是选错工具。调试这类问题我总结了一条比较高效的路子：

先打开管理后台的调试日志开关，让系统输出模型每次做工具选择时的原始推理记录。日志会显示模型选择了哪个工具、生成的参数是什么、系统返回了什么报错。对照这几层信息基本能定位问题：

• 参数格式错误 → 工具 schema 定义不够严格，或 Prompt 里没有给参数示例
• 选错工具 → 工具描述太模糊，或工具数量过多导致路由混乱
• 调用超时 → 工具执行时间太长，Agent 等不到结果就放弃了

我实际调试过的一个案例：数据分析 Agent 一直把db_query选成api_caller，仔细看才发现两个工具的 description 里都有"获取数据"这个词，模型很难区分。后来把db_query的描述改成"仅用于 SELECT 查询，返回表格数据，不允许调用其他系统 API"，把api_caller的描述改成"仅用于调用外部 REST API 获取第三方服务数据"，问题就解决了。

工具描述写得越具体，模型的选择越准确，这一点在实战中反复被验证。

6.4 内存溢出的强制兜底方案

即便配置了 64GB 内存，多用户并发时仍可能 OOM。Linux 内核的内存杀手可能会直接杀掉 Docker 容器，导致服务中断。我加了两个兜底机制：

第一个是容器内存限制，避免单个容器把整机拖垮：

deploy: resources: limits: memory: 48g

第二个是配置docker compose的restart: always，容器被杀后自动重启，不至于服务彻底瘫痪。同时把模型加载的超时时间设长一点，重启后模型重新加载需要几分钟，期间服务正常会 503，但至少不会挂死。

7. 从跑通到稳定运行的优化心得

7.1 持续排查推理长度和上下文窗口

用这个平台跑了两周之后，我最大的感受是：上下文长度比并发数更影响稳定性。模型本身支持长上下文，但如果团队成员不加限制地贴大段文档进去，KV Cache 会急剧膨胀，内存瞬间见顶。

解决方案有两个方向。一个是把TOKEN_LIMIT从 8192 降到 4096，强制截断过长的输入；另一个是在 Web UI 层做提示，当用户输入过长时提醒"当前模型处理长文本会变慢，建议拆分提问"。两个结合效果最好。

另外，日志里会记录每次请求消耗的 token 数，我每隔几天翻一下 API 日志，统计出哪些用户的提示词最长、最耗内存，然后针对性地给他们配置更大的上下文窗口，而不是一刀切。

7.2 定期备份模型服务数据

Agent 平台里的会话记录、工具配置、用户账号都存在data目录。我写了个定时备份脚本，每天凌晨打包一次：

#!/bin/bash # 每天凌晨 3 点执行：docker compose exec server backup 或直接 tar 数据目录 BACKUP_DIR="/backup/ai-platform" mkdir -p "$BACKUP_DIR" DATE=$(date +%Y%m%d) tar czf "$BACKUP_DIR/ai-platform-$DATE.tar.gz" -C /opt/ai-platform data find "$BACKUP_DIR" -name "*.tar.gz" -mtime +30 -delete

配合 crontab 每天执行。我不建议把模型文件一起备份，太大，而且模型文件是公开的可下载资源，丢了重新拷一份就行，真正要备份的是 data 目录和 docker-compose.yml 文件。

7.3 给团队的使用培训和权限落地

技术部署只是第一步，团队真正用起来才算完成。我整理了一个简短的团队使用指南：

• 注册账号后先体验通用助手，把日常问答、内容总结类工作迁移过来
• 让数据分析师先用"数据分析 Agent"，把重复性的报表推导交给它
• 开发人员直接走 API 接入现有工具链，用脚本调用 Agent 做代码解释和排查

权限落地时我做了三级设置：普通成员只能访问通用助手和知识库检索；高级成员可以创建自己的 Agent 和工具；管理员拥有系统配置和模型加载的权限。这样既保证功能开放，又不至于让所有人都能调整系统设置。

指的一提的是，我们给普通成员开放了"自定义 Agent"的权限，结果很多人创建的 Agent 质量参差不齐。后来收了权限，改成统一由管理员创建基础 Agent，普通成员可以使用但不可修改系统级配置。这个尺度大家可根据自己团队情况拿捏。

8. 写在最后的一点实操体验

跑这个平台快两个月了，最真实的感受就是：本地 Agent 平台的价值,不在于模型多聪明，而在于它把 AI 能力变成了团队内网里随手可用的基础设施。以前周报汇总要人工从各处粘贴，现在丢给 Agent 几分钟出来一张表；以前排查服务日志要翻半天,现在让运维助手直接查询日志文件并给出摘要。这种"润物细无声"的效率提升，才是这个项目最大的回报。

如果你也准备在自己的机器上搭一套,我给三条最实际的建议：第一,不要在裸机环境里折腾，直接用 Docker，模型重新部署时迁移成本极低；第二,部署前先把端口和防火墙规划好，这能省掉八成以上的"服务起不来"困扰；第三,别急着把 Agent 的权限全部放开，先把基础助手跑稳了，再逐步开放工具和 API，这样团队反馈路径更清晰，系统也不容易因为误操作翻车。

最后再分享一个小技巧：可以在 Compose 文件的server服务里加一个healthcheck，用curl定期探测/health接口，如果连续两次失败就自动重启容器。这样就算模型推理偶发卡死，服务也能自动恢复，我这套平台后来基本实现了"无人值守"运行。祝各位部署顺利，有更野的玩法欢迎交流。