ctms/docs/guides/onlyoffice-preview.md

ONLYOFFICE 标准组件运行说明

ONLYOFFICE Document Server 是 CTMS 的标准部署组件，用于附件和文档版本预览，以及共享库在线协作编辑。PDF、图片、另存为和桌面端“打开”仍使用各自原有链路。

默认安装

执行标准安装即可同时安装 CTMS 与 ONLYOFFICE：

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 scripts/onlyoffice-dev-up.sh
bash scripts/onlyoffice-dev-up.sh --rotate-secret

轮换会强制重建相关容器，已签发但尚未使用的短时预览配置会立即失效。生产环境不使用该自动生成流程，仍必须由部署密钥管理系统显式提供密钥。

可用 ONLYOFFICE_IMAGE 覆盖默认的 onlyoffice/documentserver:9.4.0.1。默认派生镜像只增加 Noto Sans CJK/Noto Serif CJK，不包含微软字体。

配置边界

• Compose 安装中的 ONLYOFFICE_ENABLED 默认 true；安装或更新旧环境时也会自动启用。
• ONLYOFFICE_INTERNAL_URL 默认 http://onlyoffice，只供后端健康探测。
• ONLYOFFICE_STORAGE_BASE_URL 默认 http://backend:8000，只允许后端生成固定的内部文件地址。
• ONLYOFFICE_CONFIG_TTL_SECONDS 默认 300 秒，允许范围为 60–900 秒。
• 内部内容接口不经过 Nginx 公网入口，仅接受 AuthorizationJwt，且 JWT 必须绑定到请求的精确 URL。
• 配置响应禁止缓存；JWT、内部文件 URL 和磁盘路径不得进入日志、审计详情或桌面缓存。
• onlyoffice_data、onlyoffice_lib 和 onlyoffice_logs 不是 CTMS 业务权威数据，不纳入业务备份或恢复来源。

生产部署要求

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

故障回退可临时关闭 ONLYOFFICE_ENABLED；下一次标准安装或更新会按标准组件策略重新启用。回退不得影响附件下载、另存为、打开、PDF 或图片预览。Community 与商业版本的授权边界以 ONLYOFFICE 官方许可说明 为准。