fix(build): harden Windows Docker checkout and web port

Keep vendored extensionless build scripts on LF so Git for Windows cannot make their Linux shebangs unexecutable. Allow the Windows Compose web host port to be overridden without editing tracked files, and document both recovery paths.

Follow-up to the Windows 11 validation of #87.

Signed-off-by: Nquyen Cubas <nquyencubas523@gmail.com>

Author: nquyencubas523-cloud

.gitattributes

@@ -1,3 +1,7 @@
+# 第三方源码中的 configure 等无扩展名脚本也必须以 LF 进入 Linux 构建容器。
+3rd/**  text=auto eol=lf
+.gitattributes text eol=lf
+
 # 强制所有源代码文件使用 LF 换行符，防止 Windows 带入 CRLF
 *.cc    text eol=lf
 *.h     text eol=lf
@@ -21,6 +25,10 @@
 CMakeLists.txt text eol=lf
 Makefile       text eol=lf
 
+# Windows 原生批处理脚本保留 CRLF。
+*.bat   text eol=crlf
+*.cmd   text eol=crlf
+
 # 二进制文件不做转换
 *.bmodel binary
 *.onnx   binary

docker-compose.x86.windows.yml

@@ -10,7 +10,7 @@ services:
     init: true
     restart: unless-stopped
     ports:
-      - "8080:80"  # Use port 8080 to avoid conflicts with host port 80.
+      - "${COSMO_X86_WEB_PORT:-8080}:80"  # Override when Windows reserves host port 8080.
       - "1936:1936"
       - "1985:1985"
       - "18088:18088"

docs/en/guide/troubleshooting.md

@@ -59,7 +59,34 @@ The x86 Compose file publishes:
 - `18088`
 - `8000/udp`
 
-If a port is occupied, you can modify the host port in `docker-compose.x86.yml` (or `docker-compose.x86.windows.yml` on Windows), or stop the service that occupies the port.
+If a port is occupied, you can modify the host port in `docker-compose.x86.yml`, or stop the service that occupies the port.
+
+On Windows, Hyper-V / WSL can reserve a TCP port range. Docker may therefore report a bind failure even when `netstat` shows no listening process. Check the reserved ranges first:
+
+```powershell
+netsh interface ipv4 show excludedportrange protocol=tcp
+```
+
+`docker-compose.x86.windows.yml` accepts `COSMO_X86_WEB_PORT`, so you can change the web host port without editing a tracked file. For example, use `8280`:
+
+```powershell
+$env:COSMO_X86_WEB_PORT = "8280"
+docker compose -f docker-compose.x86.windows.yml up -d --build
+```
+
+Then open `http://127.0.0.1:8280`. The default remains `8080` when the variable is unset.
+
+## Windows Build Scripts Report `No such file or directory`
+
+If a Docker build reports that an existing `configure`, `config`, or `Configure` file cannot be executed, Git for Windows may have checked out the extensionless script with CRLF endings. The container then cannot parse its shebang.
+
+The root `.gitattributes` pins automatically detected text files, including these extensionless scripts, to LF. After pulling the latest rules, retry from a fresh clone or clean worktree with no uncommitted changes. Confirm the rules with:
+
+```powershell
+git check-attr text eol -- 3rd/mp4v2-2.0.0/configure 3rd/openssl-3.5.3/config 3rd/srs-6.0-r0/trunk/configure
+```
+
+All three files should report `text: auto` and `eol: lf`.
 
 ## No Release Package in `build_output/`
 

docs/guide/troubleshooting.md

@@ -59,7 +59,34 @@ x86 Compose 会发布：
 - `18088`
 - `8000/udp`
 
-如果端口被占用，可以修改 `docker-compose.x86.yml` (或 Windows 上的 `docker-compose.x86.windows.yml`) 的主机端口，或停止占用端口的服务。
+如果端口被占用，可以修改 `docker-compose.x86.yml` 的主机端口，或停止占用端口的服务。
+
+Windows 的 Hyper-V / WSL 可能保留一段 TCP 端口，即使 `netstat` 没显示监听进程，Docker 仍会报告端口绑定失败。可以先查看系统保留范围：
+
+```powershell
+netsh interface ipv4 show excludedportrange protocol=tcp
+```
+
+`docker-compose.x86.windows.yml` 支持通过 `COSMO_X86_WEB_PORT` 改 Web 主机端口，无需修改受版本控制的文件。例如使用 `8280`：
+
+```powershell
+$env:COSMO_X86_WEB_PORT = "8280"
+docker compose -f docker-compose.x86.windows.yml up -d --build
+```
+
+随后访问 `http://127.0.0.1:8280`。不设置该变量时仍默认使用 `8080`。
+
+## Windows 构建脚本提示 `No such file or directory`
+
+如果 Docker 构建在执行 `configure`、`config` 或 `Configure` 时报告文件存在但无法执行，通常是 Git for Windows 将无扩展名脚本检出为 CRLF，导致容器无法识别 shebang。
+
+仓库根目录的 `.gitattributes` 会把自动识别出的文本文件（包括这些无扩展名脚本）固定为 LF。拉取最新规则后，请在没有未保存修改的全新 clone 或干净 worktree 中重试。可以用以下命令确认规则：
+
+```powershell
+git check-attr text eol -- 3rd/mp4v2-2.0.0/configure 3rd/openssl-3.5.3/config 3rd/srs-6.0-r0/trunk/configure
+```
+
+三个文件都应显示 `text: auto` 和 `eol: lf`。
 
 ## `build_output/` 没有发布包