TencentCloud · Arpit-Ahuja-293 · Aug 1, 2026 · Aug 1, 2026 · Aug 1, 2026 · cubesandboxbot
@@ -294,6 +294,9 @@ Other common parameters:
 CUBE_PROXY_HTTPS_PORT=443
 CUBE_PROXY_HTTP_PORT=80
 CUBE_PROXY_GRPC_PORT=9090
+# cube-proxy's /admin/* listener. cube-proxy uses host networking, so this
+# port must be free on the node; change it when something else holds 8082.
+CUBE_PROXY_ADMIN_PORT=8082
 # Deprecated: CUBE_PROXY_HOST_PORT is ignored; configure CUBE_PROXY_HTTP_PORT instead.
 CUBE_PROXY_CERT_DIR=/usr/local/services/cubetoolbox/cubeproxy/certs
 CUBE_PROXY_DNS_ANSWER_IP="${CUBE_SANDBOX_NODE_IP}"

@@ -281,6 +281,9 @@ CUBE_PROXY_DNS_ENABLE=1
 CUBE_PROXY_HTTPS_PORT=443
 CUBE_PROXY_HTTP_PORT=80
 CUBE_PROXY_GRPC_PORT=9090
+# cube-proxy 的 /admin/* 监听端口。cube-proxy 使用 host 网络，该端口必须在
+# 节点上空闲；当 8082 已被其它进程占用时，请修改此项。
+CUBE_PROXY_ADMIN_PORT=8082
 # 已废弃：CUBE_PROXY_HOST_PORT 会被忽略；如需调整启动后检查端口，请配置 CUBE_PROXY_HTTP_PORT。
 CUBE_PROXY_CERT_DIR=/usr/local/services/cubetoolbox/cubeproxy/certs
 CUBE_PROXY_DNS_ANSWER_IP="${CUBE_SANDBOX_NODE_IP}"

@@ -420,13 +420,13 @@ EOF
       -e 's|^\(\s*listen \)9090\( http2 reuseport;\)|\1__CUBE_PROXY_GRPC_PORT__\2|' \
       -e 's|^\(\s*set \$host_proxy_port \)8081;|\1__CUBE_PROXY_HTTP_PORT__;|' \
       -e 's|^\(\s*set \$host_proxy_port \)8080;|\1__CUBE_PROXY_HTTPS_PORT__;|' \
-      -e 's|^\(\s*listen \)127\.0\.0\.1:8082;|\1__CUBE_PROXY_ADMIN_LISTEN__:8082;|' \
+      -e 's|^\(\s*listen \)127\.0\.0\.1:8082;|\1__CUBE_PROXY_ADMIN_LISTEN__:__CUBE_PROXY_ADMIN_PORT__;|' \
       -e 's|/usr/local/openresty/nginx/certs/cube\.app+3\.pem|/usr/local/openresty/nginx/certs/__CUBE_PROXY_SSL_CERT__|' \
       -e 's|/usr/local/openresty/nginx/certs/cube\.app+3-key\.pem|/usr/local/openresty/nginx/certs/__CUBE_PROXY_SSL_KEY__|' \
       "${src}"
   } > "${dst}"
 
-  for token in __CUBE_PROXY_HTTP_PORT__ __CUBE_PROXY_HTTPS_PORT__ __CUBE_PROXY_GRPC_PORT__ __CUBE_PROXY_ADMIN_LISTEN__ __CUBE_PROXY_SSL_CERT__ __CUBE_PROXY_SSL_KEY__; do
+  for token in __CUBE_PROXY_HTTP_PORT__ __CUBE_PROXY_HTTPS_PORT__ __CUBE_PROXY_GRPC_PORT__ __CUBE_PROXY_ADMIN_LISTEN__ __CUBE_PROXY_ADMIN_PORT__ __CUBE_PROXY_SSL_CERT__ __CUBE_PROXY_SSL_KEY__; do
     if ! grep -q -F "${token}" "${dst}"; then
       die "generated nginx.conf.template is missing placeholder ${token}; upstream CubeProxy/nginx.conf may have changed"
     fi

@@ -159,6 +159,12 @@ CUBE_PROXY_HTTPS_PORT=443
 # The systemd post-start TCP listener check follows this HTTP proxy port.
 CUBE_PROXY_HTTP_PORT=80
 CUBE_PROXY_GRPC_PORT=9090
+# Port the cube-proxy /admin/* server binds to. cube-proxy uses host
+# networking, so this must be free on the node — change it when something
+# else already listens on 8082. The pre-start conflict check, the systemd
+# post-start check and the cube-lifecycle-manager discovery URLs all follow
+# this value.
+CUBE_PROXY_ADMIN_PORT=8082
 # Deprecated: CUBE_PROXY_HOST_PORT is ignored; configure CUBE_PROXY_HTTP_PORT instead.
 CUBE_PROXY_CERT_DIR=/usr/local/services/cubetoolbox/cubeproxy/certs
 CUBE_PROXY_REDIS_IP=127.0.0.1

@@ -68,12 +68,16 @@ CUBE_PROXY_HTTP_PORT="${CUBE_PROXY_HTTP_PORT:-80}"
 CUBE_PROXY_GRPC_PORT="${CUBE_PROXY_GRPC_PORT:-9090}"
 CUBE_PROXY_SSL_CERT="${CUBE_PROXY_SSL_CERT:-cube.app+3.pem}"
 CUBE_PROXY_SSL_KEY="${CUBE_PROXY_SSL_KEY:-cube.app+3-key.pem}"
-# Address the /admin/* server (port 8082) binds to. Defaults to the node's
+# Address the /admin/* server binds to. Defaults to the node's
 # cluster-reachable IP so cube-lifecycle-manager (running on the control
 # node) can push meta / state updates here. Token auth via
 # $cube_admin_token below prevents outside abuse; operators may further
 # tighten this with iptables / security groups.
 CUBE_PROXY_ADMIN_LISTEN="${CUBE_PROXY_ADMIN_LISTEN:-${CUBE_SANDBOX_NODE_IP}}"
+# Port the /admin/* server binds to. cube-proxy uses host networking, so this
+# has to be free on the node; override it when something else already holds
+# 8082. Kept at 8082 by default for backward compatibility.
+CUBE_PROXY_ADMIN_PORT="${CUBE_PROXY_ADMIN_PORT:-8082}"
 
 # Address of cube-lifecycle-manager reachable from this cube-proxy replica.
 # Consumed by the Lua $cube_sidecar_addr variable used by the
@@ -93,8 +97,8 @@ CUBE_ADMIN_TOKEN="${CUBE_ADMIN_TOKEN:-}"
 # ── CubeProxy service registration for cube-lifecycle-manager discovery ──
 # Enabled by default now that CLM owns lifecycle coordination.
 CUBE_PROXY_REGISTRY_ENABLE="${CUBE_PROXY_REGISTRY_ENABLE:-1}"
-CUBE_PROXY_ID="${CUBE_PROXY_ID:-${CUBE_SANDBOX_NODE_IP}:8082}"
-CUBE_PROXY_ADMIN_URL="${CUBE_PROXY_ADMIN_URL:-http://${CUBE_SANDBOX_NODE_IP}:8082}"
+CUBE_PROXY_ID="${CUBE_PROXY_ID:-${CUBE_SANDBOX_NODE_IP}:${CUBE_PROXY_ADMIN_PORT}}"
+CUBE_PROXY_ADMIN_URL="${CUBE_PROXY_ADMIN_URL:-http://${CUBE_SANDBOX_NODE_IP}:${CUBE_PROXY_ADMIN_PORT}}"
 CUBE_PROXY_RESUME_URL="${CUBE_PROXY_RESUME_URL:-${CUBE_PROXY_ADMIN_URL}}"
 CUBE_PROXY_NODE_IP="${CUBE_PROXY_NODE_IP:-${CUBE_SANDBOX_NODE_IP}}"
 CUBE_PROXY_VERSION="${CUBE_PROXY_VERSION:-}"
@@ -176,6 +180,7 @@ render_template_atomic \
   -e "s/__CUBE_PROXY_HTTP_PORT__/$(escape_sed "${CUBE_PROXY_HTTP_PORT}")/g" \
   -e "s/__CUBE_PROXY_GRPC_PORT__/$(escape_sed "${CUBE_PROXY_GRPC_PORT}")/g" \
   -e "s/__CUBE_PROXY_ADMIN_LISTEN__/$(escape_sed "${CUBE_PROXY_ADMIN_LISTEN}")/g" \
+  -e "s/__CUBE_PROXY_ADMIN_PORT__/$(escape_sed "${CUBE_PROXY_ADMIN_PORT}")/g" \
   -e "s/__CUBE_PROXY_SSL_CERT__/$(escape_sed "${CUBE_PROXY_SSL_CERT}")/g" \
   -e "s/__CUBE_PROXY_SSL_KEY__/$(escape_sed "${CUBE_PROXY_SSL_KEY}")/g"
 
@@ -210,7 +215,7 @@ docker_rm_if_exists "${CUBE_PROXY_CONTAINER_NAME}"
 # cube-proxy uses network_mode: host, so HTTP/HTTPS ports must be free on the
 # host before we attempt to start the container; otherwise the failure mode is
 # a cryptic "address already in use" from nginx inside the container.
-for port in "${CUBE_PROXY_HTTP_PORT}" "${CUBE_PROXY_HTTPS_PORT}" "${CUBE_PROXY_GRPC_PORT}"; do
+for port in "${CUBE_PROXY_HTTP_PORT}" "${CUBE_PROXY_HTTPS_PORT}" "${CUBE_PROXY_GRPC_PORT}" "${CUBE_PROXY_ADMIN_PORT}"; do
   if command_output_contains_fixed_string "LISTEN" ss -lnt "( sport = :${port} )"; then
     die "port ${port} is already in use; cube-proxy uses host networking and requires it to be free"
   fi

@@ -5,6 +5,7 @@ source "${SCRIPT_DIR}/common.sh"
 
 postcheck_port="${CUBE_PROXY_HTTP_PORT:-80}"
 postcheck_grpc_port="${CUBE_PROXY_GRPC_PORT:-9090}"
+postcheck_admin_port="${CUBE_PROXY_ADMIN_PORT:-8082}"
 postcheck_retries="${CUBE_PROXY_POSTCHECK_RETRIES:-30}"
 postcheck_delay="${CUBE_PROXY_POSTCHECK_DELAY:-2}"
 deprecated_host_port="${CUBE_PROXY_HOST_PORT:-}"
@@ -17,3 +18,8 @@ log "checking cube-proxy HTTP tcp port ${postcheck_port}"
 wait_for_tcp_port "${postcheck_port}" "${postcheck_retries}" "${postcheck_delay}" || die "cube-proxy HTTP tcp port not ready: ${postcheck_port}"
 log "checking cube-proxy gRPC tcp port ${postcheck_grpc_port}"
 wait_for_tcp_port "${postcheck_grpc_port}" "${postcheck_retries}" "${postcheck_delay}" || die "cube-proxy gRPC tcp port not ready: ${postcheck_grpc_port}"
+# The admin listener is what cube-lifecycle-manager drives for pause/resume.
+# Without this check nginx can fail to bind it while the public ports come up
+# fine, leaving the service "healthy" but lifecycle operations broken.
+log "checking cube-proxy admin tcp port ${postcheck_admin_port}"
+wait_for_tcp_port "${postcheck_admin_port}" "${postcheck_retries}" "${postcheck_delay}" || die "cube-proxy admin tcp port not ready: ${postcheck_admin_port}"
@@ -648,13 +648,13 @@ EOF
 				-e 's|^\(\s*listen \)9090\( http2 reuseport;\)|\1__CUBE_PROXY_GRPC_PORT__\2|' \
 				-e 's|^\(\s*set \$host_proxy_port \)8081;|\1__CUBE_PROXY_HTTP_PORT__;|' \
 				-e 's|^\(\s*set \$host_proxy_port \)8080;|\1__CUBE_PROXY_HTTPS_PORT__;|' \
-				-e 's|^\(\s*listen \)127\.0\.0\.1:8082;|\1__CUBE_PROXY_ADMIN_LISTEN__:8082;|' \
+				-e 's|^\(\s*listen \)127\.0\.0\.1:8082;|\1__CUBE_PROXY_ADMIN_LISTEN__:__CUBE_PROXY_ADMIN_PORT__;|' \
 				-e 's|/usr/local/openresty/nginx/certs/cube\.app+3\.pem|/usr/local/openresty/nginx/certs/__CUBE_PROXY_SSL_CERT__|' \
 				-e 's|/usr/local/openresty/nginx/certs/cube\.app+3-key\.pem|/usr/local/openresty/nginx/certs/__CUBE_PROXY_SSL_KEY__|' \
 				"${src}"
 		} >"${dst}"
 		local token
-		for token in __CUBE_PROXY_HTTP_PORT__ __CUBE_PROXY_HTTPS_PORT__ __CUBE_PROXY_GRPC_PORT__ __CUBE_PROXY_ADMIN_LISTEN__ __CUBE_PROXY_SSL_CERT__ __CUBE_PROXY_SSL_KEY__; do
+		for token in __CUBE_PROXY_HTTP_PORT__ __CUBE_PROXY_HTTPS_PORT__ __CUBE_PROXY_GRPC_PORT__ __CUBE_PROXY_ADMIN_LISTEN__ __CUBE_PROXY_ADMIN_PORT__ __CUBE_PROXY_SSL_CERT__ __CUBE_PROXY_SSL_KEY__; do
 			if ! grep -q -F "${token}" "${dst}"; then
 				rm -f "${dst}"
 				echo -e "  ${RED}✗ cube-proxy nginx template is missing ${token}; upstream CubeProxy/nginx.conf may have changed${NC}" >&2
@@ -687,7 +687,7 @@ http {
     location / { return 404; }
   }
   server {
-    listen __CUBE_PROXY_ADMIN_LISTEN__:8082;
+    listen __CUBE_PROXY_ADMIN_LISTEN__:__CUBE_PROXY_ADMIN_PORT__;
     server_name _;
     location / { return 404; }
   }

@@ -100,7 +100,7 @@ locals {
                       location / { return 404; }
                     }
                     server {
-                      listen __CUBE_PROXY_ADMIN_LISTEN__:8082;
+                      listen __CUBE_PROXY_ADMIN_LISTEN__:__CUBE_PROXY_ADMIN_PORT__;
                       server_name _;
                       location / { return 404; }
                     }
@@ -122,8 +122,8 @@ locals {
       "__CUBE_PROXY_SSL_KEY__",
       "cube.app+3-key.pem"
     ),
-    "__CUBE_PROXY_ADMIN_LISTEN__:8082",
-    "0.0.0.0:8082"
+    "__CUBE_PROXY_ADMIN_LISTEN__:__CUBE_PROXY_ADMIN_PORT__",
+    "0.0.0.0:${var.cube_proxy_admin_port}"
   )
 
   # Precondition for creating the TKE addons
@@ -1020,7 +1020,7 @@ resource "kubernetes_deployment" "cube_proxy" {
           }
           port {
             name           = "admin"
-            container_port = 8082
+            container_port = var.cube_proxy_admin_port
             protocol       = "TCP"
           }
           env {
@@ -1066,11 +1066,11 @@ resource "kubernetes_deployment" "cube_proxy" {
           }
           env {
             name  = "CUBE_PROXY_ADMIN_URL"
-            value = "http://$(POD_IP):8082"
+            value = "http://$(POD_IP):${var.cube_proxy_admin_port}"
           }
           env {
             name  = "CUBE_PROXY_RESUME_URL"
-            value = "http://$(POD_IP):8082"
+            value = "http://$(POD_IP):${var.cube_proxy_admin_port}"
           }
           env {
             name  = "CUBE_PROXY_NODE_IP"

@@ -377,6 +377,17 @@ variable "cube_proxy_replicas" {
   }
 }
 
+variable "cube_proxy_admin_port" {
+  description = "Port cube-proxy's /admin/* server listens on. cube-proxy uses host networking, so this must be free on the node; override it when something else already holds 8082."
+  type        = number
+  default     = 8082
+
+  validation {
+    condition     = var.cube_proxy_admin_port >= 1 && var.cube_proxy_admin_port <= 65535 && floor(var.cube_proxy_admin_port) == var.cube_proxy_admin_port
+    error_message = "cube_proxy_admin_port must be an integer between 1 and 65535."
+  }
+}
+
 variable "cube_lifecycle_manager_replicas" {
   description = "cube-lifecycle-manager Deployment replica count. Keep 1 unless CLM HA behavior has been validated for the target deployment."
   type        = number

@@ -153,17 +153,75 @@ test_cubeproxy_nginx_template_generation() {
     -e 's|^\(\s*listen \)8080\( ssl reuseport;\)|\1__CUBE_PROXY_HTTPS_PORT__\2|' \
     -e 's|^\(\s*set \$host_proxy_port \)8081;|\1__CUBE_PROXY_HTTP_PORT__;|' \
     -e 's|^\(\s*set \$host_proxy_port \)8080;|\1__CUBE_PROXY_HTTPS_PORT__;|' \
-    -e 's|^\(\s*listen \)127\.0\.0\.1:8082;|\1__CUBE_PROXY_ADMIN_LISTEN__:8082;|' \
+    -e 's|^\(\s*listen \)127\.0\.0\.1:8082;|\1__CUBE_PROXY_ADMIN_LISTEN__:__CUBE_PROXY_ADMIN_PORT__;|' \
     -e 's|/usr/local/openresty/nginx/certs/cube\.app+3\.pem|/usr/local/openresty/nginx/certs/__CUBE_PROXY_SSL_CERT__|' \
     -e 's|/usr/local/openresty/nginx/certs/cube\.app+3-key\.pem|/usr/local/openresty/nginx/certs/__CUBE_PROXY_SSL_KEY__|' \
     "${src}" >"${tmp}"
 
-  for token in __CUBE_PROXY_HTTP_PORT__ __CUBE_PROXY_HTTPS_PORT__ __CUBE_PROXY_ADMIN_LISTEN__ __CUBE_PROXY_SSL_CERT__ __CUBE_PROXY_SSL_KEY__; do
+  for token in __CUBE_PROXY_HTTP_PORT__ __CUBE_PROXY_HTTPS_PORT__ __CUBE_PROXY_ADMIN_LISTEN__ __CUBE_PROXY_ADMIN_PORT__ __CUBE_PROXY_SSL_CERT__ __CUBE_PROXY_SSL_KEY__; do
     grep -q -F "${token}" "${tmp}" || fail "cube-proxy nginx template generation is missing ${token}; CubeProxy/nginx.conf may have changed"
   done
+
+  # Round-trip the second half too: bundle-time templating is only useful if
+  # install-time substitution (up-cube-proxy.sh) renders a real listen
+  # directive from it. Use a non-default admin port so a regression that
+  # reintroduces a hardcoded 8082 fails here.
+  local rendered
+  rendered="$(sed \
+    -e 's/__CUBE_PROXY_ADMIN_LISTEN__/10.0.0.7/g' \
+    -e 's/__CUBE_PROXY_ADMIN_PORT__/9082/g' \
+    "${tmp}")"
+  grep -q -F 'listen 10.0.0.7:9082;' <<<"${rendered}" \
+    || fail "rendering the nginx template with CUBE_PROXY_ADMIN_PORT=9082 did not produce 'listen 10.0.0.7:9082;'"
+  # Match the listen directive specifically — nginx.conf also mentions the
+  # default admin address in a comment, which is not a binding.
+  if grep -q -E '^[[:space:]]*listen[[:space:]]+127\.0\.0\.1:8082;' <<<"${rendered}"; then
+    fail "rendered nginx.conf still binds the admin listener to a hardcoded 127.0.0.1:8082"
+  fi
+
   rm -f "${tmp}"
 }
 
+# 3c-bis) CubeProxy runs with host networking, so its admin listener must be
+#     movable off 8082 the same way the HTTP/HTTPS/gRPC ports already are.
+#     A hardcoded 8082 makes the whole control target fail to start with a
+#     bare "bind() ... (98: Address in use)" whenever anything else on the
+#     node holds that port. The generated nginx template, the discovery URLs
+#     CLM reads, the pre-start port check and the systemd postcheck must all
+#     agree on one configurable value.
+test_cubeproxy_admin_port_configurable() {
+  local postcheck="${ONE_CLICK_DIR}/scripts/systemd/cube-proxy-postcheck.sh"
+
+  grep -q -E 'CUBE_PROXY_ADMIN_PORT="\$\{CUBE_PROXY_ADMIN_PORT:-8082\}"' "${CUBE_PROXY_UP}" \
+    || fail "up-cube-proxy.sh does not define CUBE_PROXY_ADMIN_PORT with a backward-compatible 8082 default"
+
+  grep -q -F '__CUBE_PROXY_ADMIN_PORT__' "${CUBE_PROXY_UP}" \
+    || fail "up-cube-proxy.sh does not substitute the __CUBE_PROXY_ADMIN_PORT__ nginx placeholder"
+
+  # The discovery endpoints CLM resolves must follow the configured port,
+  # otherwise a moved admin listener registers an unreachable admin_url.
+  grep -q -F 'CUBE_PROXY_ID="${CUBE_PROXY_ID:-${CUBE_SANDBOX_NODE_IP}:${CUBE_PROXY_ADMIN_PORT}}"' "${CUBE_PROXY_UP}" \
+    || fail "CUBE_PROXY_ID still hardcodes the admin port"
+  grep -q -F 'CUBE_PROXY_ADMIN_URL="${CUBE_PROXY_ADMIN_URL:-http://${CUBE_SANDBOX_NODE_IP}:${CUBE_PROXY_ADMIN_PORT}}"' "${CUBE_PROXY_UP}" \
+    || fail "CUBE_PROXY_ADMIN_URL still hardcodes the admin port"
+
+  # Pre-start conflict detection: the admin port must be checked alongside
+  # the public ports so a conflict dies with a clear message here instead of
+  # inside the container.
+  grep -q -F '"${CUBE_PROXY_HTTP_PORT}" "${CUBE_PROXY_HTTPS_PORT}" "${CUBE_PROXY_GRPC_PORT}" "${CUBE_PROXY_ADMIN_PORT}"' "${CUBE_PROXY_UP}" \
+    || fail "up-cube-proxy.sh does not preflight the admin port for conflicts"
+
+  [[ -f "${postcheck}" ]] || { fail "cube-proxy postcheck missing: ${postcheck}"; return; }
+  grep -q -F 'CUBE_PROXY_ADMIN_PORT' "${postcheck}" \
+    || fail "cube-proxy-postcheck.sh does not verify the admin listener came up"
+
+  grep -q -F 'CUBE_PROXY_ADMIN_PORT' "${ONE_CLICK_DIR}/env.example" \
+    || fail "env.example does not document CUBE_PROXY_ADMIN_PORT"
+
+  grep -q -F '__CUBE_PROXY_ADMIN_PORT__' "${BUNDLE_SH}" \
+    || fail "build-release-bundle.sh does not emit the __CUBE_PROXY_ADMIN_PORT__ placeholder"
+}
+
 # 3d) one-click cube-proxy logs must use the same host-visible /data/log
 #     contract as the Kubernetes deployment and the other runtime components.
 test_cubeproxy_host_log_wiring() {
@@ -271,6 +329,7 @@ test_component_build_inputs_exist
 test_image_names_match
 test_webui_nginx_placeholders
 test_cubeproxy_nginx_template_generation
+test_cubeproxy_admin_port_configurable
 test_cubeproxy_host_log_wiring
 test_tke_addons_network_config_key
 test_reinstall_cleanup_tracks_packaged_components