diff --git a/cmd/hwlab-cloud-api/main.mjs b/cmd/hwlab-cloud-api/main.mjs
index 6b19241e..38b43d3a 100644
--- a/cmd/hwlab-cloud-api/main.mjs
+++ b/cmd/hwlab-cloud-api/main.mjs
@@ -2,7 +2,7 @@
 import { createCloudApiServer } from "../../internal/cloud/server.mjs";
 
 const host = process.env.HWLAB_CLOUD_API_HOST || "0.0.0.0";
-const port = Number.parseInt(process.env.HWLAB_CLOUD_API_PORT || process.env.PORT || "6667", 10);
+const port = parsePort(process.env.HWLAB_CLOUD_API_PORT, parsePort(process.env.PORT, 6667));
 const commitId = process.env.HWLAB_COMMIT_ID || process.env.HWLAB_GIT_SHA;
 const codeAgentTimeoutMs = parseTimeout(process.env.HWLAB_CODE_AGENT_TIMEOUT_MS, 600000, {
   min: 1000,
@@ -32,6 +32,12 @@ function parseTimeout(value, fallback, { min, max }) {
   return Math.min(Math.max(parsed, min), max);
 }
 
+function parsePort(value, fallback) {
+  const parsed = Number.parseInt(value || "", 10);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed >= 65536) return fallback;
+  return parsed;
+}
+
 server.listen(port, host, () => {
   const address = server.address();
   const resolvedPort = typeof address === "object" && address ? address.port : port;
diff --git a/deploy/deploy.json b/deploy/deploy.json
index 20c45b15..bdac5595 100644
--- a/deploy/deploy.json
+++ b/deploy/deploy.json
@@ -189,6 +189,7 @@
       "env": {
         "HWLAB_ENVIRONMENT": "dev",
         "HWLAB_PUBLIC_ENDPOINT": "http://74.48.78.17:16667",
+        "HWLAB_CLOUD_API_PORT": "6667",
         "HWLAB_COMMIT_ID": "3ebbbbf",
         "HWLAB_IMAGE": "127.0.0.1:5000/hwlab/hwlab-cloud-api:3ebbbbf",
         "HWLAB_IMAGE_TAG": "3ebbbbf",
diff --git a/deploy/k8s/base/workloads.yaml b/deploy/k8s/base/workloads.yaml
index b2f719fc..d29e9341 100644
--- a/deploy/k8s/base/workloads.yaml
+++ b/deploy/k8s/base/workloads.yaml
@@ -47,6 +47,10 @@
                     "name": "HWLAB_PUBLIC_ENDPOINT",
                     "value": "http://74.48.78.17:16667"
                   },
+                  {
+                    "name": "HWLAB_CLOUD_API_PORT",
+                    "value": "6667"
+                  },
                   {
                     "name": "HWLAB_COMMIT_ID",
                     "value": "3ebbbbf"
diff --git a/docs/reference/deployment-publish.md b/docs/reference/deployment-publish.md
index fff9bc93..157d625e 100644
--- a/docs/reference/deployment-publish.md
+++ b/docs/reference/deployment-publish.md
@@ -183,6 +183,11 @@ node tools/hwlab-cli/bin/hwlab-cli.mjs cicd report <cd-job-id>
   Deployment，再由同一次 `kubectl apply -k deploy/k8s/dev` 从源码 desired-state
   重新创建；报告中记录 cleanup 计划和实际动作。不要把这种 cleanup 做成某个服务
   或某个 skill 的特例。
+- Kubernetes service links 会为同 namespace Service 自动注入形如
+  `HWLAB_CLOUD_API_PORT=tcp://...` 的环境变量。应用入口不得直接把这类 env 当作
+  数字端口解析；desired-state 应显式声明服务自身监听端口
+  `HWLAB_CLOUD_API_PORT=6667`，入口代码也必须只接受合法数值端口，否则回落到
+  内置默认值。
 
 ## DEV CD Transaction