面向微信公众号内容采集、RSS 订阅、标签整理与热点分析的前后端分离系统
项目维护： 本项目的日常运维工作（包括 Issue/PR 处理、文档更新及版本发布）主要由 OpenClaw 协助支持。我们始终欢迎并期待社区开发者与学术研究者的共同参与。
核心规划与待办（摘要）：
| 规划方向 | 任务概要 |
|---|---|
| 微信内容自动生成 | 开发基于特定主题（Topic）的文章与大纲自动生成功能，支持公众号风格，并深度集成至现有的内容入库与审核流程。 |
| 智能标签与关键词 | 探索基于 GLiNER 的轻量化方案，用于提升现有的 AI 标签提取能力，支持与现有链路进行结果比对或级联增强。 |
| 社区共建计划 | 持续招募长期贡献者。诚邀学术界与开源伙伴共同参与项目的维护与建设（详情请参考 [贡献指南]）。 |
完整规划与详细待办事项请参阅 docs/ROADMAP.md。
WeRSS 是一个前后端分离的微信公众号内容采集与分析系统。它提供文章采集、RSS 输出、标签整理、热点追踪、消息通知和后台管理能力，适合用来搭建面向公众号内容的监控、归档和订阅服务。
后端：
- FastAPI - 现代化的 Python Web 框架
- SQLAlchemy - Python ORM 框架
- Playwright - 浏览器自动化
- APScheduler - 定时任务调度
前端：
- React 18 - UI 框架
- TypeScript - 类型系统
- Vite - 构建工具
- Tailwind CSS - 实用优先的 CSS 框架
- Radix UI / shadcn/ui - 组件库
- React Router v6 - 路由管理
- Zustand - 状态管理
- Axios - HTTP 客户端
- 🔄 文章采集：支持
web / api / app多种采集模式 - 📰 RSS 输出：将公众号文章整理为标准 RSS 订阅源
- 🏷️ 标签体系：支持手动管理标签，并支持基于 OpenAI 兼容接口的 AI 自动提取
- 📤 内容导出：支持 PDF、Markdown 等导出方式
- 🔔 消息通知：支持钉钉、企业微信、飞书和自定义 Webhook
- 🔐 权限控制：提供用户认证与权限管理
- ⏰ 任务调度：支持定时采集、自动补全和后台任务管理
- ✅ 自动采集微信公众号文章
- ✅ 支持多种采集模式（web/api/app）
- ✅ 文章内容自动提取和清理
- ✅ 文章搜索和筛选
- ✅ 文章标签管理与筛选
- ✅ 标准 RSS 2.0 格式输出
- ✅ 支持全文/摘要模式
- ✅ 自定义 RSS 标题、描述、封面
- ✅ 支持 CDATA 格式
- ✅ 分页支持
- ✅ 手动标签管理
- ✅ AI 自动标签提取
- 当前仅支持基于 OpenAI 兼容接口的 AI 提取
- 可接入 DeepSeek、OpenAI、Qwen 等兼容服务
- 优先提取公司名称、产品名称、技术名称等具体实体
- 对 Qwen3 模型自动关闭思考模式，直接返回可解析结果
- ✅ 基于公众号的自动标签关联
- ✅ 标签统计和分析
- ✅ 智能标签自动创建
- ✅ PDF 导出（需启用）
- ✅ Markdown 导出（需启用）
- ✅ 批量导出支持
- ✅ MinIO 对象存储支持
- ✅ 文章图片自动下载和上传
- ✅ 图片 URL 自动替换为 MinIO 链接
- ✅ 钉钉 Webhook 通知
- ✅ 企业微信 Webhook 通知
- ✅ 飞书 Webhook 通知
- ✅ 自定义 Webhook 通知
- ✅ 授权二维码过期通知
- ✅ 消息订阅模板（支持单个公众号和多公众号汇总）
系统支持通过消息任务定时汇总公众号文章，并支持自定义消息模板。
1. 单个公众号模板
适用于单个公众号的消息推送，可用变量如下：
{{feed.mp_name}}- 公众号名称{{articles}}- 文章列表{{article.title}}- 文章标题{{article.url}}- 文章链接{{article.publish_time}}- 发布时间{{article.description}}- 文章描述{{article.pic_url}}- 封面图URL
示例模板：
### {{feed.mp_name}} 订阅消息：
{% if articles %}
{% for article in articles %}
- [**{{ article.title }}**]({{article.url}}) ({{ article.publish_time }})
{% endfor %}
{% else %}
- 暂无文章
{% endif %}2. 多个公众号汇总模板（推荐）
适用于汇总多个公众号的文章，可用变量如下：
{{feeds_with_articles}}- 公众号及文章列表（数组）{{item.feed.mp_name}}- 公众号名称{{item.articles}}- 该公众号的文章列表{{total_articles}}- 总文章数{{feeds_count}}- 公众号数量{{task.name}}- 任务名称{{now}}- 当前时间
默认汇总模板：
# 每日订阅汇总
{% for item in feeds_with_articles %}
## {{ item.feed.mp_name }}
{% for article in item.articles %}
- [**{{ article.title }}**]({{ article.url }}){% if article.publish_time %} ({{ article.publish_time }}){% endif %}
{% endfor %}
{% endfor %}
---
共 {{ total_articles }} 篇文章，来自 {{ feeds_count }} 个公众号自定义汇总模板示例：
# 每日订阅汇总
{% for item in feeds_with_articles %}
### {{ item.feed.mp_name }} 订阅消息：
{% for article in item.articles %}
- [**{{ article.title }}**]({{ article.url }}) ({{ article.publish_time }})
{% endfor %}
{% endfor %}
---
共 {{ total_articles }} 篇文章，来自 {{ feeds_count }} 个公众号系统使用 Jinja2 风格模板语法，支持：
- 变量输出：
{{ variable }} - 条件判断：
{% if condition %}...{% endif %} - 循环遍历：
{% for item in items %}...{% endfor %} - 点号访问：
{{ item.feed.mp_name }}（访问嵌套属性）
- 如果自定义模板中包含
feeds_with_articles变量，系统会按汇总模式渲染 - 如果自定义模板中不包含
feeds_with_articles，系统会回退到默认汇总模板 - 单个公众号模板仅适用于单个公众号的消息推送场景
消息模板可用于以下通知平台：
- ✅ 飞书：支持富文本（post）和文本格式，自动降级
- ✅ 钉钉：支持 Markdown 格式
- ✅ 企业微信：支持 Markdown 格式
- ✅ 自定义 Webhook：支持 JSON 格式
- 多公众号汇总：优先使用包含
feeds_with_articles的模板，一次汇总多个公众号内容 - 单个公众号推送：单个公众号模板更适合做定向订阅通知
- 模板测试：可在消息任务中先使用“测试”功能预览渲染结果
- Markdown 展示：模板支持 Markdown，适合输出结构化通知内容
- ✅ 用户认证和权限管理
- ✅ 系统配置管理
- ✅ 定时任务管理
- ✅ 系统信息监控
- ✅ 数据统计面板
后端：
- Python: 3.11 或更高版本
- 数据库: SQLite / MySQL / PostgreSQL
- 浏览器: Firefox / Chromium / WebKit（用于Playwright）
前端：
- Node.js: 18 或更高版本
- 包管理器: pnpm（推荐）或 npm
# 克隆项目
git clone https://github.com/wang-h/werss.git
cd werss
# 运行一键启动脚本（自动配置环境、安装依赖、启动前后端）
chmod +x start_dev.sh
./start_dev.sh启动后访问：
- 前端界面: http://localhost:5174
- 后台API: http://localhost:8001
- API文档: http://localhost:8001/api/docs
Ubuntu/Debian:
sudo apt-get update
sudo apt-get install -y \
wget git build-essential zlib1g-dev \
libgdbm-dev libnss3-dev libssl-dev libreadline-dev \
libffi-dev libsqlite3-dev procpsmacOS:
brew install python@3.11使用 uv（推荐，更快）:
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 创建虚拟环境
uv venv
# 激活虚拟环境
source .venv/bin/activate # Linux/Mac
# 或
.venv\Scripts\activate # Windows使用传统方式:
python3 -m venv venv
source venv/bin/activate # Linux/Mac
# 或
venv\Scripts\activate # Windows# 使用 uv（推荐）
uv pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
# 或使用 pip
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simpleplaywright install firefox # 或 webkit, chromium# 复制配置文件模板
cp config.example.yaml config.yaml
# 编辑配置文件（或使用环境变量）
vim config.yaml# 设置环境变量（首次运行需要）
export WERSS_USERNAME=admin
export WERSS_PASSWORD=your_password
# 数据库配置（必须配置 DB 环境变量）
# 使用 SQLite（默认，无需额外配置）
export DB=sqlite:///data/db.db
# 或使用 PostgreSQL（推荐）
export DB=postgresql://admin:12345678@localhost:5432/werss_db
# 注意：使用 PostgreSQL 前需要先启动 PostgreSQL 服务
# 初始化数据库
python main.py -init True# 启动服务（包含定时任务）
python main.py -job True -init False
# 或仅启动API服务（不启动定时任务）
python main.py -job False -init False如果需要单独开发前端：
# 进入前端目录
cd web_ui
# 安装依赖（推荐使用 pnpm）
pnpm install
# 或使用 npm
npm install
# 创建前端环境变量文件
echo "VITE_API_BASE_URL=http://localhost:8001" > .env
# 启动前端开发服务器
pnpm dev
# 或
npm run dev前端服务启动后访问：http://localhost:5174
# 构建镜像（会自动构建前端）
docker build -t werss:latest .
# 运行容器
docker run -d -p 8001:8001 werss:latest
# 访问应用
# 前端界面: http://localhost:8001
# API文档: http://localhost:8001/api/docs# 构建镜像（使用国内镜像源，构建速度更快）
docker build -f Dockerfile.cn -t werss:latest .
# 运行容器
docker run -d -p 8001:8001 werss:latest
# 访问应用
# 前端界面: http://localhost:8001
# API文档: http://localhost:8001/api/docs注意：Docker 镜像已包含前端构建，无需单独启动前端服务。前端和 API 都通过 http://localhost:8001 访问。
一键编排默认包含 Traefik（80/443）、PostgreSQL、MinIO 与 WeRSS；应用经 Traefik 按域名路由，HTTPS 由 Let’s Encrypt 签发。请复制 .env.example 为 .env，设置 WERSS_HOST、ACME_EMAIL 等后再启动：
cp .env.example .env
docker compose up -d说明、端口与仅本机调试方式见 docs/DEPLOYMENT.md（完整栈与开发覆盖文件）。
若机器上已有 PostgreSQL 和 MinIO，不需要完整栈（会再起一套库并占用端口）。请使用仅包含应用容器的编排：
docker compose -f docker-compose.app-only.yml up -d --build说明见 docs/DEPLOYMENT.md。
配置优先级与重启： 默认情况下，后台写入数据库表 config_management 的配置会优先于 .env 和 yaml 中的同名配置；进程重启后这些值仍会保留。若希望 .env 优先，仅在环境变量未设置或为空时才回退到数据库配置，请设置 WERSS_ENV_OVERRIDES_DB=true。详见 docs/DEPLOYMENT.md 的“配置优先级”。
docker-compose.dev.yml 是开发环境覆盖文件，需要与 docker-compose.yml 一起使用。两者叠加后会启动 Traefik、PostgreSQL、MinIO 和 WeRSS，并切换到开发环境专用的容器名与数据目录；同时为 werss 映射宿主机 8001，便于本地直连（不经 Traefik）。
特点：
- ✅ Traefik、Postgres、MinIO、WeRSS 与完整栈一致；
werss额外暴露8001方便调试 - ✅ 本地可优先使用
http://localhost:8001，无需先配置域名与 HTTPS - ✅ MinIO 使用 HTTP 访问（开发环境）
- ✅ 简化配置，快速启动
- ✅ 数据持久化到本地
./data目录
快速开始：
- 配置环境变量
# 复制环境变量模板文件
cp .env.example .env
# 编辑环境变量（根据实际情况修改）
vim .env主要需要关注的环境变量：
POSTGRES_DB- PostgreSQL 数据库名（默认：werss_db）POSTGRES_USER- PostgreSQL 用户名（默认：admin）POSTGRES_PASSWORD- PostgreSQL 数据库密码DB- 重要：数据库连接字符串，例如postgresql://admin:12345678@localhost:5432/werss_dbWERSS_USERNAME- WeRSS 管理员用户名WERSS_PASSWORD- WeRSS 管理员密码MINIO_ROOT_USER- MinIO 用户名（默认：admin）MINIO_ROOT_PASSWORD- MinIO 管理员密码OPENAI_API_KEY- OpenAI 兼容 API Key（用于 AI 标签提取，可选）
重要提示：
.env由完整栈中的服务定义读取；开发覆盖文件只负责覆盖容器名、卷和调试参数- 必须配置
DB环境变量 才能使用 PostgreSQL，否则应用会回退到 SQLite - 使用
docker compose启动时，.env会自动加载 - 如果修改了环境变量，需要重启服务：
docker compose -f docker-compose.yml -f docker-compose.dev.yml restart werss
- 启动所有服务
# 启动所有服务（PostgreSQL、MinIO、WeRSS）
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d
# 查看所有服务状态
docker compose -f docker-compose.yml -f docker-compose.dev.yml ps
# 查看日志
docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f- 访问服务
启动成功后，可通过以下地址访问：
- WeRSS 前端界面: http://localhost:8001
- WeRSS API 文档: http://localhost:8001/api/docs
- PostgreSQL 数据库: localhost:5432
- 数据库名:
werss_db（或POSTGRES_DB配置的值） - 用户名:
admin（或POSTGRES_USER配置的值） - 密码: 环境变量中配置的
POSTGRES_PASSWORD - 注意：确保
.env中已经配置DB=postgresql://用户名:密码@localhost:5432/数据库名
- 数据库名:
- MinIO 控制台: http://localhost:9001
- 用户名:
admin（或MINIO_ROOT_USER配置的值） - 密码: 环境变量中配置的
MINIO_ROOT_PASSWORD
- 用户名:
- MinIO API: http://localhost:9000
- 常用操作
# 停止所有服务
docker compose -f docker-compose.yml -f docker-compose.dev.yml down
# 停止并删除数据卷（注意：会删除所有数据）
docker compose -f docker-compose.yml -f docker-compose.dev.yml down -v
# 重启单个服务
docker compose -f docker-compose.yml -f docker-compose.dev.yml restart werss
# 查看特定服务的日志
docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f werss
docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f postgres
docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f minio
# 进入容器执行命令
docker compose -f docker-compose.yml -f docker-compose.dev.yml exec werss bash
docker compose -f docker-compose.yml -f docker-compose.dev.yml exec postgres psql -U admin -d werss_db
# 重新构建并启动（代码更新后）
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build- 数据目录说明
开发环境数据会保存在项目根目录下的 ./data 目录：
data/
├── postgres-data-dev/ # PostgreSQL 数据文件
├── minio-data-dev/ # MinIO 数据文件
└── werss-data-dev/ # WeRSS 应用数据
├── cache/ # 缓存目录
├── pdf/ # PDF 导出目录（如果启用）
└── markdown/ # Markdown 导出目录（如果启用）
注意事项：
- 开发环境使用
-dev后缀的数据目录，避免与生产环境冲突 - 数据库配置：必须在
.env中配置DB才能使用 PostgreSQL- 示例：
DB=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@localhost:5432/${POSTGRES_DB} - 未配置时，应用会使用 SQLite（
sqlite:///data/db.db）
- 示例：
- 首次启动会自动初始化数据库和创建管理员账号
- 如果修改了环境变量，需要重启相关服务才能生效：
docker compose -f docker-compose.yml -f docker-compose.dev.yml restart werss - 开发环境默认启用 DEBUG 模式，日志级别为 DEBUG
- MinIO 在开发环境使用 HTTP，生产环境建议使用 HTTPS
故障排查：
# 检查服务健康状态
docker compose -f docker-compose.yml -f docker-compose.dev.yml ps
# 查看服务启动日志
docker compose -f docker-compose.yml -f docker-compose.dev.yml logs werss
# 检查数据库连接
docker compose -f docker-compose.yml -f docker-compose.dev.yml exec postgres pg_isready -U admin
# 检查 MinIO 服务
curl http://localhost:9000/minio/health/live
# 重置环境（删除所有数据并重新启动）
docker compose -f docker-compose.yml -f docker-compose.dev.yml down -v
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d项目使用 config.yaml 进行配置，首次运行请从模板复制：
cp config.example.yaml config.yaml项目支持用环境变量覆盖配置文件中的设置，且环境变量优先级更高：
# 数据库配置
export DB=postgresql://user:password@localhost:5432/werss_db
# 服务器配置
export PORT=8001
export DEBUG=False
export AUTO_RELOAD=False
# 用户认证（首次运行）
export WERSS_USERNAME=admin
export WERSS_PASSWORD=your_password
# 定时任务
export ENABLE_JOB=True
export THREADS=2
# 文章存储周期清理（可选，默认关闭；需 ENABLE_JOB 且启动参数 -job True）
# export ARTICLE_RETENTION_ENABLED=true
# export ARTICLE_RETENTION_DAYS=7
# export ARTICLE_RETENTION_BASIS=created_at
# MinIO 可用时是否转存公众号相关图片；false=保留微信原图 URL（见 docs/DEPLOYMENT.md）
# MINIO_STORE_ARTICLE_IMAGES=true
# RSS 配置
export RSS_BASE_URL=https://your-domain.com/
export RSS_TITLE=我的RSS订阅
export RSS_DESCRIPTION=微信公众号热度分析系统
# 通知配置
export DINGDING_WEBHOOK=https://oapi.dingtalk.com/robot/send?access_token=xxx
export WECHAT_WEBHOOK=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx
export FEISHU_WEBHOOK=https://open.feishu.cn/open-apis/bot/v2/hook/xxx
# AI 标签提取（可选）
export OPENAI_API_KEY=sk-xxx
export OPENAI_BASE_URL=https://api.deepseek.com
export OPENAI_MODEL=deepseek-chat# SQLite（默认）
db: sqlite:///data/db.db
# PostgreSQL
db: postgresql://username:password@host:5432/database
# MySQL
db: mysql+pymysql://username:password@host:3306/database?charset=utf8mb4rss:
base_url: https://your-domain.com/ # RSS 域名地址
local: False # 是否为本地 RSS 链接
title: 我的RSS订阅 # RSS 标题
description: 微信公众号热度分析系统 # RSS 描述
full_context: True # 是否显示全文
add_cover: True # 是否添加封面图片
page_size: 30 # RSS分页大小gather:
content: False # 是否采集内容
model: app # 采集模式：web/api/app
content_auto_check: False # 是否自动检查未采集文章
content_auto_interval: 59 # 自动检查间隔（分钟）
browser_type: firefox # 浏览器类型：firefox/edge/webkitarticle_tag:
auto_assign_by_mp: True # 根据公众号自动关联标签
auto_extract: False # 是否自动提取标签
extract_method: ai # 当前仅支持 ai（OpenAI 兼容 API）
max_tags: 5 # 最大标签数量
# AI 提取配置
ai:
auto_create: True # 是否自动创建不存在的标签当前版本的自动标签提取仅支持 OpenAI 兼容接口。你可以接入 DeepSeek、OpenAI、Qwen 等兼容服务，代码侧统一走同一套 AI 提取链路。
openai:
api_key: sk-xxx # API Key（必填，用于 AI 标签提取）
base_url: https://api.deepseek.com # 兼容接口地址
model: deepseek-chat # 模型名称环境变量配置：
# OpenAI 兼容 API 配置
export OPENAI_API_KEY=sk-xxx
export OPENAI_BASE_URL=https://api.deepseek.com
export OPENAI_MODEL=deepseek-chat
# 标签提取配置
export ARTICLE_TAG_AUTO_EXTRACT=True
export ARTICLE_TAG_EXTRACT_METHOD=ai
export ARTICLE_TAG_MAX_TAGS=5
export ARTICLE_TAG_AI_AUTO_CREATE=TrueAI 标签提取特性：
- ✅ 优先提取公司名称、产品名称、技术名称等重要实体
- ✅ 智能理解文章上下文，提取最相关的标签
- ✅ 自动过滤过于宽泛的词汇（如“AI”“技术”等）
- ✅ 支持 Qwen3 模型（自动禁用思考功能，直接返回结果）
- ✅ 每个标签 2-15 个字，按重要性排序
常见兼容服务示例：
- DeepSeek：
https://api.deepseek.com - OpenAI：
https://api.openai.com/v1 - Qwen3：
https://dashscope.aliyuncs.com/compatible-mode/v1
使用建议：
- 自动标签依赖外部模型服务，建议先在小规模数据上验证提示词效果与成本
- 若暂时不需要自动提取，可将
article_tag.auto_extract保持为False - 若希望新关键词自动沉淀到标签库，可保持
article_tag.ai.auto_create=True
minio:
enabled: false # 是否启用 MinIO 图片上传
endpoint: "localhost:9000" # MinIO 服务地址
access_key: "minioadmin" # 访问密钥
secret_key: "minioadmin" # 密钥
bucket: "articles" # 存储桶名称
secure: false # 是否使用HTTPS
public_url: "http://localhost:9000" # 公开访问URL（可选）启用 MinIO 后，文章采集过程中会自动下载图片并上传到 MinIO，文章内容中的图片 URL 也会替换为 MinIO 链接。
功能概述： 当前版本只提供 AI 自动提取这一条链路。系统会读取文章标题、描述和正文内容，调用 OpenAI 兼容接口生成标签，并在需要时自动创建新标签后再与文章关联。
配置示例：
article_tag:
auto_extract: True
extract_method: ai
max_tags: 5 # 最大标签数量（默认 5）
ai:
auto_create: True # 自动创建不存在的标签
openai:
api_key: sk-xxx # 必填
base_url: https://api.deepseek.com # 或使用其他 OpenAI 兼容服务
model: deepseek-chat # 也可以替换成其他兼容模型AI 提取工作流程：
- 系统读取文章标题、描述和内容
- 将内容发送到 OpenAI 兼容的 API
- AI 分析文章主题和关键信息，优先提取：
- 公司名称（如：字节跳动、腾讯、OpenAI 等）
- 产品/服务名称（如：ChatGPT、豆包、微信等）
- 技术/工具名称（如：React、TensorFlow 等）
- 人物名称、特定事件、特定领域等
- 返回最相关的标签关键词（默认最多 5 个）
- 系统自动创建标签（如果
auto_create: True） - 将标签关联到文章
Qwen3 模型特殊支持：
- 使用 Qwen3 模型时，系统会自动禁用思考功能
- 确保直接返回 JSON 格式的标签数组，无需额外处理思考过程
补充说明：
extract_method目前保留为配置项，但实际仅支持ai- 如果未配置
OPENAI_API_KEY或openai.api_key，自动提取不会生效 - 自动提取失败不会阻断文章入库，只会跳过该次标签关联
更多配置项请参考 config.example.yaml 文件。
启动服务后，可以通过以下地址访问 API 文档（实际前缀以 API_BASE 为准，默认为 /api/v1/wx）：
- Swagger UI: http://localhost:8001/api/docs
- ReDoc: http://localhost:8001/api/redoc
- OpenAPI Schema: http://localhost:8001/api/openapi.json
Swagger 首页说明中包含 JWT 与 API Key（X-API-Key）两种认证方式；OpenAPI 组件中已注册 ApiKeyHeader，便于对接方引用。
文章列表查询（GET/POST /api/v1/wx/articles）支持：
- 分页：
offset、limit - 标题搜索：
search（多词 OR） - 公众号：
mp_id - 发布时间：
publish_from/publish_to（秒或毫秒，与库内publish_time一致），或日历日publish_date_from/publish_date_to（YYYY-MM-DD，UTC） - 标签：
tag_id、tag_ids（逗号分隔）、tag_match=any|all
更细的字段说明与 curl 示例见 docs/ARTICLE_QUERY_API.md。
POST /api/v1/wx/auth/token- OAuth2 密码模式获取 JWTPOST /api/v1/wx/auth/login- 用户登录（表单）GET /api/v1/wx/auth/verify- 校验 Token
GET/POST /api/v1/wx/api-keys- 列表 / 创建POST /api/v1/wx/api-keys/{id}/regenerate- 轮换密钥
GET /api/v1/wx/mps- 公众号列表（kw、limit、offset）GET /api/v1/wx/mps/{mp_id}- 详情（可匿名，见 Swagger）
GET/POST/api/v1/wx/articles- 文章列表（见上文筛选参数）GET /api/v1/wx/articles/{id}- 文章详情（可匿名）
GET /rss、GET /rss/{feed_id}- RSSGET /feed/{feed_id}.xml等 - 订阅输出
完整列表以 Swagger 为准。
werss/
├── apis/ # API路由层
│ ├── article.py # 文章相关API
│ ├── auth.py # 认证相关API
│ ├── mps.py # 微信公众号相关API
│ ├── rss.py # RSS相关API
│ └── ...
├── core/ # 核心业务逻辑
│ ├── config.py # 配置管理
│ ├── database.py # 数据库操作
│ ├── wx/ # 微信公众号核心逻辑
│ ├── models/ # 数据模型
│ ├── notice/ # 通知模块
│ └── ...
├── jobs/ # 定时任务
│ ├── article.py # 文章采集任务
│ ├── mps.py # 公众号更新任务
│ └── ...
├── driver/ # 浏览器驱动（Playwright）
├── web_ui/ # 前端React应用
│ ├── src/ # 前端源代码
│ │ ├── api/ # API接口封装
│ │ ├── components/# 组件
│ │ ├── views/ # 页面组件
│ │ └── ...
│ ├── package.json # 前端依赖配置
│ └── vite.config.ts # Vite配置
├── main.py # 应用入口
├── web.py # FastAPI应用定义
├── config.example.yaml # 配置文件模板
└── requirements.txt # Python依赖
详细开发指南请参考：
-
添加新API：
# 在 apis/ 目录下创建新文件 # apis/my_feature.py from fastapi import APIRouter router = APIRouter(prefix="/my-feature", tags=["我的功能"]) @router.get("/") async def my_endpoint(): return {"message": "Hello"} # 在 web.py 中注册路由 from apis.my_feature import router as my_feature_router api_router.include_router(my_feature_router)
-
修改数据库模型：
# 在 core/models/ 下修改模型 # 然后运行迁移 python main.py -init True
-
添加定时任务：
# 在 jobs/ 目录下创建任务文件 # 任务会自动注册
- 遵循 Python PEP 8 代码规范
- 使用类型提示（Type Hints）
- 编写清晰的注释和文档字符串
# 检查端口占用
lsof -i :8001 # Linux/Mac
netstat -ano | findstr :8001 # Windows
# 修改端口
export PORT=8002
python main.py -job True -init False- 检查数据库服务是否启动
- 确认连接字符串格式正确
- 检查数据库用户权限
playwright install firefox
# 或
playwright install chromium# 使用国内镜像
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
# 或使用uv（推荐）
uv pip install -r requirements.txt# 确保脚本有执行权限
chmod +x start.sh start_dev.sh
# 确保数据目录可写
mkdir -p data
chmod 755 data更多问题请查看 开发指南 或提交 Issue。
- FastAPI: Web 框架
- SQLAlchemy: ORM 框架
- Playwright: 浏览器自动化
- APScheduler: 定时任务调度
- PyJWT: JWT 认证
- BeautifulSoup4: HTML 解析
- openai: OpenAI 兼容客户端（用于 AI 标签提取）
- psycopg2-binary: PostgreSQL 支持
- PyMySQL: MySQL 支持
- reportlab: PDF 导出支持
- python-docx: Word 文档处理
- minio: MinIO 对象存储客户端（用于图片存储）
完整依赖列表请查看 requirements.txt。
欢迎提交代码、文档或问题反馈。建议按以下流程协作：
- Fork 本项目
- 创建功能分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
详细贡献指南请查看 docs/CONTRIBUTING.md。路线图与课题向待办见 docs/ROADMAP.md。
本项目采用 MIT 许可证。详情请查看 LICENSE 文件。
本项目在开发过程中参考和借鉴了以下开源项目，在此致谢：
- we-mp-rss - 微信公众号热度分析系统，提供了核心功能实现的参考
- wewe-rss - 微信公众号RSS订阅工具，提供了架构设计的灵感
- full-stack-fastapi-template - FastAPI 全栈项目模板，提供了前后端分离架构的最佳实践
感谢这些项目的开发者和贡献者们！
如有问题、建议或使用反馈，可通过以下方式联系：
内容分析增强
- 新增 AI 文章过滤能力，可对文章进行保留、隐藏、待确认等分类处理
- 新增标签聚合与语义聚类能力，支持更清晰地组织和查看标签关系
- 新增微信公众号文章热度指标抓取，支持采集阅读、点赞、在看、评论、转发等数量信息
体验优化
- 优化文章列表与设置页交互，精简无效提示文案和重复操作入口
- 调整部分管理页面在浅色模式下的卡片背景，统一为更清晰的白色面板
功能优化
- 修复并优化标签聚类算法，提升标签标准化效果与聚类详情页可用性
- 修复 MCP 支持相关问题，提升整体接入稳定性
- 完成前端色彩体系向绿色系迁移，统一整体视觉风格
标签体系增强
- 新增标签语义聚类：基于标签 profile、文章共现与 embedding 生成标签主题簇
- 新增相似标签视图与聚类详情页
- 支持聚类 JSON 导出与合并建议展示
- 支持 BigModel / Doubao embedding provider 配置
部署与维护
- 修复
DB环境变量覆盖问题，避免 compose 锁死到错误数据库 - 新增标签聚类部署与验证清单
功能优化
- 应用设置页面新增"定时抓取任务"卡片，可查看调度器运行状态、任务数量及下次执行时间
- 修复水印功能占位符问题，现已显示实际版权文本水印
代码质量
- 使用 asyncio.to_thread 优化 Playwright 同步 API 在异步处理器中的调用
采集稳定性
- 二维码登录存活时间延长并支持自动刷新，但是由于微信限制每天还是要重新扫码登录。
- 爬取间隔
SPAN_INTERVAL默认从 10 调高到 30，降低被微信流控/封禁的风险 MAX_PAGE默认从 5 调低到 3，减少单次连续请求时长- User-Agent 去除
WeRss标识，改为模拟真实 Chrome 浏览器
部署架构重构
- Compose 文件从 4 个叠加简化为 2 个：
docker-compose.yml（完整栈）和docker-compose.app-only.yml（仅应用） - 新用户
cp .env.example .env && docker compose up -d一键启动 - 子项目模式通过环境变量
WERSS_EXTERNAL_NETWORK/WERSS_TRAEFIK_ENABLE配置，无需叠加额外 compose 文件 .env.example重写为 4 个清晰区块，移除 WeRSS 不使用的变量- 全局匿名化，移除所有私有路径和域名引用
- 脚本移除 monorepo 假设（不再加载上级目录
.env） - 文档合并为统一的
docs/DEPLOYMENT.md
初始发布版本。
本项目的开源版本适合用于 Demo、原型验证和技术评估。
如果你有真实业务场景和数据，并且在 AI 架构设计、大模型应用、RAG / Agent 系统、知识工程、信息抽取、模型评估或生产落地方面遇到问题，欢迎沟通合作。
团队长期关注人工智能、自然语言处理、知识工程与大模型应用，可提供：
- AI 技术咨询：顶层方案设计、技术选型与架构规划
- 系统研发：大模型/RAG/Agent 系统定制开发与集成
- 知识工程：垂直领域知识库构建、数据治理与标注
- 私有化部署：本地化部署、性能优化与运维支持
- 学术合作：联合研究、论文发表与项目申报
- 成果转化：软著申请、专利代理与技术转移
我们更关注把研究能力、业务理解和工程落地结合起来，把复杂问题沉淀成可部署、可评估、可持续演进的 AI 方案。
联系方式：
- 📫 Email: wang-hao@shu.edu.cn
- 📧 邮件标题建议注明：
werss 合作 + 机构/需求
⭐ 如果这个项目对你有帮助，欢迎点个 Star ⭐
Maintained by Hao