feat(系统设置): 前端独立部署改接 frontConfig.* 8 接口,页面改左菜单布局

API:src/api/frontconfig/frontConfig.ts 新增 getInfo/saveInfo/getDomain/setDomain/checkDomain/getCert/saveCert 及类型、FRONT_DOMAIN_STATUS 常量;移除被取代的 setting.warehouse.getFrontConfig/saveFrontConfig/saveFrontCert 封装与类型。

页面:FrontConfigForm.vue 改为左菜单(域名设置 / HTTPS 证书 / 品牌配置)+ 右内容布局;域名段支持保存域名、TXT 主机名与记录值复制、校验 DNS、刷新状态;证书段 saveCert 不再提交 domain,按 getCert 的 can_set_cert/can_set_cert_reason 置灰上传并展示同步状态;品牌段展示 updated_at。

请求层:request.ts 新增请求级 silentError(静默失败不弹全局提示,token 失效逻辑不受影响);frontConfig.getByDomain 静默失败(未登记/未验证域名 404「域名未配置」属预期);frontBrand 失败改为仅开发环境 debug 日志,并新增并发去重。

文档:前端独立部署操作与部署说明、接口落实任务清单同步新口径(8 接口矩阵与 2026-09-24 流程更正章节)。
This commit is contained in:
liufumingren 2026-09-25 03:13:22 +08:00
parent 2fe9a2c844
commit b20be60f45
7 changed files with 1095 additions and 378 deletions

View File

@ -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 变量容器(顶层标量键→`--<key>`,文案类不再放主题)。网页名称/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 变量容器(顶层标量键→`--<key>`)。网页名称/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` 刷新,同步状态重置为待同步。

View File

@ -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>.<domain>`)与校验值 `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(对象/数组/数字/布尔);应用时顶层标量键写入 `--<key>`
- 网页名称/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 指向」把 `<自持域名> -> <cname>`,并配置 HTTPS(证书由后端部署链路提供,前端不需持证)。
2. 浏览器访问 `https://<自持域名>`:前端入口自动按 `location.hostname` 调 `frontConfig.getByDomain` 应用品牌。
- 生效项:网页名称=`title`(登录页标题与 document.title)、主页面/登录页 Logo=`logo_url`、登录背景、favicon;其余 `theme` 键→CSS 变量(`--<key>`)。登录页文字无独立配置字段,用默认标语“现代化仓储管理系统 - 助力企业高效运营”。
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` |

View File

@ -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<T = Record<string, unknown>>(
method: string,
data: Record<string, unknown> = {},
options: FrontConfigRequestOptions = {}
): Promise<T & { code?: number; message?: string }> {
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, unknown> | 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, unknown> | 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>);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<FrontConfigPublicItem & { code?: number; message?: string }> {
return request({
url: '/system',
method: 'post',
params: {
method: 'frontConfig.getByDomain',
v,
timestamp: new Date().getTime()
},
data,
isSystemApi: true
} as any)
return postFrontConfig<FrontConfigPublicItem>('frontConfig.getByDomain', data, { silentError: true })
}
/** 查询当前仓库前端独立部署品牌配置(settings 页回显;需登录、仅仓库主体可调用;未配置返回默认空值,不 404) */
export function frontConfigGetInfo(): Promise<FrontConfigInfo & { code?: number; message?: string }> {
return postFrontConfig<FrontConfigInfo>('frontConfig.getInfo')
}
/** 保存当前仓库品牌配置(upsert 部分更新;仅受理 title/logo_url/favicon_url/login_bg_url/theme;保存即重置同步状态并清公共缓存) */
export function frontConfigSaveInfo(
data: FrontConfigSaveInfoParams = {}
): Promise<FrontConfigInfo & { code?: number; message?: string }> {
return postFrontConfig<FrontConfigInfo>('frontConfig.saveInfo', data)
}
/** 查询当前仓库域名与 DNS TXT 验证状态(settings 页回显;未设置过返回默认空值,不 404) */
export function frontConfigGetDomain(): Promise<FrontConfigDomain & { code?: number; message?: string }> {
return postFrontConfig<FrontConfigDomain>('frontConfig.getDomain')
}
/**
* 设置或变更当前仓库域名并发起 DNS TXT 归属验证(生成 verify_host/verify_value,domain_status 置 0)。
* 注意:域名变更会同时清空既有证书并重置同步状态,需重新上传证书;域名全局唯一(被占用返回 409)。
*/
export function frontConfigSetDomain(data: {
/** 自持域名(必填 ≤100,统一转小写存储,全局唯一) */
domain: string
}): Promise<FrontConfigDomain & { code?: number; message?: string }> {
return postFrontConfig<FrontConfigDomain>('frontConfig.setDomain', data)
}
/** 主动校验域名 DNS TXT 归属记录并回写库(成功→domain_status=1 并清理该域名公共缓存;失败→domain_status=2) */
export function frontConfigCheckDomain(): Promise<
FrontConfigCheckDomainResult & { code?: number; message?: string }
> {
return postFrontConfig<FrontConfigCheckDomainResult>('frontConfig.checkDomain')
}
/** 查询当前仓库证书配置(settings 页回显;含 cert_pem/key_pem 原文与 can_set_cert/can_set_cert_reason/domain_status) */
export function frontConfigGetCert(): Promise<FrontConfigCert & { code?: number; message?: string }> {
return postFrontConfig<FrontConfigCert>('frontConfig.getCert')
}
/** 上传当前仓库证书(域名取库内已验证 domain,不再传参;无域名/未验证返回 400,证书不合法统一 400「证书不合法」) */
export function frontConfigSaveCert(
data: FrontConfigSaveCertParams
): Promise<FrontConfigCert & { code?: number; message?: string }> {
return postFrontConfig<FrontConfigCert>('frontConfig.saveCert', data)
}
export const frontConfig = {
getByDomain: frontConfigGetByDomain
getByDomain: frontConfigGetByDomain,
getInfo: frontConfigGetInfo,
saveInfo: frontConfigSaveInfo,
getDomain: frontConfigGetDomain,
setDomain: frontConfigSetDomain,
checkDomain: frontConfigCheckDomain,
getCert: frontConfigGetCert,
saveCert: frontConfigSaveCert
}

View File

@ -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, unknown> | 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, unknown> | 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<string, unknown>
> {
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<string, unknown>
> {
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<string, unknown>
> {
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
}

View File

@ -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<void> {
if (loaded.value) return
/** 进行中的加载 Promise:并发调用(main.ts 入口 / 登录页)共享同一次请求,避免重复请求与重复提示 */
let brandLoading: Promise<void> | null = null
/**
* 按当前访问域名拉取品牌并应用全局(favicon / 登录页标题 / theme CSS 变量)。
* 幂等:已加载直接返回;加载中则复用同一次请求。
*/
function loadBrandByDomain(domain?: string): Promise<void> {
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<void> {
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

View File

@ -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)
}
)