From 2edc2b0ca4fd2f8cd0b2269b68cf6779a3e10112 Mon Sep 17 00:00:00 2001 From: Innei Date: Wed, 10 Jun 2026 17:59:03 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20document=20the=20Hono=20?= =?UTF-8?q?backend=20runtime=20and=20dev=20topologies?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/development/start (en + zh-CN): replace the hono-lite POC note with the full picture — Next as shell, forwarder routes + guard, the two dev topologies and when the Next shell is actually needed (SSR auth pages / SPA template / middleware), standalone server-package commands, ~server alias and build pairing - AGENTS.md: backend architecture section (handlers live in apps/server, route shells are contractual and logic-free, how to add an endpoint), refreshed dev commands and structure tree --- AGENTS.md | 23 +++++++++++---- docs/development/start.mdx | 47 ++++++++++++++++++++++++------- docs/development/start.zh-CN.mdx | 48 +++++++++++++++++++++++++------- 3 files changed, 92 insertions(+), 26 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f07a35a214..95c2f31ce5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,14 +19,14 @@ lobehub/ ├── apps/ │ ├── desktop/ # Electron desktop app │ ├── cli/ # LobeHub CLI -│ └── server/ # Server service +│ └── server/ # Backend (Hono app — single source for all API handlers) ├── packages/ # Shared packages (@lobechat/*) │ ├── database/ # Database schemas, models, repositories │ ├── agent-runtime/ # Agent runtime │ └── ... ├── src/ -│ ├── app/ # Next.js App Router (backend API + auth) -│ │ ├── (backend)/ # API routes (trpc, webapi, etc.) +│ ├── app/ # Next.js App Router (shell + auth) +│ │ ├── (backend)/ # Thin route shells — forward to apps/server (guard-tested, no logic) │ │ ├── spa/ # SPA HTML template service │ │ └── [variants]/(auth)/ # Auth pages (SSR required) │ ├── routes/ # SPA page components (Vite) @@ -44,7 +44,7 @@ lobehub/ │ │ └── router/ # React Router configuration │ ├── store/ # Zustand stores │ ├── services/ # Client services -│ ├── server/ # Server services and routers +│ ├── server/ # Next-only SSR helpers + backend-proxy client (@/server/*) │ └── ... └── e2e/ # E2E tests (Cucumber + Playwright) ``` @@ -75,13 +75,24 @@ See the **spa-routes** skill (`.agents/skills/spa-routes/SKILL.md`) for the full ### Starting the Dev Environment ```bash -# SPA dev mode (frontend only, proxies API to localhost:3010) +# SPA dev mode (frontend only, proxies API to the local backend) bun run dev:spa -# Full-stack dev (Next.js + Vite SPA concurrently) +# Full-stack dev: Hono backend (:3011) + Next shell (:3010) + Vite SPA (:9876) bun run dev + +# Backend + SPA without Next — enough for everything except the SSR auth +# pages / SPA template service / Next middleware +bun run dev:hono-lite +bun run dev:login # dev-only Better Auth endpoint, issues a real session cookie ``` +### Backend Architecture + +- All API handlers live in `apps/server` (a Hono app). Import them via the `~server/*` alias (`apps/server/src/*`); `@/server/*` refers only to the Next SSR helpers left in `src/server/`. +- `src/app/(backend)/**/route.ts` files are thin forwarders (`fetchBackendRuntime`) — never put logic in them; `route-shell.guard.test.ts` enforces this. Their file paths, HTTP method export names, and segment config (`maxDuration`, `dynamic`) are contractual for the cloud repo's re-exports. +- New API endpoints: implement the handler in `apps/server/src/api-runtime/` (or the matching Hono sub-app), mount it on the Hono root app (`apps/server/src/hono/index.ts` / `api-hono`), and add the forwarder stub route file. + After `dev:spa` starts, the terminal prints a **Debug Proxy** URL: ```plaintext diff --git a/docs/development/start.mdx b/docs/development/start.mdx index fd80ff3e7f..3775155abc 100644 --- a/docs/development/start.mdx +++ b/docs/development/start.mdx @@ -77,18 +77,32 @@ for the complete setup process, including software installation, project configuration, Docker service startup, and database migrations. -### Hono-Lite Dev Runtime (POC) +### Backend Runtime & Dev Topologies -Alongside the classic `bun run dev` (Next + Vite), -the `apps/server` package ships a standalone Hono dev runtime — -`bun run dev:hono-lite` boots Hono on `:3011` and Vite on `:9876` -with **no Next.js process**. -It is intended for fast inner-loop work on the backend without -paying the Next dev-server cost, -and is currently a T1 dev-only POC -(no gray-release machinery, no production deploy target). +The backend lives entirely in the `apps/server` package as a Hono app. +Next.js is a thin shell: every `src/app/(backend)/**/route.ts` is a +uniform forwarder (`fetchBackendRuntime`) — in dev it proxies to the +standalone Hono server, in production it loads the vite-built +`apps/server/dist` in-process. The backend dependency graph never +passes through `next build`, and a guard test +(`src/app/(backend)/route-shell.guard.test.ts`) keeps route files +logic-free. -Typical flow: +Two dev topologies: + +| Mode | Command | Processes | +| ------------- | ----------------------- | ------------------------------------------------------ | +| **Classic** | `bun run dev` | Hono (`:3011`) + Next shell (`:3010`) + Vite (`:9876`) | +| **Hono-Lite** | `bun run dev:hono-lite` | Hono (`:3011`) + Vite (`:9876`), no Next | + +In day-to-day work, Hono-Lite is enough: the SPA, the full API surface, +and `bun run dev:login` (a dev-only Better Auth endpoint that issues a +real session cookie) all work without Next. You only need the classic +mode when touching what still renders inside Next — the SSR auth pages +under `src/app/[variants]/(auth)/` (signin / OAuth consent UI), the SPA +HTML template service, or Next middleware behavior. + +Typical Hono-Lite flow: ```bash bun run dev:docker # Docker services (Postgres, Redis, RustFS, SearXNG) @@ -97,6 +111,19 @@ bun run dev:login # open the local dev-login URL in your browser open http://localhost:9876 ``` +The server package is also self-contained: + +```bash +pnpm --filter @lobechat/server dev # standalone Hono dev server (loads repo-root .env) +pnpm --filter @lobechat/server build # vite SSR build -> apps/server/dist +pnpm --filter @lobechat/server start # node dist/standalone.js (env from shell/platform) +``` + +Imports use the `~server/*` alias for `apps/server/src/*`; +`@/server/*` refers only to the Next SSR helpers remaining in +`src/server/`. The root `build` script runs `build:hono` first so the +dist always pairs with the Next build. + See [`apps/server/README.md`](https://github.com/lobehub/lobehub/blob/canary/apps/server/README.md) for the routes served, port overrides, known gaps, and troubleshooting. diff --git a/docs/development/start.zh-CN.mdx b/docs/development/start.zh-CN.mdx index 284d1560bb..130fa2b46c 100644 --- a/docs/development/start.zh-CN.mdx +++ b/docs/development/start.zh-CN.mdx @@ -72,18 +72,33 @@ lobehub/ 了解完整的环境搭建流程， 包括软件安装、项目配置、Docker 服务启动和数据库迁移等步骤。 -### Hono-Lite 开发运行时（POC） +### 后端运行时与开发拓扑 -除经典的 `bun run dev`（Next + Vite）之外， -`apps/server` 包还提供了独立的 Hono 开发运行时 —— -`bun run dev:hono-lite` 会在 `:3011` 启动 Hono、在 `:9876` 启动 Vite， -**完全不启动 Next.js 进程**。 -该模式用于在不付出 Next 开发服务器成本的前提下， -专注于后端的快速内循环开发， -目前仅作为 T1 开发期 POC 提供 -（不包含灰度发布机制，亦不作为生产部署目标）。 +后端完整地以 Hono 应用的形态存在于 `apps/server` 包中。 +Next.js 只是一层薄壳：`src/app/(backend)/**/route.ts` +全部是统一的转发器（`fetchBackendRuntime`）—— +开发环境代理到独立的 Hono 服务器， +生产环境则在进程内加载 vite 构建的 `apps/server/dist`。 +后端依赖图完全不经过 `next build`， +并由守护测试（`src/app/(backend)/route-shell.guard.test.ts`） +保证路由文件零业务逻辑。 -典型启动流程： +两种开发拓扑： + +| 模式 | 命令 | 进程 | +| ------------- | ----------------------- | --------------------------------------------- | +| **Classic** | `bun run dev` | Hono（`:3011`）+ Next 壳（`:3010`）+ Vite（`:9876`） | +| **Hono-Lite** | `bun run dev:hono-lite` | Hono（`:3011`）+ Vite（`:9876`），无 Next | + +日常开发用 Hono-Lite 即可：SPA、完整 API、 +以及 `bun run dev:login`（仅开发环境注册的 Better Auth 端点， +直接签发真实 session cookie）都不需要 Next。 +只有在改动仍由 Next 渲染的部分时才需要 Classic 模式 —— +`src/app/[variants]/(auth)/` 下的 SSR 认证页 +（signin / OAuth consent 界面）、SPA HTML 模板服务、 +或 Next middleware 行为。 + +典型 Hono-Lite 启动流程： ```bash bun run dev:docker # Docker 服务（Postgres、Redis、RustFS、SearXNG） @@ -92,6 +107,19 @@ bun run dev:login # 在浏览器中打开本地开发登录链接 open http://localhost:9876 ``` +server 包本身也可独立运转： + +```bash +pnpm --filter @lobechat/server dev # 独立 Hono 开发服务器（自动加载仓库根 .env） +pnpm --filter @lobechat/server build # vite SSR 构建 -> apps/server/dist +pnpm --filter @lobechat/server start # node dist/standalone.js（env 由 shell / 平台提供） +``` + +导入约定：`~server/*` 指向 `apps/server/src/*`； +`@/server/*` 仅剩 `src/server/` 中的 Next SSR 辅助模块。 +根目录 `build` 脚本会先执行 `build:hono`， +确保 dist 始终与 Next 构建配套。 + 可服务的路由清单、端口覆盖、已知缺口与故障排查请参见 [`apps/server/README.md`](https://github.com/lobehub/lobehub/blob/canary/apps/server/README.md)。