fix(deploy): 默认镜像源改清华(pip+apt)/ npmmirror(npm)— 腾讯源给出损坏 litellm wheel

腾讯源返回的 litellm-1.87.0 wheel 文件损坏:镜像 index 声明的 sha256(fbbba7e…,
与 PyPI 官方一致)对,但实际吐出的文件字节算出 bbebefff…,pip 报
"THESE PACKAGES DO NOT MATCH THE HASHES"。本仓 requirements.txt 未钉 hash,
是镜像端 index 自声明 hash 与文件不符 = 镜像存的文件损坏/截断(非篡改、非 require-hashes)。

deploy/update.sh 三个默认值:
- PIP_INDEX_URL -> 清华 pypi.tuna.tsinghua.edu.cn(境内稳 + 同步及时;阿里 PyPI 曾滞后到没有 litellm>=1.83)
- APT_MIRROR    -> 清华 mirrors.tuna.tsinghua.edu.cn(Debian / security 路径同官方,sed 替 host 即可)
- NPM_REGISTRY  -> registry.npmmirror.com(清华无 npm registry,npmmirror 是境内事实标准)

换默认会让下次 build 从 pip 层全量重跑一次(~5-10min),之后命中 cache。
Dockerfile ARG 默认(官方源 fallback)不动。

RUN.md:头部「最后更新」、§镜像构建默认源说明、手动 build 示例、故障表
(新增 hash-不匹配诊断行 + 其余镜像行对齐新默认)。PROGRESS.md:2026-06-03 加一条。DESIGN 不动。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

PROGRESS.md

@@ -23,6 +23,8 @@
 
 ### 2026-06-03
 
+- **默认镜像源改清华(pip+apt)/ npmmirror(npm)**:腾讯源返回了损坏的 `litellm-1.87.0` wheel —— 镜像 index 声明的 sha256(`fbbba7e…`,与 PyPI 官方一致)对,但实际吐出的文件字节算出 `bbebefff…`,pip 报 `THESE PACKAGES DO NOT MATCH THE HASHES`(本仓 `requirements.txt` 未钉 hash,是镜像 index 自声明的 hash 与文件不符 = 镜像端文件损坏/截断,非篡改、非 require-hashes)。`deploy/update.sh` 三个默认值改:`PIP_INDEX_URL` → 清华 `pypi.tuna.tsinghua.edu.cn`、`APT_MIRROR` → 清华 `mirrors.tuna.tsinghua.edu.cn`、`NPM_REGISTRY` → `registry.npmmirror.com`(清华无 npm registry,npmmirror 是境内事实标准)。清华境内稳 + 同步及时(阿里 PyPI 曾滞后到没有 `litellm>=1.83`)。换默认会让下次 build 从 pip 层全量重跑一次(~5-10min),之后命中 cache。**对外行为(默认源)变化 → 更 RUN.md**:头部「最后更新」、§镜像构建默认源说明、手动 build 示例、故障表(新增 hash-不匹配诊断行 + 其余镜像行对齐新默认)。Dockerfile ARG 默认(官方源 fallback)不动。DESIGN 不动。
+
 - **回退 `ZCBOT_WORKSPACE_DIR` env 覆盖(架构有 bug),workspace 落数据盘改用 bind mount**:2026-06-02 加的 env 覆盖与路径存储层冲突 —— `core/paths.py` 把 DB 的 `working_dir` 锚定 **ROOT**(代码仓库目录)存相对串,`to_db_path` 对 ROOT 外路径直接 `relative_to` raise。env 一旦指向 ROOT 外的 `/data/...`,三家分叉:文件面板 `/v1/files` 走 `resolve_workspace`(吃到 env)看数据盘、agent resume 走 `from_db_path`(锚 ROOT)看 `ROOT/workspace`、新建 task `to_db_path` 直接 500。现场症状:文件面板"目录尚未创建"但 agent 文件其实写在老 `ROOT/workspace`。改法:`resolve_workspace` 回退成 `显式 arg > cfg workspace_dir > 默 workspace`(均 `ROOT/<值>`),删掉 env 分支与 `import os` 无关(os 别处仍用,保留)。要落数据盘改用 **bind mount** 把 `/data/zcbot/workspace` 接到 `ROOT/workspace`(`.resolve()` 不展开 bind,内核路径保持 ROOT 内,DB 不用改,dev 不受影响)。**对外行为变化 → 更 RUN.md**:删 `.env` 的 `ZCBOT_WORKSPACE_DIR` 段、「workspace 落独立数据盘」段改 bind mount(+ `RequiresMountsFor` 开机顺序硬化)、故障表两行(替换旧 env 行 + 加"目录尚未创建"诊断行)。DESIGN 不动。
 
 ### 2026-06-02

RUN.md

@@ -2,7 +2,7 @@
 
 > 怎么把 zcbot 跑起来。env / 常用命令 / 故障兜底。设计看 `DESIGN.md`,进度看 `PROGRESS.md`。
 
-最后更新:2026-06-01(update.sh 加自更新重跑守卫;默认源改腾讯/阿里滞后卡 litellm;build 跳过改 --skip-build;pip 不静默,build 走默认 TTY UI)
+最后更新:2026-06-03(默认镜像源改清华 pip+apt / npmmirror npm —— 腾讯源给过损坏 litellm wheel;workspace 落数据盘改 bind mount,撤 ZCBOT_WORKSPACE_DIR env)
 
 ---
 
@@ -263,7 +263,7 @@ sudo bash /opt/zcbot/deploy/update.sh
 
 - **build 必须在 restart 之前**:sandbox 容器 per-user 长驻 + 复用,`tools/` 是 build 进镜像的(非 mount)。restart 时 `shutdown_all` 清旧容器,下次 `ensure()` 才用新 `zcbot-sandbox:latest` 重建 —— 顺序反了新 tools/ 要等下次重启才生效。
 - **sandbox build 每次都跑没关系**:layer cache 让重活(pip ~1G / chromium / 字体 / mermaid,都在 `COPY tools/` 之上)在改代码部署时秒过;只有 `requirements.txt` 变了才整体重建(~5-10min,正好也是该重建的时候)。host backend 机器 / 临时不想动 docker:`sudo bash deploy/update.sh --skip-build`。
-- **镜像源默认腾讯**(`APT_MIRROR=mirrors.cloud.tencent.com` / `PIP_INDEX_URL=mirrors.cloud.tencent.com/pypi/simple/` / `NPM_REGISTRY=mirrors.cloud.tencent.com/npm/`,境内快且新包同步及时)。**阿里 PyPI 镜像同步滞后**(litellm 一度只到 1.82.6,卡死 `requirements.txt` 的 `>=1.83.0`),故默认避开阿里。要命中 docker cache 就别两组源来回换(换源从 pip 层炸开全重跑)。想用官方源:`PIP_INDEX_URL= sudo -E bash deploy/update.sh`(置空即回落 Dockerfile 官方默认)。host venv 的 step 2 pip 也吃这个源(脚本显式 `--index-url`,不靠 host pip.conf)。
+- **镜像源默认:pip+apt 清华、npm npmmirror**(`PIP_INDEX_URL=pypi.tuna.tsinghua.edu.cn/simple/` / `APT_MIRROR=mirrors.tuna.tsinghua.edu.cn` / `NPM_REGISTRY=registry.npmmirror.com/`)。pip 选清华是因为**腾讯源曾返回损坏的 litellm wheel**(index hash 对、文件字节不对 → pip `DO NOT MATCH THE HASHES`),且**阿里 PyPI 又一度滞后**(litellm 只到 1.82.6,卡死 `>=1.83.0`);清华境内稳 + 同步及时。npm 用 npmmirror 是因为**清华不提供 npm registry**。要命中 docker cache 就别多组源来回换(换源从 pip 层炸开全重跑)。想用官方源:`PIP_INDEX_URL= sudo -E bash deploy/update.sh`(置空即回落 Dockerfile 官方默认)。host venv 的 step 2 pip 也吃这个源(脚本显式 `--index-url`,不靠 host pip.conf)。
 - **进度可见**:step 2 pip 不带 `-q`,部署时能看到装包进度;step 4 docker build 走默认 TTY 进度 UI(分层折叠刷新,直观)。
 - **脚本会自更新重跑**:`git pull` 若动了 `deploy/update.sh` 本身,脚本会 `exec` 新版本从头重跑(旧脚本的变量默认值在 pull 前就求值了、bash 又按字节偏移边读边跑,不重跑会跑出过期行为 —— 这是首次拉到改 update.sh 的提交时"改了源还报旧错"的根因)。日志出现「update.sh 自身有更新 —— 用新版本重跑」即正常;`ZCBOT_UPDATE_REEXEC=1` 防死循环。
 - **migration 取 DB URL**:`db/migrations/env.py` 直接读 `os.environ['ZCBOT_DB_URL']`(不读 .env),脚本从 `.env` 抠出来显式 `env ZCBOT_DB_URL=... ` 喂进 `main.py db upgrade`。
@@ -436,9 +436,9 @@ Step 4 引入 egress proxy 后,完整 5 条红队用例(metadata / loopback /
 cd /home/lighthouse/zcbot
 docker build -t zcbot-sandbox:latest -f deploy/sandbox/Dockerfile \
     --build-arg HOST_UID=$(id -u) --build-arg HOST_GID=$(id -g) \
-    --build-arg APT_MIRROR=http://mirrors.cloud.tencent.com \
+    --build-arg APT_MIRROR=https://mirrors.tuna.tsinghua.edu.cn \
-    --build-arg PIP_INDEX_URL=https://mirrors.cloud.tencent.com/pypi/simple/ \
+    --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple/ \
-    --build-arg NPM_REGISTRY=https://mirrors.cloud.tencent.com/npm/ \
+    --build-arg NPM_REGISTRY=https://registry.npmmirror.com/ \
     .
 ```
 
@@ -660,10 +660,11 @@ sudo xfs_quota -x -c "limit -p bhard=10g zcbot_<user_uuid>" /opt
 | prod 想把 workspace 落独立数据盘 | **别用 env / 别指 ROOT 外绝对路径**(workspace 锚定 ROOT,ROOT 外会让文件面板 / agent / 新建 task 三家分叉)。用 **bind mount** 把 `/data/...` 接到 `ROOT/workspace`,逻辑路径不变,DB 不用改。详「workspace 落独立数据盘」段 |
 | 文件面板"目录尚未创建"但文件确实在 / agent 写的文件面板看不到 | workspace 被指到了 ROOT 外(旧 `ZCBOT_WORKSPACE_DIR` 绝对路径残留)→ 文件面板走 `resolve_workspace` 看一处、agent 走 DB `from_db_path`(锚 ROOT)看另一处。删掉 env、改用 bind mount(见上段),三家归一 |
 | `docker run zcbot-sandbox:latest` 报 `Unable to find image` | 镜像没 build。`sudo -u zcbot docker build -f deploy/sandbox/Dockerfile --build-arg HOST_UID=$(id -u zcbot) --build-arg HOST_GID=$(id -g zcbot) -t zcbot-sandbox:latest .` |
-| 镜像 build pip 报 `ReadTimeoutError: HTTPSConnectionPool(host='files.pythonhosted.org', ...)` | 境内访问 PyPI 抖动。加 `--build-arg PIP_INDEX_URL=https://mirrors.cloud.tencent.com/pypi/simple/`(腾讯云内网)或阿里云 / 清华源,详 RUN.md「镜像构建」段。Dockerfile 已把 pip timeout 拉到 60s,主因仍是源不通而非超时 |
+| 镜像 build pip 报 `THESE PACKAGES DO NOT MATCH THE HASHES FROM THE REQUIREMENTS FILE`(本仓 requirements 未钉 hash) | **不是被篡改、也不是 require-hashes**:镜像 index 声明的 wheel hash 与它实际吐出的文件字节不符 = 该镜像存的文件损坏 / 截断(2026-06-03 腾讯源就这么坏过 litellm-1.87.0)。换源重 build:`PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple/ sudo -E bash deploy/update.sh`。验真伪:`https://pypi.org/pypi/<pkg>/<ver>/json` 看官方 sha256 是哪边对。与下面"版本滞后(Could not find)"是两回事 |
-| pip 报 `Could not find a version that satisfies the requirement litellm>=1.83.0`(伴随一串 `Ignored ... yanked versions: 0.1.xxxx`) | 用的镜像源同步滞后,没有该新版本。**阿里 PyPI 一度只到 litellm 1.82.6** —— update.sh 默认已改腾讯源(到 1.88)。若手动 build 撞到:换 `PIP_INDEX_URL=https://mirrors.cloud.tencent.com/pypi/simple/` 或清华源。那串 `0.1.xxxx` 是 litellm 远古版本,纯干扰信息 |
+| 镜像 build pip 报 `ReadTimeoutError: HTTPSConnectionPool(host='files.pythonhosted.org', ...)` | 境内访问 PyPI 抖动。加 `--build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple/`(清华,现默认)或腾讯 / 阿里源,详 RUN.md「镜像构建」段。Dockerfile 已把 pip timeout 拉到 60s,主因仍是源不通而非超时 |
-| 镜像 build npm 装 mermaid-cli 慢 / fail | npm 源境内慢。加 `--build-arg NPM_REGISTRY=https://mirrors.cloud.tencent.com/npm/`(腾讯云)或 `https://registry.npmmirror.com/`(阿里) |
+| pip 报 `Could not find a version that satisfies the requirement litellm>=1.83.0`(伴随一串 `Ignored ... yanked versions: 0.1.xxxx`) | 用的镜像源同步滞后,没有该新版本。**阿里 PyPI 一度只到 litellm 1.82.6** —— update.sh 默认已是清华源(同步及时)。若手动 build 撞到:换 `PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple/` 或腾讯源。那串 `0.1.xxxx` 是 litellm 远古版本,纯干扰信息 |
-| 镜像 build apt 报 `OpenSSL error: ... unexpected eof while reading` | 腾讯云 / 阿里 mirror HTTPS 端偶发 close_notify 缺失,OpenSSL 3 严格 fail。改用 http 形式:`--build-arg APT_MIRROR=http://mirrors.cloud.tencent.com`(apt 包 GPG 签名校验,无 HTTPS 安全收益)。Dockerfile 已配 apt retry=5 + 关 pipeline,重 build 一般直接过 |
+| 镜像 build npm 装 mermaid-cli 慢 / fail | npm 源境内慢。默认已用 npmmirror;手动 build 加 `--build-arg NPM_REGISTRY=https://registry.npmmirror.com/`(阿里,清华无 npm 源)或腾讯 `https://mirrors.cloud.tencent.com/npm/` |
+| 镜像 build apt 报 `OpenSSL error: ... unexpected eof while reading` | 某些 mirror HTTPS 端偶发 close_notify 缺失,OpenSSL 3 严格 fail(腾讯 / 阿里见过;清华一般不犯)。改用 http 形式:`--build-arg APT_MIRROR=http://mirrors.tuna.tsinghua.edu.cn`(apt 包 GPG 签名校验,无 HTTPS 安全收益)。Dockerfile 已配 apt retry=5 + 关 pipeline,重 build 一般直接过 |
 | 容器内 shell 写工作目录报 `Permission denied`(but `sandbox check` ⑤ HOST_UID aligned ok) | DockerExecutor 写死了 `--user 1000:1000` 不会自动跟 build 的 HOST_UID 同步(改 `--user zcbot` 后已修)。仍报错检查镜像内 `docker run --rm --entrypoint id zcbot-sandbox:latest zcbot` 输出 uid 是否 = `id -u $(whoami)` |
 | 模型用 run_python 跑 `render_diagrams.py` 报 `mmdc returncode=1: Failed to launch chromium` | 容器内 chromium 缺 puppeteer no-sandbox 配置。镜像已落 `/sandbox/puppeteer-config.json` + ENV `MERMAID_PUPPETEER_CONFIG`,render_diagrams.py 已读 env 自动 -p 注入;仍跪查 `docker exec ... env \| grep MERMAID` 看 env 是否在 |
 | Export 报 "无可导出内容" | task 没 messages(只 system 不算);先发条消息再 export |

deploy/update.sh

@@ -18,8 +18,10 @@
 # 可调 env(不传则用默认 / Dockerfile 默认):
 #   APP_DIR(默认=脚本上级目录,即仓库根)  APP_USER(默认=部署目录属主)  SERVICE(zcbot)  PORT(8765)
 #   APT_MIRROR / PIP_INDEX_URL / PIP_TRUSTED_HOST / NPM_REGISTRY  镜像源,
-#     默认腾讯源(境内快,litellm 等新包同步及时;阿里源滞后过——曾卡死在没有的版本上)。
+#     默认:pip+apt 清华(tuna),npm npmmirror(阿里维护,境内 npm 事实标准;清华无 npm 源)。
-#     要稳定命中 docker cache 就别在两组源之间来回换(换源会从 pip 层炸开全重跑)。
+#     原腾讯源曾给出损坏的 litellm wheel(index hash 对、文件字节不对 → pip "DO NOT MATCH THE
+#     HASHES"),故 pip 改清华;清华境内稳 + 新包同步及时(阿里 PyPI 曾滞后到没有 litellm>=1.83)。
+#     要稳定命中 docker cache 就别在多组源之间来回换(换源会从 pip 层炸开全重跑)。
 #     想用官方源:PIP_INDEX_URL= sudo -E bash ...(置空)
 
 set -euo pipefail
@@ -51,12 +53,13 @@ IMAGE="zcbot-sandbox:latest"
 PY="$APP_DIR/.venv/bin/python"
 HEALTH_URL="http://127.0.0.1:${PORT}/healthz"
 
-# 镜像源默认腾讯(境内快 + 新包同步及时;Dockerfile sed 只替 host 前缀,目录结构同官方)。
+# 镜像源默认:pip+apt 清华(tuna,境内稳 + 同步及时;Dockerfile sed 只替 host 前缀,目录结构同官方),
-# 阿里 PyPI 镜像同步滞后(litellm 曾只到 1.82.6,卡死 requirements 的 >=1.83.0),故默认改腾讯。
+# npm 用 npmmirror(清华不提供 npm registry,npmmirror 是境内 npm 事实标准)。
+# 腾讯源曾返回损坏的 litellm wheel(hash 不匹配),阿里 PyPI 又一度滞后(litellm 只到 1.82.6),故 pip 选清华。
 # 置空(如 PIP_INDEX_URL= sudo -E ...)则该项不传 build-arg,回落 Dockerfile 官方源默认。
-APT_MIRROR="${APT_MIRROR-https://mirrors.cloud.tencent.com}"
+APT_MIRROR="${APT_MIRROR-https://mirrors.tuna.tsinghua.edu.cn}"
-PIP_INDEX_URL="${PIP_INDEX_URL-https://mirrors.cloud.tencent.com/pypi/simple/}"
+PIP_INDEX_URL="${PIP_INDEX_URL-https://pypi.tuna.tsinghua.edu.cn/simple/}"
-NPM_REGISTRY="${NPM_REGISTRY-https://mirrors.cloud.tencent.com/npm/}"
+NPM_REGISTRY="${NPM_REGISTRY-https://registry.npmmirror.com/}"
 
 log()  { echo "[deploy] $*"; }
 fail() { echo "[deploy] ERROR: $*" >&2; exit 1; }