域名语言绑定

APay 可以让同一套部署接收多个精确域名,并为每个域名指定不同的前台默认语言。绑定改变的是无语言前缀 URL 的默认语言,不会把域名锁死为单一语言;其他已构建语言仍可通过 URL 前缀访问。

例如构建英文、中文和俄文后:

域名默认 URL其他语言示例
apay.example/ 为英文/zh、/ru
cn.apay.example/ 为中文/en、/ru
ru.apay.example/ 为俄文/en、/zh

构建配置

构建前设置 APAY_LOCALES 和 APAY_DOMAIN_LOCALES。APAY_DOMAIN_LOCALES 支持逗号分隔的 host=locale 列表或 JSON 对象:

APAY_LOCALES=en,zh,ru \
APAY_DOMAIN_LOCALES=apay.example=en,cn.apay.example=zh,ru.apay.example=ru \
APAY_PUBLIC_PROTOCOL=https \
npm run build
APAY_DOMAIN_LOCALES='{"apay.example":"en","cn.apay.example":"zh"}' npm run build

Host 使用精确匹配并统一转为小写。通配域名、协议、路径、用户信息、非法端口、同一 Host 的冲突绑定,以及未包含在 APAY_LOCALES 中的语言都会让构建明确失败。本地开发可以使用带端口的 Host,例如 localhost:3000=zh。

APAY_PUBLIC_PROTOCOL 可选,只接受 http 或 https。生产环境位于反向代理之后时应固定为 https,避免支付回调和邮件链接依赖不明确的内部连接协议。

未配置 APAY_DOMAIN_LOCALES 时,APay 保持单域名 APAY_DEFAULT_LOCALE 行为。还需在设置中配置绝对 HTTP(S) site_url,为 canonical、JSON-LD 和 /sitemap.xml 提供可信公网 Origin;APay 不会回退使用任意 Host Header。

请求行为

前台和业务 API 按以下顺序解析语言:

  1. URL 路由或 API 明确传入的 locale;
  2. 用户主动选择后保存的 i18n_redirected Cookie;
  3. 前台 Referer 中已支持的语言前缀;
  4. 当前域名绑定的默认语言;
  5. Accept-Language,最后回退站点默认语言。

用户第一次访问无前缀页面时,APay 会先把域名默认语言写入 i18n Cookie,再进入浏览器或 GeoIP 检测。用户之后主动选择的语言仍可在该域名生效。下单币种快照和支付方式语言过滤使用同一解析结果。

canonical 与 hreflang 保持在当前域名,因为本能力定义的是“默认语言”,不是“语言归属域名”。无前缀 URL 是该域名的 x-default,其他已构建语言继续使用正常前缀。JSON-LD 和 sitemap 使用同一可信 Origin 与语言路径,详见国际化 SEO 与结构化数据。

固定语言归属域名

需要简体中文只使用 shopark.net、英文和其他语言只使用 shopark.ai 时,在默认域名绑定之外启用 APAY_LOCALE_DOMAINS。它支持 locale=host 列表或 JSON,* 指定其余构建语言的归属;所有归属域名必须已包含在 APAY_DOMAIN_LOCALES 中,每种构建语言都必须有归属,归属域名的无前缀语言必须与绑定一致,否则构建失败。

仓库提供公开构建配置 config/shopark-domains.env:

APAY_BUILD_THEMES=shopark
APAY_LOCALES=en,zh,zh-HK,ru
APAY_DEFAULT_LOCALE=en
APAY_DOMAIN_LOCALES=shopark.net=zh,shopark.ai=en
APAY_LOCALE_DOMAINS=zh=shopark.net,*=shopark.ai
APAY_PUBLIC_PROTOCOL=https

使用该配置构建(数据库、会话密钥等私有变量仍由原部署环境提供):

node scripts/build-shopark-domains.mjs

还须在后台“本地化”的 supported_locales 中启用 en,zh,zh-HK,ru。构建语言只创建路由,非空后台白名单仍可将该语言拦截为 HTTP 404;例如 supported_locales=en,zh,ru 即使已构建繁体包,也会拒绝 /zh-HK。使用同一数据库的本地主题共用此设置。

语言唯一前台网址
简体中文https://shopark.net/
英文https://shopark.ai/
香港繁体https://shopark.ai/zh-HK
俄文https://shopark.ai/ru

语言切换保留当前页面、query 和片段并前往归属域名。前台 GET/HEAD 的错误域名、冗余默认语言前缀和 www 别名通过 HTTP 301 规范化,例如 shopark.ai/zh/page/pricing?ref=x → shopark.net/page/pricing?ref=x。客户端前台导航遵循同一规则。URL 决定语言,旧 Cookie、localStorage、后台默认语言和浏览器语言不覆盖该 URL。

API、后台、登录、用户中心、支付页、回调及静态资源不做自动跨域语言重定向,也不修改 POST 请求。用户主动在语言菜单切换时仍可跨域;账号 Cookie 与登录会话按域名独立,不提供跨域免登录。

canonical、og:url 和结构化数据中的页面 URL 使用归属域名,hreflang 双向指向各语言的规范 URL。两边的 x-default 均使用构建期 APAY_DEFAULT_LOCALE(本配置为英文)。每个域名的 sitemap 只收录自身语言的 <loc>,同时输出跨域 alternates。未设置 APAY_LOCALE_DOMAINS 时,上述默认语言绑定行为保持不变。

上线前确保两个主域名及已声明的 www 别名均有 DNS、TLS 和反向代理配置,再检查初次访问、旧语言偏好、语言切换、301 无循环、SSR SEO 与两个 sitemap。运行 node --experimental-strip-types scripts/check-locale-domains.mjs 验证语言归属契约;该守卫也在 prebuild 中强制执行。回滚可恢复上一产物,或移除 APAY_LOCALE_DOMAINS 后重建以恢复普通默认语言绑定;不涉及数据库或支付状态回滚。浏览器已缓存的 301 可能持续生效,部署前应先在测试环境验证。

使用临时数据库(active_theme=shopark)在本机 5489 端口启动构建产物后,可运行 node scripts/check-locale-domains-http.mjs。通过 APAY_DOMAIN_CHECK_BASE_URL 指定其他本机地址;该探测拒绝非本机目标,使用 Host 请求头,不访问公网域名。它验证 GET/HEAD 重定向、旧 Cookie、转发 Host、SSR 标签、分域名 sitemap、未知 Host 拒绝及会话/支付排除范围。

DNS、证书、代理与缓存

每个配置域名必须先完成所有权验证,并指向同一 APay 部署;启用映射前先准备 DNS 和有效 TLS 证书。反向代理必须覆盖而不是追加用户可控的 X-Forwarded-Host 与 X-Forwarded-Proto。

启用映射后,转发 Host 或直连 Host 只有精确命中构建 allowlist 才会被接受;未知 Host 会由核心服务端中间件返回 HTTP 400。Nitro SSR 内部可以通过 GET/HEAD 读取 /api/settings 和 /api/_nuxt_icon/<collection>.json(支持图标 query)。该例外必须带有 Nitro 内部请求标记,HTTP 请求头无法启用;私有 API 和写入方法仍须通过 Host 校验。这些公开读取不生成绝对 URL,也不改变域名语言。注册验证链接、待支付邮件链接、支付回调和默认支付返回地址还会在业务写入或支付插件执行前再次校验可信 Origin。APay 不会用未识别的 Host Header 静默生成外链。

node --experimental-strip-types scripts/check-domain-host-guard.mjs 在隔离 IO 下执行真实 Host 中间件,验证内部设置/图标读取,以及未知 Host、伪造内部请求头、私有路径和写方法的拒绝行为;语言归属的 prebuild 守卫也会运行此检查。

后台 SSR 会话读取使用 useRequestFetch() 转发当前请求的 Cookie 和域名请求头。只转发 Cookie 会导致内部 /api/admin/session 请求被 Host 校验拒绝,页面刷新(包括后台语言切换)便表现为退出登录。scripts/check-admin-session-domains.mjs 已纳入语言归属 prebuild 守卫,验证两个域名、四种语言下的加密会话,同时保留未登录与未知域名的拒绝行为。后台切换语言保持当前域名,仍不提供跨域免登录。

Nuxt 构建子进程在预渲染内容索引时可能使用内部 Host。APay 构建包装器会为该子进程设置 APAY_NUXT_BUILD=1,只跳过前台全局 Host 拒绝;可信 Origin 生成仍保持严格校验。部署运行时不得配置这个构建标记。

CDN 和反向代理缓存键必须包含 Host,不能让不同域名共享 / 的 SSR HTML 缓存。

上线与回滚

  1. 验证域名所有权、DNS、TLS、代理头和包含 Host 的缓存键。
  2. 使用完整的 APAY_LOCALES、APAY_DOMAIN_LOCALES 和 APAY_PUBLIC_PROTOCOL=https 构建。
  3. 在每个域名检查 /、其他语言前缀、注册邮件、待支付邮件和沙箱支付回调。
  4. 检查 canonical、hreflang,并确认未知 Host 请求被拒绝。

回滚时部署旧产物,或移除 APAY_DOMAIN_LOCALES 与 APAY_PUBLIC_PROTOCOL 后重新构建,并把流量恢复到主域名。不需要回滚数据库、改写订单快照、修改支付状态或处理生产数据。