返回导入中心

如何从 R2/S3 Bucket 导入词典

逐步指导你配置云存储，并从 R2 或任何兼容 S3 的 Bucket 导入词典。

你需要准备：

  • Cloudflare R2 账户（推荐）或任意兼容 S3 的存储服务
  • 已上传到 Bucket 中的 MDict 词典文件（.mdx 以及可选的 .mdd 文件）
  • API 凭据（Access Key ID 与 Secret Access Key）

步骤 1：配置 Cloudflare R2

1.1 创建 R2 Bucket

  1. 登录你的 Cloudflare 控制台
  2. 在左侧侧边栏中进入 R2
  3. 点击 Create bucket
  4. 为 Bucket 输入名称（例如 my-dictionaries）
  5. 选择合适的存储区域（尽量选择离你更近的区域以获得更好性能）
  6. 再次点击 Create bucket 完成创建

1.2 上传词典文件

  1. 打开刚刚创建的 Bucket
  2. 点击 Upload
  3. 上传你的词典文件（.mdx 文件及其对应的 .mdd 资源文件）
  4. 确保相关文件使用相同的基础文件名（例如 Oxford.mdx、Oxford.mdd）

1.3 开启公开访问（必需）

  1. 在 Bucket 设置中找到 Public Access（公开访问）区域
  2. 点击 Connect Domain 或 Allow Access
  3. 你可以选择以下其一：
    • 使用 R2 默认的公共 URL（例如 https://pub-xxxxx.r2.dev）
    • 绑定你自己的自定义域名以获得更简洁的 URL
  4. 复制 Public Bucket URL（公共 Bucket 地址），稍后会用到

1.4 生成 API Token

  1. 返回 R2 概览页面
  2. 点击 Manage R2 API Tokens
  3. 点击 Create API Token
  4. 按如下方式配置 Token：
    • Token name： 例如 “WordHub Dictionary Access”
    • Permissions： 选择 Object Read（只读权限即可）
    • TTL： 选择 “Forever”，或指定过期时间
    • （可选）限制只允许访问某些 Bucket，以提升安全性
  5. 点击 Create API Token 创建
  6. 重要： 请立即复制并保存这些凭据（之后将无法再查看）：
    • Access Key ID
    • Secret Access Key
    • Endpoint URL（通常为 https://<account-id>.r2.cloudflarestorage.com）

步骤 2：使用其他兼容 S3 的服务

WordHub 也支持其他兼容 S3 的存储服务，如 AWS S3、MinIO、Backblaze B2、DigitalOcean Spaces 等，配置步骤与上面类似：

在对应服务的控制台中创建一个 Bucket

将词典文件上传到该 Bucket

开启公共读取权限或配置合适的访问策略

生成访问凭据（Access Key ID 与 Secret Access Key）

记录 Bucket 的公共访问 URL 以及 Endpoint 地址

步骤 3：在 WordHub 中导入词典

3.1 开始导入流程

  1. 进入 词典导入中心
  2. 点击 Start Dictionary Import
  3. 选择 Bucket URL（而不是 Local Files）

3.2 填写访问凭据

  1. Bucket URL： 粘贴你的公共 Bucket 地址（例如 https://pub-xxxxx.r2.dev）
  2. Access Key ID： 粘贴在步骤 1.4 中生成的 Access Key ID
  3. Secret Access Key： 粘贴在步骤 1.4 中生成的 Secret Access Key
  4. Region： 使用 Cloudflare R2 时选择 Auto；其他服务请选择对应的区域。
  5. Endpoint（可选）： 如使用自定义 Endpoint，在此填写（例如 Cloudflare R2：https://<account-id>.r2.cloudflarestorage.com）

3.3 测试并发现词典文件

  1. 点击 Test Connection 测试连接是否成功
  2. 连接成功后，点击 Discover Files
  3. WordHub 会扫描 Bucket 并自动分组词典文件
  4. 检查发现的词典列表，选择需要导入的条目
  5. 点击 Import Selected Dictionaries 开始导入

故障排查

“Connection Failed” 或 “Access Denied”

  • 确认 Access Key ID 和 Secret Access Key 填写正确
  • 检查 Bucket 是否已开启公共读取权限
  • 确保 API Token 拥有正确的权限（至少需要 Object Read）
  • 确认填写的是公共访问 URL，而不是 API Endpoint 地址

“No Dictionary Files Found”

  • 确认 Bucket 中确实存在 .mdx 词典文件
  • 检查文件是否位于 Bucket 根目录或直接子目录（而不是过深的嵌套路径）
  • 确认文件名符合约定命名（例如 Dictionary.mdx、Dictionary.mdd）

“Region/Endpoint Issues”

  • 使用 Cloudflare R2 时请选择 “Auto” 区域，并在必要时填写 Endpoint
  • 使用 AWS S3 时，请选择 Bucket 所在的正确区域
  • 其他服务请参阅其文档，确认正确的 Endpoint URL 与区域设置

安全最佳实践

仅授予只读权限： 将 API Token 权限限制为 Object Read，以避免未授权修改。

限制 Token 作用范围： 尽量只授权访问特定 Bucket，而不是整个账户。

设置过期时间： 为 API Token 设置合理的过期时间，并定期轮换。

保护好凭据： 不要在公共场合分享 Access Key ID 或 Secret Access Key。

准备好导入你的词典了吗？

前往导入中心