Skip to content

About

Serverless Hangul-to-Hanja mixed-script converter on Cloudflare Workers + D1 + Kiwi WASM | 基于 Cloudflare 免费架构的韩汉混写转换器 (국한문혼용 변환기)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Hangul–Hanja Mixed Script · Cloudflare Free

将原版项目迁移为 Cloudflare Workers Static Assets + 浏览器官方 Kiwi WebAssembly + TypeScript 转换器 + Workers API + 两个 D1。保留原页面样式、12 种界面语言、词源、候选选择及词典详情。无需 Containers、VPS、R2 或付费 Cloudflare 产品。

原项目架构与迁移依据见 ARCHITECTURE_ANALYSIS.md。本仓库用 Git LFS 保存 2026-08-19、2026-09-19 和 2026-10-19 三份韩国语基础词典官方 JSON ZIP;生成的数据库和模型二进制不入库。构建脚本会从Kiwi 官方发布下载经校验的模型。词典文本来源为韩国国立国语院,按官方 CC BY-SA 2.0 KR 政策署名和共享;压缩包不包含单独授权的多媒体文件。

1. 获取代码与依赖

需要 Node.js 22+、Python 3.12+、Git、Cloudflare Free 账户。

git clone https://github.com/Arrow36/Hangul-Hanja-mixed-script-CF.git
cd Hangul-Hanja-mixed-script-CF
git lfs pull
npm ci
python -m pip install -r requirements.txt

npm run build 会下载 Kiwi 0.24.0 官方 CoNg 模型,校验 SHA-256,拆为小于 Workers Static Assets 单文件限额的资源,并构建前端。首次构建需下载约 88 MB 压缩包;浏览器首次访问加载约 109 MB 模型资源,后续使用 HTTP 缓存,页面显示初始化状态。Kiwi 在浏览器 Web Worker 中运行,不在 Cloudflare Worker 中运行 Python。

2. 准备词典

可直接使用 dictionary-snapshots 中的 2026-10-19 ZIP,也可将路径替换为后来下载的 ZIP。导入生成 hanja_dict.db;该文件不进入 Git。

python scripts/inspect_dictionary.py "/path/to/전체 내려받기_한국어기초사전_json_20261019.zip"
python scripts/import_dictionary.py "/path/to/전체 내려받기_한국어기초사전_json_20261019.zip"
python scripts/export_collocations.py
python scripts/export_d1.py hanja_dict.db output/d1

output/d1/main 与 output/d1/raw 各含分批 SQL。原 SQLite 为 591.8 MB,不能放入单个 D1 Free 数据库。实测主库投影约 224 MB,原始 JSON 库约 380 MB。主库保留词条、义项、译词、例证及候选;第二库保存原始 JSON 的分块。没有使用 R2。collocations.json 是原词典提取的 1,924 组消歧搭配;换词典快照时应重新生成并提交。

3. 登录 Cloudflare 并创建两个 D1

npx wrangler login
npx wrangler d1 create hangul-hanja-dictionary
npx wrangler d1 create hangul-hanja-raw

从两条命令的输出复制 database_id,分别替换 wrangler.jsonc 中的 REPLACE_WITH_MAIN_D1_ID 和 REPLACE_WITH_RAW_D1_ID。先在本地保存配置,再提交 GitHub。数据库 ID 不是密钥。

npx wrangler d1 migrations apply hangul-hanja-dictionary --remote
npx wrangler d1 migrations apply hangul-hanja-raw --remote
python scripts/import_d1.py output/d1/main hangul-hanja-dictionary
python scripts/import_d1.py output/d1/raw hangul-hanja-raw

Free Plan 初次导入需多日。 这份快照主库约 180 万业务行,远超 D1 Free 每日行写入额度,且索引也会增加写入计数。达到当日限额时脚本会停止;次日再次执行同一命令,脚本按本地检查点跳过已成功的 SQL 文件,同一文件的插入也使用 INSERT OR IGNORE 避免重放重复行。不要删除 output/d1 或其中的 .imported-remote 检查点,直到导入完成。D1 Free 限额按账户汇总,主库和原始 JSON 库共享每日额度。最新额度与计量请以官方文档为准。Cloudflare Free 超额后查询/写入会失败,而不会自动产生付费账单。

Workers Paid 账户可在额度内连续运行两条导入命令,仍需保留检查点以应对网络中断。部署前以远程数据库的实际 count(*) 核对完整性;/api/stats 中的元数据是源词典总数,不能用来判断远程导入进度。

新 JSON 快照不能直接重跑本节的全量导出和导入命令来覆盖线上词典:INSERT OR IGNORE 只用于同一快照的断点续传。增量更新请使用下节的专用脚本。

后续 JSON 快照的增量更新

dictionary-snapshots/ 中的 ZIP 通过 Git LFS 保存。新快照下载后放进该目录,提交并推送即可保存源文件;git lfs pull 可在新电脑取回完整 ZIP。GitHub 页面显示的是 LFS 指针,不能直接浏览 ZIP 内的词条。词典文本归属韩国国立国语院,来源及许可见本 README 开头。

下面以从 20260919 更新到仓库最新快照 20261019 为例,在 PowerShell 中执行。需要保留两个快照的本地 SQLite;若没有旧库,可从仓库中的旧 ZIP 重新运行导入命令生成。output/ 和 SQLite 均不提交 Git。新快照日期请替换为真实文件名。

New-Item -ItemType Directory output/snapshots -Force | Out-Null
$env:HANJA_DB_PATH = 'output/snapshots/20260919.db'
python scripts/import_dictionary.py 'dictionary-snapshots/전체 내려받기_한국어기초사전_json_20260919.zip'
$env:HANJA_DB_PATH = 'output/snapshots/20261019.db'
python scripts/import_dictionary.py 'dictionary-snapshots/전체 내려받기_한국어기초사전_json_20261019.zip'
Remove-Item Env:HANJA_DB_PATH
python scripts/prepare_incremental.py output/snapshots/20260919.db output/snapshots/20261019.db output/delta/20260919-20261019
Get-Content output/delta/20260919-20261019/manifest.json

prepare_incremental.py 比对导入后每个词条的原始 JSON,输出新增、修改、删除词条的统计和两套分批 SQL。主库脚本会替换变动词条及关联的义项、译词、例证、词形和候选;原始库脚本只替换这些词条的 JSON 分块。先检查清单和 SQL,再执行远程写入:

python scripts/apply_incremental.py output/delta/20260919-20261019 --remote --apply
python scripts/export_collocations.py output/snapshots/20261019.db
npm run deploy

应用脚本先核对线上主库 import_metadata.sha256 是否等于旧 ZIP 的哈希、词条总数是否符合旧快照,再更新原始库和主库,最后写入新版本元数据,并核对两库的词条数。每个 SQL 文件有校验值和本地断点;网络中断后用同一目录重跑上述命令。版本不符会停止,不会把旧版或不相干的快照覆盖到线上。两库无法跨库事务提交,更新期间短时间内可能出现新旧词条内容不一致,宜在低流量时操作。collocations.json 是静态资源,因此 D1 更新完成后还需从新 SQLite 重新生成并部署。新 ZIP 入库时使用 git add dictionary-snapshots、git commit、git push;仅上传 ZIP 不会自动写入 D1。

导入完成后核对关键词:

npx wrangler d1 execute hangul-hanja-dictionary --remote --command "SELECT written_form, origin_raw FROM entries WHERE written_form='경제'"
npx wrangler d1 execute hangul-hanja-dictionary --remote --command "SELECT count(*) AS n FROM entries"
npx wrangler d1 execute hangul-hanja-raw --remote --command "SELECT count(DISTINCT entry_id) AS n FROM entry_raw_chunks"

期望 경제 → 經濟、词条 56,555、原始 JSON 词条 56,555。导入占用请在 Cloudflare D1 面板确认;本地 SQLite 大小只是估计。

同一 ZIP 的解析兼容修复

20261023.1 解析器保留重复分类、全部句型和逐项配对的发音/音频,解析已核实的 <hanja> 引用,并为 <word_no> 建立目标引用。原始 JSON 保持不变。未知汉字引用会停止导入,避免静默丢失转换候选。已核实的映射及快照出处见 scripts/hanja_references.json。

线上已导入同一 ZIP 时,使用专用修复脚本;普通增量更新会拒绝相同 SHA 的输入。先从该 ZIP 的完整 SQLite 快照准备修复包,再应用主库 migration 和修复:

python scripts/repair_compatibility.py prepare output/snapshots/20261019.db output/repair/20261023-compat
npx wrangler d1 migrations apply hangul-hanja-dictionary --remote
python scripts/repair_compatibility.py apply output/repair/20261023-compat --remote --apply

准备目录必须是新目录。脚本校验源 ZIP SHA、词条数、SQL 校验和及候选前置条件,逐条比较全部补充数据后才记录完成。中断后可用同一目录重跑。此步骤只写主库的派生数据,不写原始 JSON 库,也不重新导入整个词典。20261019 快照补齐 3,709 个词条,恢复 밀착시키다 → 密着시키다 和 부담시키다 → 負擔시키다,含汉字词源的词条增至 34,150。

必须先完成数据库 migration 和修复,再部署引用新表的 Worker。之后 /api/version 应返回 parser_version: "20261023.1",数据版本仍是 20261019。详情 API 保留旧标量字段,并提供 semantic_categories、subject_categories、各义项的 syntactic_patterns 和需要多发音的词形中的 pronunciation_variants;页面只渲染允许的词典标记,其他尖括号文本按字面显示。

后续 ZIP 更新要求新旧 SQLite 使用相同解析器。可从旧 ZIP 重新导入一份新解析器基线;也可先对旧 SQLite 应用 0002_dictionary_compatibility.sql,再用修复脚本的 --sqlite 路径 --apply 修复。然后按普通增量流程更新。不要只手工修改 parser_version 来跳过检查。

4. 本地运行与验证

npm run build
npm test
python -m unittest discover -s tests_cf -p 'test_*.py' -v
npx wrangler deploy --dry-run
npm run dev

打开 http://127.0.0.1:8787/zh。本地 D1 与远程分开,可用相同 migration 与导入脚本的 --local 选项建立本地完整词典:

npx wrangler d1 migrations apply hangul-hanja-dictionary --local
npx wrangler d1 migrations apply hangul-hanja-raw --local
python scripts/import_d1.py output/d1/main hangul-hanja-dictionary --local
python scripts/import_d1.py output/d1/raw hangul-hanja-raw --local

如果已经用 scripts/import_dictionary.py 生成了完整的 hanja_dict.db,本地测试可直接把它复制到 Wrangler 本地 D1,速度更快。先停止 npm run dev,运行两条本地 migration,然后执行:

python scripts/seed_local_d1.py
npm run dev

seed_local_d1.py 只修改 .wrangler/state 中的本地测试数据库,不连接 Cloudflare;可重复运行。页面地址只有在 npm run dev 正在运行且终端显示 Ready on http://127.0.0.1:8787 时才可打开。

/kiwi-demo.html 是 Kiwi 最小浏览器测试,输入 한국 경제가 빠르게 성장했다. 后显示 form/tag/start/len。scripts/verify_conversion.py 从原 Python 版本生成 42 条回归样例;npm test 要求相同 token/候选条件下 TypeScript 显示文本全部一致,并生成 tests_cf/differences.json。实际 WASM 模型配合完整词典复测为 41/42;其中一处由 Kiwi 模型分词差异造成,不属于固定 token 回归测试的覆盖范围。

5. 部署与 GitHub 自动部署

完成 D1 配置与至少主库导入后:

npm run deploy

Wrangler 会输出实际 https://<worker>.<subdomain>.workers.dev 地址。不要猜测域名;以命令输出为准。首次使用 Workers 时,Cloudflare 可能要求设置免费的 workers.dev 子域。

GitHub 仓库 Settings → Secrets and variables → Actions 中建立:

  • CLOUDFLARE_API_TOKEN:作用域限于目标账户的 Workers 部署权限;
  • CLOUDFLARE_ACCOUNT_ID:Cloudflare 账户 ID。

官方 GitHub Actions 指南要求这两个值。.github/workflows/deploy.yml 在 main push 后安装依赖、构建和测试;启用部署变量后再执行 Wrangler 部署。D1 数据由上面的导入步骤独立管理,不随每次 push 重建。

首次仓库发布时,Workflow 仅构建与测试。填好真实 D1 ID、完成导入并设置上述两个 Secrets 后,在 Actions variables 新增 CLOUDFLARE_READY=true;此后每次推送 main 即自动部署。设置变量后可手动运行一次 Workflow 触发首次自动部署。

API 与缓存

  • POST /api/dictionary/batch:最多 80 个唯一词,返回候选映射;转换在浏览器端将词形去重后分批请求。输入使用长度检查和 D1 参数绑定。
  • POST /api/dictionary/origins:批量词源。
  • GET /api/lookup:词形或词源前缀、词条 ID 搜索。
  • GET /api/entries/:id、/api/entries/:id/raw:详情与完整原始 JSON。
  • POST /api/select-candidate:验证用户手选的词条。
  • GET /api/version、/api/stats:词典版本与统计。

浏览器使用页面内存 Map 与静态资源 HTTP 缓存;词典候选不再持久缓存,以免数据库更新后继续使用旧结果。词典服务请求失败时显示明确错误,不会将输入文本加入 Cloudflare Cache。模型只在浏览器 Worker 中初始化一次。Cloudflare Worker bundle 本地 dry-run 为约 10 KiB,不包含 WASM/模型。

已知限制

  • 首次模型下载量大,移动设备或低内存浏览器可能无法初始化;页面提示失败且不会悄悄使用低质量分词。
  • 浏览器官方 Kiwi 0.24.0 CoNg 与原 Python kiwipiepy 0.23.2 默认模型可能在少数词上产生不同 token,进而影响结果。
  • 词源搜索改为索引支持的前缀搜索,避免任意子串扫描触及 Free D1 读取额度。
  • Free D1 首次完整导入需要分多天;在主库未导入完时,网站的词典数据不完整。
  • 是否始终保持 0 美元取决于账户保持 Workers Free、没有启用付费产品,以及实际用量在Workers、D1与Static Assets官方当前限额内。超额时服务会受限。

原项目 GPL-3.0 许可证见 LICENSE。Kiwi 的 npm 包与模型遵守其官方许可证。词典文字数据来源:韩国国立国语院(국립국어원)韩国语基础词典;本站的搭配文件及回归样例是基于该数据的转换,按官方CC BY-SA 2.0 KR 著作权政策标注与共享。音视频等多媒体资源可能有不同许可,本仓库不复制其文件。

About

Serverless Hangul-to-Hanja mixed-script converter on Cloudflare Workers + D1 + Kiwi WASM | 基于 Cloudflare 免费架构的韩汉混写转换器 (국한문혼용 변환기)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages