Clerk 认证配置指南

本文档介绍如何配置 Clerk 用户认证系统，这是 Vibany 项目的身份认证解决方案。

什么是 Clerk

Clerk 是一个完整的用户认证和身份管理服务，提供：

• 邮箱/密码登录
• 社交登录（Google、GitHub 等）
• 多因素认证 (MFA)
• 用户管理仪表板
• 会话管理

注册 Clerk 账号

1. 创建账号

访问 https://clerk.com 注册账号。

2. 创建应用

1. 登录 Clerk Dashboard
2. 点击 "Create Application"
3. 输入应用名称（如 "Vibany AI"）
4. 选择登录方式（建议保留 Email + Google）

获取 API Keys

1. 进入 API Keys 页面

在 Clerk Dashboard 中：

1. 选择你的应用
2. 左侧菜单 → "Configure" → "API Keys"

2. 复制密钥

找到以下密钥：

# Publishable Key（公钥，前端使用）
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...

# Secret Key（私钥，后端使用）
CLERK_SECRET_KEY=sk_test_...

注意：

• pk_ 开头的为 Publishable Key
• sk_ 开头的为 Secret Key
• 生产环境使用 pk_live_ 和 sk_live_
• 测试环境使用 pk_test_ 和 sk_test_

配置环境变量

在 .env.local 文件中添加：

# Clerk 公钥（前端使用，NEXT_PUBLIC_ 前缀会暴露给浏览器）
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_dummydummydummydummy

# Clerk 密钥（后端使用，保密）
CLERK_SECRET_KEY=sk_test_0000000000000000000000000000000000000000

# 登录/注册页面 URL（必须设置，否则会重定向到 Clerk Portal 导致 CORS 错误）
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/login
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/register

# 登录/注册成功后的重定向 URL
CLERK_SIGN_IN_FALLBACK_REDIRECT_URL=/draw
CLERK_SIGN_UP_FALLBACK_REDIRECT_URL=/draw

# 启用 Clerk 调试日志（开发时使用）
CLERK_DEBUG=false

自定义登录/注册页面

Vibany 使用自定义的登录/注册页面，而非 Clerk 的默认页面。

1. 确保环境变量已设置

NEXT_PUBLIC_CLERK_SIGN_IN_URL=/login
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/register

2. 页面文件位置

• 登录页面：app/login/page.tsx
• 注册页面：app/register/page.tsx

3. 页面代码示例

// app/login/page.tsx
import { SignIn } from "@clerk/nextjs";

export default function LoginPage() {
  return (
    <div className="flex min-h-screen items-center justify-center">
      <SignIn 
        fallbackRedirectUrl="/draw"
        signUpUrl="/register"
      />
    </div>
  );
}

管理员配置

1. 获取管理员 User ID

1. 在 Clerk Dashboard → Users 中找到管理员账号
2. 复制 User ID（格式：user_xxxxx）

2. 配置管理员白名单

# 在 .env.local 中添加
ADMIN_USER_IDS=user_abc123,user_def456

也可以配置邮箱：

ADMIN_USER_EMAILS=admin@yourdomain.com,operator@yourdomain.com

3. 验证管理员权限

代码中检查管理员权限：

const adminIds = process.env.ADMIN_USER_IDS?.split(',') || [];
const isAdmin = adminIds.includes(userId);

多域名部署

如果使用子域名（如 cn.yourdomain.com）：

1. 在 Clerk Dashboard 添加域名

1. 进入 Dashboard → Configure → Domains
2. 点击 "Add domain"
3. 输入子域名（如 cn.yourdomain.com）

2. 配置 Satellite domains

对于子域名部署，需要配置 Satellite domains：

1. 在 Domains 页面选择 "Satellite" 类型
2. 设置主域名为 Primary domain
3. 子域名为 Satellite domain

3. 配置 Allowed Origins

在 Dashboard → Configure → Security → Allowed Origins 中添加：

https://yourdomain.com
https://cn.yourdomain.com

用户同步到本地数据库

Vibany 会自动将 Clerk 用户同步到本地 PostgreSQL 数据库。

同步流程

1. 用户首次登录时触发 webhook 或 API 调用
2. 系统检查邮箱是否在黑名单
3. 创建/更新本地用户记录
4. 初始化用户钱包

数据库表结构

// lib/db/schema.ts
export const users = pgTable("users", {
  clerkId: text("clerk_id").primaryKey(),
  email: text("email").notNull(),
  username: text("username").notNull(),
  avatarUrl: text("avatar_url"),
  extra: jsonb("extra").default({}).notNull(),
  createdAt: timestamp("created_at").defaultNow().notNull(),
  updatedAt: timestamp("updated_at").defaultNow().notNull(),
});

故障排除

CORS 错误

错误信息：

Access to fetch at 'https://...' from origin '...' has been blocked by CORS policy

解决方案：

1. 确保设置了 NEXT_PUBLIC_CLERK_SIGN_IN_URL 和 NEXT_PUBLIC_CLERK_SIGN_UP_URL
2. 在 Clerk Dashboard → Security → Allowed Origins 中添加你的域名

登录后重定向错误

解决方案：

1. 检查 CLERK_SIGN_IN_FALLBACK_REDIRECT_URL 和 CLERK_SIGN_UP_FALLBACK_REDIRECT_URL 是否设置
2. 确保路径正确（如 /draw 而非 draw）

401 Unauthorized

解决方案：

1. 检查 NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY 和 CLERK_SECRET_KEY 是否正确
2. 确认密钥未过期
3. 检查是否混淆了测试和生产密钥

调试模式

启用调试日志查看详细信息：

CLERK_DEBUG=true

安全配置

1. 密钥管理

• 不要将 .env.local 提交到 Git
• 定期轮换 Secret Key
• 生产环境使用 Live 密钥

2. 会话配置

在 Clerk Dashboard → Sessions 中配置：

• 会话持续时间
• 空闲超时时间
• 多设备登录策略

3. 安全设置

在 Dashboard → Security 中配置：

• 强制 MFA（可选）
• 密码策略
• 登录尝试限制

费用说明

功能	免费套餐	付费套餐
MAU (月活用户)	10,000	无限制
社交登录	✅	✅
自定义域名	✅	✅
多因素认证	基础	高级

对于早期项目，免费套餐通常足够使用。

相关文档

• 环境变量完整配置
• 用户管理指南
• 故障排除手册
• Clerk 官方文档