# Planet 运维手册

这份手册面向部署、值班和二次开发的运维人员。客户面向的 UI 使用流程见 [Planet 使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md)，本手册只覆盖 shell、Docker、日志、环境变量和故障排查。

## 首次启动

```bash
./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` 命令式创建。

可指定端口：

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

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

## 启停与按模块重启

停止全部：

```bash
./planet.sh stop
```

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

按模块重启：

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

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

## 破坏性重置

```bash
./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，后端会优先用保留的下载缓存重新写入数据库；如果下载缓存也不存在，只能等待 CelesTrak 下一次更新窗口或使用 Space-Track 作为 fallback。

## 健康检查

```bash
./planet.sh health
```

会检查：

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

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

## 日志

最近日志：

```bash
./planet.sh log
```

持续跟随：

```bash
./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 容器日志
```

## 命令式创建用户

```bash
./planet.sh createuser
```

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

适用场景：

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

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

## 局域网 / WSL 访问

```bash
./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 版本：

```powershell
wsl -l -v
```

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

```powershell
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 防火墙放行。

建议按顺序排查：

```bash
# 在运行 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 处理；自动请求被取消时，手动兜底命令如下：

```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` |

推荐写法：

```bash
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 展开时显式启用：

```bash
PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a
```

完全忽略 `~/.zshrc`：

```bash
PLANET_LOAD_ZSHRC_ENV=0 ./planet.sh start -a
```

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

```bash
./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`，让本地和容器里的依赖解析更可复现。需要临时使用清华源时，可在仓库根目录准备：

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

构建较慢时按层排查：

| 现象 | 常见原因 | 处理方式 |
| --- | --- | --- |
| `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}` 控制。

## 故障排查顺序

```bash
./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. 仍无法恢复时全量重启
```

## 开发命令约定

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

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

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

前端必须使用 Bun：

```bash
cd frontend
bun install
bun run dev
bun run build
```

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

验证前端构建：

```bash
source ~/.zshrc && bun run build
```

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

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

```bash
bun run preview:auto
```

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

```bash
bun run build:watch
```

后端依赖通过 uv 管理：

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

## Earth 国界 PMTiles 操作步骤

1. 在控制台 `运维与配置 -> Earth 内容 -> 国界精度` 保存国界源配置；本机配置写入 `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. 部署后打开 Earth，开启“国界线”，放大中国东南海岸、台湾、海南、南海、藏南、科索沃、加沙等区域验证 hover 和边界口径。
6. 如果本地没有高精 manifest/PMTiles，Earth 会使用 `frontend/public/earth/data/countries-admin0.min.geojson` 低精度 fallback；如果高精产物存在但瓦片请求失败，按 PMTiles range 请求、manifest provider、Nginx `.pmtiles` 静态返回和 sha256 一致性排查。

## 相关文档

- [planet.sh 启动机制](/home/ray/dev/linkong/planet/docs/technical/zh/ops-planet-sh-startup.md)
- [系统服务控制](/home/ray/dev/linkong/planet/docs/technical/zh/backend-system-service-control.md)
- [Docker + Compose + Buildx 升级](/home/ray/dev/linkong/planet/docs/technical/zh/ops-docker-compose-buildx-upgrade.md)
- [数据采集系统](/home/ray/dev/linkong/planet/docs/technical/zh/backend-collectors.md)