RushWind CMS --- 三服务拓扑:core 领域层、双 BFF 薄代理与一份契约的双面输出
本文回答一个问题:一个内容平台为什么要拆成 core-service + 双 BFF 三个进程?BFF 里为什么连一句 SQL 都找不到?同一份 proto 契约又怎么同时长出 REST 和 gRPC 两张脸、喂饱五个前端?
RushWind CMS 是一套 Rust 全栈 Headless 内容平台。它的后端是三个进程:core-service 是唯一的领域层,独占 PostgreSQL 与 Redis,只对内暴露 gRPC;admin-api 与 app-api 是两道 BFF,对浏览器与小程序提供 REST + SSE。分工写成一条铁律(仓库根 AGENTS.md):
BFF 不碰数据库:admin-api / app-api 只做协议转换与转发(生成代理 + 手写面);数据访问只发生在 core-service。
这句话的含金量在于"只发生在"------不是规范建议,是结构事实:BFF 的代码里不存在数据库连接。本文从启动序列讲到生成器,把这套拓扑的每个接缝拆开。
一、三服务分工:数据只有一个主人
三个进程、四个端口,各管一段:
| 进程 | 端口 | 职责 |
|---|---|---|
| core-service | gRPC :6602 | 领域层:认证内核 + 全部领域服务,独占 PG/Redis,不对外暴露 |
| admin-api | REST :6600 / SSE :6601 | 管理 BFF:后台全部路由 |
| app-api | REST :6700 / SSE :6701 | 前台 BFF:门户、注册登录、游客评论、公开读 |
core-service 的 main.rs 只有三件事------读配置、连库并引导、起 gRPC:
rust
// backend/services/core-service/src/main.rs
//! The core domain service entry: loads the embedded config defaults
//! (env overrides win), connects Postgres + Redis exclusively (the
//! BFFs never touch the database), runs the fresh-database bootstrap
//! (golden DDL + system seed + demo seed), and serves the domain gRPC
//! face (:6602 by default).
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let cfg = Config::load()?;
let state = Arc::new(AppState::connect(cfg.clone()).await?);
store::bootstrap::run(&state.db).await?;
let addr: std::net::SocketAddr = cfg.grpc_addr.parse()...;
let listener = tokio::net::TcpListener::bind(addr).await?;
tonic::transport::Server::builder()
.add_routes(server::registry(state))
.serve_with_incoming(tokio_stream::wrappers::TcpListenerStream::new(listener))
.await?;
Ok(())
}
空库引导值得一格:数据库全新时自动跑四段 SQL------schema、系统种子、菜单种子、演示数据。已有的库一行不动,演进交给黄金 DDL 管线:
rust
// backend/crates/store/src/bootstrap.rs
/// Applies schema + system seed + demo seed when the database is fresh.
/// Existing databases (already carrying the schema) are left untouched ---
/// the golden-DDL pipeline owns evolution.
pub async fn run(db: &DatabaseConnection) -> Result<(), sea_orm::DbErr> {
if crate::tables_present(db).await? {
return Ok(());
}
exec_statements(db, crate::SCHEMA_SQL).await?;
exec_statements(db, crate::SEED_SQL).await?;
exec_statements(db, crate::MENUS_SEED_SQL).await?;
exec_statements(db, crate::DEMO_DATA_SQL).await?;
Ok(())
}
cargo run -p core-service 连上空库,等它跑完,一个带演示数据的完整内容平台就在 :6602 后面了------"从克隆到能点"的距离被压到一个启动序列。
界面上它长这样:管理后台的帖子管理、标签管理,与 Next.js 内容门户,全部消费同一个后端栈:
| 管理后台 · 帖子管理 | 管理后台 · 标签管理 |
|---|---|
![]() |
![]() |
前台 · 内容门户(Next.js)------四套前台(React / Vue / Taro / Flutter)共用 app-api 这一道 BFF:

二、一份契约,两张脸
三个进程对外的全部接口,来自同一棵 proto 树。契约 crate 的 build.rs 是一个纯配置值------它声明两件事:gRPC 面要生成(tonic: true) ,以及 REST 面按 root prefix 切成两张:
rust
// backend/crates/proto/build.rs
rushwind_proto_build::run(rushwind_proto_build::Build {
dep_data_files: &[
"pagination/v1/pagination.proto",
"google/api/httpbody.proto",
],
auth_free: AUTH_FREE,
redact_plan_expr: Some("crate::redact_plan()"),
tonic: true,
faces: &[
rushwind_proto_build::Face {
label: "admin",
module_file: "admin_gen.rs",
root_prefix: Some("admin/service/v1/"),
module_path: Some("crate::gen_admin::"),
},
rushwind_proto_build::Face {
label: "app",
module_file: "app_gen.rs",
root_prefix: Some("app/service/v1/"),
module_path: Some("crate::gen_app::"),
},
],
..
})
为什么要切两张?模块文档给了唯一理由:admin 与 app 的 BFF 存在同名服务 (两边各有一个 CategoryService、CommentService,语义不同),两张面按 root prefix 切片、各指各的模块,不能共享。切片是字节级保真的可达性遍历------每张面只含自己前缀下的契约,挂到 crate::gen_admin / crate::gen_app。
同一棵契约树于是长出三样东西:
- prost/pbjson 类型(两个 BFF 与 core 共用同一套消息类型,"BFF 与领域方法共享消息类型,代理层零映射");
- tonic gRPC 面------core-service 的全部领域服务实现的是它;
- gen-http REST 面------两张,分别是两个 BFF 的路由/绑定/trait/挂载产物。
类型一树,三处消费。契约改一处,gRPC 与两张 REST 面同时重算------没有"REST 改了 gRPC 忘了"这种事,因为它们不是两份代码,是同一份契约的两次投影。
三、薄代理:BFF 是一张生成的宏表
BFF 里的领域路由不是手写的转发函数,是一张生成的宏表。每个 proxy impl 长这样:
rust
// backend/services/admin-api/src/services/proxies.rs(生成物)
//! Generated thin-BFF proxies --- a table of passthrough_proxy! invocations
//! ... DO NOT EDIT; regenerate via scripts/gen-proxies.py
passthrough_proxy!(
services::admin_face for AccessKeyProxy {
client: access_v1::AccessKeyServiceClient<Channel>,
behaviors: behaviors,
methods: [
pass list_access_keys(ListAccessKeysRequest) -> ListAccessKeysResponse,
pass create_access_key(CreateAccessKeyRequest) -> CreateAccessKeyResponse,
...
]
}
);
宏的方法有四种形态(proxy_kit.rs 的自述):
pass------普通透传:带上操作者戳转发,原样返回领域的响应;drop------转发但丢弃响应体(BFF 脸返回Empty,领域返回实体);stub------契约有这个方法、领域还没落地:恒答 NOT_IMPLEMENTED;hand------委托给 BFF 手写行为模块(裸转发带不动的 BFF 专属语义)。
pass 分支的全部实现,就是这一段:
rust
// backend/services/admin-api/src/services/proxy_kit.rs
// pass --- the operator-stamped forward, the inner response back.
(@body pass $method:ident($req:ty) -> $resp:ty,
client: $client:ty, behaviors: $behaviors:ident,
state: $state:expr, ctx: $ctx:expr, msg: $msg:expr) => {
{
let mut core = <$client>::new($state.core_channel.clone());
Ok(core
.$method($crate::services::with_operator($ctx, $msg))
.await
.map_err($crate::services::map_status)?
.into_inner())
}
};
这张表是脚本(gen-proxies.py)从契约生成的------admin 侧 71 个 proxy impl、app 侧 12 个,文件头一行 DO NOT EDIT。BFF 的"薄"是生成的,不是自觉的:没有人为每个新接口手写一遍转发样板,也就没有人在转发层夹带私货的机会。
hand 形态最有代表性的是 app 侧的写方法------C 端 BFF 对内容写操作直接拒绝:
rust
// backend/services/app-api/src/services/proxies.rs
hand create(content_v1::CreatePageRequest) -> content_v1::Page => forbidden_mutation,
hand update(content_v1::UpdatePageRequest) -> content_v1::Page => forbidden_mutation,
hand delete(content_v1::DeletePageRequest) -> pbjson_types::Empty => forbidden_mutation,
同一个领域服务,admin 脸 pass 全放行,app 脸写方法逐个钉成 403------BFF 的差异化语义(谁能写、谁只能读)收敛在代理表的一列动词上。
stub 形态则是诚实的进度表态:契约先行于实现时,未落地的领域方法在 BFF 脸上明确回答 NOT_IMPLEMENTED,而不是静默 404 或 500。
四、认证链在 core:刷新轮换是一次 Lua 原子操作
认证内核住在 core-service。登录链的自述(authentication_service.rs 文件头):
rust
//! * Login (password grant): tenant resolve → credential verify (AES
//! unwrap + bcrypt + dummy equalizer) → user status → permission gate
//! (sys:access_backend / sys:access_app per client type) → HS256
//! access JWT + opaque refresh, registered in the `gwc:` key family;
//! refresh grant: verify-and-revoke rotation then re-mint.
//! * Logout: revokes every token of the user (SCAN prefix family).
//! * ValidateToken: the BFF session check (whitelist + blacklist).
口令侧三件套照旧:应用层 AES 加密传输、bcrypt 哈希存储、恒时假校验 (对不存在的用户跑一遍 dummy 哈希比对,让"探测哪些用户名存在"在时间侧信道上失效)。会话侧的键族按客户端类型与令牌种类分开:gwc:at:{client}:{uid}:{jti}、gwc:rt:{client}:{uid}:{jti}、黑名单 gwc:bl:{jti}。
最能代表"这种事该住在哪一层"的是刷新轮换。access token 与 refresh token 成对登记,刷新时验旧、吊旧、发新必须是原子的------两个请求同时拿同一个 refresh token 刷新,只能成功一个。这靠一段 Redis Lua 脚本保证:
rust
// backend/services/core-service/src/token.rs
const VERIFY_AND_REVOKE: &str = r#"
local rtKey = KEYS[1]
local atKey = KEYS[2]
local refreshToken = ARGV[1]
local stored = redis.call('GET', rtKey)
if not stored or stored ~= refreshToken then
return 0
end
redis.call('DEL', rtKey)
redis.call('DEL', atKey)
return 1
"#;
GET 比对与两把 DEL 在脚本里一次执行,Redis 单线程模型天然串行化------没有竞态窗口。轮换后旧 access token 一起作废,"刷新令牌泄露"的损害窗口被压到一次使用。
BFF 这边不碰会话存储,它的鉴权门是两段式 :本地先做 HS256 验签(格式对不对、签名过不过期,纯 CPU),会话校验阶段经适配器远程调 core 的 ValidateToken(白名单 + 黑名单的 verdict 只有一个来源):
rust
// backend/crates/auth/src/lib.rs
let claims = match rushwind_authn_gate::authenticate_and_check_session(
auth.as_ref(), checker.as_ref(), &headers, bearer.as_deref(),
).await {
Ok(claims) => claims,
Err(err) => {
return rushwind_http_binding::envelope::error_response(unauthorized(package, err));
}
};
req.extensions_mut().insert(claims);
next.run(req).await
免鉴权白名单同样在契约 crate 里编译期成形(auth_free.rs:admin 10 条、app 27 条,(service 全名, 方法名) 二元组),build.rs 消费它生成公开/门内双路由树------白名单是产物,不是配置文件,改它就是改代码,review 看得见。
五、横切件:分页管线与 SSE 扇出
分页。领域服务里没有一处手写的 count+offset。repo 侧只有一个 9 行的桥接文件,管线本体在框架:
rust
// backend/crates/store/src/paging.rs(全文)
//! The deployment bridge to the framework paging pipeline
//! (`rushwind-storage-seaorm-support`): ...
pub use rushwind_storage_seaorm_support::paging::fetch_paged;
fetch_paged 收一个 Select 基座和生成的 PagingRequest,内部完成过滤绑定(按列类型匹配算子:exact / in / gt / contains / icontains / range......)、count、切片。core-service 服务层 35 处调用,全是同一形状------分页参数的拼写(page / pageSize / noPaging / orderBy / query)全仓只有一个定义处。
SSE。core 领域服务产生"推给哪些人"的事件后,经 gRPC 响应的 metadata 回传给 BFF 扇出------base64 包着的 JSON 事件列表:
rust
// backend/services/admin-api/src/services/internal_message.rs
// The SSE fan-out: the payload metadata carries the base64 of a
// JSON event list [{uid, payload}, ...] --- decoded here, each event
// pushed to its user's stream.
if let Some(wire) = resp.metadata().get("x-sse-payload").and_then(|v| v.to_str().ok()) {
let decoded = base64::engine::general::STANDARD
.decode(wire).ok()
.and_then(|b| serde_json::from_slice::<serde_json::Value>(&b).ok());
if let Some(serde_json::Value::Array(events)) = decoded {
for ev in events {
let uid = ev.get("uid").and_then(|v| v.as_u64()).unwrap_or(0) as u32;
let payload = ev.get("payload").cloned().unwrap_or_default();
if uid > 0 && payload.is_object() {
let body = serde_json::to_string(&payload).unwrap_or_else(|_| "{}".to_string());
self.state.hub.publish(uid, body);
}
}
}
}
领域层不需要知道 SSE 的存在------它只是在 gRPC 响应上多带了一份收件人列表;BFF 的 Hub 按 uid 分发;连接侧再过一道归属校验:?stream= 参数必须等于令牌的 userId,否则 FORBIDDEN: stream user mismatch,循环里还要再滤一次 user_id != uid 的事件。"谁的事件推给谁"有两层检查,中间层的广播对订阅者不可见。
六、五个前端与两份清单
五个前端(管理后台 admin-react、门户 Next.js、门户 Nuxt、Taro 小程序、Flutter 应用)以快照形式随仓同步。快照的治理是双清单:
MANIFEST.sha256------快照终态的门:树上每个文件的哈希。手改任何一个文件,--check立刻红;UPSTREAM.sha256------上游基线:同步时(品牌覆写之前)的上游哈希,用于检测"上游源仓是否又动了"。
bash
# frontend/admin/sync-frontend.sh --check 的两道判
if d="$(diff -u "$MANIFEST" <(hash_tree "$DST") 2>&1)"; then
echo "OK: frontend/admin/$FRONTEND/ matches $FRONTEND.MANIFEST.sha256"
else
echo "ERROR: ... (hand-edit? run sync-frontend.sh $FRONTEND to rebuild)" >&2
status=1 # 手改 → 退出码 1
fi
# 漂移检测:源仓在时对比上游基线(CI 无源仓时自跳过)。
if ! diff -u "$UPSTREAM_MANIFEST" <(upstream_hash) >/dev/null; then
... status=2 # 上游漂移 → 退出码 2
fi
退出码分开了两种病因:手改快照 (退出 1,必须重建)与上游有新版(退出 2,该同步了)。CI 里它们都是门,本地则是有用的信号。
快照唯一被允许的对源偏离是品牌覆写 :同步后打一层 RushWind 品牌(logo / favicon / 文案 / meta),能改什么在一个登记表里逐条列明------logo 与二进制资产、公司名与链接、系统标题与版权行、index.html meta、env 应用标题。替换表是逐条显式声明,不做全局盲替换;设计 token、代码注释、树内冻结文档明确列为禁区,保持上游原样。双清单钉的是覆写之后的终态------diff 与登记表严格对账,多一行少一行都过不了门。
于是"五个前端接同一个后端"这件事的工程形态是:同步是唯一入口,覆写是唯一偏离,清单是唯一裁判。前端升级 = 跑一次同步脚本 + 复核登记表,而不是五次手工合并。
七、E2E:三服务栈上的 125 个断言
这套拓扑对不对,最后由一个脚本裁决。backend/scripts/e2e-test.sh 在三服务栈全起后跑 125 个断言点、11 个覆盖节:
bash
check() { if [[ "$3" == *"$2"* ]]; then ok; else fail; fi; }
# ......收尾打印 结果: PASS=$PASS FAIL=$FAIL
11 节覆盖:验证码与登录链(含错误密码反枚举)、门控路由(无 token / 假 token 的 401 信封形状)、13 个模块的种子数据读、CRUD 写路径、刷新轮换与登出全吊销、app 面(注册 / 游客评论 / 公开读)、权限与审计、聚合面、multipart 文件上传下载(MinIO)、SSE 与 CORS、以及边界面(Range 206/416、草稿不可见、待审评论不可见、注册链跨租户回退)。
值得注意的不只是数量,是断言的层级:认证链的断言(fresh jti、轮换后旧 token 401、登出全吊销)打的是 core 的会话语义;门控路由的断言打的是 BFF 的门;草稿不可见打的是领域规则。三服务的每一道接缝,都有一节断言对着它。
八、机制 × 关键决策 × 失败模式
| 机制 | 关键决策 | 失败模式(若无此决策) |
|---|---|---|
| core 独占数据 | BFF 无数据库连接,数据访问单点 | 两个 BFF 各自直连库,事务与缓存口径分裂 |
| 契约双面 | 一棵契约树产出 tonic + 两张 gen-http 面 | REST 与 gRPC 两套接口定义漂移 |
| face 切片 | 按 root prefix 切 admin/app,同名服务各指各的模块 | 同名 CategoryService 在一张面里冲突 |
| 生成代理表 | passthrough_proxy! 四形态,gen-proxies.py 产物 |
转发层手写膨胀,BFF 私货与样板并存 |
| stub 形态 | 契约先行,未落地方法明确 NOT_IMPLEMENTED | 前端对半成品接口得到静默 404 |
| Lua 原子轮换 | 验旧/吊旧/发新一次脚本执行 | 并发刷新竞态,refresh token 重放 |
| 两段式门 | 本地验签 + core 远程 ValidateToken | 会话黑名单两处维护,吊销不及时 |
| 白名单进构建 | AUTH_FREE 是代码,消费于 build.rs | 公开路由靠配置文件,加路由忘配白名单 |
| SSE metadata 扇出 | 领域只带收件人列表,BFF 分发+双重过滤 | 领域层耦合推送细节;事件串台 |
| 双清单快照 | MANIFEST 终态门 + UPSTREAM 漂移基线,退出码分病因 | 前端快照被顺手修补,与上游渐行渐远 |
三服务拓扑的成本是真实的:多两个进程、多一层 gRPC 边界、部署从一变三。买到的也是真实的:领域逻辑只有一个主人,BFF 薄到可以整体生成,契约的每次变更对 REST、gRPC、五个前端同时生效。什么时候值得付这个成本?当消费端的形态开始分化------管理后台与小程序要的不仅是不同界面,而是不同的权限面与错误面------BFF 就不再是架构品味,而是必需品。
相关项目:
- rushwind ------ RushWind 框架 monorepo(http-binding / gen-http / authn-gate / transport-sse / proto-build / storage-seaorm-support 等),本项目的底座:Gitee | GitHub
- rushwind-admin ------ 姊妹项目(Rust 中后台平台,同一框架底座):Gitee | GitHub
系列文章:

