企业官网建设流程全解析

• AI Agent
• AI 应用
• 后端
• 前端
• 大模型
• RAG

本指南面向使用 Docker Compose 部署 Nexent 的运维与开发人员，系统讲解升级全流程：升级前的数据一致性备份、在线（fast-forward 拉取 + 脚本部署）与离线（离线包 +--reuse-from复用配置）两种升级路径，以及升级后的容器健康状态核查。读完本文，你将掌握 Nexent 官方推荐的"先备份、再升级、后校验"三步法，并能对照源码理解备份脚本的空间检查、SQL 自动迁移的校验和机制与级联重放逻辑等底层实现，具备独立完成一次生产级 Nexent Docker 升级的能力。

1. 升级前的检查与备份

1.1 适用范围与前置条件

本指南适用于以 Docker Compose 方式部署的 Nexent 环境。升级应尽量安排在空闲或低流量窗口执行。最关键的一条纪律是：备份开始前必须停止业务写入（用户操作、API 请求、定时任务等），但容器无需停止，不要执行docker stop或docker compose down。

⚠️ 如果复制期间业务仍在写入，PostgreSQL、Elasticsearch、Redis、MinIO 等组件的数据可能不处于同一时间点，备份可能无法恢复。

1.2 执行备份命令

在当前用于部署的 Nexent 仓库根目录下执行（离线部署则在之前解压的部署包根目录下执行），备份目录必须同时位于ROOT_DIR与NEXENT_USER_DIR之外：

bash deploy/docker/backup.sh --backup-dir /mnt/backup/nexent

该脚本有两个可识别参数：--backup-dir PATH（必填，备份所在目录）与--help|-h。脚本不会检测写入活动，也不会请求确认输入——停止业务写入完全依赖操作者的纪律。

1.3 脚本执行流程与输出解读

对照 deploy/docker/backup.sh 的源码，其执行主线为：parse_args → load_deployment_env → validate_backup_base → validate_docker → discover_volumes → validate_backup_layout_names → measure_sources → check_space → warn_writes_stopped → copy_files。关键行为如下：

• 读取部署环境：脚本从deploy/env/.env读取ROOT_DIR；若未显式设置NEXENT_USER_DIR，则使用部署默认值${HOME}/nexent（见load_deployment_env中的NEXENT_USER_DIR="${NEXENT_USER_DIR:-$HOME/nexent}"）。两个目录都必须存在且可读。
• 目录合法性校验：备份目录若位于ROOT_DIR或NEXENT_USER_DIR内部（或其子目录），脚本直接报错退出（validate_backup_base中的两条case分支）。
• Docker 前置检查：要求 Docker CLI 与 daemon 可用，且nexent-config容器处于运行状态；随后以nexent-config的镜像作为"备份辅助镜像"（BACKUP_HELPER_IMAGE），用于后续进入 named volume 进行 du/cp 操作。
• 卷发现：通过docker volume ls --filter label=com.docker.compose.project=nexent与=monitor收集命名卷，并去重（discover_volumes）。
• 名称冲突防护：ROOT_DIR与NEXENT_USER_DIR的目录名（备份后作为顶层目录名）以及各命名卷的名称之间不得重名，否则拒绝执行（validate_backup_layout_names）。
• 空间预检：脚本先打印ROOT_DIR、NEXENT_USER_DIR、本次部署使用的命名卷、未压缩数据总大小以及备份目录可用空间。文件不压缩，因此校验按原始大小计算。只有打印出[PASS] Pre-upgrade space check passed.才会开始复制；空间不足时打印[ERROR]并在复制前退出（check_space中AVAILABLE_SIZE_KIB -lt TOTAL_SIZE_KIB即fail）。

复制过程中请关注[INFO]进度消息。备份目录命名为docker-<UTC时间戳>（如docker-20261011-120000），其顶层保留源名称：两个主机路径使用各自目录名，每个命名卷使用卷名。例如默认部署会产生nexent-data/（来自ROOT_DIR目录名）、nexent/（来自NEXENT_USER_DIR）、nexent-agent-workspace/、nexent_db-config/等目录。

只有出现[PASS] Backup complete: <path>才表示备份完成，<path>为实际备份目录；若出现[ERROR]，不要使用脚本打印出的不完整目录（脚本在退出时也会提示Backup is incomplete. Inspect but do not use: <partial-dir>）。

1.4 备份脚本的工程约束（源码佐证）

deploy/tests/test_docker_backup.sh 以伪docker/du/df命令覆盖了上述全部路径，并明确断言脚本不得：

• 使用sudo（assert_not_contains ... "sudo "）；
• 创建 tar/gz/zip 等压缩归档或 SHA-256 校验文件（"tar "、"sha256"断言）；
• 停止容器或执行docker compose down（断言 fake docker log 中不含stop与down）；
• 提供写入确认交互（--confirm-writes-stopped被判定为未知选项）。

测试同样验证了：备份目录位于ROOT_DIR/NEXENT_USER_DIR内会被拒绝、源名称冲突会被拒绝、空间不足在复制前失败、复制失败不产生最终目录、未设置NEXENT_USER_DIR时回退到${HOME}/nexent。这些约束意味着备份是一个低成本、可重复、纯文件级的操作，正式升级前可放心执行。

2. 执行升级

说明：Nexent 的 Docker 升级入口统一为根目录deploy.sh（首次安装与升级共用同一入口）。仓库中的 deploy/docker/upgrade.sh 已标记为 deprecated 的兼容包装器，仅转发到deploy/docker/deploy.sh，升级请直接使用根入口。

2.1 在线升级

在可访问 GitHub 与所需镜像仓库的环境中，从当前 Nexent 仓库执行在线升级。先确认当前分支与目标版本，再以fast-forward only方式更新代码，不要用未记录的latest值替代具体版本号：

git branch --show-current git pull --ff-only bash deploy.sh docker --defaults --version X.Y.Z

各步骤要点：

• git pull --ff-only保证只做快进合并，避免出现未预料的合并提交；
• bash deploy.sh docker是根入口，内部转发到 deploy/docker/deploy.sh；--version X.Y.Z显式指定应用版本，否则脚本按 deploy/common/version.sh 的deployment_read_version自动探测：优先VERSION文件首行，其次backend/consts/const.py中的APP_VERSION，最后回退为latest。当前仓库 VERSION 记录为v2.7.0；
• --defaults复用已保存的部署配置并跳过交互界面。升级前务必确认deploy/docker/deploy.options存在，且其中的组件、端口策略与镜像源与当前环境一致（非敏感选择在部署成功后即写入该文件）。

在线部署的完整背景（组件选择、端口策略、镜像源、HTTPS 等）参见 Docker 安装与部署（对应仓库路径 installation.md）。

2.2 离线升级

当目标主机无法访问公共镜像仓库时，按 Docker 离线部署 下载与服务器架构匹配的目标版本离线包，拷贝到目标主机并解压到新目录：

unzip nexent-<version>-amd64.zip -d nexent-<version> cd nexent-<version> bash deploy.sh \ --reuse-from /path/to/previous/nexent \ --load-images \ --defaults \ docker

关键语义：

• /path/to/previous/nexent必须是之前解压部署包的真实根目录，且其中包含deploy/env/.env；
• --reuse-from复用旧包的.env、monitoring.env与 Docker 部署选项：根入口 deploy.sh 的reuse_deployment_files会先校验源目录存在且与当前包目录不同、.env可读，然后复制.env并依据当前包的deploy/env/.env.example自动补充新引入的变量（deployment_merge_env_from_example），随后按需复用deploy/env/monitoring.env与deploy/docker/deploy.options；
• --load-images从新包./images目录加载镜像 tar 文件（默认关闭，离线升级必须显式开启）；
• ARM64 服务器使用对应的nexent-<version>-arm64.zip包。

2.3 升级过程中的数据库迁移机制

升级期间，nexent-config容器会运行自动数据库迁移，其余后端容器则等待迁移到达目标状态后才继续启动。这正是 deploy/common/run-sql-migrations.sh 的两种运行模式：

• migrate模式（nexent-config执行）：使用pg_advisory_lock加锁，按版本感知文件名排序（sort -V）收集deploy/sql/migrations下所有*.sql，逐条比对nexent.schema_migrations表中记录的校验和；无记录则执行并记为applied，校验和相同则跳过，校验和不同则重放（append_one_migration_sql）；
• wait模式（其余后端容器执行）：轮询比对期望的(migration_id, checksum)集合与表内实际记录，全部匹配且状态为applied/baselined时返回ready（run_wait_mode），超时默认 300 秒（NEXENT_SQL_MIGRATION_WAIT_TIMEOUT_SECONDS）。

级联重放规则（见 deploy/sql/migrations/README.md）：一旦某个文件因校验和变化被重放，本次会话内其后的所有文件都会被强制重放——即使自身校验和未变。原因是链前部的破坏性语句（如DROP COLUMN）可能把 schema 回滚到后续文件所补偿的旧状态，跳过会导致数据不一致。因此：

已合并的 SQL 文件（v*.0_merged_migrations.sql等）不得修改、重命名或删除。哪怕只改动注释也会触发级联，导致其后所有文件在大型合并上被长时间重放。合并之后的新变更应使用新的独立版本化文件（如v2.6.0_xxxx_*.sql）。

3. 升级后检查

升级完成后，分别检查 Nexent 与可选监控项目的容器健康状态：

docker ps -a --filter label=com.docker.compose.project=nexent \ --format 'table {{.Names}}\t{{.Status}}' docker ps -a --filter label=com.docker.compose.project=monitor \ --format 'table {{.Names}}\t{{.Status}}'

判定标准：

• 通过：每个配置了 healthcheck 的容器均报告healthy；
• 等待：仍有容器处于starting，继续等待；
• 失败：任一容器报告unhealthy。

未配置 healthcheck 的容器不会报告healthy，它们不在本检查范围内。以 deploy/docker/compose/docker-compose.yml 为例，Elasticsearch 与 Redis 均配置了 healthcheck（分别探测_cluster/health的green|yellow状态与redis-cli ping），而部分服务可能不配置，属正常现象。

4. 升级前后的通用要点小结

• 备份与升级分步确认：以[PASS] Backup complete:与升级脚本正常退出为两段完成的标志；备份目录命名含 UTC 时间戳，便于多版本回滚追溯。
• 版本语义：显式指定X.Y.Z，避免latest；--defaults复用deploy/docker/deploy.options，首次交互部署的组件/端口/镜像源选择都会保存在其中，升级前应核对。
• 迁移纪律：不要在已部署后改动任何*_merged_migrations.sql；新变更走新文件；deploy/sql/init.sql每次启动都会无条件执行（不参与级联），其语句必须保持幂等。
• 回滚依据：备份保留了ROOT_DIR、NEXENT_USER_DIR与全部命名卷的原始目录/卷名结构，若升级后健康检查不通过，可直接用该备份目录对照恢复（具体恢复流程建议结合部署拓扑在测试环境先行演练）。

以上流程与脚本行为均可在当前仓库的部署脚本（deploy/docker/backup.sh、deploy.sh、deploy/docker/deploy.sh）、迁移运行器（deploy/common/run-sql-migrations.sh）与测试用例（deploy/tests/test_docker_backup.sh）中得到验证，可作为升级排障与二次开发时的权威参考。

• AI Agent
• AI 应用
• 后端
• 前端
• 大模型
• RAG