diff --git a/docs/前端独立部署-接口落实任务清单.md b/docs/前端独立部署-接口落实任务清单.md index e856da05..51c7b9c8 100644 --- a/docs/前端独立部署-接口落实任务清单.md +++ b/docs/前端独立部署-接口落实任务清单.md @@ -1,8 +1,11 @@ -# 前端独立部署 4 接口 · 项目落实任务清单 +# 前端独立部署 · 项目落实任务清单 -> 关联接口(`pending-updates.json` 2026-09-08 added): -> `frontConfig.getByDomain`、`setting.warehouse.getFrontConfig`、`setting.warehouse.saveFrontConfig`、`setting.warehouse.saveFrontCert` -> 目标:按后端「SaaS 仓库前端独立部署 + 按域名品牌化」设计把 4 接口在本项目全部落实。 +> 当前口径(2026-09-24 更正):全部能力已迁入独立模块 **前端独立部署模块 `frontConfig.*`(共 8 个方法)**: +> `frontConfig.getByDomain`(公网拉品牌,免登录免鉴权)、`frontConfig.getInfo` / `frontConfig.saveInfo`(品牌)、 +> `frontConfig.getDomain` / `frontConfig.setDomain` / `frontConfig.checkDomain`(域名 + DNS TXT 归属验证)、 +> `frontConfig.getCert` / `frontConfig.saveCert`(证书)。 +> 旧口径 `setting.warehouse.getFrontConfig / saveFrontConfig / saveFrontCert` 已废弃,前端封装已移除。 +> 历史背景(`pending-updates.json` 2026-09-08 added):`frontConfig.getByDomain`、`setting.warehouse.*` 共 4 接口。 --- @@ -10,15 +13,25 @@ | 接口 | 角色 | 鉴权 | 状态 | |---|---|---|---| -| `setting.warehouse.getFrontConfig` | 仓库侧配置回显 | 登录 + 仓库主体 | ✅ 已接入 | -| `setting.warehouse.saveFrontConfig` | 仓库侧保存品牌 | 登录 + 仓库主体 | ✅ 已接入 | -| `setting.warehouse.saveFrontCert` | 仓库侧上传域名+证书 | 登录 + 仓库主体 | ✅ 已接入 | -| `frontConfig.getByDomain` | 公网按域名拉品牌 | 免登录/免鉴权 | ❌ 未接入(消费端缺口) | +| `frontConfig.getByDomain` | 公网按域名拉品牌(仅放行 domain_status=1) | 免登录/免鉴权/免权限 | ✅ 已接入(store 消费端) | +| `frontConfig.getInfo` | 仓库侧品牌回显(8 字段) | 登录 + 仅仓库主体 | ✅ 已接入 | +| `frontConfig.saveInfo` | 仓库侧保存品牌 | 登录 + 仅仓库主体 | ✅ 已接入 | +| `frontConfig.getDomain` | 仓库侧域名与验证状态回显(9 字段) | 登录 + 仅仓库主体 | ✅ 已接入 | +| `frontConfig.setDomain` | 设置/变更域名 + 发起 DNS TXT 验证 | 登录 + 仅仓库主体 | ✅ 已接入 | +| `frontConfig.checkDomain` | 主动校验 DNS TXT 并回写 | 登录 + 仅仓库主体 | ✅ 已接入 | +| `frontConfig.getCert` | 仓库侧证书回显(13 字段,含 can_set_cert) | 登录 + 仅仓库主体 | ✅ 已接入 | +| `frontConfig.saveCert` | 上传证书(域名取库内已验证记录) | 登录 + 仅仓库主体 | ✅ 已接入 | + +> 兼容说明:`setting.warehouse.getFrontConfig / saveFrontConfig / saveFrontCert` 后端仍存在,但已不是本页流程口径; +> `setting.warehouse.getSettings / getFieldMeta / saveSettings / getweChatApp` 不受影响。 --- ## 2. 现状盘点 +> 以下 §2 / §3 / §4 为 2026-09-08 首次落实时的盘点与任务记录(历史留档)。 +> 其中涉及的 `setting.warehouse.getFrontConfig / saveFrontConfig / saveFrontCert` 口径已于 2026-09-24 更正,最新口径见 §1 与 §6。 + ### 2.1 已完成 - **API 封装** - `src/api/frontconfig/frontConfig.ts`(新目录,`frontConfigGetByDomain` + `FrontConfigPublicItem`) @@ -117,8 +130,39 @@ --- ## 5. 风险与边界(后端约束提醒) -- `saveFrontCert`:`domain` 全局唯一(占用→409);pem/key 成对必填;证书须可解析、未过期、SAN/CN 覆盖 domain,任一失败统一「证书不合法」(400) —— 前端不要过度拆解错误。 -- `saveFrontConfig`:只受理品牌字段,`domain`/证书字段传了也会被白名单忽略;`theme` 须合法 JSON 对象或 JSON 字符串。 -- `getByDomain`:仅返回公开品牌字段,绝不返回证书/同步内部字段;未登记域名返回 404 + 60s 空缓存防穿透。 -- 证书 PEM/私钥:禁止出现在前端响应/日志;前端只需展示由 `getFrontConfig` 返回的 `cert_expire_at/sync_status` 等。 -- 主题结构:`theme` 仅作动态 CSS 变量容器(顶层标量键→`--`,文案类不再放主题)。网页名称/Logo 等业务语义由品牌顶层字段承担:网页名称=`title`、主页面/登录页 Logo=`logo_url`(`getByDomain` 读取、`saveFrontConfig` 保存)。历史 theme 中曾约定的 siteName/mainLogoUrl/loginLogoUrl/loginText 不再展示/编辑,保存时透传保留。 +- `frontConfig.setDomain`:`domain` 全局唯一(占用→409);格式需至少两段标签且每段 1~63 位字母数字与连字符(排除通配符/下划线/首尾点),否则 400;**域名变更会同时清空既有证书并重置同步状态**;同一域名重复设置时已验证则幂等返回(不刷新校验码、不清证书)。 +- `frontConfig.checkDomain`:解析目标为库内 `domain_verify_host`(不解析裸域名);DoH 优先、失败降级系统 DNS;失败时 `domain_status=2`、`attempts+1`、`last_error` 截断 ≤500 字符。 +- `frontConfig.saveCert`:**不接受 domain 入参**(前端传了也忽略);无域名→400「请先设置并验证域名」,`domain_status≠1`→400「域名未通过验证,暂时无法上传证书」;证书校验链任一失败统一 400「证书不合法」(不吐细节);`cert_expire_at` 以证书 validTo 权威写入;`cert_path/key_path` 置空,等 crontab 脚本部署后回填。 +- 证书可设置性:前端按 `getCert` 的 `can_set_cert` / `can_set_cert_reason` 置灰上传入口(无域名「请先设置域名」/ 未验证「域名待验证」/ 失败「域名验证失败」)。 +- `frontConfig.saveInfo`:只受理品牌字段,`domain`/证书字段由白名单静默忽略;`theme` 须合法 JSON 对象或 JSON 字符串;保存即重置同步状态(sync_status=0、attempts=0、清空错误与时间)并清当前域名公共缓存。 +- `frontConfig.getByDomain`:仅放行 `domain + domain_status=1`,未验证/验证失败一律按未配置返回 404「域名未配置」;仅返回 6 个公开字段,绝不返回证书/私钥/同步等内部字段;未登记域名写 60s 空缓存防穿透。 +- 证书 PEM/私钥:禁止出现在前端日志;私有回显(`cert_pem`/`key_pem`)仅在仓库主体登录后的 settings 页接口。 +- 主题结构:`theme` 仅作动态 CSS 变量容器(顶层标量键→`--`)。网页名称/Logo 等业务语义由品牌顶层字段承担:网页名称=`title`、主页面/登录页 Logo=`logo_url`。历史 theme 中曾约定的 siteName/mainLogoUrl/loginLogoUrl/loginText 不再展示/编辑,保存时透传保留。 + +--- + +## 6. 2026-09-24 流程更正:迁入 frontConfig.* 8 接口 + +### 6.1 差异(旧 → 新) + +| 能力 | 旧口径 | 新口径 | +|---|---|---| +| 品牌回显/保存 | `setting.warehouse.getFrontConfig` / `saveFrontConfig`(15 字段,含证书/同步) | `frontConfig.getInfo` / `saveInfo`(8 字段,不再混载证书) | +| 证书回显/上传 | `setting.warehouse.saveFrontCert`(`domain + pem + key` 一次提交) | `frontConfig.getCert` / `saveCert`(域名不再入参,一律取库内已验证记录;新增 `can_set_cert` 闸门) | +| 域名与 DNS 验证 | 无(仅随证书一起提交域名) | `frontConfig.getDomain` / `setDomain` / `checkDomain`(TXT 归属验证,未验证不可上传证书;换域名会清证书) | +| 公网拉品牌 | `frontConfig.getByDomain`(按 domain 查库) | 同方法,但**仅放行 domain_status=1 的已验证域名** | + +### 6.2 前端落点 +- API:`src/api/frontconfig/frontConfig.ts` 新增 7 个方法 + `FrontConfigInfo` / `FrontConfigDomain` / `FrontConfigCheckDomainResult` / `FrontConfigCert` / `FrontConfigSaveInfoParams` / `FrontConfigSaveCertParams` 类型 + `FRONT_DOMAIN_STATUS` 状态常量;`setting.warehouse.ts` 中 3 个旧封装与类型已移除。 +- 页面:`.../newview/pages/FrontConfigForm.vue` 改为**左菜单 + 右内容**布局(参考微信小程序配置页),菜单为 **域名设置 → HTTPS 证书 → 品牌配置**: + - 域名菜单:`setDomain` 保存(生成 TXT 主机名/记录值,可一键复制)+ `checkDomain` 校验 + 「刷新状态」仅重查 `getDomain`; + - 证书段:`getCert` 回显(cert_pem/key_pem 与复制入口)、`can_set_cert=false` 时置灰「上传证书」并提示原因、证书到期/临期告警、同步状态与错误展示; + - 品牌段:`getInfo` 回显 + `saveInfo` 保存(保留历史 theme 透传与自定义 CSS 变量键值编辑),底部展示 `updated_at`。 +- 加载:三个接口 `Promise.all` 并行拉取,均未配置时返回默认空值而非 404。 + +### 6.3 验收回归建议(增量) +- ① 新增域名 → `getDomain` 返回 verify_host/verify_value 且 domain_status=0,上传证书按钮置灰并提示「域名待验证」; +- ② 添加 TXT 后 checkDomain → domain_status=1,上传入口解禁,且已配置证书被清空(换域名场景); +- ③ 未验证域名直接调 saveCert → 400「域名未通过验证,暂时无法上传证书」;无域名 → 400「请先设置并验证域名」; +- ④ 未验证域名访问 `getByDomain` → 404「域名未配置」→ 前端保持默认品牌; +- ⑤ 品牌保存 → `getInfo` 回显一致,`updated_at` 刷新,同步状态重置为待同步。 diff --git a/docs/前端独立部署-操作与部署说明.md b/docs/前端独立部署-操作与部署说明.md index 0061295e..67975801 100644 --- a/docs/前端独立部署-操作与部署说明.md +++ b/docs/前端独立部署-操作与部署说明.md @@ -1,7 +1,13 @@ # 前端独立部署 · 操作与部署说明(C2) > 适用:仓库「自持域名 + 品牌化」的配置与部署运维。关联任务清单 `docs/前端独立部署-接口落实任务清单.md`。 -> 关联接口:`setting.warehouse.getFrontConfig / saveFrontConfig / saveFrontCert`(仓库侧管理)、`frontConfig.getByDomain`(公网品牌拉取)。 +> 关联接口(前端独立部署模块 `frontConfig.*`,共 8 个): +> - 公网消费端:`frontConfig.getByDomain`(免登录免鉴权,按 hostname 拉品牌) +> - 品牌配置:`frontConfig.getInfo` / `frontConfig.saveInfo` +> - 域名与 DNS 验证:`frontConfig.getDomain` / `frontConfig.setDomain` / `frontConfig.checkDomain` +> - 证书:`frontConfig.getCert` / `frontConfig.saveCert` +> +> 已废弃口径:`setting.warehouse.getFrontConfig / saveFrontConfig / saveFrontCert`(域名+证书一步提交的时代)。 --- @@ -10,51 +16,71 @@ ``` 仓库侧(本系统 ·「前端独立部署」标签页) 后端 部署后的浏览器 ────────────────────────────────────────────────────────────────────────────── -1 保存品牌 title/logo/favicon/login_bg/theme → wms_warehouse_front_config -2 上传域名 domain + 证书 pem/key(saveFrontCert) - → 校验证书/写 cert_expire_at - → 定时任务部署证书并回填 cert_path/key_path - → Redis 缓存 front:config:domain:{domain} -3 访问 https://<自持域名>/... │ +1 保存自持域名(setDomain) → 生成校验子域 verify_host + 校验值 verify_value + domain_status=0(未验证) +2 域名服务商添加 TXT 记录 → 点「校验 DNS」(checkDomain) + → domain_status=1(已验证)/ 2(验证失败) +3 上传证书 pem/key(saveCert,域名取库内已验证 domain) + → 校验:可解析→未生效/过期→SPKI 配对→SAN/CN 覆盖域名 + → 写 cert_expire_at;crontab 脚本部署证书回填 cert_path/key_path +4 保存品牌 title/logo/favicon/login_bg/theme(saveInfo) + → 重置同步状态并清公共缓存 +5 访问 https://<自持域名>/... │ ▼ 免鉴权 frontConfig.getByDomain(domain) ← 按 hostname 拉品牌 应用:网页名称(title)/主页面·登录页 Logo(logo_url)/背景/favicon、 document.title、其余 theme 键→CSS 变量(theme 不再承载业务键) ``` -- 品牌与「域名+证书」**分开保存**;变更域名必须走 `saveFrontCert`(重新校验证书)。 -- 证书的部署落地由**后端定时任务**完成,前端不处理 PEM/私钥明文。 +- 顺序硬约束:**先域名并通过 DNS 校验(domain_status=1),才能上传证书**。 +- **域名变更会清空既有证书并重置同步状态**(避免 nginx 继续用旧域名证书对外服务),需重新上传证书。 +- 品牌与「域名 / 证书」**分开保存**、互不覆盖(`saveInfo` 白名单静默忽略 domain 与证书字段)。 +- 证书的部署落地由**后端 crontab 脚本**完成,前端只负责 PEM 文本上传与状态展示。 --- ## 2. 仓库侧操作(网页后台) 入口:**系统设置 → 基础设置(仓库设置)→「前端独立部署」标签页**(`basicManagement/newview` 独立表单页 `FrontConfigForm.vue`,由 `config/template-config.ts` 的 `tabPages` 注册;已不再挤在基础设置页内)。 +页面为**左侧菜单 + 右侧内容**布局(与「微信小程序」标签页一致):左侧三个菜单 **域名设置 → HTTPS 证书 → 品牌配置**(顺序与接口调用一致,菜单项带状态标签:域名待验证 / 证书同步失败 / 待域名验证),右侧为对应菜单的表单与告警;右侧内容区独立滚动。 -### 2.1 保存品牌配置(saveFrontConfig) +### 2.1 域名设置与 DNS 归属验证(setDomain / getDomain / checkDomain) +1. 填写 自持域名 `domain`(≤100,全局唯一,统一转小写;多段标签、每段 1~63 位字母数字与连字符)。 +2. 点击「保存域名」→ `frontConfig.setDomain`: + - 生成一次性校验子域 `verify_host`(形如 `wmsv-<10 位 hex>.`)与校验值 `verify_value`(32 位 hex),`domain_status=0`(未验证); + - 域名已被其他仓库占用 → 409「域名 X 已被其他仓库使用」; + - **域名变更(仅大小写差异不算变更)会清空既有证书并重置同步状态。** +3. 到域名服务商为该主机名添加 **TXT 记录**(值为 `verify_value`),前端部署按 CNAME 指向 `cname`。 +4. 点击「校验 DNS」→ `frontConfig.checkDomain`: + - 通过 → `domain_status=1`(已验证),写入 `verified_at`,并清理该域名的公共拉取缓存; + - 失败 → `domain_status=2`(验证失败),`attempts` +1,页面展示 `last_error`(如「未解析到 TXT 记录」「TXT 记录未包含校验值」)。 + - 说明:解析走 DoH 优先、失败降级系统 DNS;DNS 生效有延迟,稍后重试即可。 + - 「刷新状态」按钮:仅重查 `frontConfig.getDomain`,刷新验证状态与 TXT 信息,不覆盖尚未保存的域名输入(顶部「刷新」则整页重拉三段)。 + +### 2.2 上传 HTTPS 证书(getCert / saveCert) +1. 页面回显当前仓库证书 `cert_pem` / 私钥 `key_pem`,可直接修改后重新上传。 +2. 粘贴 证书 PEM `pem`(≤65536)、私钥 PEM `key`(≤65536)。 +3. 点击「上传证书」→ `frontConfig.saveCert`: + - **域名不再是入参**,一律取库内已设置并验证通过的 `domain`; + - 前置闸门:无域名 → 400「请先设置并验证域名」;`domain_status≠1` → 400「域名未通过验证,暂时无法上传证书」; + - 前端按 `getCert` 返回的 `can_set_cert` / `can_set_cert_reason` 置灰上传入口(无域名「请先设置域名」/ 未验证「域名待验证」/ 失败「域名验证失败」)。 + +成功后自动: +- 写入 `cert_expire_at`(以证书 validTo 为准); +- 重置同步状态 `sync_status=0`(页面「证书状态」展示同步状态、尝试次数、最近同步时间); +- 清空当前域名的公共缓存(后端处理)。 + +### 2.3 保存品牌配置(getInfo / saveInfo) - 字段: - 站点标题 `title`(≤100) - Logo `logo_url`、favicon `favicon_url`、登录背景 `login_bg_url`(各 ≤255) - 主题 `theme`:仅承载“自定义 CSS 变量”键值,保存时组装为 JSON 对象 - 每个键即前端 CSS 变量名(如 `primary`→`--primary`),值支持文本或 JSON(对象/数组/数字/布尔);应用时顶层标量键写入 `--` - - 网页名称/Logo 等业务字段一律使用上方品牌顶层字段配置:网页名称=`title`、主页面/登录页 Logo=`logo_url`、登录背景=`login_bg_url`、favicon=`favicon_url`(`getByDomain` 读取、`saveFrontConfig` 保存) + - 网页名称/Logo 等业务字段一律使用上方品牌顶层字段配置:网页名称=`title`、主页面/登录页 Logo=`logo_url`、登录背景=`login_bg_url`、favicon=`favicon_url`(`getByDomain` 读取、`saveInfo` 保存) - 历史 theme 中曾约定过的 `siteName/mainLogoUrl/loginLogoUrl/loginText` 不再展示与编辑,保存时原样透传保留(不丢失历史数据) - 品牌字段留空即清空该字段;主题自定义键删空全部行=清空主题。 -- 点击「保存品牌配置」→ 成功后自动刷新回显。 -- 说明:此处不受理 `domain`/证书字段(后端白名单忽略)。 - -### 2.2 上传自持域名与证书(saveFrontCert) -1. 填写 自持域名 `domain`(≤100,全局唯一)。 -2. 粘贴 证书 PEM `pem`(≤65536)。 -3. 粘贴 私钥 PEM `key`(≤65536)。 -4. 点击「上传证书」。 - -成功后自动: -- 写入 `cert_expire_at`(以证书 validTo 为准); -- 重置同步状态 `sync_status=0`(页面「同步详情」可看尝试次数/最近同步); -- 清空旧/新域名的公共缓存(后端处理)。 - -页面 meta 会展示:证书状态(未上传/正常/临期/过期)、同步状态与失败原因,便于自助排查。 +- 点击「保存品牌配置」→ 成功后自动刷新回显(面板底部展示 `updated_at` 最近更新)。 +- 说明:此处不受理 `domain`/证书字段(后端白名单静默忽略,不报错也不生效)。 --- @@ -75,7 +101,7 @@ - 必须满足: - 证书可解析、当前已生效、未过期; - 私钥与证书成对(后端按 SPKI 公钥指纹比对); - - 证书 `SAN DNS` / `CN` 覆盖所填 `domain`(支持精确匹配与 `*.example.com` 通配)。 + - 证书 `SAN DNS` / `CN` 覆盖**库内已保存的 `domain`**(支持精确匹配与 `*.example.com` 通配,通配仅覆盖恰好一级标签:`*.a.com` 覆盖 `b.a.com`,不覆盖 `x.y.a.com`)。 - 生成(示意,正式环境请用 CA 签发): ```bash # 自签测试证书(SAN 包含 domain) @@ -85,7 +111,7 @@ -addext "subjectAltName=DNS:self.example.com,DNS:*.example.com" # 分别把 cert.pem、key.pem 内容填入页面 ``` -- 提示:同一证书可在 SAN 里放多个域名;换域名/加域名都需重新走 `saveFrontCert`。 +- 提示:同一证书可在 SAN 里放多个域名;换域名/加域名需先 `setDomain` + `checkDomain` 通过,再重新上传证书。 --- @@ -93,29 +119,34 @@ | 现象 / 返回 | 原因 | 处理 | |---|---|---| -| 400「证书不合法」(统一文案,不返回细节) | 证书无法解析 / 未生效或已过期 / 私钥与证书不匹配 / SAN 或 CN 未覆盖 domain | 检查 PEM 完整性与配对、有效期、SAN 是否包含 domain;用 `openssl x509 -in cert.pem -noout -text` 核对 | -| 409 | 该 `domain` 已被其他仓库占用 | 换未占用域名,或联系占用方释放 | -| 400「domain 长度不能超过 100 字符」 | domain 超长 | 缩短域名 | +| 400「域名不能为空」/「domain 格式不正确」/「domain 长度不能超过 100 字符」 | `setDomain` 入参缺失、形态非法(含通配符、下划线、单段主机名等)或超长 | 填 至少两段标签、每段 1~63 位字母数字与连字符(首尾不得为连字符)、≤100 字符 | +| 409「域名 X 已被其他仓库使用」 | `domain` 全局唯一,已被占用 | 换未占用域名,或联系占用方释放 | +| 400「请先设置域名」 | `checkDomain` 时库内无域名 | 先走「保存域名」(setDomain) | +| 400「请先设置并验证域名」 | `saveCert` 前尚未设置域名 | 先 setDomain → 添加 TXT 记录 → checkDomain | +| 400「域名未通过验证,暂时无法上传证书」 | `domain_status≠1`(未验证/验证失败) | 确认 TXT 记录已生效后点「校验 DNS」;页面按 `can_set_cert_reason` 置灰上传入口 | +| 校验 DNS 失败:未解析到 TXT 记录 / TXT 记录未包含校验值 / DNS 解析失败 | TXT 记录未添加、主机名写错、未生效或值不一致 | 核对「TXT 主机名 + TXT 记录值」(`verify_host` / `verify_value`),DNS 生效后重试 | +| 400「证书不合法」(统一文案,不返回细节) | 证书无法解析 / 未生效或已过期 / 私钥与证书不匹配 / SAN 或 CN 未覆盖库内 domain | 检查 PEM 完整性与配对、有效期、SAN 是否包含域名;用 `openssl x509 -in cert.pem -noout -text` 核对 | | 400「pem/key 内容长度不能超过 65536 字符」 | 证书/私钥文本过大 | 检查是否误粘贴多个证书 | -| 保存品牌后 `getByDomain` 仍返回旧值 | 缓存 600s 内 | 等缓存过期或由后端保存时清缓存(saveFrontConfig/saveFrontCert 已清旧域名缓存) | -| 上传成功但 `sync_status=1/2` | 证书部署/同步中或失败 | 看「同步详情」`last_sync_error`,按需重新上传 | -| 域名已生效但 `cert_expire_at` 为空 | 证书未上传(仅登记 domain?) | 补传证书(saveFrontCert) | +| 保存品牌后 `getByDomain` 仍返回旧值 | 缓存 600s 内 | 等缓存过期;`saveInfo` / `saveCert` 成功后后端会自动清该域名缓存 | +| 上传成功但 `sync_status=1/2` | 证书部署/同步中或失败 | 看「证书状态」的同步状态与 `last_sync_error`,按需重新上传 | +| 域名已生效但 `cert_expire_at` 为空 | 证书未上传 | 补传证书(saveCert) | +| 访问自持域名仍是默认品牌(`getByDomain` 404「域名未配置」) | 域名未验证(`domain_status≠1`)、未登记、或前端豁免域名命中(主域名会跳过拉取) | 先完成 DNS 校验;确认 `.env` 的 `VITE_FRONT_CONFIG_EXEMPT_HOSTS` 未把该域名当作主域名豁免 | --- ## 5. 前端侧部署与验证 -1. 把本系统部署(或已有部署)解析到自持域名:`<自持域名> -> 部署 IP/负载`,并配置 HTTPS(证书由后端部署链路提供,前端不需持证)。 +1. 把本系统部署(或已有部署)解析到自持域名:按页面「CNAME 指向」把 `<自持域名> -> `,并配置 HTTPS(证书由后端部署链路提供,前端不需持证)。 2. 浏览器访问 `https://<自持域名>`:前端入口自动按 `location.hostname` 调 `frontConfig.getByDomain` 应用品牌。 - 生效项:网页名称=`title`(登录页标题与 document.title)、主页面/登录页 Logo=`logo_url`、登录背景、favicon;其余 `theme` 键→CSS 变量(`--`)。登录页文字无独立配置字段,用默认标语“现代化仓储管理系统 - 助力企业高效运营”。 -3. 未登记域名 / 直连主域名:接口返回 404 / `configured=false` → 前端静默使用系统默认品牌(无报错)。 -4. 本地联调建议:改 hosts 把自持域名指向本机测试环境即可看到品牌效果;确认无旧品牌残留可清理站点数据后刷新。 +3. 未登记域名 / 未验证域名(`domain_status≠1`)/ 直连主域名(命中 `VITE_FRONT_CONFIG_EXEMPT_HOSTS`):接口返回 404 / `configured=false` → 前端静默使用系统默认品牌(无报错)。 +4. 本地联调建议:改 hosts 把自持域名指向本机测试环境即可看到品牌效果;注意本地调试可把 `VITE_FRONT_CONFIG_EXEMPT_HOSTS` 置空(不豁免)以验证品牌;确认无旧品牌残留可清理站点数据后刷新。 5. **多仓库同一部署的域名解析(A6)**:一套前端部署可同时服务多个仓库—— - - 各仓库在各自「前端独立部署」标签页里登记自己的 `domain`(一仓一行、`domain` 全局唯一),并各自保存品牌/证书; + - 各仓库在各自「前端独立部署」标签页里登记自己的 `domain`(一仓一行、`domain` 全局唯一)并通过 DNS TXT 校验,各自保存品牌/证书; - 后端按访问 hostname 从 `wms_warehouse_front_config` 及缓存 `front:config:domain:{domain}` 返回对应仓库的公开品牌; - 前端仅按 `location.hostname` 调 `frontConfig.getByDomain`,对“多仓库同部署”无感知; - - `saveFrontConfig`/`saveFrontCert` 保存成功后后端会自动清理新旧域名缓存,因此换域名/改品牌基本即时生效(600s 缓存窗口内读到旧值属正常,无需前端处理); - - 访问主域名或未登记域名 → 返回 404 / `configured=false` → 前端走系统默认品牌。 + - `saveInfo` / `setDomain` / `checkDomain` / `saveCert` 成功后后端会自动清理相关域名缓存,因此换域名/改品牌基本即时生效(600s 缓存窗口内读到旧值属正常,无需前端处理); + - 访问主域名或未登记/未验证域名 → 返回 404 / `configured=false` → 前端走系统默认品牌。 --- @@ -123,8 +154,8 @@ | 层 | 文件/位置 | |---|---| -| API 封装 | `src/api/frontconfig/frontConfig.ts`;`src/api/setting.warehouse/settingwarehouse.ts`(3 个管理接口) | -| 配置管理(独立标签页) | `src/views/system/setting/basicManagement/newview/pages/FrontConfigForm.vue`(品牌配置 + 自持域名&证书);tab 注册:`.../newview/config/template-config.ts` `tabPages`(name=`frontConfig`);基础设置页已移除该区块(`.../pages/WarehouseSettingsForm.vue` 仅剩仓库配置) | +| API 封装 | `src/api/frontconfig/frontConfig.ts`(`frontConfig.*` 8 个方法:getByDomain / getInfo / saveInfo / getDomain / setDomain / checkDomain / getCert / saveCert) | +| 配置管理(独立标签页) | `src/views/system/setting/basicManagement/newview/pages/FrontConfigForm.vue`(域名设置 + HTTPS 证书 + 品牌配置);tab 注册:`.../newview/config/template-config.ts` `tabPages`(name=`frontConfig`);基础设置页已移除该区块(`.../pages/WarehouseSettingsForm.vue` 仅剩仓库配置) | | 品牌 store | `src/stores/modules/frontBrand.ts`(loadBrandByDomain / applyThemeCssVars / applyBrandGlobals) | | 入口触发 | `src/main.ts` | | 登录页品牌 | `src/views/login/index.vue` | diff --git a/src/api/frontconfig/frontConfig.ts b/src/api/frontconfig/frontConfig.ts index 5b1901a7..ed1931d2 100644 --- a/src/api/frontconfig/frontConfig.ts +++ b/src/api/frontconfig/frontConfig.ts @@ -2,6 +2,39 @@ import request from '@/utils/request' const v = '1.0' +/** 请求选项:silentError=true 时全局拦截器不弹错误提示(公共品牌拉取失败属预期分支) */ +export type FrontConfigRequestOptions = { silentError?: boolean } + +/** frontConfig.* 统一 POST 入口(系统标准入口 /system,method 经 params 下发) */ +function postFrontConfig>( + method: string, + data: Record = {}, + options: FrontConfigRequestOptions = {} +): Promise { + return request({ + url: '/system', + method: 'post', + params: { + method, + v, + timestamp: new Date().getTime() + }, + data, + isSystemApi: true, + ...(options.silentError ? { silentError: true } : {}) + } as any) +} + +/** 域名验证状态:0 未验证 / 1 已验证 / 2 验证失败 */ +export const FRONT_DOMAIN_STATUS = { + /** 未验证(已生成 TXT 校验记录,等待校验) */ + unverified: 0, + /** 已验证(唯一可上传证书的状态) */ + verified: 1, + /** 验证失败 */ + failed: 2 +} as const + /** frontConfig.getByDomain 响应:仓库前端公开品牌配置(不含证书/同步等内部字段) */ export type FrontConfigPublicItem = { /** 仓库自持域名 */ @@ -21,27 +54,164 @@ export type FrontConfigPublicItem = { [key: string]: unknown } +/** frontConfig.getInfo / saveInfo 响应:当前仓库品牌配置(8 字段,不含证书/私钥/证书路径/同步等内部字段) */ +export type FrontConfigInfo = { + warehouse_id?: number + /** 仓库自持域名(未设置为空字符串) */ + domain?: string + /** 站点标题(未配置为空字符串) */ + title?: string + logo_url?: string + login_bg_url?: string + favicon_url?: string + /** 主题配置对象(未配置为 null) */ + theme?: Record | string | null + updated_at?: string | null + [key: string]: unknown +} + +/** frontConfig.saveInfo 入参:仅受理品牌字段,其余(domain/证书相关)由后端白名单静默忽略 */ +export type FrontConfigSaveInfoParams = { + /** 站点标题(≤100,空值清空) */ + title?: string + /** Logo 地址(≤255,空值清空) */ + logo_url?: string + /** 站点 favicon 地址(≤255,空值清空) */ + favicon_url?: string + /** 登录页背景图地址(≤255,空值清空) */ + login_bg_url?: string + /** 主题配置(合法 JSON 对象或 JSON 字符串;空值清空) */ + theme?: Record | string | null +} + +/** frontConfig.getDomain / setDomain 响应:域名与 DNS TXT 归属验证状态(9 字段) */ +export type FrontConfigDomain = { + warehouse_id?: number + domain?: string + /** 0 未验证 / 1 已验证 / 2 验证失败 */ + domain_status?: number + /** 待添加的 TXT 记录主机名(如 wmsv-xxxxxxxxxx.);domain_status=1 时返回空字符串 */ + verify_host?: string + /** 待添加的 TXT 记录值(32 位 hex);domain_status=1 时返回空字符串 */ + verify_value?: string + /** CNAME 目标(前端部署需解析到该地址,由后端配置下发) */ + cname?: string + /** 验证通过时间(未验证为 null) */ + verified_at?: string | null + /** 校验尝试次数 */ + attempts?: number + /** 最近一次校验失败原因(脱敏截断;未失败为空字符串) */ + last_error?: string + [key: string]: unknown +} + +/** frontConfig.checkDomain 响应:getDomain 的 9 字段 + 本次校验结果 */ +export type FrontConfigCheckDomainResult = FrontConfigDomain & { + /** 本次校验是否通过 */ + verified?: boolean + /** 本次解析到的 TXT 值(最多 5 条,排障用) */ + resolved_values?: string[] +} + +/** frontConfig.getCert / saveCert 响应:证书与同步元信息(13 字段,不含 cert_path/key_path) */ +export type FrontConfigCert = { + warehouse_id?: number + domain?: string + /** 证书 PEM 原文(未配置为空字符串;仅仓库主体 settings 页回显,公共接口 getByDomain 不返回) */ + cert_pem?: string + /** 私钥 PEM 原文(读 cert_key 列;仅仓库主体 settings 页回显,禁止外泄或写入日志) */ + key_pem?: string + /** 证书到期时间(按证书 validTo 权威写入;未上传为 null) */ + cert_expire_at?: string | null + sync_status?: number + sync_attempts?: number + last_sync_error?: string + last_synced_at?: string | null + updated_at?: string | null + /** 是否允许上传证书:仅 domain 非空且 domain_status=1(已验证)时为 true */ + can_set_cert?: boolean + /** 不可上传原因(无域名「请先设置域名」/ 未验证「域名待验证」/ 失败「域名验证失败」) */ + can_set_cert_reason?: string + /** 域名验证状态(0 未验证 / 1 已验证 / 2 验证失败) */ + domain_status?: number + [key: string]: unknown +} + +/** frontConfig.saveCert 入参:域名不再作为入参(一律取库内已设置并验证通过的 domain) */ +export type FrontConfigSaveCertParams = { + /** 证书 PEM 文本(必填 ≤65536,须可解析 X.509、未过期且 SAN/CN 覆盖库内 domain) */ + pem: string + /** 私钥 PEM 文本(必填 ≤65536,须与 pem 成对,SPKI 公钥指纹比对) */ + key: string +} + /** * 按域名拉取仓库前端公开配置(公共接口:免登录、免鉴权、免权限)。 - * Redis 缓存 front:config:domain:{domain},命中 TTL 600s;未登记域名写空缓存 60s 防穿透并返回 404。 + * 仅放行已验证域名(查库条件 domain + domain_status=1):未验证/验证失败的域名一律按未配置返回 404「域名未配置」。 + * 未登记/未验证域名属预期分支,**静默失败**(silentError,不弹全局错误提示),由调用方回退默认品牌。 + * Redis 缓存 front:config:domain:{domain},命中 TTL 600s;未登记域名写空缓存 60s 防穿透。 */ export function frontConfigGetByDomain(data: { /** 待查询域名(必填,≤100 字符) */ domain: string }): Promise { - return request({ - url: '/system', - method: 'post', - params: { - method: 'frontConfig.getByDomain', - v, - timestamp: new Date().getTime() - }, - data, - isSystemApi: true - } as any) + return postFrontConfig('frontConfig.getByDomain', data, { silentError: true }) +} + +/** 查询当前仓库前端独立部署品牌配置(settings 页回显;需登录、仅仓库主体可调用;未配置返回默认空值,不 404) */ +export function frontConfigGetInfo(): Promise { + return postFrontConfig('frontConfig.getInfo') +} + +/** 保存当前仓库品牌配置(upsert 部分更新;仅受理 title/logo_url/favicon_url/login_bg_url/theme;保存即重置同步状态并清公共缓存) */ +export function frontConfigSaveInfo( + data: FrontConfigSaveInfoParams = {} +): Promise { + return postFrontConfig('frontConfig.saveInfo', data) +} + +/** 查询当前仓库域名与 DNS TXT 验证状态(settings 页回显;未设置过返回默认空值,不 404) */ +export function frontConfigGetDomain(): Promise { + return postFrontConfig('frontConfig.getDomain') +} + +/** + * 设置或变更当前仓库域名并发起 DNS TXT 归属验证(生成 verify_host/verify_value,domain_status 置 0)。 + * 注意:域名变更会同时清空既有证书并重置同步状态,需重新上传证书;域名全局唯一(被占用返回 409)。 + */ +export function frontConfigSetDomain(data: { + /** 自持域名(必填 ≤100,统一转小写存储,全局唯一) */ + domain: string +}): Promise { + return postFrontConfig('frontConfig.setDomain', data) +} + +/** 主动校验域名 DNS TXT 归属记录并回写库(成功→domain_status=1 并清理该域名公共缓存;失败→domain_status=2) */ +export function frontConfigCheckDomain(): Promise< + FrontConfigCheckDomainResult & { code?: number; message?: string } +> { + return postFrontConfig('frontConfig.checkDomain') +} + +/** 查询当前仓库证书配置(settings 页回显;含 cert_pem/key_pem 原文与 can_set_cert/can_set_cert_reason/domain_status) */ +export function frontConfigGetCert(): Promise { + return postFrontConfig('frontConfig.getCert') +} + +/** 上传当前仓库证书(域名取库内已验证 domain,不再传参;无域名/未验证返回 400,证书不合法统一 400「证书不合法」) */ +export function frontConfigSaveCert( + data: FrontConfigSaveCertParams +): Promise { + return postFrontConfig('frontConfig.saveCert', data) } export const frontConfig = { - getByDomain: frontConfigGetByDomain + getByDomain: frontConfigGetByDomain, + getInfo: frontConfigGetInfo, + saveInfo: frontConfigSaveInfo, + getDomain: frontConfigGetDomain, + setDomain: frontConfigSetDomain, + checkDomain: frontConfigCheckDomain, + getCert: frontConfigGetCert, + saveCert: frontConfigSaveCert } diff --git a/src/api/setting.warehouse/settingwarehouse.ts b/src/api/setting.warehouse/settingwarehouse.ts index 27a5b258..7e741618 100644 --- a/src/api/setting.warehouse/settingwarehouse.ts +++ b/src/api/setting.warehouse/settingwarehouse.ts @@ -597,108 +597,6 @@ export function settingWarehouseSaveSettings( } as any) } -/** 前端独立部署配置记录(getFrontConfig / saveFrontConfig / saveFrontCert 响应,一仓一行,共 15 字段) - * 证书内容已改为直接入库:响应返回 cert_pem/key_pem(PEM 原文)供 settings 页回显, - * 不再返回 cert_path/key_path(路径字段仅由后端定时任务部署后回填,不出现在响应中)。 */ -export type SettingWarehouseFrontConfig = { - warehouse_id?: number - domain?: string - title?: string - logo_url?: string - favicon_url?: string - login_bg_url?: string - theme?: Record | string | null - /** 证书 PEM 原文(读 cert_pem 列;未配置为空字符串;仅 settings 页回显,公共接口 frontConfig.getByDomain 不返回) */ - cert_pem?: string - /** 私钥 PEM 原文(读 cert_key 列;未配置为空字符串;仅 settings 页回显,公共接口 frontConfig.getByDomain 不返回) */ - key_pem?: string - /** 证书到期时间(saveFrontCert 上传后按证书 validTo 权威写入;未上传为 null) */ - cert_expire_at?: string | null - sync_status?: number - sync_attempts?: number - last_sync_error?: string - last_synced_at?: string | null - updated_at?: string | null - [key: string]: unknown -} - -export type SettingWarehouseSaveFrontConfigParams = { - /** 站点标题(≤100,空值清空) */ - title?: string - /** Logo 地址(≤255,空值清空) */ - logo_url?: string - /** 站点 favicon 地址(≤255,空值清空) */ - favicon_url?: string - /** 登录页背景图地址(≤255,空值清空) */ - login_bg_url?: string - /** 主题配置(合法 JSON 对象或 JSON 字符串;空值清空) */ - theme?: Record | string | null -} - -export type SettingWarehouseSaveFrontCertParams = { - /** 仓库自持域名(必填 ≤100,全局唯一) */ - domain: string - /** 证书 PEM 文本(必填 ≤65536,须可解析 X.509、未过期且 SAN/CN 覆盖 domain) */ - pem: string - /** 私钥 PEM 文本(必填 ≤65536,须与 pem 成对,SPKI 公钥指纹比对) */ - key: string -} - -/** 查询当前仓库前端独立部署配置(settings 页回显;无记录返回默认空配置) */ -export function settingWarehouseGetFrontConfig(): Promise< - { code?: number; message?: string; data?: SettingWarehouseFrontConfig } & Record -> { - return request({ - url: '/system', - method: 'post', - params: { - method: 'setting.warehouse.getFrontConfig', - v, - timestamp: new Date().getTime() - }, - data: {}, - isSystemApi: true - } as any) -} - -/** 保存当前仓库前端独立部署品牌配置(仅受理 title/logo/favicon/login_bg/theme,空值清空;domain/证书字段不受理) */ -export function settingWarehouseSaveFrontConfig( - data: SettingWarehouseSaveFrontConfigParams = {} -): Promise< - { code?: number; message?: string; data?: SettingWarehouseFrontConfig } & Record -> { - return request({ - url: '/system', - method: 'post', - params: { - method: 'setting.warehouse.saveFrontConfig', - v, - timestamp: new Date().getTime() - }, - data, - isSystemApi: true - } as any) -} - -/** 上传当前仓库前端独立部署证书(domain + pem/key 成对必填;通过后回填 cert_expire_at) */ -export function settingWarehouseSaveFrontCert( - data: SettingWarehouseSaveFrontCertParams -): Promise< - { code?: number; message?: string; data?: SettingWarehouseFrontConfig } & Record -> { - return request({ - url: '/system', - method: 'post', - params: { - method: 'setting.warehouse.saveFrontCert', - v, - timestamp: new Date().getTime() - }, - data, - isSystemApi: true - } as any) -} - /** 当前仓库已授权的微信小程序信息(setting.warehouse.getweChatApp 响应;字段名以后端为准,前端做多形态兼容) */ export type SettingWarehouseWeChatApp = { warehouse_id?: number @@ -744,8 +642,5 @@ export const settingWarehouse = { getSettings: settingWarehouseGetSettings, getFieldMeta: settingWarehouseGetFieldMeta, saveSettings: settingWarehouseSaveSettings, - getFrontConfig: settingWarehouseGetFrontConfig, - saveFrontConfig: settingWarehouseSaveFrontConfig, - saveFrontCert: settingWarehouseSaveFrontCert, getWeChatApp: settingWarehouseGetWeChatApp } diff --git a/src/stores/modules/frontBrand.ts b/src/stores/modules/frontBrand.ts index d439d9f8..f1f580c6 100644 --- a/src/stores/modules/frontBrand.ts +++ b/src/stores/modules/frontBrand.ts @@ -111,9 +111,24 @@ export const useFrontBrandStore = defineStore('frontBrand', () => { /** favicon 图标(空串→调用方用默认) */ const faviconUrl = computed(() => brand.value?.favicon_url?.trim() || '') - /** 按当前访问域名拉取品牌并应用全局(favicon / 登录页标题 / theme CSS 变量) */ - async function loadBrandByDomain(domain?: string): Promise { - if (loaded.value) return + /** 进行中的加载 Promise:并发调用(main.ts 入口 / 登录页)共享同一次请求,避免重复请求与重复提示 */ + let brandLoading: Promise | null = null + + /** + * 按当前访问域名拉取品牌并应用全局(favicon / 登录页标题 / theme CSS 变量)。 + * 幂等:已加载直接返回;加载中则复用同一次请求。 + */ + function loadBrandByDomain(domain?: string): Promise { + if (loaded.value) return Promise.resolve() + if (brandLoading) return brandLoading + brandLoading = doLoadBrandByDomain(domain).finally(() => { + brandLoading = null + }) + return brandLoading + } + + /** 实际加载逻辑(仅由 loadBrandByDomain 调用):失败/未登记域名一律静默回退默认品牌 */ + async function doLoadBrandByDomain(domain?: string): Promise { const host = normalizeFrontHost(domain ?? window.location.hostname) // 主域名豁免:不拉取、不应用 getByDomain 品牌配置,直接保持系统默认品牌(默认标题/默认 logo/无主题 CSS 变量) if (!host || FRONT_BRAND_EXEMPT_HOSTS.has(host)) { @@ -132,7 +147,9 @@ export const useFrontBrandStore = defineStore('frontBrand', () => { brand.value = valid ? (data as FrontConfigPublicItem) : null } } catch (e) { - console.error('[frontBrand] 拉取域名品牌失败,使用默认品牌', e) + // 未登记/未验证域名(404「域名未配置」)属预期分支:已由接口层静默(silentError)不弹提示, + // 这里仅开发环境记一条调试日志,随后回退系统默认品牌 + if (import.meta.env.DEV) console.debug('[frontBrand] 未取到域名品牌,使用默认品牌', e) brand.value = null } finally { loaded.value = true diff --git a/src/utils/request.ts b/src/utils/request.ts index 40d984fb..5f9808d8 100644 --- a/src/utils/request.ts +++ b/src/utils/request.ts @@ -16,6 +16,9 @@ const service = axios.create({ // 定义业务成功码 const SUCCESS_CODES = [200, 20000, 1,0] // 支持多种成功码 +/** 业务扩展请求配置:silentError=true 时拦截器不弹错误提示,由调用方自行兜底(如公共品牌按域名拉取) */ +type ServiceRequestConfig = { silentError?: boolean } + // 错误码映射 const ERROR_CODE_MAP = { // 认证相关错误 @@ -120,6 +123,9 @@ service.interceptors.response.use( } } + // 静默请求:业务码/网络失败不弹全局提示(调用方自行回退默认值) + const silentError = Boolean((response.config as unknown as ServiceRequestConfig | undefined)?.silentError) + // 检查业务状态码 if (!SUCCESS_CODES.includes(res.code)) { // 优先使用后端返回的 message,如果没有则从映射表获取,最后使用默认值 @@ -133,11 +139,11 @@ service.interceptors.response.use( // 权限不足处理 if ([403, 40005, 40006].includes(res.code)) { - ElMessage.warning('没有操作权限') + if (!silentError) ElMessage.warning('没有操作权限') return Promise.reject(new Error(errorMessage)) } - ElMessage.error(errorMessage) + if (!silentError) ElMessage.error(errorMessage) return Promise.reject(new Error(errorMessage)) } else { // 请求成功,返回数据 @@ -187,7 +193,9 @@ service.interceptors.response.use( message = error.message } - ElMessage.error(message) + if ((error.config as unknown as ServiceRequestConfig | undefined)?.silentError !== true) { + ElMessage.error(message) + } return Promise.reject(error) } ) diff --git a/src/views/system/setting/basicManagement/newview/pages/FrontConfigForm.vue b/src/views/system/setting/basicManagement/newview/pages/FrontConfigForm.vue index 890751cc..954f5ddc 100644 --- a/src/views/system/setting/basicManagement/newview/pages/FrontConfigForm.vue +++ b/src/views/system/setting/basicManagement/newview/pages/FrontConfigForm.vue @@ -1,10 +1,11 @@ @@ -13,178 +14,352 @@
前端独立部署 - 按仓库自持域名部署并品牌化前端(站点标题 / Logo / favicon / 登录页 / 主题 / HTTPS 证书) + 按仓库自持域名部署并品牌化前端(域名设置 / HTTPS 证书 / 品牌配置)
刷新
- - + +
+ + - -
-
-

品牌配置

-

站点标题、Logo、favicon、登录页背景图与主题变量;图片可直接上传自动填入 URL,也可手填;留空即清空

-
- - - - - -
- - - 上传图片 - - - - -
-
- -
- - - 上传图片 - - - - -
-
- -
- - - 上传图片 - - - - -
-
- -
-
- - - 删除 + +
+ + - -
-
-

自持域名 & 证书

-

域名全局唯一;证书与私钥已回显当前配置,可修改后重新上传

-
- - - - - - -
- 已配置 - 未配置 - 已回显当前仓库证书,可直接修改;证书到期:{{ formatFrontDateTime(frontMeta.cert_expire_at) }} - 复制 -
-
- - -
- 已配置 - 未配置 - 已回显当前仓库私钥,可直接修改;私钥敏感,请勿外泄 - 复制 -
-
-
- -
+ + + + + +
+