picturebook-kg：技术架构与 API 接口文档

绘本知识图谱 · 知识图谱驱动的绘本内容生产平台

项目概述

知识图谱驱动的绘本内容生产平台，服务公众号/小红书内容生产，家长端搜索为次要目标。数据库目前收录 1899 本绘本，经过 AI 多维标签提炼（主题、艺术风格、情感基调、节气等）。

域名：hui-ben.top
VPS：阿里云香港（47.239.140.218）
宿主机：opencode（Mac mini）
部署方式：PM2 + Nginx + certbot HTTPS

技术栈

层级技术
框架Next.js 16 (App Router) + React 19
数据库PostgreSQL + Prisma 7（db push，不跑 migrate）
ORMPrisma Client + PrismaPg adapter
AI 提炼SiliconFlow → Qwen/Qwen2.5-72B-Instruct
AI 文档生成MiniMax M2.7（OpenAI 兼容 SDK）
多模态GLM 5.1（通过 aiproxy）
样式Tailwind CSS 4，暖橙色系 (#F97316)，移动端优先
部署PM2 → Next.js standalone (port 3000) → Nginx (80/443) → certbot SSL

数据库模型

表说明
Book绘本主表 — 标题、作者、出版社、豆瓣信息、AI 提炼标签
RawCrawl原始爬虫数据
PromptTemplateAI Prompt 版本管理
LLMCallLogAI 调用日志（类型、模型、token、耗时）
ContentDraft小红书/公众号内容草稿
ReadingPlan阅读计划（书单）
UserEventLog用户行为日志

Book 表的关键字段

分类字段
基础信息title, author, illustrator, publisher, isbn, doubanRating
维度提炼themeTagsL1, themeTagsL2, emotionTone, ageRange, solarTerms
叙事提炼oneLineStory, parentValue, readingTips, narrativeStructure
艺术提炼artMediumTags, artStyleTags, artColorTags, artStyleDesc
质量追踪analysisStatus, qualityFlags, analysisCost, promptVersion

Agent API 接口

专为 AI agent 调用设计的只读接口，无需认证，位于 /api/agent/ 路径下。

1. 健康检查

GET /api/agent/health

返回服务状态、数据库连接状态和绘本总数。

{
  "ok": true,
  "data": {
    "status": "ok",
    "db": "connected",
    "book_count": 1899,
    "last_updated": "2026-05-04T16:25:49.187Z"
  }
}

2. 搜索绘本

GET /api/agent/books?q=<关键词>&page=<页码>&limit=<每页数>&status=<状态>
参数类型默认说明
qstring""搜索关键词（模糊匹配标题/作者/简介/一句话故事）
pageint1页码
limitint20每页条数（最大 100）
statusstring""分析状态过滤（如 done）

返回字段：id, title, author, coverUrl, ageRange, themeTagsL1, doubanRating, oneLineStory, analysisStatus, updatedAt

3. 绘本详情

GET /api/agent/books/:id

返回单本书的完整字段，涵盖所有 AI 提炼标签。

4. 数据统计

GET /api/agent/stats

返回绘本总量、按状态/年龄/来源/主题/情感的分布统计。

完整 API 路由清单

路径方法说明
/api/agent/healthGET健康检查
/api/agent/booksGET搜索绘本
/api/agent/books/:idGET绘本详情
/api/agent/statsGET数据统计
/api/books/searchGET前端搜索
/api/books/:idGET前端详情
/api/books/featuredGET推荐绘本
/api/books/recommendPOST书单推荐
/api/auth/loginPOST管理员登录
/api/admin/booksGET/POST后台管理
/api/reading-plan/*多种阅读计划相关
/api/content/*多种内容生产（小红书/公众号）
/api/proxy/imageGET图片代理（防止豆瓣防盗链）

环境配置

变量用途
DATABASE_URLPostgreSQL 连接字符串（VPS 本地）
SILICONFLOW_API_KEYAI 提炼主模型 API Key
GLM_API_KEY多模态分析 API Key
OPENAI_BASE_URL代理地址（aiproxy.xin）
JWT_SECRET管理员 JWT 密钥
ADMIN_PASSWORD管理员登录密码
NEXT_PUBLIC_IMAGE_PROXY_ENABLED豆瓣图片代理开关

部署架构

用户 → Nginx (443/80) → certbot SSL
         ↓
    proxy_pass 127.0.0.1:3000
         ↓
    Next.js (PM2 fork mode)
         ↓
    Prisma → PostgreSQL (localhost:5432)

数据流水线

① 爬取：豆瓣/喵屋绘本 → raw_crawl 表
② AI 提炼：SiliconFlow Qwen72B 两阶段（结构化 → 叙事）→ book 表
③ 生成：MiniMax M2.7 生成书单、公众号/小红书内容

最新变更（2026-05-04）