记录一次真实的私有化部署过程：Ubuntu 24.04 + Docker + Nexent v2.8.2，包含镜像加速、系统参数调整、首次登录初始化、模型接入、租户权限，以及 5 个真实报错的排查过程。
全部命令与输出来自实际运行，截图非示意图。

---

一、先说结论

项目	结果
操作系统	Ubuntu 24.04.5 LTS（aarch64）
资源	4 核 / 8 GiB / 60 GiB，可跑通全流程
部署方式	bash deploy.sh docker，组件 infrastructure,application,supabase
首次拉镜像耗时	约 40 分钟（国内网络 + 镜像加速）
镜像总占用	10.44 GB
容器数量	13 个
首次对话响应	0.9 秒（含工具调用）

关于环境选择的说明：本文以 Linux 为主线。我的宿主机是 macOS（Apple Silicon），实际部署在 Ubuntu 24.04 虚拟机里执行，命令与物理服务器、云主机完全一致。Windows 和华为云 ECS 的差异集中在第一步（Docker 与网络），文末单独列了一张对照表。全程未使用 Workbuddy 之类的自动化安装工具，所有步骤手工执行，便于复现时定位问题。

---

二、环境与前置准备

2.1 硬件要求

官方最低 4 核 / 8 GiB / 40 GiB，建议 8 核 / 16 GiB / 100 GiB。我的实测环境卡在最低线上，能跑，但必须注意两点：

1. 8 GiB 内存下 Elasticsearch 会吃掉一半，别再同时开浏览器重度使用；
2. 拉镜像期间磁盘峰值会到 10 GB 以上，留足空间。

2.2 网络准备

国内网络直接拉 Docker Hub 基本会超时。本文用两个国内代理镜像：

{
  "registry-mirrors": ["https://docker.m.daocloud.io", "https://docker.1ms.run"]
}

写入 /etc/docker/daemon.json 后重启 Docker：

sudo systemctl restart docker
sudo systemctl is-active docker

2.3 Windows / 华为云差异对照

环境	差异点	处理方式
Windows	必须用 WSL2，原生 Docker Desktop 的 Linux 容器在文件挂载上易出问题	安装 WSL2 + Docker Desktop，资源里给 8 GB 以上
华为云 ECS	默认 4 核 8 GiB 可跑，但磁盘要选 100 GB 高 IO	安全组放行 3000、5014、8010 端口
物理机 / 其他云	与本文一致	只需处理镜像加速与端口

---

三、下载链接与耗时汇总

先把要下载的东西列清楚，方便对照：

内容	地址	体积	实测耗时
Nexent 源码	https://atomgit.com/ModelEngine/nexent.git	275 MB	13.6 秒（AtomGit）
Nexent 源码（备用）	https://github.com/ModelEngine-Group/nexent.git	275 MB	10 分钟以上，不推荐
Docker 镜像（全部）	腾讯云 / daocloud / 1ms 镜像站	10.44 GB	约 40 分钟
官方文档	https://modelengine-group.github.io/nexent	—	—
对话模型	https://api.deepseek.com/v1	—	—
向量模型	https://api.siliconflow.cn/v1	—	—

镜像加速地址（写入 daemon.json）：

镜像站	地址	用途
DaoCloud	https://docker.m.daocloud.io	Docker Hub 通用镜像
1ms	https://docker.1ms.run	Docker Hub 备用
腾讯云（Nexent 官方）	部署时 --image-source mainland 自动使用	应用镜像

四、第 1 步：获取源码

官方仓库在 GitHub，国内拉取很慢。AtomGit 上有同步镜像，实测 13 秒拉完 275 MB：

time git clone --depth 1 https://atomgit.com/ModelEngine/nexent.git nexent

如果坚持用 GitHub，建议加 --depth 1，并把 git config --global http.postBuffer 调大，否则大包容易中断。

---

五、第 2 步：Docker 与 Compose 准备（第一个坑）

Ubuntu 24.04 自带的 docker.io 包会一起装上 Compose，但版本号格式和官方不一样：

❌ ERROR Docker Compose not found or version detection failed

两种解法：

• 装官方 Compose 插件（推荐，版本号带 v）；
• 或者加一个转发脚本，让 docker-compose --version 能匹配到纯版本号：

sudo tee /usr/local/bin/docker-compose >/dev/null <<'SH'
#!/bin/sh
case "$1" in
  --version|-v) exec docker compose version ;;
esac
exec docker compose "$@"
SH
sudo chmod +x /usr/local/bin/docker-compose

我用了第二种，因为不想动系统里的 Docker 源。

---

六、第 3 步：调整系统参数

Elasticsearch 需要足够的虚拟内存映射，否则启动即退出：

echo "vm.max_map_count=262144" | sudo tee /etc/sysctl.d/99-nexent.conf
sudo sysctl -w vm.max_map_count=262144

另外确认数据目录权限。容器内的 Elasticsearch 以 uid 1000 运行，宿主机数据目录属主不对就会报 failed to obtain node locks：

sudo chown -R 1000:0 "$HOME/nexent-data/elasticsearch"

---

七、第 4 步：执行部署

7.1 命令

cd nexent
bash deploy.sh --defaults docker \
  --components infrastructure,application,supabase \
  --port-policy development \
  --image-source mainland \
  --version v2.8.2 \
  --root-dir "$HOME/nexent-data"

参数说明：

参数	作用	为什么这么选
--components	选择组件	infrastructure 必选；application 是应用；supabase 提供登录与用户体系，没有它前端无法登录
--image-source mainland	使用国内镜像源	腾讯云镜像库，比 Docker Hub 快一个数量级
--version	指定版本	必须与源码 tag 一致，否则镜像 tag 找不到
--root-dir	数据目录	建议放在数据盘，别放系统盘

7.2 镜像拉取

国内网络下第一次部署，主要时间都在拉镜像。实测速度 1～6 MB/s，总量 10.44 GB：

如果卡在某一层超过 10 分钟没有进展，别等，先确认这个镜像在镜像站里有没有。我遇到的 Elasticsearch 就在 elastic.m.daocloud.io 卡死，最后换成 Docker Hub 同名镜像打标签解决。

7.3 部署完成

🎉  Deployment completed successfully!
🌐  You can now access the application at http://localhost:3000

13 个容器全部 Up，其中 nexent-elasticsearch、nexent-redis、三个 supabase-*-mini 显示 healthy 才算正常。

---

八、第 5 步：首次登录与初始化

浏览器打开 http://<主机IP>:3000，会先看到登录页：

8.1 超级管理员账号

部署脚本会自动创建一个超管，账号密码写在 deploy/env/.env 里：

NEXENT_SUPER_ADMIN_PASSWORD=Nexent@123

邮箱是 suadmin@nexent.com。用它可以登录，但登录后看到的是「租户资源管理」，不是工作台——这是最容易让人困惑的一点：

原因：Nexent v2 是多租户架构，超管只负责管租户，本身不属于任何租户，所以没有对话入口。

8.2 创建租户

点左上角 + 新建租户，填个名字（比如「12345热线」）。建完点进去，能看到这些页签：用户、API Key、用户组、模型、知识库、智能体、MCP、Skills、标签、邀请码。

8.3 创建租户用户

超管不能直接对话，需要进租户的普通用户。在「邀请码」页签生成一个管理员邀请码，然后去登录页用邀请码注册：

注册后该用户就属于这个租户，登录直接进工作台。这是本文和多数教程不一样的地方：多数教程只让你用超管登录，然后卡在「没有对话入口」上。

---

九、第 6 步：模型接入

Nexent 本身不带模型，必须自己接。我用了两个：

用途	模型	服务
对话	deepseek-chat	DeepSeek
向量	BAAI/bge-m3	硅基流动

9.1 先验证密钥

不要直接填进平台，先在命令行验证，避免把网络问题当成配置问题：

200 说明密钥和网络都通，1024 是 bge-m3 的向量维度，后面知识库和聚类都用它。

9.2 在平台添加

「租户资源管理 → 模型 → 添加模型」，填模型名、Base URL、密钥。两个模型都要通过连通性检查：

注意截图里有一条告警「1 个 LLM/VLM 模型中 1 个缺少容量字段，这些模型的输出 Token 限额未启用」。不影响使用，但长文本生成时建议手动配置输出 token 上限，否则可能被截断。

---

十、第 7 步：租户与权限

这一节是踩坑最集中的地方。

10.1 超管 ≠ 租户管理员

超管账号在租户内没有权限，点模型页签会弹「无权限访问」：

这是因为超管只有全局管理权，具体资源归租户用户管。

10.2 三类角色

角色	能做什么	登录后落点
超级管理员（SU）	建租户、建邀请码、看全局	租户资源管理
租户管理员（ADMIN）	管本租户的用户、模型、智能体、MCP	工作台
普通用户（USER）	只能使用已发布的智能体	工作台

10.3 授权给外部账号

如果要把仓库权限给别人（比如项目协作），在仓库设置里加成员，选「维护者」——这是 AtomGit 里最高的一档，对应其他平台的 Admin。

---

十一、第 8 步：启动类报错排查

下面 5 个都是我在部署中真实遇到的，按出现顺序排列。

问题 1：Compose 版本检测失败

❌ ERROR Docker Compose not found or version detection failed

定位：脚本正则要求版本号带 v，Ubuntu 包不带。
解决：见第 4 节，加 docker-compose 转发脚本。

问题 2：Elasticsearch 反复重启

docker logs --tail 20 nexent-elasticsearch

java.lang.IllegalStateException: failed to obtain node locks, tried [/usr/share/elasticsearch/data]
Caused by: java.nio.file.AccessDeniedException: /usr/share/elasticsearch/data/node.lock

定位：数据目录属主是宿主用户，容器内 uid 1000 无写权限。
解决：

sudo chown -R 1000:0 "$HOME/nexent-data/elasticsearch"
sudo chmod -R g+rwX "$HOME/nexent-data/elasticsearch"
docker restart nexent-elasticsearch

问题 3：镜像 tag 不存在

failed to resolve reference "ccr.ccs.tencentyun.com/nexent-hub/nexent:v2.8.0": not found

定位：镜像库只发布到 v2.8.2，源码却 checkout 在 v2.8.0。
解决：让代码与镜像版本对齐：

git fetch --depth 1 origin tag v2.8.2
git checkout v2.8.2

问题 4：MCP 服务返回 421

自建 MCP 服务用 SSE 方式提供工具，从容器访问时报：

HTTP/1.1 421 Misdirected Request
Invalid Host header

定位：MCP SDK 新版本默认开启 DNS 重绑定防护，只允许 Host 为 localhost/127.0.0.1，容器用网桥 IP 访问就被拒。
解决：内网环境下显式关掉防护：

from mcp.server.fastmcp import FastMCP
from mcp.server.transport_security import TransportSecuritySettings

mcp = FastMCP("ticket_analysis",
              transport_security=TransportSecuritySettings(
                  enable_dns_rebinding_protection=False))

同时把监听地址改成 0.0.0.0，否则容器连不上：

python server.py --transport sse --host 0.0.0.0 --port 8001

改完在 Nexent 的「MCP」页签里注册服务地址，状态变成「已启用 / 可用」就说明握手成功：

问题 5：智能体对话报 Agent run error

{"message":"Agent run error."}

平台日志里是 Agent run error: 'NoneType' object is not iterable。

定位：用接口直接创建智能体时，部分字段（如 model_id）为空，运行时空值被迭代。UI 创建的智能体没有这个问题。
解决：在界面里创建智能体并保存一次，或补齐字段。建议：智能体一律在界面创建，接口只用来导出和批量管理。

---

十二、资源占用与性能

12.1 运行态

项	数值
镜像占用	10.44 GB
容器	13 个
内存占用	约 5.4 GiB（8 GiB 环境下还剩 2.3 GiB 可用）
磁盘占用	约 13 GB

12.2 业务侧性能

真正跑业务时，瓶颈在模型调用而不是平台。用 2000 条工单做批量分析，规则类任务耗时可以忽略：

单轮对话（含一次工具调用）实测 0.9 秒，这个数字更值得关注，因为它包含模型推理时间。

---

十三、复现清单

按顺序执行，每一步确认通过再往下：

• Docker 24+ 与 Compose v2 可用，docker compose version 输出带 v
• daemon.json 配好国内镜像源，systemctl restart docker 成功
• vm.max_map_count=262144 已写入 /etc/sysctl.d/
• 源码版本与镜像版本一致（VERSION 文件对照）
• --components 包含 supabase，否则无法登录
• 13 个容器 Up，ES/Redis/Supabase 显示 healthy
• 超管能登录，建好租户与邀请码
• 用邀请码注册的租户用户能进工作台
• 两个模型（对话 + 向量）连通性检查通过
• 自建 MCP 服务容器内可访问（curl 返回 200）

---

十四、小结

这次部署最耗时间的不是命令本身，而是三件事：

1. 镜像：国内网络下，镜像源决定了部署是半小时还是半天；
2. 账号体系：超管不能对话这个设计，第一次遇到会以为装坏了；
3. 版本一致性：源码 tag、镜像 tag、MCP SDK 版本，三者任何一个错位都会卡住。

把这三件事提前处理好，剩下的就是等容器起来。

本文所有截图来自实际运行环境，命令输出未做修饰。环境为 Ubuntu 24.04.5 / Docker 29.1.3 / Nexent v2.8.2。