Issue/Introduction

This article describes how to troubleshoot port and dependency connectivity issues when ZCenter is inaccessible after deployment, an API returns 502/503, a service fails to start, or services cannot discover one another. It distinguishes the external proxy port from the internal Gateway port to prevent confusion between ports 8100 and 8200.

Symptoms

• A client connection to http://<host>:8100 times out, is refused, or cannot be established.
• Port 8100 accepts a connection but returns 502/503, or the page opens but API requests fail.
• Service startup logs report that connections to 3306, 6379, 5672, or 8848 were refused, timed out, or failed authentication.
• Gateway is accessible, but /api/portal/..., /api/vm/..., or another API returns 503 or has no route.

Environment

• Product: ZCenter
• Version: 5.1.0
• Component: Caddy/reverse proxy, Gateway, Nacos, Base, and business services
• Deployment: Single-node or multi-node. Deployment parameters, container mappings, load balancers, or firewall policies might override the actual ports.

Possible causes

• An external firewall, load balancer, or security group does not allow port 8100, or Caddy does not listen on that port.
• Caddy listens on port 8100 but cannot connect to local Gateway port 8200.
• Gateway is not running, or it cannot connect to Nacos on port 8848, causing service discovery or routing to fail.
• The internal ports used by Base, Portal, or a business service differ from the actual deployment mappings.
• MariaDB/MySQL, Redis, or RabbitMQ is not running, its address is incorrect, or its credentials do not match.

Resolution

Port and access relationships

1. Confirm the external endpoint from a client

• Command:

  curl -v --max-time 10 http://<zcenter-host>:8100/

• Expected result: The TCP connection succeeds and returns a page or HTTP response. Even a 404 shows that the port and HTTP path reached a service.
• If abnormal: For a timeout or Connection refused, check the external firewall, security group, load balancer/NAT mapping, and Caddy listener before troubleshooting a business API.

2. Check ports 8100 and 8200 on the ZCenter host

• Linux commands:

  ss -lntp | grep -E ':(8100|8200)\b'
  curl -v --max-time 10 http://127.0.0.1:8100/
  curl -v --max-time 10 http://127.0.0.1:8200/

• Expected result: Gateway listens on port 8200. If Caddy is enabled, the external proxy listens on port 8100 and local port 8100 is accessible.
• If abnormal: If port 8200 is not listening, check Gateway startup logs. If port 8200 works but port 8100 does not, check the Caddy configuration and process. If port 8100 is accessible only locally, check the external listen address and firewall.

3. Verify the route from the proxy to Gateway

• Command:

  curl -v --max-time 10 http://127.0.0.1:8100/api/portal/v4/pub/login

• Expected result: A parameter-validation or authentication response shows that the HTTP path reached Gateway or Portal. A refused or timed-out TCP connection is not a business-parameter issue.
• If abnormal: If port 8100 returns 502/503, check whether the Caddy upstream points to reachable 127.0.0.1:8200. If Gateway runs in a separate container, localhost might refer to the wrong network namespace. Correct the deployment configuration for the actual container network.

4. Verify Nacos and service discovery

• Command:

  curl -v --max-time 10 http://<nacos-host>:8848/nacos/actuator/health

• Check: Confirm that Gateway can access Nacos and that target services such as Portal, Base, and VM are registered and available.
• Expected result: Nacos is accessible, and Gateway can find the corresponding service instance for paths such as /api/portal/....
• If abnormal: Check the network policy for port 8848, Nacos state, namespace/credentials, and service registration logs. A running Gateway process alone does not prove that routing works.

5. Verify external dependencies

• Read-only connectivity checks:

  nc -vz <db-host> 3306
  nc -vz <redis-host> 6379
  nc -vz <rabbitmq-host> 5672

• Expected result: The ports are reachable, and application-level authentication succeeds with the actual accounts.
• If abnormal: Check the address, port, password, database, and TLS settings in the runtime configuration and inspect the corresponding service logs. 127.0.0.1 in the source code is only a default/example value and does not represent every deployment.

6. Isolate by scope

• If neither port 8100 nor 8200 is reachable: Check the Gateway/Caddy processes and host port policy first.
• If ports 8100 and 8200 work but a Portal API returns 503: Check Nacos and Portal service registration/health first.
• If the page opens but login or resource operations fail: Continue checking Redis, the database, RabbitMQ, and the corresponding business service logs.

7. Collect support information

• Record the client access time, source address, request URL, HTTP status code, and complete response headers.
• Collect Caddy, Gateway, Nacos, and affected business service logs from the same time window.
• Provide the deployment topology, container/host network, port mappings, firewall/load-balancer rules, and actual runtime configuration.

Handling

1. Allow the confirmed external endpoint on port 8100 and the required service-to-service paths while avoiding external exposure of unrelated ports.
2. Restore Caddy and Gateway, and confirm that the Caddy upstream matches the actual Gateway listen address.
3. Restore Nacos and confirm that target services register again. Restart affected services according to the deployment specification if necessary.
4. After restoring database, Redis, and RabbitMQ connections, verify each affected business path. Do not hide the root cause through bulk restarts or cache flushing.

Verification

• Endpoint: Access to port 8100 from a client succeeds, and the page and static resources are returned successfully.
• Routing: /api/portal/... and a known API from an affected business service return an application response without 502/503.
• Registration: Gateway, Portal, Base, and target business services are available in Nacos.
• Business: Complete 1 login and 1 controlled business operation, and confirm that task state and results are normal.
• Logs: Observe 1 complete request cycle and confirm that connection refusal, connection timeout, no-service-instance, and upstream errors no longer occur.

Risks and rollback

• Changing a firewall, load balancer, or port mapping can affect existing access. Record the original rules and make the change in a maintenance window.
• In a multi-node environment, do not directly expose every service port to the public network. Prefer access through the external proxy and required internal network policies.
• If a configuration change causes an error, restore the previous port mapping and runtime configuration, and reload services according to the original deployment method.

Additional information

• Key path: external client → port 8100 Caddy → port 8200 Gateway → Nacos service instance.
• Gateway port 8200 is not normally an external endpoint. Confirm whether the external endpoint is port 8100 from the target load-balancer and deployment configuration.
• Related KB: How do I identify and recover Redis when ZCenter login or resource synchronization fails?.