品牌自托管接入标准（默认接入方式）—— 域名 · realm · 边缘 · 部署

读者：在 AgentHub 上孵化 / 运营一条产品线的 SaaS 开发者与运营人员。本文是标准默认接入方式，所有产品线统一按此心智落地。 状态基准：2026-09-02（ADR-0063 D10：品牌自托管边缘为默认部署形态；PE3-5 / PE3-6 多 realm 多签发者已落地）。配套：模式 B 薄壳接入指南（前端如何接 OIDC 与会话 API）· 从零发布第一个 SaaS · 运维 runbook 索引。 契约事实源：端点与字段以 openapi.yaml 为准。

0. 一页纸心智

你的产品线 = 一个品牌域名 + 一个 Keycloak realm + 一个运营域租户 + 一台自己的服务器
你的用户   = 全程停留在品牌域名：首页 / 产品 / 登录页 / 接口，地址栏不出现基座域名
你的服务器 = 品牌边缘 nginx + 你的前端 + 你的后端 + 你的重能力 + 你的数据库
基座       = 账号 · 钱包 · 积分 · Agent 对话 —— 一套，所有产品线共用，你只通过 /api/ 和 /auth/ 两个路径碰到它

你负责	基座负责
品牌域名、DNS、证书、服务器	账号（Keycloak realm）、登录页、Google 登录
品牌边缘 nginx（模板给你）	钱包、积分、充值、PayPal
首页、产品前端、门户（用户 / 积分页）	Agent 对话运行时、知识库、工具
自有后端、重能力（3D / 渲染 / PPT / 审批流…）、自有 DB	租户与项目、发布、计费归因
把 `/api/` `/auth/` 反代到基座	认 token、判归属（R1）、扣点

"薄壳"的意思：不重做账号 / 钱包 / 租户——不是说你的代码要小。你的 3D 编辑器可以很重，它就是你的。

1. 真实案例：四个域名、五个仓库、三条产品线

基座        bhsl.cc            realm agenthub   基座节点（ops. / docs. / pay.）
教育线      aelarisle.com      realm edu        Tenant 教育运营域
              /english/  ← 仓库 aelarisle0832          Project 英语陪练
              /writing/  ← 仓库 aelarisle-writingclass Project 写作辅导
管理线      lestoform.com      realm mgmt       Tenant 企业A / 企业B / …（B2B 每客户一租户）
              /          ← 仓库 lestoform0831
建筑线      vylpa.com          realm arch       Tenant 设计运营域
              /          ← 仓库 vylpa                    Project 别墅3D

教育线的两个产品同 realm、同租户：用户注册一次两边都能登录，充值一次两边都能花，会员按产品各自独立——这是平台既有行为，不需要任何额外开发。

2. 部署形态（默认）

 aelarisle.com  @ www ──► 教育线服务器 ┐
 lestoform.com  @ www ──► 管理线服务器 ┼── 每台：品牌边缘 nginx + 前端 + 后端 + 重能力 + 自有 DB
 vylpa.com      @ www ──► 建筑线服务器 ┘          │ /api/ /auth/ 经 VPC 内网同源反代
                                                  ▼
 bhsl.cc  @ ops. docs. pay. ──────────────► 基座节点：基座网关 → api · Keycloak（多 realm）· PG · …

品牌域名的 @ 与 www 指你自己的服务器（www 只做 301 → @）。子域完全归你（render.vylpa.com 想指哪指哪）。
品牌边缘（你服务器上的 nginx）：/ 与产品路径、重能力本机直出；/api/、/auth/ 同源反代到基座网关的 VPC 内网地址；/auth/admin、/auth/realms/master 直接 404。
流量分层：控制面（登录、API、SSE）过基座；数据面（静态资源、营销页、渲染 / 文件大载荷）永不过基座。
身份不随机器变：你的 realm 设了 frontendUrl = https://<品牌域>/auth，所以登录页 URL 和 token 的签发者都是品牌域，与边缘在哪台机器无关。换服务器 = 改 DNS。

为什么是这个形态

收益	说明
用户不离站	地址栏、devtools 里只有品牌域名；零 CORS
故障域独立	你的能力崩了不影响别的线；基座宕了你的首页与已登录本地能力照常（token 约 5 分钟后需刷新）
发版解耦	你发版不用碰基座任何配置
带宽自主	你的大载荷不占基座出站带宽；可就近部署 / 上 CDN
一步到位	产品线终将有自己的能力服务器，一开始就把入口放自己这边，免二次搬迁

代价：每条线上线即需一台服务器与一份边缘配置（模板化），以及到基座的 VPC 内网通路。

3. 上线一条产品线：八步

以建筑线 vylpa.com / realm arch 为例。第 1、3~8 步你做；第 2 步由基座运维做。

3.1 域名与服务器（你）

买域名；买一台与基座同区域 / 同 VPC 的服务器；@ 与 www 的 A 记录指向它。
为 vylpa.com 签 ACME 证书。
发布 SPF / DKIM / DMARC（你的 realm 会用 noreply@vylpa.com 发验证邮件）。

3.2 建 realm（基座运维，一条命令）

基座运维在基座节点执行 new-realm.sh arch vylpa.com --client-id arch-web。它会：从模板建 Keycloak realm arch（frontendUrl=https://vylpa.com/auth，一个 PKCE 公共 client arch-web，Google IdP 占位，独立 SMTP）→ 校验签发者 → 写入信任注册表 → 打印给你的清单。基座安全组对你服务器的内网 IP 放通 443。

3.3 品牌边缘（你）

在你的服务器安装 nginx，使用基座仓库提供的模板 deploy/brand-edge/nginx.brand-edge.example.conf，替换四个占位符：

占位符	填什么
`__BRAND_DOMAIN__`	`vylpa.com`
`__BASE_GATEWAY__`	基座网关的 VPC 内网地址:443（基座运维给你）
`__BASE_DOMAIN__`	`bhsl.cc`（到基座的 TLS 以它做 SNI 与校验）
`__LOCAL_APP_UPSTREAM__`	你的应用本机地址，如 `127.0.0.1:3000`

nginx -t 通过后 reload。模板里 /api/ 与 /auth/ 已配好同源反代与 SSE 不缓冲；/auth/admin 已 404；不要给 /auth/ 加 X-Forwarded-Prefix。

3.4 Google 登录（基座运维 + 你）

基座用一个 Google OAuth client，redirect URI 里已含 https://vylpa.com/auth/realms/arch/broker/google/endpoint（新线 = 加一条）。基座运维在 realm arch 的 Identity providers → google 填凭据并启用。你无需在前端做任何事——Keycloak 登录页自动出现 Google 按钮。

3.5 前端（你）

从基座仓库的 web-saas-template 派生，构建参数：

VITE_KEYCLOAK_URL=https://vylpa.com/auth
VITE_KEYCLOAK_REALM=arch
VITE_KEYCLOAK_CLIENT_ID=arch-web
VITE_PROJECT_ID=<第 3.7 步拿到>
VITE_BASE_PATH=/            # 多产品时各产品用 /english/ /writing/ 等子目录

这些是构建期常量，改了要重建。同一品牌域下的门户、各产品、builder 都可以共用 arch-web 这一个 client（同源、无缝 SSO）。

3.6 后端与重能力（你）

你的后端 / 渲染 / PPT 服务作为 OIDC resource server 直接验 realm arch 的 JWKS（iss = https://vylpa.com/auth/realms/arch）；不要自建登录。
你的 DB 只存 user_id / tenant_id 这样的身份引用，不存凭据。
需要以服务身份调基座（代用户扣点、后台跑 Agent）时，用基座发给你的 M2M client 凭据经 VPC 内网调用。

3.7 租户与项目（你 / 你的运营）

用 Google 在 https://vylpa.com 首登 → 平台 JIT 自动建你的个人租户（已绑定 realm arch）→ 调 POST /api/v1/tenants 把它原地升级为运营域 → 在 https://vylpa.com/builder/ 建项目"别墅 3D"、发布 Agent → 拿到 project_id 填进 3.5。
多产品：在同一租户下建多个项目（教育线：英语陪练、写作辅导），每个产品的前端填自己的 project_id，用户与充值自动共享。
B2B（管理线）：每个企业客户一个租户，全部属 realm mgmt。

3.8 验收（你 + 基座运维）

curl -s https://vylpa.com/auth/realms/arch/.well-known/openid-configuration | jq .issuer → https://vylpa.com/auth/realms/arch。
浏览器在 vylpa.com 走一次 Google 登录 → GET /api/v1/me 200，返回的租户属 realm arch。
发一轮 Agent 对话（SSE 流式回来）→ 余额减少。
地址栏全程只有 vylpa.com。

4. 一次请求怎么走

1  打开 https://vylpa.com/                  你的边缘 → 你的前端
2  点登录 → https://vylpa.com/auth/realms/arch/...   你的边缘 ──VPC──► 基座 Keycloak 渲染登录页（地址栏仍 vylpa.com）
3  Google 授权 → 回 https://vylpa.com/callback       前端经 /auth/ 换 token；iss = https://vylpa.com/auth/realms/arch
4  GET https://vylpa.com/api/v1/me                  你的边缘 ──VPC──► 基座 api（验签、判归属、JIT）
5  用户在你的编辑器里工作                             全在你的机器；基座零参与
6  点「Agent」→ POST /api/v1/app/conversations/…    你的边缘 ──VPC──► 基座（扣点、跑 Agent、SSE 回传）
7  点「渲染」→ POST https://vylpa.com/render/…      你的边缘 → 你的渲染服务（验同一 realm 的 JWKS）；结果本机直出
8  渲染完成，你的服务以 M2M 凭据调基座代用户扣点      服务器对服务器

三类调用者

谁	拨什么	凭据
浏览器	`https://<品牌域>/api/...`（同源，边缘转基座）—— 主路径	用户 JWT
你的后端 / 能力服务	基座网关 VPC 内网地址	M2M client secret / API-Key + `X-AgentHub-On-Behalf-Of`
基座	你暴露给 Agent 的 HTTP Tool 接口	工具目录

浏览器从不直接请求基座域名。

5. 加一个产品到既有线

例：教育线加"数学学习"。

运营在 aelarisle.com/builder/ 建项目、发布 Agent → project_id。
新仓从 web-saas-template 派生，VITE_BASE_PATH=/math/ VITE_PROJECT_ID=<id>，realm / client 不变。
部署到教育线服务器；边缘加 location /math/；有重能力再加一条能力路径。

零后端代码、零 Keycloak 改动、零 Google 改动、零基座改动。

6. 数据边界速查

要求	机制	状态
同线注册一次两边可登录	同 realm + 同租户	已有
充值积分同线共享	充值钱包按（租户, 用户）唯一	已有
会员按产品独立	会员钱包按（用户, 项目）唯一	已有
每产品报表	流水与成本按项目归因	已有
跨线不共享	跨 realm 凭据不相认；跨租户 RLS 硬隔离	已有
一个邮箱三线通用	不支持（三 realm 三本名册，已接受）	—

7. 安全纪律（你必须遵守的）

不要在边缘暴露 /auth/admin 或 /auth/realms/master（模板已 404，别删）。
不要给 /auth/ 加 X-Forwarded-Prefix。
不要自建登录 / 存密码 / 存 token 到你的 DB；只存身份引用。
到基座的反代走 VPC 内网，TLS 以基座域做 SNI 并开启证书校验（基座换正式证书后）。
你的 realm 必须有 frontendUrl（new-realm.sh 已强制，别在 Keycloak 里删掉）。
M2M 凭据只放服务端环境变量 / 密钥库，不进仓库、不进前端。

8. 常见问题

登录页在哪渲染？ 物理上在基座 Keycloak，经你的边缘反代；用户看到的 URL 与 token 签发者都是品牌域。

我需要 api.vylpa.com / auth.vylpa.com 吗？ 不需要。它们是品牌域下的路径，边缘同源反代，零 CORS。

基座宕了我会怎样？ 登录、扣点、Agent 不可用；你的首页与已登录用户的本地能力照常，token 约 5 分钟过期后需刷新。

我能用 CDN 吗？ 能。静态资源上 CDN；/api/ /auth/ 由 CDN 按路径回源到你的边缘（再到基座）或直接回源基座网关。

一个邮箱能在三个品牌通用吗？ 不能。同一品牌线内的多个产品通用。

我的服务器可以在别的云吗？ 可以，但边缘到基座的反代就要走公网 TLS 并由基座开放对应入口；同 VPC 内网是默认推荐。

品牌自托管接入标准（默认接入方式）—— 域名 · realm · 边缘 · 部署 ​

0. 一页纸心智 ​

1. 真实案例：四个域名、五个仓库、三条产品线 ​

2. 部署形态（默认） ​

为什么是这个形态 ​

3. 上线一条产品线：八步 ​

3.1 域名与服务器（你） ​

3.2 建 realm（基座运维，一条命令） ​

3.3 品牌边缘（你） ​

3.4 Google 登录（基座运维 + 你） ​

3.5 前端（你） ​

3.6 后端与重能力（你） ​

3.7 租户与项目（你 / 你的运营） ​

3.8 验收（你 + 基座运维） ​

4. 一次请求怎么走 ​

5. 加一个产品到既有线 ​

6. 数据边界速查 ​

7. 安全纪律（你必须遵守的） ​

8. 常见问题 ​