快速开始

前置要求

Node.js 22.12+（Astro 7.2.8 的最低要求）
pnpm 10.34.5（以根目录 packageManager 为准）
PostgreSQL；当前生产使用 Neon
Git

1. 安装依赖

pnpm install

2. 配置环境变量

cp apps/server/.dev.vars.example apps/server/.dev.vars
cp apps/web/.dev.vars.example apps/web/.dev.vars
pnpm env:check

服务端本地变量统一放在 apps/server/.dev.vars。至少配置：

BETTER_AUTH_SECRET=replace-with-a-random-32-char-secret
BETTER_AUTH_URL=http://localhost:8787/api/auth
CORS_ORIGIN=http://localhost:3000
AUTH_EMAIL_FROM=IAM <no-reply@example.com>
DATABASE_URL=postgresql://username:password@host/database?sslmode=require
DATABASE_URL_DIRECT=postgresql://username:password@host/database?sslmode=require
NODE_ENV=development

可选能力还需要：

企业微信登录：WECOM_CORP_ID、WECOM_AGENT_ID、WECOM_APP_SECRET、代理 URL 与 API Key
通讯录同步：同步 secret、Cron token、回调 token 与 AES key
平台管理员引导：BOOTSTRAP_ADMIN_WECOM_USER_IDS，使用逗号分隔企微 UserID
认证邮件：生产由 Worker EMAIL Binding 和 AUTH_EMAIL_FROM 提供

前端 apps/web/.dev.vars 在本地通常只需要：

AUTH_UPSTREAM_URL=http://localhost:8787

生产环境不需要 AUTH_UPSTREAM_URL，Web Worker 使用 AUTH_API Service Binding。

3. 初始化数据库

对已有 migration 执行：

pnpm db:migrate

pnpm db:push 只用于本地临时验证 schema，不应代替可审查的 migration。

如果修改了 Better Auth 插件或认证字段，使用固定版本重新生成 schema，再生成并执行 migration：

pnpm dlx auth@1.7.1 generate --yes \
  --config packages/auth/src/index.ts \
  --output packages/db/src/schema/auth.ts
pnpm db:generate
pnpm db:migrate

4. 启动服务

推荐分别启动 Web 与 Worker 兼容 API，以匹配文档中的 8787 端口：

# 终端 1
pnpm dev:server:worker

# 终端 2
pnpm dev:web

也可以运行 pnpm dev，它会通过 Turbo 启动 Web 和 Node 模式 server。

5. 验证

运行 pnpm env:check，确认必填变量和可选功能组完整。
打开 http://localhost:3000。
访问 http://localhost:8787/api/health 检查 API、企微和邮件配置状态。
注册邮箱账号或使用已配置的企业微信登录。
运行 pnpm check 和受影响测试。

本地未配置 Cloudflare Email Binding 时，验证/重置邮件内容会输出到服务端日志；生产环境缺少 Binding 会直接报错。