wechat-download-api

---

功能特性

• RSS 订阅 — 订阅任意公众号，自动定时拉取新文章（包含完整文章内容和图片），生成标准 RSS 2.0 源，接入 FreshRSS / Feedly 等阅读器即可使用；支持批量添加（粘多个公众号名称一次性订阅）
• MCP · AI 客户端接入 — 内置 MCP 服务，Claude / Codex / Cline / Cursor 等 AI 客户端可直接搜索、订阅、读文章（6 个工具，静态 Token 鉴权，单用户自托管无需 OAuth）
• 文章内容获取 — 通过 URL 获取文章完整内容（标题、作者、正文 HTML / 纯文本、图片列表）
• 多格式导出 — 单篇 markdown 增量同步（带 YAML frontmatter，导入 Obsidian / Logseq）；整号文章一键打包成 Markdown / HTML / Word / PDF / EPUB / Excel / JSON 7 种格式（Word/PDF/EPUB 图片内嵌离线可看），纯读本地库、不触发抓取
• 反风控体系 — Chrome TLS 指纹模拟 + SOCKS5 代理池轮转 + 三层自动限频，有效对抗微信封控
• 文章列表 & 搜索 — 获取任意公众号历史文章列表，支持分页和关键词搜索
• 公众号搜索 — 按名称搜索公众号，获取 FakeID
• 公众号主体信息 — 获取公众号认证主体、认证状态、原创文章数等详细信息
• 扫码登录 — 微信公众平台扫码登录，凭证自动保存，4 天有效期
• 图片代理 — 代理微信 CDN 图片，解决防盗链问题
• Webhook 通知 — 登录过期提醒（提前24h/6h预警+已过期通知）、触发验证等事件自动推送（支持企业微信机器人）
• API 文档 — 自动生成 Swagger UI / ReDoc，在线调试所有接口

---

📦 整号导出，随身带走

订阅只是第一步。把整个公众号的存量文章一键打包成你想要的格式——喂给 AI、导入笔记、离线存档、换设备迁移，全都行。

• ❌ 一篇一篇复制粘贴，图片还丢失
• ❌ 想喂给 AI，却拿不到干净的 Markdown
• ❌ 换阅读器 / 换设备，历史内容带不走
• ✅ 一个公众号一键打包，7 种格式任选，纯读本地库、不触发任何微信抓取（零风控风险）

格式	后缀	适合场景	图片	单次上限
📝 Markdown 合集	.zip	归档 / 喂 AI / 导入 Obsidian、Logseq	引用式	3000
🌐 HTML 合集	.html	单文件、带目录、暗色适配，浏览器直接看	引用式	3000
📊 Excel	.xlsx	文章清单表（标题 / 作者 / 时间 / 链接）	—	3000
🔧 JSON	.json	二次开发 / 数据分析	—	3000
📄 Word	.docx	可编辑文档，图去重压缩	内嵌	500
📕 PDF	.pdf	固定排版、内置中文字体免装	内嵌	200
📱 EPUB	.epub	手机 / 电子书阅读器读合集	内嵌	500

文本/表格类（Markdown / HTML / Excel / JSON）图片引用式、秒出、零抓图带宽；离线自包含类（Word / PDF / EPUB）会把微信图现抓内嵌进文件、断网也能看图。全部只导已抓到正文的文章，支持按时间范围（全部 / 最近 N 天 / 时间窗 / 增量）筛选。

在 RSS 管理页（/rss.html）每个订阅右侧点「下载文章」即可可视化选格式与时间范围；也可直接调接口 GET /api/export/account/{fakeid}.{格式}，详见下方 整号文章导出（多格式）。

---

Docker 部署 🐳

最快速的部署方式，无需配置 Python 环境，一键启动：

# 方式一：使用 docker-compose（推荐）
git clone https://github.com/tmwgsicp/wechat-download-api.git
cd wechat-download-api
cp env.example .env
# 编辑 .env 设置 SITE_URL 为实际访问地址
docker-compose up -d

# 方式二：直接运行
docker run -d \
  -p 5000:5000 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/.env:/app/.env \
  --name wechat-api \
  tmwgsicp/wechat-download-api:latest

服务启动后访问 http://localhost:5000/login.html 扫码登录即可使用。

支持多架构：linux/amd64 / linux/arm64（Apple Silicon、树莓派、ARM 服务器）

---

SaaS 托管版 — 已上线 🚀

不想折腾部署？30 秒注册即可使用 👉 wechatrss.waytomaster.com

搜索公众号名称，拿到 RSS 链接，丢进你的阅读器——Feedly、Inoreader、NetNewsWire 全部兼容。

---

使用前提

本工具需要通过微信公众平台后台的登录凭证来调用接口，因此使用前需要：

1. 拥有一个微信公众号（订阅号、服务号均可）
2. 部署并启动服务后，访问登录页面用公众号管理员微信扫码登录
3. 登录成功后凭证自动保存到 .env 文件，有效期约 4 天，过期后需重新扫码

登录后即可通过 API 获取任意公众号的公开文章（不限于自己的公众号）。

本地电脑可以直接使用！ 不需要公网服务器——在本地启动服务后通过 localhost 访问即可完成扫码登录和全部功能。只有当你需要从其他设备（如手机 RSS 阅读器）远程访问时，才需要公网服务器或内网穿透。

---

快速开始

方式一：Docker 部署（推荐）

# 1. 克隆项目
git clone https://github.com/tmwgsicp/wechat-download-api.git
cd wechat-download-api

# 2. 配置环境变量
cp env.example .env
# 编辑 .env，设置 SITE_URL 为实际访问地址（如 http://your-domain.com）

# 3. 启动服务
docker-compose up -d

# 4. 查看日志
docker-compose logs -f

方式二：一键脚本部署

第一步：克隆项目

git clone https://github.com/tmwgsicp/wechat-download-api.git
cd wechat-download-api

第二步：一键启动

bash start.sh  # Linux/macOS
# 或
start.bat      # Windows

脚本会自动完成环境检查、虚拟环境创建、依赖安装和服务启动。

第三步：扫码登录

访问 http://localhost:5000/login.html，用公众号管理员微信扫码登录。

---

API 使用

访问地址

地址	说明
http://localhost:5000	管理面板
http://localhost:5000/login.html	扫码登录
http://localhost:5000/api/docs	Swagger API 文档
http://localhost:5000/api/health	健康检查

---

服务器部署

Linux 生产环境（systemd）

start.sh 脚本在 Linux 上以 sudo 运行时，会自动注册 systemd 服务并启用开机自启：

sudo bash start.sh

之后可通过以下命令管理服务：

# 查看运行状态
bash status.sh

# 停止服务
bash stop.sh

# 手动操作
sudo systemctl restart wechat-download-api
sudo systemctl status wechat-download-api

配置反向代理（可选）

如需通过域名或 HTTPS 访问，配置 Nginx 反向代理到 localhost:5000：

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

环境变量

复制 env.example 为 .env 并按需修改：

cp env.example .env

主要配置项参见 env.example 中的注释说明。

---

MCP — AI 客户端接入

内置 MCP（Model Context Protocol）服务，让 Claude、Codex、Cline、Cursor 等 AI 客户端直接搜索公众号、订阅、读文章，不用切网页、不用手动调接口——对 AI 说"帮我订阅 XX 公众号、把最新几篇总结一下"即可。

6 个工具：

工具	作用
search_accounts	按名称搜索公众号，拿 fakeid
subscribe_account	订阅公众号（传 fakeid）
unsubscribe_account	取消订阅
list_subscriptions	列出已订阅的公众号
get_recent_articles	拉最新文章（支持时间游标增量、按公众号过滤）
read_article	读某篇文章的完整正文

启用（.env）： 单用户自托管，鉴权走静态 Bearer Token，无需 OAuth。ENABLE_MCP 和 MCP_TOKEN 两者都要设置，缺一则 MCP 不启用。

ENABLE_MCP=1
MCP_TOKEN=设一个足够长的随机串           # 客户端凭它鉴权（必填，留空则不启用）
# MCP_RESOURCE_URL=https://你的域名/mcp  # 部署到公网域名时设（DNS-rebinding 白名单）

服务挂载在 /mcp（streamable-http）。

客户端配置：

# Claude Code
claude mcp add --transport http wechatrss https://你的域名/mcp \
  --header "Authorization: Bearer <MCP_TOKEN>"

// Cursor / Cline 等（JSON 配置）
{
  "mcpServers": {
    "wechatrss": {
      "url": "https://你的域名/mcp",
      "headers": { "Authorization": "Bearer <MCP_TOKEN>" }
    }
  }
}

本地自测：http://localhost:5000/mcp。启用后未带正确 Token 会返回 401。

---

API 接口

以下 HTTP 接口无需鉴权：调用方不用传任何 Token 或 Authorization 头。微信登录态由服务端扫码登录后内部持有并自动使用（前提是管理页面已扫码登录）。MCP_TOKEN / Authorization: Bearer 仅用于上面的 MCP 客户端接入，与这些 HTTP 接口无关。

文章解析与公众号搜索/文章列表接口（/api/article、/api/public/searchbiz、/api/public/accountinfo、/api/public/articles、/api/public/articles/search）统一返回 { "success": bool, "data": {...}, "error": null }，业务数据都在 data 字段下；业务失败（如登录态失效）返回 HTTP 200 且 success: false，请以 success 字段判断成败。（增量同步接口 /api/feed/articles.json 与 /api/health 直接返回数据对象、不带此包装；RSS 接口返回 XML；/api/feed/article/{id}.md 返回 markdown 文本。）

获取文章内容

POST /api/article — 解析微信公众号文章，返回标题、正文、图片等结构化数据

参数	类型	必填	说明
url	string	是	微信文章链接（https://mp.weixin.qq.com/s/...）

请求示例：

curl -X POST http://localhost:5000/api/article \
  -H "Content-Type: application/json" \
  -d '{"url": "https://mp.weixin.qq.com/s/xxxxx"}'

返回字段（均在 data 下）：title 标题、content HTML 正文、plain_content 纯文本正文、images 图片 URL 列表、author 作者、publish_time 发布时间戳（秒）、publish_time_str 可读发布时间（如 2026-02-24 09:00:00）

搜索公众号

GET /api/public/searchbiz — 按关键词搜索微信公众号，获取 FakeID

参数	类型	必填	说明
query	string	是	搜索关键词（公众号名称）

请求示例：

curl "http://localhost:5000/api/public/searchbiz?query=公众号名称"

返回示例：

{
  "success": true,
  "data": {
    "list": [
      {
        "fakeid": "MzI5NjM4MjExMg==",
        "nickname": "示例公众号",
        "alias": "example_wx",
        "round_head_img": "http://你的部署地址/api/image?url=...",
        "service_type": 1
      }
    ],
    "total": 1
  },
  "error": null
}

返回字段（公众号列表在 data.list 下）：

• fakeid — 公众号唯一 ID（后续获取文章、订阅时使用）
• nickname — 公众号名称
• alias — 微信号
• round_head_img — 头像地址（已转为服务器图片代理链接）
• service_type — 类型（0=订阅号 / 1=服务号 / 2=企业号）
• data.total — 匹配数量（已过滤黑名单后的条数）

获取公众号主体信息

GET /api/public/accountinfo — 获取公众号的认证主体、认证状态、原创文章数等信息

参数	类型	必填	说明
fakeid	string	是	公众号的 FakeID（从搜索接口获取）

请求示例：

curl "http://localhost:5000/api/public/accountinfo?fakeid=YOUR_FAKEID"

返回示例：

{
  "success": true,
  "data": {
    "identity_name": "腾讯科技(深圳)有限公司",
    "is_verify": 2,
    "original_article_count": 15234
  }
}

返回字段：

• identity_name — 认证主体名称（公司/机构名称）
• is_verify — 认证状态（0=未认证, 1=微信认证, 2=新媒体认证）
• original_article_count — 原创文章总数

获取文章列表

GET /api/public/articles — 获取指定公众号的文章列表，支持分页

参数	类型	必填	说明
fakeid	string	是	目标公众号的 FakeID（从搜索接口获取）
begin	int	否	偏移量，默认 0
count	int	否	获取数量，默认 10，最大 100
keyword	string	否	在该公众号内搜索关键词

请求示例：

# 获取前 50 篇
curl "http://localhost:5000/api/public/articles?fakeid=YOUR_FAKEID&begin=0&count=50"

# 获取第 51-100 篇
curl "http://localhost:5000/api/public/articles?fakeid=YOUR_FAKEID&begin=50&count=50"

返回示例：

{
  "success": true,
  "data": {
    "articles": [
      {
        "aid": "2650000000_1",
        "title": "示例文章标题",
        "link": "https://mp.weixin.qq.com/s/AbCdEfGhIj",
        "update_time": 1700000000,
        "create_time": 1699999000,
        "digest": "文章摘要",
        "cover": "http://mmbiz.qpic.cn/cover/0",
        "author": "作者名"
      }
    ],
    "total": 42,
    "begin": 0,
    "count": 1,
    "keyword": null
  },
  "error": null
}

返回字段（文章列表在 data.articles 下）：

• aid — 文章 ID
• title — 标题
• link — 文章链接
• update_time / create_time — 更新 / 创建时间戳
• digest — 摘要
• cover — 封面图地址
• author — 作者
• data.total — 该公众号文章总数（微信侧）；data.count — 本次返回条数；data.begin — 本次偏移量；data.keyword — 本次搜索关键词（未传为 null）

搜索公众号文章

GET /api/public/articles/search — 在指定公众号内按关键词搜索文章

参数	类型	必填	说明
fakeid	string	是	目标公众号的 FakeID
query	string	是	搜索关键词
begin	int	否	偏移量，默认 0
count	int	否	获取数量，默认 10，最大 100

请求示例：

curl "http://localhost:5000/api/public/articles/search?fakeid=YOUR_FAKEID&query=关键词"

返回结构与「获取文章列表」一致（文章列表在 data.articles 下，data.keyword 为本次搜索词）。

RSS 订阅

GET /api/rss/{fakeid} — 获取指定公众号的 RSS 2.0 订阅源

参数	类型	必填	说明
fakeid	string（路径）	是	公众号 FakeID
limit	int（查询）	否	返回文章数量上限，默认 20

使用方式：

# 1. 搜索公众号获取 fakeid
curl "http://localhost:5000/api/public/searchbiz?query=人民日报"
# 返回 fakeid: MzA1MjM1ODk2MA==

# 2. 添加订阅
curl -X POST http://localhost:5000/api/rss/subscribe \
  -H "Content-Type: application/json" \
  -d '{"fakeid": "MzA1MjM1ODk2MA==", "nickname": "人民日报"}'

# 3. 手动触发一次轮询（立即拉取文章）
curl -X POST http://localhost:5000/api/rss/poll

# 4. 获取 RSS 源（把这个地址添加到 RSS 阅读器）
curl "http://localhost:5000/api/rss/MzA1MjM1ODk2MA=="

也可以通过管理面板的 RSS 订阅 页面可视化管理，搜索公众号一键订阅并复制 RSS 地址。

关于 RSS 内容: RSS 源包含完整文章内容（图文混排），您可以直接在 RSS 阅读器中阅读全文。

系统使用 SOCKS5 代理池 + Chrome TLS 指纹模拟技术获取文章内容，有效规避微信风控。

扫码登录后，系统会自动将微信凭证用于内容获取，无需手动配置。如需禁用完整内容获取（仅保留标题和摘要），可在 .env 中设置 RSS_FETCH_FULL_CONTENT=false。

RSS 订阅管理接口

方法	路径	说明
POST	/api/rss/subscribe	添加 RSS 订阅
DELETE	/api/rss/subscribe/{fakeid}	取消 RSS 订阅
GET	/api/rss/subscriptions	获取订阅列表
POST	/api/rss/poll	手动触发轮询
GET	/api/rss/status	轮询器状态
GET	/api/rss/all	聚合源 — 所有订阅合成一个 RSS，阅读器里加一条就够
GET	/api/rss/category/{category_id}	分类源 — 某个分类下所有订阅合成一个 RSS
GET	/api/rss/{fakeid}/history	单个公众号的历史文章 RSS
GET	/api/rss/export	导出订阅列表（备份 / 迁移）

分类管理：可把订阅分组（GET/POST /api/categories、PUT/DELETE /api/categories/{id}、POST /api/subscriptions/{fakeid}/category），再用上面的分类源按主题订阅，或用聚合源一条读全部。

Markdown 导出 / 文章同步

把已抓取的文章拉成 markdown（带 YAML frontmatter），可直接导入 Obsidian / Logseq 等工具。

GET /api/feed/articles.json — 列出本地已抓取的文章元数据（含文章 id），按时间游标增量同步

参数	类型	必填	说明
since	int（查询）	否	Unix 时间戳，返回 publish_time > since 的文章；首次传 0
fakeid	string（查询）	否	只看某个公众号
limit	int（查询）	否	单次返回条数（1-200），默认 50

响应含 next_since（本批最后一篇的发布时间），作为下次 since 循环调用，拉到 articles 为空即同步完成；之后用保存的 next_since 做每日增量。

GET /api/feed/article/{id}.md — 按 id 获取单篇文章的 markdown 正文（带 title / author / nickname / fakeid / publish_time / date（可读时间）/ source_url 等 frontmatter）

# 1. 拉文章列表拿 id（循环 since 直到返回空）
curl "http://localhost:5000/api/feed/articles.json?since=0&limit=200"

# 2. 按 id 下载某篇 markdown（浏览器 / 下载工具会自动存成「标题.md」）
curl -OJ "http://localhost:5000/api/feed/article/1.md"

状态码：200 正文 / 404 不存在 / 422 内容尚未抓取完成（稍后重试）。

整号文章导出（多格式）

把某个公众号已抓取入库的文章一次性打包下载，支持 7 种格式。纯读本地库、不触发任何微信抓取；在 RSS 管理页（/rss.html）每个订阅右侧点「下载文章」即可选格式与时间范围，也可直接调接口。

GET /api/export/account/{fakeid}.{格式}

格式	后缀	说明	图片
Markdown 合集	.zip	每篇一个 .md + INDEX.md，适合归档 / 喂 AI	引用式（指向 /api/image 代理）
HTML 合集	.html	单文件，带目录、暗色适配	引用式
Excel	.xlsx	文章清单表（标题 / 作者 / 时间 / 链接）	—
JSON	.json	文章清单数据	—
Word	.docx	可编辑，图去重压缩	内嵌（离线可看）
PDF	.pdf	内置中文字体，排版固定	内嵌
EPUB	.epub	每篇一章 + 目录，手机 / 阅读器读合集	内嵌

参数	类型	必填	说明
since	int（查询）	否	只导 publish_time >= since 的文章（时间窗起点 / 增量），秒级时间戳
before	int（查询）	否	只导 publish_time <= before 的文章（时间窗终点）
limit	int（查询）	否	最多导出篇数（最近优先）。md/html/xlsx/json 上限 3000，Word/EPUB 500，PDF 200

# 整号导出为 Markdown 合集 zip（浏览器 / -OJ 会按「公众号名_导出_N篇.zip」自动命名）
curl -OJ "http://localhost:5000/api/export/account/MzA1MjM1ODk2MA==.zip"

# 只导最近 30 天、导成 EPUB
SINCE=$(($(date +%s) - 30*86400))
curl -OJ "http://localhost:5000/api/export/account/MzA1MjM1ODk2MA==.epub?since=$SINCE"

Markdown / HTML / Excel / JSON 用图片引用式，秒出、零抓图带宽（在线打开时显示图）；Word / PDF / EPUB 会现抓微信图内嵌进文件、离线自带图，篇数多时稍慢。全部只导已抓到正文的文章。

其他接口

方法	路径	说明
GET	/api/image?url=IMG_URL	图片代理（仅限微信 CDN 域名）
GET	/api/health	健康检查
GET	/api/stats	限频统计
POST	/api/login/session/{id}	初始化登录会话
GET	/api/login/getqrcode	获取登录二维码
GET	/api/login/scan	检查扫码状态
POST	/api/login/bizlogin	完成登录
GET	/api/login/info	获取登录信息
GET	/api/admin/status	查询登录状态
POST	/api/admin/logout	退出登录

完整的接口文档请访问 http://localhost:5000/api/docs

---

配置说明

复制 env.example 为 .env，登录后凭证会自动保存：

cp env.example .env

配置项	说明	默认值
WECHAT_TOKEN	微信 Token（登录后自动填充）	-
WECHAT_COOKIE	微信 Cookie（登录后自动填充）	-
WECHAT_FAKEID	公众号 FakeID（登录后自动填充）	-
WECHAT_EXPIRE_TIME	凭证过期时间（登录后自动填充）	-
WEBHOOK_URL	Webhook 通知地址（支持企业微信机器人）	空
WEBHOOK_NOTIFICATION_INTERVAL	同一事件通知最小间隔（秒）	300
RATE_LIMIT_GLOBAL	全局每分钟请求上限	10
RATE_LIMIT_PER_IP	单 IP 每分钟请求上限	5
RATE_LIMIT_ARTICLE_INTERVAL	文章请求最小间隔（秒）	3
RSS_POLL_INTERVAL	RSS 轮询间隔（秒）	3600
ARTICLES_PER_POLL	每次轮询每个公众号拉取的文章批次数	10
RSS_FETCH_FULL_CONTENT	RSS 是否获取完整内容（true/false）	true
PROXY_URLS	SOCKS5 代理池地址（强烈建议配置，避免账号风控）	空
SITE_URL	网站访问地址（用于RSS图片代理，必须配置）	http://localhost:5000
PORT	服务端口	5000
HOST	监听地址	0.0.0.0
DEBUG	调试模式（开启热重载）	false

⚠️ 重要: SITE_URL 必须配置为实际访问地址（IP或域名），否则RSS图片无法正常显示。例如：

• 本地开发: http://localhost:5000
• 局域网部署: http://192.168.1.100:5000
• 公网域名: https://你的域名.com

SOCKS5 代理池配置（⚠️ 强烈建议）

重要提示:

• ⚠️ 启用完整内容获取时，强烈建议配置代理池，避免账号被微信风控
• ⚠️ 不配置代理直连微信可能导致：频繁验证、账号限制、IP封禁
• ✅ 配置2-3个代理IP可有效分散请求，降低风控风险

用途：获取文章完整内容时分散请求 IP，配合 Chrome TLS 指纹模拟，有效规避微信风控。

本项目使用 curl_cffi 模拟 Chrome TLS 指纹，请求特征与真实浏览器一致，配合代理池效果更佳。

方案：多台 VPS 自建 SOCKS5 代理

准备 2-3 台低价 VPS（各大云厂商轻量应用服务器即可，¥20-30/月/台），每台运行一个 SOCKS5 代理服务。推荐 gost（Go 语言实现，单二进制文件，无依赖）。

第一步：在每台 VPS 上安装 gost

# 下载最新版（以 Linux amd64 为例，其他架构请去 GitHub Releases 页面选择）
# 国外服务器直接下载
wget https://github.com/go-gost/gost/releases/download/v3.2.6/gost_3.2.6_linux_amd64.tar.gz

# 国内服务器使用加速镜像（任选一个可用的）
wget https://gh-proxy.com/https://github.com/go-gost/gost/releases/download/v3.2.6/gost_3.2.6_linux_amd64.tar.gz
# 或
wget https://ghproxy.cc/https://github.com/go-gost/gost/releases/download/v3.2.6/gost_3.2.6_linux_amd64.tar.gz

# 解压并移动到系统路径
tar -xzf gost_3.2.6_linux_amd64.tar.gz
mv gost /usr/local/bin/
chmod +x /usr/local/bin/gost

# 验证安装
gost -V

第二步：启动 SOCKS5 代理服务

# 带用户名密码认证（推荐，替换 myuser / mypass 和端口）
gost -L socks5://myuser:mypass@:1080

# 不带认证（仅内网或已配置防火墙时使用）
gost -L socks5://:1080

第三步：配置为 systemd 服务（开机自启）

cat > /etc/systemd/system/gost.service << 'EOF'
[Unit]
Description=GOST Proxy
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/gost -L socks5://myuser:mypass@:1080
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable gost
systemctl start gost

第四步：开放防火墙端口

# 仅允许你的主服务器 IP 连接（替换为实际 IP）
ufw allow from YOUR_MAIN_SERVER_IP to any port 1080

# 或者如果用的是云厂商安全组，在控制台添加入站规则：
# 端口 1080 / TCP / 来源 IP 限制为你的主服务器

第五步：在主服务器 .env 中配置代理池

PROXY_URLS=socks5://myuser:mypass@vps1-ip:1080,socks5://myuser:mypass@vps2-ip:1080,socks5://myuser:mypass@vps3-ip:1080

配置后重启服务，每次文章请求会轮流使用不同的代理 IP。可以通过 GET /api/health 确认代理池状态。留空则直连（默认行为）。

---

项目结构

├── app.py                # FastAPI 主应用
├── requirements.txt      # Python 依赖
├── env.example           # 环境变量示例
├── data/                 # 数据目录（运行时自动创建）
│   └── rss.db            # RSS 订阅 SQLite 数据库
├── routes/               # API 路由
│   ├── article.py        # 文章内容获取
│   ├── articles.py       # 文章列表
│   ├── account.py        # 公众号主体信息
│   ├── rss.py            # RSS 订阅管理与输出
│   ├── search.py         # 公众号搜索
│   ├── feed.py           # 本地文章增量同步（articles.json / markdown 导出）
│   ├── login.py          # 扫码登录
│   ├── admin.py          # 管理接口
│   ├── image.py          # 图片代理
│   ├── health.py         # 健康检查
│   └── stats.py          # 统计信息
├── mcp_server/           # MCP 服务（AI 客户端接入）
│   ├── server.py         # MCP 服务端（静态 Bearer Token 鉴权）
│   ├── tools.py          # MCP 工具（搜索/订阅/读文章等）
│   └── store_adapter.py  # 公众号搜索/订阅数据适配
├── utils/                # 工具模块
│   ├── auth_manager.py   # 认证管理
│   ├── helpers.py        # HTML 解析
│   ├── http_client.py    # HTTP 客户端（curl_cffi + 代理池）
│   ├── proxy_pool.py     # 代理池轮转
│   ├── rate_limiter.py   # 限频器
│   ├── rss_store.py      # RSS 数据存储（SQLite）
│   ├── rss_poller.py     # RSS 后台轮询器
│   ├── login_reminder.py # 登录过期提醒（主动检测）
│   ├── content_processor.py  # 内容处理与图片代理
│   ├── image_proxy.py    # 图片URL代理工具
│   ├── article_fetcher.py    # 批量并发获取文章
│   └── webhook.py        # Webhook 通知
└── static/               # 前端页面（含 RSS 管理）

---

内容类型与获取策略

本项目支持多种微信公众号内容类型，包括标准富文本、纯图片文章、图文消息、短内容、音频文章等。

详细说明请查看：CONTENT_TYPES.md

文档内容：

• 所有支持的内容类型及 item_show_type 值
• 不可用状态识别（删除、违规、隐私、验证页面等）
• 反爬策略与代理配置
• 关键函数说明
• 开发贡献指南

---

常见问题

提示"服务器未登录"

访问 http://localhost:5000/login.html 扫码登录，凭证会自动保存到 .env。

触发微信风控 / 需要验证

1. 在浏览器中打开提示的文章 URL 完成验证
2. 等待 30 分钟后重试
3. 降低请求频率（系统已内置自动限频）

如何获取公众号的 FakeID

调用搜索接口：GET /api/public/searchbiz?query=公众号名称，从返回结果的 fakeid 字段获取。

Token 多久过期？如何提前知道？

Cookie 登录有效期约 4 天，系统会：

1. 前端显示到期时间（/api/admin/status 接口返回 expireTime 和 isExpired 字段）
2. 后台每 6 小时主动检测，提前 24h / 6h 通过 Webhook 预警
3. 过期后立即通过 Webhook 通知

配置 WEBHOOK_URL（支持企业微信群机器人）可收到实时提醒，避免因凭证过期导致 RSS 轮询失败或搜索功能不可用。

可以同时登录多个公众号吗

当前版本不支持多账号。建议部署多个实例，每个登录不同公众号。

---

技术栈

层级	技术
Web 框架	FastAPI
ASGI 服务器	Uvicorn
HTTP 客户端	curl_cffi（Chrome TLS 指纹）/ HTTPX（降级）
反风控	TLS 指纹模拟 + SOCKS5/HTTP 代理池轮转
RSS 存储	SQLite（零配置，数据本地化）
配置管理	python-dotenv
运行环境	Python 3.8+

---

开源协议

本项目采用 AGPL 3.0 协议开源，所有功能代码完整公开，私有化部署完全免费。

使用场景	是否允许
个人学习和研究	允许，免费使用
企业内部使用	允许，免费使用
私有化部署	允许，免费使用
修改后对外提供网络服务	需开源修改后的代码

详见 LICENSE 文件。

免责声明

• 本软件按"原样"提供，不提供任何形式的担保
• 本项目仅供学习和研究目的，请遵守微信公众平台相关服务条款
• 使用者对自己的操作承担全部责任
• 因使用本软件导致的任何损失，开发者不承担责任

---

参与贡献

由于个人精力有限，目前暂不接受 PR，但非常欢迎：

• 提交 Issue — 报告 Bug、提出功能建议
• Fork 项目 — 自由修改和定制
• Star 支持 — 给项目点 Star，让更多人看到

---

联系方式

个人微信 技术交流 · 商务合作

赞赏支持 开源不易，感谢支持

• GitHub Issues: 提交问题
• 邮箱: [email protected]
• SaaS 托管版: wechatrss.waytomaster.com

---

致谢

• FastAPI — 高性能 Python Web 框架
• curl_cffi — 支持浏览器 TLS 指纹模拟的 HTTP 客户端
• HTTPX — 现代化 HTTP 客户端
• gost — 轻量级代理工具

---