NodeWarden 二次开发手册项目结构、数据库 Schema 演进与客户端兼容性避坑指南【免费下载链接】nodewardenBitwarden-compatible server running on Cloudflare Workers项目地址: https://gitcode.com/gh_mirrors/no/nodewardenNodeWarden 是一个运行在 Cloudflare Workers 上的 Bitwarden 兼容自托管密码管理服务可让官方 Bitwarden 客户端直连你自己的服务器。本文面向想二次开发或深度定制它的用户一次讲清三件事项目结构怎么读、数据库 Schema 怎么安全演进、以及客户端兼容性有哪些常见坑帮你少走弯路。 项目结构鸟瞰先看懂目录再动手NodeWarden 采用前后端同仓的组织方式服务端是 Cloudflare Workersrc/目录前端 Web Vault 是一个独立的 PWA 应用webapp/目录两者通过共享类型和 API 契约协作。目录职责二次开发时重点关注src/handlers/各业务 HTTP 处理器认证、保险库、Send、导入等新增/修改 API 行为src/services/存储层、限流、推送中继、备份等业务服务数据模型与业务规则src/static/全局等价域名表等静态数据自动填充规则定制src/router.ts路由入口理解请求分发webapp/src/Web Vault 前端Preact TailwindUI 与交互定制shared/前后端共享的常量与类型改契约必看migrations/D1 数据库初始 SchemaSchema 演进起点scripts/构建/校验/安全审计脚本回归测试入口两个新手容易踩的第一个坑存储模式是二选一的。默认使用 D1 数据库KV 模式需要显式执行npm run deploy:kv见 scripts/ensure-kv.cjs两种模式的本地调试命令也不同npm run dev与npm run dev:kv配置错会出现数据写入成功但读不到的灵异现象。️ 数据库 Schema双文件同步机制与演进四规则NodeWarden 的数据库 Schema 由两处共同定义这是二次开发最核心的约束部署态migrations/0001_init.sqlCloudflare D1 的 migrations运行态src/services/storage-schema.ts 中的SCHEMA_STATEMENTS每次请求启动时幂等执行文件头部注释把规则写得很直白migrations/0001_init.sql任何新表/新列/新索引必须两处同时添加。核心数据表速查表名作用users账户主体含 KDF 参数、2FA 密钥、API Keyciphers/folders保险库条目与文件夹sends安全共享Bitwarden Sendrefresh_tokens/devices登录会话与设备管理webauthn_credentials/webauthn_challengesPasskey 无密码登录auth_requests跨设备登录审批audit_logs审计日志Web 端日志中心的数据源invites邀请码注册多用户控制Schema 演进四规则避坑重点双文件同步改表结构时migrations/0001_init.sql和SCHEMA_STATEMENTS必须同时改只改一处会导致新旧安装行为不一致。升级版本标记修改后需提升 src/services/storage.ts 中的STORAGE_SCHEMA_VERSION已有安装会在检测到版本变化时自动重跑幂等建表语句无需手动迁移。语句必须幂等D1 可能在后续请求中重复执行这些语句所以一律使用CREATE ... IF NOT EXISTS且 storage-schema.ts 中的执行器会静默吞掉 already exists / duplicate column name 报错——这意味着建表语句里可以安全包含ALTER TABLE ADD COLUMN作为旧库补列。同步备份契约新表如果存持久数据必须同时更新备份导出/导入逻辑src/services/backup-archive.ts与src/services/backup-import.ts否则云端备份中心会静默丢失这部分数据。备份配置的共享契约定义在 shared/backup-schema.ts。⚠️ 反例有人只往migrations/0001_init.sql加了新表。结果是新部署有这张表老安装升级后没有备份导入直接报错。 客户端兼容性三个最常见的坑NodeWarden 的价值在于让官方 Bitwarden 客户端无感接入但客户端对服务端有严格的契约要求二次开发时最容易在这里翻车。坑一/config 端点的 featureStates 开关客户端启动时会拉取/config其中的featureStates决定哪些新特性被启用。该响应由 src/config-response.ts 构建版本号来自 src/config/limits.ts 中的LIMITS.compatibility配置。正确姿势改动兼容性行为前先运行回归测试 scripts/config-compatibility.test.ts它会断言featureStates[desktop-ui-settings-dialog]等关键开关与environment字段结构不变——这个测试就是为防止兼容契约被无意破坏而存在的。坑二刷新令牌的滑动 绝对上限语义Bitwarden 桌面端对刷新令牌的行为假设非常具体桌面 Web 会话是 30 天滑动续期移动端 90 天滑动且所有会话共享 365 天绝对上限见 src/config/limits.ts。refresh_tokens表因此设计了expires_at滑动过期与absolute_expires_at硬上限双字段且 storage-schema.ts 内置了历史数据回填语句。正确姿势如果你自定义了令牌生命周期务必同时维护这两个字段并且保持绝对上限不可被滑动续期突破的语义否则桌面端会出现偶发掉线。坑三客户端支持矩阵并非全绿官方 README 明确标注了已验证客户端README.md客户端状态Windows 桌面 / Linux 桌面✅ 已验证移动端 / 浏览器扩展✅ 已验证macOS 桌面⚠️ 尚未完全验证如果你在 macOS 上遇到问题先怀疑客户端差异而不是急着改代码。另外提醒一句项目免责声明README.md本项目仅供学习交流请定期备份你的保险库——这也是内置云端备份中心WebDAV/S3 增量备份存在的原因。 二次开发入口速查改 API从 src/router.ts 找到路由 → 定位 src/handlers/ 对应处理器 → 存储逻辑在 src/services/ 的storage-*-repo.ts仓储文件。改前端页面组件在 webapp/src/components/API 封装在 webapp/src/lib/api/多语言词条在 webapp/src/lib/i18n/locales/改文案记得跑npm run i18n:validate。改表结构记住双文件 版本标记 幂等 备份契约四件套。安全相关scripts/下有一组安全审计脚本如 security-audit-backup-endpoint.mjs改动敏感接口后可作为自检参考。掌握以上三块——结构怎么读、Schema 怎么演进、兼容性怎么守住——你就具备了在 NodeWarden 上做安全二次开发的完整地图。建议先从跑通npm run dev本地环境开始再对照 README_ZH.md 逐步深入。【免费下载链接】nodewardenBitwarden-compatible server running on Cloudflare Workers项目地址: https://gitcode.com/gh_mirrors/no/nodewarden创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 NodeWarden 二次开发手册：项目结构、数据库 Schema 演进与客户端兼容性避坑指南
NodeWarden 二次开发手册项目结构、数据库 Schema 演进与客户端兼容性避坑指南【免费下载链接】nodewardenBitwarden-compatible server running on Cloudflare Workers项目地址: https://gitcode.com/gh_mirrors/no/nodewardenNodeWarden 是一个运行在 Cloudflare Workers 上的 Bitwarden 兼容自托管密码管理服务可让官方 Bitwarden 客户端直连你自己的服务器。本文面向想二次开发或深度定制它的用户一次讲清三件事项目结构怎么读、数据库 Schema 怎么安全演进、以及客户端兼容性有哪些常见坑帮你少走弯路。 项目结构鸟瞰先看懂目录再动手NodeWarden 采用前后端同仓的组织方式服务端是 Cloudflare Workersrc/目录前端 Web Vault 是一个独立的 PWA 应用webapp/目录两者通过共享类型和 API 契约协作。目录职责二次开发时重点关注src/handlers/各业务 HTTP 处理器认证、保险库、Send、导入等新增/修改 API 行为src/services/存储层、限流、推送中继、备份等业务服务数据模型与业务规则src/static/全局等价域名表等静态数据自动填充规则定制src/router.ts路由入口理解请求分发webapp/src/Web Vault 前端Preact TailwindUI 与交互定制shared/前后端共享的常量与类型改契约必看migrations/D1 数据库初始 SchemaSchema 演进起点scripts/构建/校验/安全审计脚本回归测试入口两个新手容易踩的第一个坑存储模式是二选一的。默认使用 D1 数据库KV 模式需要显式执行npm run deploy:kv见 scripts/ensure-kv.cjs两种模式的本地调试命令也不同npm run dev与npm run dev:kv配置错会出现数据写入成功但读不到的灵异现象。️ 数据库 Schema双文件同步机制与演进四规则NodeWarden 的数据库 Schema 由两处共同定义这是二次开发最核心的约束部署态migrations/0001_init.sqlCloudflare D1 的 migrations运行态src/services/storage-schema.ts 中的SCHEMA_STATEMENTS每次请求启动时幂等执行文件头部注释把规则写得很直白migrations/0001_init.sql任何新表/新列/新索引必须两处同时添加。核心数据表速查表名作用users账户主体含 KDF 参数、2FA 密钥、API Keyciphers/folders保险库条目与文件夹sends安全共享Bitwarden Sendrefresh_tokens/devices登录会话与设备管理webauthn_credentials/webauthn_challengesPasskey 无密码登录auth_requests跨设备登录审批audit_logs审计日志Web 端日志中心的数据源invites邀请码注册多用户控制Schema 演进四规则避坑重点双文件同步改表结构时migrations/0001_init.sql和SCHEMA_STATEMENTS必须同时改只改一处会导致新旧安装行为不一致。升级版本标记修改后需提升 src/services/storage.ts 中的STORAGE_SCHEMA_VERSION已有安装会在检测到版本变化时自动重跑幂等建表语句无需手动迁移。语句必须幂等D1 可能在后续请求中重复执行这些语句所以一律使用CREATE ... IF NOT EXISTS且 storage-schema.ts 中的执行器会静默吞掉 already exists / duplicate column name 报错——这意味着建表语句里可以安全包含ALTER TABLE ADD COLUMN作为旧库补列。同步备份契约新表如果存持久数据必须同时更新备份导出/导入逻辑src/services/backup-archive.ts与src/services/backup-import.ts否则云端备份中心会静默丢失这部分数据。备份配置的共享契约定义在 shared/backup-schema.ts。⚠️ 反例有人只往migrations/0001_init.sql加了新表。结果是新部署有这张表老安装升级后没有备份导入直接报错。 客户端兼容性三个最常见的坑NodeWarden 的价值在于让官方 Bitwarden 客户端无感接入但客户端对服务端有严格的契约要求二次开发时最容易在这里翻车。坑一/config 端点的 featureStates 开关客户端启动时会拉取/config其中的featureStates决定哪些新特性被启用。该响应由 src/config-response.ts 构建版本号来自 src/config/limits.ts 中的LIMITS.compatibility配置。正确姿势改动兼容性行为前先运行回归测试 scripts/config-compatibility.test.ts它会断言featureStates[desktop-ui-settings-dialog]等关键开关与environment字段结构不变——这个测试就是为防止兼容契约被无意破坏而存在的。坑二刷新令牌的滑动 绝对上限语义Bitwarden 桌面端对刷新令牌的行为假设非常具体桌面 Web 会话是 30 天滑动续期移动端 90 天滑动且所有会话共享 365 天绝对上限见 src/config/limits.ts。refresh_tokens表因此设计了expires_at滑动过期与absolute_expires_at硬上限双字段且 storage-schema.ts 内置了历史数据回填语句。正确姿势如果你自定义了令牌生命周期务必同时维护这两个字段并且保持绝对上限不可被滑动续期突破的语义否则桌面端会出现偶发掉线。坑三客户端支持矩阵并非全绿官方 README 明确标注了已验证客户端README.md客户端状态Windows 桌面 / Linux 桌面✅ 已验证移动端 / 浏览器扩展✅ 已验证macOS 桌面⚠️ 尚未完全验证如果你在 macOS 上遇到问题先怀疑客户端差异而不是急着改代码。另外提醒一句项目免责声明README.md本项目仅供学习交流请定期备份你的保险库——这也是内置云端备份中心WebDAV/S3 增量备份存在的原因。 二次开发入口速查改 API从 src/router.ts 找到路由 → 定位 src/handlers/ 对应处理器 → 存储逻辑在 src/services/ 的storage-*-repo.ts仓储文件。改前端页面组件在 webapp/src/components/API 封装在 webapp/src/lib/api/多语言词条在 webapp/src/lib/i18n/locales/改文案记得跑npm run i18n:validate。改表结构记住双文件 版本标记 幂等 备份契约四件套。安全相关scripts/下有一组安全审计脚本如 security-audit-backup-endpoint.mjs改动敏感接口后可作为自检参考。掌握以上三块——结构怎么读、Schema 怎么演进、兼容性怎么守住——你就具备了在 NodeWarden 上做安全二次开发的完整地图。建议先从跑通npm run dev本地环境开始再对照 README_ZH.md 逐步深入。【免费下载链接】nodewardenBitwarden-compatible server running on Cloudflare Workers项目地址: https://gitcode.com/gh_mirrors/no/nodewarden创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考