内容港 Harbor

English · 中文

内容进港，全网分发。 文章存在你自己的库里，AI 通过 API / MCP 全权管理：写、改、发、更新、看账号全部内容。 自带内置浏览器，扫码登录一次就长期在线，不依赖你日常的 Chrome / Edge 开着。

后端重构已完成：后端已从旧版 cli.py / core / server 迁移到 backed/（FastAPI 分层架构）， 原 REST 端点（发布 / 原地更新 / 同步 / AI / 账号）全部保留，并新增统一 CRUD 资源接口（/api/v1）。 开发规范见 AGENT.md，架构说明见 ARCHITECTURE.md。

30 秒看懂它能干什么

• 多平台一键分发：一篇文章，勾选平台，同时发到 10 个平台（掘金 / CSDN / 博客园 / 知乎 / 思否 / B站专栏 / 头条号 / 开源中国 / 51CTO / 自建博客）。

• 原地更新，不是重发：改了文章，它去打开各平台的编辑页改原文，URL 不变、评论点赞都在。

• AI 全权接管：内置 MCP Server + REST API，Claude 或任何脚本都能直接建文章、发布、抓取账号里的文章。

• 完全自托管：文章库、登录态、浏览器 profile 全在你自己的机器上，不依赖任何第三方 SaaS。

• 免扫码通道：博客园 / 51CTO / 自建博客走 MetaWeblog 协议，账号密码直发，一次配置长期免登录。

• 自带 Web 管理界面：明亮清爽的「晴空」主题，响应式适配桌面 / 平板 / 手机。

Related MCP server: Ghost CMS MCP Server

快速开始（后端 · FastAPI）

后端位于 backed/，基于 FastAPI，默认 SQLite、零外部依赖即可启动；生产可切 MySQL / PostgreSQL。

# 本地启动（仅依赖 uv，跨平台）
./start.sh          # Linux / macOS
start.bat           # Windows cmd
start.ps1           # PowerShell
# 或手动：
cd backed && uv sync && uv run uvicorn start:app --host 0.0.0.0 --port 8000 --reload

• API 文档：http://localhost:8000/docs

• 部署：见 deplay/（docker-compose + Dockerfile）

CLI 常用命令（在 backed/ 目录下运行）

cd backed
uv run python cli.py --headed login --platform juejin   # 扫码登录一次，登录态长期有效
uv run python cli.py status                             # 中台总览
uv run python cli.py publish --id 1 --platforms juejin,csdn   # 发布（--draft 只发草稿箱）
uv run python cli.py serve                              # 起 REST 服务（默认 http://127.0.0.1:8800）

旧版顶层 cli.py / core/ / server/ 已迁移：CLI 见 backed/cli.py，发布引擎见 backed/service/publishing/，REST 端点（含发布 / 原地更新 / 同步 / AI / 账号）见 backed/api/hub.py。

支持平台（10 个）

知乎 / 头条 / 开源中国的发布选择器参考社区实测（MultiPost-Extension 等），平台改版后跑 uv run python cli.py --headed diagnose --platform xxx 看现场、重抓结构即可。扩一个新平台照着任一适配器抄 150 行。

这是什么 / 不是什么

• ✅ 是：自托管的多平台内容分发中台。文章库、发布、原地更新、AI 写稿，全部在你自己机器上。

• ✅ 是：给 AI 程序用的内容 API。MCP Server + REST API 双入口，Claude / 任意脚本都能直接调用。

• ❌ 不是：群发垃圾内容的工具。发布内置限速（平台间隔 8-20s、文章间隔 30-90s），请在平台规则内使用。

一、为什么不用浏览器插件方案

代价：平台适配要自己写。目前 10 个平台已实现（见上方平台矩阵）， 扩平台照着 150 行抄一个即可。文章可以由 AI 直接写（backed/service/publishing/ai.py），接任何 OpenAI 兼容模型（DeepSeek / 豆包 / 通义 / Kimi / 智谱 / Ollama）。

二、架构

        AI（Claude / 你的脚本）
             │  MCP 协议   或   REST API
             ▼
   ┌──────────────────────┐
   │      业务层 service   │
   ├──────────────────────┤
   │  文章库 articles      │  唯一真源，AI 写/改都在这儿
   │  发布实例 publications │  文章×平台，存 post_id / edit_url
   │  任务流水 jobs        │  谁什么时候发了什么，失败原因可查
   └──────────┬───────────┘
              │
     内置 Chromium（每平台一个持久化 profile）
              │
     适配器：掘金 / CSDN / 知乎 / 思否 / B站 / 头条 / 开源中国 / 博客园 / 51CTO / 自建博客(WordPress/Typecho)
              │
     发布    列表    原地更新

原地更新靠三件事：发布时把 post_id 和 edit_url 存进 publications；列表时从 DOM 抓 edit_url（不猜 URL）；改文章时自动把已发布实例标成 pending，sync 一把推平。

三、命令行用法

CLI 入口在 backed/cli.py；以下命令请在 backed/ 目录下执行 （推荐 uv run python cli.py ...，也可在已装好依赖的环境里 python cli.py ...）。

# 1) 扫码登录（会弹出浏览器窗口，扫一次就存住了）
python cli.py login --platform juejin
python cli.py login --platform csdn

# 2) 确认登录态
python cli.py check --platform juejin

# 3) 导入一篇文章
python cli.py import-md --path ./my-post.md

# 4) 发布
python cli.py publish --id 1 --platforms juejin,csdn

# 5) 改文章 → 自动同步到所有已发平台（原地更新，不是新发一篇）
python cli.py update --id 1
# 或者一把推平所有改动
python cli.py sync

# 看看账号里已有什么
python cli.py refresh --platform juejin
python cli.py status

四、Web 管理界面

先把前端构建一次（cd web && pnpm install && pnpm build，产物落在 server/static/）， 再启动后端，浏览器打开 http://127.0.0.1:8000（cli.py serve 默认 http://127.0.0.1:8800）。 左边文章列表，中间编辑区，右边发布面板。

界面走「晴空」主题——明亮现代 SaaS 风：浅灰底 + 纯白卡片 + 飞书蓝主色， 圆角适中、无衬线字体、全链路 0 外部请求（离线可用），顶栏是分组工具条 （品牌 / 统计 / AI 状态 / 主操作），编辑器为绝对主角。

前端技术栈（web/ 目录，独立工程）：

响应式适配（窗口一变自动重排，不是简单的媒体查询隐藏）：

手机上还有个右下角浮动「发布」按钮，一点就开侧栏。

开发 / 构建：

cd web
pnpm install
pnpm dev        # 开发模式，:5173，自动代理 /api 到后端（默认 :8000）
pnpm build      # 构建到 server/static/，之后启动后端即可直接使用界面

改界面就改 web/src/，改完 pnpm build；构建产物不再随仓库提交， 未构建时后端只提供 REST API / MCP，Web 界面不生效。

五、让 AI 直接写

export AI_API_KEY=sk-xxx                       # 或写进 config.json
export AI_BASE_URL=https://api.deepseek.com/v1 # 通义/豆包/Kimi/智谱/本地 Ollama 都行
export AI_MODEL=deepseek-chat

python cli.py ai-write --topic "怎么用 AI 管内容中台" --words 2000
python cli.py ai-write --topic "Python 自动化" --publish juejin,cnblogs   # 写完直接发

python cli.py ai-rewrite --id 1 --instruction "改得更口语，补一个踩坑章节"
python cli.py ai-polish --id 1

AI 写完自动抽标题、生成摘要和 3-5 个标签，直接入库。改写/润色之后， 已发布的实例会自动标成待同步——sync 一把就推到各平台去。

Windows 一样跑，把 python 换成你的 Python 路径即可。

六、AI 怎么用

方式 A：MCP（推荐，AI 客户端直连）

配到客户端配置里：

{
  "mcpServers": {
    "content-hub": {
      "command": "python",
      "args": ["-m", "server.mcp_server"]
    }
  }
}

AI 拿到 13 个工具：

hub_status        中台总览
list_articles     列出文章
get_article       读全文
create_article    新建
edit_article      改文章（自动标记待同步）
publish_article   发布到指定平台
update_article    原地更新已发布的（不是新发一篇）
sync_pending      所有改动推平
refresh_platform  抓平台文章列表入库（AI 才看得见账号里有什么）
check_account     检查登录态
ai_write          AI 写一篇并入库，可顺手发布
ai_rewrite        AI 按指令改写（自动标记待同步）
ai_polish         AI 润色：修错别字、统一代码块语言、理顺结构

然后直接说人话：「写篇讲 XX 的文章发到掘金和 CSDN」「把 3 号文章标题改了同步到全部平台」「看看我账号里有哪些文章」。

方式 B：REST API（FastAPI 服务）

服务启动后（默认 http://127.0.0.1:8000，cli.py serve 默认 http://127.0.0.1:8800），提供两类接口。

1）业务端点（发布引擎，路径与原版保持一致）

2）统一 CRUD 资源（新增，挂在 /api/v1 下，统一响应信封 SuccessResponse / PaginationResponse）

每个资源提供：GET /（列表分页）、POST /（创建）、GET /{id}（详情）、 PUT /{id}（更新）、DELETE /{id}（删除）、PATCH /{id}/status（状态变更）。 交互式文档：http://localhost:8000/docs

七、验证码与人机识别：三层策略

先把话说清楚："绕过验证码"这个说法本身是个坑。

阿里云、极验、腾讯那类验证码，判定逻辑在服务端，前端 JS 加密后上报鼠标轨迹/环境指纹。 网上那些"破解"仓库（逆向滑块距离、训练模型识别缺口）的共同问题是： 平台一次风控升级就全部失效，而且账号被标记后直接封，代价远大于收益。

所以本项目的做法是三层递进——想办法不遇到 > 遇到一次就永久解决 > 真遇到了交人工：

L1 能走官方通道就不模拟浏览器（最彻底）

有的平台开放了协议接口，压根不会有验证码。这是首选。

python cli.py diagnose --platform cnblogs    # 看看这平台推荐怎么接

L2 反检测 + 登录态持久化（降低触发率）

backed/service/publishing/browser.py 里逐条抹平自动化痕迹：

配合 登录态持久化：一次登录存进 data/profiles/<平台>_<账号>/， 之后复用，把"过验证"从每天一次压到一次性。

L3 半自动 + 人工交接（真弹了怎么办）

backed/service/publishing/humanize.py + CaptchaPolicy：

1. 先半自动试一次 —— 纯复选框那种（"确认您不是机器人"）经常能过， 用带轨迹的鼠标去点，而不是 locator.click()（后者零延迟，行为特征明显）。 滑块会试着按变速轨迹拖过去。

2. 过不了就转人工 —— 此时浏览器窗口已经开着，你直接在里面点/拖/选。 代码每 2 秒轮询一次，验证码消失就自动接着往下跑。同时会自动截图 + 存 HTML 到 data/captcha/，方便你看现场。

3. 顺手再试 —— 人工等待期间每 20 秒重试一次半自动（有的验证码会刷新，重试能过）。

# 单独处理某平台的验证码
python cli.py solve-captcha --platform cnblogs --wait 180

# 登录时遇到验证码：默认就交人工
python cli.py login --platform juejin --on-captcha handoff
python cli.py login --platform juejin --on-captcha abort    # 无人值守时直接放弃

实测记录（本次沙箱）：博客园登录表单能正常填提交，提交后弹 阿里云验证码（"请完成安全验证 / 确认您不是机器人"，带 CertifyId）。 半自动点击复选框能点中，但服务端判定未通过 → 正确转入人工。 这正是预期结果：服务端判定的验证码不应该被硬解，交人工才是对的。

另外：博客园除了阿里云验证码，页面上还挂了 Google reCAPTCHA（走 recaptcha.net 国内镜像）。 reCAPTCHA v3 是无感的（只打分不弹框），所以反检测做好能实实在在降低它的风控评分。

无人值守怎么办

验证码天然需要人。要真无人值守，只有两条路：

1. 优先用 L1：能走协议的平台（博客园）就根本不碰验证码

2. 定期保活：登录态是有有效期的。写个定时任务每周跑一次 check， 掉线了发通知给你，你花 1 分钟手动补一次；而不是等发文章时才发现掉线

关于 xvfb（Linux 部署必看）

有头浏览器需要 X Server。服务器/容器里没有，程序会自动拉一个 Xvfb。 没装的话：

apt install -y xvfb

程序还会识别"僵尸 DISPLAY"——很多容器里被塞了 DISPLAY=:0 但根本没有 X 在监听， 盲信这个变量会让浏览器直接崩。代码会实际探测可用性，不行就换号段起 Xvfb。

八、博客园配置：浏览器登录 + 自动抠令牌（一条命令）

博客园发布走 MetaWeblog 协议最稳，但协议要三件套（endpoint / 登录用户名 / 访问令牌）， 它们都锁在「设置 → 其他设置」里、必须先登录才能看到。 所以正确姿势不是"手贴令牌"，而是拿账号密码浏览器登一次，自动抠出来：

python cli.py --headed bootstrap-cnblogs \
    --username 你的登录名 --password 你的密码

它会：开有头浏览器 → 填账号密码 → 自动点阿里「智能验证」复选框 → 登录成功存盘 → 打开设置页 → 把 endpoint / username / token 抠出来写进 config.json。 之后所有发布走纯协议，再也不开浏览器、再也不碰验证码。

登录页的验证码长什么样（别被绕）

博客园登录页叠了两层：

关键：拼图那一下脚本过不去，但它是"一次性"的。 登录态持久化在 data/profiles/cnblogs_default/，人工过完一次就一劳永逸。

如果自动登录被拦（弹图片拼图）

reCAPTCHA 的图片拼图是给你看的，用人工兜底：

python cli.py --headed login --platform cnblogs --on-captcha handoff

窗口会一直开着，你在里面把拼图点完，登录态自动存盘。过这一次，后面全自动。

⚠️ 别在短时间内反复试错登录——那会把 reCAPTCHA 风险分推高， 从"静默放行"直接变成"每次必弹拼图"。用对凭据一次过，或者干净环境重来。

关于「登录用户名」的一个真实坑

数字用户 ID ≠ 登录用户名。 比如账号站内数字 ID 1234567890 这种，是账号在站内的数字标识 （个人主页 / 用户中心 URL 里的那串），不是你登录时填的用户名： 它既不是登录名，也不是 blogApp。被服务端拒时的表现是统一的 用户名或密码错误 （而不是"用户名不存在"），极具迷惑性。

登录名是注册时那个（邮箱 / 手机号 / 你自定义的用户名）。拿不准就去 https://account.cnblogs.com/signin 点「忘记登录用户名」找回。

九、两种适配器，挑着用

浏览器型（掘金、CSDN）：开内置 Chromium 操作编辑器，通用但慢，受页面改版影响。

协议型（博客园）：走 MetaWeblog XML-RPC，不开浏览器，稳定一个数量级，登录态不过期。 适配器里设 needs_browser = False，中台会自动跳过浏览器那一步。看到哪个平台有开放 API， 优先写协议型。

十、性能与稳定性

• 浏览器实例池：无头浏览器按平台常驻复用（LRU 上限 4 个），第二次起发布不再付 1~3 秒的启动开销；页面用完即关、实例保活，浏览器崩溃会自动重建重试一次。 扫码登录前会自动释放该平台的池实例（profile 目录是独占的，不能两处同时开）。

• SQLite WAL 模式 + 30s busy_timeout：多线程并发写不再偶发 database is locked。

• 内存零泄漏：登录任务字典过期自动清理（完成 10 分钟后回收，上限 100 条）； jobs 流水表每次启动自动裁剪到最近 500 条。

• 可选 API 鉴权：config.json 里设 "api_token": "随机串" 即启用，所有请求需带 X-API-Token 头（默认关闭，本机使用不需要）。服务要暴露到局域网/公网时必须开启。

十一、测试：E2E 全模拟套件（不碰真号）

tests/ 目录自带一套本地模拟平台（Flask mock，接口与页面元素和真实平台同构）， 全流程验证适配器的真实代码路径——真实选择器、真实接口调用、真实跳转判定， 只是把目标域名换成 127.0.0.1，不注册不登录不外发：

# 掘金（协议型 API 链路）
python tests/mocks/mock_juejin.py &            # 模拟掘金 :9102
python tests/run_patched_server.py &           # Web 服务 :8800（适配器指向 mock）
python tests/e2e_login_flow.py                 # 登录→扫码→在线→建文档→发布→落库
python tests/e2e_screenshots.py [截图目录]      # 全程截图留证版

# 知乎（UI 编辑器注入链路：Draft.js 填标题 → HTML 粘贴 → 点发布 → /p/{id} 跳转）
python tests/mocks/mock_zhihu.py &
python tests/run_patched_server_zhihu.py &
python tests/e2e_zhihu.py                      # API 级 4 步冒烟
python tests/e2e_zhihu_screenshots.py [截图目录]

实测成绩（2026-09）：掘金截图版 16/16（REST 1~5ms、扫码到在线 7.9s、发布 0.6s、 刷新持久化 ✓）；知乎截图版 9/9（发布全流程 25.2s、post_id 落库 ✓）+ API 冒烟 4/4。 原理与边界（patch 方式、mock 扫码、测不到的真实风控）见 backed/tests_publishing/README.md。

十二、扩展新平台（照抄 150 行）

在 backed/service/publishing/adapters/ 新建 xxx.py，实现四个动作：

@register
class XxxAdapter(PlatformAdapter):
    id = "xxx"
    login_url = "..."
    home_url  = "..."   # 登录后才能进的页，判登录态用
    list_url  = "..."
    new_url   = "..."

    def check_auth(self, page) -> bool: ...      # 登录了吗
    def list_articles(self, page, limit=50): ... # 返回 [{'post_id','title','url','edit_url','stats'}]
    def publish(self, page, article, options): ...  # 返回 {'post_id','post_url','edit_url'}
    def update(self, page, pub, article) -> bool: ... # 打开 edit_url 改内容保存

最后在 backed/service/publishing/service.py 里 from service.publishing.adapters import xxx 导入一下即可注册。

校准技巧（必看）：平台改版导致选择器失效时，别瞎猜——

from service.publishing.browser import dump_dom
dump_dom(page, "csdn_list")     # HTML 存到 data/debug/

打开存下来的 HTML 搜关键词，真实结构一目了然，比猜快十倍。 平台专属的 URL / API / 选择器全在各适配器顶部常量区，改版了只改那一块。

十三、当前状态与已知限制

已跑通（真实账号 + 沙箱实测）：

已知限制：

• 平台风控：程序内置了平台间隔（8-20s）和文章间隔（30-90s）限速，别调太小

• 数据中心 / 云服务器 IP 容易被平台风控踢登录态（知乎 z_c0、B站 SESSDATA 实测被踢）， 首次扫码登录建议在家庭/办公网络完成，登录态持久化后换环境复用

• CSDN 更新已发布文章会重新进审核

• 掘金正式公开需在编辑器点「发布→确定并发布」（2026-09 起 publish API 收紧为草稿）， 本项目默认 draft_only 草稿先行，人工确认后上线

• 单账号模型，account 参数已预留但多账号并发未测

• 验证码做不到 100% 自动：服务端判定的验证码（阿里云/极验/reCAPTCHA）本质上需要人。 程序的设计目标是"尽量不遇到 + 遇到了一次性解决 + 真弹了交人工"， 而不是硬解。要完全无人值守，走 L1 的协议通道（博客园 / 51CTO / 自建博客的 MetaWeblog）

• 首次登录必须在能看到浏览器的机器上做：Linux 服务器上程序会自动起 Xvfb， 但你在服务器上"扫码"不现实（看不到屏幕）。建议在有桌面的机器上登录一次， 把 data/profiles/ 整个拷到服务器复用

十四、目录结构

ai-content-hub/
├─ backed/                # 后端（FastAPI）：数据层 / REST CRUD / 配置 / 基础设施
│  ├─ start.py            # 入口：uvicorn start:app
│  ├─ app/                # 应用装配（factory / config / middleware / routes）
│  ├─ api/v1/             # Resource 层（路由 + 校验 + 调 Service）
│  ├─ service/            # 业务逻辑层（DI 工厂在 __init__.py）
│  ├─ repository/         # 数据访问层
│  ├─ models/ schemas/    # ORM 模型 / Pydantic 模型
│  ├─ config/ core/       # 多环境配置 / 数据库·缓存·队列·权限
│  ├─ middleware/ utils/  # 限流 / 审计 / 日志 / 异常
│  └─ tests/              # 单元 + 集成测试
├─ deplay/                # 部署编排（docker-compose / Dockerfile / 运维配置）
├─ docs/                  # 产品 / 架构文档
├─ web/                   # 前端（Vue3 + Vite，独立工程）
├─ start.sh / .bat / .ps1 # 本地启动脚本（仅依赖 uv）
├─ AGENT.md               # 面向 AI 助手的项目说明
└─ README.md              # 本文件

开发指南（分层、约定、如何新增表、部署）见 AGENT.md。 浏览器发布能力（CLI / 适配器 / REST 端点）已随后端一并迁入 backed/， 详情见 backed/cli.py、backed/service/publishing/ 与 backed/api/hub.py。

十五、参与贡献

欢迎 Issue / PR。后端改动请先 cd backed && uv run pytest； 新增资源表见 AGENT.md 的「新增业务表」一节。

十六、AI 使用说明（透明度声明）

• 本项目的产品设计、架构与代码由人工主导完成，AI 辅助编码与测试；

• 项目自身的定位是"AI 辅助内容创作"工具：文章由 AI 起草、人审核后发布， 请遵守各平台的 AI 内容规范，ai_write 产物入库时已带 source=ai 标记供你区分；

• 请勿将本工具用于批量灌水、刷量等违反平台规则的行为，账号风险自负。

仓库地址

国内平台为主仓库（同步同一分支），GitHub 为国际镜像：

许可证

MIT © 2026 badhope