README.md

metadata

title: WeRSS
emoji: 🐠
colorFrom: green
colorTo: purple
sdk: docker
pinned: false
license: mit

WeRSS · Hugging Face Docker Space

这个目录用于把 CaPaCaptain/WeRSS 部署为 Hugging Face Docker Space。

Dockerfile 不复制 Space 仓库中的业务代码，而是在构建阶段从 GitHub 拉取指定分支或标签，因此 GitHub 仓库更新后，只需在 Hugging Face Space 中执行 Factory rebuild 即可重新构建。

本目录需要作为 Hugging Face Space 仓库的根目录使用。若它保存在主 GitHub 仓库的 huggingface/ 子目录中，请把该目录内的 Dockerfile 和 README.md 同步到 Space 根目录。

1. 部署架构

• 源代码：https://github.com/CaPaCaptain/WeRSS
• Hugging Face SDK：Docker
• 对外端口：7860
• 后端：FastAPI
• 前端：已编译 Vue 静态文件
• 默认数据库：SQLite
• 持久化路径：/data
• API 前缀：/api/v1/wx
• Swagger：/api/docs
• ReDoc：/api/redoc
• OpenAPI：/api/openapi.json

2. 创建 Hugging Face Space

1. 在 Hugging Face 新建 Space。
2. SDK 选择 Docker。
3. 建议第一次部署使用 Private Space。
4. 把本目录中的 Dockerfile 和 README.md 上传到 Space 根目录。
5. 在 Space 的 Settings → Variables and secrets 配置下列项目。
6. 如需持久保存数据库、微信公众号授权、配置、导出文件和缓存，请把持久化存储或 Storage Bucket 挂载到 /data。
7. 保存配置后执行 Factory rebuild。

3. 构建参数与 GitHub 配置

Variables

名称	建议值	是否必须	说明
REPO_URL	https://github.com/CaPaCaptain/WeRSS.git	是	构建时拉取的 GitHub 仓库
REPO_REF	main	是	分支、标签或可解析的 Git 引用
USERNAME	admin	建议	初始化管理员用户名
WEB_NAME	WeRSS微信公众号订阅助手	否	前端显示名称
RSS_BASE_URL	https://你的-space.hf.space/	建议	RSS 对外基础地址，建议以 / 结尾
ENABLE_JOB	True	否	是否启动定时更新任务
THREADS	1	建议	免费 CPU Space 建议保持 1
BROWSER_TYPE	webkit	建议	Playwright 浏览器类型
GATHER_CONTENT	False	否	是否采集正文
GATHER_MODEL	web	否	采集模式：web、api 或 app
GATHER_CONTENT_AUTO_CHECK	True	否	是否自动检查未采集正文
MAX_PAGE	5	否	首次添加公众号时最多采集页数
TOKEN_EXPIRE_MINUTES	4320	否	Web 登录 Token 有效期
LOG_LEVEL	INFO	否	日志级别
PROXY_ENABLED	False	否	是否启用代理
PROXY_HTTP_URL	空	否	HTTP 或 SOCKS5 代理地址
PROXY_DENO_URL	空	否	Deno 代理地址

Dockerfile 已设置以下默认值，通常不用在 Space 中重复配置：

PORT=7860
DB=sqlite:////data/db.db
THREADS=1
AUTO_RELOAD=False

Secrets

名称	是否必须	说明
GITHUB_TOKEN	私有仓库必须	GitHub fine-grained PAT；只授予该仓库 Contents: Read-only
PASSWORD	强烈建议	初始化管理员密码；不要使用上游默认密码
SECRET_KEY	强烈建议	JWT 签名密钥，建议使用至少 32 字节随机值
REDIS_SERVER_PASSWORD	可选	内置 Redis 密码
DINGDING_WEBHOOK	可选	钉钉通知 Webhook
WECHAT_WEBHOOK	可选	企业微信通知 Webhook
FEISHU_WEBHOOK	可选	飞书通知 Webhook
CUSTOM_WEBHOOK	可选	自定义通知 Webhook
CASCADE_API_KEY	可选	级联系统 API Key
CASCADE_API_SECRET	可选	级联系统 API Secret

生成随机密钥示例：

openssl rand -base64 48

私有 GitHub 仓库 Token

建议创建 GitHub fine-grained personal access token：

• Repository access：只选择 CaPaCaptain/WeRSS
• Repository permissions：
  • Contents：Read-only
  • Metadata：Read-only
• 不需要写入、Actions 或管理权限

把 Token 保存为 Hugging Face Secret：GITHUB_TOKEN。

Dockerfile 通过一次性的 Git HTTP Authorization Header 读取该 Secret；Token 不会写入 Git remote，并会在运行应用前清除 GITHUB_TOKEN 环境变量。

4. 持久化

WeRSS 默认会写入：

• SQLite 数据库
• 微信公众号授权 Token
• config.yaml
• 头像与文章相关文件
• 缓存
• PDF、Markdown 等导出文件
• 自动生成的 JWT Secret（未显式设置 SECRET_KEY 时）

Dockerfile 将：

/app/data        → /data
/app/config.yaml → /data/config.yaml

没有挂载持久化存储时，Space 重启、休眠或重建后，上述数据可能丢失。

推荐：

• 挂载路径：/data
• 数据库：默认 sqlite:////data/db.db
• 正式长期运行时可改用外部 PostgreSQL 或 MySQL，并通过 Secret DB 设置连接字符串

数据库连接示例：

# PostgreSQL
postgresql://username:password@host:5432/database

# MySQL
mysql+pymysql://username:password@host:3306/we-rss?charset=utf8mb4

数据库连接字符串包含密码时，必须使用 Secret，不要使用公开 Variable。

5. 本地构建测试

私有 GitHub 仓库

printf '%s' 'github_pat_xxx' > .github_token

docker build \
  --secret id=GITHUB_TOKEN,src=.github_token \
  --build-arg REPO_URL=https://github.com/CaPaCaptain/WeRSS.git \
  --build-arg REPO_REF=main \
  -t werss-hf .

运行：

mkdir -p data

docker run --rm \
  --name werss-hf \
  -p 7860:7860 \
  -v "$PWD/data:/data" \
  -e USERNAME=admin \
  -e PASSWORD='请替换为强密码' \
  -e SECRET_KEY='请替换为随机密钥' \
  -e RSS_BASE_URL='http://localhost:7860/' \
  werss-hf

访问：

http://localhost:7860/
http://localhost:7860/api/docs

公开 GitHub 仓库

docker build \
  --build-arg REPO_URL=https://github.com/CaPaCaptain/WeRSS.git \
  --build-arg REPO_REF=main \
  -t werss-hf .

6. API 配置

BASE_URL=https://你的-space.hf.space
API_BASE=${BASE_URL}/api/v1/wx

Swagger 文档：

${BASE_URL}/api/docs

获取 Bearer Token

curl -X POST "${BASE_URL}/api/v1/wx/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "username=admin" \
  --data-urlencode "password=你的管理员密码"

验证 Token：

curl "${BASE_URL}/api/v1/wx/auth/verify" \
  -H "Authorization: Bearer 你的_access_token"

创建 Access Key

curl -X POST "${BASE_URL}/api/v1/wx/auth/ak/create" \
  -H "Authorization: Bearer 你的_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "n8n",
    "description": "供 n8n 工作流调用",
    "permissions": ["article:read", "article:sync"],
    "expires_in_days": 365
  }'

其他接口、参数和认证方式以 Swagger /api/docs 中当前构建版本为准。

7. n8n / Webhook 接入

在 n8n 的 HTTP Request 节点中：

Base URL: https://你的-space.hf.space/api/v1/wx
Authentication: Header Auth
Header: Authorization
Value: Bearer <access_token>

建议正式自动化使用 Access Key，而不是长期保存管理员用户名与密码。

通知 Webhook 可通过以下 Secrets 配置：

DINGDING_WEBHOOK
WECHAT_WEBHOOK
FEISHU_WEBHOOK
CUSTOM_WEBHOOK

8. 更新与版本锁定

跟随 GitHub main

REPO_REF=main

每次 GitHub 更新后，在 Space 中执行：

Settings → Factory rebuild

固定版本

生产环境建议把 REPO_REF 设置为 Git tag、固定分支或 commit SHA，避免主分支更新造成不可预期变化。

9. Hugging Face 兼容处理

此 Dockerfile 在构建时执行以下调整：

1. 将服务端口从上游默认 8001 改为 Space 公开端口 7860。
2. 将 /app/data 和 /app/config.yaml 持久化到 /data。
3. 把点号环境变量名转换为下划线形式，例如：
   • GATHER.CONTENT → GATHER_CONTENT
   • CACHE.DIR → CACHE_DIR
   • WEBHOOK.CONTENT_FORMAT → WEBHOOK_CONTENT_FORMAT
4. 移除启动时打印全部环境变量的代码，防止 Secrets 出现在日志中。
5. 使用一次性 Git Authorization Header 拉取私有仓库，不把 Token 写入 remote，并在运行前清除 GITHUB_TOKEN。

10. 注意事项

• 微信公众号采集依赖浏览器自动化，镜像较大，首次构建时间和内存占用会高于普通 FastAPI 应用。
• 免费 Space 可能休眠；休眠期间定时更新任务不会持续执行。
• 微信接口可能受出口 IP、地区、风控和授权状态影响。
• 公网部署前必须更改管理员密码并设置 SECRET_KEY。
• 建议初期使用 Private Space，确认登录、授权、RSS 与 API 均正常后再决定是否公开。
• 不要在 README、Dockerfile、GitHub 提交或 Space Variables 中硬编码密码、Token、Webhook 或数据库凭据。