• 开发指导


    1.1 文件存储使用规范

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

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

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

    1.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 # 文件服务提供的回调地址
    

    1.3文件预览配置

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

    修改文件服务配置文件

    hzero:
      file:
        preview-type: onlyOffice
        only-office:
            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 fodp odp otp pot potm potx pps ppsm ppsx 对于复杂的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格式支持不是太好,但大多数格式还是支持的。

    1.4 pdf水印

    文件支持为pdf文件添加水印,目前仅支持文件水印。

    接口地址: /v1/{organizationId}/watermark/by-url

    参数 参数名称 必输 默认值
    bucketName 存储桶名
    url pdf文件url
    storageCode 文件存储配置编码
    text 水印文本内容
    fillOpacity 水印透明度 0.4F
    red 色彩-红 0
    green 色彩-绿 0
    blue 色彩-蓝 255
    size 字体大小 60F
    x 水印横坐标 300F
    y 水印纵坐标 500F
    align 对齐方式 1(0左对齐 1居中 2右对齐)
    rotation 旋转角度 45F

    接口地址: /v1/{organizationId}/watermark/by-key

    参数 参数名称 必输 默认值
    fileKey pdf文件key
    text 水印文本内容
    fillOpacity 水印透明度 0.4F
    red 色彩-红 0
    green 色彩-绿 0
    blue 色彩-蓝 255
    size 字体大小 60F
    x 水印横坐标 300F
    y 水印纵坐标 500F
    align 对齐方式 1(0左对齐 1居中 2右对齐)
    rotation 旋转角度 45F

    1.5 文件分片与断点续传

    使用该功能,必须先配置:hzero.file.gatewayPath

    请求接口/v1/{organizationId}/upload,返回上传页面
    接口参数:

    参数 参数名称 必输
    bucketName 存储桶名
    directory 存储目录
    storageCode 存储配置编码

    请求接口/v1/{organizationId}/server-upload,返回上传页面
    接口参数:

    参数 参数名称 必输
    configCode 服务器上传配置编码
    path 存储目录

    断点续传仅在同一文件上传中断后,重新上传该文件才会生效
    同一文件上传成功后再次上传,不会执行断点续传