Monolith 博客系统完整部署教程（macOS）

Monolith 是一套运行在 Cloudflare 全球边缘网络上的现代化无服务器博客系统，无需运维，全球延迟 < 50ms。

前置条件

  • macOS 系统（Apple Silicon M1/M2/M3 或 Intel 均可）
  • 一个 Cloudflare 账号（免费套餐即可）
  • 稳定的网络连接

第一步：安装 Node.js（通过 nvm）

推荐使用 nvm 安装 Node.js，避免权限问题，且完全兼容 Apple Silicon。

打开终端（Terminal），运行：

1
2
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

关闭终端，重新打开，然后继续：

1
2
3
4
5
6
7
8
# 安装 Node.js 20（LTS）
nvm install 20
nvm use 20
nvm alias default 20

# 验证安装
node -v   # 应显示 v20.x.x
npm -v    # 应显示 10.x.x

⚠️ macOS 注意：不要用 brew install wrangler，Apple Silicon 上 Homebrew 可能拿到 x86_64 版本跑 Rosetta，偶发段错误。始终用 npx wrangler（自动是 ARM64）。

第二步：登录 Cloudflare（Wrangler）

1
npx wrangler login

会自动打开浏览器，点击授权，终端显示 Successfully logged in 即完成。

macOS Sequoia 15+ 用户：若弹出「无法验证开发者」对话框，前往「系统设置 → 隐私与安全性 → 仍要允许」即可。

第三步：克隆项目并安装依赖

1
2
git clone https://github.com/one-ea/Monolith.git && cd Monolith
cd client && npm install && cd ../server && npm install && cd ..

第四步：创建 Cloudflare 云端资源

4.1 创建 D1 数据库

1
npx wrangler d1 create monolith-db

执行后终端会输出类似：

1
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

复制这个 ID，然后编辑配置文件：

1
open -e server/wrangler.toml

找到 [[d1_databases]] 段落，替换 database_id：

1
2
3
4
5
[[d1_databases]]
binding = "DB"
database_name = "monolith-db"
database_id = "你刚才复制的uuid"   # ← 替换这里
migrations_dir = "src/migrations"

保存文件。

4.2 创建 R2 存储桶（用于图片等媒体文件）

1
npx wrangler r2 bucket create monolith-assets

第五步：生成并配置密钥

Monolith 需要三个密钥，缺一不可。

5.1 生成密钥

1
2
3
export ADMIN_PASSWORD="$(openssl rand -base64 24)"
export JWT_SECRET="$(openssl rand -base64 48)"
export REACTION_SALT="$(openssl rand -hex 16)"

5.2 查看并保存密码

1
2
3
echo "ADMIN_PASSWORD=$ADMIN_PASSWORD"
echo "JWT_SECRET=$JWT_SECRET"
echo "REACTION_SALT=$REACTION_SALT"

⚠️ 务必把 ADMIN_PASSWORD 的值复制保存好，这是登录 /admin 后台的密码！

5.3 上传密钥到 Cloudflare

1
2
3
4
5
cd ~/Monolith/server
echo "$ADMIN_PASSWORD" | npx wrangler secret put ADMIN_PASSWORD --name monolith-server
echo "$JWT_SECRET"     | npx wrangler secret put JWT_SECRET     --name monolith-server
echo "$REACTION_SALT"  | npx wrangler secret put REACTION_SALT  --name monolith-server
cd ..

三个均显示 ✨ Success! Uploaded secret 即成功。

密钥 用途
ADMIN_PASSWORD 后台 /admin 登录密码
JWT_SECRET Session token 签名密钥
REACTION_SALT 文末 Reaction 匿名 ID 加盐

第六步：一键部署到 Cloudflare

1
2
3
cd ~/Monolith
npm install
npm run deploy:cloudflare

脚本会自动按顺序完成：

  1. 应用远程数据库迁移
  2. 写入后端密钥（ADMIN_PASSWORD / JWT_SECRET）
  3. 部署 Cloudflare Workers 后端
  4. 写入 Pages 的 API_BASE 环境变量
  5. 构建前端
  6. 部署 Cloudflare Pages 前端

全部完成后终端显示「部署流程完成」即成功。

第七步：验证部署

7.1 检查后端健康

浏览器打开（替换为你自己的 Worker 地址）：

1
https://monolith-server.<你的subdomain>.workers.dev/api/health

应返回：{"ok":true,...}

7.2 登录管理后台

1
https://monolith-client.pages.dev/admin

输入第五步保存的 ADMIN_PASSWORD，看到「主页 / 文章 / 媒体 / 设置」面板即部署成功 🎉

7.3 功能验证清单

  • 后端健康检查返回 ok: true
  • /admin 可以正常登录
  • 新建一篇测试文章并保存成功
  • 媒体上传正常

日常更新方法

最常用：拉取新代码并重新部署

1
2
3
cd ~/Monolith
git pull
npm run deploy:cloudflare

只更新密钥（无需重新部署）

1
2
3
cd ~/Monolith/server
npx wrangler secret put ADMIN_PASSWORD
# 输入新密码，回车，立即生效

只重新部署前端

1
2
cd ~/Monolith
npm run deploy:cloudflare -- --skip-migrate --skip-server

只重新部署后端

1
2
cd ~/Monolith
npm run deploy:cloudflare -- --skip-client

常见问题排查

问题 解决方法
wrangler: command not found 用 npx wrangler 替代
登录后台密码不对 重新运行 npx wrangler secret put ADMIN_PASSWORD 设置新密码
Pages 部署成功但 /api/* 404 检查 Cloudflare Dashboard → Pages → 环境变量是否有 API_BASE
D1 迁移报 database not found 检查 server/wrangler.toml 的 database_id 是否填写正确
健康检查 /health 返回 404 正确路径是 /api/health，不是 /health
PWA 旧版本不更新 Chrome: F12 → Application → Service Workers → Unregister，再强制刷新
OAuth 部署 429 限流 等待 60 秒后重试

重要信息备忘

部署完成后，建议把以下信息保存到安全的地方：

1
2
3
4
博客前端：https://monolith-client.pages.dev
管理后台：https://monolith-client.pages.dev/admin
后端地址：https://monolith-server.<subdomain>.workers.dev
管理密码：（你生成的 ADMIN_PASSWORD）

参考资料

教程整理日期：2026 年 4 月