开发指导

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 Java 、 kkFileView 和 onlyOffice

• onlyOffice文件预览
  onlyOffice的搭建参考文件在线编辑的说明。

修改文件服务配置文件

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格式支持不是太好，但大多数格式还是支持的。

• Aspose
  使用Aspose需要购买授权，授权文件的放置在文件服务中classpath:license/license.xml

修改文件服务配置文件

hzero:
  file:
    preview-type: aspose

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

• kkFileView
  kkFileView是开源免费的，服务搭建参考官方文档

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

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

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

1.4 pdf水印

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

• 根据文件url预览pdf并添加水印

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

• 参数:

• 根据文件key预览pdf并添加水印

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

• 参数:

1.5 文件分片与断点续传

使用该功能，必须先配置：hzero.file.gatewayPath。

• 对象存储的分片上传

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

• 服务器文件的分片上传

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

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