把 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 个月,可以作为参考,实际时间取决于环境复杂度和对接范围。






