|
| 1 | +# CSDN 自动发布方案 |
| 2 | + |
| 3 | +状态:设计稿,尚未实现。实现前需先完成本文“前置验证”一节。 |
| 4 | + |
| 5 | +## 结论 |
| 6 | + |
| 7 | +CSDN 采用“登录照 X、发文走接口”的方案: |
| 8 | + |
| 9 | +- **登录**:和 X 一样,工作人员通过 VNC 在服务器上的专用 Chrome Profile 中人工扫码登录一次,登录状态保存在 Profile 里。 |
| 10 | +- **发文**:不模拟操作编辑器页面。由宿主机上的会话服务从 Profile 中读出 CSDN cookie,API 在服务端计算 `x-ca-*` 签名后直接调用 CSDN 网页编辑器使用的 `saveArticle` 接口。 |
| 11 | +- **接入**:作为 `apps/api/src/lib/external-publishing.ts` 中的一个新 channel(`csdnChannel`),复用现有的排队、防重复、外部 ID 回写、成功与失败审计。 |
| 12 | + |
| 13 | +## 为什么不用其他方案 |
| 14 | + |
| 15 | +| 方案 | 不采用的原因 | |
| 16 | +|---|---| |
| 17 | +| 像 InfoQ 一样服务端账号密码登录 | 社区现有工具都依赖人工提供 cookie 或扫码,CSDN 登录大概率有人机验证;绕过验证码违反条款且不稳定 | |
| 18 | +| 完全照搬 X,模拟操作编辑器 | 长文逐字输入慢,且 Markdown 编辑器的自动补全、自动缩进会改乱内容;发布弹窗控件多,改版即失效 | |
| 19 | +| 工作人员手动粘贴 cookie 到后台 | 可行的备选。缺点是 cookie 过期后需要人工重新复制,体验不如 VNC 扫码;见“与 X 浏览器方案的关系” | |
| 20 | + |
| 21 | +CSDN 没有官方发文 API。`saveArticle` 是从网页编辑器中观察到的内部接口,可能随时变化,也可能违反 CSDN 服务条款。应使用社区专用账号,并控制发布频率。 |
| 22 | + |
| 23 | +## 运行时结构 |
| 24 | + |
| 25 | +```text |
| 26 | +admin 保存 / 发布内容 |
| 27 | + | |
| 28 | + v |
| 29 | +apps/api external-publishing.ts |
| 30 | + | csdnChannel.publish() |
| 31 | + | |
| 32 | + |-- 1. GET /cookies ──Unix socket──> 宿主机 CSDN 会话服务 |
| 33 | + | | |
| 34 | + | v |
| 35 | + | 无界面 Chrome + CSDN Profile |
| 36 | + | 读取 .csdn.net cookie 后立即关闭 |
| 37 | + | |
| 38 | + |-- 2. 计算 x-ca-signature |
| 39 | + | |
| 40 | + `-- 3. POST https://bizapi.csdn.net/blog-console-api/v3/mdeditor/saveArticle |
| 41 | + 返回文章 ID,回写 csdn_article_id |
| 42 | +``` |
| 43 | + |
| 44 | +API 容器内没有 Chrome,所以 cookie 只能由宿主机进程读取。这与 X publisher 的边界一致:Profile、Chrome 和会话服务属于宿主机维护资源,不进入 API 镜像或 `ops/.env`。 |
| 45 | + |
| 46 | +与 X 不同的是,宿主机服务只负责**提供 cookie**,签名和调用接口都在 API 内完成。这样发文逻辑可以用 TypeScript 写单元测试,失败信息也直接进入 API 日志和审计表。 |
| 47 | + |
| 48 | +## 组件 |
| 49 | + |
| 50 | +### 1. 宿主机 CSDN 会话服务 |
| 51 | + |
| 52 | +位置:`scripts/csdn-browser/`,结构参照 `scripts/x-browser/`。 |
| 53 | + |
| 54 | +- `session-server.mjs`:监听 Unix socket,提供: |
| 55 | + - `GET /ready`:存活检查。 |
| 56 | + - `GET /cookies`:用无界面 Chrome 打开 CSDN Profile,通过 CDP 读取 `.csdn.net` 域下的 cookie,确认已登录后返回 cookie 字符串和当前账号名,随后关闭浏览器。 |
| 57 | +- 读取 cookie 使用浏览器自身的 CDP 接口,不直接解密 Profile 中的 SQLite cookie 库,避免依赖 Linux Chrome 的密钥存储细节。 |
| 58 | +- 请求串行处理。Chrome Profile 被登录会话占用时(`login-start` 期间),直接返回明确错误,不等待。 |
| 59 | +- 日志沿用 X publisher 的格式:每行一条带时间戳的 JSON,追加写入,超过大小后轮转。**日志中不得写入 cookie 值**,只记录 cookie 名称列表和账号名。 |
| 60 | +- `session-service.sh`:`start | stop | status`,参照 `publisher-service.sh`。 |
| 61 | + |
| 62 | +默认路径: |
| 63 | + |
| 64 | +| 项 | 路径 | |
| 65 | +|---|---| |
| 66 | +| Profile | `/home/rebase/.local/share/rebase-csdn-profile` | |
| 67 | +| 状态目录 | `/home/rebase/.local/state/rebase-csdn-browser` | |
| 68 | +| Socket(宿主机) | `/home/rebase/.local/state/rebase-csdn-browser/session.sock` | |
| 69 | +| Socket(API 容器内) | `/var/run/rebase-csdn-browser/session.sock` | |
| 70 | + |
| 71 | +CSDN 必须使用独立 Profile,不能与 X 共用:同一个 Chrome 用户目录不能同时被两个浏览器进程打开。 |
| 72 | + |
| 73 | +### 2. 远程登录 |
| 74 | + |
| 75 | +复用 `scripts/x-browser/remote-login-session.sh` 的 Xvfb + x11vnc + Chrome 流程,需要先把以下写死的值改为可配置: |
| 76 | + |
| 77 | +- `LOGIN_URL`:CSDN 使用 `https://passport.csdn.net/login` |
| 78 | +- 状态目录、Profile 目录 |
| 79 | +- 显示编号与 VNC 端口:CSDN 使用 `:98` 与 `5908`,避免与 X(`:97`、`5907`)同时登录时冲突 |
| 80 | + |
| 81 | +`ops/manage.sh` 新增一组子命令,与 `x` 对称: |
| 82 | + |
| 83 | +```bash |
| 84 | +./ops/manage.sh csdn check # 通过会话服务确认登录状态和账号 |
| 85 | +./ops/manage.sh csdn login-start # 启动远程登录并打开 VNC |
| 86 | +./ops/manage.sh csdn login-stop # 关闭 Chrome、备份 Profile、关闭隧道 |
| 87 | +./ops/manage.sh csdn session-start |
| 88 | +./ops/manage.sh csdn session-stop |
| 89 | +./ops/manage.sh csdn session-status |
| 90 | +./ops/manage.sh csdn backup |
| 91 | +``` |
| 92 | + |
| 93 | +### 3. API channel:`apps/api/src/lib/csdn.ts` |
| 94 | + |
| 95 | +导出 `csdnChannel: ExternalChannel`: |
| 96 | + |
| 97 | +- `name: 'CSDN'`,`auditKey: 'csdn'`,`idField: 'csdnArticleId'` |
| 98 | +- `isConfigured`:`CSDN_PUBLISHER_ENABLED=true` 且 socket 路径与签名配置齐全 |
| 99 | +- `publish(input)`: |
| 100 | + 1. 通过 socket 获取 cookie;失败时报 `CSDN 登录状态无效,请执行 ./ops/manage.sh csdn login-start 重新登录`。 |
| 101 | + 2. 构造请求体(见“内容映射”)。 |
| 102 | + 3. 计算签名并调用 `saveArticle`,超时 30 秒。 |
| 103 | + 4. 解析返回的文章 ID 和地址;业务码非成功时,把 CSDN 返回的 `code`、`msg` 放进错误详情。 |
| 104 | + |
| 105 | +纯函数单独导出以便测试:`buildCsdnArticle(input)`、`signCsdnRequest(...)`、`parseCsdnResponse(...)`,在 `csdn.test.ts` 中覆盖。 |
| 106 | + |
| 107 | +### 4. 签名 |
| 108 | + |
| 109 | +按社区资料,每个发往 `bizapi.csdn.net` 的请求需要: |
| 110 | + |
| 111 | +| 请求头 | 说明 | |
| 112 | +|---|---| |
| 113 | +| `x-ca-key` | 固定值,来自 CSDN 前端代码 | |
| 114 | +| `x-ca-nonce` | 每次请求新生成的 UUID | |
| 115 | +| `x-ca-signature-headers` | `x-ca-key,x-ca-nonce` | |
| 116 | +| `x-ca-signature` | `base64(HMAC-SHA256(appSecret, stringToSign))` | |
| 117 | + |
| 118 | +`stringToSign` 由请求方法、`Accept`、`Content-Type`、`x-ca-key`、`x-ca-nonce` 和带查询串的路径按换行拼接。具体字段顺序和空行以前置验证中抓到的真实请求为准。 |
| 119 | + |
| 120 | +`x-ca-key` 和 `appSecret` 放在环境变量里,CSDN 更换时只需改配置、重新部署,不改代码。 |
| 121 | + |
| 122 | +### 5. 数据模型 |
| 123 | + |
| 124 | +`articles`、`events`、`geekdaily_episodes` 三张表新增可空列 `csdn_article_id`(与 `infoq_article_uuid`、`learnblockchain_article_id`、`x_post_id` 并列),同步修改: |
| 125 | + |
| 126 | +- `packages/db/src/schema/index.ts` 与一次新 migration |
| 127 | +- `packages/shared/src/content.ts` 中三个 admin record 类型 |
| 128 | +- 三个内容模块里把行映射为 record 的函数 |
| 129 | +- `external-publishing.ts` 中的 `ExternalIdField` 与 `externalChannels` |
| 130 | + |
| 131 | +### 6. 管理端 |
| 132 | + |
| 133 | +- 新增手动发布路由:`POST /articles/:id/csdn-publish`、`/events/:id/csdn-publish`、`/geekdaily/:id/csdn-publish`,权限与现有外部发布路由一致。 |
| 134 | +- 编辑页展示 CSDN 发布状态和文章链接;是否同时加“手动发布到 CSDN”按钮,与 X、登链的按钮一起决定。 |
| 135 | + |
| 136 | +## 内容映射 |
| 137 | + |
| 138 | +| CSDN 字段 | 取值 | |
| 139 | +|---|---| |
| 140 | +| 标题 | `contentSources` 已有规则:文章原标题、`活动|…`、`极客日报|…` | |
| 141 | +| 正文 | Markdown 正文,末尾追加 `原文链接:<Rebase 链接>`,与 InfoQ、登链一致 | |
| 142 | +| 摘要 | 内容摘要,超出 CSDN 上限时截断 | |
| 143 | +| 标签 | 内容标签取前若干个;为空时使用默认标签(CSDN 要求至少一个) | |
| 144 | +| 状态 | 正式发布 `1`。**禁止使用 `0`**,社区记录显示 `0` 可能被直接公开 | |
| 145 | +| 文章类型 | 待定,见“待确认问题” | |
| 146 | +| 可见性 | 公开 | |
| 147 | +| 封面、分类 | 默认不设置,前置验证确认是否必填 | |
| 148 | + |
| 149 | +## 频率、重复与失败处理 |
| 150 | + |
| 151 | +- **频率**:CSDN 两次写操作之间至少间隔约 11 秒。channel 本身已串行排队,额外在 `csdn.ts` 中保证与上一次请求的最小间隔。 |
| 152 | +- **没有防重复机制**:`saveArticle` 没有幂等键。请求已发出但超时、连接中断或返回 5xx 时,文章可能已经创建。这种情况: |
| 153 | + - 不自动重试; |
| 154 | + - 报错“CSDN 发布结果不确定,请先到 CSDN 创作中心确认后再决定是否重试”; |
| 155 | + - 由现有失败审计记录为 `*.csdn_publish_failed`。 |
| 156 | +- **cookie 失效**:请求前由会话服务确认登录;接口返回未登录类错误时,同样给出重新登录的提示,不重试。 |
| 157 | +- **日志**:成功与失败都走 `external-publishing.ts` 已有的 JSON 日志和审计记录。错误详情中可以包含 CSDN 返回的业务码和消息,**不得包含 cookie 和签名值**。 |
| 158 | + |
| 159 | +## 配置 |
| 160 | + |
| 161 | +`ops/.env` 新增: |
| 162 | + |
| 163 | +| 变量 | 说明 | 敏感 | |
| 164 | +|---|---|---| |
| 165 | +| `CSDN_PUBLISHER_ENABLED` | 是否启用 CSDN 发布,默认 `false` | 否 | |
| 166 | +| `CSDN_SESSION_SOCKET_PATH` | API 容器内的会话服务 socket,默认 `/var/run/rebase-csdn-browser/session.sock` | 否 | |
| 167 | +| `CSDN_CA_KEY` | 签名用 `x-ca-key` | 否 | |
| 168 | +| `CSDN_CA_SECRET` | 签名用 appSecret | 是 | |
| 169 | + |
| 170 | +`infra/production/docker-compose.yml` 的 `api` 服务新增 volume: |
| 171 | + |
| 172 | +```yaml |
| 173 | +- ${CSDN_SESSION_STATE_DIR:-/home/rebase/.local/state/rebase-csdn-browser}:/var/run/rebase-csdn-browser |
| 174 | +``` |
| 175 | +
|
| 176 | +上线后同步更新 `docs/operations/production-config.md`,并新增 `docs/operations/csdn-login-runbook.md`(参照 `x-login-runbook.md`)。 |
| 177 | + |
| 178 | +## 安全边界 |
| 179 | + |
| 180 | +- CSDN Profile 等同于账号会话凭据,权限仅限 `rebase` 用户,不提交、不下载、不通过 `ops/.env` 同步。 |
| 181 | +- cookie 只在宿主机会话服务与 API 进程内存中短暂存在,不写入数据库、日志或审计表。 |
| 182 | +- 会话服务 socket 权限 `600`,只挂载给 API 容器。 |
| 183 | +- VNC 只监听远端 `127.0.0.1`,通过 SSH 隧道访问,登录结束必须执行 `login-stop`。 |
| 184 | + |
| 185 | +## 与 X 浏览器方案的关系 |
| 186 | + |
| 187 | +本方案只在**登录**环节依赖服务器上的 Chrome。API 通过一个“获取 cookie”的接口拿登录状态,不关心 cookie 来源。 |
| 188 | + |
| 189 | +如果后续决定不再在服务器上运行 Chrome(X 浏览器自动化的遗留问题),只需把 cookie 来源换成“工作人员在后台粘贴 cookie,加密存库”(与 InfoQ 存密码的方式相同),签名、发文和 channel 部分不变。 |
| 190 | + |
| 191 | +## 前置验证 |
| 192 | + |
| 193 | +写代码前用 CSDN 测试账号完成以下验证,结果补充到本文: |
| 194 | + |
| 195 | +1. **登录保持**:通过 VNC 在独立 Profile 中扫码登录,关闭后用无界面 Chrome 重新打开,确认登录状态还在、没有额外验证。 |
| 196 | +2. **cookie 读取**:通过 CDP 读出 `.csdn.net` cookie,确认哪些 cookie 是发文必需的。 |
| 197 | +3. **接口与签名**:在编辑器里手动保存一篇草稿,抓下 `saveArticle` 的请求和响应,确认接口路径、请求体字段、`x-ca-key`、`stringToSign` 格式。 |
| 198 | +4. **服务端调用**:用本地脚本自行签名,以草稿状态 `2` 保存一篇文章,确认能拿到文章 ID;再验证状态 `1` 的正式发布。 |
| 199 | +5. **内容兼容**:确认 CSDN 对 Markdown(列表、代码块、表格)、外链图片、标签数量和摘要长度的处理。 |
| 200 | +6. **有效期**:观察数天,记录登录状态的实际失效时间。 |
| 201 | + |
| 202 | +## 实现步骤 |
| 203 | + |
| 204 | +按以下顺序提交,每步单独一个提交: |
| 205 | + |
| 206 | +1. 数据模型:新增 `csdn_article_id` 列、migration 和共享类型。 |
| 207 | +2. 远程登录脚本参数化,新增 CSDN 会话服务与 `manage.sh csdn` 子命令。 |
| 208 | +3. API:`csdn.ts`、单元测试、配置项,接入 `externalChannels` 与手动发布路由。 |
| 209 | +4. 部署配置与运维文档:compose volume、`production-config.md`、`csdn-login-runbook.md`。 |
| 210 | +5. 管理端展示 CSDN 发布状态。 |
| 211 | + |
| 212 | +上线顺序:先部署代码并保持 `CSDN_PUBLISHER_ENABLED=false`,完成登录和 `csdn check` 后,再打开开关并发布一篇内容验证。 |
| 213 | + |
| 214 | +## 待确认问题 |
| 215 | + |
| 216 | +- **文章类型**:Rebase 自有文章标为“原创”还是“转载”?极客日报以外链汇总为主,是否适合标原创? |
| 217 | +- **发布范围**:文章、活动、极客日报三类是否都发 CSDN? |
| 218 | +- **自动发布**:内容发布后是否像 InfoQ、登链、X 一样自动发到 CSDN,还是只提供手动发布? |
| 219 | +- **账号**:使用哪个 CSDN 账号作为社区专用账号? |
0 commit comments