7.6 KiB
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 # 前端: /tmp/planet_frontend.log
./planet.sh log -b # 后端: /tmp/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 只负责让前端和后端监听 0.0.0.0。WSL 中运行时，Windows 本机一般可以通过 localhost 访问，但局域网其他机器访问 Windows 局域网 IP 时还需要 Windows 端口转发和防火墙放行。
建议按顺序排查：
# 在运行 Planet 的 shell 中
curl http://localhost:3000
curl http://localhost:8000/health
ss -ltnp | grep -E ':3000|:8000'
如果看到 WSL 内部服务已经启动，但局域网 IP 仍访问失败，让 ./planet.sh start --allow-lan 启动临时 Windows relay。relay 会让 Windows 对外继续使用 3000 / 8000，并在 WSL 目标端口断开后自动退出。脚本会检测并请求管理员 PowerShell 删除旧 portproxy，也会检测 Windows 防火墙规则；缺少入站放行时会触发一次 UAC 管理员 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
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
局域网设备访问 Windows 对外端口，例如 http://<Windows局域网IP>:3000/earth。
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
后端依赖通过 uv 管理：
uv sync
uv run pytest backend/tests/test_otp_service.py