fix(deploy): 修复组件版本解析和安装升级验收流程

README.md

@@ -19,7 +19,7 @@ DEPLOY_ACCESS=domain DEPLOY_DOMAIN=demo.example.com DEPLOY_HTTPS=false ./start.s
 DEPLOY_ACCESS=domain DEPLOY_DOMAIN=demo.example.com DEPLOY_HTTPS=true CERTBOT_EMAIL=ops@example.com ./start.sh
 ```
 
-Linux IP 模式会自动安装并配置 Nginx，浏览器统一访问 `http://IP`。公网只需放行 TCP 80；前端、API、WebSocket 和 ASG 分别通过 `/`、`/api`、`/socket.io`、`/asg-api` 反向代理，容器上游端口默认仅绑定 `127.0.0.1`。
+Linux IP 模式会自动安装并配置 Nginx，浏览器统一访问 `http://IP`。公网只需放行 TCP 80；前端、API、WebSocket 和 ASG 分别通过 `/`、`/api`、`/socket.io`、`/asg-api` 反向代理，容器上游端口默认仅绑定 `127.0.0.1`。首次启动会初始化数据库和服务，核心容器默认有 180 秒启动宽限期，检查成功会立即通过；脚本等待所选服务恢复可用后才报告完成。可通过 `DEPLOY_HEALTH_TIMEOUT_SECONDS` / `UPDATE_HEALTH_TIMEOUT_SECONDS` 调整等待时限（默认 600 秒）。
 
 常用变量：
 
@@ -141,43 +141,43 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\start.ps1"
 
 
 ## 更新升级
-### 老用户（旧版本部署包）升级教程
+### 老用户原目录升级
 
-如果你当前使用的是较早版本的部署包，**无法在旧包目录里直接执行 `git pull`** 来获取配置文件，建议按下面流程升级：
+升级保留原安装目录、`.env`、`data/` 和 Docker 数据卷。**不要先执行 `docker compose down`、改名旧目录再重新安装，也不要删除数据卷。**脚本先核对现有容器的项目归属、数据库和上传目录的数据位置，再检查并拉取全部目标镜像，成功后才重建服务；失败会返回非零状态，不能把“收到更新请求”当作完成。
+
+升级前先做可恢复的数据库备份，并确认上传文件、Redis 持久化数据及凭据加密密钥已保留。脚本自动把升级前 `.env*` 和 Compose 配置备份到权限受限的 `data/deployment-backups/update-*`；**这份配置备份不包含数据库，也不能替代数据库备份**。升级不重置管理员密码或轮换已有合格安全密钥。配置中已有的自定义 Compose 项目名会保留；如果现有容器属于另一个项目，或数据库将从旧绑定目录/数据卷切换到另一位置，脚本会在拉取、重建前停止，避免误建空库。
+
+Git 安装的用户，在原目录执行：
 
-1. 先停止并下线旧项目容器：
 ```bash
 cd ~/easyai
-docker compose down
+./update.sh
 ```
-如果你的环境使用的是旧命令，请改用：
+
+默认读取官方远程发布源中的正式稳定版。Linux/macOS 和 Windows 均保留已有更新模式；没有 updater 的旧部署继续使用原模式，不强制切换。
+
+旧部署包没有 Git、或旧更新脚本无法自更新时，先把新版部署工具克隆到独立临时目录，再让工具在**原安装目录**迁移；不搬迁业务数据：
+
 ```bash
-docker-compose down
+# Ubuntu/Debian：仅旧包配置迁移需要 PyYAML
+sudo apt-get install -y python3-yaml
+TOOL_DIR=$(mktemp -d /tmp/easyai-upgrade-tool.XXXXXX)
+git clone --depth 1 https://git.51easyai.com/wangbo/easyai.git "$TOOL_DIR"
+UPDATE_PROJECT_DIR="$HOME/easyai" UPDATE_MODE=full UPDATE_NON_INTERACTIVE=1 \
+UPDATE_ADOPT_LEGACY_CONFIG=1 bash "$TOOL_DIR/update.sh"
 ```
 
-2. 将旧目录重命名备份（示例改名为 `easyai2`）：
-```bash
-cd ~
-mv easyai easyai2
-```
+请把示例中的原安装目录替换成实际路径。迁移先备份将被替换的配置与脚本，将旧 Compose 配置保存为私有覆盖文件，保留端口、数据卷和自定义配置；官方应用镜像改由发布记录选择。自定义镜像、额外覆盖链或无法安全识别的配置会阻止迁移，需要先核对差异。工具目录确认无用后可删除；不要删除原安装目录或备份。
 
-3. 重新执行一键部署命令，按脚本提示完成初始化输入。
-   如果希望跳过问答，可直接传入变量：
-   ```bash
-   DEPLOY_ACCESS=ip DEPLOY_IP=服务器IP ./start.sh
-   # 或
-   DEPLOY_ACCESS=domain DEPLOY_DOMAIN=demo.example.com DEPLOY_HTTPS=false ./start.sh
-   ```
+### 稳定版与指定版本
 
-4. 当脚本询问是否启用 HTTPS 时：
-   - 如果你之前已经有可用证书，填写 `N`（不生成新证书）。
-   - 只有在需要新申请证书时，才选择启用并生成证书。
+新安装、完整更新、仅镜像更新和页面更新默认共同读取官方远程 `system-update/release-manifest.json`，配套组件从匹配的产品记录及随部署工具提交的 `system-update/deployment-components.json` 独立基线解析。仅镜像更新无需先拉取 Git，也不会因本地清单过期而误报已是新版。自定义 `UPDATE_MANIFEST_URL` 的发布源应同时提供 `releases/<产品版本>.json`；离线部署设置 `UPDATE_MANIFEST_SOURCE=local`，由运维同步维护完整记录。主服务、网页、网关、Worker、updater、治理和记忆服务独立发布，**不能把同一个产品版本号拼到所有镜像后面**。managed 模式业务组件和固定配套组件持久化各自的 `tag@sha256`。旧 Watchtower 模式的默认更新保留核心服务官方 `latest` 稳定别名，并在拉取前后核对清单摘要，后续仍能自动获取新版稳定镜像；显式固定版本仅用于受控测试或指定版本操作。updater 默认也保留官方稳定 `latest`，继续接受原有自维护更新。保留旧 `VERSION=latest` 部署的升级入口；不把日常候选版本自动当作稳定版。
 
-5. 完成上述迁移后，后续若有新的配置文件或版本更新，可直接在新的 `easyai` 目录中执行 `./update.sh` 进行更新。
+新安装显式选取已登记产品版本可设置 `DEPLOY_RELEASE_VERSION=完整版本号`；升级可设置 `UPDATE_RELEASE_VERSION=完整版本号`。二者都按该产品记录选择组件，保留未变化的网关和 Worker 实际版本。单独测试某个组件时才使用 `UPDATE_SERVER_VERSION` 等参数，并通过 `UPDATE_SERVICES` 明确范围。缺失记录、错误标签、匿名拉取失败或平台不符会在重建前终止。
 
-日常发布只构建并推送完整版本标签，线上与测试环境均通过 `update.sh` / `update.ps1` 选择指定版本。`UPDATE_RELEASE_VERSION` 统一指定已选组件；`UPDATE_SERVER_VERSION`、`UPDATE_WEB_VERSION`、`UPDATE_GATEWAY_VERSION`、`UPDATE_WORKER_VERSION` 可分别指定已验证版本。脚本持久化 `SERVER_VERSION`、`WEB_VERSION`、`WS_GATEWAY_VERSION`、`MODEL_CONVERSION_WORKER_VERSION` 等到服务器 `.env`，保留非目标的原版本，拉取前核对有效 Compose 确实使用这些固定 tag。配置只能由已提交的部署仓库与迁移脚本更新，不手工修改服务器 `.env` 或 Compose/覆盖文件。
+日常发布只构建并推送完整版本标签，线上与测试环境均通过 `update.sh` / `update.ps1` 选择指定版本。`UPDATE_RELEASE_VERSION` 按产品记录选择已选组件；`UPDATE_SERVER_VERSION`、`UPDATE_WEB_VERSION`、`UPDATE_GATEWAY_VERSION`、`UPDATE_WORKER_VERSION` 可分别指定已验证版本。脚本持久化 `SERVER_VERSION`、`WEB_VERSION`、`WS_GATEWAY_VERSION`、`MODEL_CONVERSION_WORKER_VERSION` 等组件引用到服务器 `.env`，保留非目标的原版本，拉取前核对有效 Compose 确实使用这些固定 tag。配置只能由已提交的部署仓库与迁移脚本更新，不手工修改服务器 `.env` 或 Compose/覆盖文件。
 
-`latest` / `latest-no-ssr` 仅作为人工稳定版指针。只有用户明确指定版本转稳定版后才运行 `node scripts/promote-stable-release.mjs --version <版本> --confirm-version <同一版本>`（先 `--dry-run`），按固定产物 digest 复制稳定别名、读回并生成稳定清单，再审查和提交；日常 deploy 不调用此入口，也不修改稳定清单。该操作不重编业务镜像、不改业务环境版本。版本记录须包括独立 SSR/no-SSR 和实际使用的必要配套产物。
+`latest` / `latest-no-ssr` 仅作为人工稳定版指针。只有用户明确指定版本转稳定版后才运行 `node scripts/promote-stable-release.mjs --version <版本> --confirm-version <同一版本>`（先 `--dry-run`），按固定产物 digest 复制稳定别名、读回并生成稳定清单，再审查和提交；日常 deploy 不调用此入口，也不修改稳定清单。发布工具在修改稳定指针前会运行完整安装镜像预检；也可单独执行 `bash scripts/check-deployment-release.sh --version <产品版本>`。预检逐一验证默认安装所需镜像的匿名可访问性和 linux/amd64 平台，不拉取镜像层、不启动容器。该操作不重编业务镜像、不改业务环境版本。版本记录须包括独立 SSR/no-SSR 和实际使用的必要配套产物。
 
 update.sh 脚本用于自动更新 EasyAI 应用，包含以下功能：
 - **拉取整个仓库**：执行 `git pull` 获取最新代码（docker-compose.yml、start.sh、.env.*.sample 等全部文件）
@@ -187,7 +187,7 @@ update.sh 脚本用于自动更新 EasyAI 应用，包含以下功能：
 - 仓库版本发生变化时自动切换到拉取后的新版更新脚本继续执行，确保本次新增的迁移立即生效
 - 在重建服务前迁移并校验 `CONFIG_PUBLIC_API_BASE_URL`
 - 兼容 `docker compose` 和 `docker-compose` 两种命令格式
-- 自动拉取最新镜像并重启服务
+- 按正式稳定记录或显式选择的产品版本拉取镜像，随后重建服务
 - 等待主服务、Web 和 WebSocket 网关恢复可用后才报告成功；拉取失败、启动失败或恢复超时会明确报告失败
 
 新安装默认启用可查询进度的在线更新模式。管理员在页面发起更新后，即使主服务重启导致原请求断开，页面也会根据任务编号继续查询最终结果。存量部署如果没有 `easyai-updater` 容器，更新脚本会保留 Watchtower 模式；已经显式设置 `SYSTEM_UPDATE_MODE=legacy_watchtower` 的环境也保持该模式。只有新安装默认启用 updater。新模式只管理 `easyai-server`、`easyai-web` 和 `ws-gateway`，数据库、Redis、RabbitMQ 等基础服务仍按原部署流程维护。
@@ -207,11 +207,11 @@ WATCHTOWER_CORE_UPDATE_ENABLED=false
 WATCHTOWER_UPDATE_TARGET=easyai-updater
 SYSTEM_UPDATER_UPDATE_INTERVAL_SECONDS=86400
 UPDATE_HEALTH_TIMEOUT_MS=300000
-DOCKER_CONFIG_FILE=/root/.docker/config.json
+DOCKER_CONFIG_FILE=
 EASYAI_DEPLOYMENT_SCHEMA_VERSION=2
 ```
 
-`SYSTEM_UPDATE_INTERNAL_TOKEN` 由 `start.sh` / `update.sh` 自动生成并持久化，不需要手工填写。`UPDATE_HEALTH_TIMEOUT_MS` 控制每个核心服务替换后的恢复等待时间，默认 300000 毫秒。私有镜像仓库需要先执行 `docker login`；更新器与仅负责其自更新的 Watchtower 都会只读挂载 `DOCKER_CONFIG_FILE` 指向的 Docker 登录配置。切换后执行一次 `./update.sh`，确认 `easyai-updater` 以及三个核心服务均处于可用状态。
+`SYSTEM_UPDATE_INTERNAL_TOKEN` 由 `start.sh` / `update.sh` 自动生成并持久化，不需要手工填写。`UPDATE_HEALTH_TIMEOUT_MS` 控制每个核心服务替换后的恢复等待时间，默认 300000 毫秒。脚本优先复用现有 Docker 登录配置；匿名安装没有认证文件时自动建立权限受限的空配置文件，避免挂载源被创建成目录。私有镜像仓库需要先执行 `docker login`；更新器与仅负责其自更新的 Watchtower 都会只读挂载 `DOCKER_CONFIG_FILE` 指向的 Docker 登录配置。切换后执行一次 `./update.sh`，确认 `easyai-updater` 以及三个核心服务均处于可用状态。
 
 Watchtower 默认使用 `latest`。`start.sh/update.sh` 自动安装宿主机 cron，`start.ps1/update.ps1` 自动注册 Windows 计划任务；每六小时分别对 Watchtower 和已启用的 updater 执行 `docker compose pull <服务>`、`docker compose up -d --no-deps <服务>` 并确认健康状态。只在镜像或配置有变化时重建，拉取失败不会停止该服务的现有容器。一项维护失败仍继续处理另一项，日志保留各自结果并报告失败；因此 updater 的宿主机维护不依赖 Watchtower 可用。未启用 updater 的 legacy 部署跳过 updater，不自动切换更新模式。Watchtower 的 updater 24 小时更新计划保持不变，无需额外容器。Windows 任务使用当前登录用户，以便访问其 Docker Desktop；Docker 不可用时保留失败日志，下次计划重试。
 
@@ -267,9 +267,9 @@ UPDATE_RELEASE_VERSION="<指定完整版本号>" ./update.sh
 
 脚本拉取部署仓库后会切换到新版脚本，补齐缺失的转换配置；已有令牌、端口、数据卷和显式付费选择保持原值。指定 `UPDATE_SERVICES` 时只重建这些服务，不重建数据库等依赖；服务名称有误会在拉取镜像前终止。普通更新不指定该变量时保留原来的整组更新行为。转换容器只加入业务网络，不开放主机端口，不连接沙箱网络，不挂载 Docker socket，也不读取整个生产 `.env`。默认限额为 2 CPU、4 GiB、并发 1、单任务 300 秒、临时空间 2 GiB；原模型始终保留，轻量转换失败可使用原模型。
 
-`MODEL_CONVERSION_WORKER_VERSION` 使用已发布的固定版本，未独立填写时继承 `VERSION`；更新脚本将目标组件版本持久化到 `.env`，应用更新不接受 `latest` 或其他浮动标签。混元付费通道默认关闭，自建转换失败不自动切换到付费服务。已有 updater 的页面更新仍按稳定清单管理三个核心服务；转换 Worker 的首次安装和配置升级使用上述 `update` 脚本完成。
+`MODEL_CONVERSION_WORKER_VERSION` 使用产品记录中的实际 Worker 版本及摘要，不继承产品 `VERSION`。单独指定组件时只接受固定版本；Worker 使用固定标签和已核验摘要，核心服务的旧 Watchtower 稳定别名按前文规则保留。混元付费通道默认关闭，自建转换失败不自动切换到付费服务。已有 updater 的页面更新仍按稳定清单管理三个核心服务；转换 Worker 的首次安装和配置升级使用上述 `update` 脚本完成。
 
-测试候选版本时使用 `UPDATE_RELEASE_VERSION=3.23.0.20261003`，由更新脚本固定核心服务和转换 Worker 的版本，无需改动远端 `.env` 或移动 `latest` 标签。版本号不合法时在修改配置前终止。
+测试候选版本时使用 `UPDATE_RELEASE_VERSION=<已登记产品版本>`，由更新脚本解析记录中的核心服务和转换 Worker 实际版本，无需手工改动远端 `.env` 或移动 `latest` 标签。版本号不合法时在修改配置前终止。
 
 Linux 旧部署如果因本地 Compose 修改无法拉取仓库，可在检查差异后设置 `UPDATE_ADOPT_LEGACY_CONFIG=1`。脚本需要 Python 3 和 PyYAML；先校验合并配置，再将原始配置和冲突文件备份到 `data/deployment-backups/`，本地差异保存在 `data/deployment-config/legacy-compose.json`，仓库继续管理新增服务和配置。其他业务代码修改、未支持的文件冲突或无法表示的删除会阻止迁移，不启动容器。活动 Nginx 配置不会被改写。
 
@@ -697,23 +697,17 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\start.ps1"
 > - **推荐**：使用 `powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\start.ps1"` 执行，无需修改系统策略
 > - **或**：以管理员身份打开 PowerShell，执行 `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`，之后可直接运行 `.\start.ps1`
 
-### 启用HTTPS
-1. [更改为你的域名]修改`easyai-proxy.conf`中域名`51easyai.com`为你的域名[可以使用Ctrl+F批量替换51easyai.com为你的域名]
-2. [修改.env文件]修改如下两个环境变量为如下的对应的值
+### 启用 HTTPS
+
+首次域名部署直接使用统一入口，脚本会先验证容器，再配置代理和证书，并检查 HTTPS 首页与后端就绪接口：
+
 ```bash
-NUXT_PUBLIC_BASE_APIURL=/api
-NUXT_PUBLIC_BASE_SOCKETURL=wss://<你的域名>/socket.io
-SERVER_HTTP_BIND_IP=127.0.0.1
-```
-3. [首次执行，后续无需重复执行]添加执行权限，命令：
-```bash
-chmod +x https.sh
-```
-4. 启用HTTPS
-```bash
-./https.sh
+DEPLOY_ACCESS=domain DEPLOY_DOMAIN=demo.example.com DEPLOY_HTTPS=true \
+CERTBOT_EMAIL=ops@example.com ./start.sh
 ```
 
+已有 HTTP 站点切换 HTTPS 前，备份现有配置，按前文“后端公开 API 地址”同步公开 URL 和 WebSocket 协议，再使用 `https.sh` 的显式域名入口申请证书；自定义代理需要同步检查对应配置。域名解析、TCP 80/443 和证书申请均需在目标环境验收。
+
 ### 配置PDF图文解析Markdown功能
 如果需要启用PDF图文解析Markdown功能，需要`env.tools`中的OSS环境变量，具体参考文件中的配置说明：自动解析PDF图文，将图片文件上传到OSS，并解析成Markdown格式，并返回
 
@@ -721,16 +715,17 @@ chmod +x https.sh
 ## 常见问题
 
 1. 某个服务无法运行
-解决方案：重启docker（可以解决99%的问题）
+
+先保留现场并查看具体服务，避免整组停机。`not found` / `MANIFEST_UNKNOWN` 表示引用的标签或摘要不存在；`unauthorized` / `denied` 需要核对镜像匿名访问权限或授权；其他服务显示 `Interrupted` 不能单独证明该镜像缺失。重启 Docker 或反复重试不能修复不存在的标签。
 
 ```bash
-# 
-cd easyai && docker compose down && docker compose up -d 
-#如果提示docker "compose" is not a docker command,则使用下面的命令
-cd easyai && docker-compose down && docker-compose up -d 
-
+cd ~/easyai
+docker compose ps
+docker compose logs --tail=100 easyai-server
 ```
 
+提供诊断信息时只附服务状态和必要错误，不要发送 `.env`、完整 `docker compose config` 或认证文件。安装和升级只有在拉取、启动、健康检查全部完成后才报告成功。
+
 2. 启动时提示`Error: listen EADDRINUSE: address already in use :::3000`
 端口占用，请检查端口3000是否被其他程序占用
 3. invalid interpolation format for services.mongo.ports.[]. You may need to escape any $ with another $ 等关于docker-compose文件格式的报错
@@ -742,10 +737,9 @@ apt remove docker-compose
 ./start.sh
 ```
 
-4. 单独更新docker-compose.yml文件，并更新
-```bash
-cd ~/easyai && cp docker-compose.yml docker-compose.yml.backup && wget -q https://git.51easyai.com/wangbo/easyai/raw/main/docker-compose.yml -O docker-compose.yml && echo "✅ docker-compose.yml 更新完成"
-```
+4. 配置文件需要更新
+
+使用 `./update.sh` 的完整更新模式同步 Compose、脚本与配置迁移；不要只下载一个 Compose 文件替换，避免新旧脚本和变量契约混用。已有本地修改时先审查差异，再使用上面的 `UPDATE_ADOPT_LEGACY_CONFIG=1` 受控迁移入口。
 
 ## 官方模型目录