Skip to content

项目结构 ​

本文档描述 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.tsuseUserStore:csrf、userInfo、isLoggedIn、登录 / 登出 / 签到 / Token 过期定时器
theme.tsuseThemeStore: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
公共组件PascalCaseAppSkeleton.vue、NodeMap.vue
composableuseXxx.tsuseNotification.ts
store文件名 snake/lower,导出 useXxxStorestores/user.ts → useUserStore
工具函数camelCasenodeGeo.ts、redirect.ts
样式kebab-case 或 main.cssstyles/main.css

代码组织约定 ​

  • 缩进 2 空格(Vue / TS / CSS 一致)
  • 组件统一使用 <script setup lang="ts">
  • API 调用一律走 @/services/api,禁止在组件里直接 axios
  • 文案一律走 i18n,禁止硬编码中文 / 英文
  • 状态优先放 Pinia;页面内临时状态用 ref / reactive
  • 无测试框架,npm run build 是提交前唯一的强校验
  • 提交信息使用 feat: / fix: 前缀,一次提交只做一件事

相关页面 ​

基于 MIT 许可证发布