diff --git a/.gitea/workflows/deploy.yml b/.gitea/workflows/deploy.yml
index 8a150e2..a16efa4 100644
--- a/.gitea/workflows/deploy.yml
+++ b/.gitea/workflows/deploy.yml
@@ -455,9 +455,27 @@ jobs:
               echo "Deploy dir   : ${DEPLOY_DIR}"
               echo "=============================================="
 
-              mkdir -p "${DEPLOY_DIR}"
+              mkdir -p "${DEPLOY_DIR}" 2>/dev/null || sudo mkdir -p "${DEPLOY_DIR}" 2>/dev/null || true
               cd "${DEPLOY_DIR}"
 
+              # ========== 目录可写性预检查（权限排查友好化） ==========
+              TEST_FILE="${DEPLOY_DIR}/.deploy_writable_test_$$"
+              if ! (touch "${TEST_FILE}" && rm -f "${TEST_FILE}") 2>/dev/null; then
+                echo "================================================================="
+                echo "ERROR：deploy 用户对部署目录 ${DEPLOY_DIR} 没有写权限（Permission denied）"
+                echo "当前用户：$(whoami)"
+                echo "目录归属与权限："
+                ls -ld "${DEPLOY_DIR}" || true
+                echo ""
+                echo "请在服务器上以 root 身份执行下面 3 行命令修复（复制粘贴）："
+                echo "  chown -R deploy:docker '${DEPLOY_DIR}'"
+                echo "  chmod 775 '${DEPLOY_DIR}'"
+                echo "  setfacl -R -m u:deploy:rwx -m g:docker:rwx -m d:u:deploy:rwx -m d:g:docker:rwx '${DEPLOY_DIR}' 2>/dev/null || true"
+                echo "修复后重新触发此 workflow 即可。"
+                echo "================================================================="
+                exit 3
+              fi
+
               if [ -n "${REGISTRY_PULL_TOKEN}" ] && [ -n "${REGISTRY_PULL_USER}" ]; then
                 echo "使用专用 pull 凭证登录 Gitea Container Registry"
                 printf '%s' "${REGISTRY_PULL_TOKEN}" \
@@ -471,11 +489,13 @@ jobs:
               docker tag  "${IMAGE_NEW}" "${IMAGE_LATEST}"
               echo "New image pulled and tagged as latest"
 
-              cat > docker-compose.override.yml <<YAML
+              # heredoc 分隔符用 COMPOSE_OVERRIDE，不能用 YAML（外层是 .yml 文件，YAML parser 会冲突）
+              # 注意：heredoc 内容和结束 COMPOSE_OVERRIDE 行必须保持同样的缩进（跟 run block 对齐），否则 YAML parser 会把 services: 当 YAML key 解析
+              cat > docker-compose.override.yml <<'COMPOSE_OVERRIDE'
               services:
                 voicehub:
                   image: ${IMAGE_NEW}
-              YAML
+              COMPOSE_OVERRIDE
               echo "docker-compose.override.yml written, image=${IMAGE_NEW}"
 
               if [ ! -f docker-compose.yml ]; then
@@ -492,7 +512,7 @@ jobs:
               if [ ! -f .env ]; then
                 echo "================================================================="
                 echo "WARNING：${DEPLOY_DIR}/.env 不存在"
-                echo "首次部署请在服务器上创建 .env（至少填写 POSTGRES_PASSWORD / JWT_SECRET / NUXT_PUBLIC_SITE_URL）"
+                echo "首次部署请在服务器上创建 .env（至少填写 POSTGRES_PASSWORD / JWT_SECRET / NUXT_PUBLIC_SITE_URL + 5 个 cpus 数字兜底：APP_CPUS/APP_CPUS_LIMIT/APP_CPUS_RESERVATION/PG_CPUS/REDIS_CPUS）"
                 echo "参考仓库根目录的 .env.example"
                 echo "================================================================="
               fi