fix(review): env alias compat, stream hardening, small-host guardrails, docs + 1.6.0

- Phase 1: DISABLE_TOOLS legacy alias via shared normalizeBool/resolveDisableTools (canonical > legacy > file > default, invalid falls through); tests/env-alias.test.js
- Phase 2: compose RETRY/BIND_HOST/OPENCODE_DISABLE_TOOLS passthrough, mem/cpu/pids limits, log rotation, start_period 200s; Dockerfile RETRY default; entrypoint backend wait ~180s
- Phase 3: responses/chat/messages preflight + non-stream prompt bounded by withTimeout (Request timeout -> 504); responses stream early SSE headers + heartbeat + res-based disconnect cancel; promptWithTimeout unified; tests/stream-hardening.test.js
- Phase 4: docs (docker/configuration), CHANGELOG 1.6.0 with Breaking section, version badges 1.6.0

Author: samson910022

.env.example

@@ -25,6 +25,7 @@ OPENCODE_PROXY_CLEANUP_MAX_AGE_MS=86400000
 # Optional overrides
 # OPENCODE_PROXY_PORT=10000
 # OPENCODE_SERVER_PORT=10001
+# BIND_HOST=0.0.0.0
 # OPENCODE_USE_ISOLATED_HOME=false
 # OPENCODE_PROXY_REQUEST_TIMEOUT_MS=180000
 # Retry budget after the initial attempt (0-5, default 3; total attempts = 1+n)

CHANGELOG.md

@@ -28,6 +28,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **后端错误透出**：`/v1/responses` 在后端 session 失败时曾 `throw` 纯对象，经 `transformUpstreamError` 被洗成 `500 Internal server error / code Object`、真实讯息丢失。新增 `normalizeBackendError`（纯对象→Error，保留 `data.message`/`name`/状态码推断），两处 `throw polled.error` 改用它；`transformUpstreamError` 纵深加固（默认分支改读 `data.message`/`name`，code 默认 `upstream_error` 不再用 `constructor.name`）。现 Credits 类错误正确回 `402 insufficient_quota` 并携带原文。新增 `tests/backend-error-surface.test.js`（4 例复现 LiteLLM 案例，含 messages）。
 - **同族错误路径查漏**：responses 串流 idleTimeout 补 poll 失败检查（不再静默回空 `completed`）；messages 非串流改用 transformed `status/type/code`（不再硬编码 `502/api_error`）；messages 串流检查 `collected.error` 与 poll 失败（失败即抛正規化错误走 SSE error 事件，不再静默 200）；`isTransientUpstreamError` 纳入 `name/code/type` 参与签名匹配（无 message 纯对象不再必判 false）。
 
+## [1.6.0] - 2026-09-08
+
+### ⚠️ Breaking / 行為變更
+
+- **`DISABLE_TOOLS=false` 從被忽略變為真正生效**：舊版只讀 `OPENCODE_DISABLE_TOOLS`，經 compose/`.env` 設 `DISABLE_TOOLS=false` 的用戶實際跑的是預設 `true`（工具禁用）。本版起該別名正式生效，升級後工具會真正啟用並可執行後端操作。要保持禁用請顯式設 `DISABLE_TOOLS=true`（或改用 `OPENCODE_DISABLE_TOOLS=true`）或刪行回預設。
+- **串流錯誤語義（僅 `/v1/responses` 改變傳輸形態）**：`stream:true` 的 `/v1/responses` 在 headers 已 flush（早於 preflight）之後出錯時，改經 SSE `response.failed` 事件 + `data: [DONE]` 回報（HTTP 狀態固定為 200）。`/v1/chat/completions` 串流維持原形態（`data: {"error":…}` 後結束），`/v1/messages` 串流維持 `error` 事件後結束（無 `[DONE]`）；且 chat/messages 的 preflight 失敗仍在 headers 送出前發生，故仍回 JSON 狀態碼（行為不變）。只看 HTTP 狀態碼的 responses 串流客戶端請改為同時監聽流內 `response.failed`；`stream:false` 的 JSON 狀態碼語義三路由皆不變（含超時 → `504`）。
+
+### Added
+
+- **Docker 多架构发布**：`ghcr.io/samson910022/opencode2api:latest` 同时推送 `linux/amd64` + `linux/arm64`（此前已上线但未记入 changelog；ARM 机器可直接 pull，无需本地 build）。
+- **环境变量兼容别名**：`docker-compose`/`.env` 沿用的 `DISABLE_TOOLS` 正式生效（此前只有 `OPENCODE_DISABLE_TOOLS` 被读取）。解析收敛到共用的 `normalizeBool` + `resolveDisableTools`（无效值让位：canonical env > legacy env > `config.json` > 默认；數字僅 `0/1` 有效，其餘視為未設），`index.js` 直接調用同一 helper 不再手寫 `??` 鏈，附 `tests/env-alias.test.js`。
+- **串流强健（responses/chat/messages 三路由）**：串流 `/v1/responses` 在 preflight 等待前即 flush SSE 头 + 15s heartbeat（中转不再看到零字节 stall；chat/messages 的 headers 仍在 preflight 之後送出，其 preflight 失敗維持 JSON 狀態碼）；三路由的 `resolve/session/tool-overrides` preflight 與非串流 `prompt` 全部经 `withTimeout` 限界（真错误立即透出，超时经 `Request timeout` 映射為 `504`）；客户端断开经 `res 'close'` + `!writableEnded` 取消并清理 session（`req 'close'` 在 body 解析完即觸發，不可用）；`promptWithTimeout` 統一改調 `withTimeout`（舊 inline race 洩漏 timer 且晚拒絕可致 unhandled rejection）。附 `tests/stream-hardening.test.js`。
+- **小机部署加固（可調）**：compose 加 `mem_limit 768m`/`mem_reservation 256m`/`cpus 1.5`/`pids_limit 256`、日志轮转、`start_period 200s`，补 `OPENCODE_PROXY_RETRY_MAX_RETRIES`/`BIND_HOST`/`OPENCODE_DISABLE_TOOLS` 透传；`Dockerfile` 补 `RETRY` 默认；entrypoint 后端等待 30s→约 180s（覆盖小机冷启动）。`mem_limit` 是部署行為變更（非 API breaking）：此前無上限只會變慢，現超限會被 OOM kill；大機請用 `docker-compose.override.yml` 放寬（見 `docs/docker.md`「覆寫資源限制」）。
+
+### Fixed
+
+- **`DISABLE_TOOLS=false` 被静默忽略**：见上 Breaking（生产默认仍为 `true`，只在显式设 `false`/别名时行为变化）。
+- **断线侦测误用 `req 'close'`**：server 端该事件在请求体解析完即触发（实测 +1ms），不能用于串流断线；改用 `res 'close'` + `!writableEnded`（`/v1/messages` 旧 pattern 因监听挂得晚而等于失效，一并修复；監聽器改 `once` 避免殘留）。
+- **`withTimeout` 超時誤回 500**：超時訊息現為 `Request timeout after …(label)`，可被 `transformUpstreamError` 正確映射為 `504`（此前自訂訊息繞過映射）；`createApp` 補 `REQUEST_TIMEOUT_MS` 預設，非有限值回退到 `DEFAULT_REQUEST_TIMEOUT_MS`。
+- **`BIND_HOST` 命名分裂**：`startProxy` 後備鏈與 `index.js` 合併皆支援 `BIND_HOST` 優先、`OPENCODE_PROXY_BIND_HOST` 後備（此前 `startProxy` 只有後者，經正常 `index.js` 路徑時後備不可達）。
+- **文件範例收斂（非 breaking）**：`docs/docker.md` 的 `docker run` 範例刪除 `-p 10001:10001`（後端僅容器內部使用；運行時無變更，舊映射仍可用，建議改走代理端口）。
+
 ## [1.5.0] - 2026-04-18
 
 ### Added

Dockerfile

@@ -41,6 +41,7 @@ ENV OPENCODE_PROXY_AUTO_CLEANUP_CONVERSATIONS=false
 ENV OPENCODE_PROXY_CLEANUP_INTERVAL_MS=43200000
 ENV OPENCODE_PROXY_CLEANUP_MAX_AGE_MS=86400000
 ENV OPENCODE_PROXY_REQUEST_TIMEOUT_MS=180000
+ENV OPENCODE_PROXY_RETRY_MAX_RETRIES=3
 
 ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
 CMD ["opencode", "serve", "--hostname", "0.0.0.0", "--port", "10001"]

README.md

@@ -1,7 +1,7 @@
 # OpenCode2API
 
 <p align="center">
-  <img src="https://img.shields.io/badge/version-1.5.0-blue" alt="Version">
+  <img src="https://img.shields.io/badge/version-1.6.0-blue" alt="Version">
   <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
   <img src="https://img.shields.io/badge/Node.js-18+-orange" alt="Node">
 </p>

docker-compose.yml

@@ -13,8 +13,9 @@ services:
       - OPENCODE_SERVER_PASSWORD=${OPENCODE_SERVER_PASSWORD:-}
       - OPENCODE_ZEN_API_KEY=${OPENCODE_ZEN_API_KEY:-}
       - API_KEY=${API_KEY:-}
-      - BIND_HOST=0.0.0.0
+      - BIND_HOST=${BIND_HOST:-0.0.0.0}
       - DISABLE_TOOLS=${DISABLE_TOOLS:-true}
+      - OPENCODE_DISABLE_TOOLS=${OPENCODE_DISABLE_TOOLS:-}
       - OPENCODE_USE_ISOLATED_HOME=${OPENCODE_USE_ISOLATED_HOME:-false}
       - OPENCODE_PROXY_DEBUG=${OPENCODE_PROXY_DEBUG:-false}
       - OPENCODE_PROXY_PROMPT_MODE=${OPENCODE_PROXY_PROMPT_MODE:-standard}
@@ -23,18 +24,36 @@ services:
       - OPENCODE_PROXY_CLEANUP_INTERVAL_MS=${OPENCODE_PROXY_CLEANUP_INTERVAL_MS:-43200000}
       - OPENCODE_PROXY_CLEANUP_MAX_AGE_MS=${OPENCODE_PROXY_CLEANUP_MAX_AGE_MS:-86400000}
       - OPENCODE_PROXY_REQUEST_TIMEOUT_MS=${OPENCODE_PROXY_REQUEST_TIMEOUT_MS:-180000}
+      - OPENCODE_PROXY_RETRY_MAX_RETRIES=${OPENCODE_PROXY_RETRY_MAX_RETRIES:-3}
       - OPENCODE_PROXY_PORT=${OPENCODE_PROXY_PORT:-10000}
       - OPENCODE_SERVER_PORT=${OPENCODE_SERVER_PORT:-10001}
     volumes:
       - opencode-data:/home/node/.local/share/opencode
       - opencode-config:/home/node/.config/opencode
     restart: unless-stopped
+    # Guard small (1GB) hosts: cap memory/CPU so one slow request cannot wedge
+    # the whole machine (see docs/host-deployments.md §9). Raw `docker run`
+    # hosts should pass the equivalents: --memory=768m --memory-reservation=256m
+    # --cpus=1.5 --pids-limit=256.
+    mem_limit: 768m
+    mem_reservation: 256m
+    cpus: 1.5
+    pids_limit: 256
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
     healthcheck:
+      # Shallow on purpose: /health needs no auth; /health/details would 401
+      # when HEALTH_DETAILS_REQUIRE_AUTH=true and has no credentials here.
       test: ["CMD", "curl", "-f", "http://localhost:${OPENCODE_PROXY_PORT:-10000}/health"]
       interval: 30s
       timeout: 10s
       retries: 3
-      start_period: 60s
+      # Must cover entrypoint backend wait (~180s on cold small hosts) plus
+      # probe intervals; 120s flapped unhealthy during normal warmup.
+      start_period: 200s
 
 volumes:
   opencode-data:

docs/README.md

@@ -1,7 +1,7 @@
 # OpenCode2API 文档中心
 
 <p align="center">
-  <img src="https://img.shields.io/badge/version-1.5.0-blue" alt="Version">
+  <img src="https://img.shields.io/badge/version-1.6.0-blue" alt="Version">
 </p>
 
 > 欢迎查看 OpenCode2API 文档

docs/api-reference.md

@@ -1,7 +1,7 @@
 # 🔌 API 参考
 
 <p align="center">
-  <img src="https://img.shields.io/badge/version-1.5.0-blue" alt="Version">
+  <img src="https://img.shields.io/badge/version-1.6.0-blue" alt="Version">
 </p>
 
 ---

docs/configuration.md

@@ -1,7 +1,7 @@
 # ⚙️ 配置详解
 
 <p align="center">
-  <img src="https://img.shields.io/badge/version-1.5.0-blue" alt="Version">
+  <img src="https://img.shields.io/badge/version-1.6.0-blue" alt="Version">
 </p>
 
 ---
@@ -21,15 +21,15 @@
 | `PORT` / `OPENCODE_PROXY_PORT` | `10000` | 代理服务端口 |
 | `OPENCODE_SERVER_PORT` | `10001` | OpenCode 后端服务端口 |
 | `API_KEY` | - | Bearer Token 认证密钥 |
-| `BIND_HOST` | `0.0.0.0` | 绑定地址 |
+| `BIND_HOST` | `0.0.0.0` | 绑定地址（`BIND_HOST` 优先，`OPENCODE_PROXY_BIND_HOST` 为后备） |
 | `OPENCODE_SERVER_URL` | `http://127.0.0.1:10001` | OpenCode 后端地址 |
 | `OPENCODE_SERVER_PASSWORD` | - | OpenCode 后端密码 |
 
 ### 功能配置
 
 | 变量 | 默认值 | 说明 |
 |:-----|:-------|:-----|
-| `DISABLE_TOOLS` | `true` | 禁用 OpenCode 工具调用 |
+| `DISABLE_TOOLS` | `true` | 禁用 OpenCode 工具调用（兼容别名；`OPENCODE_DISABLE_TOOLS` 优先，二者无效值都会让位给下一顺位：canonical env > legacy env > `config.json` > 默认） |
 | `OPENCODE_EXTERNAL_TOOLS_MODE` | `proxy-bridge` | 外部工具桥接模式；当前仅支持 `proxy-bridge` |
 | `OPENCODE_EXTERNAL_TOOLS_CONFLICT_POLICY` | `namespace` | 外部工具冲突隔离策略；当前仅支持 `namespace` |
 | `OPENCODE_INTERNAL_WEB_FETCH_ENABLED` | `false` | 兼容旧开关；未显式配置 allowlist 时，启用后默认放行 `web_fetch` |

docs/development.md

@@ -1,7 +1,7 @@
 # 💻 开发指南
 
 <p align="center">
-  <img src="https://img.shields.io/badge/version-1.5.0-blue" alt="Version">
+  <img src="https://img.shields.io/badge/version-1.6.0-blue" alt="Version">
 </p>
 
 ---

docs/docker.md

@@ -1,7 +1,7 @@
 # 🐳 Docker 部署
 
 <p align="center">
-  <img src="https://img.shields.io/badge/version-1.5.0-blue" alt="Version">
+  <img src="https://img.shields.io/badge/version-1.6.0-blue" alt="Version">
 </p>
 
 ---
@@ -83,53 +83,44 @@ docker build -t my-opencode2api .
 ```bash
 docker run -d \
   -p 10000:10000 \
-  -p 10001:10001 \
   -e API_KEY=your-key \
   -e OPENCODE_SERVER_PASSWORD=your-password \
   -v opencode-data:/home/node/.local/share/opencode \
   -v opencode-config:/home/node/.config/opencode \
   my-opencode2api
 ```
 
----
+> 后端 `10001` 仅容器内部使用，不要对外发布（compose 默认也只映射代理端口；改端口用 `OPENCODE_PROXY_PORT`，如 `8090`）。
+
+### 多架构
 
-## 📝 生产部署建议
+`ghcr.io/samson910022/opencode2api:latest` 同时含 `linux/amd64` 与 `linux/arm64`，ARM 机器可直接 pull，无需本地 build（仅自带 `custom-bin/opencode` 二进制时才需按架构重建）。
 
-### 移除源码挂载
+### 覆寫資源限制
 
-如果不需要在容器内修改代码，可以移除项目目录的挂载:
+compose 預設 `mem_limit 768m`（單容器含 proxy＋後端）。大機要放寬或取消，用 override 檔：
 
 ```yaml
-# docker-compose.yml
-volumes:
-  - opencode-data:/home/node/.local/share/opencode
-  - opencode-config:/home/node/.config/opencode
-  # 移除这一行
-  # - .:/home/node/project
+# docker-compose.override.yml
+services:
+  opencode2api:
+    mem_limit: 2g
+    mem_reservation: 512m
+    cpus: 4.0
 ```
 
 ---
 
 ## 📊 日志管理
 
+compose 已内置 json-file 轮转（`max-size: 10m`、`max-file: 3`）；裸 `docker run` 请自行加上 `--log-opt max-size=10m --log-opt max-file=3`。
+
 ### 查看日志
 
 ```bash
 docker compose logs -f
 ```
 
-### 日志轮转
-
-推荐使用 Docker 的日志驱动配置:
-
-```yaml
-logging:
-  driver: "json-file"
-  options:
-    max-size: "10m"
-    max-file: "3"
-```
-
 ---
 
 ## ✅ 健康检查
@@ -138,13 +129,15 @@ logging:
 
 ```yaml
 healthcheck:
-  test: ["CMD", "curl", "-f", "http://localhost:10000/health"]
+  test: ["CMD", "curl", "-f", "http://localhost:${OPENCODE_PROXY_PORT:-10000}/health"]
   interval: 30s
   timeout: 10s
   retries: 3
-  start_period: 60s
+  start_period: 200s
 ```
 
+> `/health` 是浅检查（只确认代理活着，不测后端；`start_period` 200s 覆盖 entrypoint 约 180s 的小机冷启动等待）。小机（1GB）另有 `mem_limit 768m` / `pids_limit 256` 保护，裸 `docker run` 请加等价旗（见 `docker-compose.yml` 注释）。
+
 ---
 
 ## ❓ 常见问题