---
url: /docs/architecture.md
---
# 系统架构概览

## 请求如何流转

```mermaid
flowchart TD
  U[浏览器] --> W[公开站边缘入口]
  W -->|公开页面| S[Astro 静态页面]
  W -->|登录与工作台路径| A[React 工作台]
  W -->|接口路径| H[Hono 接口服务]
  H --> B[Better Auth 与业务接口]
  B --> D[Hyperdrive 与 PostgreSQL]
  H --> E[邮件与支付服务]
```

首页 `/` 始终返回公开网页，包括已经登录的用户。`/dashboard` 等私有路径交给工作台；工作台读取会话并决定是否跳转登录，接口再校验身份与数据归属。

## 三个部署单元

| 应用 | 职责 | 关键入口 |
| --- | --- | --- |
| 公开站 | 静态网页、工具、博客及请求分流 | `apps/web/worker.ts` |
| 工作台 | 单页应用、会话状态及私有页面 | `apps/app/wrangler.jsonc`（静态资源与单页回退） |
| 接口 | 认证与类型化业务接口 | `apps/api/worker.ts` |

公开站通过 `APP_SERVICE` 和 `API_SERVICE` 调用另外两个服务。接口使用两个 Hyperdrive 绑定；认证、权限、账单和写后读走无查询缓存的连接。

## 公开内容与私有数据

Astro 在构建时生成公开正文、元信息和博客页面；交互工具按需加载 React。搜索访问不需要登录或等待私有工作台脚本。用户历史和积分通过登录后的接口获取，不写入公开构建产物。

认证模块仍设置会话提示 cookie，但当前公开入口不据此将首页切换为工作台。该 cookie 不是授权凭据，历史设计见 [认证提示 cookie 决策](../adr/001-auth-hint-cookie.md)。

## 本地与线上

完整预览由 `scripts/preview.py` 启动各服务，再用 `scripts/local-gateway.ts` 在 4400 分流。线上使用 Worker 服务绑定。两者必须保持相同路径归属，相关检查在 `apps/app/lib/edge-routing.test.ts`。

构建顺序应让邮件模板先可供接口引用；使用根目录 `bun build`，避免手动漏掉依赖。部署依次更新接口、工作台和公开入口，细节见 [部署上线](../deployment/index.md)。