提升私有部署成功率：单机部署的关键注意事项与参考指南

本文结合实际部署经验，整理 HAP 单机部署过程中需要关注的服务器选型、环境准备、系统安装和 Nginx 代理配置，并附上相关参考文档，帮助大家减少常见问题，顺利完成部署。

1. 服务器操作系统与存储的选择

操作系统建议选择较新的 Debian 稳定版本。可从 Debian 操作系统镜像库中，按版本和架构找到对应的 ISO 文件下载。示例下载路径：https://mirrors.163.com/debian-cd/13.2.0/amd64/iso-dvd/debian-13.2.0-amd64-DVD-1.iso。

CPU、内存、存储及网络的基础性能要求，可参考 服务器性能要求。

内存配置需要特别注意：HAP 单机部署的基础资源要求为 8 核 CPU、32GB 内存，具体以 官方资源要求为准。这部分资源不包含可选的 Flink 服务开销。启用 Flink 前，服务器需有 8GB 以上空余物理内存；32GB 的 HAP 服务器不要额外启用 Flink，官方建议升级至 64GB 后再启用。

结合以往客户的生产运行经验，未同机启用 Flink 的单机生产环境，可根据业务规模考虑 16C48G 或 16C64G；如需同机启用 Flink，建议按 64GB 及以上内存规划，并预留资源余量。

硬盘存储建议重点关注以下两点：

1）选择符合性能要求的 SSD 磁盘

根据最新 服务器性能要求，生产环境必须统一使用 SSD，禁止使用机械硬盘（HDD）；MongoDB 所在服务器优先选用 NVMe SSD。最低性能指标为：随机读、写 IOPS 均不低于 15,000；顺序读、写速度均不低于 200 MiB/s。

测试前需通过软件源或离线安装包安装 fio，以下为测试命令及对应示例结果。

1、测试随机写 IOPS

fio -direct=1 -iodepth=128 -rw=randwrite -ioengine=libaio -bs=4k -size=10G -numjobs=1 -runtime=1000 -group_reporting -filename=iotest -name=Rand_Write_Testing

2、测试随机读 IOPS

fio -direct=1 -iodepth=128 -rw=randread -ioengine=libaio -bs=4k -size=10G -numjobs=1 -runtime=1000 -group_reporting -filename=iotest -name=Rand_Read_Testing

3、测试顺序写吞吐量

fio -direct=1 -iodepth=64 -rw=write -ioengine=libaio -bs=1024k -size=10G -numjobs=1 -runtime=1000 -group_reporting -filename=iotest -name=Write_PPS_Testing

4、测试顺序读吞吐量

fio -direct=1 -iodepth=64 -rw=read -ioengine=libaio -bs=1024k -size=10G -numjobs=1 -runtime=1000 -group_reporting -filename=iotest -name=Read_PPS_Testing

2）磁盘 IO 性能不足可能引发的问题

使用 SSD 后仍需确认实际 IO 性能达标。性能不足时，可能出现以下问题：

1、初次部署后提示“账号已退出”

处理方法可参考 初始化完成后提示账号已退出的解决方案。

2、使用过程中数据增删改查缓慢

如果瓶颈来自磁盘 IO，应更换为符合性能要求的 SSD，并重新核验上述 IO 指标。

2. 操作系统环境准备与环境检测

单机部署常见端口包括 8880、18880、38881 和 38880。本文以通过 Nginx 代理访问的方案为例：外网使用 HTTPS 默认端口 443，内网使用 HTTP 默认端口 80；业务访问通过代理转发，无需直接向用户开放后端服务端口。

相关端口的作用如下：

• 38881：安装管理器端口，主要用于首次部署时的初始化。
• 8880：HAP 主访问地址对应的服务端口。
• 18880：HAP 扩展访问地址对应的服务端口。
• 80 / 443：Nginx 代理端口，根据访问地址配置转发至后端的 8880 或 18880。

在上述方案中，主要按访问需求放行 80 / 443，并为初始化管理保留 38881 的访问；管理端口的开放范围应按实际运维需求控制。

本文假设 Nginx 与 HAP 服务部署在同一台服务器上。考虑后续集成、消息推送及外部门户扫码等场景，将外网地址作为主访问地址，内网地址作为扩展访问地址：

• 主访问地址（外网）：https://hap.domain.com:443。由于 443 是 HTTPS 默认端口，可简写为 https://hap.domain.com。
• 扩展访问地址（内网）：http://192.168.1.1:80。由于 80 是 HTTP 默认端口，可简写为 http://192.168.1.1。

1、操作系统环境准备

参考 环境准备，完成操作系统相关配置。

2、环境检测

参考 环境检测参数，完成 HAP 部署前的设置与检查。

3. Docker 环境与 HAP 系统安装

部分服务器采用最小化安装，可能未预装 wget 和 curl。请提前确认并安装，避免后续下载或初始化失败。以下为联网安装命令；离线环境需提前准备对应安装包。

# CentOS 系列操作系统
yum install -y wget curl

# Debian 系列操作系统
apt update
apt-get install -y wget curl

1、安装 Docker 环境

参考 Docker 安装，按步骤完成配置。

2、安装部署 HAP 系统

根据服务器架构选择对应文档：

• AMD64（x86_64）架构：HAP 单机部署示例（AMD64）。
• ARM64 架构：HAP 单机部署示例（ARM64）。

注意：初始化时会确认系统访问地址。暂时没有自定义要求时，可使用默认地址；需要配置域名或区分主、扩展访问地址时，参考 第 4 节进行设置。

3、配置开机自启

请务必完成开机自启配置，避免服务器重启后服务无法自动恢复。操作方法参考 如何配置开机自启动。

4. Nginx 代理部署注意事项

以下沿用 第 2 节的地址规划：外网地址作为主访问地址，内网地址作为扩展访问地址。

1、部署 Nginx

参考 Nginx 代理配置完成部署。

2、配置主访问地址与扩展访问地址

主访问地址与扩展访问地址的配置有所区别，参考 多地址访问进行设置。

上述配置涉及的微服务配置文件默认路径为：/data/mingdao/script/docker-compose.yaml。