前后端分离（默认同源部署）¶

Realms 采用“前后端分离”的代码结构：

后端（Go / Gin）：提供数据面 /v1/*、/v1beta/*，以及管理面 JSON API /api/*
前端（Vite + React）：位于 web/，负责页面路由（/login、/dashboard、/admin/* 等），通过 /api/* 调用后端

但对普通用户/默认部署来说，Realms 推荐并默认采用 同源一体 的运行方式：前后端仍然在同一台服务器、同一域名/端口上提供服务（只是在代码层面拆分）。

这样做的好处是： - 免去跨域 Cookie、第三方 Cookie 限制带来的登录问题 - 只需要部署一个后端进程（或一个镜像），运维更简单

方式 A（默认推荐）：同源一体（单域/单端口）¶

在该模式下： - 后端提供 /api/*、/v1/* 等接口 - 同时也会提供前端静态资源，并对 /login 等页面路径做 SPA 回落（fallback 到 index.html）

默认镜像（前后端绑在一起）：flowerrealm/realms
在构建期会先构建前端（web/dist），再通过 -tags embed_web 将其 embed 到后端二进制中；运行时只需要启动后端容器即可（同源）。

如果你希望“前后端分离部署”（外置前端/独立站点），请使用 后端专用镜像： - flowerrealm/realms:backend（跟随最新 tag） - flowerrealm/realms:<TAG>-backend（固定版本）

1) 构建前端：

cd web
npm install
npm run build

2) 启动后端（默认会从 ./web/dist 提供静态资源）：

cd ..
go run ./cmd/realms

3) 访问： - http://<host>:<port>/login

相关环境变量： - FRONTEND_DIST_DIR：静态资源目录（默认 ./web/dist） - FRONTEND_BASE_URL：留空（表示同源提供前端）

如果你希望把前端静态资源部署到独立站点（例如 Nginx / CDN），可以：

1) 构建前端产物 web/dist 并部署到某个站点（示例：https://fe.example.com） 2) 在后端设置：

FRONTEND_BASE_URL="https://fe.example.com"

行为说明： - 后端遇到“非 API 且未命中路由”的请求时，会 301 重定向 到 FRONTEND_BASE_URL + 原始路径 - /api/*、/v1/* 等已注册的路由不受影响（仍由后端处理）

建议： - 若你使用 Docker 部署后端：优先选择 flowerrealm/realms:backend，减少镜像体积（不包含 embed 的前端产物）。

⚠️ 注意：如果前端与后端跨域，浏览器 Cookie/凭证策略会显著复杂（SameSite/CORS/第三方 Cookie 限制）。Realms 默认不推荐跨域部署；更推荐用反向代理把两者放到同域名下（同源）。

1) 启动后端（默认 8080）：

go run ./cmd/realms

2) 启动前端（默认 5173，已配置 proxy 到 8080）：

cd web
npm install
npm run dev

访问：http://localhost:5173/login

make dev

该模式会同时运行： - 后端 air 热重载（:8080） - 前端 npm run build -- --watch（持续更新 web/dist）

访问：http://127.0.0.1:8080/login

Realms 的部分 cookie session JSON API（例如 /api/token、/api/channel）要求请求携带：

Realms-User: <user_id>

并且后端会校验该值与当前会话用户一致，用于降低 CSRF 风险。