同一篇内容要发到多个平台，手工复制容易漏字段、改错标题、丢链接。这份文档说明如何配置同步接口、把源站字段映射到目标平台，并用核对清单确认同步结果一致。

一、适用范围

• 适用：把站点文章同步到内容平台、社区或内部知识库；新增一个同步目标；接口字段变更后的映射调整；定期核对同步的完整性与一致性。
• 不适用：平台账号的注册与权限审批；跨平台评论与互动数据的回流；平台侧的审核规则与侵权判定，由平台方处理。

二、准备工作

项目	要求	检查方法
源数据	文章源文件在 /srv/axis/docs，字段齐全且可解析	抽查含标题、正文、标签、封面四类字段
接口凭据	目标平台的接口地址与令牌已申请，令牌不入库	凭据存于权限 600 的环境文件
字段清单	源字段与目标字段各列一列，标注必填	对照平台接口文档逐项确认
测试账号	每个平台至少一个可写测试账号	手工调用一次列表接口确认可用
工具	curl、jq 可用	curl --version、jq --version

• 首次同步只推一篇测试文章，确认字段与排版后再批量执行。
• 同步前对源数据做一次快照，出现覆盖问题时能回退。

三、操作步骤

本节拆成三个子步骤，建议按顺序执行；每一步完成后先确认结果，再进入下一步。

3.1 接口配置

在配置文件中登记平台接口地址、认证方式与超时重试策略，并用只读接口验证连通性与权限。配置与凭据分开存放：配置文件可以进版本库，凭据只能通过环境变量读取，重试只对超时与 5xx 生效。详见 3.1 接口配置。

3.2 字段映射

把源站字段逐项映射到目标平台字段，处理必填项缺失、富文本清洗与图片地址改写。映射表要显式写出类型转换，字符串与数组混用是 422 错误最常见的来源。详见 3.2 字段映射。

3.3 同步检查

同步后按唯一标识回查目标平台，比对标题、正文摘要、标签与链接，确认无重复、无遗漏。回查要按 ID 而不是按标题，标题重复时检索结果无法区分新旧记录。详见 3.3 同步检查。

三步之间不要跳步：接口没通就改映射，只会把 401 与 422 混在一起；映射没验证就批量同步，会把错误内容推到所有平台。批量执行前保留源数据快照，出错时至少能按快照重建。

四、验证方法

1. 执行 curl -sS -H "Authorization: Bearer $SYNC_TOKEN" https://api.example.com/v1/health | jq .，预期返回正常状态字段；返回 401 时先换令牌，不要改接口地址。
2. 用 jq 检查映射结果：jq -r '.title, .tags | @csv' /srv/axis/sync/payload.json，预期字段非空且格式符合目标要求，标签必须是数组而不是逗号分隔的字符串。
3. 推一篇测试文章后，用 curl 按文章 ID 回查，预期标题与源站一致，正文中无残留的本地图片路径，长度差异可解释为清洗而非截断。
4. 连续执行两次同一篇文章，预期目标平台只保留一条记录或返回“已存在”，不产生重复；出现重复说明幂等键没有生效，必须停止批量任务。

五、常见问题

现象	可能原因	处理方式
接口返回 401	令牌过期或认证头格式错误	重新申请令牌，确认 Authorization 头格式
接口返回 422	必填字段缺失或类型不符	对照字段清单补齐，注意数组与字符串的区别
正文图片无法显示	图片仍是相对路径或内网地址	映射时改写为 https://cdn.example.com/ 绝对地址
同一文章同步出多条	唯一标识不稳定或未做去重	用固定业务 ID 作为幂等键，先查后写
标签丢失	目标平台字段名不同或数量超限	按平台字段名映射，超出部分截断并记录

六、回滚与注意事项

• 回滚：保留源数据快照与上一次成功的映射配置；出现批量错发时先停用同步任务，再按 ID 逐条删除或覆盖目标记录。
• 注意：令牌只放在环境变量或密钥文件中，不要写进配置文件、日志与提交历史。
• 注意：批量同步前必须做一次单篇试跑，确认字段、图片与排版后再扩大范围。

上一页3.3 发送验证

下一页3.1 接口配置