跳到主要内容

部署问题

如何重新安装​

  1. 停止可能已经运行的明道云服务，在管理器根目录执行 bash ./service.sh stopall（正常情况下停止成功输出 stoped）；
  2. 备份明道云服务文件，mv /data/mingdao/ /home/mingdaobak/（具体备份目标位置可自定义，一般首次部署时不需要，可直接 rm -rf /data/mingdao/）；
  3. 再次确认是否已清理干净，分别执行 docker ps | grep mingdaoyun 、netstat -ntpl | grep 38881、ps -ef | grep 'mingdaoyun\|service.sh' | grep -v grep 确保输出结果都为空；
  4. 重启管理器，bash ./service.sh start，访问 http://{服务器IP}:38881 再次安装。

初始化失败​

可通过执行命令 cat /data/mingdao/script/mingdaoyun.log 查看失败原因，大部分情况下是 空间不足、镜像不存在、端口被占用、iptables failed 等，如果 iptables failed，原因是关闭防火墙时会清空 iptables 规则，所以需要重启 Docker 重新生成 Docker 默认的 iptables 规则，解决问题后 重新安装。

容器内无法访问互联网​

使用 firewalld 作为防火墙的情况下如出现容器无法访问外部网络（正常情况下，明道云服务并不需要与互联网互通，但不可避免有些系统功能需要使用到互联网，如：邮件、短信发送通道），则需添加下面的防火墙规则，2条命令都执行即可（172.16.0.1/12这个是容器网段）：

允许容器网段访问互联网（永久生效）

firewall-cmd --zone=trusted --add-source=172.16.0.1/12 --permanent

允许容器网段访问互联网（临时生效）

firewall-cmd --zone=trusted --add-source=172.16.0.1/12

如何设置开机启动（CentOS示例）​

确保具有执行权限chmod +x /etc/rc.d/rc.local 修改 /etc/rc.d/rc.local（确保该文件具有可执行权限），加入如下脚本：

sleep 30
docker system prune -f
/bin/rm -f {管理器绝对路径}/service.pid
/bin/bash {管理器绝对路径}/service.sh startall

服务器重启后，明道云服务无法正常启动​

管理器根目录下执行 bash ./service.sh stopall，如果依然存在 service.pid ，删除 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，等待命令执行完成即可。

因断电等意外情况发生后，明道云服务重启后工作流、统计等功能无法正常使用​

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

文档无法在线预览​

由于文档预览服务需要从微服务应用中读取文件，如果内网环境无法访问系统对外访问地址，则会出现文档预览失败。这种情况下需要在 docker-compose.yaml 的 doc 配置中加入环境变量 ENV_FILE_INNER_URI，指定系统内网访问地址，参考如下：

services:
  doc:
    environment:
      ENV_FILE_INNER_URI: "10.140.100.6:8880"

工作表导出 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://mdy;  # 这里按实际 upstream 名称进行调整
}

上传附件接口超时​

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

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

工作流列表加载失败、附件无法下载等​

在对明道云服务添加代理的情况下，使用代理地址进行访问需要确保 /data/mingdao/script/docker-compose.yaml 中的相关环境变量与访问地址一致，另外也需要确保代理的配置包含了推荐配置的所有内容，可参考：设置代理

如何开启子路径方式部署​

在微服务应用对应的 docker-compose.yaml 中调整环境变量 ENV_MINGDAO_SUBPATH，如下：

services:
  app:
    environment:
      ENV_MINGDAO_SUBPATH: "/mdy"       # 新增，如：/mdy

如何开启两个访问地址​

在微服务应用对应的 docker-compose.yaml 中设置环境变量 ENV_EXT_MINGDAO_PROTO、ENV_EXT_MINGDAO_HOST、ENV_EXT_MINGDAO_PORT（是与 ENV_MINGDAO_PROTO、ENV_MINGDAO_HOST、ENV_MINGDAO_PORT 对应的一组配置），暴露端口18880（具体对应主机端口自定义，这里依然使用 18880），然后将 http://mdy1.domain.com 解析到主机的 18880 端口即可（如果直接使用主机的内外网 IP 方式访问，则可忽略域名解析配置），如下：

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

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

新安装

3.6.0 及之后版本​

在启动明道云管理器前（即执行 ./service.sh start 前）， 修改 service.sh 中的 installDir 参数值。

3.6.0 之前版本​

在启动明道云管理器前（即执行 ./service.sh start 前），先创建 /etc/pdcaptain.json，指定 dataDir 属性，启动后的相关文件都会存放在 /app/mingdao 目录下，配置格式如下：

{ 
  "dataDir": "/app/mingdao" 
}

迁移

3.6.0 及之后版本​

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

3.6.0 之前版本​

对于已安装过的明道云情况，同样是创建 /etc/pdcaptain.json ，指定数据存储目录 dataDir。在明道云服务停止的情况下，将 /data/mingdao 目录下的文件全部移到 dataDir 下，然后重启服务即可。

外部如何访问各存储组件​

单机部署模式下，容器内默认会启动依赖的各存储组件，包括：mysql、mongodb、redis、kafka、file、elasticsearch，而这些组件的端口默认并不对外，如果需要外部连接，可通过修改微服务应用对应的 docker-compose.yaml 中的 ports 字段暴露对应端口，如下：

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

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

单机部署模式下如何部分启用外部存储组件​

在微服务应用对应的 docker-compose.yaml 中设置环境变量 ENV_STANDALONE_DISABLE_SERVICES，支持设置 mysql、mongodb、redis、kafka、file、elasticsearch ，如下：

services:
  app:
    environment:
      ENV_STANDALONE_DISABLE_SERVICES: "redis,file"  # 多个则使用英文逗号分隔

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

如何自定义 mongodb 最大使用内存​

在微服务应用对应的 docker-compose.yaml 中设置环境变量 ENV_MONGODB_CACHEGB，默认是 (物理内存-10)/2（单位：G），如下：

services:
  app:
    environment:
      ENV_MONGODB_CACHEGB: 3

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

默认支持嵌入同域下的 IFrame 使用，如果希望被其他系统引入，可通过修改微服务应用对应的 docker-compose.yaml，设置环境变量 ENV_FRAME_OPTIONS，支持：ALLOWALL、SAMEORIGIN、DENY、ALLOW-FROM uri。

services:
  app:
    environment:
      ENV_FRAME_OPTIONS: "ALLOWALL"

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

在微服务应用对应的 docker-compose.yaml 中设置环境变量 ENV_WORKFLOW_WEBHOOK_TIMEOUT，默认 10（单位：秒），如下：

services:
  app:
    environment:
      ENV_WORKFLOW_WEBHOOK_TIMEOUT: 30

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

在微服务应用对应的 docker-compose.yaml 中设置环境变量 ENV_WORKFLOW_COMMAND_TIMEOUT，默认 10（单位：秒），如下：

services:
  app:
    environment:
      ENV_WORKFLOW_COMMAND_TIMEOUT: 30

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

在微服务应用对应的 docker-compose.yaml 中设置环境变量 ENV_WORKFLOW_COMMAND_MAXMEMORY，默认 64（单位：M），如下：

services:
  app:
    environment:
      ENV_WORKFLOW_COMMAND_MAXMEMORY: 128

如何自定义工作流消息队列的消费线程数​

在修改工作流消息队列的消费线程数前，需要先调整 Kafka 中相关 Topic（WorkFlow、WorkFlow-Batch、WorkFlow-Button、WorkFlow-Process、WorkSheet、WorkSheet-Batch）的分区数，默认是3，消费线程数设置请不要大于分区数。

  1. 进入容器：docker exec -it $(docker ps | grep community | 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 md-workflow-consumer

  3. 如果有需要可分别执行以下命令进行分区数调整（如调整为10个分区）

    /usr/local/kafka/bin/kafka-topics.sh --alter --zookeeper localhost:2181 --partitions 10 --topic WorkFlow
    /usr/local/kafka/bin/kafka-topics.sh --alter --zookeeper localhost:2181 --partitions 10 --topic WorkFlow-Batch 
    /usr/local/kafka/bin/kafka-topics.sh --alter --zookeeper localhost:2181 --partitions 10 --topic WorkFlow-Button 
    /usr/local/kafka/bin/kafka-topics.sh --alter --zookeeper localhost:2181 --partitions 10 --topic WorkFlow-Process
    /usr/local/kafka/bin/kafka-topics.sh --alter --zookeeper localhost:2181 --partitions 10 --topic WorkSheet 
    /usr/local/kafka/bin/kafka-topics.sh --alter --zookeeper localhost:2181 --partitions 10 --topic WorkSheet-Batch

  4. 在微服务应用对应的 docker-compose.yaml 中设置环境变量 ENV_WORKFLOW_CONSUMER_THREADS，默认 3（设置的值不要过分大，需确保服务器可承受），如下：

    services:
      app:
        environment:
          ENV_WORKFLOW_CONSUMER_THREADS: 10

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

在微服务应用对应的 docker-compose.yaml 中设置环境变量 ENV_WORKFLOW_TRIGER_DELAY_SECONDS，默认 5（单位：秒），如下：

services:
  app:
    environment:
      ENV_WORKFLOW_TRIGER_DELAY_SECONDS: 1

如何自定义工作表消息队列的消费线程数​

在修改工作表消息队列的消费线程数前，需要先调整 Kafka 中相关 Topic（ws-editcontrols、ws-passiverelation）的分区数，默认是3，消费线程数设置请不要大于分区数。

  1. 进入容器：docker exec -it $(docker ps | grep community | 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

  3. 如果有需要可分别执行以下命令进行分区数调整（如调整为10个分区）

    /usr/local/kafka/bin/kafka-topics.sh --alter --zookeeper localhost:2181 --partitions 10 --topic ws-editcontrols
    /usr/local/kafka/bin/kafka-topics.sh --alter --zookeeper localhost:2181 --partitions 10 --topic ws-passiverelation

  4. 在微服务应用对应的 docker-compose.yaml 中设置环境变量 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. 在微服务应用对应的 docker-compose.yaml 中，将自定义样式文件挂载到容器内（/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），并将第三方提供脚本复制到文件内。一般情况下，第三方脚本需要引用用户唯一标识等基础用户信息，开发者可通过明道云系统提供的全局 Javascript 对象 md.global.Account 来获取。

  2. 在微服务应用对应的 docker-compose.yaml 中，将扩展脚本文件挂载到容器内（/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 获取源代码完成。

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

在微服务应用对应的 docker-compose.yaml 中设置环境变量 ENV_SESSION_TIMEOUT_MINUTES，默认是 10080（单位：分），如下：

services:
  app:
    environment:
      ENV_SESSION_TIMEOUT_MINUTES: 30

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

在微服务应用对应的 docker-compose.yaml 中设置环境变量 ENV_LOGIN_CAPTCHA_LIMIT_COUNT，设置为 0 则每次都会出现验证码，如下：

services:
  app:
    environment:
      ENV_LOGIN_CAPTCHA_LIMIT_COUNT: 0

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

在 微服务应用【单机模式】 或 文件存储服务【集群模式】对应的 docker-compose.yaml 中设置环境变量 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"

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

在微服务应用对应的 docker-compose.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

如何设置白名单访问策略​

在微服务应用对应的 docker-compose.yaml 中设置环境变量 ENV_ALLOW_IP，多个使用英文逗号分隔，如下：

services:
  app:
    environment:
      ENV_ALLOW_IP: "139.111.1.1,139.111.1.2"

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

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

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

  3. 在微服务应用对应的 docker-compose.yaml 中设置环境变量 ENV_OCR_SECRETID（对应密钥的 SecretId）、ENV_OCR_SECRETKEY（对应密钥的 SecretKey）

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

如何启用工作流获取记录打印文件节点中的 PDF 类型​

  1. 注册 WPS 开放平台账号 https://open.wps.cn/ ，进入 管理中心 提交服务商信息

  2. 申请通过后，进入 "金山文档格式转换" 服务并添加新应用，获取 APPID 和 APPKEY

  3. 在微服务应用对应的 docker-compose.yaml 中设置环境变量 ENV_WPS_APPID、ENV_WPS_APPSECRET

    services:
      app:
        environment:
          ENV_WPS_APPID: "APPID"
          ENV_WPS_APPSECRET: "APPKEY"

Web 前端如何改成引用 CDN 资源​

  1. 从云市场（如：腾讯云、阿里云）购买 CDN 服务，已有 CDN 服务的可忽略

  2. 设置加速域名，并配置回源站点（明道云系统的访问地址）

  3. 在微服务应用对应的 docker-compose.yaml 中设置环境变量 ENV_CDN_URI，如：http://mdycdn.domain.com

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