Docs 多格式转换与 .docx 导入Y-Provider 转换服务与 DocSpec 配置实战指南【免费下载链接】docsDocs is an open-source text editor: web-native, made for real-time collaboration, cleanly structured documents and sub-documents with full ownership of your data. Built to scale with Django and React.项目地址: https://gitcode.com/GitHub_Trending/docs150/docs本文档是 Docs 项目Django React 构建的 Web 原生实时协作文本编辑器中「格式转换」模块的技术指南覆盖从 Markdown / HTML / JSON 导出到 .docx 导入的完整配置链路。读完本文你将掌握formatted-content端点的用法、Y-Provider 转换服务的环境变量配置与源码调用链、Kubernetes Helm 部署下拆分 WebSocket 与转换服务的方案以及 DocSpec 服务的启用与安全部署建议。一、格式转换能力总览Docs 允许以多种格式操作文档内容导出为 HTML、Markdown、JSON 等格式以 Markdown 复制、粘贴与导入在启用 DocSpec 服务后支持导入.docx文件并转换为 Docs 内部的 Yjs 文档格式。这一切由两个外部服务支撑服务职责备注Y-Providery-provider核心转换引擎在 Markdown / HTML / JSON / Yjs / BlockNote 之间互相转换同时承载实时协作 WebSocket同一服务可拆分部署DocSpec将 legacy 格式如.docx转换为现代编辑器可用的 BlockNote 内容独立部署需自行托管转换链路并非只有文档中明示的配置项还涉及 Django 端的环境变量、y-provider 端的 API 路由与认证机制下面逐层展开。二、转换配置Django 与 Y-Provider 的环境变量2.1 Django 侧指向 Y-Provider 转换 API在 Django 服务中配置以下两个环境变量即可启用转换能力Y_PROVIDER_API_BASE_URL: http://{y-provider-service}:443/api/ Y_PROVIDER_API_KEY: a-shared-private-key-with-y-provider其中Y_PROVIDER_API_BASE_URLy-provider 转换 API 的基地址。可以指向你通过反向代理暴露的 Docs 实例 FQDN需为 y-provider 的/api路由配置代理也可以直接使用 y-provider 内部服务地址。若部署在 Kubernetes 集群中可使用 y-provider 的 Service 名称官方更推荐内部 URL。Y_PROVIDER_API_KEY与 y-provider 共享的私有密钥用于服务间认证。在 settings.py 中这两个值被声明为 Django-environ 变量Y_PROVIDER_API_KEY使用SecretFileValue支持从文件读取密钥Y_PROVIDER_API_BASE_URL使用普通Value两者environ_prefixNone意味着环境变量名与属性名完全一致。2.2 y-provider 侧共享同一个 API Keyy-provider 也必须配置相同的密钥Y_PROVIDER_API_KEY: a-shared-private-key-with-y-provider在 env.ts 中y-provider 通过Y_PROVIDER_API_KEY_FILE优先或Y_PROVIDER_API_KEY环境变量读取该密钥。认证校验位于 middlewares.ts服务维护VALID_API_KEYS列表包含协作服务器密钥与转换 API 密钥并校验请求头authorization是否在其中。注意根据 converter_services.py 的实现Django 端实际发送的是Bearer {Y_PROVIDER_API_KEY}形式注释也特别提醒y-provider 微服务只接受裸 tokenraw token这并非推荐做法仅作为当前实现的事实说明。2.3 formatted-content 端点配置好之后的调用入口完成上述配置后即可使用formatted-content端点获取文档的多格式内容GET /api/v1.0/documents/{document_id}/formatted-content/?content_format(json|html|markdown)该端点由 viewsets.py 中的formatted_contentaction 实现通过content_format查询参数指定输出格式缺省为json仅接受json、markdown、html三种取值否则返回 400从文档对象中取出 Base64 编码的 Yjs 内容base64.b64decode解码调用Converter服务将mime_types.YJS转换为目标格式转换失败时按异常类型返回 400验证失败或 500服务不可用。同一转换服务还被create-for-owner端点以及 Markdown 文件导入流程复用。三、转换调用链的源码级解析3.1 Converter 编排器Django 侧的转换入口是 converter_services.py 中的Converter类它内部组合了两个专用转换器DocSpecConverter处理.docx→ BlockNote 的转换YdocConverter处理 Markdown / Yjs / HTML / JSON 等格式间的转换。convert(data, content_type, accept)的编排逻辑为if content_type mime_types.DOCX and accept mime_types.YJS: blocknote_data self.docspec.convert(data, content_type, mime_types.BLOCKNOTE) return self.ydoc.convert(blocknote_data, mime_types.BLOCKNOTE, mime_types.YJS) return self.ydoc.convert(data, content_type, accept)也就是说.docx导入实际是两段式转换先由 DocSpec 转成 BlockNote JSON再由 y-provider 把 BlockNote 转成 Docs 内部的 Yjs 文档从而让用户享受到 Docs 全部编辑能力而无需受 legacy 格式限制。3.2 YdocConverter 与 y-provider 的 convert 端点YdocConverter._request以POST方式请求{Y_PROVIDER_API_BASE_URL}{CONVERSION_API_ENDPOINT}/端点默认值为convert见 settings.py携带Authorization、Content-Type、Accept三个请求头并受CONVERSION_API_TIMEOUT默认 30 秒与CONVERSION_API_SECURE默认 False控制。y-provider 侧对应的处理逻辑位于 convertHandler.ts路由定义为CONVERT: /api/convert/见 routes.ts。其支持的输入输出矩阵如下方向Content-Type输入Accept输出说明读取text/markdown、text/x-markdown、application/x-www-form-urlencoded—后者为向后兼容按 Markdown 解析读取application/vnd.yjs.doc、application/octet-stream—Yjs 二进制更新读取application/vnd.blocknotejson—BlockNote JSON写出—application/vnd.blocknotejson、application/json返回 blocks写出—application/vnd.yjs.doc、application/octet-stream编码为 Yjs state update写出—text/markdown、text/x-markdownblocksToMarkdownLossy有损写出—text/htmlblocksToHTMLLossy有损转换基于服务端ServerBlockNoteEditorBlockNote 的服务器端编辑器并将CommentsExtension注册进 schema以保留评论标记mark在转换中的完整性——若缺少该扩展被评论包裹的文本在转换时会被静默丢弃导致相关块变空。在YdocConverter.convert的返回处理中converter_services.py输出为 Yjs 时将二进制响应base64编码后返回字符串输出为 Markdown / HTML 时返回文本输出为 JSON 时解析为对象返回。3.3 异常与错误语义转换模块定义了三个异常类型converter_services.pyConversionError基类ValidationError输入校验失败空数据、不支持的格式组合对应 400ServiceUnavailableError无法连接转换服务或请求异常对应 500。y-provider 侧则按 HTTP 语义返回请求体为空返回 400、不支持的 Content-Type 返回 415、不支持的 Accept 返回 406、内容解析失败返回 400、服务端异常返回 500并将错误上报 Sentry。四、拆分转换服务WebSocket 与 Converter 分而治之转换服务与 WebSocket 服务同属于 y-provider 服务器。当转换负载较重时可以将二者拆分部署一份 y-provider 专用于 WebSocket另一份专用于转换。该能力目前仅在官方 Helm Chart 中提供若使用其他部署方式可参考其实现自行落地。4.1 Helm 中一键启用在 Helm values 中启用即可yProvider: converter: enabled: trueyProvider.converter下的所有参数都可以覆盖yProvider下的同名参数values.yaml 中可看到 replicas、resources、service.port、command、args、sidecars、persistence、pdb 等完整可覆盖项Chart 会为此单独生成yprovider_deployment_converter.yaml与yprovider_svc_converter.yaml见 helm/impress/templates 目录。4.2 更新 Django 的 Y_PROVIDER_API_BASE_URL启用拆分后Django 需要指向新生成的转换服务其命名规则是在原服务名后追加-converter拆分前Y_PROVIDER_API_BASE_URL: http://impress-docs-y-provider:443/api/拆分后Y_PROVIDER_API_BASE_URL: http://impress-docs-y-provider-converter:443/api/五、DocSpec 配置启用 .docx 导入5.1 DocSpec 是什么DocSpec 是一个外部服务负责把 legacy 文档格式转换为现代编辑器可访问、可复用的内容。Docs 使用它将.docx文件转换为 BlockNote 内容后接入 Docs 编辑体系从而获得 Docs 的全部能力而规避 legacy 格式的限制。DocSpec 需要自行部署。若使用官方 Helm Chart只需在 values 中启用docSpec: enabled: truevalues.yaml 中提供了docSpec的完整配置项镜像仓库默认ghcr.io/docspecio/api、replicas、command/args、envVars、service.port、探针路径、resources、nodeSelector、tolerations、extraVolumes 等。5.2 安全部署注意事项DocSpec 暴露的是公开 API——任何知道其 URL 的人都可以调用。因此官方强烈建议将其部署在私有网络中仅允许 Docs 后端访问切勿直接暴露到公网。5.3 Django 侧启用 DocSpecDocSpec 部署完成后在 Django 中配置以下环境变量开启 .docx 导入CONVERSION_UPLOAD_ENABLED: True DOCSPEC_API_URL: http://impress-docs-docspec:4000/conversionCONVERSION_UPLOAD_ENABLED是否允许上传文件并转换默认False见 settings.pyDOCSPEC_API_URLDocSpec 转换接口地址。DocSpecConverter会向该地址发送POST请求请求头为Content-Type: 源格式、Accept: application/vnd.blocknotejson见 converter_services.py。六、导入相关的进阶配置项除上述核心变量外settings.py 还暴露了一组与文件导入相关的可调参数供生产环境按需调整环境变量默认值说明CONVERSION_FILE_MAX_SIZEDATA_UPLOAD_MAX_MEMORY_SIZE允许上传转换的文件大小上限字节CONVERSION_FILE_EXTENSIONS_ALLOWED[.docx, .md]允许上传转换的文件扩展名白名单CONVERSION_API_ENDPOINTconvert转换 API 路径段拼接到Y_PROVIDER_API_BASE_URL之后CONVERSION_API_CONTENT_FIELDcontent转换请求中内容字段名CONVERSION_API_TIMEOUT30转换请求超时秒CONVERSION_API_SECUREFalse转换请求是否校验 TLS 证书注意y-provider 侧还有独立的CONVERSION_FILE_MAX_SIZE默认 20 MB见 env.ts上传文件时两侧限制都会生效需确保二者匹配。七、配置速查与典型部署形态7.1 最小配置清单仅启用 Markdown / HTML / JSON 多格式转换无需 .docx 导入# Django Y_PROVIDER_API_BASE_URL: http://{y-provider-service}:443/api/ Y_PROVIDER_API_KEY: a-shared-private-key-with-y-provider # y-provider Y_PROVIDER_API_KEY: a-shared-private-key-with-y-provider启用 .docx 导入追加# Django CONVERSION_UPLOAD_ENABLED: True DOCSPEC_API_URL: http://impress-docs-docspec:4000/conversion7.2 典型部署形态单体形态单一 y-provider 同时承担 WebSocket 与转换适合小规模部署拆分形态Helm 中启用yProvider.converter.enabled将转换负载隔离适合转换频繁或大规模文档导入场景私有化 DocSpecDocSpec 仅部署于内网由 Django 后端通过DOCSPEC_API_URL调用实现安全可控的 .docx 导入。相关参考资源端点实现viewsets.py转换编排与异常converter_services.pyDjango 环境变量定义settings.pyy-provider 转换处理convertHandler.ts、routes.tsy-provider 环境变量与认证env.ts、middlewares.tsHelm 配置values.yaml、部署示例转换服务测试test_services_converter_services.py、convert.test.ts【免费下载链接】docsDocs is an open-source text editor: web-native, made for real-time collaboration, cleanly structured documents and sub-documents with full ownership of your data. Built to scale with Django and React.项目地址: https://gitcode.com/GitHub_Trending/docs150/docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Docs 多格式转换与 .docx 导入：Y-Provider 转换服务与 DocSpec 配置实战指南
Docs 多格式转换与 .docx 导入Y-Provider 转换服务与 DocSpec 配置实战指南【免费下载链接】docsDocs is an open-source text editor: web-native, made for real-time collaboration, cleanly structured documents and sub-documents with full ownership of your data. Built to scale with Django and React.项目地址: https://gitcode.com/GitHub_Trending/docs150/docs本文档是 Docs 项目Django React 构建的 Web 原生实时协作文本编辑器中「格式转换」模块的技术指南覆盖从 Markdown / HTML / JSON 导出到 .docx 导入的完整配置链路。读完本文你将掌握formatted-content端点的用法、Y-Provider 转换服务的环境变量配置与源码调用链、Kubernetes Helm 部署下拆分 WebSocket 与转换服务的方案以及 DocSpec 服务的启用与安全部署建议。一、格式转换能力总览Docs 允许以多种格式操作文档内容导出为 HTML、Markdown、JSON 等格式以 Markdown 复制、粘贴与导入在启用 DocSpec 服务后支持导入.docx文件并转换为 Docs 内部的 Yjs 文档格式。这一切由两个外部服务支撑服务职责备注Y-Providery-provider核心转换引擎在 Markdown / HTML / JSON / Yjs / BlockNote 之间互相转换同时承载实时协作 WebSocket同一服务可拆分部署DocSpec将 legacy 格式如.docx转换为现代编辑器可用的 BlockNote 内容独立部署需自行托管转换链路并非只有文档中明示的配置项还涉及 Django 端的环境变量、y-provider 端的 API 路由与认证机制下面逐层展开。二、转换配置Django 与 Y-Provider 的环境变量2.1 Django 侧指向 Y-Provider 转换 API在 Django 服务中配置以下两个环境变量即可启用转换能力Y_PROVIDER_API_BASE_URL: http://{y-provider-service}:443/api/ Y_PROVIDER_API_KEY: a-shared-private-key-with-y-provider其中Y_PROVIDER_API_BASE_URLy-provider 转换 API 的基地址。可以指向你通过反向代理暴露的 Docs 实例 FQDN需为 y-provider 的/api路由配置代理也可以直接使用 y-provider 内部服务地址。若部署在 Kubernetes 集群中可使用 y-provider 的 Service 名称官方更推荐内部 URL。Y_PROVIDER_API_KEY与 y-provider 共享的私有密钥用于服务间认证。在 settings.py 中这两个值被声明为 Django-environ 变量Y_PROVIDER_API_KEY使用SecretFileValue支持从文件读取密钥Y_PROVIDER_API_BASE_URL使用普通Value两者environ_prefixNone意味着环境变量名与属性名完全一致。2.2 y-provider 侧共享同一个 API Keyy-provider 也必须配置相同的密钥Y_PROVIDER_API_KEY: a-shared-private-key-with-y-provider在 env.ts 中y-provider 通过Y_PROVIDER_API_KEY_FILE优先或Y_PROVIDER_API_KEY环境变量读取该密钥。认证校验位于 middlewares.ts服务维护VALID_API_KEYS列表包含协作服务器密钥与转换 API 密钥并校验请求头authorization是否在其中。注意根据 converter_services.py 的实现Django 端实际发送的是Bearer {Y_PROVIDER_API_KEY}形式注释也特别提醒y-provider 微服务只接受裸 tokenraw token这并非推荐做法仅作为当前实现的事实说明。2.3 formatted-content 端点配置好之后的调用入口完成上述配置后即可使用formatted-content端点获取文档的多格式内容GET /api/v1.0/documents/{document_id}/formatted-content/?content_format(json|html|markdown)该端点由 viewsets.py 中的formatted_contentaction 实现通过content_format查询参数指定输出格式缺省为json仅接受json、markdown、html三种取值否则返回 400从文档对象中取出 Base64 编码的 Yjs 内容base64.b64decode解码调用Converter服务将mime_types.YJS转换为目标格式转换失败时按异常类型返回 400验证失败或 500服务不可用。同一转换服务还被create-for-owner端点以及 Markdown 文件导入流程复用。三、转换调用链的源码级解析3.1 Converter 编排器Django 侧的转换入口是 converter_services.py 中的Converter类它内部组合了两个专用转换器DocSpecConverter处理.docx→ BlockNote 的转换YdocConverter处理 Markdown / Yjs / HTML / JSON 等格式间的转换。convert(data, content_type, accept)的编排逻辑为if content_type mime_types.DOCX and accept mime_types.YJS: blocknote_data self.docspec.convert(data, content_type, mime_types.BLOCKNOTE) return self.ydoc.convert(blocknote_data, mime_types.BLOCKNOTE, mime_types.YJS) return self.ydoc.convert(data, content_type, accept)也就是说.docx导入实际是两段式转换先由 DocSpec 转成 BlockNote JSON再由 y-provider 把 BlockNote 转成 Docs 内部的 Yjs 文档从而让用户享受到 Docs 全部编辑能力而无需受 legacy 格式限制。3.2 YdocConverter 与 y-provider 的 convert 端点YdocConverter._request以POST方式请求{Y_PROVIDER_API_BASE_URL}{CONVERSION_API_ENDPOINT}/端点默认值为convert见 settings.py携带Authorization、Content-Type、Accept三个请求头并受CONVERSION_API_TIMEOUT默认 30 秒与CONVERSION_API_SECURE默认 False控制。y-provider 侧对应的处理逻辑位于 convertHandler.ts路由定义为CONVERT: /api/convert/见 routes.ts。其支持的输入输出矩阵如下方向Content-Type输入Accept输出说明读取text/markdown、text/x-markdown、application/x-www-form-urlencoded—后者为向后兼容按 Markdown 解析读取application/vnd.yjs.doc、application/octet-stream—Yjs 二进制更新读取application/vnd.blocknotejson—BlockNote JSON写出—application/vnd.blocknotejson、application/json返回 blocks写出—application/vnd.yjs.doc、application/octet-stream编码为 Yjs state update写出—text/markdown、text/x-markdownblocksToMarkdownLossy有损写出—text/htmlblocksToHTMLLossy有损转换基于服务端ServerBlockNoteEditorBlockNote 的服务器端编辑器并将CommentsExtension注册进 schema以保留评论标记mark在转换中的完整性——若缺少该扩展被评论包裹的文本在转换时会被静默丢弃导致相关块变空。在YdocConverter.convert的返回处理中converter_services.py输出为 Yjs 时将二进制响应base64编码后返回字符串输出为 Markdown / HTML 时返回文本输出为 JSON 时解析为对象返回。3.3 异常与错误语义转换模块定义了三个异常类型converter_services.pyConversionError基类ValidationError输入校验失败空数据、不支持的格式组合对应 400ServiceUnavailableError无法连接转换服务或请求异常对应 500。y-provider 侧则按 HTTP 语义返回请求体为空返回 400、不支持的 Content-Type 返回 415、不支持的 Accept 返回 406、内容解析失败返回 400、服务端异常返回 500并将错误上报 Sentry。四、拆分转换服务WebSocket 与 Converter 分而治之转换服务与 WebSocket 服务同属于 y-provider 服务器。当转换负载较重时可以将二者拆分部署一份 y-provider 专用于 WebSocket另一份专用于转换。该能力目前仅在官方 Helm Chart 中提供若使用其他部署方式可参考其实现自行落地。4.1 Helm 中一键启用在 Helm values 中启用即可yProvider: converter: enabled: trueyProvider.converter下的所有参数都可以覆盖yProvider下的同名参数values.yaml 中可看到 replicas、resources、service.port、command、args、sidecars、persistence、pdb 等完整可覆盖项Chart 会为此单独生成yprovider_deployment_converter.yaml与yprovider_svc_converter.yaml见 helm/impress/templates 目录。4.2 更新 Django 的 Y_PROVIDER_API_BASE_URL启用拆分后Django 需要指向新生成的转换服务其命名规则是在原服务名后追加-converter拆分前Y_PROVIDER_API_BASE_URL: http://impress-docs-y-provider:443/api/拆分后Y_PROVIDER_API_BASE_URL: http://impress-docs-y-provider-converter:443/api/五、DocSpec 配置启用 .docx 导入5.1 DocSpec 是什么DocSpec 是一个外部服务负责把 legacy 文档格式转换为现代编辑器可访问、可复用的内容。Docs 使用它将.docx文件转换为 BlockNote 内容后接入 Docs 编辑体系从而获得 Docs 的全部能力而规避 legacy 格式的限制。DocSpec 需要自行部署。若使用官方 Helm Chart只需在 values 中启用docSpec: enabled: truevalues.yaml 中提供了docSpec的完整配置项镜像仓库默认ghcr.io/docspecio/api、replicas、command/args、envVars、service.port、探针路径、resources、nodeSelector、tolerations、extraVolumes 等。5.2 安全部署注意事项DocSpec 暴露的是公开 API——任何知道其 URL 的人都可以调用。因此官方强烈建议将其部署在私有网络中仅允许 Docs 后端访问切勿直接暴露到公网。5.3 Django 侧启用 DocSpecDocSpec 部署完成后在 Django 中配置以下环境变量开启 .docx 导入CONVERSION_UPLOAD_ENABLED: True DOCSPEC_API_URL: http://impress-docs-docspec:4000/conversionCONVERSION_UPLOAD_ENABLED是否允许上传文件并转换默认False见 settings.pyDOCSPEC_API_URLDocSpec 转换接口地址。DocSpecConverter会向该地址发送POST请求请求头为Content-Type: 源格式、Accept: application/vnd.blocknotejson见 converter_services.py。六、导入相关的进阶配置项除上述核心变量外settings.py 还暴露了一组与文件导入相关的可调参数供生产环境按需调整环境变量默认值说明CONVERSION_FILE_MAX_SIZEDATA_UPLOAD_MAX_MEMORY_SIZE允许上传转换的文件大小上限字节CONVERSION_FILE_EXTENSIONS_ALLOWED[.docx, .md]允许上传转换的文件扩展名白名单CONVERSION_API_ENDPOINTconvert转换 API 路径段拼接到Y_PROVIDER_API_BASE_URL之后CONVERSION_API_CONTENT_FIELDcontent转换请求中内容字段名CONVERSION_API_TIMEOUT30转换请求超时秒CONVERSION_API_SECUREFalse转换请求是否校验 TLS 证书注意y-provider 侧还有独立的CONVERSION_FILE_MAX_SIZE默认 20 MB见 env.ts上传文件时两侧限制都会生效需确保二者匹配。七、配置速查与典型部署形态7.1 最小配置清单仅启用 Markdown / HTML / JSON 多格式转换无需 .docx 导入# Django Y_PROVIDER_API_BASE_URL: http://{y-provider-service}:443/api/ Y_PROVIDER_API_KEY: a-shared-private-key-with-y-provider # y-provider Y_PROVIDER_API_KEY: a-shared-private-key-with-y-provider启用 .docx 导入追加# Django CONVERSION_UPLOAD_ENABLED: True DOCSPEC_API_URL: http://impress-docs-docspec:4000/conversion7.2 典型部署形态单体形态单一 y-provider 同时承担 WebSocket 与转换适合小规模部署拆分形态Helm 中启用yProvider.converter.enabled将转换负载隔离适合转换频繁或大规模文档导入场景私有化 DocSpecDocSpec 仅部署于内网由 Django 后端通过DOCSPEC_API_URL调用实现安全可控的 .docx 导入。相关参考资源端点实现viewsets.py转换编排与异常converter_services.pyDjango 环境变量定义settings.pyy-provider 转换处理convertHandler.ts、routes.tsy-provider 环境变量与认证env.ts、middlewares.tsHelm 配置values.yaml、部署示例转换服务测试test_services_converter_services.py、convert.test.ts【免费下载链接】docsDocs is an open-source text editor: web-native, made for real-time collaboration, cleanly structured documents and sub-documents with full ownership of your data. Built to scale with Django and React.项目地址: https://gitcode.com/GitHub_Trending/docs150/docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考