架构、路由、安全与支持
了解 Starter 的架构边界、公开路由、安全责任、许可与支持政策。
VibeAny 使用渐进式 Clean Architecture 构建 SaaS 内核。目标是在不把 Starter 变成黑盒的前提下，让框架和服务商细节保持可替换。
分层说明
| 目录 | 职责 |
|---|---|
src/app | Next.js 页面、路由处理器、布局和传输层组装 |
src/interfaces | HTTP、MCP、CLI、cron 和 Webhook 协议适配器 |
src/features | UI、Hook、面向展示的 API 和产品组合 |
src/application | 用例、端口、角色上下文、策略和业务编排 |
src/entities | 纯领域类型、模型和算法 |
src/infrastructure | PostgreSQL 仓储，以及实现应用端口的服务商适配器 |
src/shared | 可复用 UI、认证辅助函数、Hook、状态和工具 |
src/lib | 正在逐步迁移到端口之后的底层配置与集成 |
核心依赖规则：
- 应用层代码不导入 Next.js 路由、UI、Drizzle 或基础设施实现。
- 实体层不依赖框架、数据库、服务商和环境。
- 基础设施层实现应用端口，并负责外部副作用。
- 路由处理器保持精简，把 HTTP 关注点转换为功能层或应用层调用。
- 服务商注册表按能力定义类型；它们不是全局服务定位器。
架构测试会强制执行这些边界。仅当变化点、复用需求、外部副作用，或安全与账务风险需要隔离时才引入抽象，不要为每个函数增加一层。
浏览器路由
根路由会重定向到默认语言，目前为英文。Starter 定义了 en、zh 和 es 三种语言。
| 路由 | 用途 |
|---|---|
/[locale] | 营销首页 |
/[locale]/about, /features, /pricing, /contact | 营销与转化页面 |
/[locale]/blog, /blog/[slug] | MDX 博客 |
/[locale]/privacy, /terms | 法律页面 |
/[locale]/login, /signup | Better Auth 入口页面 |
/[locale]/forgot-password, /reset-password, /verify-email | 凭据找回与验证 |
/[locale]/dashboard | 受保护的控制台 |
/[locale]/dashboard/billing, /credits, /integrations, /settings | 受保护的产品区域 |
/[locale]/dashboard/admin | 管理员界面 |
/[locale]/account | 受保护的账户设置 |
/[locale]/demo/image-generator | 可选、需要认证的图片生成演示 |
/oauth/authorize | 稳定且不本地化的 OAuth 授权入口；内部按语言渲染 |
认证页面是各语言下的扁平路由。不要链接到已经移除的 /auth/login 或 /auth/register 路径。
API 路由
(billing)、(public) 和 (internal) 等 Next.js 路由组只用于组织源文件，绝不会出现在 URL 中。
| 路由 | 方法与访问权限 |
|---|---|
/api/auth/[...all] | Better Auth 处理器 |
/api/payments/checkout | POST，需要认证的一次性支付结账 |
/api/payments/subscription/checkout | POST，需要认证的订阅结账 |
/api/payments/subscription | GET，需要认证的当前订阅 |
/api/payments/subscription/cancel | POST，需要认证、在周期结束时取消订阅 |
/api/payments/portal | POST，需要认证，打开已保存服务商的客户门户 |
/api/payments/confirm | POST，需要认证的支付结账返回确认 |
/api/payments/webhook | POST，由服务商签名的系统投递 |
/api/credits/balance, /history, /stats | GET，需要认证的积分视图 |
/api/credit-packages | GET，公开的有效产品目录 |
/api/storage/upload, /confirm, /delete | 需要认证的存储生命周期操作 |
/api/generate-image | POST，需要认证且受功能开关控制的图片生成 |
/api/contact | POST，公开联系表单提交 |
/api/user/profile, /password, /delete | 需要认证的账户操作 |
/api/admin/users/*, /api/admin/credits/adjust | 管理员操作 |
/api/mcp, /api/mcp/api-keys/* | MCP 传输层和需要认证的密钥管理 |
/api/oauth/authorize, /consent, /register, /token, /revoke | OAuth 授权服务器端点 |
/api/cron/subscription-credits | GET，由 CRON_SECRET 认证的系统任务 |
应用还会在 /.well-known/ 下发布 OAuth 授权服务器和受保护资源的元数据。
支付服务商边界
PAYMENTS_PROVIDER=stripe|creem 为新的支付结账和 Webhook 流量选择一个当前服务商。与服务商无关的应用层用例通过端口调用 Stripe 和 Creem 适配器。已保存的订阅会继续使用其原始服务商执行取消和客户门户操作。
因此，日常应用流程无需感知服务商，但现有订阅不会自动迁移。客户、支付方式、订阅和 Webhook 所有权迁移仍是一项独立的外部运维工作。
安全基线
生产应用会配置 CSP、HSTS、strict-origin referrer policy、SAMEORIGIN frame policy、MIME sniffing 防护和限制严格的 permissions policy。Better Auth 在生产环境使用安全 Cookie；邮箱密码认证要求完成邮箱验证，并使用 bcrypt cost 12 哈希密码。可选 Turnstile 验证需要同时配置浏览器站点密钥和服务端密钥。
这些默认设置不能替代针对具体应用的安全工作。尤其需要注意：内置 API 限流器把计数器存储在单个进程中，明确不适合在 Vercel、横向扩展服务或负载均衡器环境中充当生产级分布式控制。依赖限流防止滥用前，请换成共享且兼容无服务器架构的限流器。
应用所有者仍需负责：
- 轮换密钥，并为服务商凭据设置最小权限；
- 数据库备份、恢复演练和迁移审查；
- 为新增页面和 API 配置授权；
- 审查依赖和安全更新；
- 确保日志不包含凭据和个人数据；
- 承担最终产品的隐私、税务、支付、退款和其他法律义务。
如需报告未修改 Starter 中的漏洞，请发送邮件到 support@vibeany.io，主题为 [SECURITY] Vibeany Starter。请包含受影响版本、影响范围、复现步骤和最小概念验证，并移除凭据及无关客户数据。不要公开尚未修复的漏洞，也不要测试自己不拥有或未获授权的系统。
仓库不承诺响应或修复 SLA。安全维护以受支持 1.0.x 系列中的最新补丁版本为目标；经过修改或版本更旧的部署可能需要自行移植修复。
商业许可摘要
权威商业许可随购买的源码提供，具体权利仍以订单确认为准。该许可向订单指定的被许可方授予非独占、不可转让、永久的使用权。被许可方可以在购买范围内使用和修改已获得的版本，并构建商业托管终端产品。
该许可不允许：
- 公开 Starter 源码，或将源码放入公开仓库；
- 以源码形式重新分发或再许可；
- 转售 Starter；
- 使用 Starter 制作与其竞争的 Starter 或模板；
- 移除所有权声明；
- 向授权用户之外的其他人分享源码。
客户项目、承包商参与和源码交付并非默认授权。只有订单明确包含相应范围时，才允许这些用途。
已购买版本不依赖卖方激活服务或回传机制。只有订单或书面报价明确说明时，才包含更新、未来主版本和支持。本摘要仅用于解释，不能替代许可或订单条款。
支持边界
只有订单确认或购买时的书面报价明确包含支持，才能获得支持服务。已包含的支持涵盖：关于安装未修改 Starter 的合理问题、复现 Starter 缺陷，以及理解已记录的配置。
除非另有约定，支持不包含定制功能开发、具体应用调试、数据恢复、基础设施运维、服务商故障、第三方账户配置，也不包含法律和合规建议。仓库不承诺响应时间、解决时间、更新频率或持续提供未来版本。
如果支持服务已包含在订单中，请使用订单指定的联系渠道。提供 Starter 版本、已脱敏日志、复现步骤和预期行为。报告漏洞时，请使用上面的私密安全渠道，不要通过普通支持请求提交。
如需继续排查运维问题，请阅读部署故障排查。