部署与运维 | Nexus 文档

部署前准备

服务端推荐使用 Docker Compose。准备可运行 Docker 与 Compose 插件的服务器、持久数据磁盘，以及可以访问模型服务的出站网络。对外服务还需要域名和 HTTPS 网关。

nexus 与 nexus-control 放在同一父目录。Control 管理服务端身份，Nexus 管理 Agent、会话、工作区与运行时。

git clone https://github.com/nexus-research-lab/nexus.git
git clone https://github.com/nexus-research-lab/nexus-control.git
cd nexus
cp env.example .env

配置首次启动

编辑 .env，至少配置管理员密码、Control 服务令牌和持久数据目录。以下示例列出主要字段，密码和令牌需替换为自行生成的值。

AUTH_INIT_OWNER_USERNAME=admin
AUTH_INIT_OWNER_PASSWORD=replace-with-a-strong-password
CONTROL_SERVICE_TOKEN=replace-with-a-random-token
HOST_DATA_DIR=./data
HTTP_PORT=80
NO_PROXY=localhost,127.0.0.1,::1,control,nexus,nginx

使用 openssl rand -hex 32 生成服务令牌并填入配置。不要把示例占位值作为真实密码或令牌。

CONNECTOR_CREDENTIALS_KEY 是用于加密连接器和 IM 凭据的 32 字节随机值的标准 Base64 表示。Docker 留空时会生成并持久化；显式配置时可用 openssl rand -base64 32 生成，并把这份配置纳入安全备份。

启动和检查

make start
make logs

打开服务器地址，使用初始化账号登录。完成模型服务配置，执行第一份文件任务，并验证刷新后会话与文件仍可读取。

部署验证包括登录、模型调用、运行时启动、工具审批与文件交付。停止服务使用 make stop，不要用删除数据卷代替停止。

分层验收部署结果

make start 会构建并启动服务。命令结束后，继续检查容器状态与真实任务，不仅看进程是否存在。

make status

层次	检查动作	成功结果
服务	查看状态与启动日志	服务没有持续退出或重启
身份	使用初始化账号登录	能进入自己的工作台
模型	配置并测试具体模型	普通请求获得有效响应
运行时	发起文件读取与写入任务	工具能执行，审批能处理
持久化	刷新后重新打开会话与文件	历史和文件仍可读取
网络入口	从实际使用的域名访问	登录和实时消息保持正常

后端日志使用 make logs，需要查看其他服务时使用 make logs-all；入口问题查看 make logs-nginx。这些命令会持续跟随日志，按 Ctrl+C 结束查看，不会停止服务。

遇到失败从所在层继续检查。例如网页能打开但无法登录，先看 Control 与认证路径；能登录但任务启动失败，再看模型、运行时和文件权限。

使用 Web 首次初始化

如果不设置 AUTH_INIT_OWNER_PASSWORD，可配置至少 32 字符的 CONTROL_SETUP_TOKEN，启动后访问 /setup 完成首个 owner 初始化。

Setup code 只用于建站，不要放进公开链接、日志或浏览器存储。已有 owner 后，修改初始化环境变量不会重新初始化账号。

配置生产入口

默认 Compose 暴露 HTTP。由外层反向代理或负载均衡终止 TLS，并正确转发 HTTP、WebSocket 与同源认证路径。根据实际域名配置 ALLOWED_WEBSOCKET_ORIGINS；HTTPS 部署检查 AUTH_COOKIE_SECURE 等 Cookie 设置。

使用 OAuth 连接器时，CONNECTOR_OAUTH_REDIRECT_URI 必须与平台登记的回调完全一致，并配置允许来源。不要公开暴露仅供内部使用的 Control 接口、数据库或运行时服务。

数据和代理

HOST_DATA_DIR 指向需要持久保留的宿主数据位置，Compose 将其中的 .nexus/ 挂载为状态根。状态根中 app/ 保存 Nexus 宿主数据，control/ 保存 Control 状态，control-public/ 保存公钥镜像，users/ 保存用户文件与运行时状态。更完整布局见备份指南。

服务端出站可以使用 HTTPS_PROXY 等标准变量。Docker 的回环地址指向容器自身；入口支持宿主代理改写，但仍应检查最终连通性。NO_PROXY 保留内部服务名，避免内部请求绕到外部代理。

配置变更如何确认生效

记录修改前的值和受影响服务，再更改配置并按部署方式重建相关服务。环境文件已经保存不代表正在运行的容器已采用新值。

更改模型出站代理后，验证一次真实模型调用；更改域名后，验证登录、实时消息和 OAuth 回调。不要只检查网页首页，它不能覆盖后端出站与认证链路。

使用 Relay 或 Atlas 等 Compose 覆盖层的部署，检查、重建和重启都必须保留相同的覆盖层组合及环境文件。不能用较短的基础 Compose 命令重建共享入口，导致原有路由或服务配置丢失。

固定一次可恢复的升级

记录 Nexus、Control 的代码版本或镜像标签，并保存当前部署配置。先完成一致备份，再升级。测试新版本时依次验证登录、文件任务和需要的连接器，最后恢复定时与消息工作。

如果升级失败，保留新环境的错误信息及数据副本。恢复旧版本时使用升级前的匹配数据，不把新数据库直接交给旧程序尝试写入。

升级和单实例边界

升级前停止写入并完整备份，再按目标版本说明更新代码或镜像，启动后执行同一套登录与小任务验证。回退需要匹配升级前的数据版本。

同一数据库建议只运行一个后台 worker。IM 轮询、Gateway 和长连接可能在多副本间争抢；增加副本前需解决这些服务的独占运行要求。运行时隔离要求见运维文档。