# Server SDK

> 为应用准备文档服务、数据存储和访问权限。

- Human documentation: [https://docs.univer.ai/zh-CN/server](https://docs.univer.ai/zh-CN/server)

- Agent Markdown: [https://docs.univer.ai/zh-CN/server.md](https://docs.univer.ai/zh-CN/server.md)

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

- Source: [index.zh-CN.mdx](https://github.com/dream-num/documentation/blob/dev/content/server/index.zh-CN.mdx)

---

服务端负责保存文档、检查用户权限，并为协同编辑或文件转换提供接口。当前版本通过 [Server SDK](https://docs.univer.ai/zh-CN/server.md)接入这些能力，服务运行在你自己的应用环境中。

本节按集成任务组织：本页说明服务端的搭建、存储和权限；[协同集成](https://docs.univer.ai/zh-CN/server/collaboration/browser-integration.md)说明编辑器如何连接共享文档；[导入导出集成](https://docs.univer.ai/zh-CN/server/import-export.md)说明文件上传、转换和下载的对接。按需要阅读对应文章；需要授权的 功能，先完成[许可证配置](https://docs.univer.ai/zh-CN/guides/license.md)。只使用前端编辑功能时，不必接入协同服务。

## 按步骤完成集成

1. [运行 Quick Start](https://docs.univer.ai/zh-CN/server/collaboration/quick-start.md)：两个独立浏览器会话打开同一文档，验证双向编辑。
2. [接入持久化](https://docs.univer.ai/zh-CN/server/collaboration/database-adapters.md#verify-persistence)：重启 SQLite 示例，确认数据仍在。
3. [接入身份与权限](https://docs.univer.ai/zh-CN/server/collaboration/identity-and-authorization.md#verify-permissions)：分别验证 editor 和 viewer。
4. [连接业务前端](https://docs.univer.ai/zh-CN/server/collaboration/browser-integration.md)：替换演示身份、文档创建逻辑和协议地址。
5. [按需增加扩展](https://docs.univer.ai/zh-CN/server/collaboration/examples.md)：基础链路跑通后，再增加历史、评论、Worktree 或 Exchange。只需要文件转换时，直接从 [Exchange](https://docs.univer.ai/zh-CN/server/import-export/node.md) 开始。

## 选择需要的服务

| 需求              | 服务端需要准备                     | 实现文档                                                                                                   |
| --------------- | --------------------------- | ------------------------------------------------------------------------------------------------------ |
| 多人编辑同一份文档       | Collaboration SDK、文档存储和用户权限 | [协同快速开始](https://docs.univer.ai/zh-CN/server/collaboration/quick-start.md)                                                      |
| 导入或导出 Office 文件 | 文件转换、上传、任务查询和下载接口           | [文件转换](https://docs.univer.ai/zh-CN/server/import-export/node.md)与 [Exchange 示例](https://docs.univer.ai/zh-CN/server/collaboration/examples.md#exchange) |
| 历史记录或共享评论       | 对应的服务、存储和权限                 | [协同扩展模块](https://docs.univer.ai/zh-CN/server/collaboration/extensions.md)                                                       |

这些能力按需接入。例如，只做文件转换时，无需先搭建多人协同服务。安装前按 [SDK 环境与版本要求](https://docs.univer.ai/zh-CN/server/requirements.md)准备运行环境，并保持 Univer 包版本匹配。

## 连接业务系统和存储

先运行所选服务的官方示例，再接入现有业务后端。对于协同文档，业务后端创建文档、记录归属，再把文档 ID 返回给前端；创建接口的用法见[模块边界与关系](https://docs.univer.ai/zh-CN/server/collaboration/modules.md)。用户、项目和目录仍由业务系统管理。

协同示例默认使用内存存储，重启后内容会丢失。按 [Database Adapter 文档](https://docs.univer.ai/zh-CN/server/collaboration/database-adapters.md)换成数据库，并验证服务重启后仍能读取已保存的文档。

文件转换还需要安排上传文件、转换任务和下载文件的保存与清理。相关实现见 [Exchange 示例](https://docs.univer.ai/zh-CN/server/collaboration/examples.md#exchange)。

## 接入登录和权限

按[身份与权限](https://docs.univer.ai/zh-CN/server/collaboration/identity-and-authorization.md)验证现有登录状态，并检查当前用户能否读取或修改文档。替换示例中的固定用户和默认放行规则。

权限检查要覆盖文档内容、协同连接、修改提交，以及启用的历史记录、评论和文件下载。将前端设为只读，不能代替服务端权限检查。

## 部署并连接前端

将接口部署到应用使用的域名。协同服务经过反向代理时，需要同时转发 HTTP 和 WebSocket；HTTPS 页面使用 WSS。文件接口需要设置上传大小限制，并处理转换失败和超时。

后端就绪后，继续完成对应的功能集成：

* [协同集成](https://docs.univer.ai/zh-CN/server/collaboration/browser-integration.md)：连接编辑器，创建和打开共享文档，验证多用户同步。
* [导入导出集成](https://docs.univer.ai/zh-CN/server/import-export.md)：连接文件上传、转换和下载，验证实际文件结果。