牛牛GEO内容推送开放协议 v1.0

让你的官网一键接收牛牛GEO平台生成的内容。

这是什么

牛牛GEO平台生成的文章，可以通过标准 HTTP API 直接推送到你自己的官网，无需人工复制粘贴。

由于每个官网的技术栈、数据库结构、后台系统都不同，我们无法逐一适配。因此我们定义了一套开放的推送协议：你只需在自己的官网部署一个「接收器」（我们提供了常见技术栈的开箱即用模板），配置好数据库映射和密钥，平台就能把文章直接写入你的官网数据库。

支持的技术栈

你的官网类型	接收器获取方式	说明
PHP + MySQL 自建站	平台添加站点后下载已配好密钥的版本	虚拟主机/宝塔/LNMP 均可，下载后只需配置数据库
WordPress	平台添加站点后下载已配好密钥的版本	放入插件目录启用即可，零配置，自动落地封面图到媒体库
Node.js	receiver-node.js 参考模板	Express + MySQL，密钥需从平台复制后手动填入
Java	receiver-spring-boot.java 参考模板	Spring Boot 示例，密钥需从平台复制后手动填入
.NET	receiver-dotnet.cs 参考模板	ASP.NET Core Minimal API 单文件（.NET 6+），密钥需从平台复制后手动填入
Python / 其他技术栈	参照本协议自行实现	协议完全开放，任何语言都能实现

用 Java / Node / .NET / Python 等技术开发的同学：在本页下载对应参考模板或参照协议规范自行实现，密钥在平台站点列表点「复制密钥」获取。

对接流程（4 步）

1. 添加站点：在牛牛GEO平台「官网管理」点「添加站点」，点「随机生成」自动生成密钥（生成后明文可见，保存后隐藏）
2. 下载接收器：保存成功后直接下载已配好密钥和站点信息的接收器文件（PHP 通用版 / WordPress 插件版），无需手动复制粘贴任何配置；Node/Java/.NET 等其他技术栈在本页下载参考模板后，用站点列表的「复制密钥」手动填入
3. 部署到官网：
   • PHP 版：上传到网站可访问目录（如根目录），只需配置数据库连接信息
   • WordPress 版：放入 wp-content/plugins/ngeo-receiver/ 目录并在后台启用，无需任何其他配置
   • Node/Java/.NET 版：集成到你的服务，用 Nginx 反代对外暴露
4. 两步测试连接：回到站点列表，先点「测试密钥」，平台发送 verify 请求验证接口可达与密钥正确；再点「测试传输」，平台真实推送一篇测试文章（默认草稿，可删除）验证数据库写入。两步都通过才算连接成功

密钥说明

密钥（secret_key）由平台在添加站点时自动生成（64 位随机字符串），并自动预填到你下载的 PHP / WordPress 接收器文件中，全程无需手动复制。

Node / Java / .NET / Python 等其他技术栈：添加站点后，在站点列表点「复制密钥」获取完整密钥，手动填入你的接收器配置区，两边完全一致即可通过认证。

密钥相当于推送接口的密码，请勿泄露；如怀疑泄露，在平台重新生成密钥并重新下载部署接收器即可。

站点状态说明

站点列表的状态徽章对应两步测试的进度：

状态	含义
未测试	站点已建档，还未做过连接测试
密钥通过·待传输测试	第一步「测试密钥」通过：接口可达、密钥正确，还未验证数据库写入
已连通	第二步「测试传输」也通过，可以正式发布内容
异常	测试失败，查看站点下方的错误信息定位（会标明失败在哪一步）

---

协议规范

接口约定

• 传输协议：HTTPS（生产环境强制要求）
• 请求格式：application/json
• 响应格式：application/json
• 统一响应结构：

{ "code": 0, "msg": "提示信息", "data": { } }

code = 0 表示成功，非 0 表示失败。

认证方式（三选一）

方式	位置	示例
Bearer Token（推荐）	请求头 Authorization	Authorization: Bearer 你的密钥
API Key 请求头	请求头 X-API-Key	X-API-Key: 你的密钥
URL 参数（兜底）	Query 参数 api_key	?api_key=你的密钥

认证失败返回：{ "code": 1001, "msg": "认证失败：密钥不正确" }

三种行为

1. 连通性测试

平台「添加站点」后点击「测试密钥」时调用（两步测试的第一步，不触碰数据库）。

POST /receiver.php
Authorization: Bearer 密钥
{"_action": "verify"}

成功响应：

{ "code": 0, "msg": "连接成功" }

2. 获取栏目列表

平台发布前调用，让用户选择文章归属的栏目/分类。

GET /receiver.php          （或 POST {"_action": "channels"}）
Authorization: Bearer 密钥

成功响应：

{
  "code": 0,
  "msg": "success",
  "data": [
    { "id": 1, "name": "公司新闻", "parent_id": 0 },
    { "id": 2, "name": "行业动态", "parent_id": 0 }
  ]
}

data 为栏目数组，无栏目功能时返回空数组即可。

3. 推送文章

POST /receiver.php
Authorization: Bearer 密钥

推送载荷字段

所有字段均由平台自动组装推送，接收器无需为可选字段做专门处理（收到就存，没收到就跳过）。

每次必推（平台自动生成，无需你操心）：

字段	类型	说明
title	string	文章标题
content	string	正文，HTML 格式
summary	string	文章摘要（未填写时自动截取正文前 150 字）
seo_keywords	string	SEO 关键词（由标签自动生成）
seo_description	string	SEO 描述（由摘要自动生成）
source_id	string	牛牛GEO平台文章唯一 ID，用于幂等去重
status	int	1=发布（默认），0=草稿

按文章实际内容条件推送（有才推）：

字段	类型	说明
thumbnail	string	封面图 URL
images	string[]	正文配图 URL 数组
tags	string[]	标签数组
category_id	int/string	栏目 ID（用户在发布时选择栏目才推送，来自「获取栏目」返回的 id）

特殊字段：

字段	类型	说明
_action	string	verify / channels，见上方行为说明

成功响应

{ "code": 0, "msg": "文章接收成功", "data": { "id": 123 } }

data.id 为新文章在你数据库中的主键。

幂等去重（推荐实现）

同一 source_id 重复推送时，不产生重复记录，直接返回已存在的文章：

{ "code": 0, "msg": "文章已存在，跳过重复推送", "data": { "id": 123, "exists": true } }

错误码表

code	含义
0	成功
1001	认证失败（密钥错误/未配置）
1002	IP 不在白名单 / 要求 HTTPS
1003	请求过于频繁（触发速率限制）
2001	参数错误（标题缺失、请求方法不对等）
3001	数据库写入失败
5000	服务器内部错误

---

安全建议

1. 强制 HTTPS：生产环境务必通过 HTTPS 访问接收器，避免密钥明文传输（receiver.php 可开启 require_https）
2. 密钥强度：使用 32 位以上随机字符串，可用 openssl rand -hex 32 生成
3. IP 白名单：部署稳定后，在接收器配置中只放行牛牛GEO平台的出口 IP
4. 密钥轮换：怀疑泄露时，两端同时更换密钥即可立即生效
5. 文件位置：PHP 版接收器不要放在可列目录的位置，关闭目录浏览
6. 权限最小化：数据库账号只授予目标表的 INSERT/SELECT 权限

测试命令

部署完成后，可用 curl 自检（替换为你的实际地址和密钥）：

# 连通性测试
curl -X POST https://你的域名/receiver.php \
  -H "Authorization: Bearer 你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"_action":"verify"}'

# 获取栏目
curl https://你的域名/receiver.php \
  -H "Authorization: Bearer 你的密钥"

# 推送测试文章
curl -X POST https://你的域名/receiver.php \
  -H "Authorization: Bearer 你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"title":"测试文章","content":"<p>这是正文</p>","source_id":"test-001","status":1}'

WordPress 版把地址换成 https://你的域名/wp-json/niugeo/v1/push； Node 版为 http://127.0.0.1:3900/receiver； Java 版为 https://你的域名/ngeo/push； .NET 版为 https://你的域名/ngeo/push。

实现自检清单

自行实现接收器时，请逐项确认：

• POST {"_action":"verify"} 返回 code=0
• GET 请求返回栏目数组（无栏目功能返回空数组）
• POST 完整载荷能写入文章并返回新文章 ID
• 三种认证方式至少支持 Bearer Token
• 所有响应均为 {code, msg, data} 结构，成功时 code=0
• 错误密钥返回 code=1001
• （推荐）支持 source_id 幂等去重

常见问题

Q：我的官网不是 PHP/WordPress 怎么办？ A：用 Java / Node / .NET 的同学可下载本页的参考模板，密钥从平台站点列表「复制密钥」获取；Python 等其他技术栈参照本协议规范自行实现「认证 + 三个行为 + 统一响应格式」，参照上方自检清单。

Q：密钥是谁给的？ A：由平台在添加站点时自动生成，并自动预填到下载的 PHP / WordPress 接收器文件中；其他技术栈用站点列表的「复制密钥」按钮获取。

Q：只点了「测试密钥」就显示成功，但发布还是失败？ A：「测试密钥」只验证接口可达和密钥正确，不碰数据库。请继续点「测试传输」验证真实写入——数据库未配置、表结构不对等问题只有这一步才能发现。两步都通过（状态变为「已连通」）才算对接完成。

Q：发布失败怎么排查？ A：先用 curl 按上方命令自检；开启接收器的日志功能查看请求记录；确认两端密钥完全一致、接口地址可公网访问。

Q：图片会不会失效？ A：推送时图片以 URL 形式传递，但两个官方接收器都会自动「落地」：PHP 版默认开启图片落地，封面图/配图自动下载到你自己的服务器并替换为本地地址；WordPress 版自动把封面图下载进媒体库。图片文件最终都在你自己服务器上，不依赖平台外链。