快速开始#

安装依赖#

bun install
bun run version:write

准备本地环境#

cp apps/api-worker/.dev.vars.example apps/api-worker/.dev.vars
cp apps/web/.env.example apps/web/.env

最少补齐这些变量：

• apps/api-worker/.dev.vars
  • SESSION_SECRET
  • BOOTSTRAP_ADMIN_INVITE_CODE（可选；仅当你希望空库本地环境可通过邀请码引导首个管理员时才需要）
  • WEB_APP_ORIGIN（passkey 必需；它提供主 WebAuthn 可信来源，单来源时也直接决定 RP ID；本地调试 passkey 时必须使用 http://localhost:4173，不要用 IP 字面量）
  • WEB_APP_ORIGINS（可选；如果要同时保留多个生产控制台域名给 passkey 使用，并共享一套非 public suffix 的 RP ID 后缀，就在这里补充）
  • GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET（可选；启用 GitHub 登录）
  • LINUXDO_CLIENT_ID / LINUXDO_CLIENT_SECRET（可选；启用 LinuxDO 登录）
• apps/web/.env
  • VITE_API_BASE_URL

启动 API Worker 和控制台#

WORKER_PORT=8787 bun run --cwd apps/api-worker dev
PORT=4173 bun run --cwd apps/web dev

启动公开文档和 Storybook#

DOCS_PORT=56007 bun run --cwd docs-site dev
STORYBOOK_PORT=6006 bun run --cwd apps/web storybook

本地访问地址#

• 控制台：http://localhost:4173
• API Worker：http://localhost:8787
• 公开文档：http://localhost:56007
• Storybook：http://localhost:6006

登录方式#

• 第三方登录与注册统一收敛到 /login
• Passkey 首次注册必须走邀请码；绑定完成后可直接用于后续登录
• 自动化与应急恢复流程继续使用 API Key
• 本地验 passkey 时，请从 localhost 打开控制台，不要用 127.0.0.1

生产发布面#

• Cloudflare Workers：API 与收信 Worker
• Cloudflare Pages：登录后的控制台
• GitHub Pages：公开文档站和 Storybook

相关文档#

• Cloudflare Token 权限
• 部署与环境变量
• 域名目录与启用流程