---
url: /docs/agentbuff-stack.md
---
# AgentBuff Stack

AgentBuff Stack 是用于快速发布海外英文工具站的通用底座，先自用，再考虑出售。模板与具体任务分开：示例 JSON 格式化和文本清理只用于验证输入、预览、下载和账号历史流程，不代表已验证的新词机会。

当前版本 **0.3**。公开页面、工作台和本地 API 可运行；第三方集成需要独立服务凭据及验收；尚未开发的能力有明确边界。完整状态见 [模块总览](./modules.md)。

## 技术栈

| 层 | 当前选择 | 职责与配置入口 |
| --- | --- | --- |
| 公开网站 | Astro + React islands | 静态 HTML、工具页、博客；`apps/web/` |
| 用户工作台 | React + TanStack Router / Query + Jotai | 登录、历史、积分、团队与设置；`apps/app/` |
| 设计系统 | Astryx + StyleX，保留 Radix 控件 | 统一主题与组件；`packages/ui/design/` |
| API | Hono + tRPC + Zod | 认证边界、输入校验、类型化接口；`apps/api/` |
| 身份 | Better Auth | 密码、OTP、Passkey、Google / GitHub OAuth、组织 |
| 数据 | PostgreSQL + Drizzle | 用户、组织、订阅、结果与积分账本；`db/` |
| 生产数据路径 | Neon + Cloudflare Hyperdrive | 未部署验收；缓存连接不用来读权限或支付状态 |
| 邮件 | React Email + Resend | 验证、密码重置、OTP；本地预览捕获邮件 |
| 支付 | Better Auth Stripe plugin | 订阅与账单；未做真实沙箱验收 |
| 公开页统计 | 可选 Cloudflare Web Analytics | 默认关闭，不收集工具输入或私有页面 |
| 文档 | VitePress | 独立静态文档、搜索、模块说明；`docs/` |
| 本地与测试 | Bun、TypeScript、Vitest、PGlite、Oxlint、Oxfmt | Bun 仅用于本地；生产运行时是 Workers |
| 部署 | Cloudflare Workers + Wrangler；Terraform 管资源 | 三个 Worker 内部服务绑定；未上线验收 |

版本以 `package.json` 和 `bun.lock` 为准，不把文档里的版本号当作自动升级指令。当前选择继续保持 Cloudflare + Neon 方向，不为对齐竞品而改成 Next.js。

## 三类配置

1. **产品选项**：`packages/core/website.ts`；只放公开、可打包的数据。
2. **服务凭据**：本地 `.env.local`，部署时 Cloudflare Secrets；通过 API 环境契约校验。
3. **资源与路由**：各应用的 `wrangler.jsonc` 和 `infra/`；Worker 名、域名、Hyperdrive、未来的 R2 / Queue 绑定。

修改产品选项后重新构建全部应用，修改后端环境后重启 API。`packages/core/site.ts` 是兼容读取视图，品牌的唯一编辑入口是 `website.ts`。

## 文档路径

[快速开始](./quick-start.md) → [网站配置](./website.md) → [环境变量](./env.md) → [模块总览](./modules.md) → [部署与验收](./deployment.md)。

侧边栏后半部分保留 Kriasoft 的架构与配方参考。遇到上游示例与本站配置不一致，以 AgentBuff Stack 本节和当前源码为准；保留原 MIT 版权及第三方许可。

## 公开参考

核对日期：2026-10-09。参考 [MkSaaS 模板介绍](https://mksaas.com/zh/docs)、[网站配置](https://mksaas.com/zh/docs/config/website)、[环境配置](https://mksaas.com/zh/docs/env) 的模块组织方式；未使用其商业源码。我们的选择与实现状态独立记录，不宣称已拥有相同的全部能力。

模板官网与产品底座已经分开。见[官网、案例与演示](./website-showcase)以及[版本与升级](./template-upgrades)。

文件上传的频率保护、可选 Turnstile、服务故障处理和真实验收边界见[执行限制与验证](./execution-security)。

异步任务的内部记录、并发、输入保留与未完成的队列 / 界面验收见[任务生命周期](./task-lifecycle)。