Skip to content

feat(system): 多站点地址访问控制台 (HQ-Task T261113-11) - #42

Merged
AdoreJc merged 4 commits into
fork-mainfrom
hq/T261113-11-multi-server-address
Nov 14, 2026
Merged

AdoreJc merged 4 commits into
fork-mainfrom
hq/T261113-11-multi-server-address

Conversation

@AdoreJc

@AdoreJc AdoreJc commented Nov 13, 2026

Copy link
Copy Markdown
Owner

HQ-Task: T261113-11

本 PR 由 AI(Claude Code,claude-fable-5-2)生成,由 Project HQ 会话派发。移植本地提交 71491b3cb 到最新 fork-main(09cca3d97)。

Change

  • 新增选项 AlternateServerAddresses(每行一个 origin;保存时拒绝路径、通配、非 http(s))。
  • service.RequestServerAddress:Origin / Referer / Host 只在已配置地址里做精确匹配,否则回落 ServerAddress。多个或带逗号的 Origin、带 userinfo 的 Referer 视为无效。
  • 跟随线路:/api/status 的 server_address、密码重置链接、OAuth redirect_uri(流程开始时记录,回调时必须仍在配置里,否则回落)、Epay 充值回跳、Stripe 充值(含支付宝/微信)success/cancel、Stripe 订阅与一次性订阅 Checkout、Waffo 回跳、订阅 Epay 的浏览器 return_url 及其后的控制台跳转。
  • 保持 ServerAddress / 回调地址不变:Epay、订阅 Epay、Waffo 的 notify_url;邮件 OAuth redirect URI(未改动);Creem(无服务端回跳地址)、Waffo Pancake(管理员配置的 ReturnURL);额度提醒邮件里的充值链接(无请求上下文);MJ/任务媒体地址。
  • 会话 cookie origin 检查额外信任已配置的 HTTPS 地址。
  • 订阅 Epay return_url:仅当请求来自备用线路时改用该线路,其他情况仍是回调地址(含 CustomCallbackAddress)。这是原提交没有的新增判断,请审查。

Verification

  • Mac mini(macOS,Go 1.26.10)GOWORK=off go test ./common/... ./controller/... ./middleware/... ./model/... ./oauth/... ./service/... ./setting/...:全部 ok(a29dbf4b5;之后只改了一个前端测试夹具)。
  • 前端(Bun 1.4.4):bun run typecheck 无错误;bun run test 244 文件 2715 项通过;bun run build 成功;改动文件 oxlint 0 error。
  • 端到端(Mac mini 一次性容器,空 SQLite,ServerAddress=https://main.example.com,备用=https://line2.example.com,跑完已删除容器与数据):
    • /api/status:Host/Origin 为 main → main;line2 → line2;未配置主机、配置主机作后缀的主机、带逗号的 Origin → main。未配置备用地址时 line2 的 Host → main。
    • Telegram OAuth(假 client)authorization_url 的 redirect_uri:main → main,line2 → line2,未配置 → main。
    • 密码重置邮件(本地 SMTP 接收器抓取)链接:line2 → line2,main → main,未配置 → main。
    • 保存 https://line2.example.com/app、https://*.example.com、line2.example.com 均被拒绝。
  • 新增测试:TestPaymentReturnPathFollowsConfiguredLineOnly、TestSubscriptionEpayReturnFollowsAlternateLineAndNotifyStays(controller/return_path_test.go),原提交的测试全部保留。

Not verified / notes

🤖 Generated with Claude Code

AdoreJc and others added 3 commits November 13, 2026 18:51
新增选项 AlternateServerAddresses,同一部署可通过多个站点地址打开控制台。
给浏览器的链接跟随用户进来的线路:OAuth redirect_uri(流程开始时记录,
回调换 token 时复用)、密码重置邮件链接、支付完成后的回跳页、/api/status
的 server_address。Origin / Referer / Host 只在已配置地址中做精确匹配,
匹配不上一律回落 ServerAddress;已配置的 HTTPS 地址同时被会话 cookie 的
origin 检查信任。

移植自 71491b3cb,并覆盖其后新增的回跳点:Stripe 支付宝/微信充值、
订阅 Stripe 订阅与一次性 Checkout、订阅 Epay 的浏览器回跳。支付平台
异步通知地址与邮件 OAuth 的 redirect URI 仍使用 ServerAddress。

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@AdoreJc

AdoreJc commented Nov 14, 2026

Copy link
Copy Markdown
Owner Author

HQ-Review R1 @ f08cd8a: REQUEST_CHANGES

审查范围:fork-main(09cca3d)...f08cd8a,三个提交全部看过;与原提交 71491b3cb 逐文件对照,后端核心(server_address.go、RequestServerAddress、RequestBrowserOrigin、auth_origin、oauth/*)与原提交一致,冲突处保留了 fork-main 的行为(completeEpaySubscriptionOrder、Stripe paymentMethod 参数、ValidateRedirectURL 校验、站点内容多语言等均未回退)。

阻塞项

  1. web/src/features/system-settings/integrations/email-oauth-settings.tsx:95-101 —— 邮件 OAuth 设置页显示的 Redirect URI 现在会跟着线路变,但后端仍固定用 ServerAddress。
    • 该页面用 /api/status 的 server_address 拼出"请在 Google Cloud / Entra 登记的 Redirect URI"并提供复制按钮;本 PR 让 server_address 跟随请求线路,而 controller/email_oauth.go:37 的 emailOAuthRedirectURI() 按 brief 要求保持 ServerAddress。
    • 失败场景:管理员从备用线路打开系统设置,复制到的是"备用线路 + 回调路径",登记到 OAuth 应用后,实际授权请求带的是 ServerAddress 的 redirect_uri,提供方报 redirect_uri_mismatch,发信授权失败,且页面显示与实际不一致难以排查。
    • 这是原提交之后 feat(email): OAuth 授权发信邮箱(Gmail / Microsoft 365)(HQ-Task T261111-06) #24 新增的消费点,移植时漏查。建议:后端在 email OAuth 相关接口(或 status 里单独字段)返回 emailOAuthRedirectURI() 的值,前端用它显示;不要从 server_address 推导。补一条测试:配置备用线路并从备用线路请求时,显示/返回的仍是 ServerAddress 的回调地址。

非阻塞项

  1. middleware/auth_origin.go:53 —— 会话 cookie origin 检查用 MatchServerAddress,它除了备用地址外也匹配 ServerAddress 本身。因此即使没配置任何备用地址,HTTPS 的 ServerAddress origin 现在也会被信任(以前只有同源和 SESSION_COOKIE_TRUSTED_URL)。这是原提交的设计,信任的是本站自己的地址,风险低,但与"未配置备用地址时行为与 fork-main 完全一致"不符。请在 PR 描述里写明,或改成只匹配 AlternateServerAddresses。另外这处放宽没有任何测试:建议补 middleware 测试覆盖"已配置 HTTPS 备用地址 → 放行;已配置的 http 备用地址 → 拒绝;未配置 / 后缀相似的 origin → 拒绝"。
  2. setting/system_setting/server_address.go:15 —— AlternateServerAddresses 是包级切片,option 同步(每 60 秒 loadOptionsFromDatabase 对每个 option 调 updateOptionMap)在 OptionMapRWMutex 写锁下整体赋值,而 RequestServerAddress / MatchServerAddress / 会话 origin 检查在大多数请求路径上不持锁读取(只有 GetStatus 持读锁)。这是数据竞争(go test -race 会报),理论上切片头可能读到撕裂值。与现有 ServerAddress 字符串同一模式、实际风险很低,建议改成 atomic.Pointer[[]string](或在 updateOptionMap 中仅在值变化时替换)。不阻塞。
  3. 与 PR fix(epay): check callback amount, keep signatures out of logs, honour webhook switch for subscriptions (SEC-2026-003) #21 的合并:已确认 fix(epay): check callback amount, keep signatures out of logs, honour webhook switch for subscriptions (SEC-2026-003) #21(06300db13)在 controller/subscription_payment_epay.go 新增了一处 paymentReturnPath("/wallet?pay=fail") 旧签名调用;两者文本无冲突但合并后无法编译。这是语义冲突,不是本 PR 的缺陷;后合并的一方需改为 paymentReturnPath(c, ...),合并前请在合并结果上重新 go build ./...。
  4. 行为变化(预期内,已在描述中说明):/api/status 的 server_address 与重置链接、OAuth redirect_uri 都会去掉 ServerAddress 末尾 /;API Key 页、聊天预设、模型详情等用 server_address 显示 API 基址的地方也会跟随线路。确认这是想要的即可。
  5. 链接生成点清单核对(同意实现者的处理):跟随线路——/api/status、密码重置、Discord/OIDC/自定义 OAuth/Telegram redirect_uri、Epay 充值 return_url、Stripe 充值(含支付宝/微信)默认 success/cancel、Stripe 订阅与一次性订阅 Checkout、Waffo return_url(管理员配置的 WaffoReturnUrl 仍优先)、订阅 Epay return_url 及回跳。保持 ServerAddress / 回调地址——Epay、订阅 Epay、Waffo 的 notify_url,邮件 OAuth redirect_uri,Creem(成功页在 Creem 产品上配置,请求里不传)、Waffo Pancake(管理员配置的 ReturnURL)、额度提醒邮件充值链接(无请求上下文)、MJ/任务媒体地址(给 API 客户端而非浏览器回跳)。GitHub、LinuxDO 换 token 不带 redirect_uri,无需改。

已核对、无问题

  • Origin / Referer / Host 只与已配置列表做规范化后的精确比较,无前缀/后缀/通配;多个 Origin、多个 Referer、带逗号的 Origin、带 userinfo 的 Referer 均视为无效;未匹配一律回落 ServerAddress。密码重置链接走同一函数。
  • OAuth:site_address 记在服务端 flow payload 里,回调时只有仍在配置中才使用,否则回落;state / 会话绑定校验未改动;Telegram 的 redirect_uri 同样要求仍在配置中。
  • 保存校验:validateOptionValue 走 NormalizeOrigin,拒绝路径、通配、userinfo、query、fragment、非 http(s);所有管理员写入路径都经过它。
  • 未配置备用地址时:除第 2、5 条外,各链接与 fork-main 一致。
  • 范围:只改了 brief 允许的文件;7 个 locale 各只新增 3 个 key;没有带入 feat/multi-server-address 上更早的提交;代码、测试、PR 文本只用 example.com 类示例地址。
  • 测试:新增测试断言的是可观察结果(返回 URL、Location 头、notify_url、redirect_uri),且依赖新签名/新变量,在 fork-main 上无法通过。

我实际运行的(Windows,Go 1.26.10,worktree 未改动)

  • go test ./service/ ok;./oauth/ ./model/ ./setting/... ./common/... ok。
  • ./middleware/:仅 TestAccessAndPanicLogsFollowLogRotation 失败,原因是 Windows 临时目录清理时日志文件被占用(TempDir RemoveAll cleanup),与本 PR 无关;会话 origin 相关测试全部通过。
  • ./controller/:本 PR 相关测试(TestPaymentReturnPath*、TestSubscriptionEpayReturnFollowsAlternateLineAndNotifyStays、TestOAuthCallbackRepeatsRedirectAddressOfStartingLine、TestStripeSubscriptionCheckoutParams、TestGetStatus*)全部通过;整包 go test ./controller/ 在本机运行到第 432 个顶层测试时因 Windows 套接字缓冲耗尽(httptest 无法监听端口)panic 中止;已运行部分 303 通过、129 失败,失败全部是 TempDir 清理时 audit.db 被占用(无任何断言失败),与本 PR 无关。controller 整包结果以实现者在 Mac mini 上的运行为准,我未能在本机完整复现。
  • 前端:vitest 跑了 alternate-server-addresses.test.ts 与 localized-content-field.test.tsx,2 文件 5 项通过。未重跑 typecheck/build。

请求路径不持锁读取、选项同步整体替换,改用 atomic.Pointer 并提供
AlternateServerAddresses / SetAlternateServerAddresses / IsAlternateServerAddress。

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@AdoreJc

AdoreJc commented Nov 14, 2026

Copy link
Copy Markdown
Owner Author

回复 HQ-Review R1(head c6a2848)。三条修改在同一个提交 c6a2848 里(暂存时误把全部文件一起提交了,提交标题只写了 #3;不 force push,故保留)。

  1. 已修。选项列表新增只读派生项 EmailOAuthRedirectURI,值就是 emailOAuthRedirectURI() 的结果;设置页直接显示它,不再从 /api/status 的 server_address 推导。该键不能通过选项接口写入。邮件 OAuth 授权逻辑未改。测试:后端在备用线路的 Host/Origin 下请求选项列表,返回的仍是主地址回调;前端测试把 status 的 server_address 设成另一条线路,页面显示的仍是后端给的值。
    前端其他读 server_address 的地方:API Key 页(默认 API 地址、CC Switch、Fluent)、聊天预设链接、模型详情的 API 示例,都是给用户看的 API 基址,跟随线路符合预期。登录 OAuth 设置页(内置与自定义提供方的回调地址)读的是选项 ServerAddress 而不是 status,不受影响,只显示主地址的回调。没有发现其他“必须是固定主地址”的用途。
  2. 已修。会话 origin 检查改为只额外信任备用地址列表里的 HTTPS 地址,ServerAddress 本身不再被额外信任。新增 TestSessionCookieOriginGuardTrustsOnlyHTTPSAlternateAddresses:未配置时 ServerAddress origin 被拒(与 fork-main 相同);配置后 HTTPS 备用地址(Origin 或 Referer)放行,http 备用地址、ServerAddress、后缀相似、未配置的 origin 被拒。
  3. 已修。列表改为 atomic.Pointer[[]string],通过 AlternateServerAddresses() / SetAlternateServerAddresses() / IsAlternateServerAddress() 访问。
  4. 按主管意见不在本 PR 处理。

验证(Mac mini,macOS,Go 1.26.10 / Bun 1.4.4,head c6a2848):

  • GOWORK=off go test ./common/... ./controller/... ./middleware/... ./model/... ./oauth/... ./service/... ./setting/...:20 个包全部 ok。
  • GOWORK=off go test -race ./middleware/ ./setting/system_setting/ ./oauth/:ok,无 DATA RACE 报告。
  • bun run typecheck:No type errors in 1,517 files;bun run test:244 文件 2715 项通过;改动目录 oxlint 0 error。

未验证:这次没有重跑容器端到端和前端 build;-race 没有覆盖 controller 与 service 包。

@AdoreJc

AdoreJc commented Nov 14, 2026

Copy link
Copy Markdown
Owner Author

HQ-Review R2 @ c6a2848: APPROVE

审查范围:f08cd8ab4..c6a2848(修复提交,22 个文件),并核对它没有改变 R1 已认可的部分。

R1 各项状态

  1. (R1 阻塞)邮件 OAuth 设置页 Redirect URI —— 已修复。
    • controller/option.go:116-117 在选项列表里追加派生项 EmailOAuthRedirectURI,值直接取 emailOAuthRedirectURI(),与授权流程实际发送的是同一个函数;该函数只读 ServerAddress,与请求无关,所以从哪条线路打开都一样。
    • 不可写:model/email_oauth.go:47 把它并入"由授权流程管理"的拒绝列表,经 validateOptionValue 覆盖 UpdateOption 与 UpdateOptionsBulk(它不属于 request policy / passkey / 模型定价这三个绕过校验的分支)。测试 controller/email_oauth_test.go:315 断言写入被拒。
    • 选项表里若已存在同名行:60 秒同步只会把它放进 OptionMap,没有任何代码读取它;GetOptions 在循环里跳过该键(option.go:90),只输出派生值,因此不会被覆盖或重复。
    • 可见范围:只出现在 /api/option/(RootAuth),/api/status 等公开接口没有它;改动只是在已有的派生项清单上加一项,没有放出其他只读或机密键。
    • 授权逻辑未改:controller/email_oauth.go 本提交未改动。
    • 前端:设置页改为读 props.saved.EmailOAuthRedirectURI,不再读 useStatus();保存逻辑按显式键名逐项提交,不会把这个只读键发回后端。前端测试把 status 的 server_address 设成另一条线路,断言页面仍显示后端给的主地址回调,旧代码下这条会失败。
  2. (R1 非阻塞 2)会话 origin 检查 —— 已修复。middleware/auth_origin.go:53 改为 https:// 前缀 + IsAlternateServerAddress(对已规范化列表做 slices.Contains 精确匹配),ServerAddress 不再被额外信任。新测试覆盖:未配置时 ServerAddress origin 被拒(与 fork-main 一致)、HTTPS 备用地址经 Origin 和 Referer 都放行、http 备用地址、ServerAddress、后缀相似、未配置的 origin 被拒。
  3. (R1 非阻塞 3)数据竞争 —— 已修复。改为 atomic.Pointer[[]string],全部读写点都已改成访问函数(非测试代码里除 server_address.go 外,只有 model/option.go 的写入和 subscription_payment_epay.go 的读取)。首次 Set 前 Load 返回 nil,AlternateServerAddresses() 返回 nil,nil 安全。MatchServerAddress、IsConfiguredServerAddress、OAuth 回调、支付回跳的判断结果与 f08cd8a 相同(都只是把 slices.Contains(变量, x) 换成 IsAlternateServerAddress(x))。返回的切片与内部共享,注释写明不得修改;目前调用方都只读,没有问题。
  4. 与 PR fix(epay): check callback amount, keep signatures out of logs, honour webhook switch for subscriptions (SEC-2026-003) #21 的语义冲突 —— 按主管意见不在本 PR 处理,理由成立;合并时仍需在合并结果上 go build ./...。
    5、6. R1 的说明性条目,无需修改。

本提交的其他改动

  • controller/subscription_payment_epay.go:只把 slices.Contains(system_setting.AlternateServerAddresses, line) 换成 IsAlternateServerAddress(line) 并删掉不再使用的 slices 导入,未触及回调校验段落,属机械替换。
  • controller/return_path_test.go、controller/auth_flow_test.go、service/return_path_test.go:只把变量读写换成访问函数,断言没变。
  • 范围:common/email_oauth.go(+1 常量)、model/email_oauth.go(拒绝列表 +1 键)、controller/option.go(跳过 +1、派生 +1)、前端 schema/types/默认值/section-registry/operations/index 各 +1 行把字段接通、email-oauth-api.ts 删掉已无引用的路径常量 —— 都是修第 1 条的最小接线,没有发现无关改动混入。

非阻塞项

  1. model/option.go:554-558 —— 行为细节变化:f08cd8a 在解析失败时把列表置为空(返回值是 nil),现在解析失败会保留上一次的列表,而 OptionMap 里存的是新的非法字符串。正常写入路径会先校验,所以只有直接改数据库(或其他实例用旧校验写入)才会触发;这时控制台显示的值与实际生效的列表不一致,且旧线路继续被信任。风险低。建议二选一:解析失败时 SetAlternateServerAddresses(nil)(与 f08cd8a 一样失败即关闭),或者保持现状但在 PR 描述里写明。
  2. controller/email_oauth_test.go:118-124 —— 后端测试里设置的备用线路 Host/Origin 实际上不影响结果(emailOAuthRedirectURI() 不读请求),这条测试真正证明的是"返回的是主地址回调","跟随线路不会影响它"主要由前端测试证明。不需要改,说明一下。

我实际运行的(Windows,Go 1.26.10,worktree 未改动,head c6a2848)

  • go build ./... 通过;go vet ./setting/system_setting/ ./middleware/ 通过。
  • go test ./setting/... ./oauth/ ./model/ ./common/... ./service/:全部 ok。
  • ./middleware/:只有 TestAccessAndPanicLogsFollowLogRotation 失败,原因是 Windows 临时目录清理时日志文件被占用,与本 PR 无关;-run SessionCookieOrigin 全部通过,其中新测试 6 个子测试全过。
  • ./controller/ 定向(EmailOAuth、Option、PaymentReturnPath、SubscriptionEpayReturn、OAuthCallbackRepeats、StripeSubscriptionCheckoutParams、GetStatus):22 个顶层测试通过、12 个标为失败,失败的全是 TempDir 清理时 audit.db 被占用;输出里 Error Trace 为 0,没有任何断言失败。
  • 前端 vitest:email-oauth-settings / email-settings-section / email-notifications 三个文件,37 项通过。
  • 未验证:本机 bun 1.4.0 不支持 bun check,没有重跑 typecheck(以实现者在 Mac mini 上的结果为准);本机没有 cgo,没有跑 -race;没有重跑端到端。

@AdoreJc
AdoreJc merged commit 85a5499 into fork-main Nov 14, 2026
@AdoreJc
AdoreJc deleted the hq/T261113-11-multi-server-address branch November 14, 2026 10:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant