Bitwarden Server Seeder 实战：用 dev.playground 预设从零构建可登录、含真实业务数据的开发数据库

Bitwarden Server Seeder 实战：用 dev.playground 预设从零构建可登录、含真实业务数据的开发数据库

【免费下载链接】serverBitwarden infrastructure/backend (API, database, Docker, etc).项目地址: https://gitcode.com/GitHub_Trending/ser/server

当你的 Bitwarden 开发数据库被清空或全新初始化后，直接对着空库调试登录、组织权限和 Vault 体验既低效又缺乏真实感。本文基于仓库中的场景文档 fresh-database.md 展开，讲清如何用一条dotnet run -- preset --name dev.playground命令，通过 SeederUtility 向本地数据库注入一个企业版组织：四个以角色命名的可记忆登录账号、十二个带真实职衔的团队成员、精心设计的 Collection 权限组合以及二十一条贴近生产形态的保险库条目，读完即可掌握本地开发基线数据的一键搭建、预设文件结构剖析与常用变体命令。

适用场景：你需要一个能登录、有真实数据的数据库

该场景文档针对的痛点非常直白："Just wiped my DB, new to the team, or starting fresh. I need something to log into."（刚清库、新入职团队，或者想从头开始，需要能登录的东西。）它面向三类人：新加入团队的工程师、刚重置过本地环境的开发者、以及任何想要一个干净基线来开始工作的场景。

在 Bitwarden server 仓库中，这一需求由 Seeder 体系解决。Seeder 场景索引 中有一句重要提示：

Seeder 直接写数据库，只应对本地开发数据库运行。

所有 Seeder 命令都在util/SeederUtility/目录下执行，所有被播种的用户默认密码为asdfasdfasdf（可用--password覆盖）。CLI 参数全集见 SeederUtility README。

快速开始：一条命令播种

在util/SeederUtility/目录下执行：

dotnet run -- preset --name dev.playground

这条命令加载名为dev.playground的内置预设（preset），把一套经过人工设计的组织数据写入当前连接的数据库。几个要点：

• 跳过--mangle：场景文档明确建议这里不要使用--mangle。--mangle会随机化 ID、邮箱和标识符以隔离测试，避免重复运行冲突，但代价是登录邮箱变得不可记忆。dev.playground预设的核心价值恰恰在于"登录名即角色"，保持可记忆是这个预设的设计意图。
• 无需 Azurite：该预设不包含任何附件（attachment）数据，因此不需要配置本地 Azure Blob 存储模拟（Azurite）或其他对象存储即可完整运行。
• 默认即仓库内置种子：这正是dev/seed.ps1的默认播种内容之一（见下文"与 dev/seed.ps1 的关系"一节）。

播种后你能得到什么

运行完成后，数据库中会出现一个企业版组织Dev Org（域名bw.example，来自 dev-org.json），其登录账号与可见数据如下。

四个角色账号：登录名即角色

预设使用 roster 中的email字段覆盖，让四个管理角色拥有可预测的登录邮箱。四个账号密码均为asdfasdfasdf（除非--password覆盖），每个角色登录看到的是有意不同的 Vault 视图：

登录邮箱	角色	登录后看到的内容
[e-mail]	Owner	一切内容——对每个 Collection 都有直接 Can Manage 权限
[e-mail]	Admin	Company-Wide、Break Glass，外加两个只读的 Leadership 视图（CI & Releases、Vendors & Contracts）
[e-mail]	Custom	Company-Wide、CI & Releases（只读）、Finance（只读且隐藏密码）
[e-mail]	User	Company-Wide 加 Engineering 系列 Collection，并带有个人文件夹与收藏

这正是"deliberate permission mix"（刻意的权限组合）的体现：权限不是全放开，也不是全锁死，而是按 Bitwarden 真实的权限模型（管理/只读/隐藏密码）分层铺设，使得切换四个账号登录就能直观感受不同角色下的 Vault 差异。

八位真实感同事与分组结构

除四个角色账号外，dev-roles roster 还定义了八位"production-realistic colleagues"，每位都有姓名、角色（user）与职衔：

姓名	职衔	所属分组
Elena Vasquez	Engineering Lead	Everyone、Engineering、Leadership
Marcus Webb	Site Reliability Engineer	Everyone、Engineering
Priya Sharma	Backend Engineer	Everyone、Engineering
Tom Okafor	Frontend Engineer	Everyone、Engineering
Ingrid Larsen	Finance Director	Everyone、Finance、Leadership
Diego Fuentes	Accountant	Everyone、Finance
Hana Kobayashi	People Operations Manager	Everyone、People Ops
Sam Whitaker	Recruiter	Everyone、People Ops

场景文档说这八位同事分布在"四个 group"中；从 dev-roles.json 的源码看，roster 实际定义了 5 个 group：Everyone（全部 12 人）、Engineering（5 人）、Finance（2 人）、People Ops（2 人）、Leadership（owner、admin 及两位业务负责人）。八位同事覆盖其中 Everyone / Engineering / Finance / People Ops 四组，Leadership 组主要用于承载权限实验。

Collection 权限矩阵

dev-roles 定义了 8 个 Collection，每个 Collection 通过groups/users两个维度的manage、readOnly、hidePasswords标记组合出不同权限。这是权限测试的核心资产，摘录几个典型配置：

• Company-Wide：Everyone 组全员可见，owner 可管理；
• Engineering与Engineering/Cloud Infrastructure：Engineering 组可见，owner 与 Engineering Lead（elena.vasquez）可管理；
• Engineering/CI & Releases：Engineering 组可访问，Leadership 组只读，casey.custom只读——这是 admin/custom 账号"只读 Leadership 视图"的来源；
• Finance：Finance 组可管理，casey.custom只读且hidePasswords: true（隐藏密码）；
• Leadership/Break Glass：没有绑定任何 group，仅 owner 可管理、admin 可访问，是典型的"破窗（break glass）"应急凭据隔离设计。

二十一条贴近生产的保险库条目

ciphers 夹具 dev-playground.json 提供了 21 条条目，覆盖 Bitwarden 的主要条目类型，且细节刻意贴近真实团队：

• Login（13 条）：GitHub（含 TOTP）、Docker Hub、npm Registry、Figma、AWS IAM - Developer（含 TOTP）、PgAdmin (Production)、Datadog、Stripe Dashboard（含 TOTP）、Xero、BambooHR、Slack、Google Workspace Admin（含 TOTP）、AWS Console (Root)（含 TOTP）。部分 Login 标注cipherEncryption: "cipherKey"（如 Figma、PgAdmin、AWS Root），即使用 cipher-key 加密模式写入，用于验证两种加密路径；
• Secure Note（5 条）：Office Wi-Fi、Office Door Codes（含季度轮换说明）、Incident Response Runbook、Release Signing Checklist、Onboarding Checklist——这些笔记内容甚至与其他 Collection 的权限设计互相呼应（如 Onboarding Checklist 提到"加入正确的 group"）；
• Card（1 条）：Corporate Amex，持卡人 DEV ORG LLC；
• Identity（1 条）：Office Shipping Profile，完整的公司收货地址；
• SSH Key（1 条）：Deploy Key - prod-web-01，带伪造的 OPENSSH 私钥/公钥与指纹。

条目中的"密码"、token、密钥均为明确的假数据（如ghp_FakeSeederToken4DevOrg2026、FAKE-EXAMPLE-NOT-A-REAL-KEY），仅用于本地开发体验。

预设文件的结构剖析：playground.json 如何组装数据

dev.playground的完整定义在 util/Seeder/Seeds/fixtures/presets/dev/playground.json，它引用了三个夹具并叠加三类分配关系：

{ "$schema": "../../../schemas/preset.schema.json", "organization": { "fixture": "dev-org", "planType": "enterprise-annually", "seats": 20, "allowAdminAccessToAllCollectionItems": false }, "roster": { "fixture": "dev-roles" }, "ciphers": { "fixture": "dev-playground" }, "collectionAssignments": [ ... 21 条 cipher→collection 映射 ... ], "folderAssignments": [ ... 5 条 用户文件夹映射 ... ], "favoriteAssignments": [ ... 4 条 用户收藏映射 ... ] }

各部分含义：

1. organization：fixture: "dev-org"指向上文组织夹具；planType: "enterprise-annually"声明企业年付计划（schema 支持的枚举值还包括teams-monthly、teams-annually、families-annually等，见 preset.schema.json）；seats: 20给组织 20 个席位；allowAdminAccessToAllCollectionItems: false显式关闭"管理员可访问全部 Collection 条目"的组织选项——这保证了权限矩阵必须靠显式授权生效，而不是被组织级开关兜底绕过，这也是四个角色看到不同 Vault 的前提。
2. roster/ciphers：分别引用 roster 夹具与 cipher 夹具，保证每次播种出的成员、分组、条目完全确定、可复现（preset 的定位就是"same data every time"，与生成式数据相对，见 presets.md）。
3. collectionAssignments：21 条条目逐一指派到 8 个 Collection（含两级路径如Engineering/Cloud Infrastructure、Finance/Vendors & Contracts、Leadership/Break Glass），例如AWS Console (Root)与Google Workspace Admin都落在 Break Glass 中，Office Wi-Fi等落入 Company-Wide。
4. folderAssignments：为特定用户创建个人文件夹。例如uma.user把 GitHub、Figma 放进 Work 文件夹，npm Registry 放进 Personal Projects；owen.owner为两个破窗凭据建立 Break Glass 文件夹。
5. favoriteAssignments：为四个用户标记收藏（uma.user收藏 GitHub 和 Office Wi-Fi、owen.owner收藏 AWS Root、ingrid.larsen收藏 Stripe Dashboard），让每个角色登录后的首页体验各不相同。

这些字段均受 preset.schema.json 约束：schema 要求预设二选一包含organization或user，并严格限定additionalProperties: false，即预设文件不允许出现未定义的字段——这也是仓库内所有预设文件格式统一的依据。

CLI 侧，preset命令的参数定义在 PresetArgs.cs，与本文相关的开关有：

• --list：列出全部可用预设；
• --name：预设名；
• --mangle：启用 ID/邮箱随机化以隔离测试；
• --password：全部账号密码，默认asdfasdfasdf；
• --owner-email/--org-name：覆盖 owner 登录邮箱与组织显示名（均可与--mangle组合）。

PresetArgs.cs中对 owner-email 的注释值得注意："Must not already exist in the User table; add--mangleto make repeat runs unique." 由此可以推断：不带--mangle重复运行dev.playground时，若[e-mail]等邮箱已存在，运行将不会成功——这正是该场景文档默认前提为"刚清库/全新环境"的原因；若需要多次播种同一预设做隔离测试，应改用带--mangle的其他预设（见变体表）。

与 dev/seed.ps1 的关系：仓库的默认本地种子

场景文档提到 "This is whatdev/seed.ps1seeds by default."。dev/seed.ps1 是仓库为本地开发提供的批量播种脚本，其工作机制：

1. 读取 dev/seeds.json（数组形式的种子清单），若存在本地seeds.local.json则追加其条目；
2. 将每条条目的args按 PascalCase→kebab-case 规则转换成 CLI 参数；
3. 逐条执行dotnet run --project util/SeederUtility -- <command> <args>，任一条失败即中断并返回其退出码；
4. 支持-DryRun开关：只打印将要执行的命令而不真正执行。

seeds.json当前包含三条种子：

[ { "label": "Jane Doe Free (individual, free)", "command": "individual", "args": { "subscription": "free", "firstName": "Jane", "lastName": "Doe", "email": "[e-mail]" } }, { "label": "John Doe (individual, premium)", "command": "individual", "args": { "subscription": "premium", "firstName": "John", "lastName": "Doe", "email": "[e-mail]" } }, { "label": "Dev Playground (dev.playground preset)", "command": "preset", "args": { "name": "dev.playground" } } ]

即：一个 Free 个人账号、一个 Premium 个人账号，加上本文主角dev.playground组织预设。因此在本地按标准流程启动开发环境（dev/下的 docker-compose 等）后运行./seed.ps1，数据库会自动获得上述基线数据；也可以单独执行第三条目等价的手动命令dotnet run -- preset --name dev.playground。

变体：同一需求下的其他预设

场景文档给出的变体表完整继承如下，均可在util/SeederUtility/下执行：

场景	命令
附件覆盖测试（需要 Azurite）	dotnet run -- preset --name qa.enterprise-basic --mangle
更大规模组织（58 用户、14 分组）	dotnet run -- preset --name qa.dunder-mifflin-enterprise-full --mangle
Families 计划	dotnet run -- preset --name qa.families-basic --mangle
Free 计划个人 Vault	dotnet run -- preset --name qa.stark-free-basic --mangle
只要个人用户、不要组织	dotnet run -- individual --subscription premium --first-name Jane --last-name Smith --vault

这些变体与dev.playground的区别在于：QA 预设普遍携带附件数据（因此需要 Azurite 或本地附件目录），且都建议使用--mangle以便重复播种互不冲突；individual命令则完全跳过组织，创建一个带个人 Vault（约 75 条生成式条目、5 个文件夹）的高级订阅用户，邮箱规则为{first}.{last}@individual.example（见 SeederUtility README）。如需浏览完整预设目录（Developer / Features / QA / Scale / Individual / Validation 六大类），见 presets.md。

验证与注意事项

• 登录验证：用[e-mail]/asdfasdfasdf登录应看到全部 8 个 Collection；换成[e-mail]登录，Finance 条目密码应不可见，Leadership 视图只读——这是最直接的权限行为验证方式。
• 运行边界：Seeder 直写数据库，务必只指向本地开发库；命令在util/SeederUtility/下以dotnet run执行，前置是dotnet build成功且连接串指向目标库。
• 重复运行：dev.playground不含--mangle，邮箱固定，重复运行依赖"库中无同名邮箱"的前提；若需反复播种同一形状的组织，选择带--mangle的 QA/Scale 预设。
• 数据位置：本文引用的预设与夹具全部位于util/Seeder/Seeds/下（fixtures/presets/dev/、fixtures/rosters/、fixtures/organizations/、fixtures/ciphers/），格式契约在util/Seeder/Seeds/schemas/中，可作为自定义预设时的模板。

综上，dev.playground预设以极低的命令成本（一行）交付了一个结构完整、权限分层、可逐个角色体验的 Bitwarden 开发基线：组织（20 席位企业年付）+ 12 名成员 + 5 个分组 + 8 个带权限标记的 Collection + 21 条多类型保险库条目，且刻意排除附件依赖，是清空数据库或新环境搭建后的首选播种方案。

【免费下载链接】serverBitwarden infrastructure/backend (API, database, Docker, etc).项目地址: https://gitcode.com/GitHub_Trending/ser/server