# 智能星球运维手册

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

## Docker 初始化与访问权限

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

```bash
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` 单元存在时才给出启动该单元的建议。验证准备结果可执行：

```bash
docker info
docker compose version
docker buildx version
```

## 数据库初始化与连接检查

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

容器内部的 `pg_isready` 只检查服务是否接受连接，不能证明宿主机上的后端使用正确地址和密码。容器健康后，`init` 通过 `scripts/check_database_connection.py` 读取与后端相同的有效 `DATABASE_URL`，检查本地 PostgreSQL 的实际发布端口并执行只读 `SELECT 1`；通过后才显示“数据库服务已就绪”并创建表和默认数据。

- 如果本地实际端口映射仍缺失或不匹配，脚本会保留数据卷，按 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 侧监听。初始化不会为了占用数据库端口而自动结束其他数据库服务，也不会删除数据卷或重设密码。

## 首次启动

```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，后端会优先用保留的下载缓存重新写入数据库；如果 active 缓存不存在，会尝试有效 CelesTrak 分组缓存作为 fallback；如果下载缓存也不存在，只能等待 CelesTrak 下一次更新窗口或使用 Space-Track。控制台里的数据源“删除数据库”和“清理缓存”不会删除 `$PLANET_CACHE_DIR/downloads/celestrak`。

## 健康检查

```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 路径差异。

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

验证前端构建：

```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. 在控制台 `运维与配置 -> 智能星球内容 -> 国界精度` 保存国界源配置；本机配置写入 `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 启动机制](/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)