release: bump version to 0.74.6

docs/technical/zh/ops-runbook.md

@@ -274,6 +274,15 @@ url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/"
 default = true
 ```
 
+启动和重启默认按指纹判断是否需要构建。需要明确复用已有镜像时，可对本次命令增加 --no-build：
+
+```bash
+./planet.sh start --no-build
+./planet.sh restart -a --no-build
+```
+
+该选项只影响 AI Provider，不会关闭其他服务的启动检查；缺少本地镜像时直接报错，也不会把旧镜像的指纹更新成当前代码。已有 Compose v2 时，构建、启动和能力检查只使用 v2，失败直接保留错误；只有未检测到 v2 时才考虑 v1。
+
 构建较慢时按层排查：
 
 | 现象 | 常见原因 | 处理方式 |
@@ -291,6 +300,66 @@ default = true
 
 OTP 一次性验证码走 Redis，key 格式 `otp:{purpose}:{email}`，TTL 600 秒。错误尝试 5 次后该 key 失效；重发冷却 60 秒，由 `otp_rate:{purpose}:{email}` 控制。
 
+## 错误原因对照表
+
+`planet.sh` 的所有 `log_error` 输出保留现场信息，并直接从下表读取错误编号、原因和处理建议；AI Provider 构建失败还会匹配完整构建日志。匹配按表中顺序进行，不区分英文大小写，分号分隔多个字面关键片段，具体错误优先于汇总错误。错误编号不是进程退出码，失败仍返回非零状态。
+
+确认新的故障原因时，必须更新中英文表，补充稳定编号、可辨识的日志片段和回归用例，再接入脚本。未确认的错误归入 `P_UNKNOWN`，不得自动把未知日志当成已验证原因写入手册。表由 `scripts/lib/error-diagnostics.zsh` 读取，不要在单元格中使用竖线；`scripts/harness/test_error_diagnostics.py` 验证匹配、双语编号和输出一致性。
+
+<!-- planet-error-catalog:start -->
+| 错误编号 | 匹配片段（分号分隔） | 原因／已确认的故障现象 | 处理建议 |
+| --- | --- | --- | --- |
+| P_PROXY_EXTERNAL | PLANET_PROXY_EXTERNAL | 当前 Docker 代理由其他配置管理，或已被人工修改，不能安全自动覆盖。 | 检查 daemon.json、systemd 代理及 Planet 管理记录，确认归属后再调整；脚本保留现有配置。 |
+| P_PROXY_CHANGED | PLANET_PROXY_CONFIG_CHANGED | 检测后 Docker 代理配置发生了变化。 | 等待其他配置操作结束后重试，避免覆盖并发修改。 |
+| P_PROXY_ROLLBACK | PLANET_PROXY_ROLLBACK_FAILED | 自动代理更新失败后，Docker 或原有容器未能完成恢复。 | 检查 Docker 服务日志和容器状态；原配置已还原，必要时依据 daemon.json.planet-proxy.bak 手动恢复服务。 |
+| P_PROXY_CONFIG | PLANET_PROXY_CONFIG_FAILED;Docker 构建代理检测失败;Docker 构建代理更新失败 | 自动代理检测、配置校验或服务更新失败。 | 检查 Python 3、curl、Docker 状态和 sudo 权限；配置更新会尝试回滚，代理凭据不会写入错误输出。 |
+| P_PROXY_NO_ROUTE | PLANET_PROXY_NO_ROUTE | 未找到能访问构建所需仓库的主机代理，直连探测也未通过。 | 恢复可用代理或修复直连网络、DNS及仓库地址后重试；不要把禁止构建当成网络修复。 |
+| P_REGISTRY_RATE_LIMIT | 429 Too Many Requests;toomanyrequests;pull rate limit | 镜像仓库已响应，但请求频率或拉取配额触发限流；具体限制需依据仓库响应确认。 | 停止反复重试，按上游提示等待；若为匿名拉取配额，核对 docker login 身份及额度。不要把限流误判为代理不可达。 |
+| P_DNS | no such host;temporary failure in name resolution;could not resolve host | 域名解析失败，尚不能确定是 DNS 配置还是上游解析异常。 | 检查 Docker 所在环境的 DNS 和代理解析；对比终端与 Docker 的解析结果。 |
+| P_TLS_CERT | x509:;certificate verify failed;certificate signed by unknown authority | TLS 证书校验失败。 | 检查系统时间、证书链和代理 CA；安装可信 CA，不要关闭证书校验。 |
+| P_PROXY_AUTH | proxy authentication required;407 proxy | 代理要求认证，当前请求未通过认证。 | 检查 Docker 服务的代理凭据和代理端权限，不要把凭据写入仓库或日志。 |
+| P_NETWORK_TIMEOUT | i/o timeout;tls handshake timeout;context deadline exceeded;deadlineexceeded | 网络连接或 TLS 握手超时，单凭日志不能认定是代理、DNS 或 IPv6 中的哪一项。 | 对比直连与代理请求；检查 Docker 服务自身的代理、DNS 和 IPv6 路由，终端代理不等于 Docker 服务代理。 |
+| P_CONNECTION_REFUSED | connection refused | 目标地址拒绝连接，服务可能未监听或地址、端口配置不匹配。 | 检查被拒绝的目标是代理、数据库还是镜像仓库，再确认监听端口和服务状态。 |
+| P_REGISTRY_AUTH | pull access denied;unauthorized:;insufficient_scope;denied: requested access | 镜像仓库拒绝访问或当前身份无拉取权限。 | 核对镜像名、仓库权限及 docker login 使用的身份。 |
+| P_IMAGE_TAG | manifest unknown;manifest not found | 镜像仓库中找不到指定的镜像清单或标签。 | 核对 PYTHON_IMAGE、UV_IMAGE 或其他镜像标签，确认目标架构受支持。 |
+| P_DISK_FULL | no space left on device | 磁盘空间或 inode 不足。 | 检查 df -h、df -i 和 docker system df；确认用途后定向清理，不要删除数据库卷。 |
+| P_DOCKER_SOCKET | permission denied while trying to connect;刷新组权限后仍无法访问 Docker socket | 当前用户无法访问 Docker socket。 | 检查 socket 属组和 docker 组成员资格；执行 ./planet.sh init 配置权限后重新打开终端。 |
+| P_DOCKER_SERVICE | 没有可用的 docker.service;Docker Engine 启动失败;cannot connect to the docker daemon;无法连接 daemon | Docker 服务未就绪，或客户端无法连接当前 endpoint。 | 检查 systemctl status docker、docker context ls 和 journalctl -u docker.service；不要把连接失败当成未安装。 |
+| P_DOCKER_DESKTOP | 检测到 Docker Desktop，但当前 WSL | Docker Desktop 或当前 WSL 集成不可用。 | 启动 Docker Desktop，并启用当前发行版的 WSL Integration。 |
+| P_DOCKER_ENDPOINT | 当前 Docker 使用其他 context 或远程/rootless endpoint | 当前远程或 rootless Docker endpoint 不可用。 | 检查 docker context ls、DOCKER_HOST 和目标服务；不要自动替换成本地引擎。 |
+| P_BUILDX | 未检测到 docker buildx;buildx 0.17;buildx >=;buildx v;当前 docker compose 不支持 build;安装后 Docker CLI、Compose v2 | Docker 构建插件缺失、版本不足或构建能力不可用。 | 检查 docker buildx version 和 docker compose version，按项目要求安装或升级相应插件。 |
+| P_COMPOSE_MISSING | 未检测到可用的 Docker Compose | 未发现可用的 Compose 命令。 | 安装 Compose v2 插件并验证 docker compose version；已有 v2 执行失败时不回退 v1。 |
+| P_LOCAL_IMAGE_MISSING | 已指定 --no-build，但本地没有 AI Provider 镜像 | 禁止构建时，本地没有可复用的 AI Provider 镜像。 | 先成功构建或导入镜像，再使用 --no-build；该选项不会自动构建。 |
+| P_SUDO | 缺少 sudo | 自动安装或配置系统依赖所需的提权工具不可用。 | 由管理员安装 sudo 并授予必要权限，或预先安装依赖。 |
+| P_UNSUPPORTED_OS | Docker 自动安装目前支持;未识别系统包管理器 | 当前系统不在脚本自动安装的支持范围内。 | 按系统官方方式安装依赖，再重新执行脚本。 |
+| 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_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、凭据、库名和端口；容器健康不等于后端能连接。 |
+| P_DB_START | 数据库启动失败;数据库重启失败;PostgreSQL 启动失败;数据库初始化失败 | 数据库启动、健康检查或初始化未完成。 | 检查 PostgreSQL、Redis 容器日志及具体数据库错误；不要通过删除数据卷排障。 |
+| P_BACKEND_START | 后端进程已退出;后端启动失败 | 后端进程退出或未通过健康检查。 | 查看 ./planet.sh log -b，优先处理导入、配置、数据库连接或应用初始化错误。 |
+| P_AI_START | AI Provider 启动失败 | AI Provider 容器未正常启动或未通过健康检查。 | 查看 ./planet.sh log -a，检查运行配置、端口和容器退出原因。 |
+| P_FRONTEND_START | 前端启动失败 | 前端未通过启动健康检查。 | 查看 ./planet.sh log -f，检查 Bun、依赖、Vite 入口和端口占用。 |
+| P_MOTION_START | Motion Agent 启动失败 | Motion Agent 未正常启动。 | 查看 ./planet.sh log -m，检查依赖、摄像头和输入模式。 |
+| P_ACCOUNT_INPUT | 用户名不能为空;密码不能为空;密码长度不能少于;两次输入的密码不一致 | 创建用户时输入不满足校验要求。 | 按提示重新输入用户名及满足长度要求且一致的密码。 |
+| P_HTTP_HEALTH | 不可访问: | 指定 HTTP 端点未通过访问检查。 | 检查目标 URL、服务监听、防火墙和本机／局域网路由；HTTPS 还需检查证书信任。 |
+| 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 服务代理与构建网络
+
+终端的 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 时，不做联网探测；这不是后台监控，代理启停在下一次实际构建时检测。
+
+`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。代理地址从环境读取，不硬编码某台机器的端口。
+
+AI Provider Dockerfile 使用 BuildKit 内置解析器，避免额外拉取 docker/dockerfile 解析器镜像；Python、uv 基础镜像和依赖下载仍需网络。--no-build 只用于明确复用本地镜像，不是构建网络错误的修复。构建错误日志位于 `${XDG_STATE_HOME:-$HOME/.local/state}/planet/aiprovider_build.log`；重启恢复后的服务可用 ./planet.sh health 检查。
+
 ## 故障排查顺序
 
 ```bash