跳到主要内容

部署问题

如何重新安装​

  1. 停止可能已经运行中的服务，在管理器根目录执行以下命令：（正常情况下停止成功输出 stoped）；

    bash ./service.sh stopall
    rm -f ./installer.stage

  2. 备份服务文件（具体备份目标位置可自定义，一般首次部署时不需要，可直接 rm -rf /data/hap/）；

    mv /data/hap/ /home/hapbak/

  3. 再次确认是否已清理干净，分别执行以下命令，确保输出结果都为空（不为空则将对应进程 kill）；

    docker ps | grep hap
    netstat -ntpl | grep 38881
    ps -ef | grep 'hap\|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/hap/script/docker-compose.yaml 配置文件中添加环境变量，延迟微服务启动时间。

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

services:
  app:
    environment:
      ENV_ROLE_MODE_WAITMS: "90000"

  • ENV_ROLE_MODE_WAITMS 环境变量值的单位是毫秒，默认值为 30 秒。

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

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

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

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

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

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

检查​方法​​：

  1. 尝试访问服务页面，如能正常访问并使用则表明核心服务启动完成。

  2. 执行 docker logs $(docker ps | grep -E 'hap-community|hap:' | awk '{print $1}') 检查微服务容器日志：

    • 正常情况应主要为 INFO 级别日志，则代表正常。

    • 如出现 ERROR 或 WARN 级别日志需重点关注。 ​

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

如何配置开机自启动​

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

实现方式：基于操作系统自带的 systemd 服务，将服务启动命令写入自定义的 manager.service 服务单元文件中实现服务开机自启动。

  1. 编辑 /etc/systemd/system/manager.service 文件，添加服务启动命令。

可直接通过下方命令创建 manager.service 文件：

cat > /etc/systemd/system/manager.service <<'EOF'
[Unit]
Description=Manager
After=docker.service
Wants=docker.service
[Service]
Type=oneshot
WorkingDirectory=/usr/local/MDPrivateDeployment
ExecStart=/bin/bash service.sh restartall
RemainAfterExit=yes
StandardOutput=append:/usr/local/MDPrivateDeployment/manager.log
StandardError=append:/usr/local/MDPrivateDeployment/manager.log
[Install]
WantedBy=multi-user.target
EOF

  1. 启用开机自启动：

    systemctl daemon-reload
    systemctl enable manager

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

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

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

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

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

可能原因：

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

Kafka 启动失败​

在单机模式 下，Kafka 服务作为内置组件运行于容器中。当 Kafka 服务不可用时，会出现包括但不限于以下现象：

  • 工作流无法正常运行；
  • 工作表行记录数据提交缓慢；
  • 统计功能异常或数据不同步。

Kafka 在运行过程中，会将消息数据及位点信息存储在本地数据目录中。当系统发生非正常关闭（如断电关机、内存不足导致进程被强制终止）时，Kafka 与 Zookeeper 的元数据文件可能出现以下问题：

  • 日志数据文件损坏：消息日志或位点文件未写入完整，导致校验失败；
  • Zookeeper 状态不一致：事务日志未正确提交，导致 Kafka 启动时无法加载集群元数据；
  • Kafka 启动卡死：Kafka 在恢复阶段检测到不一致的索引或日志文件，进入异常恢复循环。

由于单机模式下 Kafka 不具备集群副本机制，这类错误无法自动恢复，只能通过清空异常数据重新初始化 Kafka 服务。

在检查容器日志时，若发现 Kafka 服务无法启动，可按下方步骤进行修复:

  1. 在管理器根目录下执行 bash ./service.sh stopall 停止服务；

  2. 执行以下命令重命名 Kafka 与 Zookeeper 的数据目录，以清除异常状态数据：

    mv /data/hap/script/volume/data/kafka{,_bak_$(date +%Y%m%d%H%M)}
    mv /data/hap/script/volume/data/zookeeper{,_bak_$(date +%Y%m%d%H%M)}

  3. 在管理器根目录下执行 bash ./service.sh startall 启动服务；

上传附件接口超时​

上传大于 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://example1.domain.com 解析到主机的 18880 端口即可（如果直接使用主机的内外网 IP 方式访问，则可忽略域名解析配置），如下：

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

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

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

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

新安装​

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

迁移​

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

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

单机部署模式下，默认会启动依赖的各存储组件，包括：mysql、mongodb、redis、kafka、file，而这些组件的端口默认并不对外，如果需要外部连接，可通过修改配置文件（默认 /data/hap/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/hap/script/docker-compose.yaml）添加环境变量 ENV_STANDALONE_DISABLE_SERVICES，支持设置 mysql、mongodb、redis、kafka、file ，多个则使用英文逗号分隔，如下：

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;
    }
  }
}

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

在配置文件中添加环境变量
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 中添加对应环境变量

如何给容器增加 hosts 解析​

在 hdp 服务中添加 extra_hosts 配置，如：

services:
  hdp:
    extra_hosts:
      - "a.domain.com:192.168.1.10"
      - "b.domain.com:172.17.13.42"