部署问题

如何重新安装

停止可能已经运行中的 HAP 服务，在管理器根目录执行以下命令：（正常情况下停止成功输出 stoped）；
```
bash ./service.sh stopall
```
```
rm -f ./installer.stage
```
备份 HAP 服务文件（具体备份目标位置可自定义，一般首次部署时不需要，可直接 rm -rf /data/mingdao/）；
```
mv /data/mingdao/ /home/hapbak/
```
再次确认是否已清理干净，分别执行以下命令，确保输出结果都为空（不为空则将对应进程kill）；
```
docker ps | grep mingdaoyun
```
```
netstat -ntpl | grep 38881
```
```
ps -ef | grep 'mingdaoyun\|service.sh' | grep -v grep
```
执行以下命令重启管理器，启动成功后访问 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 服务部署在性能较高的硬盘之上，否则使用过程中可能会遇到性能问题，硬盘性能指标可参阅服务器基础性能要求。

服务启动完成遇到响应码错误（Service response code error）

问题现象：服务启动完成后出现 "Service response code error" 报错，但后续可能仍可正常访问。

问题原因：在磁盘I/O性能较低的环境（如使用机械硬盘作为数据盘）会导致服务启动较慢。服务启动后5分钟会进行健康检查，当健康检查超时未收到响应时，系统会抛出此错误。

检查方法：

尝试访问 HAP 页面，如能正常访问并使用则表明核心服务启动完成。
执行 docker logs $(docker ps | grep mingdaoyun-community | awk '{print $1}') 检查微服务容器日志：
- 正常情况应主要为INFO级别日志，则代表正常。
- 如出现ERROR或WARN级别日志需重点关注。

后续建议：为确保服务稳定运行、保障性能表现及数据存储安全，强烈建议将服务部署于高性能磁盘，当前主流云服务商的标准磁盘均可满足最低基础性能需求，物理机部署则推荐选用 SSD 磁盘。

如何配置开机自启动

实现方式：基于操作系统自带的 rc-local 服务，将 HAP 服务启动命令写入开机自启动脚本中实现 HAP 服务开机自启动。

以安装管理器所在路径为 /usr/local/MDPrivateDeployment/ 为例，以下提供几种常见操作系统的配置方法供参考：

CentOS
Debian
Ubuntu

编辑 /etc/rc.d/rc.local 文件，尾部追加 HAP 服务启动命令。

可直接通过下方命令在文件尾部追加 HAP 服务启动命令：

cat >> /etc/rc.d/rc.local << EOF
sleep 30
cd /usr/local/MDPrivateDeployment/ && /bin/bash ./service.sh restartall
EOF

为确保此文件具有可执行权限，请执行：chmod +x /etc/rc.d/rc.local

Debian 默认没有启用 rc-local 服务，因此需要手动启用。可参考以下步骤进行操作：

检查 rc-local 服务状态
```
systemctl status rc-local
```
- 如果 rc-local 服务已启用并正在运行，跳至步骤 4。
- 如果 rc-local 服务未启用，继续进行下一步。

创建 rc.local 初始文件并添加可执行权限

echo '#!/bin/bash' > /etc/rc.local
chmod +x /etc/rc.local

启动 rc.local 服务
```
systemctl enable rc-local
systemctl start rc-local
systemctl status rc-local
```
- 确保 rc-local 服务正常启动，以便在系统启动时自动执行相关命令。
编辑 /etc/rc.local 文件，尾部追加 HAP 服务启动命令。

可直接通过下方命令在文件尾部追加 HAP 服务启动命令：
```
cat >> /etc/rc.local << EOF
sleep 30
cd /usr/local/MDPrivateDeployment/ && /bin/bash ./service.sh restartall
EOF
```

Ubuntu 默认没有启用 rc-local 服务，因此需要手动启用。可参考以下步骤进行操作：

检查 rc-local 服务状态
```
systemctl status rc-local
```
- 如果 rc-local 服务已启用并正在运行，跳至步骤 5。
- 如果 rc-local 服务未启用，继续进行下一步。
修改 /lib/systemd/system/rc-local.service 文件

先备份 rc-local.service 文件
```
cp /lib/systemd/system/rc-local.service /lib/systemd/system/rc-local.service.bak
```
随后修改 rc-local.service 文件，追加 [Install] 段配置，定义 rc-local.service 服务将在操作系统正常启动后跟随启动。

可直接通过下方命令在文件尾部追加 [Install] 段配置
```
cat >> /lib/systemd/system/rc-local.service << EOF
[Install]
WantedBy=multi-user.target
EOF
```

创建 rc.local 初始文件并添加可执行权限

echo '#!/bin/bash' > /etc/rc.local
chmod +x /etc/rc.local

启动 rc.local 服务
```
systemctl daemon-reload
systemctl enable rc-local
systemctl start rc-local
systemctl status rc-local
```
- 确保 rc-local 服务正常启动，以便在系统启动时自动执行相关命令。
编辑 /etc/rc.local 文件，尾部追加 HAP 服务启动命令。

可直接通过下方命令在文件尾部追加 HAP 服务启动命令：
```
cat >> /etc/rc.local << EOF
sleep 30
cd /usr/local/MDPrivateDeployment/ && /bin/bash ./service.sh restartall
EOF
```

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

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

bash ./service.sh stopall

rm -f service.pid

bash ./service.sh startall

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

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

可能原因：

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

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

停止服务，管理器根目录下执行 bash ./service.sh stopall；
备份 /data/mingdao/；
执行命令 rm -rf /data/mingdao/script/volume/data/{kafka,zookeeper}/* 删除消息队列中的异常数据，正常情况不会造成数据丢失（除非有未执行完成的工作流）；
管理器根目录下执行 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: "6.3.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_PROTO、ENV_EXT_MINGDAO_HOST、ENV_EXT_MINGDAO_PORT（与 ENV_MINGDAO_PROTO、ENV_MINGDAO_HOST、ENV_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

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

如何修改默认的存储路径

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

新安装

管理器版本>=3.6.0
管理器版本<3.6.0

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

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

{ 
  "dataDir": "/app/hap" 
}

迁移

管理器版本>=3.6.0
管理器版本<3.6.0

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

对于已安装过的 HAP 情况，修改 /etc/pdcaptain.json ，指定新的数据存储目录 dataDir。在 HAP 服务停止的情况下，将 /data/mingdao 目录下的文件全部移到新 dataDir 下，然后重启服务即可。

外部如何访问各存储组件

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

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

微服务版本>=5.1.0
微服务版本<5.1.0

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

services:
  app:
    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，支持设置 mysql、mongodb、redis、kafka、file、elasticsearch ，多个则使用英文逗号分隔，如下：

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，支持：ALLOWALL、SAMEORIGIN、DENY、ALLOW-FROM uri，如下：

services:
  app:
    environment:
      ENV_FRAME_OPTIONS: "ALLOWALL"

设置IP白名单访问策略

允许针对访问来源IP做限制，需要基于客户端访问的第一层代理进行配置，具体配置示例参考：

# 示例一
http {
  server {
    ......
    # 允许192.168.0.1 IP访问
    allow 192.168.0.1;
    # 允许192.168.0.1/32网段内的IP访问
    allow 192.168.0.1/32;
    # 拒绝所有其他IP地址访问
    deny all;

    location / {
      ......
    }
  }
}

# 示例二
http {
  server {
    ......

    location / {
      # 允许192.168.0.1 IP访问
      allow 192.168.0.1;
      # 允许192.168.0.1/32网段内的IP访问
      allow 192.168.0.1/32;
      # 拒绝所有其他IP地址访问
      deny all;
    }
  }
}

如何自定义工作流 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（WorkFlow、WorkFlow-Batch、WorkFlow-Button、WorkFlow-Process、WorkFlow-Router、WorkSheet、WorkSheet-Batch、WorkSheet-Router、WorkSheet-onlyimport）的分区数，默认分区数是 10，消费线程数设置请不要大于分区数。

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

执行以下命令可查看 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

# kafka安装包文件下载链接，下载完成后上传到部署服务器/tmp/目录下：
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

如果有需要可分别执行以下命令调整 Kafka 分区数（如调整为 20 个分区）

/usr/local/kafka/bin/kafka-topics.sh --alter --bootstrap-server ${ENV_KAFKA_ENDPOINTS:=127.0.0.1:9092} --partitions 20 --topic WorkFlow
/usr/local/kafka/bin/kafka-topics.sh --alter --bootstrap-server ${ENV_KAFKA_ENDPOINTS:=127.0.0.1:9092} --partitions 20 --topic WorkFlow-Batch 
/usr/local/kafka/bin/kafka-topics.sh --alter --bootstrap-server ${ENV_KAFKA_ENDPOINTS:=127.0.0.1:9092} --partitions 20 --topic WorkFlow-Button 
/usr/local/kafka/bin/kafka-topics.sh --alter --bootstrap-server ${ENV_KAFKA_ENDPOINTS:=127.0.0.1:9092} --partitions 20 --topic WorkFlow-Process
/usr/local/kafka/bin/kafka-topics.sh --alter --bootstrap-server ${ENV_KAFKA_ENDPOINTS:=127.0.0.1:9092} --partitions 20 --topic WorkFlow-Router
/usr/local/kafka/bin/kafka-topics.sh --alter --bootstrap-server ${ENV_KAFKA_ENDPOINTS:=127.0.0.1:9092} --partitions 20 --topic WorkSheet 
/usr/local/kafka/bin/kafka-topics.sh --alter --bootstrap-server ${ENV_KAFKA_ENDPOINTS:=127.0.0.1:9092} --partitions 20 --topic WorkSheet-Batch
/usr/local/kafka/bin/kafka-topics.sh --alter --bootstrap-server ${ENV_KAFKA_ENDPOINTS:=127.0.0.1:9092} --partitions 20 --topic WorkSheet-Router
/usr/local/kafka/bin/kafka-topics.sh --alter --bootstrap-server ${ENV_KAFKA_ENDPOINTS:=127.0.0.1:9092} --partitions 20 --topic WorkSheet-onlyimport

在配置文件中添加环境变量 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-editcontrols、ws-passiverelation、ws-formulaensure）的分区数，默认是3，消费线程数设置请不要大于分区数。

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

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

/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

# kafka安装包文件下载链接，下载完成后上传到部署服务器/tmp/目录下：
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

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

/usr/local/kafka/bin/kafka-topics.sh --alter --bootstrap-server ${ENV_KAFKA_ENDPOINTS:=127.0.0.1:9092} --partitions 20 --topic ws-editcontrols
/usr/local/kafka/bin/kafka-topics.sh --alter --bootstrap-server ${ENV_KAFKA_ENDPOINTS:=127.0.0.1:9092} --partitions 20 --topic ws-passiverelation
/usr/local/kafka/bin/kafka-topics.sh --alter --bootstrap-server ${ENV_KAFKA_ENDPOINTS:=127.0.0.1:9092} --partitions 20 --topic ws-formulaensure

在配置文件中添加环境变量 ENV_WORKSHEET_CONSUMER_THREADS，默认 2（设置的值不要过大，需确保服务器资源充足），如下：
```
services:
  app:
    environment:
      ENV_WORKSHEET_CONSUMER_THREADS: "10"
```

如何自定义功能模块样式

创建自定义样式文件（如：freestyle.css），通过网页的审查元素功能定位并获取元素标识（如：html tag、id、class），设置自定义样式（如：隐藏功能模块、调整字体、背景色）
```
/* 隐藏消息模块 */
#chat {display:none!important }
```
在配置文件中将自定义样式文件挂载到容器内（/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、神策等一些数据分析引擎，监控系统的使用状态。

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

在配置文件中将扩展脚本文件挂载到容器内（/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"

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

在配置文件中添加环境变量 ENV_LOGIN_IP_LOCK_LIMIT_COUNT，ENV_LOGIN_IP_LOCK_MINUTES（单位：分），如下：

开启需确保代理层已添加 X-Real-IP（代理参考，同IP判断基于此参数）；另外还需特别注意，如果是内网环境，客户端IP可能一样，开启后全员将受影响。

services:
  app:
    environment:
      ENV_LOGIN_IP_LOCK_LIMIT_COUNT: "10"
      ENV_LOGIN_IP_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（单位：分，最大：5256000）；设置环境变量 ENV_FILE_DOWNLOAD_TOKEN_EXPIRE_MINUTES，文件下载链接中 token 过期时间，默认：60（单位：分，最大：5256000），如下：

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

如何配置高德地图 API Key

系统默认的高德地图 API Key 是所有私有部署用户共享的，有日调用用量限制，超过最大日调用量会导致相关功能无法正常使用，所以建议配置自己的 API Key（用量超出后可选择购买）

通过高德开放平台 https://lbs.amap.com 注册开发者账号（个人或企业均可，建议个人认证开发者即可）
创建应用并设置 key，服务平台选择 Web端(JS API)，创建成功会生成 Key 和安全密钥
在 HAP 系统配置 > 集成 > 地图服务，类型选择高德地图，配置 API Key、安全密钥
使用系统定位/地图功能出现异常时，可确认是否是高德地图调用量不足，若用量不足可进入高德地图控制台查看实时用量。用量不足可购买用量，购买请参考：https://lbs.amap.com/upgrade#price 通常来说只需要购买基础搜索服务流量包即可

如何引用在线翻译资源文件

默认情况下，翻译资源引用微服务镜像版本内携带的文件。由于版本迭代周期不定，为了较快引用到最新的翻译资源文件，产品支持配置外部翻译资源地址（更新频率相对较高）。

在微服务应用对应的 yaml 配置文件中添加环境变量 ENV_TRANSLATION_SOURCE_HOST_V2，如下：

services:
  app:
    environment:
      ENV_TRANSLATION_SOURCE_HOST_V2: "https://alifile.mingdaocloud.com/lang/HAP-Private"

注意：

部署环境需要支持访问 https://alifile.mingdaocloud.com/lang/HAP-Private
前端采用二次开发的情况不建议使用（可能存在文案异化，翻译匹配不上）

如何改成引用 CDN 资源

从云市场（如：腾讯云、阿里云）购买 CDN 服务，已有 CDN 服务的可忽略
设置加速域名，并配置回源站点（HAP 系统的访问地址）
在微服务应用对应的 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"

如何重新安装​

初始化失败​

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

服务启动完成遇到响应码错误（Service response code error）​

如何配置开机自启动​

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

密钥丢失，服务器Id 不显示​

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

文档无法在线预览​

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

工作表导出 Excel 失败​

上传附件接口超时​

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

如何开启双访问地址​

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

新安装​

迁移​

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

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

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

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

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

设置IP白名单访问策略​

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

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

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

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

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

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

如何自定义功能模块样式​

如何添加全局性 Javascript 脚本​

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

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

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

如何自定义同一IP下连续登录失败次数开始锁定及锁定时长​

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

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

如何配置高德地图 API Key​

如何引用在线翻译资源文件​

如何改成引用 CDN 资源​

如何给容器增加 hosts 解析​