KrabiClaw

KrabiClaw

KrabiClaw 为餐厅、体验活动运营商、律师事务所和住宿接待方提供网站、预订、支付和消息服务，可通过控制面板或 ChatGPT 和 Claude 使用一个 MCP 服务进行管理。住宿服务包括房源、按晚提供的可订状态和价格、直接住宿预订以及住客消息。

基于 AGPL-3.0 开源。

• 报告漏洞或请求功能：提交 issue。 代表用户提交 issue 的助手可以预先填写表单；字段 ID 请见 .github/ISSUE_TEMPLATE。
• 账户、账单或私人数据：krabiclaw.com/help。
• 安全：SECURITY.md。
• 贡献：CONTRIBUTING.md。

Nuxt 5 nightly + Nitro 3 + Cloudflare Workers + D1。

包管理器：仅限 yarn。 切勿使用 npm 或 pnpm。

---

脚本

命令	功能
yarn dev	启动 Nuxt 开发服务器，支持 HMR，并在本地模拟 Cloudflare 绑定，地址为 http://localhost:3000。
yarn local:setup	唯一本地设置入口：迁移 D1、刷新测试数据、创建本地开发者账户并验证结果。
yarn dev:worker	使用 Wrangler 在本地构建并运行类生产环境的 Worker，地址为 http://localhost:3000。
yarn dev:worker:start	在本地运行现有的 .output Worker 构建产物，不重新构建。
yarn build	生产构建 → .output/
yarn db:generate	根据 server/db/schema.ts 生成新的 migrations/*.sql 文件
yarn drizzle:check	检查 server/db/schema.ts 是否与实时 D1 架构保持一致
yarn stripe:listen	将 Stripe webhook 转发到本地主机（仅限本地开发）
yarn canary:prod	用于生产环境的安全认证浏览器 canary（只读检查）。
yarn canary:notifications	生产环境提供商级别的电子邮件/WhatsApp 通知 canary。

---

生产环境 Canary 运行

为避免每次合并都意外产生电子邮件/WhatsApp 费用，正常的 main 部署会有意关闭真实发送的生产环境 canary。如需按需运行，请使用 GitHub Actions 工作流 Production Real-Send Canaries，并选择是否发送：

• 身份验证 OTP canary
• 通知电子邮件/WhatsApp canary

该工作流始终先运行生产环境冒烟测试，然后仅发送你为本次运行明确选择的真实 canary。

完整了解仅记录与实时电子邮件/WhatsApp 测试、生产环境安全验证，以及哪些公开提交路径会在生产环境中真实发送，请参阅 docs/notification-testing.md。

---

本地设置

1. 安装

corepack yarn install

仓库使用 Node.js 24.18.1。安装依赖前，请使用 .nvmrc 中指定的准确版本。更改 Node 版本时，请遵循 Node 运行时升级操作手册，以确保本地开发、CI、类型定义和 Worker 构建同步升级。

Yarn 只会在新版本发布满七天后接受新的直接和传递依赖包。常规的 yarn add 和 yarn up 命令会自动应用此规则。CI 会以不可变模式安装依赖包图，并在加固作业中重新检查注册表元数据。

对于紧急且经过审核的安全修复，只更新受影响的软件包：

corepack yarn up <package>@<fixed-version> --no-time-gate

请在拉取请求中记录安全公告以及绕过等待期的原因。不要将软件包添加到 npmPreapprovedPackages，也不要在 .yarnrc.yml 中停用版本等待限制。

2. 环境

将 .env.example 复制为 .env，并在其中填写应用程序密钥。这是 Nuxt、Wrangler、设置脚本和 E2E 测试共用的唯一一份本地配置。有关设置和迁移旧版 .dev.vars 文件的信息，请参阅本地开发。无需第二份密钥文件或符号链接。

3. 准备本地开发

corepack yarn local:setup

此命令可以安全地重复运行。它会将本地 D1 恢复到当前的迁移、测试数据、凭据和外键基线，然后输出唯一的本地开发者登录凭据：

URL: http://localhost:3000/login?email=developer%40playwright.example
Email: [email protected]
Password: <fresh value generated by local:setup>

此仅限 localhost 使用的账户是所有精选租户的成员，可以访问平台控制面板。每次运行设置时都会生成一个密码，该密码只会输出一次，并且仅以哈希形式存储在本地 D1 中。重复运行设置会删除现有的本地会话，因此之后请使用新输出的密码重新登录。

4. 运行

corepack yarn dev

应用位于 http://localhost:3000。

yarn dev 是常规的应用开发工作流。Nitro 会读取 wrangler.toml 中声明的绑定，模拟本地 D1/KV/R2 资源，并保留 Nuxt 热模块替换功能。它绝不会重置 D1。想要从生产快照恢复本地 D1 时，请运行 corepack yarn local:setup。

请通过控制面板 UI 打开租户控制面板，而不要猜测其 URL。必须手动构造路由时，控制面板路径中的组织标识是组织的 slug，而不是其子域名，其余路径都直接接在该标识后面：Kikuzuki 的 locations 路径为 /dashboard/org-bVY8SxxUuG6Ctk2CQnfCk8T2cPsj4jJX/locations。

如需验证生产运行时的浏览器行为，请使用本地生成的 Worker。Wrangler 和 Nuxt 会读取同一个 .env。Playwright 也会加载它，并向 Worker 提供测试专用的本地 URL 和交付设置。

yarn test:e2e:local tests/e2e/tenant-rendering.spec.ts

如需运行近似生产环境的本地 Worker：

yarn dev:worker

成功构建后，yarn dev:worker:start 会在不重新构建的情况下重启同一个 .output。源代码的修改不会自动编译到 .output 中；常规的热模块替换编辑工作流请使用 yarn dev。

Playwright 会应用本地 D1 架构、清除可丢弃的端到端测试产物、恢复生产快照、为经过验证的 Better Auth 账户配置合成数据、构建 Cloudflare Worker，并在本地 workerd 下启动它。通过身份验证的测试会使用 Playwright 进程内部生成的随机密码，经由 Better Auth 登录；此过程不需要电子邮箱收件箱，也不涉及绕过身份验证的路由。这些测试凭据并非第二种手动登录方式。进行浏览器操作时，请使用 corepack yarn local:setup 输出的本地开发者账户。

本地租户测试使用共享主机路由约定：浏览器访问 localhost，测试辅助工具则为所选测试数据提供 x-preview-tenant。部署的预发布环境使用直接的一级租户别名。这是权威的本地浏览器路径；进行 Worker 浏览器验证时，请勿依赖直接导航到 *.localhost。

http://localhost:3000/                  (x-preview-tenant: ncls)
http://localhost:3000/services          (x-preview-tenant: ncls)
http://localhost:3000/experiences       (x-preview-tenant: pottery-house)
http://localhost:3000/reservations      (x-preview-tenant: kikuzuki-krabi-thailand)

macOS 文件数限制修复

ulimit -n 65536

---

部署

部署流程遵循 .github/workflows/ci.yml 中的分支：

1. 拉取请求会针对本地 Worker 和从生产环境复制的本地 D1（db:pull:local）运行 Checks 和 E2E 套件。拉取请求不会触发部署。
2. 推送到 staging 后会运行 Checks，然后部署暂存 Worker、应用暂存迁移，并针对暂存环境本身运行只读 MCP 和租户渲染验证。不会向真实暂存环境写入测试数据。
3. 推送到 main 后会运行 Checks，然后部署生产 Worker、应用生产迁移，并运行只读生产浏览器验证。

CI 只会在相应分支的作业中调用原生 Wrangler 命令。

发生事故时，请使用 Cloudflare 的部署历史恢复到最近一次已知正常的生产部署，且不要更改 D1 数据。然后通过 staging 和 main 合入源代码修复，并重新执行浏览器检查。

生产密钥位于 Cloudflare 控制面板 → Workers & Pages → krabiclaw → Settings → Variables。

使用 Wrangler 设置受保护的内部作业密钥：

openssl rand -base64 32
yarn wrangler secret put CRON_SECRET

CRON_SECRET 用于保护内部定时端点。本地命令从 .env 读取配置；已部署的 Worker 使用 Cloudflare 密钥和 wrangler.toml 中的变量。

MCP 重新连接分诊和 Cloudflare 身份验证调试文档见 docs/observability.md。

强制执行的已部署浏览器发布检查和服务中断恢复规则文档见 docs/operations/release-and-outage-prevention.md。

---

架构

server/db/schema.ts 是唯一的架构事实来源；migrations/ 存放生成的输出。禁止手写迁移。

---

Stripe（本地）

yarn stripe:listen

将输出的 whsec_... 签名密钥复制到 .env，作为 STRIPE_WEBHOOK_SECRET。部署前切换回生产 webhook 密钥。

原生市场入驻使用单独的 Accounts v2 精简事件目标和签名密钥。参见 Stripe Connect onboarding。