📝 docs: document the Hono backend runtime and dev topologies

- 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
2026-06-13 19:20:04 +00:00 · 2026-06-10 17:59:03 +08:00
parent 7eee9518ca
commit 2edc2b0ca4
3 changed files with 92 additions and 26 deletions
@@ -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
@@ -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.

@@ -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)。