小氢云商城自定义路由系统完整使用教程
适用版本：小氢云商城系统（Go 后端 + 管理后台 web-antd）
阅读对象：站长、运营、二次开发者
最后更新：2026-05-29
一、这套「路由系统」到底是什么？
在小氢云商城里，自定义路由映射系统（后台菜单：路由映射管理）是一套无需改代码、无需重新打包前端就能上线新页面的能力。
你可以把它理解成：
用户访问 URL → 系统查映射表 → 读取 doc 目录文件 / 装修配置 → 渲染页面
典型用途包括：
- 落地页、活动页、品牌介绍页
- 独立 API 文档页、帮助中心
- 绑定独立域名做品牌站首页
- 绑定「网站装修项目」做可视化拖拽页面
- 付费内容页（会员专享资料、教程等）
和 Vue Router 的区别： PC/PE 前端里的 Vue Router 管的是商城 SPA 内部跳转；本文讲的是服务端级别的自定义路由，直接由 Go 中间件拦截 HTTP 请求并返回内容，SEO 友好、可独立访问。
二、整体架构（建议先建立心智模型）
flowchart TD
A[用户请求 /promo/sale] --> B{是否为 /api/* 或后台路径?}
B -->|是| C[放行给 API / 静态资源]
B -->|否| D[CustomRouteMiddleware 中间件]
D --> E{Redis 缓存命中?}
E -->|否| F[查 MySQL sky_route_mapping]
F --> G[写入 Redis 永久缓存]
E -->|是| H[读取映射配置]
G --> H
H --> I{数据源类型}
I -->|file| J[读取 doc 下 HTML/JS/CSS/PHP 等]
I -->|decoration| K[读取装修项目 JSON 配置]
J --> L{访问控制}
K --> L
L -->|需登录/付费| M[拦截并展示登录/付费页]
L -->|通过| N[占位符替换 + 静态路径重写 + 返回内容]
核心存储
| 层级 | 作用 |
|---|---|
MySQL sky_route_mapping |
持久化所有路由映射配置 |
| Redis | 永久缓存映射关系，加速访问 |
| doc 目录 | 与后端可执行文件同级的文件仓库，存放 HTML/静态资源/PHP 等 |
缓存键规则
键名 = route_mapping: + md5(全局配置 zhuzhan + 路由路径)
值 = 文件相对路径，如 promo/sale.html
创建、更新、删除映射时系统会自动维护 Redis；也可在后台点击 「刷新缓存」 批量同步。
三、功能清单（一张表看懂能做什么）
| 功能 | 说明 |
|---|---|
| 路由映射 | 如 /about → pages/about.html |
| 域名映射 | 如 brand.example.com 根路径 → 指定页面（需 DNS 解析到服务器） |
| 数据源：文件 | HTML / JSON / CSS / JS / PHP / SVG / MD 等文本格式 |
| 数据源：装修项目 | 绑定后台「网站装修」拖拽项目，前端 SPA 动态渲染 |
| 设备类型 | pc 电脑端 / pe 手机端 / def 通用 |
| 强制登录 | 未登录用户看到内置登录页（需开启用户系统） |
| 付费访问 | 设置价格，未购买用户看到付费引导页 |
| 元数据 Metadata | JSON 表单配置，写入 Cookie，页面内可用 [元数据] 占位符读取 |
| 占位符变量 | 自动替换网站标题、备案号、Logo、SEO 等系统配置 |
| 静态资源自动映射 | 页面同级目录下的 assets/、static/、css/ 等自动可访问 |
| 导入/导出 | 批量迁移路由配置 |
| 在线文件管理 | 后台可直接上传、编辑 doc 目录文件 |
| 访问统计 | 今日/累计访问量（Redis 统计） |
| PHP 动态页 | 配置 PHP 解释器后可执行 .php 文件 |
四、快速上手：5 分钟发布第一个单页
步骤 1：进入管理后台
路径：系统管理 → 路由映射管理（或全局搜索「路由映射」）。
步骤 2：准备页面文件
方式 A — 后台在线创建（推荐新手）
- 点击 「浏览文件」
- 在
doc目录下新建文件夹，如pages - 新建文件
welcome.html，粘贴下方【完整单页示例】代码 - 保存
方式 B — 服务器手动上传
# 在后端程序同级目录
mkdir -p doc/pages
cp welcome.html doc/pages/welcome.html
doc目录若不存在，系统会在首次浏览文件时自动创建。
步骤 3：添加路由映射
点击 「添加路由」，填写：
| 字段 | 示例值 |
|---|---|
| 映射方式 | 通过路由 |
| 路由路径 | /welcome |
| 数据源类型 | 文件 |
| 文件路径 | pages/welcome.html |
| 状态 | 启用 |
| 设备类型 | 通用 |
保存后，访问：
https://你的域名/welcome
即可看到页面。
步骤 4：验证
- 页面标题、Logo 等占位符是否被正确替换
- 打开浏览器开发者工具 → Network，确认 CSS/JS 加载 200
- 后台列表中「访问统计」是否增加
五、完整单页 HTML 示例（可直接复制使用）
将以下代码保存为 doc/pages/welcome.html，并映射路由 /welcome：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>[title] - 欢迎页</title>
<meta name="keywords" content="[seo_keywords]" />
<meta name="description" content="[seo_description]" />
<link rel="icon" href="[favicon]" />
<style>
* { margin: 0; padding: 0; box-sizing: border-box; }
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
min-height: 100vh;
display: flex;
align-items: center;
justify-content: center;
color: #fff;
}
.card {
background: rgba(255,255,255,0.95);
color: #333;
border-radius: 16px;
padding: 48px 40px;
max-width: 520px;
width: 90%;
box-shadow: 0 20px 60px rgba(0,0,0,0.3);
text-align: center;
}
.logo { width: 64px; height: 64px; border-radius: 12px; margin-bottom: 20px; }
h1 { font-size: 28px; margin-bottom: 12px; }
p { color: #666; line-height: 1.8; margin-bottom: 24px; }
.meta { font-size: 13px; color: #999; margin-bottom: 32px; }
.btn {
display: inline-block;
padding: 12px 32px;
background: #667eea;
color: #fff;
text-decoration: none;
border-radius: 8px;
font-weight: 600;
transition: transform 0.2s, box-shadow 0.2s;
}
.btn:hover { transform: translateY(-2px); box-shadow: 0 8px 20px rgba(102,126,234,0.4); }
footer { margin-top: 32px; font-size: 12px; color: #bbb; }
</style>
</head>
<body>
<div class="card">
<img class="logo" src="[logo]" alt="Logo" onerror="this.style.display='none'" />
<h1>欢迎来到 [title]</h1>
<p>这是通过<strong>自定义路由系统</strong>发布的独立单页。<br/>无需修改前端代码，后台配置即可上线。</p>
<div class="meta">
当前路由：<code>[router]</code><br/>
站点地址：<a href="[base_url]">[base_url]</a><br/>
建站时间：[site_time]
</div>
<a class="btn" href="[base_url]">进入商城首页</a>
<footer>
[RecordNumber] [PoliceRecordNumber]
</footer>
</div>
<script>
// 元数据占位符已被 Unicode 转码，可安全嵌入
var routeMeta = "[元数据]";
if (routeMeta && routeMeta !== "[元数据]") {
try {
var meta = JSON.parse(routeMeta);
console.log('路由元数据:', meta);
} catch (e) {}
}
console.log('自定义路由页面加载成功，路径:', '[router]');
</script>
</body>
</html>
这个示例演示了什么？
- 占位符自动替换：
[title]、[logo]、[base_url]等来自系统配置 - 纯 CSS 单页：无外部依赖，复制即用
- 元数据读取：若在后台配置了 Metadata，可通过
[元数据]在 JS 中使用 - 备案信息：
[RecordNumber]、[PoliceRecordNumber]自动填充
六、占位符（变量）完整列表
在 所有文本格式文件（HTML、JS、CSS、JSON、TXT、PHP 等）中，以下占位符会在访问时自动替换：
| 占位符 | 替换内容 |
|---|---|
[title] / [Title] / [网站标题] |
网站标题 |
[base_url] |
系统网址（优先 config.yaml，否则从请求构建） |
[RecordNumber] / [备案号] |
ICP 备案号 |
[PoliceRecordNumber] / [公安备案号] |
公安备案号 |
[logo] / [favicon] |
网站 Logo / 图标 |
[seo_keywords] / [SEO关键词] |
SEO 关键词 |
[seo_description] / [SEO描述] |
SEO 描述 |
[site_time] / [建站时间] |
建站时间 |
[pcurl] / [PC背景] |
PC 端背景图 URL |
[peurl] / [手机背景] |
手机端背景图 URL |
[router] / [ROUTER] |
当前访问的路由路径 |
[元数据] / [metadata] |
当前路由 Metadata JSON（Unicode 转码，可安全嵌入 script） |
注意：二进制文件（图片等）不会做占位符替换，避免损坏文件。
七、静态资源：为什么你的 CSS/JS 能自动加载？
假设你映射了 /landing → campaign/index.html，且文件结构为：
doc/
└── campaign/
├── index.html
├── assets/
│ ├── app.js
│ └── style.css
└── static/
└── banner.png
当 index.html 中引用：
<link rel="stylesheet" href="/assets/style.css" />
<script src="/assets/app.js"></script>
系统会自动重写路径为：
/landing/assets/style.css
/landing/assets/app.js
并从 doc/campaign/assets/ 目录读取文件返回。
支持的静态目录前缀
/assets/、/static/、/js/、/css/、/images/、/img/、/fonts/、/libs/、/lib/ 等。
最佳实践
- 把静态资源放在 HTML 同级或子目录，不要散落到 doc 根目录
- 打包 UniApp/H5 项目时，直接解压到
doc/某路由名/下即可 - 路径写
/assets/xxx即可，系统会自动加路由前缀
八、进阶用法
8.1 域名映射（独立品牌站）
场景：shop.example.com 是商城，brand.example.com 想展示品牌首页。
配置步骤：
- DNS 将
brand.example.comA 记录解析到服务器 IP - 后台添加映射：
- 映射方式：通过域名
- 域名：
brand.example.com - 文件路径：
brand/home.html
- 用户访问
https://brand.example.com/时渲染该页面
/api/*、/static/*等非根路径仍正常走后端，不影响接口。
8.2 绑定网站装修项目
场景：已在「网站装修」里拖拽好了 PC/ 手机页面，想挂到自定义 URL。
- 数据源类型选 「网站装修项目」
- 选择对应装修项目 ID
- 保存后，PC 端 SPA 的
DynamicRoute.vue会读取装修 JSON 并渲染组件树
装修类型不走直接 HTML 返回，而是注入到前端 SPA 的 sessionStorage，由 Vue 组件渲染。
8.3 PHP 动态页面
- 在 网站设置 → 基础设置 配置 PHP 解释器路径
- 上传
doc/api/hello.php - 映射
/api-demo→api/hello.php
系统会用 CLI 模式执行 PHP，并传递 HTTP 上下文（Method、Headers、Body 等）。
安全限制：exec、eval、shell_exec、system 等高危函数默认禁用。
8.4 强制登录 & 付费访问
| 设置 | 行为 |
|---|---|
| 强制登录 = 开启 | 未登录用户看到内置登录页 |
| 付费 + 价格 | 需先登录，再检查是否已购买该路由 |
若全局关闭了用户系统（
user_code = false），强制登录和付费功能不会生效。
8.5 元数据 Metadata（动态表单）
Metadata 是一个 JSON 数组，描述表单组件（input、select、radio 等）。
后台操作：添加路由 → 元数据 → 「可视化配置」。
页面中使用：
<script>
var fields = JSON.parse("[元数据]");
// fields 是表单组件数组，可动态渲染表单
</script>
系统还会将 Metadata 写入 Cookie（键名 route_meta_ + md5(域名 + 路由)），有效期 30 天，供跨页面读取。
8.6 设备类型分流
同一 URL，可为 PC 和手机配置不同映射：
/promo+ 设备类型pc→promo/pc.html/promo+ 设备类型pe→promo/mobile.html
系统通过 User-Agent 自动识别设备；调试时可加 ?force_device=pc 或 ?force_device=pe 强制指定。
九、后台文件管理 API（开发者参考）
除可视化「浏览文件」外，还提供完整文件操作接口（均需管理员 Token）：
| 接口 | 说明 |
|---|---|
GET /api/admin/route-mapping/doc-files?path=xxx |
列出 doc 目录 |
POST /api/admin/route-mapping/upload |
上传文件 |
POST /api/admin/route-mapping/create-file |
创建文件 |
POST /api/admin/route-mapping/update-file |
更新文件内容 |
GET /api/admin/route-mapping/read-file |
读取文件 |
POST /api/admin/route-mapping/unzip-file |
解压 zip（适合整站 H5 包） |
创建映射示例（curl）
TOKEN="你的管理员Token"
curl -X POST http://127.0.0.1:8080/api/admin/route-mapping/create \
-H "Content-Type: application/json" \
-H "admin-token: Bearer $TOKEN" \
-d '{
"route": "/welcome",
"route_type": "route",
"file_path": "pages/welcome.html",
"source_type": "file",
"title": "欢迎页",
"status": 1,
"device_type": "def",
"force_login": 0,
"is_paid": 0
}'
十、导入 / 导出（批量迁移）
导出：勾选路由 → 点击「导出」→ 得到 JSON 配置文件。
导入规则：
- 按「路由路径 + 设备类型」判重
- 已存在则更新，不存在则新建
- 支持 JSON 文件或远程 URL 导入
适合从测试环境迁移到生产环境，或备份路由配置。
十一、请求处理优先级（排查问题时必看）
中间件 CustomRouteMiddleware 的执行顺序：
- 跳过
/api/*、管理后台路径、砍价分享页 - 静态资源路径 → 尝试从 doc 目录匹配
- 根路径
/→ 优先尝试域名映射 - 按路由路径精确匹配（
/promo与/promo/等价） - 父路由静态资源 → 如
/landing/css/style.css找/landing映射 - 未命中 → 交给 SPA 的 NoRoute 处理（404 或装修兜底）
访问控制优先级
- 全局强制登录中间件
- 路由级强制登录
- 路由级付费访问
十二、常见问题 FAQ
Q1：访问自定义路由返回 404？
检查清单：
- 路由映射状态是否为 启用
- 文件路径是否正确（相对于 doc，不含
doc/前缀） - doc 目录下文件是否真实存在
- 设备类型是否匹配（PC 页设置了
pe-only 时，电脑访问会 404） - 点击「刷新缓存」后重试
Q2：改了 HTML 但页面没变化？
- 文件内容不走 Redis 缓存，改完应即时生效
- 若仍不变，检查浏览器缓存（Ctrl+F5 / Cmd+Shift+R）
- 若改了映射配置本身，需刷新路由缓存
Q3：CSS/JS 404？
- 确认静态资源在 HTML 同级目录的
assets/或static/下 - HTML 里用
/assets/xxx相对根路径写法，系统会自动加路由前缀 - 不要手动写完整路由前缀（除非你知道自己在做什么）
Q4：强制登录设置了但不生效？
- 检查 用户系统 是否开启（网站设置 → 用户系统）
- 用户系统关闭时，后台会显示「无效」标签
Q5：能和商城 Vue 路由冲突吗？
- 自定义路由优先级低于
/api/*和后台路径 - 与 PC SPA 路由：若后端中间件已命中并返回内容，则不会进入 Vue；未命中则走 SPA 的
DynamicRoute.vue兜底 - 建议：自定义路由使用
/promo/、/landing/等独立前缀，避免与商城内置路径冲突
Q6：doc 目录在哪？
与后端可执行程序同级，例如：
/opt/xqy/
├── server # 后端程序
├── doc/ # ← 这里
│ └── pages/
│ └── welcome.html
└── static/
十三、推荐目录结构
doc/
├── pages/ # 通用单页
│ ├── about.html
│ └── contact.html
├── campaign/ # 活动页（含静态资源子目录）
│ ├── index.html
│ └── assets/
├── docs/ # 文档
│ └── api.html
└── brand/ # 域名映射专用
└── home.html
十四、安全注意事项
- 禁止路径遍历：文件路径不允许
..，无法访问 doc 外文件 - 管理接口鉴权：所有配置/文件操作需管理员 Token
- PHP 高危函数禁用：生产环境务必配置解释器并审查 PHP 代码
- 付费页：涉及资金，修改价格前确认已购用户权益策略
- 唯一路由：同一路由 + 设备类型不可重复，防止映射冲突
十五、总结
| 你想做什么 | 怎么做 |
|---|---|
| 快速上一个介绍页 | doc 放 HTML → 后台添加路由映射 → 访问 URL |
| 上线 H5 活动整包 | 解压到 doc/xxx/ → 映射 /xxx → 静态资源自动可用 |
| 独立域名首页 | 域名映射 + DNS 解析 |
| 可视化拖拽页 | 数据源选「装修项目」 |
| 会员专享内容 | 开启付费 + 设价格 |
| 动态接口页 | 上传 PHP + 配置解释器 |
自定义路由系统是小氢云商城最灵活的页面发布通道——运营同学可以独立上线页面，开发同学可以对接 PHP/H5 整包，无需每次改代码发版。
附录：数据库表字段速查
sky_route_mapping 主要字段：
| 字段 | 含义 |
|---|---|
| route | 路由路径或域名 |
| route_type | route 或 domain |
| file_path | doc 下相对路径 |
| source_type | file 或 decoration |
| decoration_id | 装修项目 ID |
| force_login | 是否强制登录 |
| device_type | pc / pe / def |
| is_paid / price | 付费设置 |
| metadata | 元数据 JSON |
| status | 1 启用 / 0 禁用 |
本文由小氢云商城技术团队整理，基于系统源码与后台「路由映射管理」模块编写。如有疑问，欢迎在评论区留言。