跳到主要内容

部署问题

如何重新安装

  1. 停止可能已经运行中的 HAP 服务,在管理器根目录执行以下命令:(正常情况下停止成功输出 stoped);

    bash ./service.sh stopall
    rm -f ./installer.stage
  2. 备份 HAP 服务文件(具体备份目标位置可自定义,一般首次部署时不需要,可直接 rm -rf /data/mingdao/);

    mv /data/mingdao/ /home/hapbak/
  3. 再次确认是否已清理干净,分别执行以下命令,确保输出结果都为空(不为空则将对应进程kill);

    docker ps | grep mingdaoyun
    netstat -ntpl | grep 38881
    ps -ef | grep 'mingdaoyun\|service.sh' | grep -v grep
  4. 执行以下命令重启管理器,启动成功后访问 http://{服务器IP}:38881 再次安装

    bash ./service.sh start

初始化失败

首次部署页面提示初始化失败时,请到服务器上执行以下命令观察输出,通常终端中会输出异常信息,根据输出内容进一步判断问题。

bash ./service.sh restartall

如果有 iptables failed 关键字错误,通常是关闭 firewalld 时会清空 iptables 规则,所以需要重启 Docker 重新生成默认的 iptables 规则,然后再 重新安装

初始化完成后提示“账号已退出,请重新登录”

问题基本原因:服务器硬盘 IOPS 性能较低,服务启动过程中硬盘IO占满,导致存储组件服务启动缓慢。

解决方法

/data/mingdao/script/docker-compose.yaml 配置文件中添加环境变量,延迟微服务启动时间。

环境变量添加后在安装管理器目录下执行 bash service.sh restartall 重启服务,待重启完成后再重新填写初始信息。

services:
app:
environment:
ENV_ROLE_MODE_WAITMS: "90000"
  • ENV_ROLE_MODE_WAITMS 环境变量值的单位是毫秒,默认值为30秒。

  • 本示例中,将环境变量的默认值调大至90秒,让微服务延迟启动90秒,先保证存储组件进程在微服务启动前完成启动。

  • 如果问题仍然无法解决,可以继续增加等待时间,例如180秒,然后重启服务进行测试。

  • 此环境变量值调大会带来服务整体启动速度变慢的问题,更加建议将 HAP 服务部署在性能较高的硬盘之上,否则使用过程中可能会遇到性能问题,硬盘性能指标可参阅服务器基础性能要求

如何配置开机启动(CentOS示例)

修改 /etc/rc.d/rc.local 文件,加入如下内容:

sleep 30
docker system prune -f
cd {安装管理器绝对路径} && /bin/bash ./service.sh startall
  • 为确保此文件具有可执行权限,请执行:chmod +x /etc/rc.d/rc.local

服务器重启后,HAP 服务无法正常启动

管理器根目录下执行分别执行以下命令,等待 startall 命令执行完成即可。如果未加入开机启动,参考 配置开机启动

bash ./service.sh stopall
rm -f service.pid
bash ./service.sh startall

密钥丢失,服务器Id 不显示

  1. 停止服务,管理器根目录下执行 bash ./service.sh stopall
  2. 执行命令 ps -ef | grep 'mingdaoyun\|service.sh' | grep -v grep (如果有输出,把对应 pid 全部 kill);
  3. 执行 bash ./service.sh startall,等待命令执行完成即可。

可能原因:

  • 服务器资源饱和,导致管理器进程被强制终止
  • 服务器时间不准确,导致密钥有效期判断错误
  • 服务器重启,但管理器未设置开机自启
  • 服务启停命令操作不规范,导致密钥周期性的有效状态识别失败

因断电等意外情况发生后,HAP 服务重启后工作流、统计等功能无法正常使用(以及断电后重启服务过程中由于kafka原因重启失败)

  1. 停止服务,管理器根目录下执行 bash ./service.sh stopall
  2. 备份 /data/mingdao/
  3. 执行命令 rm -rf /data/mingdao/script/volume/data/{kafka,zookeeper}/* 删除消息队列中的异常数据,正常情况不会造成数据丢失(除非有未执行完成的工作流);
  4. 管理器根目录下执行 bash ./service.sh startall,等待命令执行完成即可。

文档无法在线预览

由于文档预览容器需要读取文件,如果内网与系统外部访问地址(文件地址)不通,则会出现文档预览失败。
这种情况下需要在配置文件的 doc 服务中添加环境变量 ENV_FILE_INNER_URI,如下:

services:
doc:
environment:
ENV_FILE_INNER_URI: "app:8880"

如果上述配置没有问题,可以在浏览器访问文件预览界面按下F12进入开发者界面,重新触发预览报错,查看console(控制台)报错做进一步分析(例如跨域、协议头http/https不同导致)。

升级后页面左下角显示的版本号不正确

在配置文件的 app 服务中添加环境变量 ENV_APP_VERISON,然后重启服务即可,如下:

services:
app:
environment:
ENV_APP_VERSION: "5.2.3"

工作表导出 Excel 失败

由于有些表单数据量问题,导出有时候会出现 504 Gateway Time-out 等情况,这一般是由于代理层默认超时时间和文件大小限制问题,可添加如下规则(nginx 为例):

location ~ /excelapi {
proxy_set_header Host $http_host;
proxy_read_timeout 1800s;
client_max_body_size 256m;
proxy_pass http://hap; # 这里按实际 upstream 名称进行调整
}

上传附件接口超时

上传大于4MB文件默认采用分片上传模式。某些情况下因网络原因可能导致上传某段分片出现超时,从而导致整个文件上传失败。解决这个问题可添加如下规则(nginx为例)

location ~ /file {
proxy_set_header Host $http_host;
proxy_read_timeout 1800s;
client_max_body_size 20480m;
proxy_pass http://hap; # 这里按实际 upstream 名称进行调整
}

如何开启子路径方式部署

在配置文件的 app 服务中添加环境变量 ENV_MINGDAO_SUBPATH,如下:

services:
app:
environment:
ENV_MINGDAO_SUBPATH: "/hap"

如何开启双访问地址

在配置文件的 app 服务中添加环境变量 ENV_EXT_MINGDAO_PROTOENV_EXT_MINGDAO_HOSTENV_EXT_MINGDAO_PORTENV_MINGDAO_PROTOENV_MINGDAO_HOSTENV_MINGDAO_PORT 对应的一组配置),暴露端口18880(具体对应主机端口自定义,这里依然使用 18880),然后将 http://hap1.domain.com 解析到主机的 18880 端口即可(如果直接使用主机的内外网 IP 方式访问,则可忽略域名解析配置),如下:

services:
app:
environment:
ENV_EXT_MINGDAO_PROTO: "http"
ENV_EXT_MINGDAO_HOST: "hap1.domain.com"
ENV_EXT_MINGDAO_PORT: "18880"
ports:
- 8880:8880
- 18880:18880

更详细可参考 多地址配置说明

如何修改默认的存储路径 /data/mingdao

在安装管理器所在目录下执行 tail -n 3 service.sh 可以看到安装管理器版本号

新安装

在启动 HAP 管理器前(即执行 ./service.sh start 前), 修改 service.sh 中的 installDir 参数值。

迁移

对于已安装过的 HAP 情况,修改 service.sh 中的 installDir 参数值。在 HAP 服务停止的情况下,将 /data/mingdao 目录下的文件全部移到 installDir 下,然后重启服务即可。

外部如何访问各存储组件

单机部署模式下,默认会启动依赖的各存储组件,包括:mysqlmongodbrediskafkafileelasticsearch,而这些组件的端口默认并不对外,如果需要外部连接,可通过修改配置文件(默认 /data/mingdao/script/docker-compose.yaml)对应容器的 ports 字段暴露端口,如下:

操作前请仔细阅读关于 数据安全 的文档 ⚠️⚠️⚠️

services:
sc:
ports:
- 3306:3306 # mysql
- 27017:27017 # mongodb
- 6379:6379 # redis
- 9092:9092 # kafka
- 9000:9000 # file
- 9200:9200 # elasticsearch

如何部分启用外部存储组件

单机部署模式下,在配置文件中(默认 /data/mingdao/script/docker-compose.yaml)添加环境变量 ENV_STANDALONE_DISABLE_SERVICES,支持设置 mysqlmongodbrediskafkafileelasticsearch ,多个则使用英文逗号分隔,如下:

services:
app:
environment:
ENV_STANDALONE_DISABLE_SERVICES: "redis,file"

启用自定义存储组件需要将对应服务的连接地址通过环境变量进行配置,参考 环境变量说明

如何自定义 MongoDB 最大使用内存

在配置文件中添加环境变量 ENV_MONGODB_CACHEGB,默认是 (物理内存-18)/2(单位:G),如下:

services:
app:
environment:
ENV_MONGODB_CACHEGB: 6

如何自定义 Redis 最大使用内存

在配置文件中添加环境变量 ENV_REDIS_MAXMEMORY,默认不限制,限制后基于 LRU 算法进行淘汰,如下:

services:
app:
environment:
ENV_REDIS_MAXMEMORY: "5gb"

如何被其他系统通过 IFrame 引用

默认支持嵌入同域下的 IFrame 使用,如果希望被其他域名系统嵌入,可通过在配置文件中添加环境变量 ENV_FRAME_OPTIONS,支持:ALLOWALLSAMEORIGINDENYALLOW-FROM uri,如下:

services:
app:
environment:
ENV_FRAME_OPTIONS: "ALLOWALL"

如何自定义工作流 Webhook 执行超时时间

可通过在配置文件中添加环境变量 ENV_WORKFLOW_WEBHOOK_TIMEOUT,默认 10(单位:秒),如下:

services:
app:
environment:
ENV_WORKFLOW_WEBHOOK_TIMEOUT: 30

如何自定义工作流代码块执行超时时间

可通过在配置文件中添加环境变量 ENV_WORKFLOW_COMMAND_TIMEOUT,默认 10(单位:秒),如下:

services:
app:
environment:
ENV_WORKFLOW_COMMAND_TIMEOUT: 30

如何自定义工作流代码块执行允许使用的最大内存

可通过在配置文件中添加环境变量 ENV_WORKFLOW_COMMAND_MAXMEMORY,默认 64(单位:M),如下:

services:
app:
environment:
ENV_WORKFLOW_COMMAND_MAXMEMORY: 128

如何查看现有分区数、当前消息堆积情况以及如何自定义工作流消息队列的消费线程数

在修改工作流消息队列的消费线程数前,需要先调整 Kafka 中相关 Topic(WorkFlowWorkFlow-BatchWorkFlow-ButtonWorkFlow-ProcessWorkFlow-RouterWorkSheetWorkSheet-BatchWorkSheet-RouterWorkSheet-onlyimport)的分区数,默认分区数是 10,消费线程数设置请不要大于分区数。

  1. 进入容器:docker exec -it $(docker ps | grep '\-sc' | awk '{print $1}') bash

  2. 执行以下命令可查看 Topic 的现有分区数以及当前消息堆积情况

    /usr/local/kafka/bin/kafka-consumer-groups.sh --bootstrap-server ${ENV_KAFKA_ENDPOINTS:=127.0.0.1:9092} --describe --group md-workflow-consumer
    • 如果上述命令执行输出 Note: This will not show information about old Zookeeper-based consumers. 字样错误,可以参考如下方式进行查看:

      cd /tmp/ && wget https://pdpublic.mingdao.com/private-deployment/offline/common/kafka_2.13-3.4.0.tgz
      docker cp /tmp/kafka_2.13-3.4.0.tgz $(docker ps | grep '\-sc' | awk '{print $1}'):/tmp/
      docker exec -it $(docker ps | grep '\-sc' | awk '{print $1}') bash
      cd /tmp/ && tar -zxvf kafka_2.13-3.4.0.tgz
      cd /tmp/kafka_2.13-3.4.0/bin/ && ./kafka-consumer-groups.sh --bootstrap-server ${ENV_KAFKA_ENDPOINTS:=127.0.0.1:9092} --describe --group md-workflow-consumer
  3. 如果有需要可分别执行以下命令调整 Kafka 分区数(如调整为 20 个分区)

    /usr/local/kafka/bin/kafka-topics.sh --alter --zookeeper localhost:2181 --partitions 20 --topic WorkFlow
    /usr/local/kafka/bin/kafka-topics.sh --alter --zookeeper localhost:2181 --partitions 20 --topic WorkFlow-Batch
    /usr/local/kafka/bin/kafka-topics.sh --alter --zookeeper localhost:2181 --partitions 20 --topic WorkFlow-Button
    /usr/local/kafka/bin/kafka-topics.sh --alter --zookeeper localhost:2181 --partitions 20 --topic WorkFlow-Process
    /usr/local/kafka/bin/kafka-topics.sh --alter --zookeeper localhost:2181 --partitions 20 --topic WorkFlow-Router
    /usr/local/kafka/bin/kafka-topics.sh --alter --zookeeper localhost:2181 --partitions 20 --topic WorkSheet
    /usr/local/kafka/bin/kafka-topics.sh --alter --zookeeper localhost:2181 --partitions 20 --topic WorkSheet-Batch
    /usr/local/kafka/bin/kafka-topics.sh --alter --zookeeper localhost:2181 --partitions 20 --topic WorkSheet-Router
    /usr/local/kafka/bin/kafka-topics.sh --alter --zookeeper localhost:2181 --partitions 20 --topic WorkSheet-onlyimport
  4. 在配置文件中添加环境变量 ENV_WORKFLOW_CONSUMER_THREADS 指定工作流消费线程,默认 10(设置的值不要过大,需确保服务器资源可承受),如下调整为 20:

    services:
    app:
    environment:
    ENV_WORKFLOW_CONSUMER_THREADS: 20

如何自定义工作表触发工作流延迟时间

在配置文件中添加环境变量 ENV_WORKFLOW_TRIGER_DELAY_SECONDS,默认 5(单位:秒),如下:

services:
app:
environment:
ENV_WORKFLOW_TRIGER_DELAY_SECONDS: 1

如何查看现有分区数、当前消息堆积情况以及如何自定义工作表消息队列的消费线程数

在修改工作表消息队列的消费线程数前,需要先调整 Kafka 中相关 Topic(ws-editcontrolsws-passiverelationws-formulaensure)的分区数,默认是3,消费线程数设置请不要大于分区数。

  1. 进入容器:docker exec -it $(docker ps | grep '\-sc' | awk '{print $1}') bash

  2. 执行以下命令可查看各自现有分区数以及当前消息堆积情况

    /usr/local/kafka/bin/kafka-consumer-groups.sh --bootstrap-server ${ENV_KAFKA_ENDPOINTS:=127.0.0.1:9092} --describe --group worksheet-passiverelation
    /usr/local/kafka/bin/kafka-consumer-groups.sh --bootstrap-server ${ENV_KAFKA_ENDPOINTS:=127.0.0.1:9092} --describe --group worksheet-editcontrols
    /usr/local/kafka/bin/kafka-consumer-groups.sh --bootstrap-server ${ENV_KAFKA_ENDPOINTS:=127.0.0.1:9092} --describe --group worksheet-formula
    • 如果上述命令执行输出Note: This will not show information about old Zookeeper-based consumers.字样错误,可以参考如下方式进行查看:

      cd /tmp/ && wget https://pdpublic.mingdao.com/private-deployment/offline/common/kafka_2.13-3.4.0.tgz
      docker cp /tmp/kafka_2.13-3.4.0.tgz $(docker ps | grep '\-sc' | awk '{print $1}'):/tmp/
      docker exec -it $(docker ps | grep '\-sc' | awk '{print $1}') bash
      cd /tmp/ && tar -zxvf kafka_2.13-3.4.0.tgz
      cd /tmp/kafka_2.13-3.4.0/bin/ && ./kafka-consumer-groups.sh --bootstrap-server ${ENV_KAFKA_ENDPOINTS:=127.0.0.1:9092} --describe --group worksheet-passiverelation
      cd /tmp/kafka_2.13-3.4.0/bin/ && ./kafka-consumer-groups.sh --bootstrap-server ${ENV_KAFKA_ENDPOINTS:=127.0.0.1:9092} --describe --group worksheet-editcontrols
      cd /tmp/kafka_2.13-3.4.0/bin/ && ./kafka-consumer-groups.sh --bootstrap-server ${ENV_KAFKA_ENDPOINTS:=127.0.0.1:9092} --describe --group worksheet-formula
  3. 如果有需要可分别执行以下命令进行分区数调整(如调整为 15 个分区)

    /usr/local/kafka/bin/kafka-topics.sh --alter --zookeeper localhost:2181 --partitions 15 --topic ws-editcontrols
    /usr/local/kafka/bin/kafka-topics.sh --alter --zookeeper localhost:2181 --partitions 15 --topic ws-passiverelation
    /usr/local/kafka/bin/kafka-topics.sh --alter --zookeeper localhost:2181 --partitions 15 --topic ws-formulaensure
  4. 在配置文件中添加环境变量 ENV_WORKSHEET_CONSUMER_THREADS,默认 2(设置的值不要过分大,需确保服务器资源充足),如下:

    services:
    app:
    environment:
    ENV_WORKSHEET_CONSUMER_THREADS: 10

如何自定义功能模块样式

  1. 创建自定义样式文件(如:freestyle.css),通过网页的审查元素功能定位并获取元素标识(如:html tag、id、class),设置自定义样式(如:隐藏功能模块、调整字体、背景色

    /* 隐藏消息模块 */
    #chat {display:none!important }
  2. 在配置文件中将自定义样式文件挂载到容器内(/usr/local/MDPrivateDeployment/www/staticfiles/mdcss/freestyle.css),如下:

    services:
    app:
    volumes:
    - freestyle.css宿主机路径:/usr/local/MDPrivateDeployment/www/staticfiles/mdcss/freestyle.css

更多自定义开发可前往:https://github.com/mingdaocom/pd-openweb 获取源代码完成。

如何添加全局性 Javascript 脚本

通过添加全局性的 Javascript 脚本可快速实现引入百度统计、谷歌统计、GrowingIO、神策等一些数据分析引擎,监控系统的使用状态。

  1. 创建自定义扩展脚本文件(如:freestyle.js),并将第三方提供脚本复制到文件内。一般情况下,第三方脚本需要引用用户唯一标识等基础用户信息,开发者可通过HAP系统提供的全局 Javascript 对象 md.global.Account 来获取。

  2. 在配置文件中将扩展脚本文件挂载到容器内(/usr/local/MDPrivateDeployment/www/staticfiles/mdjs/freestyle.js),如下:

    services:
    app:
    volumes:
    - freestyle.js宿主机路径:/usr/local/MDPrivateDeployment/www/staticfiles/mdjs/freestyle.js

更多自定义开发可前往:https://github.com/mingdaocom/pd-openweb 获取源代码完成。

如何自定义登录状态过期时间

在配置文件中添加环境变量 ENV_SESSION_TIMEOUT_MINUTES,默认是 10080(单位:分),如下:

services:
app:
environment:
ENV_SESSION_TIMEOUT_MINUTES: 30

如何自定义是否每次登录出现验证码

在配置文件中添加环境变量 ENV_LOGIN_CAPTCHA_LIMIT_COUNT,设置为 0 则每次都会出现验证码,如下:

services:
app:
environment:
ENV_LOGIN_CAPTCHA_LIMIT_COUNT: 0

如何自定义连续登录失败次数开始锁定及锁定时长

在配置文件中添加环境变量 ENV_LOGIN_LOCK_LIMIT_COUNT,默认是 5,ENV_LOGIN_LOCK_MINUTES,默认:20(单位:分),如下:

services:
app:
environment:
ENV_LOGIN_LOCK_LIMIT_COUNT: 4
ENV_LOGIN_LOCK_MINUTES: 30

如何自定义上传文件格式黑白名单

在配置文件中添加环境变量
ENV_FILEEXT_BLOCKLIST(黑名单,默认值:.exe,.vbs,.bat,.cmd,.com,.sh
ENV_FILEEXT_ALLOWLIST(白名单)来控制上传的文件类型
当设置了 ENV_FILEEXT_ALLOWLIST 时,ENV_FILEEXT_BLOCKLIST 将自动失效,如下:

如果是单机部署模式:

services:
app:
environment:
ENV_FILEEXT_BLOCKLIST: ".exe,.sh,.html"
ENV_FILEEXT_ALLOWLIST: ".docx,.txt,.png"

如果是集群部署模式,在 file.yaml 中添加对应环境变量

如何自定义附件上传/下载 Token 过期时间

在微服务应用对应的 yaml 配置文件中设置环境变量 ENV_FILE_UPLOAD_TOKEN_EXPIRE_MINUTES,文件上传token过期时间,默认:120(单位:分);设置环境变量 ENV_FILE_DOWNLOAD_TOKEN_EXPIRE_MINUTES,文件下载链接中 token 过期时间,默认:60(单位:分),如下:

services:
app:
environment:
ENV_FILE_UPLOAD_TOKEN_EXPIRE_MINUTES: 10
ENV_FILE_DOWNLOAD_TOKEN_EXPIRE_MINUTES: 10

如何启用表单配置中的文本识别控件

  1. 开通腾讯云的通用文字识别服务,https://cloud.tencent.com/product/generalocr

  2. 通过右上角用户名下的菜单,进入 访问管理 > 访问密钥 > API 密钥管理 新建或获取现有密钥

  3. 在微服务应用对应的 yaml 配置文件中设置环境变量 ENV_OCR_SECRETID(对应密钥的 SecretId)、ENV_OCR_SECRETKEY(对应密钥的 SecretKey

    services:
    app:
    environment:
    ENV_OCR_SECRETID: "SecretId"
    ENV_OCR_SECRETKEY: "SecretKey"

如何改成引用 CDN 资源

  1. 从云市场(如:腾讯云、阿里云)购买 CDN 服务,已有 CDN 服务的可忽略

  2. 设置加速域名,并配置回源站点(HAP 系统的访问地址)

  3. 在微服务应用对应的 yaml 配置文件中设置环境变量 ENV_CDN_URI,如:http://hapcdn.domain.com

    services:
    app:
    environment:
    ENV_CDN_URI: "加速域名"

如何给容器增加 hosts 解析

在 app 服务中添加 extra_hosts 配置,如:

services:
app:
extra_hosts:
- "hap.domain.com:192.168.1.10"
- "test.domain.com:172.17.13.42"