⚡ 快速开始

三种方式，从最快捷到最灵活。它们最终都会得到管理面板、API 和已加载的词典：使用 Docker 时位于 http://localhost:3241 和 http://localhost:3240，不使用 Docker 时位于 http://localhost:3000 和 http://localhost:3010。

1. 运行已发布的镜像

无需检出仓库 — 一个文件夹、两个文件、Docker：

mkdir vocab-bloom-hub && cd vocab-bloom-hub
curl -fsSLO https://raw.githubusercontent.com/Fristail27/vocab-bloom-hub/main/docker-compose.yml
curl -fsSL  https://raw.githubusercontent.com/Fristail27/vocab-bloom-hub/main/.env.example -o .env

打开 .env 并设置两个密码：ADMIN_PASSWORD（管理员登录密码）和 POSTGRES_PASSWORD （内置数据库的密码）。然后：

docker compose up -d

首次启动会下载并导入词典 — 需要几分钟。在此期间 GET /api/ready 返回 503，完成后返回 200；然后使用 .env 中的 ADMIN_USERNAME / ADMIN_PASSWORD 登录。

curl -s localhost:3240/api/ready            # {"status":"ok"}
curl -s localhost:3240/api/v1/words/run     # 词典给出响应

# 搜索：匹配的词条，最佳匹配在前
curl -s 'localhost:3240/api/v1/search?search=run&limit=5'
# 同上，并带释义、例句和翻译
curl -s 'localhost:3240/api/v1/search/detailed?search=run&with_meanings=true'

提示

要固定使用某个发布版本而不是 main 开发构建，请在 .env 中设置 VBH_TAG=1.0.0。要在 http://localhost:3242 上添加网站（文档、API 参考、演练场、单词页面），请设置 COMPOSE_PROFILES=db,site。

2. 从仓库运行

同一个 compose 文件，从源代码构建 — 适用于 fork 或尚未发布的修改：

git clone https://github.com/Fristail27/vocab-bloom-hub.git
cd vocab-bloom-hub
cp .env.example .env                           # 同样的两个密码
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

3. 不使用 Docker 运行

直接在机器上以生产模式运行：Node.js 22.13+、Yarn 4（corepack enable）和一个可以连接的 Postgres（docs/database.md）。

git clone https://github.com/Fristail27/vocab-bloom-hub.git
cd vocab-bloom-hub
yarn install
printf 'NODE_ENV=production\nDATABASE_URL=postgres://user:password@localhost:5432/vocab_bloom\nADMIN_USERNAME=admin\nADMIN_PASSWORD=change-me\nNEXT_PUBLIC_BASE_API_URL=http://localhost:3010/api\nDICTIONARY_AUTO_IMPORT=true\n' > .env
yarn build && yarn start                       # API :3010，管理面板 :3000；词典在首次启动时自行加载
yarn site:build && yarn start:site             # 网站 :3020，可选，在另一个终端中运行

在域名和 TLS 之后，使用 systemd 或 PM2：docs/deployment/。

用于开发

无需数据库：没有 DATABASE_URL 时服务器使用本地 SQLite 文件，并且每个应用在更改时自动重启。

printf 'NODE_ENV=development\nADMIN_USERNAME=admin\nADMIN_PASSWORD=change-me\nNEXT_PUBLIC_BASE_API_URL=http://localhost:3010/api\n' > .env
yarn dev                                       # API :3010，管理面板 :3000，网站 :3020

重要

请在管理面板中使用 Import dictionary 加载词典。

面向贡献者的其他内容：CONTRIBUTING.md。

下一步

文档网站，含 API 参考和演练场： vocab-bloom-hub.com。
部署到服务器：docs/deployment/ — TLS 和反向代理、 systemd / PM2、升级。
数据库：docs/database.md — Postgres 要求、迁移、备份、容量规划。
每一项设置：docs/environment.md。
指标和日志：docs/observability.md — 一条命令启动 Prometheus 和 Grafana，或使用您自己的。
读取数据：docs/api.md，以及 Node.js 和 Python SDK。

在 GitHub 上编辑此页面