release(main): 修复云端台账保存与备份重开

docs/guides/branch-environment-installation.md

@@ -137,7 +137,9 @@ bash scripts/install.sh release --base-url https://ctms.example.com
 可选参数：
 
 ```text
---base-url <url>   健康检查使用的访问地址。dev/main 默认 http://127.0.0.1:8888，release 必填或交互输入。
+--base-url <url>   对外访问基址，同时用于健康检查及 ONLYOFFICE 保存地址校验。dev/main 默认
+                   http://127.0.0.1:8888；已有环境优先复用 .env 的 CTMS_BASE_URL，
+                   首次 release 安装必填或交互输入。只接受协议与主机组成的 origin。
 --yes              跳过交互确认，适合自动化执行。
 --skip-build       跳过镜像构建，仍会执行 docker compose up -d。
 --skip-migrate     跳过 alembic upgrade head。
@@ -147,12 +149,14 @@ bash scripts/install.sh release --base-url https://ctms.example.com
 
 ```text
 1. 检查 docker、docker compose、openssl、curl。
-2. 检查 .env；保留已有身份与登录密钥，补齐并默认启用标准 ONLYOFFICE 配置，不存在则新建。
+2. 检查 .env；保留已有身份与登录密钥，补齐并默认启用标准 ONLYOFFICE 配置，不存在则新建；将
+   `CTMS_BASE_URL` 与 `FRONTEND_PUBLIC_URL` 同步为 `--base-url`，确保公开缓存 URL 可通过保存回调校验。
 3. 所有环境自动生成独立的 ONLYOFFICE JWT 与稳定实例标识；新建 main/release 的 .env 时同时生成登录 JWT 和 RSA 私钥。
 4. main/release 先构建并执行 backend-init，确保数据库迁移使用当前代码中的 Alembic revision。
-5. 默认构建并启动数据库、后端、前端/Nginx 和 ONLYOFFICE；ONLYOFFICE 不再使用可选 Compose Profile。
-6. 执行 docker compose run --rm backend python -m alembic upgrade head。
-7. 检查全部容器状态、后端环境、/health、/api/v1/auth/login-key 和 /onlyoffice/healthcheck。
+5. 在重启服务前通过 ONLYOFFICE `info` 命令检查真实在线编辑者；存在在线编辑时中止部署，待用户退出并完成最终保存后重试。
+6. 默认构建并启动数据库、后端、前端/Nginx 和 ONLYOFFICE；ONLYOFFICE 不再使用可选 Compose Profile。
+7. 执行 docker compose run --rm backend python -m alembic upgrade head。
+8. 检查全部容器状态、后端环境、/health、/api/v1/auth/login-key 和 /onlyoffice/healthcheck。
 ```
 
 更新进入“执行部署更新”后会持续显示 Docker 镜像拉取与构建进度：交互终端使用滚动实时输出窗口，CI、远程面板或管道环境直接流式输出构建日志，并在两种模式下显示累计耗时。
@@ -193,6 +197,8 @@ cat > .env <<'EOF'
 COMPOSE_PROJECT_NAME=ctms_dev
 ENV=development
 JWT_SECRET_KEY=dev-secret
+CTMS_BASE_URL=http://127.0.0.1:8888
+FRONTEND_PUBLIC_URL=http://127.0.0.1:8888
 LOGIN_RSA_KEY_ID=default
 LOGIN_RSA_PRIVATE_KEY=
 ONLYOFFICE_ENABLED=true

docs/onlyoffice-collaboration.md

@@ -45,10 +45,12 @@
 5. 最后一位编辑者退出后，状态 2 回调产生最终修订并推进文件代次；下一次编辑使用新的 `document.key`。
 6. 重复回调通过指纹幂等处理；旧代次回调不会覆盖当前文件。
 
-如果最终保存返回状态 3，后端将会话标记为保存失败。再次打开文件时，先通过 ONLYOFFICE `getForgotten` 命令取回服务器保留的备份副本，校验 Office 包结构后写入一条“服务器备份恢复”修订，再推进文件代次并使用新的 `document.key`。如果文档服务器已经没有备份，则从 CTMS 最后一次确认保存的修订开始新代次。恢复服务暂时不可用或返回的备份无效时阻止打开并提示重试，避免反复打开未持久化副本或静默丢弃仍可恢复的数据。状态 7 仅表示本次强制保存失败，不终止仍在进行的共同编辑会话。
+状态 2、3 或 4 的最终回调结束当前编辑生命周期，已关闭会话不得重新激活或复用原 `document.key`。数据库仍标记为 `ACTIVE`、但已接收过回调且 Document Server 的 `info` 命令确认没有在线编辑者时，同样按中断会话退役；刚签发但尚未收到首次连接回调的 key 保留 15 秒连接宽限，避免并发配置请求误判。对于保存错误或这类中断会话，再次打开文件时后端通过 ONLYOFFICE `getForgotten` 命令检查服务器是否保留了备份副本；存在备份时，校验 Office 包结构后写入一条“服务器备份恢复”修订，再推进文件代次并使用新的 `document.key`。正常的无修改关闭只推进代次，不做不必要的备份查询。如果文档服务器没有备份，则从 CTMS 最后一次确认保存的修订开始新代次。恢复服务暂时不可用或返回的备份无效时阻止打开并提示重试，避免反复打开未持久化副本或静默丢弃仍可恢复的数据。状态 7 仅表示本次强制保存失败，不终止仍在进行的共同编辑会话。
 
 内部内容和回调接口不经过 Nginx 公网入口，只接受 `AuthorizationJwt`。回调结果文件仅允许从配置的 Document Server 内部源获取，禁止重定向、凭据 URL 和任意主机。
 
+安装和更新流程在重启服务前使用 ONLYOFFICE `info` 命令核实数据库中 `ACTIVE` 会话的真实在线用户。仍有编辑者时部署会在服务重启前终止，并只显示文件名和在线人数；应通知用户退出编辑器并等待最终保存后重试。数据库中的陈旧 `ACTIVE` 记录若已不在 Document Server 中存在，不会误阻塞部署。不要通过强制重启或删除 ONLYOFFICE 数据卷绕过检查。
+
 ## 本地开发
 
 标准开发安装会直接启动 ONLYOFFICE：
@@ -62,6 +64,7 @@ bash scripts/install.sh dev
 关键配置：
 
 - `ONLYOFFICE_ENABLED`
+- `FRONTEND_PUBLIC_URL`（必须与用户访问 CTMS 的 origin 一致；安装脚本会同步为 `--base-url`）
 - `ONLYOFFICE_JWT_SECRET`
 - `ONLYOFFICE_INTERNAL_URL`
 - `ONLYOFFICE_STORAGE_BASE_URL`