幻影二级域名分发系统 V6 门户模板开发文档

文档版本：6.0.5
适用范围：系统内置 Vue 门户、可安装的 portal 静态模板、门户首页、文章详情页和开放 API 文档页

1. 门户模板运行方式

系统支持内置模板和外置模板，两者对访客使用相同的公开地址：

外置模板文件虽然存放在：

但这个地址只是系统内部的静态资源目录，不是门户公开地址。模板代码、导航菜单、文章链接和对外文档中都不要展示或跳转到该目录。

1.1 模板选择流程

门户入口通过以下公开接口获取当前模板：

内置模板返回示例：

外置模板返回示例：

字段说明：

1.2 外置模板加载机制

当前系统按以下顺序加载外置模板：

1. 后端读取 portal.active_template 配置。
2. 检查 plugins/portal/{plugin_code}/index.html 是否存在。
3. 访问 /、/portal/api-docs 或 /portal/article/{id} 时，后端优先返回当前模板的 index.html。
4. 后端把入口 HTML 中的 ./assets/... 和 assets/... 自动映射到 /portal-templates/{plugin_code}/assets/...。
5. 浏览器地址保持公开页面地址，不再跳转到模板存储目录。
6. 如果部署环境由 Nginx 直接提供主前端，主前端会在当前页面内兼容加载外置模板，浏览器顶层地址仍保持不变。

因此模板绝对不能执行下面的代码：

2. 模板目录和清单

最小模板结构：

manifest.json 示例：

清单字段说明：

压缩包根目录必须直接出现 manifest.json 和 index.html，不要在 ZIP 最外层再套一层同名文件夹。

3. 通用接口约定

门户只调用公开接口，统一使用相对地址：

禁止写死开发地址或线上域名：

所有接口使用统一响应结构：

判断成功时兼容 code === 0 和 code === 200：

门户不得读取或保存用户 Token、管理员 Token、API 秘钥、数据库账号和插件私密配置。

4. 全站公共配置

三个门户页面都必须请求：

完整返回示例：

字段与页面位置：

建议封装：

5. 首页 /

5.1 首页数据对应关系

功能介绍、产品优势、FAQ 和开发流程属于模板展示内容，可以由模板提供；网站名称、Logo、文章、公告、版权和备案信息不能写死。

5.2 公告接口

返回列表字段：

接口只返回已发布且处于有效时间范围内的公告。模板不需要再次判断后台状态，但应按 display_mode、allow_close 和重复展示规则处理。

5.3 文章分类接口

返回示例：

分类选择器必须以 id 作为筛选值，以 name 作为显示文字。模板可以在前端额外增加“全部分类”，但不要把“全部分类”提交成真实分类编号。

5.4 文章列表接口

全部文章：

按分类筛选：

文章列表字段：

列表接口不返回正文 content。点击文章后必须再调用详情接口，不能把 summary 当作正文。

文章点击支持两种方式：

如果使用弹窗，必须提供关闭按钮、正文滚动区域、加载状态和请求失败提示。

5.5 首页固定链接

外置模板建议使用普通链接并指定顶层窗口：

这样在后端直出模式和前端兼容承载模式下都能正确离开模板页面。

6. 文章详情页 /portal/article/{id}

{id} 是文章列表返回的 id，不是分类编号。

请求接口：

详情字段：

浏览器标题格式：

Vue Router 获取编号示例：

原生 JS 获取编号示例：

正文可以使用 innerHTML 或 Vue v-html 渲染，但模板自身不得拼接脚本，也不得执行正文中的任意 JavaScript。正文区域至少需要适配标题、段落、列表、引用、代码块、表格和响应式图片。

错误状态：

7. 开放 API 文档页 /portal/api-docs

API 文档页使用 /site/home 的以下字段：

浏览器标题格式：

接口基础地址必须从当前访问站点生成：

页面应展示以下开放接口：

认证请求头示例：

文档示例只允许使用 phk_your_api_key，不能出现真实秘钥。API 文档页面只负责展示说明，不应自动请求需要秘钥的 /open/* 接口。

8. 路由兼容规范

外置模板必须能够识别三种公开路径：

为兼容统一后端直出和旧部署方式，推荐在模板启动前规范化路径：

Vue 3 路由示例：

不要使用模板目录作为 Router base，也不要把下面的地址注册成公开路由：

模板内部进入用户中心、后台、登录、注册和门户公开页面时，使用绝对路径和顶层跳转；页面内锚点滚动可以留在模板内部。

9. 静态资源与构建配置

HTML 中推荐使用相对资源：

系统从根路径提供模板入口时，会把这些地址映射到当前模板自己的资源目录。

Vite 模板必须设置相对资源基础路径：

禁止：

• 把资源写成开发机绝对路径。
• 写死 /assets/app.js，这可能与主程序资源重名。
• 引用 node_modules 中未打包的文件。
• 依赖开发服务器才能加载的模块。
• 把 sourcemap、缓存目录、源码依赖和整个主系统前端打入模板包。

10. 标题、SEO 和 favicon

三个页面加载站点配置后分别设置标题：

更新 SEO：

favicon 使用 site.ico，Logo 使用 site.logo。图片地址可能是绝对 URL，也可能是 /uploads/... 相对站点地址，模板不要自行拼接固定域名。

11. 加载、空数据和错误状态

每个动态区域都必须分别处理：

站点配置接口失败时可以使用模板默认品牌文字继续显示；文章详情接口失败时不能伪造文章内容。

12. 安全限制

• 只调用 /api/v1/site/home、文章、分类、公告等公开接口。
• 不调用 /api/v1/admin/*。
• 不读取 localStorage 中的登录 Token。
• 不在模板中保存 API 秘钥、AppSecret、数据库信息和授权密钥。
• 不在浏览器中实现扣费、权限判断、实名认证或违规检测业务。
• 不执行文章和公告内容中的 <script>。
• 外部链接使用 rel="noopener noreferrer"。
• 所有用户输入和 URL 参数在展示前进行类型检查。

13. 本地开发和打包

开发阶段可以独立启动模板，也可以放入系统插件目录测试。发布前目录应整理为：

打包 ZIP 时压缩 dist 内部内容，而不是压缩 dist 文件夹本身。

安装后的文件位置：

启用模板后依次验证：

浏览器地址不得出现：

14. 发布检查清单

• ☐ ZIP 根目录直接包含 manifest.json 和 index.html。
• ☐ plugin_type 为 portal，runtime 为 static。
• ☐ 首页、API 文档和文章详情三个公开地址都能直接刷新。
• ☐ 浏览器顶层地址不会跳转到 /portal-templates/。
• ☐ JS、CSS、图片均从当前模板目录加载，没有 404 和 MIME 错误。
• ☐ 登录、注册、用户中心链接使用绝对路径并跳转顶层窗口。
• ☐ 网站名称、标题、描述、Logo、favicon 来自 /site/home。
• ☐ 页脚版权、ICP 备案和公安备案来自 /site/home。
• ☐ 文章分类来自 /article-categories，没有写死后台分类。
• ☐ 文章列表不把摘要当正文，详情通过 /articles/{id} 获取。
• ☐ 公告使用 position=home，并处理展示方式和关闭规则。
• ☐ API 文档没有真实秘钥和敏感信息。
• ☐ 请求失败、空数据和文章不存在时不会白屏。
• ☐ 桌面端、平板和移动端没有横向溢出或文字遮挡。
• ☐ 发布包不包含 node_modules、缓存、源码和主系统无关文件。

15. 系统内对应实现位置