Cheng Zhou
d5279b124f
Storage Persistence Guard / storage-persistence-audit (push) Has been cancelled
Client Quality Gates / Shared client and Web (push) Has been cancelled
Client Quality Gates / macOS Desktop (push) Has been cancelled
Client Quality Gates / Shared client and Web (pull_request) Has been cancelled
Client Quality Gates / macOS Desktop (pull_request) Has been cancelled
Storage Persistence Guard / storage-persistence-audit (pull_request) Has been cancelled
77 lines
7.5 KiB
Markdown
77 lines
7.5 KiB
Markdown
# ONLYOFFICE 在线协作模块
|
||
|
||
## 范围
|
||
|
||
在线协作是共享库下的独立业务模块，不复用附件、文档管理、文件版本管理或 eTMF 的数据表和文件标识。当前支持新建或导入 `DOCX`、`XLSX`、`PPTX`，通过 ONLYOFFICE 进行多人共同编辑，并把保存结果固化为不可变修订。
|
||
|
||
原有附件与文档版本仍保持只读预览流程，不会自动进入协作空间，也不会因协作回调被覆盖。
|
||
|
||
## 数据与权限边界
|
||
|
||
- `collaboration_files` 保存协作文件元数据、当前修订指针和统一的内容操作权限设置。
|
||
- `collaboration_revisions` 保存不可变文件修订；每次有效保存或历史恢复都会创建新修订。
|
||
- `collaboration_members` 保存文件级编辑者和管理者。
|
||
- `collaboration_edit_requests` 保存系统内项目成员发起的编辑权限申请及审批结果；同一成员、同一文件同时只允许存在一条待处理申请。
|
||
- `notifications` 是收件人级通用通知表，统一保存通知类别、优先级、内部操作路径、业务来源、去重键、已读和业务关闭状态。编辑权限申请只通知当前有效的文件所有者和文件管理者；申请处理后，同一业务来源的所有收件人通知一并关闭。
|
||
- `collaboration_sessions` 使用稳定的文件代次生成 ONLYOFFICE `document.key`，同一代次的用户进入同一共同编辑会话。
|
||
- `collaboration_callback_receipts` 对回调做幂等确认。
|
||
- `collaboration_share_links` 保存单文件公开链接的启停状态、查看/编辑权限、有效期策略和密码哈希；不保存明文密码或共享令牌。
|
||
- 项目接口权限只控制在线协作模块入口、项目级新建/导入/文件夹操作，以及账号能否被授予文件角色；文件创建后的编辑、管理、导出和所有权转让统一由文件身份判定，项目角色不再隐式覆盖文件角色。
|
||
- 文件所有者始终拥有编辑、管理、导出和转让能力；文件管理者始终拥有编辑、管理和导出能力，但不能转让所有权；文件编辑者可以编辑，导出能力由文件“权限设置”开关控制。系统管理员继续保留平台级完整访问能力。
|
||
- 授予编辑者、管理者或转让所有权时，目标账号必须是当前项目的有效成员，并具备对应项目角色资格；不合格账号在联系人列表中不可选择，后端同时拒绝绕过界面的授权请求。
|
||
- 文件管理者可开启“允许申请编辑权限”。只读项目成员可从 CTMS 顶栏或 ONLYOFFICE 的“请求编辑”入口提交申请；批准后写入文件级编辑者授权，拒绝或重复处理均有明确状态和审计记录。匿名链接访问者不能申请系统账号权限。
|
||
- 顶栏铃铛通过通用通知 Feed 展示当前收件人的未关闭通知并记录已读状态；编辑权限申请通知可直接进入对应文件的“权限设置”，审批结果作为一次性信息通知申请人。AE、监查问题、文件回执和里程碑时效提醒也由同一 Feed 返回，具体规则见 `docs/project-notifications.md`。
|
||
- Excel 文件可通过“允许所有协作者添加、删除工作表”控制工作簿结构。关闭时 CTMS 在新的不可变修订中启用工作簿结构保护并推进文件代次；重新开启时恢复文件原有的工作簿保护状态。该开关作用于所有协作者且不影响单元格内容编辑权限。
|
||
- 仅文档所有者和系统管理员可转让所有权。目标联系人必须具备文件管理者资格；转让后目标联系人升级为文件管理者，原所有者保留管理者身份，所有权变更写入审计。
|
||
- 文件编辑器“下载为”由文件导出规则判定：所有者和管理者始终允许，编辑者受文件开关控制，并由 CTMS 网页/桌面文件运行时保存到本机且记录下载审计。“另存为…”还会在项目工作区创建独立协作文件，因此额外要求项目级 `collaboration:create` 权限。
|
||
|
||
## 公开分享链接
|
||
|
||
- 文件管理者可开启链接，并选择只读或协作编辑、1 天/7 天/30 天/永久有效及可选访问密码；设置修改后自动保存，无需额外提交整张表单。
|
||
- 文件操作菜单以一个“访问与权限”弹窗统一管理账号授权、匿名访问和“权限设置”；下载、打印、另存和复制不在两种访问方式下重复配置。
|
||
- “权限设置”中的内容操作开关只作用于已授权编辑者和匿名访问者。所有者、文件管理者和系统管理员始终保留导出能力；外部链接不具备向项目工作区另存副本的权限。
|
||
- 共享令牌只放在网页 URL 的 fragment（`#...`）中，不进入服务器请求路径、查询参数或本地缓存；前端调用公开 API 时通过会被审计层脱敏的请求头传递。
|
||
- 每个文件首次创建分享记录后使用固定共享地址；修改权限、密码、有效期或关闭后重新开启都不会改变 URL。关闭期间同一地址暂停访问，重新开启后恢复访问。
|
||
- 链接密码仅保存 bcrypt 哈希；验证成功后签发短时、链接记录绑定的内存访问凭证。连续错误达到阈值后链接密码验证会临时锁定。
|
||
- 外部共享页不依赖 CTMS 登录状态，不提供工作区“另存为”；开启允许导出后可下载到访问者本机，编辑链接仍通过现有 ONLYOFFICE 会话写入不可变修订。
|
||
- `JWT_SECRET_KEY` 轮换属于平台级全局失效操作，会使现有公开分享链接和短时访问凭证失效；生产环境必须按安全变更流程评估影响并提前通知链接使用者。
|
||
|
||
## 保存流程
|
||
|
||
1. 浏览器请求 `/api/v1/studies/{study_id}/collaboration/files/{file_id}/editor-config`。
|
||
2. 后端生成带 JWT 的编辑配置、内部内容地址和回调地址。
|
||
3. Document Server 从内部内容接口读取当前修订。
|
||
4. 共同编辑期间使用 fast 模式；强制保存产生新修订并更新会话恢复基线。
|
||
5. 最后一位编辑者退出后，状态 2 回调产生最终修订并推进文件代次；下一次编辑使用新的 `document.key`。
|
||
6. 重复回调通过指纹幂等处理；旧代次回调不会覆盖当前文件。
|
||
|
||
内部内容和回调接口不经过 Nginx 公网入口，只接受 `AuthorizationJwt`。回调结果文件仅允许从配置的 Document Server 内部源获取，禁止重定向、凭据 URL 和任意主机。
|
||
|
||
## 本地开发
|
||
|
||
标准开发安装会直接启动 ONLYOFFICE：
|
||
|
||
```bash
|
||
bash scripts/install.sh dev
|
||
```
|
||
|
||
安装脚本会生成或复用独立的开发 JWT 密钥和稳定实例标识，默认启动 Document Server，并验证后端配置和 HTTP 健康状态。`bash scripts/onlyoffice-dev-up.sh` 仅用于开发环境单独重建、验证或轮换密钥。协作修订保存在现有后端上传卷下的独立 `collaboration/` 目录。
|
||
|
||
关键配置：
|
||
|
||
- `ONLYOFFICE_ENABLED`
|
||
- `ONLYOFFICE_JWT_SECRET`
|
||
- `ONLYOFFICE_INTERNAL_URL`
|
||
- `ONLYOFFICE_STORAGE_BASE_URL`
|
||
- `ONLYOFFICE_INSTANCE_ID`
|
||
- `ONLYOFFICE_CONFIG_TTL_SECONDS`
|
||
- `COLLABORATION_MAX_FILE_BYTES`
|
||
|
||
生产标准安装同样包含 ONLYOFFICE；正式上线前必须按既有发布要求确认镜像许可、独立 JWT 密钥、内部网络、容量、备份与监控。
|
||
|
||
参考：
|
||
|
||
- [ONLYOFFICE 共同编辑模式](https://api.onlyoffice.com/docs/docs-api/get-started/how-it-works/co-editing/)
|
||
- [ONLYOFFICE 回调处理器](https://api.onlyoffice.com/docs/docs-api/usage-api/callback-handler/)
|
||
- [ONLYOFFICE 文档权限](https://api.onlyoffice.com/docs/docs-api/usage-api/config/document/permissions/)
|