一个Docker命令，40万首古诗词API开箱即用

01 引言

在开发国风应用、诗词学习工具或文化类小程序时，最耗时的往往不是前端页面，而是底层数据的整理与检索。从零开始搭建一套包含近 40 万首诗词的数据库，并完成清洗、分类、搜索接口的开发，足以让项目还没开工就耗掉大半精力。

诗泉（Chinese Poetry API）正是为了解决这个痛点而生。它是一个基于 Go 语言开发的高性能中国古诗词 API 服务，将海量诗词数据转化为开箱即用的标准化接口，让开发者可以专注于内容呈现，而非数据工程。

02 简介

诗泉（Chinese Poetry API）基于 chinese-poetry的数据集，通过Go语言构建高性能中国古诗词 API 服务，支持 REST 和 GraphQL 接口，提供简体/繁体中文、爬虫练习场等功能。

GitHub地址：https://github.com/palemoky/chinese-poetry-api

官网地址（在线体验）：https://poetry.palemoky.com/

数据源地址：

GitHub地址：https://github.com/chinese-poetry/chinese-poetry

官网地址：https://awesome-poetry.top/huajianji/

2.1 数据集

数据集包括：

整体数据规模接近 40 万条，按标题、正文、作者、朝代、体裁等维度进行了结构化整理。

2.2 搜索

提供了支持多种搜索方式，满足不同场景需求：

2.3 双接口支持

同时提供 REST API 和 GraphQL API，适应不同技术栈和开发习惯：

• REST API：简单直观，适合快速集成
• GraphQL：灵活查询，按需获取字段，减少数据传输

2.4 简繁转化

同一数据库同时存储简体和繁体中文，通过 ?lang= 参数自由切换：

• zh-Hans：简体中文（默认）
• zh-Hant：繁体中文

对于面向不同地区用户的阅读产品，无需维护两套内容。

03 Docker部署

直接拉取镜像：

docker run -d -p 1279:1279 palemoky/chinese-poetry-api:latest

也可以同过克隆项目构建Docker镜像实现。

在启动镜像的时候会下载数据库(data/poetry.db),需要耐心等待一下。可通过

docker logs -f 容器ID

命令查看下载的进度：

可能因为机器版本的问题导致数据集无法下载：

可以通过自己下载数据集，直接挂载即可：

-v /opt/chinese-poetry-data/data:/app/data

数据库的下载可以通过AI修复下载，也可以通过官网手动下载：

我这边是通过AI直接修复的，不在赘述。提供一下最终修复的脚本：

docker run -d -p 1279:1279 \
  --security-opt seccomp=unconfined \
  -v /opt/chinese-poetry-data/data:/app/data \
  --name poetry-test \
  palemoky/chinese-poetry-api:latest \
  sh -c "exec ./server"

04 测试

这边测试以REST API为例。

4.1 随机获取一首（简体）

curl "http://localhost:1279/api/v1/poems/random"

4.2 随机获取一首（繁体）

curl "http://localhost:1279/api/v1/poems/random?lang=zh-Hant"

4.3 搜索诗词

curl "http://localhost:1279/api/v1/poems/search?q=静夜思"

其他更多的接口可以参考官方文档：https://poetry.palemoky.com/

05 小结

诗泉不是一款完整的诗词学习软件，而是一个已经准备好的数据基础设施层。围绕它，可以快速构建一些非常有意思的小插件，如之前非常火的诗词大会中的飞花令、以及诗词类的小游戏等

如果你正在开发国风应用、诗词学习工具，或需要为中国传统文化项目提供数据支撑，诗泉值得放入你的技术选型清单。