README.md

---
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 中重复配置：

```text
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 |

生成随机密钥示例：

```bash
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 将：

```text
/app/data        → /data
/app/config.yaml → /data/config.yaml
```

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

推荐：

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

数据库连接示例：

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

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

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

## 5. 本地构建测试

### 私有 GitHub 仓库

```bash
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 .
```

运行：

```bash
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
```

访问：

```text
http://localhost:7860/
http://localhost:7860/api/docs
```

### 公开 GitHub 仓库

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

## 6. API 配置

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

Swagger 文档：

```text
${BASE_URL}/api/docs
```

### 获取 Bearer Token

```bash
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：

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

### 创建 Access Key

```bash
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 节点中：

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

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

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

```text
DINGDING_WEBHOOK
WECHAT_WEBHOOK
FEISHU_WEBHOOK
CUSTOM_WEBHOOK
```

## 8. 更新与版本锁定

### 跟随 GitHub main

```text
REPO_REF=main
```

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

```text
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 或数据库凭据。