planet/docs/technical/zh/ops-runbook.md

智能星球运维手册

这份手册面向部署、值班和二次开发的运维人员。客户面向的 UI 使用流程见 智能星球使用手册，本手册只覆盖 shell、Docker、日志、环境变量和故障排查。

Docker 初始化与访问权限

新机器应先执行初始化，再启动应用服务：

zsh ./planet.sh init --non-motion-agent && zsh ./planet.sh start --non-motion-agent

脚本入口仍需先安装 zsh、curl，并保证软件源可访问。init 在同步 Python 和前端依赖之前准备 Docker：

• 已有可用的 Docker、Compose v2 和 Buildx（至少 0.17.0）时直接复用。
• Ubuntu / Ubuntu WSL 缺少依赖时，通过 apt 安装 docker.io、docker-compose-v2、docker-buildx 中缺失的部分。若已安装 Docker CE CLI，则使用已配置的 Docker CE 软件源和对应插件包，避免混用软件包系列。
• 本地 Docker daemon 未运行时，确认 docker.service 存在后启用并启动它。WSL 必须启用 systemd；如果服务管理不可用，脚本会在 Docker 准备阶段明确报错。
• 当前用户不能读写 Docker socket 时，检查并补装提供 usermod 的 passwd 包，将用户加入 docker 组。该组拥有管理本机 Docker 的高权限。脚本使用 sudo 以原用户身份刷新组权限并继续原命令，保留参数，不依赖 sg，也不会把应用进程改为 root 用户运行。

需要提权时，脚本会在前台请求 sudo 认证。普通用户缺少 sudo、认证失败、软件源不可用或安装后版本仍不满足要求时，初始化会停止并报告具体原因。

同一旧终端随后执行 planet.sh start 等命令时，也会检测已加入但尚未生效的 Docker 组权限并刷新。若要在终端直接使用 docker，重新打开 Ubuntu 会话即可。

Docker Desktop 已存在但 WSL 集成不可用时，脚本提示启动 Desktop 并启用当前发行版的 WSL Integration。已有远程或 rootless endpoint 无法连接时，提示检查当前环境；这些情况不会自动安装另一套本地引擎。其他操作系统的自动安装暂未支持。

安装逻辑由 planet.sh 调用 scripts/lib/docker-bootstrap.zsh；缺少 CLI、没有服务单元、socket 权限不足和 daemon 未启动会分别诊断。仅在确认 docker.socket 单元存在时才给出启动该单元的建议。验证准备结果可执行：

docker info
docker compose version
docker buildx version

数据库初始化与连接检查

init 和 start 会先通过 Compose 同步 PostgreSQL / Redis 容器配置，包括已有容器的端口映射；仅执行 docker start 无法应用配置变化。Compose 同步失败时会保留具体错误，例如端口被占用，不会继续复用旧容器并报告成功。

容器内部的 pg_isready 只检查服务是否接受连接，不能证明宿主机上的后端使用正确地址和密码。容器健康后，init 和后端启动流程通过 scripts/check_database_connection.py 读取与后端相同的有效 DATABASE_URL，检查本地 PostgreSQL 的实际发布端口并执行只读 SELECT 1。启动流程在准备 AI Provider 镜像之前完成此检查；失败会立即停止。init 通过检查后才创建表和默认数据。

• 如果本地实际端口映射仍缺失或不匹配，脚本会保留数据卷，按 Compose 配置重建一次 PostgreSQL 并重新检查；再次失败就停止。
• 认证、库名或网络错误会在建表前停止，诊断只显示目标主机、端口和库名，不输出密码、完整连接串或驱动异常原文。
• 进程环境变量中的 DATABASE_URL 优先于 backend/.env。单独修改 POSTGRES_PASSWORD 不会自动更新连接串，也不会改变已有数据卷内的密码。已有环境文件会保留，需要核对其有效配置。
• 显式配置的外部数据库不要求本地容器端口匹配；host 网络模式也不要求发布端口，两者仍须通过实际连接检查。

出现 port is already allocated 或 address already in use 时，检查 docker ps 的端口信息和 ss -ltnp '( sport = :5432 )'；WSL 镜像网络下还需检查 Windows 侧监听。初始化不会为了占用数据库端口而自动结束其他数据库服务，也不会删除数据卷或重设密码。

首次启动

./planet.sh start

默认行为：

• 启动 PostgreSQL 和 Redis
• 启动 AI Provider
• 启动后端 API
• 启动前端 Vite dev server
• 输出 Earth、控制台、Playground 和后端 API 文档入口

首次启动会自动写入两个默认账号（见 backend/app/db/session.py 的 DEFAULT_LOGIN_USERS）：

用户名	密码	角色
admin	admin123	super_admin
linkong	LK12345678	super_admin

两个默认账号 email_verified 为 true，可直接登录控制台。任何在该列表之外的账号都必须走公开注册 + 邮箱验证流程（见使用手册），或用 ./planet.sh createuser 命令式创建。

可指定端口：

./planet.sh start -b 8001 -f 3001 -a 8101

参数	含义
-b <port>	后端端口
-f <port>	前端端口
-a <port>	AI Provider 端口
--allow-lan	允许局域网访问
--verbose	显示更多命令输出

启停与按模块重启

停止全部：

./planet.sh stop

会停止后端、AI Provider、前端、PostgreSQL、Redis。

按模块重启：

./planet.sh restart        # 全量
./planet.sh restart -b     # 后端
./planet.sh restart -f     # 前端
./planet.sh restart -a     # AI Provider
./planet.sh restart -d     # 数据库

按模块重启适合日常开发，能避免无关服务被打断。

破坏性重置

./planet.sh destroy

destroy 用于把本地开发环境退回到接近空项目的状态。执行前需要输入 Y 确认；源码和现有 .env 配置文件会保留。

清理顺序和边界：

• 如果 planet_postgres 正在运行，脚本会先清空 planet_db 的 public schema。这样即使后续 Docker volume 删除失败，旧的 collected_data.is_current = true 也不会让 Earth OOBE 继续显示 ready=true。
• Docker 清理只针对 Compose project 为 planet 的资源，以及显式列出的 planet_postgres_data、planet_redis_data、postgres_data、redis_data；不要按 planet_* 模式删除没有 label 的 volume，避免误删同机其他项目。
• 本地编译状态会删除 .venv、前端 node_modules / dist、Planet state，以及散落的 Python / Vite 缓存目录；$PLANET_CACHE_DIR/downloads 会保留，用于保存 CelesTrak 这类受上游下载窗口限制的原始文件缓存。

重置后重新执行 ./planet.sh init 会重建表和默认数据，但不会恢复旧采集结果；首次进入 Earth 时 OOBE 会重新按后端真实采集状态判断。触发 CelesTrak 采集时，如果上游返回“本轮 GP 数据未更新”的 403，后端会优先用保留的下载缓存重新写入数据库；如果 active 缓存不存在，会尝试有效 CelesTrak 分组缓存作为 fallback；如果下载缓存也不存在，只能等待 CelesTrak 下一次更新窗口或使用 Space-Track。控制台里的数据源“删除数据库”和“清理缓存”不会删除 $PLANET_CACHE_DIR/downloads/celestrak。

健康检查

./planet.sh health

会检查：

• planet_* 容器状态
• 后端 /health
• AI Provider /health
• 前端页面可达性

如果某项显示 offline，优先看对应日志。

日志

最近日志：

./planet.sh log

持续跟随：

./planet.sh log -f   # 前端: ~/.local/state/planet/frontend.log
./planet.sh log -b   # 后端: ~/.local/state/planet/backend.log
./planet.sh log -a   # AI Provider: planet_aiprovider 容器日志

命令式创建用户

./planet.sh createuser

交互式提示用户名、密码、角色，直接落库并标记 email_verified = TRUE。

适用场景：

• SMTP 还没配置好，但需要先发账号给一名管理员
• 想批量预置内部测试账号
• 公开注册流程因任何原因不可用，需要应急兜底

正式用户开通推荐走控制台 /settings -> SMTP 邮件 配好发件后，让用户在 /register 自助注册。

局域网 / WSL 访问

./planet.sh start --allow-lan

适用于：

• WSL 中启动，Windows 浏览器访问
• 手机或平板演示 Earth
• 局域网其他机器访问同一开发实例

Windows 侧可以使用仓库根目录的 planet.cmd 作为一键入口。它会请求管理员权限，进入 Ubuntu WSL 发行版的 /home/linkong/planet，执行 ./planet.sh restart --allow-lan，成功后打开 http://localhost:3000/earth，并把终端停留在 WSL shell 中便于继续排查日志。若本机发行版名称或项目路径不同，需要先按实际环境调整 planet.cmd 中的 wsl.exe -d ... --cd ... 参数。

新机器优先确认 WSL 版本：

wsl -l -v

Planet 开发环境建议使用 WSL2。WSL1 下网络、文件系统和进程模型与 Linux 差异更大，可能表现为 Bun 包管理命令只返回 An unknown error occurred (Unexpected)、端口释放不稳定，或局域网访问行为与脚本预期不一致。若发行版仍是 WSL1，可转换：

wsl --set-version Ubuntu 2

--allow-lan 会让前端、后端和 AI Provider 直接对开发机开放：前端 3000、后端 8000、AI Provider 8010。脚本启动前会检查这三个端口；如果 WSL/Linux 侧无法释放端口，并检测到 Windows 侧 listener 或旧 portproxy，会请求管理员 PowerShell 清理。WSL 中运行时，Windows 本机一般可以通过 localhost 访问，局域网其他机器访问 Windows 局域网 IP 时还需要 Windows 防火墙允许访问。

建议按顺序排查：

# 在运行 Planet 的 shell 中
curl http://localhost:3000
curl http://localhost:8000/health
curl http://localhost:8010/health
ss -ltnp | grep -E ':3000|:8000|:8010'

如果服务已经启动但局域网 IP 仍访问失败，优先清理旧 portproxy 并确认 Windows 防火墙允许访问。脚本会自动检测并请求管理员 PowerShell 处理；自动请求被取消时，手动兜底命令如下：

netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=3000
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8000
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8010

New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000
New-NetFirewallRule -DisplayName "WSL Planet 8010" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8010

局域网设备访问 Windows 对外端口，例如 http://<Windows局域网IP>:3000/earth、http://<Windows局域网IP>:8000/health、http://<Windows局域网IP>:8010/health。

AI Provider 环境变量与构建

AI Provider 运行期配置可以放在两处：

位置	适合内容	说明
aiprovider/.env	团队约定的本地默认配置	Docker Compose 作为 env_file 读取
~/.zshrc	个人 provider、模型、密钥、代理	planet.sh 启动时读取常见 AI_*、SERVICE_*、PYTHON_IMAGE、UV_IMAGE

推荐写法：

export AI_PROVIDER=minimax
export AI_PROVIDER_API=anthropic-messages
export AI_BASE_URL=https://api.example.com/anthropic
export AI_API_KEY=sk-change-me
export AI_MODEL=MiniMax-M2.7
export AI_PROVIDER_SERVICE_TOKEN=change_me

planet.sh 默认只静态解析 ~/.zshrc 中简单的 export KEY=value 或 KEY=value 行。需要复杂 shell 展开时显式启用：

PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a

完全忽略 ~/.zshrc：

PLANET_LOAD_ZSHRC_ENV=0 ./planet.sh start -a

AI Provider 镜像只在代码、Dockerfile、Compose 配置或相关 Python 依赖变化时重建。修改密钥或 Base URL 后只需重启容器：

./planet.sh restart -a

重建判断使用内容 fingerprint，而不是只看文件 mtime。planet.sh 会把 aiprovider/ 文件、aiprovider/Dockerfile、pyproject.toml、uv.lock、PYTHON_IMAGE、UV_IMAGE 和依赖指纹合成 AI_PROVIDER_BUILD_FINGERPRINT，构建时写入镜像 label planet.aiprovider.build-fingerprint。如果现有 planet-aiprovider:latest 镜像的 label 与当前 fingerprint 一致，脚本会跳过 rebuild 并刷新本地 stamp；旧镜像没有 label 时才回退到 state/cache 里的 stamp 判断。

Docker 构建统一使用 uv sync --frozen。为了让容器构建也能复用本机 uv 镜像源配置，脚本会解析以下顺序中的第一个配置文件，并通过 BuildKit secret 挂到容器内 /root/.config/uv/uv.toml：

1. 当前环境的 UV_CONFIG_FILE
2. 仓库根目录 uv.toml
3. ${XDG_CONFIG_HOME:-~/.config}/uv/uv.toml
4. ~/.uv/uv.toml

如果都不存在，脚本会创建一个空的 state 文件作为 secret，避免 Compose 的 secret file 缺失。进入 Docker 构建前会清掉 UV_DEFAULT_INDEX、UV_INDEX_URL、UV_EXTRA_INDEX_URL 这类环境变量，只保留明确的 UV_CONFIG_FILE，让本地和容器里的依赖解析更可复现。需要临时使用清华源时，可在仓库根目录准备：

[[index]]
name = "tsinghua"
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/"
default = true

启动和重启默认按指纹判断是否需要构建。需要明确复用已有镜像时，可对本次命令增加 --no-build：

./planet.sh start --no-build
./planet.sh restart -a --no-build

该选项只影响 AI Provider，不会关闭其他服务的启动检查；缺少本地镜像时直接报错，也不会把旧镜像的指纹更新成当前代码。已有 Compose v2 时，构建、启动和能力检查只使用 v2，失败直接保留错误；只有未检测到 v2 时才考虑 v1。

构建较慢时按层排查：

现象	常见原因	处理方式
transferring context 很大	build context 含前端资源等无关文件	.dockerignore 只发送必需文件
uv sync --frozen 下载较慢	首次构建、缓存为空或 uv 镜像源未配置	等待首次完成，后续复用 BuildKit 缓存；必要时配置 uv.toml
改密钥后仍是旧配置	容器未重启	./planet.sh restart -a
修改代码但镜像未重建	fingerprint 与镜像 label 一致	确认改动是否进入 aiprovider/、Dockerfile 或 Python 依赖；必要时删除 planet-aiprovider:latest 后重试

SMTP 邮件（公开注册依赖）

公开注册和邮箱验证依赖 SMTP。管理员在控制台 /settings -> SMTP 邮件 子 tab 中填写主机、端口、账号、密码、发件地址、TLS 模式，然后用"发送测试邮件"按钮验证。配置同时写入 system_settings.smtp 表行。

未配置时 POST /api/v1/auth/register 返回 503 EMAIL_PROVIDER_NOT_CONFIGURED，前端的注册流程会给出明确提示。运维兜底方式是 ./planet.sh createuser。

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 验证匹配、双语编号和输出一致性。

错误编号	匹配片段（分号分隔）	原因／已确认的故障现象	处理建议
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	—	尚未归类，不能从现有证据确认原因。	保留完整错误和执行命令；确认根因后补充本表、中英文说明及回归用例。

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 检查。

故障排查顺序

./planet.sh health        # 1. 看服务状态
./planet.sh log           # 2. 看最近日志
./planet.sh log -f        # 3. 按模块查看
./planet.sh log -b
./planet.sh log -a
./planet.sh restart -f    # 4. 只重启有问题的模块
./planet.sh restart -b
./planet.sh restart -a
./planet.sh restart -d    # 5. 数据库 / 缓存异常时
./planet.sh restart       # 6. 仍无法恢复时全量重启

开发命令约定

后端和脚本初始化统一使用锁文件：

uv python install 3.14
uv sync --frozen --group dev

--frozen 会拒绝隐式改写 uv.lock，适合新机器、CI 和 Docker 构建。需要升级依赖时，应先在开发机明确更新 pyproject.toml / uv.lock，再提交锁文件。

前端必须使用 Bun：

cd frontend
bun install
bun run dev
bun run build

不要使用 npm run ...。项目在 WSL / Windows 混合环境优先依赖 Bun，避免 Node/npm 路径差异。

./planet.sh start / init 会在启动前执行一次 bun install，而不是只检查 Vite 入口文件是否存在。这样新设备、清过 node_modules 的环境或 lockfile 已变更的环境，都能在进入控制台前同步前端依赖，避免动态 import 因缺失依赖返回 500。

验证前端构建：

source ~/.zshrc && bun run build

开发时继续使用 bun run dev，Vite HMR 会在保存源码后刷新浏览器。bun run build 只生成 dist 产物，不会刷新已经打开的 dev 页面。

需要看生产包并在构建成功后自动刷新时使用：

bun run preview:auto

只想监听源码并持续构建，不启动预览服务时使用：

bun run build:watch

后端依赖通过 uv 管理：

uv sync
uv run pytest backend/tests/test_otp_service.py

Earth 国界 PMTiles 操作步骤

1. 在控制台 运维与配置 -> 智能星球内容 -> 国界精度 保存国界源配置；本机配置写入 config/earth-boundary-sources.local.json，不要提交。
2. 点击“构建高精国界”，或在 Earth 页面工具栏齿轮中切到“高精”触发首次构建。后端会下载三类源到 data/earth-boundary-sources/，生成 source manifest，并调用 PMTiles 构建脚本。
3. 构建器需要本机 PATH 里有 tippecanoe 和 pmtiles。缺工具时接口返回明确错误，不会写入数据源采集记录。
4. 构建成功后应输出 frontend/public/earth/data/boundaries/earth-boundaries-china-pov-v1.pmtiles 和对应 manifest。
5. 部署后打开智能星球，开启“国界线”，放大中国东南海岸、台湾、海南、南海、藏南、科索沃、加沙等区域验证 hover 和边界口径。
6. 如果本地没有高精 manifest/PMTiles，Earth 会使用 frontend/public/earth/data/countries-admin0.min.geojson 低精度 fallback；如果高精产物存在但瓦片请求失败，按 PMTiles range 请求、manifest provider、Nginx .pmtiles 静态返回和 sha256 一致性排查。

相关文档

• planet.sh 启动机制
• 系统服务控制
• Docker + Compose + Buildx 升级
• 数据采集系统