Starlr Forum 从零部署完整教程：单 Worker 同域部署实测

星辰旅人 · 2026-11-02 14:35:27 · 浏览 5 · 回复 0

Starlr Forum 从零部署完整教程：小白也能跟着做

这篇教程把后端仓库和前端仓库的两份 README 合在一起，改写成给新手的版本：每一步都先讲清楚这是在干什么，再给命令，照着敲就行。内容按 2026-11-01 的真实从零重建实测整理过，敏感信息（资源编号、密钥、令牌、密码）一律不写原文，看到尖括号的地方换成你自己的。

部署完就是这个样子（演示站实拍）

图片

先看一眼成品，可以点开看看：https://starlr-demo-forum.wwwaaa123123.workers.dev

一、这是什么？要准备什么？

Starlr Forum 是一个论坛程序，分成两部分，缺一不可：

部署完你会得到一个属于你自己的论坛：可以注册、发帖、回帖、搜帖子，还有管理后台可以改名字、管用户、管帖子。

开始之前，先准备好这 3 样东西：

  1. 一个 Cloudflare 账号：去 Cloudflare 官网免费注册一个就行，免费额度足够小论坛起步。
  2. 一台电脑：装好 Git（用来下载代码）和 Node.js（版本号 20 或更高）。打开终端输入 node -v，能看到 v20 以上的数字就行。
  3. 一个地址：第一次部署不用买域名，先用 Cloudflare 免费给的 workers.dev 地址跑起来（就是上面演示站那种地址）。以后有了自己的域名，再绑定上去。

全程不用改任何源代码。跟着做下来，第一次操作建议留出半小时，慢慢来。

二、名词小词典（只看一次就行）

后面会反复出现这几个词，先认一下：

三、第一步：把两份代码下载下来

打开终端，先进到你想放代码的文件夹，然后依次运行：

git clone https://github.com/wwwaaa123122/starlr-forum-backend.git
git clone https://github.com/wwwaaa123122/starlr-forum-frontend-x.git

下载完你会看到两个文件夹：starlr-forum-backend（后端）和 starlr-forum-frontend-x（前端）。这两个文件夹必须放在同一个文件夹里面、并排摆着，因为后端要去隔壁文件夹找前端打包好的页面，摆错位置就找不到了。

然后分别装好它们需要的依赖包（就是程序运行要用的零件）：

cd starlr-forum-backend && npm ci
cd ../starlr-forum-frontend-x && npm ci

注意：这里用的是 npm，不是 pnpm。看到命令跑完、没有报错红字，就算成功。

偷懒办法：后端 README 里还有一个一键脚本 npm run setup，在后端文件夹里运行后会自动建好下面的云资源并生成配置文件，跑完它会打印剩下的手动步骤。下面为了让你知道每一步在干什么，还是按手动步骤讲，你也可以先试一键脚本。

四、第二步：登录你的 Cloudflare 账号

回到后端文件夹，运行：

cd ../starlr-forum-backend
npx wrangler login

这条命令会在浏览器里打开 Cloudflare 的授权页面，点确认登录就行（也可以用设备码方式，按提示操作）。登录完再运行一条命令确认身份：

npx wrangler whoami

能看到你的账号名和一串权限，说明登录成功了。后面所有操作都要靠这个登录状态。

五、第三步：创建三个云资源

还是在后端文件夹里，依次运行这三条命令，分别创建数据库、小本本和图片桶：

npx wrangler d1 create starlr-demo-db
npx wrangler kv namespace create starlr-demo-forum-kv
npx wrangler r2 bucket create starlr-demo-uploads

名字里的 starlr-demo-* 只是本次演示用的名字，你可以换成你自己的名字，但后面配置文件里填的名字要和这里一致。

六、第四步：写好配置文件

后端文件夹里有一个模板文件 wrangler.example.jsonc，先复制一份出来，真正用的就是复制出来的这份（它已经被设置成不会传到代码仓库里，放心填）：

cp wrangler.example.jsonc wrangler.prod.jsonc

打开 wrangler.prod.jsonc，只需要改下面这几处，其他地方不用动：

{
  "name": "starlr-demo-forum",           // 你的 Worker 名字，小写字母、数字、连字符
  "assets": {
    "directory": "../starlr-forum-frontend-x/dist"   // 前端打包好的页面位置，不用改
  },
  "d1_databases": [
    { "binding": "DB", "database_name": "starlr-demo-db",
      "database_id": "<把上一步记下的 database_id 粘贴到这里>" }
  ],
  "kv_namespaces": [
    { "binding": "CACHE", "id": "<把上一步记下的 KV 的 id 粘贴到这里>" }
  ],
  "r2_buckets": [
    { "binding": "UPLOADS", "bucket_name": "starlr-demo-uploads" }
  ],
  "vars": {
    "SITE_URL": "https://starlr-demo-forum.wwwaaa123123.workers.dev",
    "JWT_ISSUER": "https://starlr-demo-forum.wwwaaa123123.workers.dev",
    "JWT_AUDIENCE": "api"
  }
}

这里讲清楚三个最容易填错的地方：

特别提醒：当前版本的代码里没有 ADMIN_INITIAL_PASSWORD 这个东西，不要按网上旧资料去加它。管理员是怎么来的，后面第八步会讲。

七、第五步：设置一把钥匙（密钥）

登录凭证需要一把钥匙来签名，这把钥匙只存在 Cloudflare 那边，运行下面这条命令，钥匙会直接写进 Cloudflare 的保密设置里，不会保存在你的电脑上，也不会进代码仓库：

node scripts/generate-jwt-keys.mjs --print | npx wrangler secret put JWT_SIGNING_KEYS -c wrangler.prod.jsonc

运行完可以用这条命令检查一下，只能看到名字、看不到钥匙本身，这就对了：

npx wrangler secret list -c wrangler.prod.jsonc

应该只能看到 JWT_SIGNING_KEYS 这一个名字。以后想换钥匙，重新生成一次再写进去就行，换完所有人要重新登录一次。

八、第六步：建表

数据库还是空的，先把装数据的格子造好。迁移文件都在后端文件夹的 migrations/ 里面，从 0001 到 0011，一条命令全部跑完：

npx wrangler d1 migrations apply starlr-demo-db --remote -c wrangler.prod.jsonc

看到 11 条全部通过，就说明表建好了，里面还会自动放进 4 个默认板块：站务公告、技术分享、闲聊灌水、问答求助。已经建好的表不要再去改迁移文件的内容，以后要改，加新的迁移文件。

九、第七步：打包前端页面

去前端文件夹，把页面打包出来：

cd ../starlr-forum-frontend-x
npm ci && npm run build

跑完会生成一个 dist/ 文件夹，里面就是打包好的页面。看到 built in 加几秒的字样就是成功了（可能会有一行 chunk 太大的提示，不用管，不影响）。

这里有个重点，也是新手最容易踩的坑：前端只有一个构建用的变量叫 VITE_API_BASE。咱们这种页面和接口用同一个地址的部署方式，这个变量要留空，什么都不用填，接口会自动走相对路径。只有把前端和后端分开放在两个地址时，才需要在构建时填接口地址。

还有一点很省事：论坛的名字、标语、注册开关这些，都不用改前端代码。它们都是后端下发给前端的，论坛跑起来后去管理后台「站点设置」里改，刷新页面就生效。

十、第八步：上线

回到后端文件夹，一条命令上线：

cd ../starlr-forum-backend
npx wrangler deploy -c wrangler.prod.jsonc

点回车之前，先对照检查一遍：云资源建好了、配置文件填好了、钥匙设置好了、表建好了、前端打包好了。命令里一定要带上 -c wrangler.prod.jsonc，不要用成本地开发的配置。

部署成功后，命令输出里会给一个地址，和你配置文件里 SITE_URL 填的地址一致。打开这个地址，能看到论坛首页，就说明上线成功了。

十一、第九步：注册第一个账号，你就是站长

打开你的论坛地址，点注册，注册第一个账号。这个账号会自动成为管理员（站长），而且邮箱会被当作已验证。不需要什么初始密码，第一个注册的就是站长。

注册和登录时，账号那一栏填的是 identifier（可以是用户名），不要被名字绕晕。登录后，页面上会出现「管理后台」「发帖」这些入口，点进管理后台就能改站点名字、开关注册、管用户和帖子。

管理后台里常用的几样东西：

十二、检查一下是不是真的成功了

在终端里运行下面几条，看看返回的是不是预期的样子（把地址换成你自己的）：

curl -A "Mozilla/5.0" https://你的地址/api/health
# 应该返回 {"status":"ok"}

curl -A "Mozilla/5.0" https://你的地址/api/config
# 应该返回一串 JSON，里面有你的站点名

curl -A "Mozilla/5.0" https://你的地址/api/posts
# 刚建好、还没人发帖时，应该返回空列表，这是正常的

注意：用脚本去访问时要带上 -A "Mozilla/5.0"（假装自己是浏览器），不然 Cloudflare 可能会直接挡掉，返回 403，这不是论坛的毛病。

十三、新手常见问题

| 遇到的问题 | 先看这里 |
|---|---|
| 部署时说找不到数据库 | 配置文件里的 database_id 和 Cloudflare 里实际的库对不上，运行 npx wrangler d1 list 核对一下 |
| 打开页面一片空白 | 前端没打包好，或者配置文件里页面文件夹的路径不对。先去前端文件夹重新 npm run build，确认 dist/ 文件夹存在 |
| 一登录就掉线、接口报 401 | JWT_ISSUER 和你实际打开的地址不一致；或者刚换过钥匙，旧的登录凭证全部作废了，重新登录就行 |
| 浏览器报跨域（CORS）错误 | 只有前后端分开部署时才会遇到，是后端 ALLOWED_ORIGINS 没写前端地址。咱们这种同地址部署不应该出现 |
| 构建失败 | 先重新 npm ci 再 npm run build，看报错里是不是 Node.js 版本太低，确认 node -v 是 20 或更高 |
| 注册后收不到验证邮件 | 很可能根本没配置发邮件的服务。没配置时系统会静默跳过，不影响注册；去管理后台「服务配置 → 邮件」里填好 Resend 的 Key 和发件人，或者让管理员在「用户」页手动帮你激活 |
| 注册提示人机校验失败 | 只配了公开钥匙、没配保密钥匙，或者域名没加进人机验证的允许名单。两个钥匙要配齐 |
| 发帖提示邮箱没验证 | 账号还没验证邮箱。管理员可以在「用户」页手动标记已验证，或者在站点设置里关掉「注册需要邮箱」 |

通用办法：先看实时日志 npx wrangler tail -c wrangler.prod.jsonc，日志里一般会直接写清楚错在哪，再去对绑定、钥匙和域名，不要乱改配置。

十四、跑起来之后的事

npx wrangler d1 export <你的数据库名> --remote -c wrangler.prod.jsonc --output backup-$(date +%F).sql

十五、最后说两句

上面这些步骤，照着顺序做下来，一个完全没接触过的新手也能把自己的论坛跑起来。哪一步卡住了，先看第十三节的常见问题，再看日志，实在不行就把报错信息贴到评论区。

部署中遇到问题，欢迎在评论区交流，我会逐一回复。

暂无回复