ThinkingAI Logo
返回博客列表

Agent私有化部署教程:部署准备与验证流程

从部署边界、资源清单到实施步骤和验证记录,拆解 Agent 私有化部署的准备、部署与验收流程,并以 Dify 开源版为例给出可核对的命令、成功信号和回滚方法。

2026-11-2014分钟
Agent私有化部署教程:部署准备与验证流程

把 Agent 平台做私有化部署,落地到企业自己的机房、专属云或托管环境,安装命令只是其中一步。部署前要把环境、权限和回滚想清楚,部署后要能证明系统可用、权限生效、数据留在可控范围。

这篇教程按准备、部署、验证三个阶段展开。通用流程适用于多数企业级 Agent 平台,具体命令以 Dify 开源版为例。其他产品的菜单、参数和版本要求会有差异,执行时以所选版本的官方文档为准。

部署完成可以用四个结果判断:

  • 服务能启动,数据库、缓存、向量库等依赖组件健康。
  • 一个真实任务能从输入跑到输出,步骤和工具调用可追溯。
  • 不同权限的账号看到的数据不同,权限落到数据层。
  • 断开外网后核心功能仍可用,审计日志查得到。

一、先定部署边界和验收标准

私有化部署的边界决定了后面要准备什么。企业常见的边界有三类:

边界适合的情况要提前确认
全本地部署数据不能离开企业网络,生产环境需要内网隔离离线安装、模型本地化、升级包怎么进内网
混合部署敏感数据留在本地,通用能力调用外部服务哪些字段出网、网关怎么放行、日志存在哪里
专属云或托管希望资源专属,同时由厂商承担部分运维资源隔离方式、运维责任、数据访问审计

私有化部署不等于数据不出域。 系统装在内网,仍可能有遥测、插件更新和外部模型调用。私有化部署 AI 智能体时,要把模型、知识库、工具调用和运维通道一起纳入边界,靠出站策略和验证确认数据流向。

边界定完后,先把验收标准写下来。验收标准不需要很长,但要能回答四个问题:

  • 哪些数据允许进入系统,哪些必须脱敏或禁止上传。
  • 哪些角色能用哪些 Agent,能查哪些库、哪些字段。
  • 哪些操作必须留日志,日志保留多久,谁能查。
  • 故障时多长时间恢复,升级失败怎么回滚。

这四个问题会直接影响服务器配置、网络策略、权限模型和备份方案。把它们写进验收表,后面的准备和验证才有依据。

企业级 AI Agent 平台通常由模型接入、Agent 编排、知识库和治理四层组成,部署时要逐层确认,避免只把界面装好、关键链路没跑通。

二、Agent 私有化部署前要准备什么

准备清单按资源、系统、网络、权限、数据五块展开。每一项都要有负责人和完成状态,避免部署当天才发现缺项。

1. 服务器与算力

平台本体和模型推理要分开估算。 平台本体主要消耗 CPU、内存和磁盘 IO,模型推理主要消耗 GPU 显存。把两部分混在一起估,容易出现平台能启动、模型跑不动,或者 GPU 闲置、内存不足。

资源要确认的内容判断方法
CPU 与内存平台本体、并发用户、任务队列Dify 官方文档给出的最低配置是 2 核 CPU、4 GiB 内存,适合试用;生产环境按真实并发和任务量做压测
GPU是否本地推理、模型规模、量化方式本地部署模型时按模型参数量和并发估算;使用内网或云端模型 API 时,本地通常不需要 GPU
存储镜像、日志、备份、向量索引按现有数据量和增长速度预留,系统盘不要写满
网络带宽、延迟、跨网段访问模型调用和文档同步都要走网络,先测实际链路

Dify 的最低配置只说明软件能启动,不能代表生产容量。用演示数据估算资源,上线后很容易出现内存不足和响应变慢。

2. 操作系统、容器与依赖

操作系统要确认版本、内核、依赖库、时区和时间同步。国产化环境还要确认交付包在麒麟、统信等系统上的依赖是否完整,能安装和能稳定运行要分开验证。

容器与编排版本要写进检查表。Dify 当前文档要求 Docker Compose 2.35.0 或更高版本,并确保 Docker 守护进程正在运行;使用 Kubernetes 时,要确认交付包支持的版本范围,避免生产集群与交付包不匹配。

部署前还要准备 Git、OpenSSL 等基础工具。Dify 的 Docker Compose 部署需要 Git 下载发行版,需要 OpenSSL 生成沙箱令牌。

3. 网络与离线源

网络要分两个方向确认。入站方向包括管理界面、API 和单点登录回调;出站方向包括模型端点、镜像仓库、邮件服务和时间同步。

纯内网环境要提前准备离线源:

  • 容器镜像仓库,或把镜像保存成 tar 包导入。
  • 操作系统和语言依赖的离线包。
  • 模型权重文件和推理服务镜像。
  • 许可证、证书和升级包。

还要确认 DNS、代理、防火墙策略和时间同步。内网无法拉取镜像,是私有化部署最常见的卡点之一,安装往往停在第一步。

4. 账号、密钥与权限

部署前要明确四类账号:平台管理员、普通用户、服务账号和数据库账号。管理员账号用于初始化,日常运维应使用单独账号,避免多人共用。

密钥包括数据库密码、缓存密码、API Key、沙箱令牌和插件密钥。密钥不要写进代码仓库或聊天记录,至少放在加密配置或密钥管理服务里。部署账号只给安装和配置所需权限,完成后再收回或降权。

如果 Agent 要调用内部业务系统,提前准备测试账号和访问权限,权限按最小可用配置。业务系统没有接口时,要先确认替代方案,别等部署完再补。

5. 数据、备份与回滚

数据准备包括三件事:分类分级、脱敏规则和知识库权限。哪些文档可以进知识库,哪些字段必须脱敏,哪些人只能看部分内容,都要在导入前定好。

备份要在部署前做一次完整演练,确认备份能恢复,不能只看备份文件是否存在。记录当前版本、镜像 tag、配置文件、数据库版本和向量库类型,准备对应的回滚包。

升级通道也要提前设计。离线升级包怎么进内网,升级失败怎么回退,谁有权执行,都要写进运维手册。

部署前对照这张表逐项确认:

检查项完成标准
边界与验收标准数据流、角色、日志、回滚四项已确认
服务器CPU、内存、GPU、磁盘满足目标规模
系统与容器版本匹配,依赖齐全
网络端口、代理、DNS、离线源可用
账号与密钥管理员、服务账号、密钥保管明确
数据与备份分类完成,备份可恢复
升级与回滚离线包和回退步骤已演练

三、选哪种部署方式

部署方式按规模、可用性要求和运维能力选择,不必一开始就上最复杂的架构。

方式适合阶段优点限制
单机 Docker Compose试点、小团队、功能验证依赖打包在一起,上手快单点故障,扩容和高可用能力有限
Kubernetes生产、多团队、需要弹性和滚动升级调度、故障转移、滚动升级成熟运维门槛高,网络和存储要求高
厂商交付的私有化平台缺少专职运维、需要交付支持责任边界清晰,通常包含调优和巡检依赖厂商响应,定制空间受产品限制
混合部署敏感数据本地、通用能力使用外部服务兼顾合规与成本数据流和网络策略复杂,审计要求高

试点阶段的目标是验证链路。 先跑通一个模型、一个知识库、一个 Agent 和一组用户,再扩规模。上来就做高可用集群,问题定位会更难。

如果还在选平台,可以先对照支持私有化部署的 Agent 平台,确认交付边界、适用条件和验收方式。

四、Agent 私有化部署步骤:以 Dify 开源版为例

下面以 Dify 社区版为例,演示单机 Docker Compose 的部署过程。命令和版本要求来自 Dify 官方文档。其他版本可能调整参数,执行前先看对应版本的部署说明。

1. 锁定版本并获取发行版

  • 从 Dify releases 选择版本,检出对应标签。生产环境不要直接使用 main 分支。
  • 记录版本号、镜像 tag 和 Compose 文件,写入部署记录。
  • 成功信号:目录完整,版本号与计划一致。

2. 生成配置文件

进入 docker 目录,从 .env.example 复制 .env。用 OpenSSL 生成令牌,写入 DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN。Agent 后端和本地沙箱共用这个令牌,缺一项都启动不了。

首次启动前要定好数据库和向量库。 Dify 默认自带 PostgreSQL 和 Weaviate,不需要另外准备;如果要用外部 MySQL、PostgreSQL 或其他向量库,先在 .env 中设置。官方文档明确说明,首次启动后再切换,已有数据不会自动迁移。

成功信号:.env 存在,关键变量有值,数据库和向量库类型与方案一致。

3. 启动服务并检查状态

在 dify/docker 目录运行:

<code class="language-bash">docker compose up -d

</code>

查看服务状态:

<code class="language-bash">docker compose ps

</code>

持续运行的服务应显示 Up 或 healthy。init_permissions 是一次性任务,负责准备存储权限,完成后显示 Exited (0)。如果服务反复重启,先看日志,常见原因是端口占用、内存不足、镜像拉取失败或依赖服务连接不上。

成功信号:核心服务健康,日志没有持续报错。

4. 初始化管理员并做安全加固

浏览器访问 http://服务器地址/install,创建管理员账号。默认 HTTP 端口是 80;端口被占用时,在 .env 中设置 EXPOSE_NGINX_PORT,访问时带上对应端口。

开放给其他人之前,按官方安全加固清单替换默认凭据:

  • 数据库和 Redis 的密码。
  • 代码执行沙箱的 SANDBOX_API_KEY 和 CODE_EXECUTION_API_KEY,两者设为同一个强密钥。
  • Weaviate 的 API Key,并关闭匿名访问。
  • 插件守护进程的 PLUGIN_DAEMON_KEY 和 PLUGIN_DIFY_INNER_API_KEY。
  • Agent 相关令牌。

启用 HTTPS,限制管理入口的访问来源。数据库密码有一个例外:数据库初始化后,要先在数据库里改密码,再同步更新 DB_PASSWORD。

成功信号:管理员能登录,默认凭据已替换,HTTPS 访问正常。

5. 接入模型和知识库

  • 在模型设置中添加模型端点,填入内网地址或经批准的 API 地址,先测试一次对话。
  • 上传一份带标准答案的文档,建立知识库,问一个文档中明确写出的问题,检查召回片段和引用来源。
  • 创建一个最小 Agent,只给它一个工具和一个知识库,跑一个真实任务。
  • 成功信号:模型有响应,知识库能召回正确片段,Agent 能完成任务并留下执行记录。

做到这里,系统具备基本可用性。是否可以上线,还要看下一节的验证结果。

五、部署后怎么验证

部署完成不等于可以上线。 验证要覆盖可用性、权限、数据边界和恢复能力,每项都留下记录。

验证项怎么操作通过标准不通过时
服务与依赖查看容器状态、数据库连接、磁盘和日志核心服务健康,错误日志没有持续增长查端口、资源、依赖配置
登录与权限用管理员、普通用户、受限账号分别登录菜单、数据范围、操作权限不同检查角色绑定和权限下推
模型接入发送固定问题,记录延迟和错误响应稳定,失败有明确报错检查端点、密钥、网络策略
知识库检索问文档中明确写出的问题召回正确片段并显示来源检查解析、切片、索引和权限
Agent 任务跑一个含工具调用的任务步骤、输出、工具结果可追溯检查工具权限和超时设置
审计查登录、提问、导出、配置变更日志记录完整,时间、账号、对象可查补日志字段和留存策略
数据边界断外网或封禁出站,观察核心功能核心功能可用,没有未授权外联查 DNS、代理、遥测和插件
备份与回滚备份后恢复到测试环境,重启服务,演练回滚数据和配置完整,服务能恢复修备份脚本和回滚步骤

权限验证要用不同账号问同一个问题,看返回的数据是否不同。只在界面隐藏菜单不算通过,权限要下推到数据层,接口和导出也要受限。

数据边界验证要在业务低峰做。断开外网或封禁出站后,观察核心功能是否可用,同时检查 DNS 请求、代理日志和容器出站连接。发现未授权外联,先定位来源,再决定关闭还是加白名单。可以对照真私有化验收清单检查断网、出站审计和凭据替换。

审计日志要确认记录完整,包括登录、提问、知识库检索、工具调用、导出和配置变更。日志存储与业务数据分开,保留时间满足内控要求。

备份恢复要在测试环境演练。只备份不恢复,无法证明备份有效。重启服务后检查数据、索引和权限是否完整,再演练一次回滚版本。

六、常见失败点与处理

  • 按演示数据估资源。 演示数据几十万行,生产可能几千万行,内存和磁盘差距很大。上线前用真实数据做一次压测,覆盖峰值并发和最大文档。
  • 内网拉不到镜像。 安装停在第一步。提前搭离线镜像仓库,或把镜像保存成 tar 包导入,并验证内网能拉取。
  • 版本不匹配。 Docker Compose 低于 2.35.0,或 Kubernetes 版本与交付包不一致。部署前把版本写进检查表,交付方和运维方共同确认。
  • 先启动再换数据库或向量库。 Dify 官方文档说明,首次启动后切换不会迁移已有数据。存储方案要在第一次启动前定好。
  • 权限只在应用层做。 界面看不到,接口仍能查到。把权限条件下推到数据层,用受限账号验证。Agent 权限、审计和运行监控的检查项,可以参考Agent 安全与治理。
  • 没有升级和回滚方案。 系统半年后停在旧版本。准备离线升级包、备份和回滚步骤,先在测试环境演练。
  • 管理入口直接暴露公网。 默认端口和弱口令会放大风险。先完成 HTTPS、强密码和访问限制,再开放访问。

七、自建、厂商交付还是混合

部署工作可以由内部团队完成,也可以交给厂商交付,或者双方分工。选择取决于运维能力、上线时间和合规责任。

  • 自建:适合有平台团队、希望完全掌控环境的企业。需要承担安装、调优、升级和值守。
  • 厂商交付:适合缺少专职运维、需要快速上线的企业。责任边界、交付物、响应时限和验收标准要写进合同。
  • 混合:企业准备服务器和网络,厂商负责应用部署、调优和巡检。私有化项目里这种分工很常见。

ThinkingAI 的私有化部署按需求评估、方案设计、环境准备、部署实施、验收交付、持续运营六步推进,支持在客户自有基础设施上部署,数据和推理留在企业可控环境。平台支持接入企业私有化模型和自定义模型端点,审计日志可以追溯操作。

以世嘉《女神异闻录:夜幕魅影》项目为例,世嘉负责准备服务器,ThinkingAI 负责应用搭建和运维,导入周期约 1 到 2 个月,目前运维工作量接近零。这是单个项目的交付情况,具体周期取决于环境复杂度和系统对接范围。ThinkingAI 已服务全球超过 1500 家企业,接入超过 8000 款产品。

常见问题

私有化部署一定要 GPU 吗

看模型放在哪里。使用内网或云端模型 API,本地只运行 Agent 平台,通常不需要 GPU;本地部署模型,才需要按模型规模和并发配置 GPU。多数企业会采用混合方式,敏感数据本地处理,通用问答调用经批准的模型服务。

最少需要几台服务器

试点阶段可以用一台服务器跑单机 Docker Compose,Dify 官方最低配置是 2 核 CPU、4 GiB 内存。生产环境要根据并发、可用性和数据量决定,通常会把数据库、向量库和对象存储拆开,并配置备份和监控。没有适用于所有企业的固定台数。

纯内网断网能用吗

可以,前提是镜像、依赖、模型权重和许可证都能离线进入内网,并且升级包有固定通道。部分插件、在线模型和外部工具依赖公网,部署前要逐项确认。断网测试能帮助发现隐藏的外联依赖。

Docker Compose 能直接上生产吗

小规模、单团队的生产环境可以用,但要接受单点故障和有限的扩容能力。多团队、高可用或需要滚动升级的场景,更适合 Kubernetes 或厂商交付的私有化平台。

怎么证明数据没有离开内网

看证据,不看口头承诺。检查防火墙出站规则、DNS 日志、代理日志和容器网络连接,做一次断网测试,确认核心功能仍可用。私有化部署只提供基础条件,数据是否留在可控范围,要靠配置和验证。

升级会不会丢数据

按官方升级说明操作,先备份 .env、持久化卷、数据库和向量库,再在测试环境演练。Dify 官方文档提示,首次启动后切换数据库或向量库不会自动迁移已有数据。升级前读对应版本的升级说明,保留回滚包。

私有化部署一般要多久

试点环境通常几天可以跑通;生产环境涉及服务器、网络、权限、系统对接和验收,周期会长一些。世嘉项目的导入周期约 1 到 2 个月,可以作为参考,实际时间取决于环境复杂度和对接范围。

参考资料

  • Dify 官方文档,《使用 Docker Compose 部署 Dify》,访问日期 2026-11-18
  • ThinkingAI 私有化部署
  • ThinkingAI 博客,私有化智能体平台
  • ThinkingAI 客户案例,《世嘉〈女神异闻录:夜幕魅影〉:自动化数据删除,让分析环境几乎零运维》:https://www.thinkingai.cn/user-case/d42c4b71f3/

准备好构建你的 Agent 团队了吗

立即体验 Agentic Engine, 让 AI 成为真正的团队成员

ThinkingAI Big Logo
电话咨询