Quick Start

🚀 快速开始

5 分钟跑起本地 Monolith 开发环境。

---

环境要求

工具	版本	用途
Node.js	≥ 18 LTS	运行时 (推荐用 nvm/fnm 管理)
npm	≥ 8	包管理
Wrangler	≥ 4.x	Cloudflare CLI (随项目自动安装)
Git	≥ 2.x	版本控制

---

1. 克隆 + 安装

git clone https://github.com/one-ea/Monolith.git
cd Monolith

# 一次安装所有 workspace（根 + client + server）
npm install

项目使用 npm workspaces，无需手动 cd client && npm install。

---

2. 配置后端密钥

在 server/ 目录下创建 .dev.vars：

# server/.dev.vars
ADMIN_PASSWORD=change_me_to_a_strong_password
JWT_SECRET=随机生成至少32位字符串
REACTION_SALT=另一个随机盐值

# 可选：切换数据库后端（默认 d1）
# DB_PROVIDER=turso
# TURSO_DATABASE_URL=libsql://your-db.turso.io
# TURSO_AUTH_TOKEN=eyJ...

# 可选：切换对象存储（默认 r2）
# STORAGE_PROVIDER=s3
# S3_BUCKET=...

⚠️ .dev.vars 与 .env* 已在 .gitignore，禁止提交。 💡 生成 JWT_SECRET：openssl rand -base64 48

---

3. 初始化本地 D1 数据库

cd server

# 应用所有迁移到本地 D1
npx wrangler d1 migrations apply monolith-db --local

# (可选) 灌入测试种子文章
npm run db:seed:test-posts:local

本地 D1 数据存储于 server/.wrangler/state/v3/d1/，删除即重置。

---

4. 启动开发服务器

需要两个终端并行：

终端 A：后端 Workers

cd server
npm run dev
# 监听 http://localhost:8787

终端 B：前端 Vite

cd client
npm run dev
# 监听 http://localhost:5173

Vite 已配置 dev proxy，所有 /api/* 自动转发到 localhost:8787，无需改代码。

---

5. 访问与登录

入口	说明
http://localhost:5173	博客前台
http://localhost:5173/admin/login	后台登录页 (直接访问)
双击 Logo / Ctrl+Shift+A	隐藏式后台触发
http://localhost:8787/api/health	后端健康检查

登录密码 = .dev.vars 中的 ADMIN_PASSWORD。

---

6. 常用脚本

# 根目录
npm run lint              # ESLint 全工程
npm run deploy:cloudflare # 一键部署到生产

# server/
npm run dev               # Workers 本地开发
npm run db:generate       # 修改 schema.ts 后生成迁移 SQL
npm run db:seed:test-posts:local

# client/
npm run dev               # Vite 开发
npm run build             # 构建到 dist/
npm run preview           # 本地预览生产构建

---

故障排查

Q: ADMIN_PASSWORD not set

.dev.vars 不存在或未在 server/ 目录下，确认路径与文件名拼写。

Q: /api/* 请求 404

后端未启动，确认终端 A 的 wrangler dev 还在运行。

Q: 数据库迁移报错

# 重置本地 D1
rm -rf server/.wrangler/state
cd server && npx wrangler d1 migrations apply monolith-db --local

Q: 前端报 Failed to fetch

检查浏览器控制台是否被广告拦截器误伤；切换到隐身窗口验证。

---

下一步

• 改第一篇文章 → 前端指南
• 加新 API 端点 → 后端指南
• 部署到生产 → 部署指南
• 接入 AI 助手 → MCP 集成