fix(deploy): HOST/PORT 在容器里生效 + compose 透传全部配置项

两处静默失效的配置陷阱：

1. Dockerfile CMD 硬编码 --host 0.0.0.0 --port 8000，config.py 里的
   HOST/PORT 只在本地 `python -m src.main` 生效。容器里改 PORT 只改端口
   映射、改 HOST 完全无效（文档化配置项却不管用）。
   → CMD 改走 src.main:run；实测 PORT=18231 时确实监听在 18231
2. compose 没有 env_file，.env 只用于 ${VAR} 插值、不注入容器。此前只透传
   10 个变量，ALLOWED_HOSTS / PACER_* / REFRESH_SKEW_HOURS / DUMP_REQUEST_BODIES
   / CODEBUDDY_ALLOWED_ENDPOINTS / CODEBUDDY_CHAT_MIN_INTERVAL / HOST / PORT /
   USERS_FILE / DATA_DIR 在 .env 里设了全部无效，且无任何报错。
   → 全部补齐（含注释说明为什么必须显式列出）

新增两个静态断言把这两类问题挡在 CI：compose 必须透传 config.py 的每个
字段；CMD 不得硬编码 --host/--port。README 指明 config.py 是权威清单。

前端：统计明细的失败列此前直接显示机器码（rate_limit 等），
现按 TECHNICAL §6.5 同一原则翻成中文，未知值兜底「失败（原值）」。

Author: RobbsLuo

Dockerfile

@@ -51,4 +51,6 @@ EXPOSE 8000
 HEALTHCHECK --interval=30s --timeout=5s --start-period=10s \
     CMD python -c "import urllib.request;urllib.request.urlopen('http://127.0.0.1:8000/health')"
 
-CMD ["python", "-m", "uvicorn", "src.main:build_app", "--factory", "--host", "0.0.0.0", "--port", "8000"]
+# CMD 走 src.main:run（而非硬编码 --host/--port）：HOST/PORT 是文档化配置项
+# （config.py + README），硬编码会让它们只对本地启动生效、在容器里静默失效。
+CMD ["python", "-m", "src.main"]

README.md

@@ -102,7 +102,9 @@ curl http://127.0.0.1:8000/v1/user/balance -H "Authorization: Bearer sk-你的ke
 
 ## 配置
 
-常用项如下，其余高级项（监听地址、上游端点白名单、节流、预刷新窗口、诊断转储等）见 `docker-compose.yml` 与 `src/config.py`。
+常用项如下；完整的可配置项见 `src/config.py`（权威），且**每一个都已透传到 `docker-compose.yml`**——`.env` 里写这些变量即可生效（compose 的 `.env` 只做插值，未透传的变量不会进容器）。
+
+> 容器里改监听地址用 `HOST`/`PORT`（`PORT` 同时决定宿主机映射端口），入口读 `config.py`，不硬编码。
 
 | 变量 | 默认 | 说明 |
 |---|---|---|

TECHNICAL.md

@@ -360,3 +360,8 @@ fixture 断言两个方向：**解析正确**（样本 → 期望 Event）与**
 - **手写 SQL 而非 ORM**：8 张表规模下 ORM 收益为负
 - **polling OAuth 不转回调**（Q17=C）：上游协议决定；TRAE 回调走主端口 + PUBLIC_BASE_URL
 - **v1 无 Anthropic**（Q8=A）：Event 层已预留，v1.1 只加 `compat/anthropic/` 适配器
+- **两套数据源共存（已知不一致）**：`overview` / `by_provider` 读 `usage_events`（即时，
+  仅覆盖 90 天明细），`timeline` / `model-timeline` 读 `usage_hourly`（≤5 分钟滞后，永久）。
+  时间范围 ≤90 天时两者一致（汇总由同一批明细算出）；选「全部」时总览会小于图表，
+  因为超过 90 天的明细已被清理、只剩小时汇总。修法已列入待办（把总览也切到小时表），
+  但会引入 ≤5 分钟延迟，待定。

docker-compose.yml

@@ -21,6 +21,29 @@ services:
       # 会话粘性 TTL（秒）：同一对话多轮请求固定用同一凭证；≤0 关闭
       CONVERSATION_STICKY_SECONDS: ${CONVERSATION_STICKY_SECONDS:-3600}
       LOG_LEVEL: ${LOG_LEVEL:-INFO}
+      # ---- 高级项：默认值已合适，需要时在 .env 里设即可生效 ----
+      # 注意：compose 的 .env 只用于 ${VAR} 插值，只有在这里透传过的变量
+      # 才会真正进容器；漏透传会让 .env 里的设置静默失效（无任何报错）。
+      # Host 白名单（防 DNS rebinding）；空 = 本地回环 + PUBLIC_BASE_URL 主机
+      ALLOWED_HOSTS: ${ALLOWED_HOSTS:-}
+      # 上游端点白名单（逗号分隔）；改 CODEBUDDY_API_ENDPOINT 时必须同时含它
+      CODEBUDDY_ALLOWED_ENDPOINTS: ${CODEBUDDY_ALLOWED_ENDPOINTS:-https://copilot.tencent.com,https://www.codebuddy.ai}
+      # CodeBuddy 聊天最小间隔（秒）：腾讯频率风控，0 关闭
+      CODEBUDDY_CHAT_MIN_INTERVAL: ${CODEBUDDY_CHAT_MIN_INTERVAL:-5}
+      # token 预刷新窗口（小时）
+      REFRESH_SKEW_HOURS: ${REFRESH_SKEW_HOURS:-24}
+      # 全局节流器随机区间（秒）
+      PACER_MIN_SECONDS: ${PACER_MIN_SECONDS:-5}
+      PACER_MAX_SECONDS: ${PACER_MAX_SECONDS:-20}
+      # 诊断：把 /v1 原始请求体落盘到 data/dumps/（含对话内容，仅排查用）
+      DUMP_REQUEST_BODIES: ${DUMP_REQUEST_BODIES:-false}
+      # 服务监听地址（容器内必须 0.0.0.0 才能被映射访问）
+      HOST: ${HOST:-0.0.0.0}
+      PORT: ${PORT:-8000}
+      # 用户文件路径（容器内固定挂载点，一般无需改）
+      USERS_FILE: ${USERS_FILE:-/app/secrets/users.txt}
+      # SQLite 与运行数据目录（容器内固定挂载点，一般无需改）
+      DATA_DIR: ${DATA_DIR:-/app/data}
     ports:
       - "${PORT:-8000}:8000"
     volumes:

tests/test_deployment_assets.py

@@ -107,6 +107,33 @@ def test_compose_publishes_same_port_as_dockerfile():
     assert f":{dockerfile_port.group(1)}" in COMPOSE.read_text(encoding="utf-8")
 
 
+def test_compose_forwards_every_settings_field():
+    """compose 必须透传 config.py 的每个可配置字段。
+
+    compose 的 .env 只用于 ${VAR} 插值，**不会**注入容器：没写进
+    environment 的变量在 .env 里设了也无效，而且完全无报错（静默失效）。
+    所以这里把两边对一遍，漏一个就抦住。
+    """
+    config_text = (ROOT / "src" / "config.py").read_text(encoding="utf-8")
+    fields = set(re.findall(r"^    ([a-z_]+):[^=\n]*=", config_text, re.MULTILINE))
+    # pydantic-settings 默认大小写不敏感，惯例上 env 全大写
+    expected = {name.upper() for name in fields}
+    compose_text = COMPOSE.read_text(encoding="utf-8")
+    forwarded = set(re.findall(r"^\s+([A-Z_]+):", compose_text, re.MULTILINE))
+    missing = expected - forwarded
+    assert not missing, f"compose 未透传（.env 里设了也不会生效）: {sorted(missing)}"
+
+
+def test_compose_forwards_port_used_by_entrypoint():
+    """HOST/PORT 必须既透传又在入口生效（CMD 不得硬编码地址）。"""
+    compose_text = COMPOSE.read_text(encoding="utf-8")
+    assert "${PORT" in compose_text
+    cmd = re.search(r"^CMD (.+)$", DOCKERFILE.read_text(encoding="utf-8"), re.MULTILINE)
+    assert cmd is not None
+    # 硬编码 --host/--port 会让 config.py 里的 HOST/PORT 在容器里静默失效
+    assert "--host" not in cmd.group(1) and "--port" not in cmd.group(1)
+
+
 def test_ci_workflow_paths_match_repository():
     """CI 里用到的路径必须存在，否则 workflow 必然失败。"""
     workflow = (ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")

web/src/api/__tests__/client.test.tsx

@@ -13,6 +13,7 @@ import {
   formatTime,
   healthView,
   probeFailureLabel,
+  usageErrorLabel,
   quotaSemantics,
 } from "../display";
 import { makeCredential } from "../../pages/__tests__/helpers";
@@ -211,6 +212,15 @@ describe("display helpers", () => {
     expect(probeFailureLabel("something_new" as never)).toBe("未知错误");
   });
 
+  it("明细失败类型翻成中文，未知值不进主提示但保留原文", () => {
+    expect(usageErrorLabel("rate_limit")).toBe("额度耗尽");
+    expect(usageErrorLabel("client_disconnect")).toBe("客户端中断");
+    expect(usageErrorLabel(null)).toBe("失败");
+    expect(usageErrorLabel(undefined)).toBe("失败");
+    // 后端新增枚举时前端不能显示空白：兜底文案带原值便于对照排查
+    expect(usageErrorLabel("brand_new_reason")).toBe("失败（brand_new_reason）");
+  });
+
   it("时间与数字格式化处理空值", () => {
     expect(formatTime(null)).toBe("—");
     expect(formatTime(1_700_000_000)).not.toBe("—");

web/src/api/display.ts

@@ -143,6 +143,35 @@ export function formatChartValue(value: number, metric: string): string {
 }
 
 
+/** 统计明细的失败类型（线值，来自后端 CONTROLLED_ERROR_TYPES）。
+ *  注意与 ProbeFailureReason 不是同一套：那是探测失败，这是请求失败。 */
+export type UsageErrorType =
+  | "client_disconnect"
+  | "credential_unavailable"
+  | "invalid_request"
+  | "no_healthy_credential"
+  | "rate_limit"
+  | "upstream_error"
+  | "upstream_protocol";
+
+/** 明细失败类型的中文说明（TECHNICAL §6.5：界面只展示稳定枚举的翻译）。 */
+export const USAGE_ERROR_LABEL: Record<UsageErrorType, string> = {
+  client_disconnect: "客户端中断",
+  credential_unavailable: "凭证失效",
+  invalid_request: "请求无效",
+  no_healthy_credential: "无可用凭证",
+  rate_limit: "额度耗尽",
+  upstream_error: "渠道错误",
+  upstream_protocol: "渠道响应异常",
+};
+
+/** 未知取值不得原样透传（TECHNICAL §6.5），兜底为「失败」。 */
+export function usageErrorLabel(errorType: string | null | undefined): string {
+  if (!errorType) return "失败";
+  return USAGE_ERROR_LABEL[errorType as UsageErrorType] ?? `失败（${errorType}）`;
+}
+
+
 export const PROBE_FAILURE_LABEL: Record<ProbeFailureReason, string> = {
   credential_rejected: "凭证被渠道拒绝，需要重新登录该账号",
   rate_limited: "渠道限流，稍后重试",

web/src/pages/StatsPage.tsx

@@ -8,7 +8,7 @@ import {
   useStatsOverview,
   useStatsTimeline,
 } from "../api/hooks";
-import { formatCompact, formatLatency, formatNumber, formatTime } from "../api/display";
+import { formatCompact, formatLatency, formatNumber, formatTime, usageErrorLabel } from "../api/display";
 import { Notice } from "../ui";
 import { ModelTrendChart } from "../components/ModelTrendChart";
 import { PageHeader } from "../components/PageHeader";
@@ -51,12 +51,12 @@ const PROVIDER_LABEL: Record<Provider, string> = { codebuddy: "CodeBuddy", trae:
 /** 明细分页的可选每页条数。 */
 const PAGE_SIZES = [10, 20, 50, 100];
 
-/** 明细状态列：成功固定文案；失败展示受控错误类型（脱敏，不含原始错误体）。 */
+/** 明细状态列：成功固定文案；失败展示受控错误类型的中文说明（脱敏，不含原始错误体）。 */
 function statusCell(row: UsageEventRow) {
   if (row.ok) {
     return <span className="text-ok">成功</span>;
   }
-  return <span className="text-destructive">{row.error_type ?? "失败"}</span>;
+  return <span className="text-destructive">{usageErrorLabel(row.error_type)}</span>;
 }
 
 export function StatsPage() {

web/src/pages/__tests__/StatsPage.test.tsx

@@ -234,7 +234,7 @@ describe("StatsPage", () => {
     expect(within(table).getByText("主账号")).toBeInTheDocument();
     expect(within(table).getByText("glm-5.2")).toBeInTheDocument();
     expect(within(table).getByText("成功")).toBeInTheDocument();
-    expect(within(table).getByText("rate_limit")).toBeInTheDocument();
+    expect(within(table).getByText("额度耗尽")).toBeInTheDocument();
     expect(within(table).getByText("8.2 s")).toBeInTheDocument();
     expect(within(table).getByText("2.4 s")).toBeInTheDocument();
     expect(within(table).getByText("90")).toBeInTheDocument();