tinyship-auth

TinyShip Auth 认证方式配置指南

本技能用于指导在 TinyShip 中配置认证方式，底层基于 Better Auth 构建。

可用认证方式

• 邮箱/密码：简单，完成基础设置后即可使用
• Google OAuth：中等难度，需要 Google Cloud Console 项目
• GitHub OAuth：中等难度，需要 GitHub OAuth App
• 微信登录：复杂，需要微信开放平台 + 营业执照
• 短信验证码（SMS OTP）：复杂，需要 Twilio 或阿里云短信账号

请先询问用户想配置哪一种或哪几种方式，再按照对应章节操作。

邮箱/密码（默认）

基础设置完成后即可使用。若要启用邮箱验证和密码重置邮件，需配置邮件服务商：

1. 设置 Resend（最简单）：在 resend.com 获取 API key
2. 在 .env 中添加：

RESEND_API_KEY="re_xxxxx" EMAIL_DEFAULT_FROM="noreply@yourdomain.com"

详细邮件认证配置参见 docs/user-guide/auth/email.md。

Google OAuth

详细步骤见 references/google-oauth.md。摘要：

1. 在 Google Cloud Console 创建项目
2. 配置 OAuth 同意屏幕
3. 创建 OAuth 2.0 凭据，重定向 URI 填写：{APP_BASE_URL}/api/auth/callback/google
4. 在 .env 中添加：

GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com" GOOGLE_CLIENT_SECRET="GOCSPX-xxxxx"

GitHub OAuth

详细步骤见 references/github-oauth.md。摘要：

1. 进入 GitHub Settings > Developer settings > OAuth Apps > New
2. 设置回调地址：{APP_BASE_URL}/api/auth/callback/github
3. 在 .env 中添加：

GITHUB_CLIENT_ID="Ov23xxxxxxxxxx" GITHUB_CLIENT_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

微信登录

详细步骤见 references/wechat-login.md。摘要：

1. 在微信开放平台注册（需要营业执照）
2. 创建网站应用
3. 在 .env 中添加：

NEXT_PUBLIC_WECHAT_APP_ID="wx_xxxxx" VITE_WECHAT_APP_ID="wx_xxxxx" WECHAT_APP_SECRET="xxxxx"

短信验证码登录

详细步骤见 references/sms-login.md。

Twilio 摘要：

1. 创建 Twilio 账号并获取凭据
2. 在 .env 中添加：

TWILIO_ACCOUNT_SID="ACxxxxx" TWILIO_AUTH_TOKEN="xxxxx" TWILIO_DEFAULT_FROM="+1234567890"

阿里云摘要：

1. 开通阿里云短信服务，创建签名和模板
2. 在 .env 中添加：

ALIYUN_ACCESS_KEY_ID="xxxxx" ALIYUN_ACCESS_KEY_SECRET="xxxxx" ALIYUN_SMS_SIGN_NAME="YourSign" ALIYUN_SMS_TEMPLATE_CODE="SMS_000000000"

前端：配置登录按钮

添加服务商后，更新社交登录按钮以显示或隐藏它们：

Next.js：编辑 apps/next-app/components/social-auth.tsx：

const defaultProviders: SocialProvider[] = ['google', 'github']; // 可增减：'google', 'github', 'wechat', 'phone'

Nuxt.js：编辑 apps/nuxt-app/components/SocialAuth.vue：

providers: () => ['google', 'github'] // 可增减：'google', 'github', 'wechat', 'phone'

TanStack Start：编辑 apps/tanstack-app/src/components/social-auth.tsx（与 Next.js 模式相同）。

验证

1. 修改 .env 后重启开发服务器
2. 访问 /signin，检查已配置的服务商是否出现
3. 测试各服务商的登录流程
4. 在 /admin/users 管理面板中确认用户已生成

TinyShip 仓库中的参考文件

• config/auth.ts — 认证服务商配置
• libs/auth/AGENTS.md — 认证库架构
• docs/user-guide/auth/overview.md — 认证文档索引
• apps/next-app/components/social-auth.tsx — Next.js 社交登录按钮
• apps/tanstack-app/src/components/social-auth.tsx — TanStack Start 社交登录按钮
• apps/nuxt-app/components/SocialAuth.vue — Nuxt.js 社交登录按钮