项目结构
本文档描述 HayFrp Console 5.0 的目录结构(仓库 HayFrp-Console-5.0,包名 hayfrp-web)。
顶层结构
HayFrp-Console-5.0/
├── src/ # 前端源码
├── public/ # 静态资源(favicon、robots.txt、sitemap.xml、logo 等)
├── scripts/ # 构建 / 数据生成脚本
├── docs/ # 前端接口调用补充文档(api-calls.md 等)
├── dist/ # 构建输出
├── index.html # HTML 模板
├── vite.config.ts # Vite 配置(别名、PWA、分包、terser)
├── tsconfig.json # TS 配置(strict + noUnusedLocals 等)
├── package.json # 依赖与脚本
├── API.md # 后端接口完整文档(项目内主参考)
├── admin.md / login-api.md / traffic-api.md # 后端接口补充说明(登录 / 流量趋势等)
├── README.md # 前端路由、守卫、登录态、接口接入约定
└── AGENTS.md / CLAUDE.md # 面向 AI 助手 / 协作者的工程约定src 目录
src/
├── App.vue # 根组件:NConfigProvider + 全局弹窗 + AppLayout
├── main.ts # 入口:Pinia / Router / i18n / Naive UI / 进度条 / 彩蛋
├── vite-env.d.ts # Vite 环境类型声明
├── components/ # 公共组件
│ ├── AppLayout.vue # 主布局(顶栏 / 侧边栏 / 用户菜单 / 通知中心)
│ ├── AppSkeleton.vue # 骨架屏
│ ├── NodeMap.vue # 节点分布地图(SVG)
│ ├── AnnouncementModal.vue # 系统公告弹窗
│ ├── AdBanner.vue # 广告横幅
│ ├── CnRedirectModal.vue # 国内用户域名切换提示
│ ├── OfflineIndicator.vue # PWA 离线提示
│ ├── SeoHead.vue # 动态 SEO 标签
│ └── DevWatermark.vue # 开发环境水印
├── composables/
│ └── useNotification.ts # 浏览器通知 + 通知历史
├── data/ # 静态数据
│ ├── worldCountries.json # 世界国界轮廓
│ ├── chinaProvinces.json # 中国省界
│ ├── nodeLocations.json # 城市 / 国家坐标表
│ └── developmentTimeline.json # 开发时间线
├── i18n/ # 国际化(5 种语言)
│ ├── index.ts
│ ├── zh-CN.ts / zh-TW.ts / en-US.ts / ja-JP.ts / ru-RU.ts
├── plugins/
│ └── progressPlugin.ts # 路由切换顶部进度条
├── router/
│ └── index.ts # 路由配置 + 全局守卫
├── services/
│ └── api.ts # 唯一的 API 客户端(含多端点故障转移)
├── stores/ # Pinia
│ ├── user.ts # 登录态、用户信息、Token
│ └── theme.ts # 主题、菜单位置、移动端检测
├── styles/
│ └── main.css # 全局样式(含移动端覆盖、暗色 / 二次元风格)
├── utils/
│ ├── token.ts # Token 读写 / 过期判断
│ ├── redirect.ts # Open Redirect 防护
│ └── nodeGeo.ts # 节点名称 → 经纬度
└── views/ # 15 个路由组件 + 404
├── Landing.vue # 首页
├── Login.vue # 登录
├── Register.vue # 注册
├── Dashboard.vue # 控制台
├── Proxies.vue # 隧道管理
├── Lobby.vue # 联机大厅
├── UserSettings.vue # 用户设置
├── Customize.vue # 面板个性化
├── Nodes.vue # 节点列表
├── Download.vue # 下载
├── About.vue # 关于
├── ServiceProvider.vue # 服务商控制台
├── Launcher.vue # 启动器授权
├── CloudControl.vue # 云控设备
├── Bind.vue # 绑定账户
└── NotFound.vue # 404目录职责说明
src/services/api.ts
唯一的后端访问入口,导出 api 对象(约 90 个方法),内部实现:
API_ENDPOINTS:3 个 API 端点,按优先级排列requestWithFallback():网络错误或status >= 500时自动切下一个端点(最多 3 次)createRequestInstance():每个请求使用独立 axios 实例,避免并发时baseURL互相覆盖- 响应拦截器:剥离 PHP Warning / Notice 前缀后重新解析 JSON;HTTP
401自动登出并跳/login - 默认请求头带
waf: off(绕过雷池 WAF),超时 15 秒
详见 通用约定。
src/router/index.ts
路由表 + 全局前置守卫。守卫从 @/utils/token 读取登录态,见 路由守卫。
src/stores/
| 文件 | 说明 |
|---|---|
user.ts | useUserStore:csrf、userInfo、isLoggedIn、登录 / 登出 / 签到 / Token 过期定时器 |
theme.ts | useThemeStore:isDark、theme、animeStyle、menuPosition、isMobile |
src/styles/main.css
全局样式,包含:主题 CSS 变量、暗色模式适配(html.dark)、二次元风格(html.anime-style)、紧凑模式(body.compact-mode)、移动端断点覆盖、进度条样式。
配置文件说明
package.json
json
{
"name": "hayfrp-web",
"scripts": {
"dev": "vite",
"build": "vue-tsc -b && vite build",
"preview": "vite preview"
}
}构建即校验
npm run build 会先跑 vue-tsc -b,配置中开启了 strict、noUnusedLocals、noUnusedParameters、noFallthroughCasesInSwitch。未使用的变量 / 参数会直接让构建失败,提交 PR 前必须通过 npm run build。
vite.config.ts
typescript
export default defineConfig({
plugins: [vue(), VitePWA({ registerType: 'autoUpdate', /* ... */ })],
resolve: { alias: { '@': resolve(__dirname, 'src') } },
server: { port: 3000 },
build: {
cssCodeSplit: true,
rollupOptions: {
output: {
assetFileNames: 'assets/[ext]/[name]-[hash][extname]',
manualChunks: {
'vue-vendor': ['vue', 'vue-router', 'pinia'],
'naive-ui': ['naive-ui'],
'utils': ['axios', 'dompurify', 'qrcode']
}
}
},
minify: 'terser',
terserOptions: { compress: { drop_console: true, drop_debugger: true } }
}
})- 开发端口固定 3000
@/指向src/- 生产构建使用
terser且drop_console: true,线上没有 console 输出 - PWA 使用
autoUpdate,clientsClaim/skipWaiting/cleanupOutdatedCaches
文件命名规范
| 类型 | 规范 | 示例 |
|---|---|---|
| 视图组件 | PascalCase,与路由名一致 | UserSettings.vue、CloudControl.vue |
| 公共组件 | PascalCase | AppSkeleton.vue、NodeMap.vue |
| composable | useXxx.ts | useNotification.ts |
| store | 文件名 snake/lower,导出 useXxxStore | stores/user.ts → useUserStore |
| 工具函数 | camelCase | nodeGeo.ts、redirect.ts |
| 样式 | kebab-case 或 main.css | styles/main.css |
代码组织约定
- 缩进 2 空格(Vue / TS / CSS 一致)
- 组件统一使用
<script setup lang="ts"> - API 调用一律走
@/services/api,禁止在组件里直接axios - 文案一律走 i18n,禁止硬编码中文 / 英文
- 状态优先放 Pinia;页面内临时状态用
ref/reactive - 无测试框架,
npm run build是提交前唯一的强校验 - 提交信息使用
feat:/fix:前缀,一次提交只做一件事