KnowForge 全栈部署指南：API（Hono）+ Web + Admin

0阅读5分钟

架构一览

本项目是 Turborepo + pnpm monorepo，三个应用分工如下：

应用技术栈本地端口生产域名（示例）
apps/apiCloudflare Workers + Hono + D1 + R28787https://api.aistudy8.com
apps/webNext.js 16 用户前台3005https://aistudy8.com
apps/adminNext.js 16 管理后台3006https://admin.aistudy8.com
用户浏览器
    │
    ├─ aistudy8.com          → Web（Next.js）
    ├─ admin.aistudy8.com    → Admin（Next.js）
    └─ api.aistudy8.com      → API（Workers + Hono）
                                    ├─ D1 数据库
                                    ├─ R2 对象存储
                                    └─ Cron 定时任务

部署顺序建议：先 API（含 D1 迁移与 Secrets）→ 再 Web / Admin（配置 API 地址）→ 最后 DNS 与 OAuth 回调联调。

一、本地开发快速启动

# 仓库根目录
pnpm install
 
# 按需启动（建议开三个终端）
pnpm dev:api     # API，默认 http://127.0.0.1:8787
pnpm dev:web     # 前台，http://localhost:3005
pnpm dev:admin   # 后台，http://localhost:3006

API 本地初始化（首次 / 换电脑）

本地 D1 数据在 apps/api/.wrangler/，不进 git，换机器需重新初始化：

pnpm --filter @repo/api db:setup:local

复制环境变量模板：

cp apps/api/.dev.vars.example apps/api/.dev.vars

Web / Admin 复制各自 .env.example 为 .env，默认 API 地址为 http://127.0.0.1:8787。

注意：若 8787 被占用，Wrangler 可能自动改用 8788，导致前台登录 ERR_CONNECTION_REFUSED。可在 apps/api/package.json 的 dev 脚本加 --port 8787 固定端口，或同步修改前端 .env 中的 API 地址。

二、理解 wrangler.jsonc

API 的配置文件位于 apps/api/wrangler.jsonc，Wrangler 据此启动 Worker、绑定资源并注入变量。

顶层 = 默认环境（本地 development）

块作用
d1_databases绑定 D1，代码里用 env.DB
r2_buckets绑定 R2，代码里用 env.AVATAR_BUCKET
vars非敏感环境变量（域名、TTL、模型名等）
triggers.crons定时任务（AI 资讯每 6 小时抓取）

env.remote-dev / env.production = 命名环境

通过 --env 切换：

pnpm dev:remote            # wrangler dev --env remote-dev
pnpm deploy:production     # wrangler deploy --env production

合并规则：先读顶层，再用 env.xxx 覆盖；d1_databases / r2_buckets 在命名环境里会替换为对应实例，不会与顶层叠加成两个库。

两类环境变量

类型配置位置示例
非敏感wrangler.jsonc → varsWEB_ORIGIN、DEEPSEEK_MODEL
敏感本地 .dev.vars；线上 wrangler secret putJWT_*、DEEPSEEK_API_KEY

生产环境当前域名配置（env.production.vars）：

WEB_ORIGIN=https://aistudy8.com
ADMIN_ORIGIN=https://admin.aistudy8.com
GITHUB_OAUTH_CALLBACK_URL=https://api.aistudy8.com/auth/web/github/callback

三、API 部署（Hono + Cloudflare Workers）

3.1 前置准备

pnpm install
cd apps/api
npx wrangler login

确认 env.production.d1_databases[0].database_id 为真实 UUID（占位符 33333333-... 必须替换）。

3.2 首次：创建云端资源

cd apps/api
 
# 创建生产 D1
npx wrangler d1 create ai-agent-production-auth
 
# 创建生产 R2
npx wrangler r2 bucket create ai-agent-production-avatars

将 d1 create 返回的 database_id 写入 wrangler.jsonc → env.production.d1_databases。

3.3 配置 Secrets

.dev.vars 不会随 deploy 上传：

npx wrangler secret put JWT_ACCESS_SECRET --env production
npx wrangler secret put JWT_REFRESH_SECRET --env production
npx wrangler secret put DEEPSEEK_API_KEY --env production
npx wrangler secret put GITHUB_OAUTH_CLIENT_SECRET --env production

JWT 建议使用 32 位以上随机字符串。

3.4 远程数据库迁移

本地 D1 与云端 完全独立：

npx wrangler d1 migrations apply ai-agent-production-auth --env production --remote

dev/seed-admin.sql 仅用于本地联调，不要直接用于生产。生产 admin 账号需单独创建或使用专用 seed。

3.5 部署 Worker

# 仓库根目录
pnpm --filter @repo/api deploy:production

成功后默认地址类似 https://api.<account>.workers.dev。

3.6 绑定自定义域名

Cloudflare Dashboard → Workers & Pages → 选中 api Worker → Domains & Routes → 添加：

api.aistudy8.com

验证：

curl https://api.aistudy8.com/system/ping

3.7 常用命令

场景命令
生产部署pnpm --filter @repo/api deploy:production
本地连接远程数据开发pnpm --filter @repo/api dev:remote
远程迁移wrangler d1 migrations apply ai-agent-production-auth --env production --remote
同步 TS 类型pnpm --filter @repo/api cf-typegen

3.8 后续更新

# 有新 migration 时
cd apps/api
npx wrangler d1 migrations apply ai-agent-production-auth --env production --remote
 
# 再部署
pnpm --filter @repo/api deploy:production

四、Web 部署（Next.js 用户前台）

Web 是标准 Next.js 16 应用，本地端口 3005，通过环境变量连接 API。

4.1 生产环境变量

在部署平台（Cloudflare Pages / Vercel 等）配置：

APP_ENV=production
API_BASE_URL=https://api.aistudy8.com
NEXT_PUBLIC_APP_ENV=production
NEXT_PUBLIC_API_BASE_URL=https://api.aistudy8.com

说明：

  • NEXT_PUBLIC_* 会暴露到浏览器，用于客户端直接请求 API（登录、GitHub OAuth 等）。
  • API_BASE_URL 供服务端组件 / Server Actions 使用。

4.2 构建命令

Monorepo 需在仓库根目录安装依赖后再构建：

pnpm install
pnpm --filter web build

本地验证生产构建：

pnpm --filter web build
pnpm --filter web start   # 默认 3000，可按需指定端口

4.3 Cloudflare Pages 部署（推荐，与 API 同账号）

配置项值
框架Next.js
根目录仓库根目录 /
构建命令pnpm install && pnpm --filter web build
Node 版本22+
自定义域名aistudy8.com（可同时配置 www 跳转）

在 Pages 项目 Settings → Environment variables 填入上一节的生产变量。

4.4 Vercel 部署（备选）

配置项值
Root Directoryapps/web
Build Commandcd ../.. && pnpm install && pnpm --filter web build
Install Commandpnpm install

同样在 Project Settings → Environment Variables 配置 API 地址。

4.5 GitHub OAuth 注意

Web 端 GitHub 登录的回调由 API 处理，GitHub OAuth App 的 Authorization callback URL 应为：

https://api.aistudy8.com/auth/web/github/callback

与 wrangler.jsonc 中 GITHUB_OAUTH_CALLBACK_URL 保持一致。

五、Admin 部署（Next.js 管理后台）

Admin 结构与 Web 类似，本地端口 3006，登录时浏览器直接请求 API。

5.1 生产环境变量

APP_ENV=production
API_BASE_URL=https://api.aistudy8.com
NEXT_PUBLIC_APP_ENV=production
NEXT_PUBLIC_API_BASE_URL=https://api.aistudy8.com

5.2 构建命令

pnpm install
pnpm --filter admin build

Admin 还支持 test 环境构建（使用 .env.test.local）：

pnpm --filter admin build:test
pnpm --filter admin start:test

5.3 Cloudflare Pages 部署

单独创建一个 Pages 项目（与 Web 分开）：

配置项值
构建命令pnpm install && pnpm --filter admin build
自定义域名admin.aistudy8.com
环境变量见 5.1

5.4 安全建议

  • Admin 建议设置 Cloudflare Access 或 IP 限制（可选）。
  • 生产环境勿使用 dev/seed-admin.sql 中的默认密码。
  • 确保 API 的 ADMIN_ORIGIN 为 https://admin.aistudy8.com，否则 CORS 会拦截登录请求。

六、全链路联调清单

部署完成后，按顺序自检：

# 1. API 健康检查
curl https://api.aistudy8.com/system/ping
 
# 2. CORS：从浏览器打开 admin 登录页，Network 里登录请求不应被 CORS 拦截
 
# 3. 前台首页能加载（本地文章 + 远程文章）
open https://aistudy8.com
 
# 4. Admin 登录
open https://admin.aistudy8.com/login
检查项预期
API ping返回 200
Web 首页正常渲染，API 失败时有本地文章兜底
Admin 登录不报 ERR_CONNECTION_REFUSED
GitHub OAuth回调到 api.aistudy8.com，登录后跳回 Web
AI 资讯 Cronproduction 已配 triggers.crons；本地可手动触发抓取

七、常见问题

现象原因 / 处理
Admin 登录 ERR_CONNECTION_REFUSEDAPI 未启动，或前端 API_BASE_URL 端口与 Wrangler 实际端口不一致
CORS 错误检查 API WEB_ORIGIN / ADMIN_ORIGIN 是否与访问域名完全一致（含 https://）
部署后表不存在未执行 wrangler d1 migrations apply ... --remote
AI 资讯无中文摘要未设置 DEEPSEEK_API_KEY secret
本地有数据、线上为空本地 .wrangler/ 与云端 D1 独立，需单独迁移与初始化
Cron 不触发确认 Workers 付费计划支持 Cron；本地 wrangler dev 不会自动跑定时任务

八、命令速查表

# ── 本地 ──
pnpm dev:api
pnpm dev:web
pnpm dev:admin
pnpm --filter @repo/api db:setup:local
 
# ── API 生产 ──
pnpm --filter @repo/api deploy:production
wrangler d1 migrations apply ai-agent-production-auth --env production --remote
 
# ── Web / Admin 构建 ──
pnpm --filter web build
pnpm --filter admin build

相关文件

文件说明
apps/api/wrangler.jsoncWorker、D1、R2、Cron、生产域名
apps/api/.dev.vars.example本地 Secrets 模板
apps/web/.env.exampleWeb 环境变量模板
apps/admin/.env.exampleAdmin 环境变量模板
apps/api/README.mdAPI 本地开发与数据库说明

按本文顺序操作，即可将 KnowForge 从本地 monorepo 完整发布到 aistudy8.com 生产环境。

评论 0

我
0 / 1000