Gumroad 本地开发环境用户与认证（Users Authentication）完全指南

Gumroad 本地开发环境用户与认证（Users & Authentication）完全指南

【免费下载链接】gumroadSee what sticks项目地址: https://gitcode.com/GitHub_Trending/gumr/gumroad

本文围绕 Gumroad 开源仓库的 docs/users.md 展开，系统讲解开发环境预置的种子用户体系、团队角色（Team Roles）权限模型、内部管理员（Internal Admin）判定逻辑，以及非生产环境的双因素认证（2FA）调试技巧。读完本文，你将掌握如何用seller@gumroad.com等预置账号快速登录本地开发环境、如何借助不同团队角色测试店铺权限边界，以及000000万能验证码背后的源码原理。

一、种子用户总览：一条命令准备好整套测试账号

在 Gumroad 仓库中，运行bin/rails db:prepare即可完成数据库的创建、schema 迁移与数据填充（seeding）。该命令会通过 db/seeds.rb 加载公共种子，并按当前RAILS_ENV匹配加载环境专属种子目录（目录名以下划线分隔环境名，见 seeds.rb），最终播种出以下 5 个用户：

所有账号密码统一为password（种子脚本特意跳过校验写入这个"易被爆破但开发环境专用"的密码，见 01_users.rb）。这套账号体系同时服务于开发（development）与预发布（staging）环境，属于db/seeds/020_development_staging/目录。

提示：bin/rails db:prepare是幂等入口。种子脚本本身也做了幂等处理——例如 01_users.rb 先User.find_by(email:)查重，已存在则跳过创建。

二、Primary User：seller@gumroad.com的特殊身份

seller@gumroad.com是整个开发环境的"主用户"（Primary User），它同时具备以下四类特殊能力：

1. 内部管理员（Internal Admin）：可以访问/admin管理入口；
2. Payout 特权：拥有提现（Payout）相关操作权限；
3. Risk 特权：拥有风控（Risk）相关操作权限；
4. 服务类产品创建资格：账户年龄超过User::MIN_AGE_FOR_SERVICE_PRODUCTS，可创建服务类产品（Service Products）。

内部管理员判定：is_team_member?

在 01_users.rb 中，主用户被显式设置为seller.is_team_member = true。而/admin的访问控制正是基于该布尔字段实现的：管理员控制器 app/controllers/admin/base_controller.rb 中的require_admin!钩子会校验current_user.is_team_member?，非团队成员的请求会被重定向或返回 404（见 base_controller.rb）。

值得注意的是，该控制器注释说明原管理后台 Web UI 已移除，目前保留的是两个仍被其他页面引用的团队成员入口：用户模拟登录（impersonate）与 Stripe 后台跳转（见 base_controller.rb）。此外is_team_member?还广泛用于代码库各处的能力判定，例如商品列表的越权跳过逻辑（links_controller.rb）、用户模拟权限（impersonate.rb）、以及废弃购物车工作流与群发邮件资格的提前放行（user.rb、user.rb）。

服务类产品资格：MIN_AGE_FOR_SERVICE_PRODUCTS

文档指出主用户"有资格创建服务类产品"，其硬性前提是账户注册时间足够久。该阈值定义于 app/models/user.rb：

MIN_AGE_FOR_SERVICE_PRODUCTS = 30.days

对应的资格判定逻辑（user.rb）为：

Time.current - created_at > MIN_AGE_FOR_SERVICE_PRODUCTS

种子脚本为了让主用户天然满足该条件，直接把其created_at回拨为2 个月前（01_users.rb），同时预置了一笔状态为completed、金额 1000 美分的 PayPal 历史打款记录（01_users.rb），为后续测试提现、结算等流程做好准备。在测试环境中，这一资格同样通过回拨created_at的方式构造，例如 users.rb 工厂 使用User::MIN_AGE_FOR_SERVICE_PRODUCTS.ago - 1.day生成"刚好超过 30 天"的卖家。

Payout 与 Risk 特权

文档将 Payout 与 Risk 特权列为主用户的专属能力。从源码结构看，这两类能力与用户模型中的提现调度和风控状态机两大子系统强相关：User上挂着has_many :scheduled_payouts（user.rb），并以 JSON 属性持久化payout_threshold_cents、payout_frequency、payouts_paused_by等提现配置（user.rb）；同时维护一个以user_risk_state为核心的有限状态机（初始态为not_reviewed，user.rb），并提供compliant、not_suspended等作用域（user.rb）。主用户在种子脚本中设置了user_risk_state = "compliant"，这是其具备风险相关操作基础的前提。

三、Team Users：用团队角色测试店铺权限

其余 4 个用户（seller+admin、seller+marketing、seller+support、seller+accountant）用于在主用户店铺上测试特定团队角色。它们不是内部管理员，也不具备任何特殊权限——文档特别强调：seller+admin@gumroad.com是店铺管理员（store admin），而非内部管理员（internal admin）。这两个"admin"概念极易混淆，务必区分。

角色模型：TeamMembership::ROLES

团队角色由 app/models/team_membership.rb 建模，合法角色全集定义在 team_membership.rb：

ROLES = %w(owner accountant admin marketing support).freeze

代码通过元编程为每个角色动态生成role_<name>?谓词方法与role_<name>作用域（team_membership.rb）。种子脚本正是遍历TeamMembership::ROLES.excluding(TeamMembership::ROLE_OWNER)（01_users.rb），为除 owner 外的每个角色创建一个seller+<role>@gumroad.com用户，并建立其与主用户店铺之间的user_memberships关系（01_users.rb）。

角色的约束校验

TeamMembership上还有几条关键校验，理解它们有助于读懂种子脚本的写法：

• owner 角色只能分配给店铺的自然所有者（user == seller），且自然所有者的成员关系角色必须是 owner（team_membership.rb）；
• 非 owner 成员必须先有 owner 成员存在，否则校验失败（owner_membership_must_exist，team_membership.rb）。

因此种子脚本中先创建主用户seller@gumroad.com（其 Owner 成员关系通过create_owner_membership_if_needed!建立，见 01_users.rb），再为其他角色挂靠成员关系，顺序正好满足上述约束。

四、双因素认证（2FA）：非生产环境的万能验证码

所有非生产环境（development / staging / test）都接受000000作为双因素认证验证码。这意味着你在本地开发时，即使账号开启了 2FA，也无需查看邮件即可用000000直接登录。

该行为的核心实现在 app/models/concerns/two_factor_authentication.rb：

DEFAULT_AUTH_TOKEN = "000000" TOKEN_VALIDITY = 10.minutes TWO_FACTOR_AUTH_EXPIRY = 2.months

验证入口方法token_authenticated?的逻辑是（two_factor_authentication.rb）：

def token_authenticated?(authentication_token) return true if authenticate_otp(authentication_token, drift: TOKEN_VALIDITY).present? # Allow 000000 as valid authentication token in all non-production environments !Rails.env.production? && authentication_token == DEFAULT_AUTH_TOKEN end

可以看到两个要点：

1. 优先走标准 OTP 校验：authenticate_otp允许 10 分钟（TOKEN_VALIDITY）的漂移容差；
2. 兜底万能码：只要不是production环境，000000永远通过验证；而一旦切到生产环境，该分支短路返回false，000000立即失效——这正是文档强调"非生产环境"的原因，也是仓库在安全上的一道防线。

该模块还包含 2FA 的周边设施：每个用户对应一个不可猜测的 cookie 键（基于external_id加密后取 SHA-256 前 13 位，用于同一浏览器记住多账号的 2FA 状态，two_factor_authentication.rb）、TOTP（totp_credential）与 Passkey（webauthn_credentials）能力探测（two_factor_authentication.rb），以及通过TwoFactorAuthenticationMailer异步投递验证码邮件的send_authentication_token!（two_factor_authentication.rb）。

五、实战速查：从初始化到登录

将以上内容串成一条完整的本地开发上手链路：

1. 准备数据库：运行bin/rails db:prepare，自动播种上文 5 个用户；
2. 登录主用户：使用seller@gumroad.com/password登录，2FA 输入000000（官方 README 也确认了这组凭证与万能验证码）；
3. 体验内部管理员能力：主用户可访问/admin入口（受 Admin::BaseController#require_admin! 的is_team_member?校验保护），并可使用用户模拟登录功能；
4. 测试团队协作：分别用seller+admin、seller+marketing、seller+support、seller+accountant登录，验证不同团队角色在同一店铺上的权限差异（这些账号无内部管理后台访问权、无特殊权限）；
5. 测试服务类产品：主用户账户已"年满"30 天且带有历史打款记录，可直接创建服务类产品；测试代码中则常用created_at: User::MIN_AGE_FOR_SERVICE_PRODUCTS.ago - 1.day构造此类卖家（参考 users.rb 工厂 与 bundle_contents_controller_spec.rb）。

若需在 Windows（WSL）环境下搭建整套开发环境，可参考 docs/development/windows.md；更多环境与测试相关文档见 docs/OVERVIEW.md 与 docs/testing.md。

六、常见误区小结

• 两个 admin 不是一回事：seller+admin@gumroad.com只是店铺管理员角色（TeamMembership::ROLE_ADMIN），不能访问/admin；
• 000000不是生产环境万能钥匙：其有效性由!Rails.env.production?硬性约束，切勿在生产环境尝试；
• 主用户的"特权"来自种子数据而非魔法：内部管理员来自is_team_member = true，服务类产品资格来自被回拨的created_at与预置打款记录，团队角色则来自TeamMembership成员关系——理解这些底层字段，才能在写测试时正确构造所需用户。

【免费下载链接】gumroadSee what sticks项目地址: https://gitcode.com/GitHub_Trending/gumr/gumroad