linkong/planet
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity
Files
fbca3815129898b44036d0577ccb2b543b46d5a7
planet/docs/technical/zh/ops-runbook.md
linkong fbca381512
Some checks failed
ci / backend (push) Has been cancelled
Details
ci / frontend (push) Has been cancelled
Details
ci / delivery (push) Has been cancelled
Details
release / images (push) Has been cancelled
Details
release: bump version to 0.62.0
2026-05-21 01:37:32 +08:00

9.4 KiB
Raw Blame History

Planet 运维手册

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

首次启动

./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 12345678 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 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
  • 局域网其他机器访问同一开发实例

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

构建较慢时按层排查：

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

故障排查顺序

./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：

cd frontend
bun install
bun run dev
bun run build

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

验证前端构建：

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. 在控制台 运维与配置 -> 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 一致性排查。

相关文档

Reference in New Issue View Git Blame Copy Permalink