forked from xiaohei/taiji-AI-PAD
docs(heicode): §21-§24 #19 收口 + 开闸 + HM#74 落地域名改 code.heicode.cc
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.8
@@ -588,3 +588,83 @@ mcp-server 在本节下方回 **§19.2 的 1–4**(尤其邮件基建 owner +
|
||||
|
||||
## 一句话
|
||||
**发信定 189.cn(送达率本期不考虑、已接受);开闸前置除"运维置 `MAGIC_LINK_EMAIL_ENABLED=true`"外均已就绪;mcp-server 侧无其它阻塞。** HM 可据此在 #19 收尾,真发信由运维按上表开闸。
|
||||
|
||||
---
|
||||
|
||||
# 21. HM owner @zsbgnw12 — 确认收到 §20,#19 收口(2026-06-10)
|
||||
|
||||
收到 §20。**确认 mcp-server 侧无功能/契约阻塞**;契约 D-4=APIM、登录产物等价、三端点 + landing + verify 生产可用,均已在 §16/§18 共同验证。#19 在 mcp-server 侧视为完成,余下仅两类:
|
||||
|
||||
## 21.1 各方剩余(非 mcp-server 阻塞)
|
||||
- **运维**:满足 §20 Q3 表后,置 `k8s/prod/configmap.yaml` 的 `MAGIC_LINK_EMAIL_ENABLED=true` + 滚动重启即开闸。开闸动作归运维。
|
||||
- **HM/客户端**:cc-haha 邮箱登录 UI + `heicode://auth/callback` 深链转发 + `state` 比对 + 调 request/verify(HM 侧自推,不依赖 mcp-server)。
|
||||
|
||||
## 21.2 ⚠️ 需产品/owner 知悉的一个风险(非工程项)
|
||||
mcp-server 已**接受 189.cn 的送达率风险**(企业/海外可能收不到或进垃圾箱、无 SPF/DKIM/DMARC、无退信回收)作为本期已知风险。这属**产品/运营风险接受**,工程侧据此实现没问题;是否以此口径对外开闸,请产品 owner 知悉确认。后续要正式运营,按 §20 Q2 再评估换 SES/SendGrid + 域名背书。
|
||||
|
||||
## 21.3 状态
|
||||
magic-link **后端 + 代理 + APIM 透传 + 登录等价 = 全通**;**开闸=运维一个配置**;**客户端 UI=HM 侧自推**。本对接(mcp-server 侧)收口,感谢配合。
|
||||
|
||||
---
|
||||
|
||||
# 22. 产品/owner 拍板:接受 189.cn 风险 → 开闸放行(2026-06-10)
|
||||
|
||||
**owner 已确认接受** §20 Q2/§21.2 的 189.cn 已知送达率风险(企业/海外送达、垃圾箱、无 SPF/DKIM/DMARC、无退信),作为本期已知风险记录在案。
|
||||
|
||||
→ **开闸放行**:满足 §20 Q3 前置(均已就绪)后,**mcp-server 运维**可执行开闸:确认 189.cn `SMTP_PASSWORD` 有效 → `k8s/prod/configmap.yaml` 置 `MAGIC_LINK_EMAIL_ENABLED=true` → 滚动重启。开闸后 `request` 即对已存在 `role=user` 邮箱真发链接。
|
||||
|
||||
> 后续若要正式运营再按 §20 Q2 评估换 SES/SendGrid + 域名背书。开闸动作归 mcp-server 运维(其 k8s/prod);HM 侧并行推进客户端 cc-haha 邮箱登录 UI。本对接收口。
|
||||
|
||||
---
|
||||
|
||||
# 23. ⚠️ magic-link 邮件落地链接的**域名**要改(HM owner @zsbgnw12,2026-06-12,对应 HM #74)
|
||||
|
||||
## 23.1 现象 / 问题
|
||||
客户端 magic-link 邮件里的**落地/verify 链接 base 落在 `apimtaiji.azure-api.net`**(例:`https://apimtaiji.azure-api.net/api/mcp/api/auth/magic-link/landing?token=...`)。这是 mcp-server 用**自身网关域名**拼的绝对 URL。问题:
|
||||
- 与客户端实际登录域名不一致(客户端 request/verify 走的是 HM 反代的登录域名,不是 apimtaiji),off-brand/钓鱼观感;
|
||||
- apimtaiji 曾是设备配对 404 的历史问题网关,脆弱;
|
||||
- 不符合"只登客户端登录域名"的口径。
|
||||
|
||||
## 23.2 当前/未来的客户端登录域名(请据此拼落地链接)
|
||||
HM 已迁到 AKS,生产域名:
|
||||
- **`code.heicode.cc`** → App GW → HM(控制台 + `/api` + `/v1`)。**客户端登录走 `https://code.heicode.cc/api/heicode-auth/*`**,HM 反代到 mcp-server。
|
||||
- `api.heicode.cc` → APIM → HM API(程序化访问,非登录落地)。
|
||||
- (并行期客户端仍可能用旧域名 `https://code.xinghanlab.com/api/heicode-auth/*`。)
|
||||
|
||||
## 23.3 ✅ 推荐改法(域名无关,一次到位)
|
||||
**magic-link 邮件里的落地/verify 链接,不要硬编码 apimtaiji.azure-api.net;改为按 HM 反代透传的转发头拼绝对 URL:**
|
||||
- `X-Forwarded-Host`(= 客户端访问的域名,如 `code.heicode.cc`)
|
||||
- `X-Forwarded-Proto`(= `https`)
|
||||
- `X-Forwarded-Prefix`(= `/api/heicode-auth`,HM 反代前缀)
|
||||
|
||||
→ 落地链接拼成 `https://{X-Forwarded-Host}{X-Forwarded-Prefix}/api/auth/magic-link/landing?...`,即 `https://code.heicode.cc/api/heicode-auth/api/auth/magic-link/landing`(经 HM 反代可达、与 verify 同源)。**这样无论客户端用 code.xinghanlab.com 还是 code.heicode.cc 都自动正确,mcp-server 不用硬编码任何域名。**
|
||||
|
||||
**HM 侧已实现透传**:`HeicodeAuthProxy` 在 `/api/heicode-auth/*` 已带上述三个头(HM PR#75 已合并 main)。
|
||||
|
||||
## 23.4 兜底(若 mcp-server 不便读转发头)
|
||||
则把 magic-link 落地 public base 配成客户端登录域名常量:
|
||||
- 迁 AKS 后:`https://code.heicode.cc/api/heicode-auth`
|
||||
- 并行期/旧:`https://code.xinghanlab.com/api/heicode-auth`
|
||||
|
||||
## 23.5 影响范围
|
||||
仅 magic-link 邮件里**落地/verify 链接的 base 拼接**;**不改登录产物 `{token,refreshToken,user}`、不改 JWT claims、不改任何接口契约**。请 mcp-server 确认采用 23.3(推荐)还是 23.4,并排期。@mcp-server
|
||||
|
||||
---
|
||||
|
||||
# 24. mcp-server 回复 §23:采用 23.4(`code.heicode.cc`)+ 已部署生产(2026-06-12)
|
||||
|
||||
> 选 **23.4**(域名常量),**已部署生产验证通过**。未采纳 23.3 的原因是安全考量(见下)。本改动仅落地链接 base,**不动任何接口/JWT/登录产物**(与 §23.5 一致)。
|
||||
|
||||
## 24.1 已落地(真实生产值)
|
||||
- `k8s/prod/configmap.yaml` 的 `MAGIC_LINK_PUBLIC_BASE_URL`:`https://apimtaiji.azure-api.net/api/mcp` → **`https://code.heicode.cc/api/heicode-auth`**,已 `apply` + 滚动重启(3 pod 全新,env 已生效)。
|
||||
- 拼出的落地链接(生产 pod 实测)= **`https://code.heicode.cc/api/heicode-auth/api/auth/magic-link/landing?token=...&state=...`**,与 §23.3 期望一致、与 verify 同源。
|
||||
- 代码无改动([auth.py:1411-1412](services/mcp-server/app/routes/auth.py:1411) 的 `base + /api/auth/magic-link/landing` 拼接逻辑不变,仅换 base 值)。
|
||||
|
||||
## 24.2 为何没选 23.3(转发头动态拼)——安全
|
||||
`/api/auth/magic-link/request` 经 APIM 也可**直达**(不只走 HM 反代)。若**裸读 `X-Forwarded-Host`** 拼落地域名,攻击者可伪造该头 + 填某真实用户邮箱 → 该用户收到的 magic-link 邮件**落地域名指向攻击者站**(钓鱼/窃 code)。所以 23.3 要做必须**配域名白名单**(只认 `code.heicode.cc`/`code.xinghanlab.com`,否则回退常量)。本期先用更稳的 23.4 常量;**若后续要 23.3 的"双域名自动正确",我方按"白名单版 23.3"另行排期 + 安全评审**(改鉴权路径,先评审)。
|
||||
|
||||
## 24.3 ⚠️ 请 HM 确认一条(归你方反代)
|
||||
落地链接改走 `code.heicode.cc/api/heicode-auth` 后,用户点链接 = **浏览器 → HM 反代 → mcp landing → 302 `heicode://`**。此前只验证过:① `apimtaiji` 直连的成功 302(§18.1)、② HM 反代的**失败分支** HTML(§16.1)。**"成功路径的 `302 Location: heicode://...` 经 `code.heicode.cc` HM 反代是否被原样透回浏览器"尚未实测**——这属 HM 反代行为,请你方按 §11 的 4 条(重点保留非 http 的 `Location`、不 follow/不改写)在 `code.heicode.cc/api/heicode-auth` 上验一次。mcp 侧 landing 返回 302 的行为不变(§18.1 已证)。
|
||||
|
||||
## 24.4 状态
|
||||
落地域名改 `code.heicode.cc` **已上生产**;`request/verify/landing` 契约不变;只待 HM 验 §24.3 的"成功 302 经新反代透传"。
|
||||
|
||||
Reference in New Issue
Block a user