我在 Mac 上用 Docker 部署 Nexent：从拉取镜像到接入模型

这次直接在自己的 Mac 上跑起 Nexent，完成部署和租户初始化，再接入一个大语言模型。服务运行在 Docker Desktop 里，可以从浏览器直接访问；没有用云服务器，也没有配置公网域名或端口转发。

部署中间卡了两次。第一次 Supabase 镜像连接超时；第二次 Supabase 已经启动，Nexent 核心镜像却在腾讯云仓库找不到 v2.8.0。两次都发生在拉镜像时，处理办法却不一样。最后我保留已启动的服务，换到有对应版本的镜像源，才把平台跑起来。

先看 Mac 和 Docker 环境

动手前我先在终端看了 macOS 版本、CPU 架构和 Docker 版本。我的 Mac 是 arm64，Docker Engine 为 24.0.6，Compose 为 v2.23.0。Nexent 支持 ARM64，Docker 和 Compose 版本也符合仓库 README 的要求。

sw_vers
uname -m
docker version
docker compose version

docker version 会同时显示 Client 和 Server。只有客户端版本并不能说明 Docker Desktop Engine 已经启动，所以我也确认了 Server 信息正常返回。先把这几个版本记下来，后面排错时就能先排除架构或 Docker 版本不符。

确认本机环境后，我再对照 Nexent 官方列出的系统要求。README 中 Docker 部署最低需要 4 核 CPU、8 GiB 内存和 40 GiB 磁盘，并支持 ARM64。Docker 版本要求有一处不一致：README 写 24+，安装文档写 Engine 18.09+。我按较新的 README 要求准备，实际使用 Docker 24.0.6。

我的 Mac 总内存是 16 GB，但 Docker Desktop 要单独分配 Linux Engine 能用的资源。我把 CPU 调到 8 核、内存调到 10 GB，应用设置并重启。重启后用 docker info 检查，Engine 可用内存显示为 9.711 GiB；系统盘还有约 180 GiB。3000 端口也没有其他进程监听，Web 入口可以使用默认端口。

docker info | grep -E 'Server Version|Operating System|Architecture|Total Memory'
df -h /
lsof -nP -iTCP:3000 -sTCP:LISTEN

最后一条命令没有输出，表示当时没有进程监听 3000 端口。Engine 可用内存高于官方最低值，磁盘空间也够，我才继续拉代码。这样如果后面安装失败，可以先把注意力放到部署和镜像环节。

固定版本后开始部署

我从 AtomGit 克隆 v2.8.0 标签，没有直接使用持续变化的开发分支：

time git clone --depth 1 --branch v2.8.0 \
  https://atomgit.com/ModelEngine/nexent.git ~/nexent-quickstart
cd ~/nexent-quickstart
cat VERSION
git rev-parse --short HEAD

仓库下载约 93.41 MiB，速度约 10.81 MiB/s，命令耗时 11.518 秒。VERSION 输出 v2.8.0，提交短哈希为 f116427。固定版本后，代码和部署时请求的镜像 tag 能对应起来，排错时不必再猜是不是开发分支更新造成的差异。

部署前我先复制环境模板并修改超级管理员密码。这个文件还包含数据库等服务的配置，应留在本机，不要提交到公共仓库。

cp deploy/env/.env.example deploy/env/.env
vim deploy/env/.env

我在文件中把 NEXENT_SUPER_ADMIN_PASSWORD 改为自己的临时密码。默认超级管理员密码是公开信息，本地体验也建议先改掉。修改后回到仓库根目录运行部署入口：

bash deploy.sh docker

组件页面默认选中了 infrastructure、application、data-process 和 supabase，我保留了这四组。它们分别负责基础数据库和对象存储、Nexent Web 与后端、文件处理，以及用户登录和租户权限。第一次部署要完成登录和创建租户，这些服务都需要启动。

terminal 和 monitoring 是可选组件，我这次没有勾选。当前目标是先确认平台能启动、账号能登录，暂时用不到终端工具和额外观测服务。少拉一些镜像，也能少等一会儿。组件确认后，安装器继续让我选择端口策略。

本机端口和镜像选择

我选 development，方便在自己的 Mac 上调试。这个策略会把 Web 和更多调试、内部服务端口映射到主机；production 则只发布生产入口端口。部署汇总中，这次选择的组件需要检查 17 个端口。

我选 development 是因为服务只部署在本机，没有云服务器、域名或端口转发。这次浏览器通过 localhost:3000 打开；我没有测试局域网中其他设备能否访问。Docker 会把服务端口映射到 Mac 主机，所以"本地运行"不代表端口只绑定在 127.0.0.1。线上部署不要照搬本地调试策略，应选 production，再通过云安全组和主机防火墙只开放必要的 Web 或 HTTPS 入口。

镜像源我先选 mainland，想优先从国内镜像站拉 Nexent。界面还提供 general 和 local-latest：mainland 指向腾讯云仓库，general 使用常规公共镜像仓库，local-latest 使用本机已有的 latest 镜像。最后一种不保证与 v2.8.0 一致，这次不适合固定版本复现。

mainland 改变的是 Nexent 应用镜像的来源，不代表整套部署中的每个容器都走同一个仓库。实际运行时，Supabase 和 Nexent 核心应用使用不同 Registry。我原先以为选择 mainland 后依赖镜像也会统一走国内源，后面才发现要根据具体服务的仓库地址和 tag 判断。

沙箱模式我保留默认的 lightweight。disabled 会使用本地执行模式，不启用 Docker 沙箱；full 会额外包含文档、设计、前端和 MCP 技能依赖。这次只做快速入门，没有用到这些扩展技能，先让平台本身跑起来。

lightweight 足够这次部署使用。沙箱决定智能体代码和 Skill 的执行环境，不会决定 Web 页面能不能打开或租户能不能登录；后面要验证文档、前端或 MCP 技能，再考虑 full。安装器接着询问 HTTPS 模式。

HTTPS 保持默认的 disabled，本机先通过 HTTP 访问。启用 HTTPS 会增加 Nginx 反向代理服务和独立入口；这次没有域名或远程访问需求，我就没有配置证书。

线上部署还要准备证书、核对登录回调地址和入口端口，并检查云安全组与主机防火墙。本地页面能打开不能替代这些验证。确认入口方式后，脚本询问 ROOT_DIR，也就是宿主机保存运行文件和持久化数据的位置，我沿用默认目录。

数据库、Elasticsearch、MinIO 等运行状态会保存在 ROOT_DIR 对应的目录或 Docker volume 中。第一次拉镜像失败时，我保留了已启动的基础设施和数据卷，没有运行卸载或 delete-all。拉镜像失败不能说明数据库坏了，贸然删卷反而会把已经初始化的数据一起删除。

两次镜像故障

第一次部署时，Redis、Elasticsearch、PostgreSQL 和 MinIO 都启动了；接下来 Supabase 的 auth、kong、db 拉取失败。错误信息指向 docker.m.daocloud.io 的 TLS handshake timeout，整条命令耗时约 22 分 35 秒。Nexent 核心服务还没开始启动，所以我先查镜像仓库连接，没有去改模型或登录配置。

我先单独检查 DaoCloud Registry 的 HTTPS 入口，看看当前网络能不能完成 TLS 握手：

curl -I --connect-timeout 10 --max-time 20 https://docker.m.daocloud.io/v2/

后续检查返回 HTTP 401，并带有 WWW-Authenticate 响应。对 Registry 的 /v2/ 根路径来说，这是未认证请求收到的认证挑战，说明这次 TLS 连接已经建立；它不是镜像拉取失败，也和 Nexent 网页登录错误不是一回事。

这次检查发生在首次超时之后，只能说明后来可以连接，不能反推第一次拉取时的网络状态。如果遇到同样的 TLS 超时，先确认 Docker Desktop 正在运行，再检查当前网络或代理，并用 curl 复测。稍后重试也可能恢复；如果 DaoCloud 持续超时，而 Docker Hub 可以访问，可以运行：

bash deploy.sh docker --image-source general

提示复用已有部署配置时选择复用，组件、端口和沙箱设置都能保留。如果 Docker Hub 和其他在线仓库都不可访问，Nexent 安装文档还提供按架构下载的 ARM64 离线部署包；解压后在离线包根目录运行 bash deploy.sh --load-images docker。这个分支我本机没有实测，下载时要确认版本和 ARM64 架构匹配。

网络恢复后我重新运行部署，Supabase 和基础设施都启动了，但 Nexent 六个核心服务还是没起来。这次返回的不是 TLS 超时，而是腾讯云仓库的 manifest unknown：请求的 nexent:v2.8.0 tag 没有找到。前一次是连接没完成，这一次是已经连上仓库但仓库中没有指定 tag。

manifest unknown 时反复重试同一个仓库和 tag 通常不会有帮助。可以等该版本同步到腾讯云，或者换到确实存在 v2.8.0 的镜像源。我选择 general，保留已经启动的基础设施和数据卷，只切换应用镜像源：

bash deploy.sh docker --image-source general --refresh-es-key

如果没有把 Elasticsearch API Key 发到日志或共享记录里，切源本身可以简化为 bash deploy.sh docker --image-source general。这次日志曾打印 Elasticsearch API Key，所以我加了 --refresh-es-key 重新生成。提示复用本地部署配置时，我选择复用；组件、development 端口策略和 lightweight 沙箱都保留，只覆盖镜像源。general 能连接 Docker Hub 后，六个核心服务顺利启动，脚本还拉取了 MCP 和沙箱镜像。Supabase 和基础设施没有重新清空。

部署脚本给出的地址是 localhost:3000。我直接在本机浏览器打开，开始验证登录和租户初始化。

登录并创建租户管理员

我使用 suadmin@nexent.com 和 deploy/env/.env 里设置的密码登录。超级管理员用于平台级管理，不能直接创建智能体或知识库；接下来还要创建租户和租户管理员。

登录后我进入租户资源，创建 acowbo 租户，并打开"立即生成租户管理员账户"。这样创建租户时会同时生成管理员账号。"自动安装官方技能"保持关闭，这次先不增加技能安装环节。管理员密码只保存在本机。

创建完成后，我退出 suadmin，再用生成的租户管理员账号登录。租户管理员负责该租户中的模型、知识库和智能体资源，与平台级超级管理员是不同角色。

工作台左侧出现了模型配置、知识库配置和智能体配置等入口；聊天区域提示暂无可用模型。下一步需要接入模型，才能开始对话测试。

添加大语言模型

进入模型配置后，我看到可以手动添加单个模型，也可以从服务商批量导入。批量导入会请求服务商的模型列表；单个添加则要手动填写服务商、模型类型、模型 ID、Base URL 和 API Key。模型 ID 和地址要按服务商文档填写，不能只因为都兼容 OpenAI 接口就互相照搬。

我先试批量导入：选服务商、填写 API Key，再点"获取模型列表"。这一步会请求服务商的模型列表；请求返回 401，页面弹出"登录已过期"。重新登录后再次点击，结果还是一样。

后来我查了 v2.8.0 的调用逻辑：模型服务商返回的 HTTP 状态会由 /model/provider/create 传回前端，而前端把所有 HTTP 401 都显示成登录过期。因此单看弹窗不能确定 Nexent 会话真的过期，也可能是服务商拒绝了 API Key 或请求地址。这个 401 来自模型列表接口，和前面 DaoCloud Registry 的认证挑战不是同一个问题。

要区分这两种情况，可以在浏览器开发者工具的 Network 中找到 POST /api/model/provider/create，看 Response 里的 detail。若提示 API Key 无效或服务商认证失败，就检查服务商、API URL 和 Key；若提示 token expired 或 authorization header missing，再排查 Nexent 登录会话。不要复制 Request Payload、Cookie 或 Authorization，它们可能包含凭证。我当时没有保存 Response 正文，所以不能确认自己的 401 属于哪一种。

之后模型库出现了 glm-5.3-flash，来源显示 OpenAI-API-Compatible，状态为"可用"，并带有默认标记。这先证明模型配置已经保存并通过可用状态检查。

我又回到工作台，选用 glm-5.3-flash 发起了一轮对话。界面进入 Reasoning/Thinking，并显示一次工具调用；这说明模型请求确实运行到了推理阶段，也触发了工具调用。

这张记录停在推理过程中，没有显示最终答复，所以我用它证明模型被调用和工具调用已发起，不评价最终回答是否完整或正确。

本地体验和线上部署

这次在 Mac 上完成了 Nexent v2.8.0 部署、超级管理员登录、租户管理员创建和模型入库。服务通过 Docker Desktop 运行，浏览器访问 localhost，没有用云服务器，也没有配置公网域名或端口转发。

Nexent 仓库：https://atomgit.com/ModelEngine/nexent

官方文档：https://modelengine-group.github.io/nexent/zh/

线上部署不能照搬这次的 development 端口策略。应使用 production，确认服务只发布需要的入口端口，通过云安全组和主机防火墙限制访问；公网访问要配置 HTTPS，并更换默认凭证、保护 API Key，安排数据库和文件数据备份。本次没有测试公网访问、生产认证配置或备份恢复。