部署与初始化

一次安装选定模块和算法套件,用 docker compose 启动。只有 Nexus Core 对外发布端口,模块都在内部网络里。

安装包里的部署目录是 deploy/nexus。它是一个 compose 工程,包含 Nexus Core(带统一控制台)、PostgreSQL、一次性的数据库初始化任务,以及五个模块服务:数脉、知汇、运枢、联枢、研枢。每个模块服务属于同名的 compose profile,装哪个就启动哪个。

准备什么

  • 主机:Linux,x86_64 或 aarch64,内核 5.4 以上,建议 cgroup v2。需要 root 权限运行安装脚本。Docker Desktop 和 rootless Docker 不在支持范围内。
  • Docker 与 compose:Docker Engine 24.0 以上,Compose 插件 2.24 以上。
  • 容量:全部模块都装时,建议至少 8 核、16 GB 内存。各容器的默认资源上限在安装后写入 .env 的注释行里,取消注释即可调整。
  • 对外域名与证书:控制台和 Agent 接口走同一个端口。正式使用时请在前面放一层自己的 TLS 终止,见下文「反向代理与 TLS」。
  • 主机时间:请保持时间同步。许可证的到期判断依赖主机时间。

安装

在部署目录所在的主机上运行安装脚本。下面的例子安装国密套件和四个模块,并且不创建默认账号:

sudo sh deploy/nexus/install.sh --suite sm --modules warehouse,knowledge,ops,integrations \
  --public-origin https://nexus.example.com --default-admin off

脚本会写入 deploy/nexus/.env 和 deploy/nexus/secrets/ 下属主只读的秘密文件。重复运行不会覆盖已有的秘密。

参数含义
--suite算法套件,安装时确定。international 使用 Ed25519、SHA-256、AES-256-GCM;sm 使用 SM2(含签名者 ID)、SM3、SM4-GCM。套件写入数据库后不能靠改配置切换,核心发现不一致会拒绝启动。需要切换时见下文「切换算法套件」。国密套件可再加 --sm2-signer-id 指定签名者 ID。
--modules要安装的模块,逗号分隔:warehouse(数脉)、knowledge(知汇)、ops(运枢)、integrations(联枢)、engineering(研枢)。只装核心写 ""。
--public-origin浏览器访问控制台时使用的完整地址(协议、主机名、端口),写入 NEXUS_PUBLIC_ORIGINS。不写时默认是 http://127.0.0.1:8080。
--default-adminon(默认)会在核心首次启动时创建默认账号 admin,密码 admin;off 不创建默认账号,改用一次性凭据初始化首个管理员。生产环境建议写 off。
--port、--bind核心发布的端口和绑定地址。默认只绑定 127.0.0.1:8080。
--start安装后直接启动,并等到核心健康。不写这个参数时,自己运行下一节的启动命令。

以后加装或卸载模块,改 --modules 的列表再运行一次:

sudo sh deploy/nexus/install.sh --modules warehouse,ops
docker compose -f deploy/nexus/compose.yaml up -d

卸载一个模块时,把它从列表中去掉,并在 up -d 后面加 --remove-orphans。该模块上的授权会自动进入「模块未安装」状态。

deploy/nexus/secrets/core/master_key 能解开所有静态加密的凭据,包括签名私钥、TOTP 种子和模型 Key。它丢失后无法恢复,请另行加密保管。

启动

docker compose -f deploy/nexus/compose.yaml up -d

只有 core 发布宿主端口,默认是 127.0.0.1:8080,承载控制台和 Agent 接口。模块服务不发布任何宿主端口,只在内部网络里被核心调用,访问你的业务系统时走单独的出站网络。PostgreSQL 和核心的内部端口 8081 也只在内部网络里。

每次 up 都会运行一次数据库初始化任务:缺少的数据库角色和 schema 会被创建,口令从秘密文件同步。

首次登录与初始化管理员

用浏览器打开 --public-origin 指定的地址。有两种初始化方式,由安装时的 --default-admin 决定。

默认账号(--default-admin on)

核心首次启动且还没有任何账号时,会创建账号 admin,密码 admin。首次登录只会出现「修改初始密码」页面:输入当前密码和至少 12 位的新密码。改密之前,控制台的其他功能(包括 Agent、Key、授权、模型设置和模块面板)在服务端一律拒绝。改密之后,其他会话全部失效。

改默认密码之前,不要把控制台端口暴露到不受信任的网络。任何能访问控制台的人都可以用 admin / admin 登录并抢先设置密码。安装脚本默认只绑定 127.0.0.1:8080,请在本机或经 SSH 隧道完成改密,再配置对外的 TLS 终止。

一次性凭据(--default-admin off)

不创建默认账号。登录页会显示「首次部署?初始化管理员」,用 deploy/nexus/secrets/core/bootstrap_credential 里的一次性凭据创建首个平台管理员。凭据用后作废,密码由本人设置,不再强制修改。

也可以在安装之后、核心首次启动之前,把 .env 里的 NEXUS_DEFAULT_ADMIN 改成 off。已经有账号的部署,无论这个开关怎么设,都不会再创建默认账号。

管理员之后在控制台「管理员账号」里添加的账号,同样要求持有人首次登录先修改初始密码。

接下来做什么

  • 在「概览 › 系统状态」确认已安装的模块在线。没装的模块在控制台、授权编辑器和 Agent 目录里都不出现。
  • 在「模型设置」添加模型连接:DeepSeek、通义千问、Kimi、智谱 GLM、豆包,或任意 OpenAI 兼容接口。Key 按部署套件加密保存,可以按用途分别指定。内网或本机的模型需要在 .env 的 ECHOMIND_EGRESS_ALLOW 里放行。
  • 在「接入中心 › Agent 与密钥」创建 Agent、签发 Key,在「接入中心 › 授权管理」按模块资源授权,再按「接入中心 › 接入帮助」把地址和 Key 配到智能体里。步骤见接入智能体和授权、审批与审计。
  • 在左侧「模块」打开各模块面板,接入你的系统。下面几项需要先改 .env,改完后运行 docker compose -f deploy/nexus/compose.yaml up -d。
模块接入时要注意
数脉在面板里登记数据源。JDBC 数据源需要 Java 17 运行时和驱动 JAR,由你挂载,不随镜像提供。
知汇在面板里登记文库来源。本地目录需要先写进 ECHOMIND_KNOWLEDGE_LOCAL_ROOTS,并挂载为只读卷。
联枢在面板里登记上游。上游的来源要列入 ECHOMIND_INTEGRATIONS_ALLOWED_ORIGINS;没有 TLS 的内网上游还要列入 ECHOMIND_INTEGRATIONS_INSECURE_ORIGINS。
运枢在面板里新增连接,直接填写 SSH 私钥、主机公钥,或 Kubernetes 的 CA 和 Token。它们加密保存,只写不读。
研枢访问 GitLab、禅道、Jenkins 等研发系统,走出站网络。

模块访问私网地址时,该地址需要列入 ECHOMIND_EGRESS_ALLOW。

反向代理与 TLS

建议在核心前面放你们自己的、负责 TLS 终止的反向代理,由你们维护代理、证书和补丁。国密 TLS 由铜锁(Tongsuo)网关承担。

部署目录里有一份 nginx 示例 deploy/nexus/examples/nginx.conf。它是需要按环境修改的示例,不是经过验证的交付物。接入时有几件事要对上:

  • NEXUS_PUBLIC_ORIGINS 必须和浏览器实际使用的地址完全一致,包括协议、主机名和端口。
  • NEXUS_TRUSTED_PROXIES 写代理地址,且只写代理。不写时核心忽略 X-Forwarded-Proto 和 X-Forwarded-For,会把请求当作明文 http,登录限流和审计记录里看到的也都是代理的地址。
  • 代理只转发到核心的 8080,不要转发模块服务的端口或 8081。
  • 修改 .env 后,重新运行 docker compose -f deploy/nexus/compose.yaml up -d。

备份、恢复与恢复演练

备份

sudo sh deploy/nexus/backup.sh --passphrase-file /root/nexus-backup-passphrase [--out /backup/nexus]

这是冷备份,需要停机几十秒到几分钟:停止核心和模块服务,记录数据库清单,停止 PostgreSQL,归档全部数据卷,再把 .env 和 secrets/ 打包,用部署套件在口令派生的密钥下单独加密,最后重新启动。口令文件属主只读、至少 16 个字符,请单独保管,不要和备份放在一起。需要跨 PostgreSQL 大版本迁移时,加 --logical 另导出逻辑备份。

备份不包含 S3 兼容对象存储里的桶。如果知汇和联枢的文件放在对象存储,请用对象存储自己的版本控制或复制,并让桶与数据卷备份处在同一个时间窗口。

恢复

# 新主机:解开同一发布版本的 deploy/nexus,把备份目录拷进来
sudo sh deploy/nexus/restore.sh --backup /backup/nexus/nexus-backup-<时间> \
  --passphrase-file <口令文件> --sample-key-file <演练 Key 文件>

恢复只写入空主机:已有 .env、secrets/ 或同名数据卷时会拒绝。脚本先校验备份文件,再恢复数据卷,然后只启动 PostgreSQL,逐表核对行数和摘要、校验审计链、确认恢复出来的主密钥能打开全部静态加密的凭据。这些都通过之后才启动全部服务。最后用演练 Key 访问核心,并把结果写入 restore-report-<时间>.json。

恢复演练

交付时请完成一次恢复演练,并记录结果:

  1. 在原环境签发一把专用的 Agent Key,保存为文件。
  2. 执行备份,在另一台主机(或清空的主机)上恢复。
  3. 确认报告里 verify_restore.ok 为 true,sample_key_status 为 200。
  4. 用原管理员账号(含 TOTP)登录控制台,核对授权和模块状态,每个模块各做一次 Agent 调用。
  5. 撤销演练用的 Key,把报告和核对结论归档。

切换算法套件

套件可以在国际(international)和国密(sm)之间切换,但这是一次有停机和后续动作的操作,请先备份,再安排窗口:

sudo sh deploy/nexus/backup.sh --passphrase-file <口令文件>
sudo sh deploy/nexus/switch-suite.sh --to sm --cutoff 2026-12-31T00:00:00+08:00 [--sm2-signer-id <ID>] [--dry-run]

--cutoff 是旧 Key 的截止时间,--dry-run 先演练不改动。脚本会停止服务并重新加密凭据,影响如下:

  • 全部静态加密的凭据,用新算法和新主密钥重新加密。旧主密钥另存为 master_key.<旧套件>.retired-<时间>,核对无误后可以删除。
  • 签名密钥轮换为新算法,旧公钥在发布窗口内继续保留。
  • 所有仍然有效的 Agent Key 被标记为「需重签」,有效期截至 --cutoff。截止前仍按原算法校验,截止后失效。请在截止日前在控制台为每个 Agent 重新签发 Key,并更新智能体里配置的 Key。
  • 控制台会话全部失效。
  • 审计哈希链开启新分段,新分段的第一条记录以新算法引用旧分段的最后一条,旧分段仍按原算法校验。
  • 许可证不受影响。许可证的签名与部署套件无关。

各模块自己保存的凭据(数脉数据源、知汇来源、联枢上游、运枢连接、研枢连接)按各模块自己的密钥加密。切换后旧值仍然可读,在下次保存时用新套件重新加密。想立即处理,平台管理员可以在控制台「概览 › 系统状态 › 凭据加密」点「按算法套件重新加密」,逐个模块给出结果;离线的模块会列为未处理,上线后再点一次。应答里的 unreadable 表示无法解密(例如密钥文件丢失),保持原样,需要在面板里重新填写。

日志与健康检查

核心和各模块输出 JSON 行日志,用 docker compose logs 查看,每个容器最多保留 5 个 50 MiB 的文件。核心的探针是 /healthz(存活)和 /readyz(就绪),模块是 /health。核心和模块还输出 Prometheus 指标,只在内部网络里可访问。部署目录里有一份示例 Prometheus 与告警规则的 compose 覆盖文件 compose.monitoring.example.yaml,启用前请核实其中的镜像标签。

进一步交流

带一件正在做的事来聊

告诉我们你想让智能体接哪一类系统。我们在演示环境里把这件事走一遍,再一起判断合不合适。