用 Eigent 搭建本地化文档处理智能体：从 Docker 部署到任务编排

如果你所在团队既要用 AI 智能体自动处理合同、报表、会议纪要这类敏感文档，又不放心把原文上传到第三方云端，那 Eigent 值得认真评估。它是一款开源的本地优先（local-first）智能体编排平台，自带一个可以跑在自己机器上的后端服务，把用户账号、模型配置、工具设置和聊天记录都留在本地数据库中。下面按“部署准备 → 模型接入 → 任务编排 → 结果检查”的顺序，把整条私有化文档流水线走一遍。

为什么把文档处理交给可自托管的智能体

传统做法里，文档自动化通常靠脚本拼接：一个脚本抽取文本，一个脚本调模型做总结，再用定时任务串起来。任务一多，脚本之间的状态传递、失败重试和结果归档就变成维护负担。

Eigent 的思路是把这类多步骤工作交给一组智能体协作完成。按照官方文档的描述，它采用多智能体协作架构，并支持浏览器自动化、终端自动化和 MCP（Model Context Protocol）等通用能力，让智能体像人一样操作桌面环境，而不必为每个流程单独写深度 API 集成。对文档处理场景来说，这意味着“读取一批文件 → 提取关键字段 → 生成结构化摘要 → 归档到指定目录”可以描述成一个任务，而不是一堆脚本。

更关键的是数据边界。server/ 目录提供的本地后端基于 FastAPI + PostgreSQL，官方说明中明确写道：部署该服务后，用户注册信息、模型供应商配置、工具设置和聊天历史等敏感数据存储在你自己机器上，除非你显式配置外部服务（例如云端模型供应商或远程 MCP 服务器），否则不会上传到官方云端。这条边界决定了它适合哪些场景：数据合规要求高、但又能接受调用外部模型 API 的团队。

需要提前说明的是，本地部署不等于全链路离线。如果你接入的是云端模型 API，文档内容在推理阶段仍会发送给该模型供应商。真正意义上的“完全本地”需要配合本地推理服务，这一点后文会单独讲。

部署前的环境准备

Eigent 是 Node/Electron 应用，官方建议的 Node.js 版本区间是 18 到 22，内存建议至少 8GB。如果你只是连接外部模型 API，纯 CPU 环境也能跑起来；但若打算在本地跑模型推理，硬件要求会显著提高。

部署前请确认以下几项：

Docker 与 Docker Compose：本地后端依赖容器化的 PostgreSQL，先按 Docker 官方文档安装并启动 Docker。
Node.js 与 npm：用于克隆仓库后安装前端依赖。
Git：拉取仓库代码。
磁盘空间：容器镜像、数据库和文档副本会占用额外空间，建议预留充足余量。

有一点必须提醒：Eigent 迭代较快，v0.0.89 版本对服务端做了重构，将代码库改为领域驱动架构，并明确标注这是面向本地部署用户的破坏性变更。因此不要照搬网上任何一份旧教程，部署前先到 GitHub Releases 页面确认当前版本号和升级说明。

用 Docker 启动本地后端

第一步是把仓库克隆到本地，然后进入 server 目录准备环境变量。

git clone https://github.com/eigent-ai/eigent.git
cd eigent/server
cp .env.example .env
docker compose up -d

cp .env.example .env 这一步是把示例配置复制成实际生效的配置文件，之后模型密钥、数据库连接等参数都写在这个 .env 里，不要把它提交到版本库。

容器启动后，本地后端会提供 API 服务。按照仓库说明，API 文档默认在 http://localhost:3001/docs（Swagger 界面），你可以先用浏览器打开确认服务是否正常。如果页面打不开，优先检查容器状态：

docker compose ps
docker compose logs -f

日志里出现数据库连接失败，通常是 PostgreSQL 容器还没就绪，等待几十秒后重试即可。

如果你需要用到应用触发器（incoming webhooks），要注意本地后端必须部署在可被公网访问的域名上，因为外部服务需要通过 HTTPS 回调地址访问你的服务器。纯本地开发时可以用 ngrok 之类的工具临时暴露端口；但如果你的目标是数据不出内网，就不建议开启这类触发器。

前端连接本地后端

后端跑起来后，还需要让前端指向本地服务，而不是官方云端。在项目根目录创建或修改 .env.development：

VITE_USE_LOCAL_PROXY=true
VITE_PROXY_URL=http://localhost:3001

然后安装依赖并启动前端：

npm install
npm run dev

VITE_USE_LOCAL_PROXY=true 表示启用本地代理模式，VITE_PROXY_URL 指向你刚启动的后端地址。如果你改了后端端口，这里要同步修改。官方也提供了打包好的桌面客户端（macOS 11+ 与 Windows），安装后同样可以配置为连接本地后端，适合不想折腾前端构建的团队成员。

接入模型供应商

后端本身不包含模型能力，你需要配置模型供应商。Eigent 的本地后端提供了模型供应商相关接口，包括查询、新增、修改、删除以及设置首选供应商：

GET /providers：查看已配置的供应商
POST /provider：新增供应商配置
PUT /provider/{id}、DELETE /provider/{id}：修改或删除
POST /provider/prefer：设置首选供应商，前后端会优先使用它

配置入口在客户端的设置界面，通常需要填写 API Base URL、API Key 和模型名称。这里有几个容易出错的点：

Base URL 是否带 /v1。不同供应商的 OpenAI 兼容端点路径不一致，填错会直接返回 404。
模型名称必须与供应商文档一致。名称拼写错误往往表现为“模型不存在”而不是认证失败，容易误判为密钥问题。
首选供应商设置。配置了多个供应商时，如果没有设置首选，任务可能落到非预期的模型上，成本和效果都会偏离预期。

Eigent 官方文档也介绍了与 GLM Coding Plan 配合使用的方式，说明它支持接入第三方模型计划。如果你所在团队已有既定的模型采购渠道，可以优先复用，不必额外开通。

如果你的合规要求是“文档内容不得离开内网”，那么这里的模型供应商必须指向内网自建的推理服务。此时需要评估本地硬件能否支撑所选模型的推理负载——这是整条流水线里最吃资源的一环，也是最容易低估的一环。

编排一个文档处理任务

配置完成后，就可以下发任务了。Eigent 的任务描述方式接近自然语言，但为了结果稳定，建议把任务拆成明确的阶段。以“处理一批季度报表”为例，可以这样描述：

读取 /data/reports/2026-Q1/ 目录下的所有 PDF 报表，逐份提取公司名称、报告期、营业收入和净利润四项字段，输出为 CSV 文件保存到 /data/output/，并对缺失字段的文件单独列出清单。

这类描述之所以比“帮我处理一下报表”更可靠，是因为它明确了输入路径、抽取字段、输出格式和异常处理方式。智能体在执行过程中会调用终端和文件操作能力，路径写绝对路径可以避免工作目录不一致导致的找不到文件。

对于重复性任务，可以把它保存为可复用的技能（skill）。v0.0.89 版本新增了安全审计员作为默认示例技能，说明技能机制是官方主推的扩展方式。你可以把团队常用的文档处理流程固化成技能，后续只需替换输入目录。

任务执行期间，界面会显示任务进度和 token 用量。官方在该版本中优化了聊天头部的 token 展示，用提示框区分任务与项目两个维度的总量。对需要控制成本的团队来说，这个数字值得定期查看。

检查结果与常见问题

任务跑完后不要直接采信输出，尤其是涉及数字的场景。建议按以下顺序检查：

核对条目数。输入目录有多少份文件，输出 CSV 就应该有多少行（或与异常清单行数相加后匹配）。
抽查关键字段。随机挑几份原文，人工比对抽取的金额和日期，确认没有串行或错位。
检查异常清单。缺失字段的文件是否被正确识别，而不是被静默跳过。
查看 token 用量。如果单次任务消耗远超预期，通常是任务描述过于宽泛，导致智能体反复尝试。

几个常见问题及排查方向：

服务启动后前端仍连到云端：检查 .env.development 是否生效，以及前端进程是否重启过。
任务执行中断：先看后端容器日志，再确认模型 API 是否触发限流或额度耗尽。
升级后服务无法启动：v0.0.89 是破坏性变更，Docker 用户需要执行 cd server && docker compose up --build -d 重新构建，非 Docker 用户需要拉取最新代码后重启服务进程。
文件读取失败：确认容器内的路径映射与宿主机一致，容器默认无法访问宿主机任意目录，需要在 compose 配置中挂载卷。