把唐诗宋词元曲全装进Docker，一键部署自己的诗词API

发表于 分类于 Waline： 阅读次数： 本文字数： 2.9k 阅读时长 ≈ 3 分钟
诗泉 (chinese-poetry-api) 是一个基于 Go 语言的高性能中国古诗词 API 服务，支持 REST 和 GraphQL 接口，收录近 40 万首诗词。

简介

什么是诗泉 (chinese-poetry-api) ？

诗泉是一个基于 Go 语言的高性能中国古诗词 API 服务，收录了唐诗、宋词、元曲等近 40 万首诗词作品。它提供 REST 和 GraphQL 双接口，支持简繁体中文切换、全文搜索和 IP 限流，一条 Docker 命令即可完成部署。

主要特点

  • 高性能：Go 语言编写，支持并发处理，简繁转换仅需 ~300ns/op
  • 海量数据：收录近 40 万首诗词，涵盖唐诗、宋词、元曲、诗经、楚辞等
  • 强大搜索：支持全文搜索、按标题/内容/作者分类搜索
  • 双语支持：同一数据库同时存储简体和繁体中文，通过 ?lang= 参数一键切换
  • 多种接口：REST API 和 GraphQL 双接口支持，满足不同开发需求
  • 限流保护：内置 IP 限流，防止恶意滥用
  • 容器化：Docker 镜像开箱即用，支持 amd64/arm64 多架构
  • 开源免费：基于 GPL-3.0 协议开源，可免费使用和修改

应用场景

  • 个人博客/网站：为个人网站添加每日诗词展示、飞花令等功能
  • 教育/学习工具：作为古诗词学习 App 或小程序的后端数据源
  • AI 应用：为 AI 对话、写作助手提供古诗词内容素材
  • 开发者测试：开发人员可以快速搭建测试环境，也可用于爬虫练习

诗泉是一个开箱即用的古诗词数据 API，让你无需自己处理海量数据即可拥有完整的古诗词查询能力。

安装

在群晖上以 Docker 方式安装。

在注册表中搜索 palemoky，选择第二个 palemoky/chinese-poetry-api，版本选择 latest。

本文写作时，latest 版本对应为 0.6.0；

卷

在 docker 文件夹中，创建一个新文件夹 chinese-poetry-api，并在其中建一个子文件夹 data

文件夹 装载路径 说明
docker/chinese-poetry-api/data /app/data 存放诗词数据库

端口

本地端口不冲突就行，不确定的话可以用命令查一下

1
2
# 查看端口占用
netstat -tunlp | grep 1279
本地端口 容器端口
1279 1279

环境

可变 值
TZ Asia/Shanghai

环境变量说明：TZ 用于设置时区，可选。其他如 PORT（默认 1279）、RATE_LIMIT_RPS（默认 10）、RATE_LIMIT_BURST（默认 20）等均有内置默认值，无需额外设置。

命令行安装

docker cli 安装

如果你熟悉命令行，可能用 docker cli 更快捷

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 新建文件夹 chinese-poetry-api 和 子目录
mkdir -p /volume1/docker/chinese-poetry-api/data

# 进入 chinese-poetry-api 目录
cd /volume1/docker/chinese-poetry-api

# 一键启动
docker run -d \
  --name=chinese-poetry-api \
  --restart=unless-stopped \
  -p 1279:1279 \
  -v $(pwd)/data:/app/data \
  -e TZ=Asia/Shanghai \
  palemoky/chinese-poetry-api:latest

docker-compose 安装

也可以用 docker-compose 安装，将下面的内容保存为 docker-compose.yml 文件

1
2
3
4
5
6
7
8
9
10
11
12
13
version: '3.8'

services:
  poetry-api:
    image: palemoky/chinese-poetry-api:latest
    container_name: chinese-poetry-api
    restart: unless-stopped
    ports:
      - "1279:1279"
    volumes:
      - ./data:/app/data  # 存放诗词数据库
    environment:
      - TZ=Asia/Shanghai

然后通过 SSH 登录到您的群晖，执行下面的命令：

1
2
3
4
5
6
7
8
9
10
# 新建文件夹 chinese-poetry-api 和 子目录
mkdir -p /volume1/docker/chinese-poetry-api/data

# 进入 chinese-poetry-api 目录
cd /volume1/docker/chinese-poetry-api

# 将 docker-compose.yml 放入当前目录

# 一键启动
docker-compose up -d

运行

在浏览器中访问 http://<群晖IP>:1279 会看到错误提示 ，因为这只是个 API 接口服务，并没有包含 Web 服务

首次启动时，容器会自动从 GitHub Release 下载诗词数据库，请耐心等待下载完成。查看启动日志：

1
2
# 命令行查看日志
docker logs -f chinese-poetry-api

下载的诗词数据库会在 data 目录中

如果自动下载有问题，也可以手动下载后解压上传

当看到 Starting API server... 的日志后，即可开始使用 API：

1
2
3
4
5
6
7
8
9
10
11
# 获取随机诗词
curl http://<群晖IP>:1279/api/v1/poems/random

# 搜索诗词
curl http://<群晖IP>:1279/api/v1/poems/search?q=静夜思

# 繁体中文
curl http://<群晖IP>:1279/api/v1/poems/random?lang=zh-Hant

# 随机一首李白的诗
curl http://<群晖IP>:1279/api/v1/poems/random?author=李白

如果习惯使用图形化界面，项目还提供了在线 Demo：https://poetry.palemoky.com

AI 演示

以前这种 API 应用一般都是给程序员用的，但是有了 AI 之后就不一样了

做不了复杂的，可以让 AI 给我们搓个简单的

支持搜索

支持统计

朝代也可以随机

注意事项

  1. 首次启动需联网：容器启动时会从 GitHub Release 下载约 382MB 的 SQLite 数据库文件，首次启动需要稳定的网络连接
  2. 数据持久化：数据库下载到 /app/data 目录后，更新检查在每次容器启动时自动进行，持久化该目录可避免重复下载
  3. 端口选择：1279 是默认端口，可通过环境变量 PORT 自定义，修改后需同步更新端口映射
  4. 资源占用：SQLite 数据库加载到内存中运行，建议分配至少 512MB 内存给容器

参考文档

palemoky/chinese-poetry-api: 📜 诗泉：高性能中国古诗词 API 服务
地址：https://github.com/palemoky/chinese-poetry-api

palemoky/chinese-poetry-api - Docker Image
地址：https://hub.docker.com/r/palemoky/chinese-poetry-api

诗泉 — 免费开源的中文古诗词 API
地址：https://poetry.palemoky.com/