明道云 HAP 主访问地址与扩展访问地址部署思路参考
明道云 HAP 主访问地址与扩展访问地址部署思路参考
适用：HAP 私有部署，前面有公网映射和 Nginx。以下为 HTTP 示例，IP 仅用于说明，实际以客户环境为准。
一、先弄清楚两种地址
建议： 如果内外网都要访问，通常可将公网域名设为主地址，内网地址设为扩展地址；生产公网访问优先使用 HTTPS。若只需要一个地址，配置主访问地址即可。
| 项目 | 主访问地址 | 扩展访问地址 |
|---|---|---|
| 含义 | HAP 默认主要访问入口 | 同一套 HAP 新增的访问入口，如内网地址 |
| 地址数量 | 只能配置 1 个 | 可以配置多个 |
| 第三方集成 | 钉钉、企业微信等集成使用主访问地址 | 不作为此类集成的主访问地址 |
| 示例 | http://203.0.113.10 |
http://192.168.1.10:8080 |
| Nginx 转发到 HAP | 8880 | 18880 |
| HAP 环境变量 | ENV_ADDRESS_MAIN |
ENV_ADDRESS_ALLOWLIST |
| 特殊要求 | 使用官方 HTTP 代理配置 | 另外添加 pdaddr 请求头 |
二、网络图（先看流量怎么走）
假设 Nginx 在 192.168.1.10，HAP 在 192.168.1.20。
1. 主访问地址：外部用户访问 HAP
外部用户打开 http://203.0.113.10
|
v
公网映射（NAT）：203.0.113.10:80 -> 192.168.1.10:80
|
v
Nginx 代理服务器 192.168.1.10（监听 80）
|
| 转发到 http://192.168.1.20:8880
v
HAP 服务器 192.168.1.20（主入口 8880）
2. 扩展访问地址：内网用户访问同一套 HAP
内网用户打开 http://192.168.1.10:8080
|
v
Nginx 代理服务器 192.168.1.10（监听 8080）
|
| 转发到 http://192.168.1.20:18880
| 携带 pdaddr: http://192.168.1.10:8080
v
HAP 服务器 192.168.1.20（扩展入口 18880）
看图须知：
- 公网映射：把公网
IP:端口转发到 Nginx 的内网IP:端口；不是直接转发到 HAP。 - Nginx：接收用户请求，再转发到 HAP；Nginx 监听 80 不要求把 HAP 的 8880 改为 80。
- 同机/分机都支持：如 Nginx 与 HAP 在同一台宿主机，上图中的
192.168.1.20:8880/18880可换成127.0.0.1:8880/18880（前提是容器端口已映射到本机）。如果在不同服务器，就使用 HAP 的实际内网 IP。 - 上图公网
80 -> 内网 80只是示例；实际也可能公网 8080 -> 内网 80，以客户 NAT 规则为准。若公网使用 HTTPS，应按实际 TLS 终止位置配置 HTTPS 代理。
三、HAP 配置（按实际访问地址填写）
在 HAP 的 docker-compose.yaml 中配置对应服务：
主地址：
ENV_ADDRESS_MAIN"http://203.0.113.10"
扩展地址： 在 app 服务中保留原配置，增加：
ports
"18880:18880" # 新增，原有端口映射不要删除
environment
ENV_ADDRESS_ALLOWLIST"http://192.168.1.10:8080"
以上是需要添加/修改的字段片段，不是完整的 Compose 文件；要合并到原有的
ports、environment下，不要重复新建同名字段。多个扩展地址用英文逗号分隔。修改后按实际安装方式重启 HAP。早期版本没有ENV_ADDRESS_MAIN时，参考官方 HTTP 文档中的旧版变量说明。
官方依据：HTTP 代理——主访问地址与环境变量 · 多个访问地址——18880、ENV_ADDRESS_ALLOWLIST 及重启
四、Nginx 配置要点
主地址（转发到 8880）：
server {
listen 80;
location / {
proxy_set_header Host $http_host;
proxy_pass http://192.168.1.20:8880;
}
}
扩展地址（转发到 18880）：
server {
listen 8080;
location / {
proxy_set_header Host $http_host;
proxy_set_header pdaddr http://192.168.1.10:8080;
proxy_pass http://192.168.1.20:18880;
}
}
重要：上述是帮助理解的最简片段，不是可直接上线的完整配置。 正式配置时必须以官方模板为基础，保留 IM /mds2（WebSocket）和 /agent、/api/workflow/api/sse/chat（流式响应）等规则；扩展地址的相关 location 都需添加 pdaddr。经过 WAF/负载均衡终止 HTTPS 时，还需正确传递真实访问协议。
官方完整模板：HTTP 代理配置 · 扩展地址配置及 pdaddr 示例 · 代理部署说明
五、上线前简单检查
- 确认网络：公网映射到哪台 Nginx、哪个端口？Nginx 和 HAP 是否同机？
- 确认配置：主地址是否对应
ENV_ADDRESS_MAIN；扩展地址是否配置 18880、ENV_ADDRESS_ALLOWLIST和pdaddr？ - 确认连通：在 Nginx 服务器执行（分机示例）：
curl -I --connect-timeout 5 http://192.168.1.20:8880
curl -I --connect-timeout 5 http://192.168.1.20:18880
nginx -t && nginx -s reload - 实际访问验证：分别使用主地址、扩展地址登录，检查页面、消息、文件上传下载和流式响应。
curl -I只用于初步检查连接，返回 302/401/405 不一定表示网络不通。
记住一句话：主地址走 8880；新增扩展地址走 18880 + pdaddr + ENV_ADDRESS_ALLOWLIST。不能只把新地址简单代理到 8880。
