Skip to content

Commit bdb6043

Browse files
committed
docs: design CSDN publishing via browser login and signed API
1 parent 6ec11ef commit bdb6043

2 files changed

Lines changed: 220 additions & 0 deletions

File tree

‎docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@
3434
- `admin-information-architecture.md`
3535
- `admin-data-model.md`
3636
- `admin-data-model-fields.md`
37+
- `csdn-publishing.md`:CSDN 自动发布方案(设计稿)
3738

3839
### `docs/operations/`
3940

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
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

Comments
 (0)