首页 > 默认 > HZERO PaaS平台-Docker版demo笔记（三）非容器环境运行jar包适配

HZERO PaaS平台-Docker版demo笔记（三）非容器环境运行jar包适配

2025年12月9日

我们为了制作Docker版本的Demo, 让微服务在容器中顺利运行，更改了所有微服务的yml配置，重新构建了所有的jar,详情可参考：

Jacksen的技术博客 » HZERO PaaS平台-Docker版demo笔记（一）Docker版制作  

现在回过头来想想，其实当时也可以不改的，不用去把每个微服务的yml文件中的中间件服务域名改成容器服务名的，只需要这些中间件服务的容器都给他们起个别名，跟原来yml中的域名保持一致就可以相互在容器间访问到的。但是当时不懂，已经那么做了，所以现在就继续在这个基础上继续吧。

当时我们备份了所有微服务原来的yml配置和jar文件，想着后面在linux 中直接运行这些微服务的时候还要把原来备份的yml配置恢复过来，然后重建微服务的jar包，但这么做会比较麻烦，因为后面每个微服务版本升级后还可能要继续重新构建适用于Docker的Jar包，而我们的微服务升级频率又很高，所以要考虑yml配置和jar包最好有方法同时适用于容器内运行和直接在linux运行。

问题分析：

我们对微服务门的application.yml和bootstrap.yml配置文件的更改，主要就是四种：中间件服务的域名、部分微服务的域名（注册中心、网关、配置中心等）、网络preferred ip、系统界面上的域名配置。

分别来看；

一、中间件服务域名

mysql,redis,mongo,mino，kkfileview,onlyoffice,elasticsearch 中间件服务的域名，改成了容器的服务名；

这一点：如果直接在linux中运行，那么只需要在hosts中把容器服务名的DNS解析指定到本机IP就可以。当然也可以不改，在run.sh和run_nobuild.sh中的启动命令中在JAVA_OPTS字符串中把原来的域名比如mysql的域名：db.hzero.com.cn 作为环境变量注入进去，类似PREFERRED_IP那样处理。但是也麻烦，每个服务都有两个脚本，每个脚本都要去改。所以还是在linux的hosts文件更改方便：

172.18.14.48 mysql-hzero  

172.18.14.48 redis-hzero   

172.18.14.48 mongo-hzero

172.18.14.48 kkfileview-hzero

172.18.14.48 onlyoffice-hzero 

172.18.14.48 elasticsearch-hzero  

二、注册中心、网关、配置中心等微服务的域名

这些域名在微服务的application.yml和bootstrap.yml中改成了容器的服务名；

这一点：如果直接在linux中运行，那么只需要在hosts中把容器名的DNS解析指定到本机IP就可以。

172.18.14.48 hzero-gateway   

172.18.14.48 hzero-register    

172.18.14.48 hzero-admin     

172.18.14.48 hzero-hkms      

172.18.14.48 hzero-hype      

172.18.14.48 hzero-aip-app   

三、网络preferred ip

网络从指定preferred ip改成去掉preferred ip，网络接口忽略改成了：

      ignored-interfaces:

        – lo

        – docker0

        – veth.*

      这一点，我们无需恢复到指定preferred ip，这样的写法可同时兼容linux本机运行和Docker容器中运行。

四、需要进入系统之后更改的配置

1、minio配置：需要进入系统->文件管理->minio 配置服务器地址，原来的oss.hzero.com.cn，没有更改。无需更改。

2、aigc开放api地址（AI网关）：需要进入系统->AIGC中台->全局选项配置->开发api地址，原来是aigc.hzero.com.cn， 没有更改。  无需更改。

3、neo4j 图数据库地址：需要进入系统->AIGC中台->知识图谱->图数据库管理，原来是个IP地址，需要改成neo4j-hzero，在hosts中要添加172.18.14.48 neo4j-hzero  

4、向量数据库配置地址：需要进入系统->AIGC中台->向量库管理->向量库配置/平台内置向量库类型：ElasticSearch，原来是个IP地址，需要改成elasticsearch-hzero，在hosts中要添加172.18.14.48 elasticsearch-hzero  

备注：由于我们在全局设置中默认向量库用的是elasticsearch，没用milvus，所以milvus不用配置。

解决执行

一、更改linux的hosts文件

$ cp /etc/hosts /etc/hosts.bak20251126

$ vi /etc/hosts

删除定制原来内容，添加如下内容：

172.18.14.48 mysql-hzero

172.18.14.48 redis-hzero

172.18.14.48 mongo-hzero

172.18.14.48 elasticsearch-hzero

172.18.14.48 neo4j-hzero

172.18.14.48 hzero-gateway

172.18.14.48 hzero-register

172.18.14.48 hzero-admin

172.18.14.48 hzero-hkms

172.18.14.48 hzero-hype

172.18.14.48 hzero-aip-app

172.18.14.48 oss.hzero.com.cn

172.18.14.48 kkv.hzero.com.cn

172.18.14.48 gateway.hzero.com.cn

二、更改windows 客户端的hosts文件设置：

172.18.14.48  dev.hzero.com.cn          #hzero-demo环境 Nginx服务器地址

172.18.14.48  gateway.hzero.com.cn     # 网关的地址

172.18.14.48  aigc.hzero.com.cn         # AIGC ai-app服务的反向代理

172.18.14.48  kkv.hzero.com.cn          # 文件预览服务域名

172.18.14.48  oss.hzero.com.cn          # minio文件服务域名（客户端直接预览PDF需要）

三、启动AI平台服务，更改向量数据库和图数据库配置

$ cd /d02/

$ bash service-ai-all-start.sh

#启动完成，进入系统

3、图数据库配置更改成功：

4、向量数据库配置更改成功：

四、测试：

1、从原来的导出文件中恢复导入模型对接账号，并重新填入api_key后这些账号测试工作正常。
2、AIGC平台/企业应用库/我的运营知识库：知识库问答工作正常。
3、AIGC平台/文档库管理：上传文档向量化操作正常，PDF，Word文档预览正常，查看切片操作正常；

4、Office文件在线编辑问题：

按照开放平台 文件服务/在线编辑 结合自己的域名和端口进行hzero-file服务的application.yml配置：

hzero:

  file:

    only-office:

      edit-type: onlyOffice

      file-key-expire: 30

      doc-server-url: http://onlyoffice-hzero:8800

      call-back-url: http://dev.hzero.com.cn/hfle/v1/only-office/save/file

      converter-url: http://onlyoffice-hzero:8800/ConvertService.ashx

镜像使用平台打包的镜像：registry.hand-china.com/hzero-public/hzero-office:1.0

考虑到容器需要访问Minio服务和回调写文件的APi，所以在容器的docker -compose.yml中添加：

    extra_hosts:

      – “oss.hzero.com.cn:172.18.14.48”

      – “dev.hzero.com.cn:172.18.14.48”

平台 /文件管理/文件汇总查询  pdf,docx,xlsx 预览正常，docx编辑错误，错误信息：

分析：

1、前端界面错误显示是无法读取未定义的属性’document’

2、浏览器检查/网络中的API调用没有错误，URL返回正常；

3、hzero-file服务后端日志没有显示任何错误。

说明问题出在前端。假设前端代码跟onlyoffice容器服务返回的内容不兼容，这么假设是因为平台提供的onlyoffice镜像是5.6版本的，是2020年的版本，假设文档没有更新，但由于部分客户已经使用了更新版本的onlyoffice，前端为了适配新版onlyoffice做了改动，因而与旧版不兼容。

尝试：更换onlyoffice到8.02版镜像，这是2024年的镜像。

swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/onlyoffice/documentserver:8.2.0

#考虑到新的镜像中的安全策略跟平台提供的镜像不一样（在local.json中默认是需要验证的，平台镜像已经把验证去掉了），所以要先启动镜像，然后把local.json拷贝出来，

$ cd /d02/hzero/project/ps-file/onlyoffice

$ docker cp onlyoffice-hzero:/etc/onlyoffice/documentserver/local.json ./volumes/onlyoffice/DocumentServer/

然后再改local.json, 去掉验证，

      “token”: {

        “enable”: {

          “request”: {

            “inbox”: false,

            “outbox”: false

          },

          “browser”: false

然后再挂载到容器。再重启容器，使得新的镜像也不需要验证。

    volumes:

      – ${DOCKER_VOLUME_DIRECTORY:-./volumes}/onlyoffice/DocumentServer/local.json:/etc/onlyoffice/documentserver/local.json

chown -R 109:112 ./volumes

# 再次测试：问题依旧，而且问题表现也是一样的，假设失败。

看容器日志：

docker exec -it onlyoffice-hzero bash

cd /var/log/onlyoffice/documentserver/docservice

tail -f out.log看不到任何错误

docker exec -it onlyoffice-hzero tail -f /var/log/onlyoffice/documentserver/docservice/out.log

看前端  url API返回的响应内容：这个内容展开后发现跟http://onlyoffic-hzero:8800的主页是一样的。也就是说这返回的内容并不是具体我们要编辑的那篇文档的内容。

我们先测试onlyoffice服务器本身的可用性：

提示词给AI

我的onlyoffice服务器的 doc-server-url是: http://onlyoffice-hzero:8800 call-back-url是：http://hzero-gateway:8080/hfle/v1/only-office/save/file 要编辑的文件地址是： http://oss.hzero.com.cn:9000/hz-haip/haip01/0/MINIO/588ed65df356418282963399668bbccc@上海益吉-低代码平台应用成功案例.docx 请帮我构建一个在bash 中测试的命令，获得onlyoffice返回的编辑该文档的URL

元宝建议直接构建本地Html: 用5.6版本的onlyoffice 是可以正常使用的

<!DOCTYPE html>

<html lang=”zh-CN”>

<head>

    <meta charset=”UTF-8″>

    <title>OnlyOffice 编辑器测试</title>

    <!– 新增：让页面根元素撑满视口，消除默认边距 –>

    <style>

        html, body {

            height: 100%;  /* 让html、body占满浏览器窗口高度 */

            margin: 0;     /* 消除页面默认边距 */

            padding: 0;    /* 消除页面默认内边距 */

        }

    </style>

    <!– 引入 OnlyOffice API –>

    <script type=”text/javascript” src=”http://onlyoffice-hzero:8800/web-apps/apps/api/documents/api.js”></script>

</head>

<body>

    <div id=”editor” style=”height: 100%; width: 100%;”></div>

    <script type=”text/javascript”>

        // 编辑器配置

        var config = {

            document: {

                fileType: “docx”,

                key: “test-doc-key-001”, // 一个唯一的文档标识，可用于跟踪保存版本

                title: “上海益吉-低代码平台应用成功案例.docx”,

                url: “http://oss.hzero.com.cn:9000/hz-haip/haip01/0/MINIO/588ed65df356418282963399668bbccc%40%E4%B8%8A%E6%B5%B7%E7%9B%8A%E5%90%89-%E4%BD%8E%E4%BB%A3%E7%A0%81%E5%B9%B3%E5%8F%B0%E5%BA%94%E7%94%A8%E6%88%90%E5%8A%9F%E6%A1%88%E4%BE%8B.docx”

            },

            documentType: “text”,

            editorConfig: {

                callbackUrl: “http://hzero-gateway:8080/hfle/v1/only-office/save/file”, // 文档保存后的回调地址

                lang: “zh-CN”,

                mode: “edit”, // 设置为编辑模式

            },

            width: “100%”,

            height: “100%”

        };

        // 初始化编辑器

        new DocsAPI.DocEditor(“editor”, config);

    </script>

</body>

</html>

所以，结论是： hzero-file服务的url 这个api返回的内容错误，他返回了onlyoffice的主页，实际要返回我们上面这样的内容才对。

另外hero-file的POM中两个依赖也没添加：这要加上。

       <dependency>

           <groupId>org.hzero.starter</groupId>

           <artifactId>hzero-starter-fileview-onlyoffice</artifactId>

      </dependency>

     <dependency>

        <groupId>org.hzero.starter</groupId>

        <artifactId>hzero-starter-fileview-hoffice</artifactId>

     </dependency>

POM中加了这两个依赖后重启hzero-file服务，再测效果一样不行，。

比较公司开发环境发现用的onlyoffice是9.1.0 的版本，是2025年10月发的最新版

我换用latest版本，就是9.1.0的，去掉认证JWT要求：

$ docker exec -it onlyoffice-hzero bash

$ nano /etc/onlyoffice/documentserver/local.json

# 把认证去掉，重启：

$docker exec -it onlyoffice-hzero supervisorctl restart all

结果，本地那个测试html文件也提示无法下载文件，无法保存了，打不开：

看onlyoffice 日志：

$ docker exec -it onlyoffice-hzero tail -f /var/log/onlyoffice/documentserver/docservice/out.log

错误日志

[2025-12-06T11:21:56.832] [ERROR] [localhost] [test-doc-key-001] [uid-17649991598246] nodeJS – postData error: url = http://hzero-gateway:8080/hfle/v1/only-office/save/file;data = {“key”:”test-doc-key-001″,”status”:4,”actions”:[{“type”:0,”userid”:”uid-1764999159824″}]} Error: DNS lookup 172.18.14.48(family:4, host:hzero-gateway) is not allowed. Because, It is private IP address.

豆包说是触发了onlyoffice的内网渗透限制

更改local.json , 把IP限制去掉：

“services”: { “CoAuthoring”: { “sql”: { … }, “token”: { … }, “secret”: { … }, 在这个后面添加：

“requests”: { “restrictions”: { “ip”: { “allow”: [“*”], // 允许所有IP（测试用，生产不推荐） “deny”: [] } } }

再重启
$ supervisorctl restart all

问题依旧，chatgpt, 元宝，豆包均没有给出真正的解决方案， 豆包是瞎说，元宝和chatgpt就不会，他们基本没有onlyoffice的知识。

但在onlyoffice的官网论坛搜索问题，有个答案，并且答案是有用的：

参数 allowPrivateIPAddress 定义是否允许连接私有IP地址。这包括私有IP地址和预留IP地址

文档服务器默认不允许使用内部IP地址。为避免这种情况，请在docker容器中打开/etc/onlyoffice/documentserver/default.json，找到allowPrivateIPAddress参数并将其值改为true。

之后执行supervisorctl restart all并检查问题是否仍然存在。

把这个修改后的文件拷贝出来：

$ docker cp onlyoffice-hzero:/etc/onlyoffice/documentserver/default.json /d02/hzero/project/ps-file/onlyoffice/volumes/onlyoffice/DocumentServer/

顺便把local.json也拷贝出来

$ docker cp onlyoffice-hzero:/etc/onlyoffice/documentserver/local.json /d02/hzero/project/ps-file/onlyoffice/volumes/onlyoffice/DocumentServer/

这个方案确实可以，改了之后本地html中调用onlyoffice可以正常显示：

注意：allowPrivateIPAddress 这个参数本身不能像 JWT_ENABLED 那样通过简单的环境变量来设置，可以通过文件挂载的方式实现持久生效。

HZERO里面文件编辑会报错：

 HZERO-file 服务后台也会报错（认证我去掉了，不是认证问题） ,把hzero-file服务的错误日志给元宝查一下，元宝指出：

根据您提供的完整错误日志，核心问题已经明确：​OnlyOffice文档服务返回了HTTP 308状态码（永久重定向）​，导致HZERO服务无法完成HTML预览生成。以下是关键证据：

​明确的状态码记录​

ERROR o.hzero.starter.fileview.util.HttpUtils: current onlyOffice resultCode was:308

​重定向引发的处理中断​

日志显示在收到308响应后，系统立即抛出CommonException: hfle.error.onlyOffice.generateHtml

关于308重定向的问题，元宝根据他从CSDN别人分享的经验文章，给出了解决方案：

docker run -i -t -d -p 8800:80 \

  -e JWT_ENABLED=false \

  -e USE_UNAUTHORIZED_STORAGE=true \

  -e ONLYOFFICE_HTTPS_HSTS_ENABLED=false \

  onlyoffice/documentserver

编辑/etc/nginx/includes/ds-docservice.conf

全局替换$the_host成$http_host

nginx -s reload

这个方案未能解决308问题，测试发现还是报错，还是308。

我们把hzero-file的日志级别改成debug,看更详细的日志：

2025-12-07T12:04:39.075+08:00 DEBUG 119681 — [hzero-file] [  XNIO-1 task-2] o.h.s.f.service.impl.HofficeServiceImpl  : generateRequestParam param : RequestParam{accessToken=’epFl7vl24D’, docServerUrl=’http://onlyoffice-hzero:8800′, bodyJson='{“document”:{“title”:”公牛集团-aPaaS飞搭低代码项目案例.docx”,”url”:”http://oss.hzero.com.cn:9000/hz-haip/haip01/0/MINIO/343b6feac396458e8bb0817e64442a6b%40%E5%85%AC%E7%89%9B%E9%9B%86%E5%9B%A2-aPaaS%E9%A3%9E%E6%90%AD%E4%BD%8E%E4%BB%A3%E7%A0%81%E9%A1%B9%E7%9B%AE%E6%A1%88%E4%BE%8B.docx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=hzero.admin%2F20251207%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20251207T040439Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=3b2852b7ef47d629f4531bc610952f23f60affa717b561198fb14c34dbd01a3d”,”fileId”:”http://oss.hzero.com.cn:9000/hz-haip/haip01/0/MINIO/343b6feac396458e8bb0817e64442a6b@公牛集团-aPaaS飞搭低代码项目案例.docx”},”permissions”:{“edit”:true,”review”:true,”dealWithReview”:true,”dealWithReviewOnly”:false,”changeReview”:true,”download”:true,”print”:true,”comment”:false},”editor”:{“callbackUrl”:”http://hzero-gateway:8080/hfle/v1/only-office/save/file”,”userId”:”2″,”userName”:”超级管理员”},”customization”:{“logoImage”:””,”logoLink”:””,”preloaderLogoImage”:””},”extra”:”{\”type\”:\”U\”,\”tenantId\”:0,\”bucketName\”:\”haip\”,\”storageCode\”:\”MINIO\”}”}’}

这里面docserverurl 没看到拼接完整的url；http://onlyoffice-hzero:8800/web-apps/apps/api/documents/api.js

在hzero-file的yml里面改下配置再试试看，再次测试报405（Method Not Allowed）错误了。看起来也不是这个问题。调用程序应该是自己做了拼接的。还是改回来。http://onlyoffice-hzero:8800

接下来：

Docker-compose.yml中增加环境变量：

  – JWT_ENABLED=false 

  – USE_UNAUTHORIZED_STORAGE=true 

  – ONLYOFFICE_HTTPS_HSTS_ENABLED=false 

更改后的defauly.json 实现挂载持久化：

      – ${DOCKER_VOLUME_DIRECTORY:-./volumes}/onlyoffice/DocumentServer/default.json:/etc/onlyoffice/documentserver/default.json

重启onlyoffce容器，再次测试，还是308问题；

我在onlyoffice中怎样才能看到请求方发起内容的详细日志？我必须看到hzero-file 发给onlyoffce的详细内容才能明白为啥还有308,

$ ps aux | grep nginx 可以看到：

tail -F /var/log/onlyoffice/documentserver/adminpanel/out.log /var/log/onlyoffice/documentserver/adminpanel/err.log /var/log/onlyoffice/documentserver/docservice/out.log /var/log/onlyoffice/documentserver/docservice/err.log /var/log/onlyoffice/documentserver/converter/out.log /var/log/onlyoffice/documentserver/converter/err.log /var/log/onlyoffice/documentserver/nginx.error.log /var/log/onlyoffice/documentserver/metrics/out.log /var/log/onlyoffice/documentserver/metrics/err.log /var/log/onlyoffice/documentserver-example/out.log /var/log/onlyoffice/documentserver-example/err.log

这条命令应该是看所有log的， 执行这条命令，可以看到所有日志，其中有条日志是我想要看到的：

==> /var/log/onlyoffice/documentserver/nginx.error.log <==

2025/12/07 04:22:22 [error] 29581#29581: *211 open() “/var/www/onlyoffice/documentserver/web-apps/apps/api/documents/api.js/web-apps/apps/api/documents/api.js” failed (20: Not a directory), client: 172.18.0.1, server: , request: “GET /9.1.0-bc930140d198d21185b7c6cf5139630d/web-apps/apps/api/documents/api.js/web-apps/apps/api/documents/api.js HTTP/1.1”, host: “onlyoffice-hzero:8800”

这一条：就是我刚才更改了hzero-file的application.yml中的 doc-server-url 导致的。这条日志印证了hzero-file确实会加上/web-apps/apps/api/documents/api.js ，所以，doc-server-url确实只需要配置为http://onlyoffice-hzero:8800就可以了。

那我现在要接着找我的配置改回http://onlyoffice-hzero:8800后反馈308错误的日志：

可惜我多次刷新，在hzero-file中的log都能看到308，但是在onlyoffice的错误日志跟踪中看不到相关内容，这种错误不会出现在onlyoffice的错误日志中吗？

/var/log/onlyoffice/documentserver/nginx.error.log

/var/log/onlyoffice/documentserver/docservice/out.log /var/log/onlyoffice/documentserver/docservice/err.log

1. ​确认请求是否真正到达OnlyOffice​

查找有308重定向配置的地方：

$ grep “return 30” /etc/nginx/includes/*

返回： /etc/nginx/includes/ds-docservice.conf:

 return 308 $the_scheme://$the_host$the_prefix/9.1.0-$cache_tag$cache;

打开这个配置文件，查看具体内容：

#welcome page
location = / { return 308 $the_scheme://$the_host$the_prefix/welcome/; }

就是说直接访问跟路径的时候，就会重定向到welcome页面，但是从之前的日志可以看出我们设置的http://onlyoffice-hzero:8800 会被容器端口转发到80端口，而在onlyoffice服务器上

root@47397c159d32:/etc/nginx# more nginx.conf

user www-data;

worker_processes 1;

pid /run/nginx.pid;

error_log /var/log/nginx/error.log;

include /etc/nginx/modules-enabled/*.conf;

也就是说主要配置在：/etc/nginx/conf.d/ ds.conf 中：

/etc/nginx/conf.d/ ds.conf

include /etc/nginx/includes/http-common.conf;

server {

  listen 0.0.0.0:80;

  listen [::]:80 default_server;

  server_tokens off;

  set $secure_link_secret 8qldl8B12tCtjYXWA2gS;

  include /etc/nginx/includes/ds-*.conf;

}

也就是说主要配置在：/etc/nginx/includes/ds-docservice.conf 中：

而在ds-docservice.conf中，第一句就是 把根目录重定向到 welcom页面

location = / { return 308 $the_scheme://$the_host$the_prefix/welcome/; }

但我们从之前的日志可以看出，hzero-file服务确实是把 根目录拼接上了/web-apps/apps/api/documents/api.js 再请求onlyoffice的，所以不存在直接请求根目录的情况。

还有第二个308的配置：

#script caching protection
location ~ ^(?<cache>\/web-apps\/apps\/(?!api\/documents\/api\.js$).*)$ {
return 308 $the_scheme://$the_host$the_prefix/9.1.0-$cache_tag$cache;
}

这是缓存策略，也是版本兼容策略，当请求方发出一个固定的路径请求后，onlyoffice可以根据实际版本重定向到不同版本的实际脚本路径。

308 跳转到带版本号的 URL 后，OnlyOffice 配置了专门的 location 处理版本号路径：

location ~ ^/([\d]+\.[\d]+\.[\d]+[\.|-][\w]+)/(?<path>.*)$ {

  proxy_pass http://docservice/$path$is_args$args;

  # 其他 proxy 配置（超时、版本等）

}

作用：剥离版本号前缀（如 9.1.0-abc123/），将剩余路径（web-apps/apps/main.js）代理到 OnlyOffice 后端服务（docservice），确保资源能正确访问。

4. OnlyOffice 业务目的（核心价值）

（1）静态资源长期缓存

/web-apps/apps/ 下的 JS/CSS 等资源变动极少，通过 308 永久重定向到带版本号 + 缓存标签的 URL，让浏览器 / CDN 长期缓存（后续配置中设置 max-age=31536000），大幅减少重复下载。

（2）版本隔离

OnlyOffice 升级版本（如 9.1.0 → 9.2.0）时，修改 308 中的版本号（9.2.0），旧缓存的 URL（9.1.0-xxx）自动失效，浏览器会请求新的版本 URL，避免缓存污染导致的功能异常。

（3）核心文件缓存隔离

通过负向断言排除 api.js，因为该文件包含文档服务器的接口地址、版本逻辑等动态内容，若缓存会导致客户端调用旧接口，因此专门为 api.js 配置了「禁用缓存」规则：

nginx

location ~ ^(\/[\d]+\.[\d]+\.[\d]+[\.|-][\w]+)?\/(web-apps\/apps\/api\/documents\/api\.js)$ {

  expires off;  # 禁用过期缓存

  add_header Cache-Control “no-store, no-cache, must-revalidate”;  # 强制不缓存

  # 其他配置（gzip、alias 等）

}

308 配置的关键注意事项（OnlyOffice 专属）

1. 变量必须提前定义

$the_scheme/$the_host/$the_prefix/$cache_tag 是 OnlyOffice 在主配置中定义的自定义变量，若缺失会导致 308 跳转 URL 异常（如 :///9.1.0-/web-apps/apps/main.js），Nginx 启动报错。

2. 308 缓存与版本升级

308 是永久重定向，浏览器缓存后不会自动失效，因此 OnlyOffice 升级时必须修改版本号（如 9.1.0→9.2.0）或 $cache_tag，让新 URL 触发新请求；

测试 / 开发阶段可临时改用 307（临时重定向），避免缓存干扰。

先改成307试试（conf文件中，只需要把308改成307，别的不用改）

sed -i ‘s/return 308/return 307/g’ /etc/nginx/includes/ds-docservice.conf

nginx -s reload

再次访问hzero-file文件服务的word文档在线编辑，这次没有返回308，返回了405

405是方法不允许，元宝说可能是服务端点配置不正确，建议改成http://onlyoffice-hzero:8800/ConvertService.ashx

再次测试，hzero-file文件服务没有返回错误，但是前端界面显示 error , 并且onlyoffice日志出现错误：
[2025-12-07T09:17:43.588] [WARN] [localhost] [null] [userId] nodeJS – convertRequest unexpected outputtype =

说明不是这么回事。

元宝搜索到 CSDN有篇文章说：有碰到308的问题是因为

onlyoffice容器里的nginx无法正确识别$the_host.

编辑/etc/nginx/includes/ds-docservice.conf

全局替换$the_host成$http_host

重启nginx

nginx -s reload

但实际测试下来也没用，这是个过时的说法。

继续分析，

根路径测试：

curl -I -X GET http://onlyoffice-hzero:8800

HTTP/1.1 307 Temporary Redirect
Server: nginx
Date: Sun, 07 Dec 2025 09:38:34 GMT
Content-Type: text/html
Content-Length: 164
Connection: keep-alive
Location: http://onlyoffice-hzero:8800/welcome/

curl -I -X POST http://onlyoffice-hzero:8800

HTTP/1.1 307 Temporary Redirect
Server: nginx
Date: Sun, 07 Dec 2025 09:40:45 GMT
Content-Type: text/html
Content-Length: 164
Connection: keep-alive
Location: http://onlyoffice-hzero:8800/welcome/

 测试静态资源 307

curl -I -X GET http://onlyoffice-hzero:8800/web-apps/apps/main.js

HTTP/1.1 307 Temporary Redirect
Server: nginx
Date: Sun, 07 Dec 2025 09:43:09 GMT
Content-Type: text/html
Content-Length: 164
Connection: keep-alive
Location: http://onlyoffice-hzero:8800/9.1.0-8b6a79642574012ffddb2cd8aeecfa96/web-apps/apps/main.js

所以，测试下来服务端没啥问题，就是调用端的问题，hzero-file服务的 application.yml中更改编辑器类型配置，再重启：

      # 编辑器类型 onlyOffice/hoffice

      edit-type: ${ONLY_OFFICE_EDIT_TYPE:onlyOffice}

这次有显示了，这是说文档安全令牌的格式不正确：

Hzero-file 服务的日志中没有错误，onlyoffice 容器服务有错误信息：

[2025-12-07T10:11:01.796] [WARN] [localhost] [17651021616605e223b9] [userId] nodeJS – checkJwt error: name = JsonWebTokenError message = jwt malformed token = epFl7vl24D

由于我已经在容器的docker-compose.yml中设置了- JWT_ENABLED=false，所以理论上应该不要求token了，但测试发现，如果在调用的时候传了token，onlyoffice还是会检查token的有效性，刚开始报格式错误，改成标准的jwt格式后又报错验证错误，docker-compose.yml和hzero-file的application.yml两边保持一致都不行，不管是两边都填密钥还是两边都填同一密钥计算出来的长长的TOKEN都通不过验证。

所以后来就想，已经设置jwt验证为false，为啥还要提供token啊，就把hzero-file的application.yml中的 onlyoffice配置部分的token注释掉，这样前端检查的网络中看url 这个api的响应中就没有token了，onlyoffice就不不报错了。

总结：

  1. onlyoffice 最新版的容器 9.1.0版本可用。trail环境用的8.x的版本也可用，看起来不同版本的onlyoffice兼容性都不错。
  2. 非全容器环境，Hzero相关服务都直接运行在linux,非docker网络内的话， onlyoffice 容器的compose-yml中要把minio文件服务的域名和网关服务的域名解析加上。（如果是全容器环境则不需要）

    extra_hosts:

      – “oss.hzero.com.cn:172.18.14.48”

      – “hzero-gateway:172.18.14.48”

  • 为方便demo环境配置，去掉jwt验证，这需要在onlyoffice 容器的compose-yml中加上配置：

    environment:

      – JWT_ENABLED=false

  • demo非全容器环境，hzero-gateway网关地址在onlyoffice看来属于本地host机地址，其默认安全策略禁止访问，导致回调地址不可用，文件不能保存，所以要去掉这个策略，方法是修改default.json,把”allowPrivateIPAddress”: true,为持久有效，拷贝到容器外，修改后进行挂载

    volumes:

      – ${DOCKER_VOLUME_DIRECTORY:-./volumes}/onlyoffice/DocumentServer/default.json:/etc/onlyoffice/documentserver/default.json

备注：在全容器环境，这个配置也需要更改。

  • onlyoffice容器中的local.json 每次启动会被服务器自动修改，因此不要去修改这个文件，也不要去做持久性挂载，网上和AI里面说的很多修改这个文件的方法并不可取。要禁用JWT验证要通过docker-compose.yml配置去设置，而不是修改这个文件。
  • Hzero-file 的application.yml文件中的配置，编辑器类型edit-type一定要配置onlyOffice, 选配平台选配下来的配置文件默认是hoffice, 这个配置不对就导致一系列308,405…等等错误，怎么改都搞不定。后来跟产研聊，hoffice是啥选项？ 他们说这是6年前onlyoffice还不成熟，有很多bug, 他们基于开源的onlyoffice,修改了很多bug, 形成了hoffice版本， 但后来onlyoffice本身不断迭代进步，比他们自己的hoffice版本好，他们就放弃了hoffice的继续迭代，直接用onlyoffice了，所以hoffice这个配置选项，早就没用了，只是为了兼容5年前还在用hoffice的用户。

token注释掉，留着就会导致onlyoffice去验证，跟我设置去掉验证冲突。当然我看到公司开发环境和试用环境是留着的，他们可能启用了jwt验证。其他跟开放平台文档的配置保持一致是可以的。

    only-office:

      # 编辑器类型 onlyOffice/hoffice

      edit-type: ${ONLY_OFFICE_EDIT_TYPE:onlyOffice}

      # onlyOffice文件key过期时间

      file-key-expire: ${ONLY_OFFICE_FILE_KEY_EXPIRE:30}

      #token: ${DOC_SERVER_TOKEN:LSe9EvjMC5z8QvF0S3p1P7rAI236tWpd}

      doc-server-url: ${DOC_SERVER_URL:http://onlyoffice-hzero:8800}

      call-back-url: ${DOC_SERVER_CALL_BACK:http://hzero-gateway:8080/hfle/v1/only-office/save/file}

      converter-url: ${DOC_SERVER_CONVERTER_URL:http://onlyoffice-hzero:8800/ConvertService.ashx}

备注：后来在搞容器环境测试的时候，把onlyoffice-hzero改成onlyoffice.hzero.com.cn了：

doc-server-url: ${DOC_SERVER_URL:http://onlyoffice.hzero.com.cn}

converter-url: ${DOC_SERVER_CONVERTER_URL:http://onlyoffice.hzero.com.cn/ConvertService.ashx}

所以要做些改动：
a) 在 /etc/hosts中加上 172.18.14.48 onlyoffice.hzero.com.cn

b) nginx做反向代理：

server {

    listen 80;

    server_name onlyoffice.hzero.com.cn;  # 匹配统一域名

    # 反向代理到Docker网络内的onlyoffice容器8800端口（直接用别名）

    location / {

        proxy_pass http://onlyoffice.hzero.com.cn:8800;  # 直接指向onlyoffice容器服务端口

        proxy_set_header Host $host;

        proxy_set_header X-Real-IP $remote_addr;

        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_connect_timeout 300s;

        proxy_send_timeout 300s;

        proxy_read_timeout 300s;

    }

}

  • 记得在hzero-file的POM文件中加上onlyoffice的依赖，这在开放平台文档中有提到。

        <dependency>

            <groupId>org.hzero.starter</groupId>

            <artifactId>hzero-starter-fileview-onlyoffice</artifactId>

        </dependency>

总之，搞明白了就很好用，也很好配置。

 

 

关于作者:

昵称:Jack.shang
档案信息:jack.shang 程序员->项目经理->技术总监->项目总监->部门总监->事业部总经理->子公司总经理->集团产品运营支持
联系方式:你可以通过syfvb@hotmail.com联系作者
点击查看发表过的所有文章...
本文永久链接： http://blog.retailsolution.cn/archives/4911

 

 

对本文的评价:

 

 

分类: 默认 标签:
本文的评论功能被关闭了.