部署与初始化
一次安装选定模块和算法套件,用 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-admin | on(默认)会在核心首次启动时创建默认账号 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、授权、模型设置和模块面板)在服务端一律拒绝。改密之后,其他会话全部失效。
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。
恢复演练
交付时请完成一次恢复演练,并记录结果:
- 在原环境签发一把专用的 Agent Key,保存为文件。
- 执行备份,在另一台主机(或清空的主机)上恢复。
- 确认报告里
verify_restore.ok为true,sample_key_status为200。 - 用原管理员账号(含 TOTP)登录控制台,核对授权和模块状态,每个模块各做一次 Agent 调用。
- 撤销演练用的 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,启用前请核实其中的镜像标签。