Configuring Multiple Access Addresses for the HAP System

Background

In practical applications, you might need to access the same HAP system through multiple domain names or addresses (e.g., hap.example.com and new.example.com).

However, due to the routing and security mechanisms within the HAP system, directly reverse proxying a new access address to the main address can result in session verification failures, abnormal page resource loading, and other issues.

This document will guide you on how to configure the system properly to enable safe and stable access to the HAP system from multiple addresses.

Core Principle

To ensure the HAP system correctly processes requests from multiple source addresses, the key is to enable the backend services to recognize the "true origin" of each request. This requires the cooperative function of three configurations:

1. Unified Proxy Target: All requests from extended addresses should be forwarded through a reverse proxy (such as Nginx) to a dedicated port 18880 within the HAP container.

2. Declare Source Address (pdaddr): In the reverse proxy configuration, an HTTP request header named pdaddr must be added. Its value is the complete address of the client's actual request, used to clearly inform the HAP backend.

3. Address Whitelist: All extended access addresses must be added to an address whitelist environment variable ENV_ADDRESS_ALLOWLIST to ensure system validation of their legitimacy.

With the above configurations, the system can correctly identify and process requests from different addresses, dynamically generating the correct resource URLs to ensure normal functionality.

Configuration Steps

1. Add a new port mapping under the ports section for the app service in docker-compose.yaml to map the 18880 port inside the container:

   - 18880:18880

2. Add a new environment variable under the environment section for the app service. The value of the environment variable should be your extended access addresses, separated by commas if there are multiple:

   ENV_ADDRESS_ALLOWLIST: "https://hap2.domain.com"

3. Restart the HAP service within the installation manager directory for the changes to take effect:

   bash ./service.sh restartall

4. Configure the nginx file to reverse proxy the new access address to the HAP microservices' 18880 port. Nginx reverse proxy configuration file references:

   • HTTP
   • HTTPS

5. In the nginx configuration file, add proxy_set_header pdaddr under the location to specify the access address of the system:

   Example:

   location / {
       set $real_ip '';
       if ($http_x_real_ip) {
           set $real_ip $http_x_real_ip;
       }
       if ($http_x_real_ip = '') {
           set $real_ip $remote_addr;
       }
       proxy_set_header X-Real-IP $real_ip;
       proxy_set_header Host $http_host;
       proxy_set_header X-Forwarded-Proto $scheme;
       proxy_pass http://hap;
       proxy_set_header pdaddr https://hap2.domain.com; # Added, modify to your actual extended access address
   }
   
   location ~ /mds2 {
       proxy_set_header Host $http_host;
       proxy_hide_header X-Powered-By;
       proxy_set_header X-NginX-Proxy true;
       proxy_pass http://hap;
       proxy_redirect off;
       proxy_http_version 1.1;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection upgrade;
       proxy_set_header pdaddr https://hap2.domain.com; # Added, modify to your actual extended access address
   }

6. Reload nginx and you should be able to use the HAP system normally through the new access addresses.