release: bump version to 0.74.7

docs/technical/zh/ops-runbook.md

@@ -302,7 +302,7 @@ OTP 一次性验证码走 Redis，key 格式 `otp:{purpose}:{email}`，TTL 600
 
 ## 错误原因对照表
 
-`planet.sh` 的所有 `log_error` 输出保留现场信息，并直接从下表读取错误编号、原因和处理建议；AI Provider 构建失败还会匹配完整构建日志。匹配按表中顺序进行，不区分英文大小写，分号分隔多个字面关键片段，具体错误优先于汇总错误。错误编号不是进程退出码，失败仍返回非零状态。
+`planet.sh` 默认只保留状态主行下的具体错误；使用 `--verbose` 时，`log_error` 从下表读取错误编号、原因和处理建议；AI Provider 构建失败还会匹配完整构建日志。匹配按表中顺序进行，不区分英文大小写，分号分隔多个字面关键片段，具体错误优先于汇总错误。错误编号不是进程退出码，失败仍返回非零状态。
 
 确认新的故障原因时，必须更新中英文表，补充稳定编号、可辨识的日志片段和回归用例，再接入脚本。未确认的错误归入 `P_UNKNOWN`，不得自动把未知日志当成已验证原因写入手册。表由 `scripts/lib/error-diagnostics.zsh` 读取，不要在单元格中使用竖线；`scripts/harness/test_error_diagnostics.py` 验证匹配、双语编号和输出一致性。
 
@@ -335,6 +335,7 @@ OTP 一次性验证码走 Redis，key 格式 `otp:{purpose}:{email}`，TTL 600
 | P_LOCKFILE_CHANGED | 修改了 uv.lock | 依赖准备意外修改了锁文件。 | 检查依赖清单与锁文件的一致性；新环境使用 frozen 安装，不要隐式更新锁文件。 |
 | P_DEPENDENCIES | 安装失败;安装后仍不可用;安装完成后仍未找到;未找到 .venv/bin/python;自动安装后仍无法解析运行时;未找到 Vite Bun 入口;缺少 mediapipe/opencv-python;仍无法导入 mediapipe/opencv-python;需要 openssl | 必需依赖安装失败、缺失或未进入当前运行环境。 | 查看对应安装日志，检查网络、软件源和 PATH；前端使用 Bun，Python 使用项目 uv 环境。 |
 | P_ARGUMENT | 未知参数;非法端口;需要端口号;需要逗号分隔;--motion-agent-mode 需要;--motion-agent-wsl-usbipd-busid 需要;用法: ./planet.sh | 命令或参数不符合脚本支持的格式。 | 查看 ./planet.sh 用法，修正参数和值后重试。 |
+| P_DB_PORT_OCCUPIED | PLANET_DB_PORT_OCCUPIED | Planet 的数据库或 Redis 宿主机端口已被其他容器或服务占用。 | 根据错误中的占用者核对 docker ps；调整 backend/.env 的 DATABASE_URL 端口或 REDIS_PORT（进程 REDIS_URL 优先），planet.sh 会同步 Compose 映射；不停止其他项目或删除数据卷。 |
 | P_PORT | 地址已被占用;端口仍不可用;清理失败，请检查占用进程;port is already allocated;address already in use | 请求的端口被占用，或在宿主机／外部环境中不可绑定。 | 检查 ss 和 Windows Get-NetTCPConnection，确认占用者后调整端口或停止对应服务。 |
 | P_CAMERA | live 模式缺少可用摄像头;未找到可打开并能读帧的摄像头 | Motion Agent 无法取得可用摄像头画面。 | 检查设备、权限和 WSL USB 转发；无需摄像头时使用 --non-motion-agent 或明确选择 dry-run。 |
 | P_DB_CONNECTION | 后端数据库连接检查失败 | 后端实际数据库连接或发布端口检查未通过。 | 查看连接探测的具体输出，核对 DATABASE_URL、凭据、库名和端口；容器健康不等于后端能连接。 |
@@ -345,16 +346,46 @@ OTP 一次性验证码走 Redis，key 格式 `otp:{purpose}:{email}`，TTL 600
 | P_MOTION_START | Motion Agent 启动失败 | Motion Agent 未正常启动。 | 查看 ./planet.sh log -m，检查依赖、摄像头和输入模式。 |
 | P_ACCOUNT_INPUT | 用户名不能为空;密码不能为空;密码长度不能少于;两次输入的密码不一致 | 创建用户时输入不满足校验要求。 | 按提示重新输入用户名及满足长度要求且一致的密码。 |
 | P_HTTP_HEALTH | 不可访问: | 指定 HTTP 端点未通过访问检查。 | 检查目标 URL、服务监听、防火墙和本机／局域网路由；HTTPS 还需检查证书信任。 |
+| P_DOCKER_MIRROR_FAILED | PLANET_DOCKER_MIRROR_FAILED | 备用镜像的 manifest 校验或实际拉取失败，未能完成回退。 | 查看具体仓库错误；检查备用站可用性、镜像白名单、架构和 digest，不把首页可达当成镜像可用。可配置 PLANET_DOCKER_MIRROR_PREFIX 或关闭自动回退后修复原源。 |
+| P_DOCKER_COMMAND_TIMEOUT | PLANET_DOCKER_COMMAND_TIMEOUT | 当前 Docker 命令超过脚本的等待上限；仅凭超时不能确定是代理、网络还是本地引擎问题。 | 根据阶段名称、最近输出和日志定位；无输出时检查对应 Docker 命令及 daemon 日志，确认仍有进展后再调整该阶段超时。 |
 | P_COMPOSE_FAILED | Docker Compose 执行失败;docker-compose v1 执行失败 | 所选 Compose 命令失败，尚未识别更具体原因。 | 查看命令前面的原始错误；已有 Compose v2 时修复其错误，不安装 v1 作为回退。 |
 | P_BUILD_FAILED | AI Provider 镜像构建失败;failed to solve | 镜像构建失败，现有证据未匹配已知的具体原因。 | 查看 aiprovider_build.log 中最早的具体错误，确认原因后补充本表和回归用例。 |
 | P_UNKNOWN | — | 尚未归类，不能从现有证据确认原因。 | 保留完整错误和执行命令；确认根因后补充本表、中英文说明及回归用例。 |
 <!-- planet-error-catalog:end -->
 
+### Docker 等待进度与超时
+
+Docker 检查、Compose 启动、数据库连接检查和 AI Provider 构建的最新步骤更新在现有状态主行下面的副行，不打印额外的开始/完成记录、版本号或日志路径。成功后清除副行；静默等待时保留当前步骤并更新耗时。失败时保留具体错误并退出，后续汇总错误和清理通知不会覆盖它。Compose 执行失败不再重复启动；容器正常启动后的健康等待继续沿用原有预算。
+
+`PLANET_DOCKER_PROBE_TIMEOUT` 默认 15 秒，`PLANET_COMPOSE_TIMEOUT` 默认 180 秒，`PLANET_DOCKER_BUILD_TIMEOUT` 默认 900 秒，均为单次命令总时限，可设为正数秒。超时终止本次 CLI 进程组；daemon 可能已接受请求，仍应检查实际容器状态。Compose 检查超时不会回退到 v1。
+
+详细日志位于 `${PLANET_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/planet}`：Compose 使用 `compose.*.log`，构建使用 `aiprovider_build.log`，连接检查使用 `database-check.*.log`。日志权限为 600，URL 中的代理用户名和密码会被遮盖。`scripts/docker_command.py` 负责记录、计时和进程清理，终端渲染由 `planet.sh` 统一负责。直接执行系统 `docker compose` 不会加载此包装器。
+
+### 演示启动的数据库排障
+
+已确认的冲突案例是另一个项目的 PostgreSQL 和 Redis 分别占用 `5432`、`6379`。Planet 容器可能显示健康，却没有实际发布宿主机端口；后端也可能误连另一套数据库并报认证失败。`scripts/check_database_connection.py --ports` 在启动前检测占用者，冲突时立即停止，不通过反复重建解决端口争用。
+
+需要共存时，在 `backend/.env` 中将 `DATABASE_URL` 的端口改为可用端口（例如 `15432`），将 `REDIS_PORT` 改为可用端口（例如 `16379`）。保留账号、密码和库名；若进程设置了 `REDIS_URL`，也必须同步它。`planet.sh` 从后端实际配置导出 `PLANET_POSTGRES_PORT`、`PLANET_REDIS_PORT`，重建容器映射时保留命名数据卷。直接使用 Compose 时需显式提供这两个变量。数据库端口只发布到 `127.0.0.1`。
+
+其他错误按证据分别处理：认证失败先核对连接目标和已有卷的密码，修改 `POSTGRES_PASSWORD` 不会重置已有密码；端口映射缺失且没有冲突时允许保留卷重建一次；镜像下载的 DNS、TLS、代理认证和限流错误按上表各自处理。正常下载或依赖安装的慢进度不算失败，代码与依赖未变化时后续启动应复用镜像。
+
+### Docker 镜像的临时备用源
+
+清华 [Docker CE 软件仓库](https://mirrors.tuna.tsinghua.edu.cn/help/docker-ce/) 只提供 Docker 安装包，不是 Docker Hub 镜像服务。Docker 镜像回退默认使用 [DaoCloud 公开镜像服务](https://github.com/DaoCloud/public-image-mirror)，清华 PyPI 回退仍只用于本机 Python 依赖。
+
+构建前先检测原仓库的代理和直连；均不可达时验证备用路径。原路径探测成功、实际拉取仍发生 DNS/连接超时等网络错误时，也只回退一次。认证失败、证书错误、限流、端口冲突及 Dockerfile 内部依赖安装失败不会触发镜像源切换。所有路径失败后保留错误副行并退出。原始失败日志保留为同目录的 `*.primary.log`。
+
+备用站必须通过具体镜像的 manifest 检查，执行时锁定返回的 `sha256` digest；输入本身指定 digest 时必须一致。基础镜像只临时传入本次构建参数，原配置、构建指纹和最终镜像名不变。数据库只为本次请求中缺少的镜像执行备用拉取，成功后加回原始本地标签，再执行原 Compose 启动。不会修改全局 `registry-mirrors` 或源码配置，已有命名数据卷不变。
+
+`PLANET_DOCKER_MIRROR_FALLBACK=0` 关闭回退；`PLANET_DOCKER_MIRROR_PREFIX` 默认 `m.daocloud.io`，可设置为可信镜像服务的 `registry/path` 前缀；`PLANET_DOCKER_MIRROR_TIMEOUT` 默认 120 秒，用于基础镜像验证。仅映射 Planet 使用的公开 Python、uv、PostgreSQL 和 Redis 仓库，自定义/私有镜像不会被自动送往公共站。公共镜像服务有白名单、限流和缓存延迟，可变标签可能滞后；需要严格固定版本时应使用 digest，演示前应完成构建并保留本地镜像。
+
+`scripts/docker_mirror.py` 负责映射、manifest 校验及数据库镜像拉取，`scripts/lib/docker-mirror.zsh` 负责网络错误筛选和临时参数；它们复用现有命令进度与超时执行器。回归覆盖私有仓库保护、digest 不一致、非网络错误、一次回退与原配置保留。
+
 ### Docker 服务代理与构建网络
 
 终端的 HTTP_PROXY / HTTPS_PROXY 不会自动配置已经运行的 Docker 服务。若终端通过代理能访问镜像仓库，而 Docker 拉取超时，应分别验证代理连接、直连和 Docker 服务的实际代理设置。探测收到 HTTP 401、403 或 429 表示仓库已响应，不等于已获得镜像拉取权限或剩余额度；认证及限流仍由实际构建验证，不能据此把可达代理切换掉。
 
-实际构建 AI Provider 镜像前，脚本自动读取当前环境的 HTTPS_PROXY、HTTP_PROXY、ALL_PROXY（含小写形式），依次验证 HTTP/HTTPS 代理能否访问 PYTHON_IMAGE、UV_IMAGE 对应的仓库，并尊重 NO_PROXY。有可用代理才为本地 Linux Docker Engine 设置代理；没有代理或代理不可用时测试直连并清除脚本管理的旧代理。两种路径都不可用时，用 P_PROXY_NO_ROUTE 明确停止。没有代理且 Docker 原本也是直连时，不新增代理配置。指纹命中跳过构建或使用 --no-build 时，不做联网探测；这不是后台监控，代理启停在下一次实际构建时检测。
+实际构建 AI Provider 镜像前，脚本自动读取当前环境的 HTTPS_PROXY、HTTP_PROXY、ALL_PROXY（含小写形式），依次验证 HTTP/HTTPS 代理能否访问 PYTHON_IMAGE、UV_IMAGE 对应的仓库，并尊重 NO_PROXY。有可用代理才为本地 Linux Docker Engine 设置代理；没有代理或代理不可用时测试直连并清除脚本管理的旧代理。原源两种路径都不可用时继续检测备用镜像路径；备用路径也不可用时，用 P_PROXY_NO_ROUTE 明确停止。没有代理且 Docker 原本也是直连时，不新增代理配置。指纹命中跳过构建或使用 --no-build 时，不做联网探测；这不是后台监控，代理启停在下一次实际构建时检测。
 
 `scripts/docker_proxy.py` 管理 `/etc/docker/daemon.json` 的 proxies，归属记录保存在仅 root 可读写的 `/etc/docker/planet-proxy-state.json`。不覆盖管理员配置、systemd 代理或人工修改过的代理。配置相同不提权、不重启；需要修改时使用现有 sudo 流程，保留其他 Docker 设置，备份到 daemon.json.planet-proxy.bak，校验后重启 Docker 并启动原先运行的容器。失败时回滚；恢复后应检查容器健康。代理凭据只经环境或受限文件传递，不输出到日志。Docker Desktop、远程和 rootless Docker 沿用自身设置，不修改本机 daemon.json。代理地址从环境读取，不硬编码某台机器的端口。