# 🐋 Awesome TTRSS

Docker Pulls Docker Stars Docker Automated build FOSSA Status

# 关于

Tiny Tiny RSS (opens new window) 是一款基于 PHP 的免费开源 RSS 聚合阅读器。🐋 Awesome TTRSS 旨在提供一个 「一站式容器化」 的 Tiny Tiny RSS 解决方案，通过提供简易的部署方式以及一些额外插件，以提升用户体验。

# 鸣谢

(opens new window)

# 部署

推荐使用一台 VPS 来部署您的 Awesome TTRSS 实例，DigitalOcean (opens new window) 提供高性价比的 VPS 仅需 $5/月。除此之外，通过 Awesome TTRSS 的 💰OpenCollective 页面 (opens new window) 进行赞助，即可获得定制支持，全托管服务，全托管 VPS 等私人服务。

Awesome TTRSS 支持多架构 x86 ✓arm32v7 ✓arm64v8 ✓（暂不包括 OpenCC API）。

# 通过 Docker 部署

docker run -it --name ttrss --restart=always \
-e SELF_URL_PATH=[ TTRSS 实例地址 ]  \
-e DB_HOST=[ 数据库地址 ]  \
-e DB_PORT=[ 数据库端口 ]  \
-e DB_NAME=[ 数据库名称 ]  \
-e DB_USER=[ 数据库用户名 ]  \
-e DB_PASS=[ 数据库密码 ]  \
-p [ 容器对外映射端口 ]:80  \
-d wangqiru/ttrss

# 通过 Docker Compose 部署

docker-compose.yml (opens new window) 包含了 4 个镜像：

TTRSS (opens new window)
PostgreSQL (opens new window)
Mercury Parser API (opens new window)
OpenCC API (opens new window) arm32v7 ✗arm64v8 ✗

# 步骤

下载 docker-compose.yml (opens new window) 至任意目录。
更改 docker-compose.yml 中的设置，请务必更改 postgres 用户密码。
通过终端在同目录下运行 docker compose up -d 后等待部署完成。
默认通过 181 端口访问 TTRSS，默认账户：admin 密码：password，请第一时间更改。
wangqiru/mercury-parser-api 及 wangqiru/opencc-api-server 为支持高级功能而加入的可选服务类容器，删除不会影响 TTRSS 基础功能。

# 支持的环境变量列表

SELF_URL_PATH: TTRSS 实例地址。🔴 请注意，该变量值必须与你在浏览器中用于访问 TTRSS 的 URL 保持完全一致，否则 TTRSS 将无法启动。
DB_HOST: 数据库地址
DB_PORT: 数据库端口
DB_NAME: 数据库名字
DB_USER: 数据库用户名
DB_PASS: 数据库密码
DB_USER_FILE: Docker Secrets 支持（替代 DB_USE），包含数据库用户名的文件
DB_PASS_FILE: Docker Secrets 支持（替代 DB_PASS），包含数据库密码的文件
ENABLE_PLUGINS: 全局启用的插件名称，其中 auth_internal 为必须启用的登录插件
ALLOW_PORTS: 逗号分隔端口号，如1200,3000。允许订阅非 80,443 端口的源。🔴 谨慎使用。
SESSION_COOKIE_LIFETIME: 使用网页版登陆时 cookie 过期时间，单位为小时，默认为 24 小时
HTTP_PROXY: ip:port, TTRSS 实例的全局代理，为源地址添加单独代理请使用 Options per Feed
DISABLE_USER_IN_DAYS: 当用户 X 天后没有登录后，停止为其自动更新订阅源，直至用户再次登陆
FEED_LOG_QUIET: true 禁用订阅源更新所产生的日志打印

更多环境变量，参见官方 tt-rss (opens new window)。

# 配置 HTTPS

TTRSS 容器自身不负责使用 HTTPS 加密通信。参见下方的样例自行配置 Caddy 或 Nginx 反向代理。使用 Let's Encrypt (opens new window) 可以获取免费 SSL 证书。

# Caddyfile
ttrssdev.henry.wang {
    reverse_proxy 127.0.0.1:181
    encode zstd gzip
}

# nginx.conf
upstream ttrssdev {
    server 127.0.0.1:181;
}

server {
    listen 80;
    server_name  ttrssdev.henry.wang;
    return 301 https://ttrssdev.henry.wang$request_uri;
}

server {
    listen 443 ssl;
    gzip on;
    server_name  ttrssdev.henry.wang;

    ssl_certificate /etc/letsencrypt/live/ttrssdev.henry.wang/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ttrssdev.henry.wang/privkey.pem;

    location / {
        proxy_redirect off;
        proxy_pass http://ttrssdev;

        proxy_set_header  Host                $http_host;
        proxy_set_header  X-Real-IP           $remote_addr;
        proxy_set_header  X-Forwarded-Ssl     on;
        proxy_set_header  X-Forwarded-For     $proxy_add_x_forwarded_for;
        proxy_set_header  X-Forwarded-Proto   $scheme;
        proxy_set_header  X-Frame-Options     SAMEORIGIN;

        client_max_body_size        100m;
        client_body_buffer_size     128k;

        proxy_buffer_size           4k;
        proxy_buffers               4 32k;
        proxy_busy_buffers_size     64k;
        proxy_temp_file_write_size  64k;
    }
}

🔴 请注意，你需要更新 SELF_URL_PATH 环境变量。

# 更新

Awesome TTRSS 会自动监控 TTRSS 官方更新并与之同步，这意味着更新会比较频繁。

TTRSS 官方不再释出 tag (opens new window)。 wangqiru/ttrss:latest 会与官方 main branch (opens new window) 同步。

# 手动更新

通过以下命令进行手动更新：

    docker pull wangqiru/ttrss:latest
    # docker pull wangqiru/mercury-parser-api:latest
    # docker pull wangqiru/opencc-api-server:latest
    docker compose up -d # 如果您没有使用 docker compose，我确信您知道该怎么做。

# 自动更新

样例 Docker Compose 中包含了 Watchtower (opens new window)，它会自动拉取并更新您所有的服务容器（包括当前系统上运行的非 Awesome TTRSS 服务的容器）。该服务默认关闭，启用前请确认它将不会影响您其他的服务容器。

您也可以设置 watchtower 忽略您的其他容器：

service.mercury:
  image: wangqiru/mercury-parser-api:latest
  container_name: mercury
  expose:
    - 3000
  restart: always
  # ⬇️ 这将使 Watchtower 跳过对 mercury-parser-api 的更新检测
  labels:
    - com.centurylinklabs.watchtower.enable=false

# 数据库更新或迁移

Postgres 大版本更新 (15->16) 需要额外的步骤来确保服务正常运行。为了更好地优化 Awesome TTRSS，有时候可能会推出一些破坏性更新。

# 步骤

注意

在升级时，请勿跳过多个大版本，例如直接从 13.x 升级到 16.x 是不支援的，并可能导致数据丢失。

这些步骤演示了如何进行 Postgres 大版本更新（从 15.x 至 16.x），或者从其他镜像迁移至 postgres:alpine。

停止所有服务容器：
```
docker compose stop
```
复制 Postgres 数据卷 ~/postgres/data/（或者你在 Docker Compose 中指定的目录）至其他任何地方作为备份，这非常重要！

执行如下命令来导出所有数据：

docker exec postgres pg_dumpall -c -U 数据库用户名 > export.sql

删除 Postgres 数据卷 ~/postgres/data/。
根据最新 docker-compose.yml (opens new window) 中的database.postgres 部份来更新你的 Docker Compose 文件（注意 DB_NAME 不可更改），并启动：
```
docker compose up -d
```

执行如下命令来导入所有数据：

cat export.sql | docker exec -i postgres psql -U 数据库用户名

测试所有服务是否正常工作，现在你可以移除步骤二中的备份了。

# 插件

# Mercury 全文获取 (opens new window)

全文内容提取插件，配合单独的 Mercury Parser API 服务器使用。样例 Docker Compose 中已经包含了 HenryQW/mercury-parser-api (opens new window) 服务器。

# 设置步骤

在设置中启用 mercury-fulltext 插件
在设置中填入 Mercury Parser API 地址

使用 Awesome-TTRSS 部署的 mercury 可填写service.mercury:3000。

# 全文提取按钮

# FreshRSS / Google Reader API (opens new window)

FreshRSS / Google Reader API插件，用于小型RSS

# Steps

导航到Tiny Tiny RSS中的“首选项”菜单，然后选中 “General” “Enable API”下的框
偏好，打开插件菜单并启用 “freshapi”
配置移动应用程序时，请选择 “FreshRSS”或 “Google Reader API”。根据您的设置，您需要将客户指向TT-RSS安装。如果您使用子域来主持TT-RSS，请使用 https://yoursubdomain.yourdomain.com/plugins.local/freshapi/api/greader.php .如果您在根域上运行，请使用 https://yourdomain.com/plugins.local/freshapi/api/greader.php
使用您的标准TT-RSS用户名和密码。如果您启用了2个因子身份验证（2FA）生成并使用应用程序密码。与所有处理身份验证的插件一样，强烈建议使用开启 HTTPS。