从 Word 导入和导出到 Word

概述

“从 Word 导入”和“导出到 Word"服务是一组在本地主机基础设施内运行的服务器端转换器组件。它们提供：

• 导出：将结构化 HTML 内容（例如使用 TinyMCE 编辑器创建的内容）转换为 .docx Microsoft Word 文件。

• 导入：将来自 .docx 和 .dotx 文件的内容转换为带有样式的 HTML。

这些服务可以通过两种方式使用：

• 作为 TinyMCE 编辑器中 从 Word 导入 和 导出到 Word 插件的后端。

• 直接通过 REST API，独立于编辑器。

运行本地的“从 Word 导入”和“导出到 Word"服务需要有效的服务许可证密钥。此密钥与 TinyMCE 编辑器许可证密钥分开。还需要访问令牌才能访问 Tiny Cloud Docker 注册表并拉取 Docker 镜像。有关更多信息，请参阅 服务许可证密钥。

要开始使用，请联系 Tiny 支持团队获取试用服务许可证密钥和 Docker 访问令牌。

在本地运行“从 Word 导入”和“导出到 Word"服务的唯一要求是容器运行时或编排工具，例如 Docker、Kubernetes 或 Podman。

要求

要运行本地的“从 Word 导入”和“导出到 Word"，需要一个 Docker 环境。或者，使用云提供商提供的 CaaS，例如 AWS ECS、Google GKE 或 Azure ACS。

有许多因素可能会影响本地“导出到 Word"的性能。最具影响力的因素包括：导出内容的大小、图像的大小以及并发请求的数量。此外，因为您的应用程序可以优先考虑快速响应时间，或者应该处理高负载，所以不可能提供一个适合所有用例的推荐服务器规格。

假设响应时间在 10 秒以下，一台服务器（2CPU 2GB RAM）带有一个 Docker 容器可以处理：

• 最多 45 个并发请求，平均内容为 1 页 A4 (~1k 字符)

• 最多 30 个并发请求，平均内容为 5 页 A4 (~7,5k 字符)

• 最多 10 个并发请求，平均内容为 20 页 A4 (~30k 字符)

列出的并发请求数量不是本地“从 Word 导入”和“导出到 Word"实例的硬性限制。它可以处理更多并发请求，但响应时间会更长。

高可用性

一个包含本地“从 Word 导入”和“导出到 Word"的 Docker 容器可以从机器的额外 CPU 中受益。建议每个 Docker 容器分配 2 个 CPU。要在单台机器上扩展应用程序，请增加 CPU 数量和 Docker 容器数量，但是 TinyMCE 建议在至少三台主机上进行扩展以确保系统的可靠性。

在多台机器上扩展时需要负载均衡器，如 HAProxy 或 NGINX（请参阅 SSL 通信指南中的负载均衡器配置示例）。当然，可以使用任何云提供商进行扩展，如 Amazon ECS、Azure Container Instances 或 Kubernetes。

如果您有关于运行本地“从 Word 导入”和“导出到 Word"所需的服务器资源的任何问题，请联系我们。

安装

运行本地的“从 Word 导入”和“导出到 Word"服务需要两个单独的凭据：

• Docker 注册表访问令牌，用于与 Tiny Docker 注册表进行身份验证并拉取服务镜像。

• 服务许可证密钥，用于在运行时启用服务。此密钥与 TinyMCE 编辑器许可证密钥分开。

详细信息请参阅 服务许可证密钥。联系我们获取试用服务许可证密钥。

支持的技术

默认情况下，该应用程序以 Docker 镜像形式提供。

它可以与任何 Open Container 运行时工具一起运行，例如 Kubernetes、OpenShift、Podman、Docker 等。

有关运行本地“从 Word 导入”和“导出到 Word"的硬件和软件要求的更多信息，请参阅要求指南。

使用 Docker 容器设置应用程序

1. 登录 Docker 注册表并使用提供的访问令牌检索 Docker 镜像。

2. 使用 docker 或 docker-compose 对应用程序进行容器化。

3. 使用演示页面验证应用程序是否正常工作。

使用 docker 进行容器化的示例

登录 Docker 注册表：

docker login -u tiny -p [access-token] registry.containers.tiny.cloud

拉取 Docker 镜像：

docker pull registry.containers.tiny.cloud/docx-converter-tiny:[version]

要查看所有可用的 Docker 镜像版本，请参阅 docx-converter-tiny 中的更改日志。

为了确保能够访问服务的最新版本，Tiny 建议在拉取镜像时使用 latest 标签。

启动 Docker 容器：

docker run --init -p 8080:8080 -e LICENSE_KEY="$DOCX_LICENSE_KEY" registry.containers.tiny.cloud/docx-converter-tiny:[version]

用服务许可证密钥替换 $DOCX_LICENSE_KEY，或将 DOCX_LICENSE_KEY 设置为环境变量。有关详细信息，请参阅 使用特定于服务的环境变量。

如果使用授权，请提供 SECRET_KEY：

docker run --init -p 8080:8080 -e LICENSE_KEY="$DOCX_LICENSE_KEY" -e SECRET_KEY=[your_secret_key] registry.containers.tiny.cloud/docx-converter-tiny:[version]

有关使用授权的更多信息，请参阅授权部分。

使用 docker-compose 进行容器化的示例

1. 创建 docker-compose.yml 文件：

   version: "3.8"
   services:
     doc-converter:
       image: registry.containers.tiny.cloud/docx-converter-tiny:[version]
       ports:
         - "8080:8080"
       restart: always
       init: true
       environment:
         LICENSE_KEY: "${DOCX_LICENSE_KEY}"
         # Secret Key is optional
         SECRET_KEY: "secret_key"

   有关 SECRET_KEY 使用的详细信息，请检查授权部分。

2. 运行：

docker compose up

• 如果没有正确的 LICENSE_KEY，应用程序将无法启动。在 .env 文件或 shell 环境中设置 DOCX_LICENSE_KEY，并输入有效的服务许可证密钥。

  • 如果许可证无效，日志中将显示错误的许可证密钥错误，并且应用程序将不会运行。

• 出于安全原因，建议使用独特且难以猜测的字符串覆盖 SECRET_KEY 变量。

后续步骤

使用 http://localhost:8080/v2/convert/html-docx 端点导出 DOCX 文件。查看授权部分以了解更多关于令牌和令牌端点的信息。

使用位于 http://localhost:8080/demo 的演示页面生成示例 DOCX 文件。

有关更多详细信息，请参阅 http://localhost:8080/docs 上的“从 Word 导入”和“导出到 Word"REST API 文档。

授权

要启用授权，请在安装期间设置 SECRET_KEY 环境变量。

如果设置了 SECRET_KEY 变量，则所有请求都必须具有使用此密钥签名的 JWT (JSON Web Token) 标头。令牌应作为发送给“从 Word 导入”和“导出到 Word"REST API 的每个请求的 Authorization 标头的值传递。

如果在安装期间未设置 SECRET_KEY，则当向“从 Word 导入”和“导出到 Word"REST API 发送请求时，本地的“从 Word 导入”和“导出到 Word"将不需要任何带有令牌的标头。但是，不建议在公共网络中运行本地的“从 Word 导入”和“导出到 Word"时跳过授权。

生成令牌

Tiny 建议使用 jwt.io 上列出的库来生成令牌。当满足以下条件时，令牌被视为有效：

• 它使用与传递给本地“从 Word 导入”和“导出到 Word"实例相同的 SECRET_KEY 签名，

• 它在过去 24 小时内创建，

• 它不是在将来发行的（即 iat 时间戳不能比当前时间更新），

• 它尚未过期。

用于“从 Word 导入”和“本地部署导出到 Word"的令牌不需要任何额外的声明，例如 aud（该声明仅针对基于云端的文档转换器），因此可以使用空负载创建令牌。

如果特定用例涉及从后端服务器发送请求，则可以像下面的请求示例所示在本地生成 JWT 令牌。

对于编辑器插件或其他前端用途，应创建一个令牌端点，为授权用户返回有效的 JWT 令牌。

使用编辑器插件

TinyMCE 有两个可用的插件：从 Word 导入 和 导出到 Word 插件。这些插件将自动从给定的 tokenUrl 变量请求令牌，并在发出导出请求时设置 Authorization 头。有关将“从 Word 导入”和“导出到 Word"功能添加到您的 WYSIWYG 编辑器的详细信息，请参阅各自的指南！

带有 Authorization 头的请求示例

以下示例展示了一个生成有效 JWT 令牌并将其设置为 Authorization 头的请求：

const fs = require( 'fs' );
const jwt = require( 'jsonwebtoken' );
const axios = require( 'axios' );

const SECRET_KEY = 'secret';

const token = jwt.sign( {}, SECRET_KEY, { algorithm: 'HS256' } );

const data = {
   html: "<p>I am a teapot</p>",
   css: "p { color: red; }",
};

const config = {
   headers: {
      Authorization: token
   },
   responseType: 'arraybuffer',
};

axios.post( 'http://localhost:8080/v2/convert/html-docx', data, config )
   .then( response => {
      fs.writeFileSync('./file.docx', response.data, 'binary');
   } ).catch( error => {
      console.log( error );
   } );

SECRET_KEY：这是传递给“从 Word 导入”和“本地部署导出到 Word"实例的密钥。

请参阅 从 Word 导入 和 导出到 Word REST API 文档以开始使用该服务。

如果使用 Postman 或 Insomnia 等 API 客户端，请在 Headers 选项卡中将 JWT 令牌设置为 Authorization 头。不要使用内置的令牌授权，因为这会生成无效的头部，其中会在令牌前添加 Bearer 前缀。

API 用法

“从 Word 导入”和“本地部署导出到 Word"由两个服务组成：

• 导出到 Word 通过 Restful API 提供将 HTML 文档转换为 .docx 文件的功能。

• 从 Word 导入 允许导入 .docx 文件并将其转换为带有注释和建议的样式化 HTML 文档。

API 可在 http://localhost:[port] 上使用（默认端口为 8080）。

REST API 文档位于 http://localhost:[port]/v2/convert/docs。或者，您可以查看我们公共资源中关于 从 Word 导入 和 导出到 Word 插件的规范。

如果您启用了 API 授权，则应提供授权令牌。更多说明请参见授权部分。

SSL 通信

可以使用安全连接与“从 Word 导入”和“本地部署导出到 Word"进行通信。为此，需要使用 SSL 证书配置负载均衡器，如 NGINX 或 HAProxy。

以下是 HAProxy 和 NGINX 的配置示例。

HAProxy 示例

这是一个基本的 HAProxy 配置：

global
  daemon
  maxconn 256
  tune.ssl.default-dh-param 2048

defaults
  mode http
  timeout connect 5000ms
  timeout client 50000ms
  timeout server 50000ms

frontend http-in
  bind *:80
  bind *:443 ssl crt /etc/ssl/your_certificate.pem
  http-request set-header X-Forwarded-Proto https if { ssl_fc }
  http-request set-header X-Forwarded-Proto http if !{ ssl_fc }
  redirect scheme https if !{ ssl_fc }

  default_backend servers

backend servers
  server server1 127.0.0.1:8080 maxconn 32

NGINX 示例

这是一个基本的 NGINX 配置：

events {
    worker_connections  1024;
}

http {
  server {
    server_name your.domain.name;

    listen 443;
    ssl on;
    ssl_certificate /etc/ssl/your_cert.crt;
    ssl_certificate_key /etc/ssl/your_cert_key.key;

    location / {
      proxy_pass http://127.0.0.1:8080;

      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection "Upgrade";
      proxy_set_header Host $host;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_http_version 1.1;
    }
  }
}

Docker 镜像不包含内置的 SSL 配置。必须由反向代理处理 SSL，并将请求转发到容器上的 HTTP 服务（端口 8080）。

日志

“从 Word 导入”和“本地部署导出到 Word"的日志写入 stdout 和 stderr。大多数日志格式化为 JSON。它们可用于监控或调试目的。在生产环境中，建议将日志存储到文件中或使用分布式日志系统（如 ELK 或 CloudWatch）。

使用日志监控“从 Word 导入”和“本地部署导出到 Word"

为了更深入地了解“从 Word 导入”和“本地部署导出到 Word"的运行情况，可以使用日志进行监控。要启用这些功能，请添加 ENABLE_METRIC_LOGS=true 环境变量。

日志结构

日志结构包含以下信息：

• handler：操作的统一标识符。使用此字段来识别调用。

• traceId：唯一的 RPC 调用 ID。

• tags：分号分隔的标签列表。使用此字段过滤指标日志。

• data：包含附加信息的对象。它在不同传输方式之间可能有所不同。

• data.duration：请求持续时间（毫秒）。

• data.transport：请求传输的类型。可以是 http 或 ws（websocket）。

• data.status：请求状态。它可以等于 success、fail 或 warning。

• data.statusCode：HTTP 状态码标准中的响应状态。

此外，对于 HTTP 传输，还包括以下信息：

• data.url：URL 路径。

• data.method：请求方法。

如果发生错误，data.status 将等于 failed，且 data.message 将包含错误消息。

HTTP 传输的日志示例：

{
  "level": 30,
  "time": "2021-03-09T11:15:09.154Z",
  "msg": "Request summary",
  "handler": "postConvert",
  "traceId": "85f13d92-57df-4b3b-98bb-0ca41a5ae601",
  "data": {
    "duration": 752,
    "transport": "http",
    "statusCode": 200,
    "status": "success",
    "url": "/v2/convert/html-docx",
    "method": "POST"
  },
  "tags": "metrics"
}

Docker

Docker 具有内置的日志机制，可捕获容器的输出日志。默认日志驱动程序将日志写入文件。

使用此驱动程序时，请使用 docker logs 命令显示容器的日志。使用 -f 标志实时查看日志。有关日志命令的更多信息，请参阅 官方 Docker 文档。

当容器长时间运行时，日志可能会占用大量空间。为了避免这个问题，您应该确保已启用日志轮转。这可以通过 max-size 选项设置。

分布式日志

如果运行多个“从 Word 导入”和“本地部署导出到 Word"实例，建议使用分布式日志系统。它允许在一个地方查看和分析所有实例的日志。

AWS CloudWatch 和其他云服务解决方案

如果在云中运行“从 Word 导入”和“本地部署导出到 Word"，最简单且推荐的方法是使用所选提供商提供的服务。

以下是一些可用服务：

• AWS：CloudWatch

• Google Cloud：Cloud Logging

• Azure：Azure Monitor

要在 AWS ECS 中使用 CloudWatch，必须预先创建日志组，并将日志驱动程序更改为 awslogs。正确配置日志驱动程序后，日志将直接流式传输到 CloudWatch。

logConfiguration 可能看起来如下：

"logConfiguration": {
  "logDriver": "awslogs",
  "options": {
    "awslogs-region": "us-west-2",
    "awslogs-group": "tinysource",
    "awslogs-stream-prefix": "tiny-docx-converter-logs"
  }
}

有关更多信息，请参阅使用 awslogs 日志驱动程序文章。

本地解决方案

如果使用特定基础设施（例如您自己的基础设施）或因某些原因无法使用提供商提供的服务，可以使用一些本地分布式日志系统。

目前有大量可用的解决方案，包括：

• ELK + Filebeat

这是基于 Elasticsearch、Logstash 和 Kibana 构建的堆栈。在此配置中，Elasticsearch 存储日志，Filebeat 从 Docker 读取日志并将其发送到 Elasticsearch，而 Kibana 用于查看它们。由于日志已经是结构化的，因此不需要 Logstash。

• Fluentd

它使用专用的Docker 日志驱动程序来发送日志。它具有内置的前端，也可以与 Elasticsearch 和 Kibana 集成以实现更好的过滤。

• Graylog

它使用专用的Docker日志驱动程序来发送日志。它具有内置的前端，需要 Elasticsearch 来存储日志，还需要 MongoDB 数据库来存储配置。

示例配置

此示例配置使用 Fluentd、Elasticsearch 和 Kibana 捕获来自 Docker 的日志。

在运行“从 Word 导入”和“导出到 Word 本地版”之前，请准备好日志服务。为了本示例的目的，使用了 Docker Compose。在docker-compose.yml文件中创建fluentd、elasticsearch和kibana服务：

version: '3.7'
services:
  fluentd:
    build: ./fluentd
    volumes:
      - ./fluentd/fluent.conf:/fluentd/etc/fluent.conf
    ports:
      - "24224:24224"
      - "24224:24224/udp"

  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:6.8.5
    expose:
      - 9200
    ports:
      - "9200:9200"

  kibana:
    image: docker.elastic.co/kibana/kibana:6.8.5
    environment:
      ELASTICSEARCH_HOSTS: "http://elasticsearch:9200"
    ports:
      - "5601:5601"

要将 Fluentd 与 Elasticsearch 集成，首先需要在 Fluentd 镜像中安装fluent-plugin-elasticsearch。为此，创建一个fluentd/Dockerfile，内容如下：

FROM fluent/fluentd:v1.10-1

USER root

RUN apk add --no-cache --update build-base ruby-dev \
  && gem install fluent-plugin-elasticsearch \
  && gem sources --clear-all

接下来，在fluentd/fluent.conf文件中配置输入服务器和到 Elasticsearch 的连接：

<source>
  @type forward
  port 24224
  bind 0.0.0.0
</source>
<match *.**>
  @type copy
  <store>
    @type elasticsearch
    host elasticsearch
    port 9200
    logstash_format true
    logstash_prefix fluentd
    logstash_dateformat %Y%m%d
    include_tag_key true
    type_name access_log
    tag_key @log_name
    flush_interval 1s
  </store>
  <store>
    @type stdout
  </store>
</match>

现在服务已准备就绪，可以运行：

docker-compose up --build

当服务就绪后，启动“从 Word 导入”和“导出到 Word 本地版”。

docker run --init -p 8080:8080 \
--log-driver=fluentd \
--log-opt fluentd-address=[Fluentd address]:24224 \
[Your config here] \
registry.containers.tiny.cloud/docx-converter-tiny:[version]

• 在浏览器中打开 Kibana。

  • 访问地址为http://localhost:5601/。

• 在首次运行时，可能会提示您创建索引。

• 使用fluentd-*模式并按“Create"按钮。

• 完成此步骤后，日志应出现在"Discover"标签页中。