适用于 Kubernetes 的 ONLYOFFICE 文档

1. 部署 ONLYOFFICE 文档许可证

1. 创建密钥

   如果您有有效的 ONLYOFFICE 文档许可证，请从文件创建名为license的密钥：

   $ kubectl create secret generic [SECRET_LICENSE_NAME] --from-file=path/to/license.lic

   其中SECRET_LICENSE_NAME是带有许可证的未来密钥的名称。

   源许可证文件名应为 'license.lic'，因为此名称将用作创建密钥中的字段。
   如果安装时没有使用现有许可证文件创建密钥，则会自动创建一个空的密钥license。有关如何更新现有许可证密钥的信息，请参阅此处。
2. 在安装 ONLYOFFICE 文档时指定参数

   安装 ONLYOFFICE 文档时，指定license.existingSecret=[SECRET_LICENSE_NAME]参数。

   $ helm install documentserver onlyoffice/docs --set license.existingSecret=[SECRET_LICENSE_NAME]

   如果需要在 ONLYOFFICE 文档已安装后添加许可证，您需要执行步骤 1.1，然后运行helm upgrade documentserver onlyoffice/docs --set license.existingSecret=[SECRET_LICENSE_NAME] --no-hooks命令，或者如果参数已在values.yaml文件中指定，则运行helm upgrade documentserver -f ./values.yaml onlyoffice/docs --no-hooks。

2. 部署 ONLYOFFICE 文档

使用发布名称documentserver部署 ONLYOFFICE 文档：

$ helm install documentserver onlyoffice/docs

该命令在默认配置下将 ONLYOFFICE 文档部署到 Kubernetes 集群上。参数部分列出了可以在安装过程中配置的参数。

3. 卸载 ONLYOFFICE 文档

要卸载/删除documentserver部署：

$ helm delete documentserver

执行helm delete命令会启动钩子，这些钩子在完全删除 ONLYOFFICE 文档之前执行一些准备操作，包括停止服务器、清理已使用的 PVC 和数据库表。默认的钩子执行时间为 300 秒。可以使用--timeout [time]更改执行时间，例如：

$ helm delete documentserver --timeout 25m

如果您想删除 ONLYOFFICE 文档而不执行任何准备操作，请运行以下命令：

$ helm delete documentserver --no-hooks

helm delete命令会删除与 Chart 关联的所有 Kubernetes 组件，并删除该发布。

4. 参数

• *注意：镜像仓库的值中指定了后缀 -de，这代表解决方案类型。可能的选项：
  • -de。用于商业开发者版。
  • -ee。用于商业企业版。

  此参数的默认值指向 ONLYOFFICE 文档服务器开发者版。要了解有关此版本的更多信息并将其与其他版本进行比较，请参阅此页面上的比较表。

使用 --set key=value[,key=value] 参数为 helm install 指定每个参数。例如：

$ helm install documentserver onlyoffice/docs --set ingress.enabled=true,ingress.ssl.enabled=true,ingress.host=example.com

此命令通过 HTTPS 暴露 ONLYOFFICE 文档。

或者，可以在安装 Chart 时提供一个 YAML 文件来指定参数的值。例如：

$ helm install documentserver -f values.yaml onlyoffice/docs

5. 配置和安装细节

1. 示例部署（可选）

   要部署示例，请将 example.enabled 参数设置为 true：

   $ helm install documentserver onlyoffice/docs --set example.enabled=true

2. 指标部署（可选）

   要部署指标，请将 metrics.enabled 设置为 true：

   $ helm install documentserver onlyoffice/docs --set metrics.enabled=true

   如果您想使用 Grafana 可视化指标，请将 grafana.enabled 设置为 true。如果您想使用 Nginx Ingress 访问 Grafana，请将 grafana.ingress.enabled 设置为 true：

   $ helm install documentserver onlyoffice/docs --set grafana.enabled=true --set grafana.ingress.enabled=true

3. 暴露 ONLYOFFICE 文档
   1. 通过服务暴露 ONLYOFFICE 文档（仅限 HTTP）
      如果您打算通过 HTTPS 暴露 ONLYOFFICE 文档，应跳过此步骤。

      这种暴露方式性能开销最小，它会创建一个负载均衡器来访问 ONLYOFFICE 文档。如果您使用外部 TLS 终结，并且 k8s 集群中没有其他 WEB 应用程序，请使用此暴露类型。

      要通过服务暴露 ONLYOFFICE 文档，请将 service.type 参数设置为 LoadBalancer：

      $ helm install documentserver onlyoffice/docs --set service.type=LoadBalancer,service.port=80

      运行以下命令获取 documentserver 服务的 IP：

      $ kubectl get service documentserver -o jsonpath="{.status.loadBalancer.ingress[*].ip}"

      之后，ONLYOFFICE 文档将在 http://DOCUMENTSERVER-SERVICE-IP/ 可用。

      如果服务 IP 为空，请尝试获取 documentserver 服务的主机名：

      $ kubectl get service documentserver -o jsonpath="{.status.loadBalancer.ingress[*].hostname}"

      在这种情况下，ONLYOFFICE 文档将在 http://DOCUMENTSERVER-SERVICE-HOSTNAME/ 可用。

   2. 通过 Ingress 暴露 ONLYOFFICE 文档
      1. 安装 Kubernetes Nginx Ingress 控制器

         要将 Nginx Ingress 控制器安装到您的集群，请运行以下命令：

         $ helm install nginx-ingress ingress-nginx/ingress-nginx --set controller.publishService.enabled=true,controller.replicaCount=2

         要使用相同参数安装 Nginx Ingress 并启用暴露 ingress-nginx 指标供 Prometheus 收集，请运行以下命令：

         $ helm install nginx-ingress -f https://raw.githubusercontent.com/ONLYOFFICE/Kubernetes-Docs/master/sources/ingress_values.yaml ingress-nginx/ingress-nginx

         有关通过 Helm 安装 Nginx Ingress 的更多详细信息，请参阅此处。

      2. 通过 HTTP 暴露 ONLYOFFICE 文档
         如果您打算通过 HTTPS 暴露 ONLYOFFICE 文档，应跳过此步骤。

         与服务暴露相比，这种暴露方式性能开销更大，它也会创建一个负载均衡器来访问 ONLYOFFICE 文档。如果您使用外部 TLS 终结，并且 k8s 集群中有多个 WEB 应用程序，请使用此类型。您可以为它们使用一组 Ingress 实例和一个负载均衡器。这可以优化入口点性能并减少您的集群费用，因为提供商可能会对每个负载均衡器收费。

         要通过 Ingress HTTP 暴露 ONLYOFFICE 文档，请将 ingress.enabled 参数设置为 true：

         $ helm install documentserver onlyoffice/docs --set ingress.enabled=true

         运行以下命令获取 documentserver Ingress 的 IP：

         $ kubectl get ingress documentserver -o jsonpath="{.status.loadBalancer.ingress[*].ip}"

         之后，ONLYOFFICE 文档将在 http://DOCUMENTSERVER-INGRESS-IP/ 可用。

         如果 Ingress IP 为空，请尝试获取 documentserver Ingress 的主机名：

         $ kubectl get ingress documentserver -o jsonpath="{.status.loadBalancer.ingress[*].hostname}"

         在这种情况下，ONLYOFFICE 文档将在 http://DOCUMENTSERVER-INGRESS-HOSTNAME/ 可用。

      3. 通过 HTTPS 暴露 ONLYOFFICE 文档

         这种暴露方式允许您为 ONLYOFFICE 文档启用内部 TLS 终结。

         创建包含 SSL 证书的 tls 密钥。

         将 SSL 证书和私钥放入 tls.crt 和 tls.key 文件中，然后运行：

         $ kubectl create secret generic tls \
           --from-file=./tls.crt \
           --from-file=./tls.key

         $ helm install documentserver onlyoffice/docs --set ingress.enabled=true,ingress.ssl.enabled=true,ingress.host=example.com

         运行以下命令获取 documentserver Ingress 的 IP：

         $ kubectl get ingress documentserver -o jsonpath="{.status.loadBalancer.ingress[*].ip}"

         如果 Ingress IP 为空，请尝试获取 documentserver Ingress 的主机名：

         $ kubectl get ingress documentserver -o jsonpath="{.status.loadBalancer.ingress[*].hostname}"

         通过您的 DNS 提供商将 documentserver Ingress IP 或主机名与您的域名关联起来。

         之后，ONLYOFFICE 文档将在 https://your-domain-name/ 可用。

      4. 使用 Let's Encrypt 证书通过 HTTPS 暴露 ONLYOFFICE 文档
         • 添加 Helm 仓库：

           $ helm repo add jetstack https://charts.jetstack.io
           $ helm repo update

         • 安装 cert-manager

           $ helm install cert-manager --version v1.17.4 jetstack/cert-manager \
             --namespace cert-manager \
             --create-namespace \
             --set crds.enabled=true \
             --set crds.keep=false

           接下来，通过将 ingress.enabled、ingress.ssl.enabled 和 ingress.letsencrypt.enabled 参数设置为 true 来执行安装或升级。同时，在参数 ingress.letsencrypt.email、ingress.host 或 ingress.tenants（例如，--set "ingress.tenants={tenant1.example.com,tenant2.example.com}"）中设置您自己的值，如果您想使用多个域名。

   3. 在虚拟路径上暴露 ONLYOFFICE 文档

      这种暴露方式允许您在虚拟路径上暴露 ONLYOFFICE 文档，例如 http://your-domain-name/docs。要通过 Ingress 在虚拟路径上暴露 ONLYOFFICE 文档，请设置 ingress.enabled、ingress.host 和 ingress.path 参数。

      $ helm install documentserver onlyoffice/docs --set ingress.enabled=true,ingress.host=your-domain-name,ingress.path=/docs

      支持虚拟路径配置的 Ingress 控制器列表：

      • Ingress NGINX by Kubernetes
      • NGINX Ingress by NGINX
      • HAProxy Ingress by HAProxy

      对于使用 Ingress NGINX by Kubernetes 的虚拟路径配置，请将模式 (/|$)(.*) 附加到 ingress.path，例如 /docs 变为 /docs(/|$)(.*)。

4. 在 OpenShift 中通过路由暴露 ONLYOFFICE 文档

   这种暴露方式允许您在 OpenShift 中通过路由暴露 ONLYOFFICE 文档。要通过路由暴露 ONLYOFFICE 文档，请使用以下参数：openshift.route.enabled、openshift.route.host、openshift.route.path。

   $ helm install documentserver onlyoffice/docs --set openshift.route.enabled=true,openshift.route.host=your-domain-name,openshift.route.path=/docs

   对于 tls 终结，请通过 OpenShift Web 控制台手动将证书添加到路由。

6. 扩展 ONLYOFFICE 文档（可选）

1. 水平 Pod 自动缩放

   您可以启用自动缩放，以便根据指标的值和类型自动计算 docservice 和 converter 部署的副本数。

   对于资源指标，必须注册 API metrics.k8s.io，这通常由 metrics-server 提供。它可以作为集群附加组件启动。

   要使用目标利用率值（target.type==Utilization），必须在部署中指定 resources.requests 的值。

   有关水平 Pod 自动缩放的更多信息，请参阅此处。

   要为 docservice 部署启用 HPA，请指定 docservice.autoscaling.enabled=true 参数。在这种情况下，docservice.replicas 参数将被忽略，副本数由 HPA 控制。

   类似地，要为 converter 部署启用 HPA，请指定 converter.autoscaling.enabled=true 参数。在这种情况下，converter.replicas 参数将被忽略，副本数由 HPA 控制。

   启用 autoscaling.enabled 参数后，默认情况下自动缩放将根据平均 CPU 利用率百分比调整副本数。有关其他可配置的自动缩放参数，请参阅参数表。

2. 手动缩放

   docservice 和 converter 部署默认各包含 2 个 Pod。

   要缩放 docservice 部署，请使用以下命令：

   $ kubectl scale -n default deployment docservice --replicas=POD_COUNT

   其中 POD_COUNT 是 docservice Pod 的数量。

   对 converter 部署执行相同操作：

   $ kubectl scale -n default deployment converter --replicas=POD_COUNT

7. 更新 ONLYOFFICE 文档

必须设置更新参数。例如：

$ helm upgrade documentserver onlyoffice/docs \
  --set docservice.image.tag=[version]

或者修改 values.yaml 文件并运行命令：

$ helm upgrade documentserver -f values.yaml onlyoffice/docs

运行 helm upgrade 命令会启动一个钩子，该钩子会关闭 ONLYOFFICE 文档并清理数据库。这在更新 ONLYOFFICE 文档版本时需要。默认的钩子执行时间为 300 秒。可以使用 --timeout [time] 更改执行时间，例如：

$ helm upgrade documentserver -f values.yaml onlyoffice/docs --timeout 15m

如果您想更新 ONLYOFFICE 文档版本以外的任何参数，请在 helm upgrade 命令中不带 hooks 运行，例如：

$ helm upgrade documentserver onlyoffice/docs --set jwt.enabled=false --no-hooks

要回滚更新，请运行以下命令：

$ helm rollback documentserver

8. 关闭 ONLYOFFICE 文档（可选）

要执行关闭，请运行以下命令：

$ kubectl apply -f https://raw.githubusercontent.com/ONLYOFFICE/Kubernetes-Docs/master/sources/shutdown-ds.yaml -n <NAMESPACE>

其中 <NAMESPACE> 是安装了 ONLYOFFICE 文档的命名空间。如果未指定，将使用默认值：default。

例如：

$ kubectl apply -f https://raw.githubusercontent.com/ONLYOFFICE/Kubernetes-Docs/master/sources/shutdown-ds.yaml -n onlyoffice

成功执行 Job 创建的 Pod shutdown-ds 后，使用以下命令删除此 Job：

$ kubectl delete job shutdown-ds -n <NAMESPACE>

如果在停止 ONLYOFFICE 文档后需要再次启动它，请重新启动 docservice 和 converter Pod。例如，使用以下命令：

$ kubectl delete pod converter-*** docservice-*** -n <NAMESPACE>

9. 更新 ONLYOFFICE 文档许可证（可选）

从 v5.1.1 版本开始，您可以通过简单地使用新许可证重新创建密钥来更新许可证，而无需删除或重启 Pod。documentserver 现在能够在替换许可证文件后动态重新读取它。例如：

要更新许可证，您需要执行以下步骤：

• 将包含新密钥的 license.lic 文件放在某个目录中
• 运行以下命令：

  $ kubectl delete secret [SECRET_LICENSE_NAME] -n <NAMESPACE>
  $ kubectl create secret generic [SECRET_LICENSE_NAME] --from-file=path/to/license.lic -n <NAMESPACE>

  其中 SECRET_LICENSE_NAME 是包含许可证的现有密钥的名称

就这样，documentserver 将自行重新读取新许可证。

$ kubectl delete pod converter-*** docservice-*** -n <NAMESPACE>

10. ONLYOFFICE 文档安装测试（可选）

您可以通过运行以下命令测试 ONLYOFFICE 文档的可用性以及对连接依赖项的访问：

$ helm test documentserver -n <NAMESPACE>

输出应包含以下行：

Phase: Succeeded

要查看作为 helm test 命令结果运行的 Pod 的日志，请运行以下命令：

$ kubectl logs -f test-ds -n <NAMESPACE>

ONLYOFFICE 文档的可用性检查被认为是优先级，因此如果检查失败并出现错误，则测试被视为失败。

之后，您可以通过运行以下命令删除 test-ds Pod：

$ kubectl delete pod test-ds -n <NAMESPACE>

11. 在私有 k8s 集群中运行任务（可选）

当运行用于安装、更新、回滚和删除的Job时，启动的容器需要访问互联网以下载最新的 sql 脚本。如果您的 k8s 集群中禁止容器访问外部网络，则可以通过设置privateCluster=true参数并手动创建一个包含必要 sql 脚本的ConfigMap来执行这些任务。

为此，请运行以下命令：

如果您的集群中已存在remove-db-scripts和init-db-scripts配置映射，请删除它们：

$ kubectl delete cm remove-db-scripts init-db-scripts

下载用于数据库清理和数据库表创建的 ONLYOFFICE 文档数据库脚本：

如果选择 PostgreSQL 作为数据库服务器：

$ wget -O removetbl.sql https://raw.githubusercontent.com/ONLYOFFICE/server/master/schema/postgresql/removetbl.sql
$ wget -O createdb.sql https://raw.githubusercontent.com/ONLYOFFICE/server/master/schema/postgresql/createdb.sql

如果选择 MySQL 作为数据库服务器：

$ wget -O removetbl.sql https://raw.githubusercontent.com/ONLYOFFICE/server/master/schema/mysql/removetbl.sql
$ wget -O createdb.sql https://raw.githubusercontent.com/ONLYOFFICE/server/master/schema/mysql/createdb.sql

从这些文件创建配置映射：

$ kubectl create configmap remove-db-scripts --from-file=./removetbl.sql
$ kubectl create configmap init-db-scripts --from-file=./createdb.sql

如果您为ConfigMap及其创建的文件指定了不同的名称，请为相应的任务设置适当的参数：

• 用于数据库清理脚本的existingConfigmap.tblRemove.name和existingConfigmap.tblRemove.keyName
• 用于数据库表创建脚本的existingConfigmap.tblCreate.name和existingConfigmap.tblCreate.keyName

接下来，在执行helm install|upgrade|rollback|delete命令时，设置参数privateCluster=true

12. 访问信息页面（可选）

默认情况下，对/info页面的访问是受限的。为了允许访问，您需要使用proxy.infoAllowedIP参数指定 IP 地址或子网（在这种情况下，它们将是代理容器客户端）。考虑到 Kubernetes 网络交互的特性，有可能获取用户的原始 IP（代理客户端），尽管这不是标准场景。通常，Pod/节点/负载均衡器地址实际上是客户端，因此应使用这些地址。在这种情况下，信息页面的访问将对所有人可用。您可以使用 Nginx 基本认证进一步限制对info页面的访问，您可以通过设置proxy.infoAllowedUser参数值并使用proxy.infoAllowedPassword参数设置密码来启用该认证，或者您可以使用proxy.infoAllowedExistingSecret参数设置包含密码的现有密钥的名称。