docs: 单域名多租户（路径前缀路由）+ 上线收口项设计 spec
Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
浅念
@@ -0,0 +1,90 @@
|
||||
# 单域名多租户（路径前缀路由）+ 上线收口项 设计
|
||||
|
||||
- 日期：2026-10-19
|
||||
- 状态：待评审
|
||||
- 范围：后端路由层 + 静态面前缀自推导 + 平台管理面小改 + 登录限流 XFF + limiter 清扫
|
||||
- 前置：配置中心优化已合入 main（6d6d8a8）
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
现状租户按域名（Host）解析，一租户至少一个域名——给大量网站挂客服时 DNS/证书/反代条目线性增长，不适合运营。目标：**一个共享域名承载任意多租户**，租户标识在 URL 路径中；Host 模式原样保留，两种共存。
|
||||
|
||||
上线收口项（随本 spec 一并实施）：
|
||||
1. **登录限流 XFF**：反代形态下 `client.host` 恒为 127.0.0.1，登录限流键退化为纯用户名，多 IP 爆破同一账号不受 IP 维度限制——解析 XFF 首段入键；
|
||||
2. **limiter 清扫**（日志/内存上限铁律的进程内面）：登录限流器与聊天限流桶的过期键永不回收，周期清扫。
|
||||
|
||||
## 2. 方案总览
|
||||
|
||||
```
|
||||
Host 模式（不动）：chat.xxx.com → registry.resolve_site(host)
|
||||
路径模式（新增）： kefu.xxx.com/t/<slug>/... → 按 slug 解析 → 剥前缀 → 下游路由零改动
|
||||
```
|
||||
|
||||
嵌入代码形态（脚本地址即租户标识，无需新参数）：
|
||||
|
||||
```html
|
||||
<script src="https://kefu.xxx.com/t/<slug>/static/widget.js" async></script>
|
||||
```
|
||||
|
||||
## 3. 路由层设计（TenantHostMiddleware 扩展）
|
||||
|
||||
优先级：**平台豁免 → 路径前缀解析 → Host 解析**。
|
||||
|
||||
1. **slug 形态校验先行**：前缀段须 `^[a-z0-9-]+$`（与租户创建 `SLUG_RE` 一致，tenant_routes.py:65 同款正则常量提取共用）；不匹配（含 `..`、编码畸形、大小写不符）直接走 Host 解析（共享域名下即 404），**不做任何剥离**。
|
||||
2. **路径改写**：匹配 `/t/<slug>/` 或精确 `/t/<slug>`（后者无尾斜杠 → 不剥离，走 Host 解析 → 共享域名 404，语义记录在案）；剥离时同步改写 `scope["path"]` 与 `scope["raw_path"]`（bytes，存在才改）；http 与 websocket 两类 scope 同构处理。
|
||||
3. **orig_path 留痕**：原始 path 存 `scope["state"]["orig_path"]`（排障/日志对账用；uvicorn 访问日志显示剥离后路径为已知性状）。
|
||||
4. **解析与错误语义**：slug → `registry._by_slug` 查租户（缺停用判断与 resolve_site 同款：未知 slug → http 404 / ws close(1008)；停用 → 503 暂停页 / ws close(1013)）；站点 = 租户**首个站点**为默认（`?site=` 覆盖链路既有），`state["site"]` 同样写入。
|
||||
5. **平台豁免优先级在前**：`/health`、`/api/platform/`、`/admin` 不受影响；`/t/x/api/platform/...` 剥离后命中平台路由属 by design（认证守护，与未知 Host 下 admin 面可达同级）。
|
||||
6. 已知边界（记录不修）：StaticFiles 目录 308 的 Location 不带前缀（挂件/页面只引用具体文件，不触发）。
|
||||
|
||||
## 4. 静态面前缀自推导
|
||||
|
||||
- **widget.js**：`var basePath = new URL(script.src).pathname` 剥掉尾部 `/static/widget.js...`（得 "" 或 `/t/<slug>`）；brand / avatar（含 DEFAULT_AVATAR_PATH）/ WS 三类端点构造统一 `wsBase + basePath + 原路径`。Host 模式 basePath="" 零变化；`tests/test_widget_static.py` 风格静态断言钉住。
|
||||
- **chat.html**：新增 15 行内联引导脚本——按 `location.pathname` 推导 basePath（`/t/<slug>/` → `/t/<slug>`；`/` → ""），改写自身 `<link>/<script>/<img>` 的绝对引用前缀并定义 `window.__BASE_PATH__`；`static/js/chat.js` 的 brand fetch / avatar / WS 消费该变量（缺省 "" 兼容）。`test_chat_static.py` 同款守卫。
|
||||
|
||||
## 5. 平台管理面
|
||||
|
||||
- **registry**：新增 `resolve_by_slug(slug) -> tuple[TenantRuntime, Site]`（含停用判断，默认站点 = 站点表首项；空站点表的租户按 UnknownTenantError 处理——路径模式无从选站点）。
|
||||
- **创建向导**：域名步骤放宽为可跳过（后端 `domains: list[str]` 本就 default 空；前端向导与「租户详情无域名」展示同步）；无域名租户 = 纯路径模式。
|
||||
- **平台设置**：推荐键新增 `shared_widget_domain`（共享挂件域名，运营填一次）。
|
||||
- **嵌入代码生成器**（配置中心品牌页）：双形态——租户有域名 → 域名形态 + 共享域名形态（`shared_widget_domain` 已配置时）都给；无域名 → 仅共享形态；都无 → 引导文案（去平台设置配共享域名 / 去租户详情绑域名）。`data-site` 等参数两形态通用。
|
||||
|
||||
## 6. 登录限流 XFF（可信代理语义）
|
||||
|
||||
与聊天面 `_server_ip`（XFF 服务端优先、取首段）同款提取：登录端点把 `request.headers.get("x-forwarded-for")` 首段作为限流 IP，无 XFF 回退 `request.client.host`。**只进限流键**（认证语义、日志、其他端点不动）。部署注记：直连形态（无反代）行为不变；反代形态下 XFF 由我方 1Panel 反代附加，客户端伪造的 XFF 会被反代追加在尾部、首段仍为真实来源（OpenResty `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for` 语义——部署模板已有则复用，没有则在模板补此头）。
|
||||
|
||||
## 7. limiter 周期清扫（内存上限铁律合规）
|
||||
|
||||
- 登录限流器（platform/auth.py LoginLimiter）与聊天限流桶（engine/services/rate_limit.py `_buckets`）、WS 连接计数：注册**定期清扫**（lifespan 启动 asyncio 任务，每 300s 全量清过期键/空键；停用即取消）。实现走各模块自有数据结构私有方法，不新增共享抽象（YAGNI）。
|
||||
- 验收注记：compose 已有 `mem_limit: 768m` 与日志 `json-file 10m×3` 封顶（铁律的容器面已合规，本条补齐进程内面）。
|
||||
|
||||
## 8. 部署形态（本 spec 落地后）
|
||||
|
||||
- 共享域名（如 `kefu.hnxinyouhe.com`）：一次 DNS + 一张证书 + 一条 1Panel 反代（透传 Host 头、WS 开关、超时 3600s——模板 `deploy/openresty-all-kefu.conf.template` 增补该域名 server 块与 XFF 头注记）。
|
||||
- 新租户接入 = 后台建租户（可零域名）→ 复制嵌入代码 → 完事，零 DNS 操作。
|
||||
- `docs/deploy-production.md` 增补「共享域名模式」一节（含 `/t/<slug>/` 地址形态与无尾斜杠语义）。
|
||||
|
||||
## 9. 测试策略
|
||||
|
||||
- 中间件：slug 形态校验（畸形/编码/大小写/无尾斜杠）、path+raw_path 双改写、orig_path、未知/停用语义（http+ws 双 scope）、Host 模式回归（既有 test_host_routing 全绿）、平台豁免优先级、`/t/x/static/…` 全链（chat 页/静态/public/chat REST/WS）。
|
||||
- registry：resolve_by_slug（默认首站点/site 覆盖/停用/空站点表）。
|
||||
- 静态守卫：widget.js basePath 构造、chat.html 引导脚本、chat.js __BASE_PATH__ 消费（grep 式静态测试既有风格）。
|
||||
- 登录限流：XFF 首段入键/无 XFF 回退/伪造 XFF 追加形态（反代追加语义模拟）。
|
||||
- 清扫：过期键回收、lifespan 启停。
|
||||
- 前端 vitest：嵌入代码生成器双形态 model 纯函数。
|
||||
- 基线：pytest 632+2skip 与 vitest 182 不回归，新增只增不减。
|
||||
|
||||
## 10. 非目标
|
||||
|
||||
- 不做 RAG 知识库（等首个真实新租户知识量再定）；
|
||||
- 不做挂件防盗嵌白名单（演进项）;
|
||||
- 不动 Host 模式任何行为；不做多 worker（单进程硬约束不变）；
|
||||
- 不做 `/t/<slug>` 无尾斜杠 308 重定向（404 语义即可）。
|
||||
|
||||
## 11. 验收标准
|
||||
|
||||
1. 全量 pytest + vitest 绿；两模式共存回归（chat./chat2. 本地 hosts 走查不受影响）；
|
||||
2. 共享域名模拟走查：`/t/<slug>/` 打开聊天页、挂件加载、WS 对话、试金石、限流隔离（同 IP 双租户互不干扰）；
|
||||
3. 嵌入代码：无域名租户在 `shared_widget_domain` 配置后可生成可用嵌入代码；
|
||||
4. 登录限流：反代形态（XFF）下按真实 IP 计数；清扫任务可见过期键回收；
|
||||
5. 日志/内存上限：compose 封顶配置在位（铁律检查项过一遍）。
|
||||
Reference in New Issue
Block a user