# 部署与运维

使用 Docker Compose 部署，配置账号、数据目录与网络入口。

## 部署前准备

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

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

```bash
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 服务令牌和持久数据目录。以下示例列出主要字段，密码和令牌需替换为自行生成的值。

```dotenv
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` 生成，并把这份配置纳入安全备份。

## 启动和检查

```bash
make start
make logs
```

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

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

## 分层验收部署结果

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

```bash
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/` 保存用户文件与运行时状态。更完整布局见[备份指南](/docs/backup)。

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

## 配置变更如何确认生效

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

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

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

## 固定一次可恢复的升级

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

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

## 升级和单实例边界

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

同一数据库建议只运行一个后台 worker。IM 轮询、Gateway 和长连接可能在多副本间争抢；增加副本前需解决这些服务的独占运行要求。运行时隔离要求见[运维文档](https://github.com/nexus-research-lab/nexus/tree/main/docs/operations)。