基于 DuckDuckGo Email Protection 的临时邮箱管理系统，支持多 Token 负载均衡、智能冷却期管理、RESTful API 和 Web 管理界面。

• 🔄 多 Token 负载均衡 - 智能轮询，自动选择最佳可用 Token
• ⏱️ 智能冷却期管理 - 防止 API 限流，支持失败重试
• 🚀 RESTful API - 完整的 REST API，支持批量生成
• 🌐 Web 管理界面 - 简洁的 Dashboard，表格展示邮箱数据
• 🔐 统一认证 - 单一密钥用于 API 和 Web 登录
• 💾 SQLite 存储 - 轻量级数据库，零配置
• 💽 一键备份恢复 - 内置数据库备份、恢复和保留策略
• 📊 统计监控 - 实时统计 Token 使用情况和邮箱数据

• Node.js >= 20.0.0
• npm >= 10.0.0

# 克隆项目（如果从 Git 克隆）
git clone <repository-url>
cd duckduckgoapi

# 安装依赖
npm install

# 配置环境变量
cp .env.example .env
nano .env  # 修改 API_SECRET

编辑 .env 文件：

# 重要：修改为你的强密钥
API_SECRET=your-very-secure-secret-key-here

# 其他配置（可选）
PORT=3000
DATABASE_PATH=./data/emails.db
# DATABASE_BACKUP_DIR=./data/backups
# DATABASE_MAX_BACKUP_FILES=7
# DATABASE_AUTO_BACKUP_ENABLED=true
# DATABASE_AUTO_BACKUP_CRON=0 0 3 * * *

# 开发模式
npm run start:dev

# 生产模式
npm run build
npm run start:prod

• Web 界面：http://localhost:3000
• API 文档：http://localhost:3000/api/docs
• 健康检查：http://localhost:3000/health

首先需要从 DuckDuckGo 获取 Token（参考下方"获取 Token"章节），然后通过以下方式添加：

方式一：通过 Web 界面

1. 登录 Dashboard（密码为 .env 中的 API_SECRET）
2. 进入"Token 管理"页面
3. 填写用户名和 Token，点击"添加"

方式二：通过 API

curl -X POST http://localhost:3000/api/tokens \
  -H "Authorization: Bearer your-api-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "userName": "user123",
    "token": "abcd1234efgh5678"
  }'

单个邮箱：

curl -X POST http://localhost:3000/api/emails/generate \
  -H "Authorization: Bearer your-api-secret"

批量生成：

curl -X POST http://localhost:3000/api/emails/generate-batch \
  -H "Authorization: Bearer your-api-secret" \
  -H "Content-Type: application/json" \
  -d '{"count": 10}'

duck 获取access_token

curl 'https://quack.duckduckgo.com/api/email/dashboard' \
  -H 'accept: */*' \
  -H 'accept-language: ja-JP,ja;q=0.9' \
  -H 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjhmNzI2MzZkLTc4OGMtNGU5Ny1hYTZiLTEzZGU0YzNmYmU4MyJ9.eyJpYXQiOjE3NTk5OTM1ODAsImV4cCI6MTc1OTk5NTM4MCwidXNyIjoidmlydHVhbGMiLCJpc3MiOiJEdWNrRHVja0dvIn0.wk6KtRkn6ee7-TVJjWd2DFSyKcxUmOQlS5N5X9jcEQJEdtadV2e8VHSiSegOrRKZTwyJ_ASJtjiDHMvCFqvwRw' \
  -H 'origin: https://duckduckgo.com' \
  -H 'priority: u=1, i' \
  -H 'referer: https://duckduckgo.com/' \
  -H 'sec-ch-ua: "Not)A;Brand";v="8", "Chromium";v="138", "Google Chrome";v="138"' \
  -H 'sec-ch-ua-mobile: ?0' \
  -H 'sec-ch-ua-platform: "macOS"' \
  -H 'sec-fetch-dest: empty' \
  -H 'sec-fetch-mode: cors' \
  -H 'sec-fetch-site: same-site' \
  -H 'sec-gpc: 1' \
  -H 'user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36'

Web 界面：登录后在 Dashboard 即可查看

API：

curl http://localhost:3000/api/emails?page=1&limit=20 \
  -H "Authorization: Bearer your-api-secret"

1. 访问 https://duckduckgo.com/email
2. 登录你的 DuckDuckGo 账号
3. 打开浏览器开发者工具（F12）
4. 切换到 Network 标签
5. 在页面上进行任何操作（如生成邮箱）
6. 找到 addresses 请求
7. 在 Request Headers 中找到 Authorization: Bearer <token>
8. 复制 Bearer 后面的 token

完整 API 文档访问：http://localhost:3000/api/docs

• POST /api/tokens - 添加 Token
• GET /api/tokens - 获取 Token 列表
• PATCH /api/tokens/:id - 更新 Token 状态
• DELETE /api/tokens/:id - 删除 Token

• POST /api/emails/generate - 生成单个邮箱
• POST /api/emails/generate-batch - 批量生成邮箱
• GET /api/emails - 获取邮箱列表
• DELETE /api/emails/:id - 删除邮箱

• GET /api/statistics - 获取系统统计

所有 API 请求需要携带密钥：

Authorization: Bearer <your-api-secret>

duckduckgoapi/
├── src/
│   ├── modules/        # 业务模块
│   ├── database/       # 数据库模块
│   ├── common/         # 通用模块（守卫、拦截器等）
│   ├── config/         # 配置
│   ├── app.module.ts
│   └── main.ts
├── views/              # Web 模板
├── public/             # 静态资源
├── docs/               # 文档
│   ├── requirements.md
│   └── development.md
└── data/               # 数据库文件

变量名	说明	默认值	必填
NODE_ENV	运行环境	development	否
PORT	服务端口	3000	否
API_SECRET	API 密钥	-	是
DATABASE_PATH	数据库路径	./data/emails.db	否
TOKEN_NORMAL_COOLDOWN	正常冷却时间（秒）	60	否
TOKEN_FAILURE_COOLDOWN	失败冷却时间（秒）	300	否
TOKEN_MAX_REQUESTS_PER_HOUR	每小时限制	20	否

系统采用智能负载均衡，自动选择最佳 Token：

1. 过滤不可用 Token

   • 状态为 disabled 或 expired 的 Token
   • 仍在冷却期的 Token

2. 优先级排序

   • 最久未使用的 Token 优先
   • 使用次数少的 Token 优先

3. 冷却期管理

   • 成功使用：冷却 60 秒
   • 失败使用：冷却 300 秒
   • 连续失败 5 次：自动禁用

# 单元测试
npm run test

# E2E 测试
npm run test:e2e

# 测试覆盖率
npm run test:cov

npm run build
npm run start:prod

docker build -t duck-email-api .
docker run -d -p 3000:3000 \
  -e API_SECRET=your-secret \
  -v $(pwd)/data:/app/data \
  duck-email-api

npm install -g pm2
pm2 start dist/main.js --name duck-email-api
pm2 save
pm2 startup

• 需求文档 - 详细的功能需求说明
• 开发文档 - 开发指南和 API 文档

登录后台后，可在左侧菜单进入 “数据库备份” 页面，查看历史备份、手动创建备份或一键恢复，也可以上传本地 .db 文件立即恢复。

如需脚本化操作，服务同样提供 REST API，所有请求需要携带 X-API-KEY 请求头（值为 .env 中的 API_SECRET）。

• 创建备份

curl -X POST http://localhost:3000/api/database/backup \
  -H "X-API-KEY: ${API_SECRET}"

• 查看备份列表

curl http://localhost:3000/api/database/backups \
  -H "X-API-KEY: ${API_SECRET}"

• 从备份恢复（谨慎操作，会覆盖当前数据）

curl -X POST http://localhost:3000/api/database/restore \
  -H "X-API-KEY: ${API_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{"filename":"emails_20250101_120000.db"}'

备份文件默认保存在 ${DATABASE_BACKUP_DIR}（默认 ./data/backups）目录下，系统会自动保留最近 DATABASE_MAX_BACKUP_FILES 份备份，并在每天 03:00 执行一次自动备份（可通过环境变量关闭或调整）。

1. API_SECRET 安全

   • 使用强密钥（建议 32 字符以上）
   • 不要将密钥提交到 Git
   • 定期更换密钥

2. Token 管理

   • 定期检查 Token 是否过期
   • 失效的 Token 及时删除
   • 建议配置 5-10 个 Token

3. 数据库备份

   • 使用 Dashboard -> 数据库备份 页面或 API 及时导出数据
   • 自动备份默认保留 7 份，也建议定期异地备份
   • 数据库文件不要提交到 Git

4. 速率限制

   • 遵守 DuckDuckGo API 限制
   • 不要频繁请求
   • 使用冷却期机制

# 连接数据库
sqlite3 data/emails.db

# 重置冷却期
UPDATE tokens SET cooldown_until = NULL WHERE status = 'active';

检查环境变量：

cat .env | grep API_SECRET

# 删除临时文件
rm data/emails.db-shm data/emails.db-wal

# 重启服务
npm run start:prod