故障排查
按症状快速定位问题。始终先运行：
reactpress doctor
reactpress logs --tail 100
诊断命令速查
| 命令 | 用途 |
|---|---|
reactpress doctor | 环境、端口、DB、进程总览 |
reactpress doctor --show-logs | 失败时附带日志片段 |
reactpress logs -f | 实时跟踪 API 日志 |
reactpress logs --grep error | 过滤错误行 |
reactpress stop | 停止后干净重启 |
Monorepo：pnpm status、pnpm docker:dev:logs
安装与 init 失败
postinstall 超时 / 网络错误
全局安装时 bundled runtime 下载失败：
# 重试安装
npm install -g @fecommunity/reactpress --force
# 检查代理与 registry
npm config get registry
Node 版本过低
node -v # 需要 ≥ 20
init --force 后数据丢失
--force 会重置 .reactpress/ 与 SQLite。生产数据请先手动复制 .reactpress/reactpress.db（或 MySQL 场景下用 Monorepo 的 db backup / 外部备份工具）。
服务无法启动
端口被占用
doctor 输出中会标注 3000 / 3001 / 3002 占用。
# macOS / Linux 查看占用
lsof -i :3002
# 停止 ReactPress 后重试
reactpress stop
reactpress init
修改端口见 项目配置项。
API 启动但 Admin / 主题无法访问
| 现象 | 可能原因 | 处理 |
|---|---|---|
| :3000 无法打开 | web 进程未起 | Monorepo：pnpm dev:web；检查 logs |
| :3001 空白 | 主题未启用 | Admin → 外观 → 启用主题 |
| CORS 错误 | URL 配置不一致 | 核对 CLIENT_SITE_URL / SERVER_SITE_URL |
主题进程报错 REACTPRESS_THEME_NOT_FOUND
未安装或未启用主题。Admin 安装主题，或 Monorepo 确认 themes/hello-world 已在 registry。
数据库问题
SQLite 文件损坏
reactpress stop
mv .reactpress/reactpress.db .reactpress/reactpress.db.bak
reactpress init --force # 会清空数据，慎用
MySQL 连接 refused
pnpm docker:dev:status确认容器运行- 核对
.env中DB_HOST/DB_PORT/ 凭据 config.json中database.mode是否为embedded-docker
配置不同步
终端用户：同时更新 config.json 与 .env，再 reactpress stop → reactpress init。Monorepo 贡献者可使用仓库内完整 CLI 的 reactpress config --apply。勿只改 .env 而忘记 config 源。
内容与 API
Headless 401 / 403
- 检查
X-API-Key头 - Key 是否过期或被撤销
- 请求路径是否使用
/api/前缀
上传失败
uploads/目录写权限- 磁盘空间
- OSS 配置错误（若启用远程存储）
插件 Hook 不执行
- Admin 确认插件已启用
pnpm run build:plugins（开发态）- 重启 API
logs --grep插件 id
生产环境
OG / 图片 URL 错误
CLIENT_SITE_URL / SERVER_SITE_URL 仍为 localhost → 更新 config 并 --apply，重启服务。
HTTPS 混合内容
全站启用 HTTPS；媒体 URL 使用相对路径或 HTTPS CDN。
PM2 / Docker 部署
仍无法解决？
提交 GitHub Issue 时请包含：
- OS 与 Node 版本
@fecommunity/reactpress版本reactpress doctor完整输出reactpress logs --tail 200（脱敏后）- 复现步骤