# Metapi 项目目录规范 本文档说明 Metapi 的目录组织方式，目标是让新功能落位更稳定、查找更直接、临时文件不污染根目录。 ## 顶层目录 ```text metapi/ ├── data/ # 运行时数据（SQLite 数据库） ├── dist/ # 构建产物（前后端） ├── docker/ # 容器相关文件 │ ├── Dockerfile # 多阶段构建（Alpine） │ └── docker-compose.yml # Docker Compose 编排 ├── docs/ # 文档与资源 │ ├── logos/ # Logo 素材 │ │ └── drafts/ # Logo 草稿 │ └── project-structure.md ├── drizzle/ # Drizzle ORM 迁移 SQL 与元数据 ├── scripts/ # 项目脚本（按场景分组） │ └── dev/ │ └── restart.bat # Windows 开发环境快捷重启 ├── src/ │ ├── server/ # Fastify 后端服务 │ └── web/ # React 前端应用 ├── tmp/ # 临时调试文件（已 gitignore） ├── package.json ├── tsconfig.json ├── tsconfig.server.json ├── vite.config.ts └── README.md ``` ## 后端目录约定（`src/server`） ```text src/server/ ├── index.ts # 服务启动入口 ├── config.ts # 环境变量与配置加载 ├── middleware/ │ └── auth.ts # 认证中间件 ├── db/ │ ├── index.ts # 数据库连接 │ ├── schema.ts # Drizzle 表定义（全部 Schema） │ └── migrate.ts # 迁移执行器 ├── routes/ │ ├── api/ # 管理 API 路由 │ │ ├── auth.ts # 登录 / 登出 │ │ ├── sites.ts # 站点 CRUD │ │ ├── accounts.ts # 账号管理 │ │ ├── accountTokens.ts # Token 同步与管理 │ │ ├── tokens.ts # Token 批量操作 │ │ ├── tokenRoutes.ts # 路由规则管理 │ │ ├── checkin.ts # 签到触发与日志 │ │ ├── stats.ts # 仪表盘统计 │ │ ├── search.ts # 全局搜索 │ │ ├── events.ts # 事件日志 │ │ ├── tasks.ts # 后台任务状态 │ │ ├── settings.ts # 运行时配置 │ │ ├── monitor.ts # 外部监控集成 │ │ └── test.ts # 测试 / 验证端点 │ └── proxy/ # 代理路由 │ ├── router.ts # 代理路由注册 │ ├── chat.ts # Chat Completions & Claude Messages │ ├── completions.ts # Legacy Completions │ ├── embeddings.ts # 向量嵌入 │ ├── images.ts # 图像生成 │ ├── models.ts # 模型列表 │ └── chatFormats.ts # OpenAI <-> Claude 格式转换 └── services/ ├── platforms/ # 平台适配器 │ ├── base.ts # 适配器接口定义 │ ├── index.ts # 适配器注册表 │ ├── newApi.ts # New API 适配器 │ ├── oneApi.ts # One API 适配器 │ ├── oneHub.ts # OneHub 适配器 │ ├── doneHub.ts # DoneHub 适配器 │ ├── veloera.ts # Veloera 适配器 │ ├── anyrouter.ts # AnyRouter 适配器 │ └── sub2api.ts # Sub2API 适配器 ├── tokenRouter.ts # 智能路由引擎 ├── checkinService.ts # 签到执行 ├── checkinScheduler.ts # 签到调度 ├── checkinRewardParser.ts # 奖励金额解析 ├── balanceService.ts # 余额刷新 ├── modelService.ts # 模型发现与管理 ├── modelPricingService.ts # 模型定价 ├── modelAnalysisService.ts # 使用分析 ├── notifyService.ts # 多渠道通知 ├── notificationThrottle.ts # 通知节流 ├── alertService.ts # 告警事件 ├── alertRules.ts # 告警规则 ├── backupService.ts # 数据导入导出 ├── backgroundTaskService.ts # 后台任务管理 ├── accountCredentialService.ts # 凭证加密 ├── accountHealthService.ts # 健康状态管理 ├── accountExtraConfig.ts # 平台专属配置 ├── proxyRetryPolicy.ts # 重试策略 ├── proxyUsageParser.ts # Token 用量解析 ├── proxyUsageFallbackService.ts # 余额兜底估算 ├── failureReasonService.ts # 错误分类 ├── siteDetector.ts # 平台自动检测 ├── dailySummaryService.ts # 每日摘要 ├── todayIncomeRewardService.ts # 今日收入快照 ├── localTimeService.ts # 时区处理 ├── upstreamModelDescriptionService.ts # 上游模型描述缓存 ├── startupInfo.ts # 启动信息 └── settings.ts # 运行时配置管理 ``` ## 前端目录约定（`src/web`） ```text src/web/ ├── App.tsx # 应用入口与路由配置 ├── main.tsx # Vite 入口 ├── api.ts # 统一 API 请求客户端 ├── authSession.ts # 认证会话管理 ├── i18n.tsx # 国际化 ├── components/ # 通用 UI 组件 │ ├── BrandIcon.tsx # 模型品牌图标 │ ├── ModelAnalysisPanel.tsx # 消费分析图表 │ ├── SearchModal.tsx # 全局搜索弹窗 │ ├── NotificationPanel.tsx # 实时事件面板 │ ├── Toast.tsx # 通知提示 │ ├── SiteDistributionChart.tsx # 余额分布饼图 │ └── SiteTrendChart.tsx # 消费趋势图 ├── pages/ # 页面组件（路由页） │ ├── Dashboard.tsx # 仪表盘 │ ├── Sites.tsx # 站点管理 │ ├── Accounts.tsx # 账号管理 │ ├── Tokens.tsx # Token 管理 │ ├── TokenRoutes.tsx # 路由规则 │ ├── Models.tsx # 模型广场 │ ├── CheckinLog.tsx # 签到日志 │ ├── ProxyLogs.tsx # 代理日志 │ ├── Settings.tsx # 系统设置 │ ├── About.tsx # 关于页面 │ └── helpers/ # 页面级纯逻辑 / 工具函数（含测试） └── public/ # 静态资源 ``` ## 目录卫生规则 - 所有调试临时文件放入 `tmp/`，不要散落在项目根目录。 - 开发脚本统一放入 `scripts//`，根目录仅保留必要入口文件。 - 素材草稿统一归档到 `docs/logos/drafts/`，避免根目录堆积二进制文件。 - 测试文件与被测文件同目录（`*.test.ts`），方便就近维护。 - 平台适配器新增时，在 `services/platforms/` 中创建独立文件并注册到 `index.ts`。