pixpulse · API 文档

🚀

01

快速开始

前置依赖：Go 1.26+ · PostgreSQL 14+ · Redis 6+

bash

# 准备 PG 数据库和角色
psql -U postgres -c "CREATE ROLE pixpulse WITH LOGIN PASSWORD 'pixpulse';"
psql -U postgres -c "CREATE DATABASE pixpulse OWNER pixpulse;"

# 配置
cp .env.example .env
# 编辑 DATABASE_URL / REDIS_URL（默认指向本地）

# 编译 + 启动
make build              # 或: go build -o bin/pixpulse.exe ./cmd/pixpulse
./pixpulse.bat start    # Windows  · Linux 用 ./pixpulse.sh start

打开 http://localhost:8688/dashboard 启用源后，调度器立即触发一次抓取，之后按 fetch_interval 周期更新。

⚡

02

API endpoint 速查

所有 GET 端点都走 Redis 缓存；POST /refresh 是唯一触发抓取的端点。

方法	路径	用途	缓存
GET	/api/v1/health	健康检查（pg/redis/scheduler 状态）	—
GET	/api/v1/dashboard?category=hot	按分类聚合（推荐接入）	✓
GET	/api/v1/source/:slug/items	单源分页条目	✓
GET	/api/v1/source/:slug/raw	单源原始 JSON（调试用）	✓
GET	/api/v1/feed/:slug?format=rss	RSS / Atom feed（兼容阅读器）	✓
GET	/api/v1/latest?format=markdown	LLM 友好的纯文本	✓
GET	/api/v1/search?q=AI&format=markdown	跨源搜索（多关键词 AND）	✓
GET	/api/v1/metrics?slugs=gold,crypto	工具卡片批量	✓
POST	/api/v1/source/:slug/refresh	手动同步刷新（触发抓取）	触发抓取

Tip 调用方只要不调 POST /refresh，就 100% 读缓存。

AI GET /openapi.json 暴露 OpenAPI 3.0.3 spec（9 个只读端点，带 ETag），供 AI 工具直接消费。详见 AI 集成指南。

🔌

03

第三方接入（以 pixGallery 为例）

3.1 配置后端 API base URL

env

# pixGallery/.env
PIXPULSE_API_BASE_URL=http://localhost:8688/api/v1

3.2 重写 `fetch_feed()`

python

import os, httpx

PIXBASE = os.getenv("PIXPULSE_API_BASE_URL", "http://localhost:8688/api/v1")

def fetch_feed(source) -> list[dict]:
    """从 pixpulse 拉一个源的最新条目（读缓存，毫秒级）"""
    url = f"{PIXBASE}/source/{source.slug}/items?size=50"
    with httpx.Client(timeout=10) as client:
        resp = client.get(url)
        resp.raise_for_status()
        return resp.json()["data"]["items"]

3.3 字段映射（pixpulse Item → 业务方 NewsItem）

pixpulse 字段	业务方字段	说明
guid	guid	去重主键
title	title	标题
url	url	原文链接
summary	summary	摘要
author	author	作者
image_url	image_url	封面图
published_at	published_at	RFC3339 字符串
extra	extra_json	dict，需 json.dumps
rank	—	丢弃或塞进 extra

3.4 seed 文件改造

把原本的 RSSHub route 字段直接换成 pixpulse 的 slug：

diff

# 改前：{"slug": "zhihu-hotlist", "rsshub_route": "/zhihu/hotlist", ...}
# 改后：{"slug": "zhihu-hotlist", "pixpulse_slug": "zhihu-hotlist", ...}

或者更彻底：业务方不再维护源清单，直接 GET /api/v1/admin/sources 同步 pixpulse 的源列表。

⚠️

调度建议

不要在业务方再跑 sync_source 调 pixpulse 的 refresh —— pixpulse 自己有 cron 调度。业务方只需周期性（比如每 5 分钟）调 GET /dashboard?category=hot 拉缓存数据即可。

🔐

04

鉴权说明

local 模式（默认）

·所有 API 无鉴权直接开放
·CORS 全开
·限速关闭
·适合本地开发 / 内网部署

public 模式

·DEPLOY_MODE=public
·管理 API 需 Bearer JWT
·CORS 白名单
·匿名 60 r/min，登录 300 r/min
·登录: POST /api/v1/auth/login

bash

# public 模式生成密码哈希
go run ./cmd/hashpw "your-password"
# 输出 $2a$10$... 写入 .env 的 ADMIN_PASSWORD_HASH

# 登录获取 token
curl -X POST http://localhost:8688/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-password"}'

# 带 token 调管理 API
curl -H "Authorization: Bearer " \
  http://localhost:8688/api/v1/admin/sources

📚

05