feat: update README files for clarity and consistency in descriptions

This commit is contained in:
shuaiplus
2026-03-20 06:47:25 +08:00
parent a17ed646a0
commit 98e94e766f
2 changed files with 135 additions and 118 deletions
+63 -54
View File
@@ -3,7 +3,7 @@
</p> </p>
<p align="center"> <p align="center">
运行在 Cloudflare Workers Bitwarden 第三方服务端,兼容官方客户端 运行在 Cloudflare Workers 上的第三方 Bitwarden 兼容服务端。
</p> </p>
[![Powered by Cloudflare](https://img.shields.io/badge/Powered%20by-Cloudflare-F38020?logo=cloudflare&logoColor=white)](https://workers.cloudflare.com/) [![Powered by Cloudflare](https://img.shields.io/badge/Powered%20by-Cloudflare-F38020?logo=cloudflare&logoColor=white)](https://workers.cloudflare.com/)
@@ -11,51 +11,50 @@
[![Latest Release](https://img.shields.io/github/v/release/shuaiplus/NodeWarden?display_name=tag)](https://github.com/shuaiplus/NodeWarden/releases/latest) [![Latest Release](https://img.shields.io/github/v/release/shuaiplus/NodeWarden?display_name=tag)](https://github.com/shuaiplus/NodeWarden/releases/latest)
[![Sync Upstream](https://github.com/shuaiplus/NodeWarden/actions/workflows/sync-upstream.yml/badge.svg)](https://github.com/shuaiplus/NodeWarden/actions/workflows/sync-upstream.yml) [![Sync Upstream](https://github.com/shuaiplus/NodeWarden/actions/workflows/sync-upstream.yml/badge.svg)](https://github.com/shuaiplus/NodeWarden/actions/workflows/sync-upstream.yml)
[更新日志](./RELEASE_NOTES.md) [提交问题](https://github.com/shuaiplus/NodeWarden/issues/new/choose) [最新发布](https://github.com/shuaiplus/NodeWarden/releases/latest) [更新日志](./RELEASE_NOTES.md) | [提交问题](https://github.com/shuaiplus/NodeWarden/issues/new/choose) | [最新发布](https://github.com/shuaiplus/NodeWarden/releases/latest)
English[`README_EN.md`](./README_EN.md)
English: [`README_EN.md`](./README_EN.md)
> **免责声明** > **免责声明**
> 本项目仅供学习交流使用。我们不对任何数据丢失负责,强烈建议定期备份的密码库。 > 本项目仅供学习交流使用,请定期备份的密码库。
> 本项目与 Bitwarden 官方无关,请向 Bitwarden 官方反馈问题。 > 本项目与 Bitwarden 官方无关,请不要向 Bitwarden 官方反馈 NodeWarden 的问题。
--- ---
## 与 Bitwarden 官方服务端能力对比 ## 与 Bitwarden 官方服务端能力对比
| 能力 | Bitwarden | NodeWarden | 说明 | | 能力 | Bitwarden | NodeWarden | 说明 |
|---|---|---|---| |---|---|---|---|
| Web Vault(登录/笔记/卡片/身份) | ✅ | ✅ | 网页端密码库管理页面 | | 网页密码库 | ✅ | ✅ | **原创Web Vault界面** |
| 文件夹 / 收藏 | ✅ | ✅ | 常用管理能力可用 | | 全量同步 `/api/sync` | ✅ | ✅ | 已针对官方客户端做兼容优化 |
| 全量同步 `/api/sync` | ✅ | ✅ | 已做兼容与性能优化 | | 附件上传 / 下载 | ✅ | ✅ | Cloudflare R2 或 KV |
| 附件上传/下载 | ✅ | ✅ | Cloudflare R2 和 KV 二选一 | | Send | ✅ | ✅ | 支持文本与文件 Send |
| 导入导出功能 | ✅ | ✅ | 完整实现,含 Bitwarden 密码库+附件 ZIP 导入 | | 导入 / 导出 | ✅ | ✅ | 支持 Bitwarden JSON / CSV / **ZIP 导入(包括附件)** |
| 网站图标代理 | | ✅ | 通过 `/icons/{hostname}/icon.png` | | **云端备份中心** | | ✅ | 支持 WebDAV / E3 定时备份 |
| passkey、TOTP 字段 | ✅ | ✅ | 完全支持,无需高级版 | | 密码提示(网页端) | ⚠️ 有限 | ✅ | 支持注册、登录辅助、解锁、设置 |
| Send | ✅ | ✅ | Cloudflare R2 和 KV 二选一 | | TOTP / Steam TOTP | ✅ | ✅ | 含 `steam://` 支持 |
| 多用户 | ✅ | ✅ | 完整的用户管理,邀请机制 | | 多用户 | ✅ | ✅ | 支持邀请码注册 |
| 组织/集合/成员权限 | ✅ | ❌ | 没必要实现 | | 组织 / 集合 / 成员权限 | ✅ | ❌ | 实现 |
| 登录 2FATOTP/WebAuthn/Duo/Email | ✅ | ⚠️ 部分支持 | 仅支持用户级 TOTP | | 登录 2FA | ✅ | ⚠️ 部分支持 | 当前仅支持用户级 TOTP |
| SSO / SCIM / 企业目录 | ✅ | ❌ | 没必要实现 | | SSO / SCIM / 企业目录 | ✅ | ❌ | 实现 |
| 紧急访问 | ✅ | ❌ | 没必要实现 |
| 管理后台 / 计费订阅 | ✅ | ❌ | 纯免费 |
| 推送通知完整链路 | ✅ | ❌ | 没必要实现 |
## 测试情况:
- ✅ Windows 客户端(v2026.1.0
- ✅ 手机 Appv2026.1.0
- ✅ 浏览器扩展(v2026.1.0
- ✅ Linux 客户端(v2026.1.0
- ⬜ macOS 客户端(未测试)
--- ---
## 已测试客户端
- ✅ Windows 桌面端
- ✅ 手机 App
- ✅ 浏览器扩展
- ✅ Linux 桌面端
- ⚠️ macOS 桌面端尚未完整验证
---
## 网页部署 ## 网页部署
1. Fork 本仓库。若本项目对你有帮助,欢迎点个 Star。 1. Fork 本仓库。若本项目对你有帮助,欢迎点个 Star。
2. 打开 [Workers](https://dash.cloudflare.com/?to=/:account/workers-and-pages/create) ➜ `Continue with GitHub` ➜ 选择你 Fork 后的仓库(`NodeWarden`)➜ 下一步 ➜ (默认使用 R2 存储;若未开通,可切换为 KV,并将部署命令改为 `npm run deploy:kv`)➜ 部署 ➜ 打开生成的链接 2. 打开 [Workers](https://dash.cloudflare.com/?to=/:account/workers-and-pages/create) ➜ `Continue with GitHub` ➜ 选择你 Fork 后的仓库(`NodeWarden`)➜ 下一步 ➜ (默认使用 R2 存储;若未开通,可用 KV 来代替,将**部署命令**改为 `npm run deploy:kv`)➜ 部署 ➜ 打开生成的链接
| 储存 | 是否需绑卡 | 单个附件/Send文件上限 | 免费额度 | | 储存 | 是否需绑卡 | 单个附件/Send文件上限 | 免费额度 |
|---|---|---|---| |---|---|---|---|
@@ -72,51 +71,60 @@ English[`README_EN.md`](./README_EN.md)
## CLI 部署 ## CLI 部署
```powershell ```powershell
# 先把仓库拉到本地
git clone https://github.com/shuaiplus/NodeWarden.git git clone https://github.com/shuaiplus/NodeWarden.git
cd NodeWarden cd NodeWarden
# 安装依赖
npm install npm install
# Cloudflare CLI 登录
npx wrangler login npx wrangler login
# 部署到 Cloudflare # 默认:R2 模式
npm run deploy npm run deploy
# 可选KV 模式(无 R2 / 无信用卡) # 可选KV 模式
npm run deploy:kv npm run deploy:kv
# 本地开发 # 本地开发
npm run dev npm run dev
npm run dev:kv npm run dev:kv
# 后续更新时重新拉取仓库并重新部署即可,无需重复创建云资源
git clone https://github.com/shuaiplus/NodeWarden.git
cd NodeWarden
npm run deploy
``` ```
---
## 云端备份说明
- 远程备份支持 **WebDAV****E3**
- 勾选“包含附件”后:
- ZIP 内仍只包含 `db.json``manifest.json`
- 真实附件单独存放在 `attachments/`
- 后续备份会按稳定 blob 名复用已有附件,不会每次全量重传
- 远程还原时:
- 会从 `attachments/` 目录按需读取附件
- 缺失的附件会被安全跳过
- 被跳过的附件不会在恢复后的数据库中留下脏记录
--- ---
## 常见问题
**Q: 如何备份数据?** ## 导入 / 导出
A: 在客户端中选择「导出密码库」,保存 JSON 文件。
**Q: 导入导出支持哪些格式?** 当前支持的导入来源包括:
A: 支持 Bitwarden `json/csv/密码库+附件 zip` 和 NodeWarden `密码库+附件 json`(均含加密模式),且导入下拉中看到的格式都可直接导入。
A: 另外还支持直接导入 Bitwarden `密码库+附件 zip`,这条路径官方 Bitwarden Web 暂不支持。
**Q: 忘记主密码怎么办?** - Bitwarden JSON
A: 无法恢复,这是端到端加密的特性。建议妥善保管主密码。 - Bitwarden CSV
- Bitwarden 密码库 + 附件 ZIP
- NodeWarden JSON
- 网页导入器里可见的多种浏览器 / 密码管理器格式
**Q: 可以多人使用吗?** 当前支持的导出方式包括:
A: 支持。第一个注册的用户会自动成为管理员;管理员可在管理页面生成邀请码,其他用户凭邀请码注册。
- Bitwarden JSON
- Bitwarden 加密 JSON
- 带附件的 ZIP 导出
- NodeWarden JSON 系列
- 备份中心中的实例级完整手动导出
--- ---
## 开源协议 ## 开源协议
LGPL-3.0 License LGPL-3.0 License
@@ -125,11 +133,12 @@ LGPL-3.0 License
## 致谢 ## 致谢
- [Bitwarden](https://bitwarden.com/) - 原始设计客户端 - [Bitwarden](https://bitwarden.com/) - 原始设计客户端
- [Vaultwarden](https://github.com/dani-garcia/vaultwarden) - 服务实现参考 - [Vaultwarden](https://github.com/dani-garcia/vaultwarden) - 服务实现参考
- [Cloudflare Workers](https://workers.cloudflare.com/) - 无服务器平台 - [Cloudflare Workers](https://workers.cloudflare.com/) - 无服务器平台
--- ---
## Star History ## Star History
[![Star History Chart](https://api.star-history.com/svg?repos=shuaiplus/NodeWarden&type=timeline&legend=top-left)](https://www.star-history.com/#shuaiplus/NodeWarden&type=timeline&legend=top-left) [![Star History Chart](https://api.star-history.com/svg?repos=shuaiplus/NodeWarden&type=timeline&legend=top-left)](https://www.star-history.com/#shuaiplus/NodeWarden&type=timeline&legend=top-left)
+72 -64
View File
@@ -3,7 +3,7 @@
</p> </p>
<p align="center"> <p align="center">
A third-party Bitwarden server running on Cloudflare Workers, fully compatible with official clients. A third-party Bitwarden-compatible server running on Cloudflare Workers.
</p> </p>
[![Powered by Cloudflare](https://img.shields.io/badge/Powered%20by-Cloudflare-F38020?logo=cloudflare&logoColor=white)](https://workers.cloudflare.com/) [![Powered by Cloudflare](https://img.shields.io/badge/Powered%20by-Cloudflare-F38020?logo=cloudflare&logoColor=white)](https://workers.cloudflare.com/)
@@ -11,105 +11,114 @@
[![Latest Release](https://img.shields.io/github/v/release/shuaiplus/NodeWarden?display_name=tag)](https://github.com/shuaiplus/NodeWarden/releases/latest) [![Latest Release](https://img.shields.io/github/v/release/shuaiplus/NodeWarden?display_name=tag)](https://github.com/shuaiplus/NodeWarden/releases/latest)
[![Sync Upstream](https://github.com/shuaiplus/NodeWarden/actions/workflows/sync-upstream.yml/badge.svg)](https://github.com/shuaiplus/NodeWarden/actions/workflows/sync-upstream.yml) [![Sync Upstream](https://github.com/shuaiplus/NodeWarden/actions/workflows/sync-upstream.yml/badge.svg)](https://github.com/shuaiplus/NodeWarden/actions/workflows/sync-upstream.yml)
[Release Notes](./RELEASE_NOTES.md) [Report an Issue](https://github.com/shuaiplus/NodeWarden/issues/new/choose) [Latest Release](https://github.com/shuaiplus/NodeWarden/releases/latest) [Release Notes](./RELEASE_NOTES.md) | [Report an Issue](https://github.com/shuaiplus/NodeWarden/issues/new/choose) | [Latest Release](https://github.com/shuaiplus/NodeWarden/releases/latest)
中文文档:[`README.md`](./README.md) English: [`README.md`](./README.md)
> **Disclaimer** > **Disclaimer**
> This project is for learning and communication purposes only. We are not responsible for any data loss; regular vault backups are strongly recommended. > This project is for learning and communication purposes only. Please back up your vault regularly.
> This project is not affiliated with Bitwarden. Please do not report issues to the official Bitwarden team. > This project is not affiliated with Bitwarden. Please do not report NodeWarden issues to the official Bitwarden team.
--- ---
## Feature Comparison Table (vs Official Bitwarden Server) ## Feature Comparison with Official Bitwarden Server
| Capability | Bitwarden | NodeWarden | Notes | | Capability | Bitwarden | NodeWarden | Notes |
|---|---|---|---| |---|---|---|---|
| Web Vault (logins/notes/cards/identities) | ✅ | ✅ | Web-based vault management UI | | Web Vault | ✅ | ✅ | **Original Web Vault interface** |
| Folders / Favorites | ✅ | ✅ | Common vault organization supported | | Full sync `/api/sync` | ✅ | ✅ | Optimized for official clients |
| Full sync `/api/sync` | ✅ | ✅ | Compatibility and performance optimized | | Attachment upload / download | ✅ | ✅ | Cloudflare R2 or KV |
| Attachment upload/download | ✅ | ✅ | Choose either Cloudflare R2 or KV | | Send | ✅ | ✅ | Supports both text and file Sends |
| Import / export | ✅ | ✅ | Fully implemented, including Bitwarden vault + attachments ZIP import | | Import / Export | ✅ | ✅ | Supports Bitwarden JSON / CSV / **ZIP import with attachments** |
| Website icon proxy | ✅ | ✅ | Via `/icons/{hostname}/icon.png` | | **Cloud Backup Center** | ❌ | ✅ | Scheduled backup with WebDAV / E3 |
| passkey / TOTP fields | ✅ | ✅ | Fully supported, no premium required | | Password hint (web) | ⚠️ Limited | ✅ | Supports registration, login assist, unlock, and settings |
| Send | ✅ | ✅ | Choose either Cloudflare R2 or KV | | TOTP / Steam TOTP | ✅ | ✅ | Includes `steam://` support |
| Multi-user | ✅ | ✅ | Full user management with invitation mechanism | | Multi-user | ✅ | ✅ | Invite-based registration |
| Organizations / Collections / Member roles | ✅ | ❌ | Not necessary to implement | | Organizations / Collections / Member roles | ✅ | ❌ | Not implemented |
| Login 2FA (TOTP/WebAuthn/Duo/Email) | ✅ | ⚠️ Partial | User-level TOTP only | | Login 2FA | ✅ | ⚠️ Partial | Currently only user-level TOTP |
| SSO / SCIM / Enterprise directory | ✅ | ❌ | Not necessary to implement | | SSO / SCIM / Enterprise directory | ✅ | ❌ | Not implemented |
| Emergency access | ✅ | ❌ | Not necessary to implement |
| Admin console / Billing & subscription | ✅ | ❌ | Free only |
| Full push notification pipeline | ✅ | ❌ | Not necessary to implement |
## Tested clients / platforms
- ✅ Windows desktop client (v2026.1.0)
- ✅ Mobile app (v2026.1.0)
- ✅ Browser extension (v2026.1.0)
- ✅ Linux desktop client (v2026.1.0)
- ⬜ macOS desktop client (not tested)
--- ---
## Web deploy ## Tested Clients
1. Fork this repository. If you find this project helpful, please consider giving it a Star. - ✅ Windows desktop client
2. Open [Workers](https://dash.cloudflare.com/?to=/:account/workers-and-pages/create) -> `Continue with GitHub` -> select your forked repository (`NodeWarden`) -> `Next` -> (R2 storage is used by default; if R2 is unavailable for your account, switch to KV and change the deploy command to `npm run deploy:kv`) -> deploy -> open the generated URL. - ✅ Mobile app
- ✅ Browser extension
- ✅ Linux desktop client
- ⚠️ macOS desktop client not fully verified
---
## Web Deploy
1. Fork this repository. If this project helps you, please consider giving it a Star.
2. Open [Workers](https://dash.cloudflare.com/?to=/:account/workers-and-pages/create) -> `Continue with GitHub` -> select your forked repository (`NodeWarden`) -> `Next` -> deploy.
R2 is used by default. If R2 is unavailable for your account, you can use KV instead by changing the **deploy command** to `npm run deploy:kv`.
| Storage | Card required | Single attachment / Send file limit | Free tier | | Storage | Card required | Single attachment / Send file limit | Free tier |
|---|---|---|---| |---|---|---|---|
| R2 | Yes | 100 MB (soft limit, can be changed) | 10 GB | | R2 | Yes | 100 MB (soft limit, can be adjusted) | 10 GB |
| KV | No | 25 MiB (Cloudflare limit, cannot be changed) | 1 GB | | KV | No | 25 MiB (Cloudflare limit) | 1 GB |
> [!TIP] > [!TIP]
> Sync upstream (keep your fork updated): > How to keep your fork updated:
>- Manual: open your fork on GitHub, click `Sync fork`, then click `Update branch`. > - Manual: open your fork on GitHub, click `Sync fork`, then `Update branch`
>- Automatic: in your fork, go to `Actions` -> `Sync upstream` -> `Enable workflow`. It will automatically sync from upstream every day at 3 AM. > - Automatic: go to your fork -> `Actions` -> `Sync upstream` -> `Enable workflow`; it will sync upstream automatically every day at 3 AM
## CLI deploy ## CLI Deploy
```powershell ```powershell
# Clone repository
git clone https://github.com/shuaiplus/NodeWarden.git git clone https://github.com/shuaiplus/NodeWarden.git
cd NodeWarden cd NodeWarden
# Install dependencies
npm install npm install
# Cloudflare CLI login
npx wrangler login npx wrangler login
# Deploy to Cloudflare # Default: R2 mode
npm run deploy npm run deploy
# (Optional) KV mode (no R2 / no credit card) # Optional: KV mode
npm run deploy:kv npm run deploy:kv
# Local development # Local development
npm run dev npm run dev
npm run dev:kv npm run dev:kv
# To update later, pull the repository again and redeploy
git clone https://github.com/shuaiplus/NodeWarden.git
cd NodeWarden
npm run deploy
``` ```
--- ---
## FAQ ## Cloud Backup Notes
**Q: How do I back up my data?** - Remote backup supports **WebDAV** and **E3**
A: Use **Export vault** in your client and save the JSON file. - When `Include attachments` is enabled:
- the ZIP still contains only `db.json` and `manifest.json`
- real attachment files are stored separately under `attachments/`
- later backups reuse existing attachments by stable blob name instead of uploading everything again
- During remote restore:
- required attachment files are loaded from `attachments/`
- missing attachments are skipped safely
- skipped attachments do not leave broken rows in the restored database
**Q: Which import/export formats are supported?** ---
A: NodeWarden supports Bitwarden `json/csv/vault + attachments zip` and NodeWarden `vault + attachments json` in both plain and encrypted modes, and every format visible in the import selector is directly importable.
A: It also supports direct import of Bitwarden `vault + attachments zip`, which is not directly supported by official Bitwarden Web import.
**Q: What if I forget the master password?** ## Import / Export
A: It cant be recovered (end-to-end encryption). Keep it safe.
**Q: Can multiple people use it?** Current supported import sources include:
A: Yes. The first registered user becomes the admin. The admin can generate invite codes from the admin panel, and other users register with those codes.
- Bitwarden JSON
- Bitwarden CSV
- Bitwarden vault + attachments ZIP
- NodeWarden JSON
- Multiple browser / password-manager formats visible in the web import selector
Current supported export formats include:
- Bitwarden JSON
- Bitwarden encrypted JSON
- ZIP export with attachments
- NodeWarden JSON variants
- Full manual instance export from the backup center
--- ---
@@ -125,9 +134,8 @@ LGPL-3.0 License
- [Vaultwarden](https://github.com/dani-garcia/vaultwarden) - server implementation reference - [Vaultwarden](https://github.com/dani-garcia/vaultwarden) - server implementation reference
- [Cloudflare Workers](https://workers.cloudflare.com/) - serverless platform - [Cloudflare Workers](https://workers.cloudflare.com/) - serverless platform
--- ---
## Star History ## Star History
[![Star History Chart](https://api.star-history.com/svg?repos=shuaiplus/NodeWarden&type=timeline&legend=top-left)](https://www.star-history.com/#shuaiplus/NodeWarden&type=timeline&legend=top-left) [![Star History Chart](https://api.star-history.com/svg?repos=shuaiplus/NodeWarden&type=timeline&legend=top-left)](https://www.star-history.com/#shuaiplus/NodeWarden&type=timeline&legend=top-left)