# ONLYOFFICE 标准组件运行说明

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

## 默认安装

执行标准安装即可同时安装 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
bash scripts/onlyoffice-dev-up.sh --rotate-secret
```

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

可用 `ONLYOFFICE_IMAGE` 覆盖默认的 `onlyoffice/documentserver:9.4.0.1`。默认派生镜像增加 Noto Sans CJK/Noto Serif CJK；其他字体由上游镜像或部署方提供。

## 导入宋体和 Times New Roman

将获准使用的字体放到 `onlyoffice/fonts/`，文件名为 `simsun.ttc`、`times.ttf`、`timesbd.ttf`、`timesi.ttf`、`timesbi.ttf`。宋体集合包含 SimSun（宋体）和 NSimSun（新宋体），Times New Roman 的四个文件分别提供常规、粗体、斜体和粗斜体。该目录的字体文件被 Git 忽略，必须在每台构建主机上单独提供；构建得到的镜像会包含这些字体。

从仓库根目录执行以下命令；如果运行的是独立开发栈，为每条 Compose 命令增加 `-f docker-compose.dev.yaml -p ctms_dev`：

```bash
docker compose build onlyoffice
docker compose exec -T onlyoffice documentserver-prepare4shutdown.sh
docker compose up -d --no-deps onlyoffice
```

维护前先完成文档保存。上述关闭准备会等待在线文档保存，随后替换 ONLYOFFICE 容器；启动脚本自动重建字体索引。构建脚本仅在四个 Times New Roman 文件齐全时移除上游同名字体，避免编辑器继续选用旧版本。未提供字体的环境沿用原有字体。

健康检查通过后，重新打开在线文档，在字体列表中查找 `SimSun`（宋体）和 `Times New Roman`。可用以下命令核对字体来源：

```bash
docker compose exec -T onlyoffice fc-match SimSun
docker compose exec -T onlyoffice fc-match 'Times New Roman'
docker compose exec -T onlyoffice curl -fsS http://127.0.0.1/healthcheck
```

补充说明：当前版本的生成器也会扫描 `onlyoffice_data` 卷中的 `/var/www/onlyoffice/Data/custom-fonts/`。放在该处的字体可跨容器重建保留，但同名字体仍可能被上游版本优先选中；替换 Times New Roman 时使用上述镜像构建流程。迁移部署时应单独携带字体来源文件。字体索引刷新方式参见 [ONLYOFFICE 官方字体安装说明](https://helpcenter.onlyoffice.com/docs/installation/docs-install-fonts-docker.aspx)。

## 配置边界

- 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 官方许可说明](https://helpcenter.onlyoffice.com/docs/faq/docs-community.aspx) 为准。