273 lines
9.4 KiB
Markdown
273 lines
9.4 KiB
Markdown
# 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 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
|
||
- 局域网其他机器访问同一开发实例
|
||
|
||
`--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
|
||
```
|
||
|
||
构建较慢时按层排查：
|
||
|
||
| 现象 | 常见原因 | 处理方式 |
|
||
| --- | --- | --- |
|
||
| `transferring context` 很大 | build context 含前端资源等无关文件 | `.dockerignore` 只发送必需文件 |
|
||
| `uv sync` 下载较慢 | 首次构建或缓存为空 | 等待首次完成，后续复用 BuildKit 缓存 |
|
||
| 改密钥后仍是旧配置 | 容器未重启 | `./planet.sh restart -a` |
|
||
|
||
## 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. 仍无法恢复时全量重启
|
||
```
|
||
|
||
## 开发命令约定
|
||
|
||
前端必须使用 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)
|