feat(deploy): 默认安装 ONLYOFFICE 标准组件

2026-07-16 17:09:12 +08:00
parent 3e77127687
commit 1837ceff58
8 changed files with 128 additions and 52 deletions
@@ -147,12 +147,12 @@ bash scripts/install.sh release --base-url https://ctms.example.com

 ```text
 1. 检查 docker、docker compose、openssl、curl。
-2. 检查 .env；已存在则保留不改，不存在则新建。
-3. 新建 main/release 的 .env 时自动生成 JWT 和 RSA 私钥。
+2. 检查 .env；保留已有身份与登录密钥，补齐并默认启用标准 ONLYOFFICE 配置，不存在则新建。
+3. 所有环境自动生成独立的 ONLYOFFICE JWT 与稳定实例标识；新建 main/release 的 .env 时同时生成登录 JWT 和 RSA 私钥。
 4. main/release 先构建并执行 backend-init，确保数据库迁移使用当前代码中的 Alembic revision。
-5. 启动容器；默认执行 docker compose up -d --build，--skip-build 时执行 docker compose up -d。
+5. 默认构建并启动数据库、后端、前端/Nginx 和 ONLYOFFICE；ONLYOFFICE 不再使用可选 Compose Profile。
 6. 执行 docker compose run --rm backend python -m alembic upgrade head。
-7. 检查容器状态、后端环境、/health、/api/v1/auth/login-key。
+7. 检查全部容器状态、后端环境、/health、/api/v1/auth/login-key 和 /onlyoffice/healthcheck。
 ```

 更新进入“执行部署更新”后会持续显示 Docker 镜像拉取与构建进度：交互终端使用滚动实时输出窗口，CI、远程面板或管道环境直接流式输出构建日志，并在两种模式下显示累计耗时。
@@ -195,6 +195,12 @@ ENV=development
 JWT_SECRET_KEY=dev-secret
 LOGIN_RSA_KEY_ID=default
 LOGIN_RSA_PRIVATE_KEY=
+ONLYOFFICE_ENABLED=true
+ONLYOFFICE_JWT_SECRET=<替换为独立的随机密钥，至少 32 个字符>
+ONLYOFFICE_INTERNAL_URL=http://onlyoffice
+ONLYOFFICE_STORAGE_BASE_URL=http://backend:8000
+ONLYOFFICE_INSTANCE_ID=ctms-dev-<替换为随机实例标识>
+ONLYOFFICE_CONFIG_TTL_SECONDS=300
 EOF
 ```

@@ -316,6 +322,12 @@ ENV=production
 JWT_SECRET_KEY=<替换为 JWT 密钥>
 LOGIN_RSA_KEY_ID=main-YYYYMMDD
 LOGIN_RSA_PRIVATE_KEY=<替换为 RSA 私钥单行文本>
+ONLYOFFICE_ENABLED=true
+ONLYOFFICE_JWT_SECRET=<替换为不同于 JWT_SECRET_KEY 的独立随机密钥>
+ONLYOFFICE_INTERNAL_URL=http://onlyoffice
+ONLYOFFICE_STORAGE_BASE_URL=http://backend:8000
+ONLYOFFICE_INSTANCE_ID=ctms-main-<替换为随机实例标识>
+ONLYOFFICE_CONFIG_TTL_SECONDS=300
 EOF
 ```

@@ -495,6 +507,12 @@ ENV=production
 JWT_SECRET_KEY=<替换为生产 JWT 密钥>
 LOGIN_RSA_KEY_ID=release-YYYYMMDD
 LOGIN_RSA_PRIVATE_KEY=<替换为生产 RSA 私钥单行文本>
+ONLYOFFICE_ENABLED=true
+ONLYOFFICE_JWT_SECRET=<替换为不同于 JWT_SECRET_KEY 的独立生产随机密钥>
+ONLYOFFICE_INTERNAL_URL=http://onlyoffice
+ONLYOFFICE_STORAGE_BASE_URL=http://backend:8000
+ONLYOFFICE_INSTANCE_ID=ctms-release-<替换为随机实例标识>
+ONLYOFFICE_CONFIG_TTL_SECONDS=300
 EOF
 ```

@@ -1,26 +1,28 @@
-# ONLYOFFICE 只读预览运行说明
+# ONLYOFFICE 标准组件运行说明

-当前集成只用于附件和文档版本的 Office 文件只读预览。PDF、图片、另存为和桌面端“打开”仍使用原有链路；第一期不启用编辑、保存回调、历史记录或强制保存。
+ONLYOFFICE Document Server 是 CTMS 的标准部署组件，用于附件和文档版本预览，以及共享库在线协作编辑。PDF、图片、另存为和桌面端“打开”仍使用各自原有链路。

-## 开发环境启动
+## 默认安装

-普通 `docker compose up` 不会拉取或启动 Document Server。开发环境需要预览时执行专用启动脚本：
+执行标准安装即可同时安装 CTMS 与 ONLYOFFICE：
+
+```bash
+bash scripts/install.sh dev
+```
+
+安装脚本会自动完成以下工作：
+
+- 首次安装时生成独立的 256-bit 随机 `ONLYOFFICE_JWT_SECRET`，写入根目录 `.env`，且不在终端回显。
+- 自动生成稳定、按部署环境隔离的实例标识并写入 `.env`。
+- 将 `.env` 权限设置为 `0600`；该文件已被 Git 忽略。
+- 默认构建并启动 backend、Document Server 与 Nginx，不再使用可选 Compose Profile。
+- 将 Document Server 纳入容器状态、后端配置和 HTTP 健康检查。
+- 后续启动默认复用密钥，防止后端和 Document Server 因签名密钥漂移而无法通信。
+
+开发环境需要单独重建、验证或主动轮换密钥时，可使用兼容维护脚本：

 ```bash
 bash scripts/onlyoffice-dev-up.sh
-```
-
-脚本会自动完成以下工作：
-
- 首次启动时生成 256-bit 随机 `ONLYOFFICE_JWT_SECRET`，写入根目录 `.env`，且不在终端回显。
- 自动生成稳定的开发实例标识并写入 `.env`。
- 将 `.env` 权限设置为 `0600`；该文件已被 Git 忽略。
- 使用同一环境重建 backend，并显式启用 `office` Profile 启动 Document Server。
- 后续启动默认复用密钥，防止后端和 Document Server 因签名密钥漂移而无法通信。
-
-需要主动轮换开发密钥时执行：
-
-```bash
 bash scripts/onlyoffice-dev-up.sh --rotate-secret
 ```

@@ -30,7 +32,7 @@ bash scripts/onlyoffice-dev-up.sh --rotate-secret

 ## 配置边界

- `ONLYOFFICE_ENABLED` 默认 `false`。
+- Compose 安装中的 `ONLYOFFICE_ENABLED` 默认 `true`；安装或更新旧环境时也会自动启用。
 - `ONLYOFFICE_INTERNAL_URL` 默认 `http://onlyoffice`，只供后端健康探测。
 - `ONLYOFFICE_STORAGE_BASE_URL` 默认 `http://backend:8000`，只允许后端生成固定的内部文件地址。
 - `ONLYOFFICE_CONFIG_TTL_SECONDS` 默认 300 秒，允许范围为 60–900 秒。
@@ -38,8 +40,8 @@ bash scripts/onlyoffice-dev-up.sh --rotate-secret
 - 配置响应禁止缓存；JWT、内部文件 URL 和磁盘路径不得进入日志、审计详情或桌面缓存。
 - `onlyoffice_data`、`onlyoffice_lib` 和 `onlyoffice_logs` 不是 CTMS 业务权威数据，不纳入业务备份或恢复来源。

-## 生产启用前
+## 生产部署要求

-生产保持功能开关关闭，直至商业许可、批准镜像和真实授权环境回归完成。启用时必须使用生产随机密钥和稳定、唯一的 `ONLYOFFICE_INSTANCE_ID`，并完成 Web、macOS 和 Windows 内测端的真实 DOCX/XLSX/PPTX/WPS/ET/DPS 预览验证。
+标准生产安装同样包含 ONLYOFFICE，并自动生成独立随机密钥和稳定、唯一的 `ONLYOFFICE_INSTANCE_ID`。正式上线前仍必须确认商业许可或 Community 版本授权边界、批准镜像、容量与备份监控策略，并完成 Web、macOS 和 Windows 内测端的真实 DOCX/XLSX/PPTX/WPS/ET/DPS 预览验证。

-故障回退只关闭 `ONLYOFFICE_ENABLED`；不得影响附件下载、另存为、打开、PDF 或图片预览。Community 与商业版本的授权边界以 [ONLYOFFICE 官方许可说明](https://helpcenter.onlyoffice.com/docs/faq/docs-community.aspx) 为准。
+故障回退可临时关闭 `ONLYOFFICE_ENABLED`；下一次标准安装或更新会按标准组件策略重新启用。回退不得影响附件下载、另存为、打开、PDF 或图片预览。Community 与商业版本的授权边界以 [ONLYOFFICE 官方许可说明](https://helpcenter.onlyoffice.com/docs/faq/docs-community.aspx) 为准。