• 文件服务


    服务简码 HFLE

    默认端口 8110

    默认路由 /hfle/**

    组件编码 hzero-file

    简介

    1.1 概述

    对接多种云存储、本地存储的文件管理服务,并能够通过配置,对文件上传进行控制

    1.2 组件坐标

        <dependency>
            <groupId>org.hzero</groupId>
            <artifactId>hzero-file</artifactId>
            <version>${hzero.service.version}</version>
        </dependency>
    
        <dependency>
            <groupId>org.hzero</groupId>
            <artifactId>hzero-file-saas</artifactId>
            <version>${hzero.service.version}</version>
        </dependency>
    

    1.3 主要功能

    1.4 服务配置参数

    # 租户允许的最大存储容量,String类型,单位允许MB和KB,   默认值 10240MB  
    hzero.file.maxCapacitySize
    
    # 文件授权url的有效访问时间,Long类型,默认值300L
    hzero.file.defaultExpires
    
    # 华为、百度跨域配置 List<String>  若不设置,表示允许所有跨域
    hzero.file.origins
    
    # 文件预览的方式 String类型 允许的值: aspose  kkFileView  onlyOffice
    hzero.file.previewType
    
    # kkFileView的文件预览地址,previewType为kkFileView时需要指定
    hzero.file.kkFileViewUrl
    

    开发指导

    2.1 文件存储使用规范

    1.1.0.RELEASE版本出具了文件存储使用规范。

    1. HzeroService类新增了各个服务使用的桶名元数据,hzero的所有服务的所有的文件存储都使用了HzeroService定义的bucketName,对应的前端也是,禁止使用自定义的bucketName。开发人员可以通过更改前后端的配置,已达到更改存储桶的目的。注意:需要公共权限的文件 ,统一存储在public权限的桶下

    2. 所有服务的文件存储,在上传时都要指定目录字段(仅使用一级目录),目录的命名需要保证全局唯一,命名规范:模块名+序号,开发人员需要在值集“HFLE.DIRECTORY_MAPPING”中,维护文件目录和表的映射关系。例如hrpt01目录存储的是报表模板文件,表名为hrpt_report_template,需要在值集中维护 值:hrpt01/ 含义:hrpt_report_template

    2.2 onlyOffice文件在线编辑

    文件在线编辑搭建documentServer

    使用docker安装,镜像文件向平台管理员索取

    导入镜像

    # if file suffix is XXXX.tar.gz
    docker load < hoffice.tar.gz
    
    # if file suffix is XXX.tar
    docker load -i hoffice.tar
    

    使用docker-compose创建容器
    创建docker-compose.yml文件,内容如下:

    version: '3'
    services:
      hoffice:
        container_name: hoffice
        image: hoffice:1.2
        restart: always
        privileged: true
        stdin_open: true
        tty: true
        ports:
          - '8000:8000'
          - '7000:7000'
        environment:
          DOC_SERVER: http://127.0.0.1:8000
        command: /bin/sh -c /root/start.sh
        volumes:
          - "./hoffice/logs:/root/documentserver/logs"
          - "./hoffice/cache:/root/documentserver/server/App_Data"
    

    image中的版本根据实际的镜像版本修改,如hoffice:1.2、hoffice:1.1
    ports可根据实际情况映射到空闲的端口 DOC_SERVER必须替换为服务器地址,端口与容器中8000端口映射的端口一致,如果使用了代理或https,应设置为代理后的地址 如:通过nginx将hoffice的doc_server服务代理到了 https://www.example.com/hoffice/docserver
    则DOC_SERVER应设置为 https://www.example.com/hoffice/docserver
    volumes映射的分别为日志文件和缓存文件,如果服务器磁盘不足,可进入容器,执行sh /root/documentserver/shell/clear-cache.sh清除缓存 在docker-compose.yml文件所在目录执行以下命令,创建容器

    docker-compose up -d
    

    查看token

    token用于服务对接时接口的header中携带
    # 进入容器
    docker exec -it hoffice /bin/bash 
    # 查看token
    sh /root/documentserver/shell/token.sh
    

    如果token出现多个,请使用第一个即可

    检测服务是否正常启动,可访问如下地址:

    http://${host}:7000/ // => true
    
    http://${host}:8000/healthcheck // => true
    

    查看日志 容器中的日志文件映射到了当前目录的hoffice/logs下,查看日志的方式如下:

    # doc-server日志
    tail -f hoffice/logs/doc-server.log
    # server-manager日志
    tail -f hoffice/logs/server-manager/server-manager-web.log
    # file-converter日志
    tail -f hoffice/logs/file-converter.log
    

    版本升级

    导入新版本的镜像
    修改docker-compose.yml中image的版本号
    执行docker-compose up -d重新构建容器
    更新应用程序中的token配置

    # 进入容器
    docker exec -it hoffice /bin/bash 
    # 查看token
    sh /root/documentserver/shell/token.sh
    

    调整服务的配置文件

    hzero:
      file:
        only-office:
          token: xxxx   # 上面在容器中查到的token
          doc-server-url: http://ip:7000/document   # IP为documentServer的服务ip,端口根据实际映射端口调整
          call-back-prefix: http://xxxxx/hfle/v1/only-office/save # 文件服务提供的回调地址
    

    2.3文件预览配置

    文件服务支持三种文件预览的方式 Aspose.Words for JavakkFileViewonlyOffice

    修改文件服务配置文件

    hzero:
      file:
        preview-type: onlyOffice
        converter-url: http://xxxxx:8000/converter   # 搭建的onlyOffice,8000端口的那个服务
    

    说明: onlyOffice预览方式,支持的文件类型:
    jpeg jpg png doc docm docx dot dotm dotx epub fodt html mht odt ott pdf rtf txt xps``csv fods ods ots xls xlsm xlsx xlt xltm xltx fodp odp otp pot potm potx pps ppsm ppsx ppt pptm pptx
    对于复杂的word格式支持不是太好,但大多数格式还是支持的。

    修改文件服务配置文件

    hzero:
      file:
        preview-type: aspose
    

    说明: 该文件预览方式支持的文件类型较少,目前仅支持:jpeg jpg png doc docx pdf, 但该预览方式对word文件中的一些特殊格式支持很好,对格式要求比较高的推荐使用

    服务创建完成后,修改文件服务配置文件

    hzero:
      file:
        preview-type: kkFileView
        kk-file-view-url: http://xxxxxx:8012/onlinePreview   # kkFileView的文件预览地址
    

    说明: kkFileView预览方式支持的文件类型比较多,这里就不一一举例了,具体可以查阅官方文档。字体问题在官方文档也有说明。 kkFileView的文件预览是基于openOffice的,对于复杂的word格式支持不是太好,但大多数格式还是支持的。

    展望