Docker搭建FreshRSS私人阅读器

每天查看技术博客、开源项目更新，往往需要来回打开多个网站。使用 FreshRSS，可以把支持 RSS 或 Atom 的内容集中到一个页面，按分类阅读，把重要文章收藏起来。

本教程使用 Docker 搭建 FreshRSS，通过 Caddy 配置 HTTPS，使用 SQLite 保存数据。从安装 Docker 到添加订阅、自动刷新和数据备份，按照下面的步骤完成即可。

1. 项目介绍

FreshRSS 是一款开源的 RSS 阅读器，可以部署在自己的服务器上，通过浏览器管理订阅内容。

它支持订阅分类、未读管理、文章收藏、搜索，以及订阅列表的导入和导出。数据库可以使用 SQLite，也支持其他数据库。

本次教程完成以下功能：

• 使用自己的域名，通过 HTTPS 登录阅读器。
• 集中订阅博客文章和开源项目更新。
• 对订阅源进行分类，收藏需要保留的文章。
• 配置后台自动刷新。
• 导出 OPML 订阅列表。
• 备份项目配置和阅读数据。

本文采用 SQLite，个人使用不需要额外部署数据库，也不需要配置邮件服务器。

2. 相关地址

FreshRSS 项目地址：
https://github.com/FreshRSS/FreshRSS

FreshRSS 官方文档：
https://freshrss.github.io/FreshRSS/

FreshRSS 版本发布：
https://github.com/FreshRSS/FreshRSS/releases

Caddy 自动 HTTPS 文档：
https://caddyserver.com/docs/automatic-https

3. 搭建环境

本次建议使用以下配置：

• CPU：建议 2 核
• 内存：建议 2GB
• 磁盘：建议预留 10GB 可用空间
• 系统：Debian 12 或 Ubuntu 24.04
• Docker：需要安装 Docker Engine
• Compose：使用新版 docker compose 插件
• 域名：一个可以修改 DNS 解析的子域名
• 端口：TCP 80、443 空闲，并允许公网访问

以上是个人演示和小规模使用的建议配置，并非官方最低要求。订阅源和保留文章数量增加后，应关注数据库大小及磁盘空间。

建议使用独立服务器跟随本教程操作。如果服务器已经运行宝塔、Nginx 或其他网站，需要先确认 80、443 端口是否被占用。

服务器还需要能够访问镜像仓库、证书服务和准备订阅的网站。

本次教程推荐使用莱卡云 Linux 云服务器进行搭建。

查看官网购买链接： https://www.lcayun.com

9折优惠码：bloglcayun

4. 搭建视频

配套视频按照以下顺序演示：

1. 安装并验证 Docker 和 Compose。
2. 解析域名，保存部署配置。
3. 启动 FreshRSS，通过 HTTPS 完成安装。
4. 添加订阅源，演示分类、收藏和搜索。
5. 配置自动刷新，导出订阅列表。
6. 备份数据并验证服务恢复运行。

5. 正式搭建

以下命令均在服务器终端执行，使用 root 用户。

如果当前使用具有 sudo 权限的普通用户，先执行：

sudo -i

本文固定使用 freshrss/freshrss:1.30.4 镜像，方便文章与录屏保持一致。

5.1 安装 Docker 和 Docker Compose

Docker 基础操作也可以参考本站的服务器上安装docker和docker-compose教程。

该文章的 Compose 部分采用旧版安装方式，本教程使用新版插件命令：

docker compose

下面已经包含完整安装过程，无需另外补充安装命令。软件源配置采用 Docker 官方 Debian、Ubuntu 安装方式。

在尚未安装 Docker 的新服务器上，执行：

(
  set -e
  . /etc/os-release

  case "$ID" in
    debian)
      freshrss_dist=debian
      freshrss_suite="$VERSION_CODENAME"
      ;;
    ubuntu)
      freshrss_dist=ubuntu
      freshrss_suite="${UBUNTU_CODENAME:-$VERSION_CODENAME}"
      ;;
    *) echo "本教程仅适用于 Debian 或 Ubuntu"; exit 1 ;;
  esac

  apt-get update
  apt-get install -y ca-certificates curl
  install -m 0755 -d /etc/apt/keyrings

  curl -fsSL "https://download.docker.com/linux/$freshrss_dist/gpg" \
    -o /etc/apt/keyrings/docker.asc
  chmod a+r /etc/apt/keyrings/docker.asc

  cat > /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/$freshrss_dist
Suites: $freshrss_suite
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

  apt-get update
  apt-get install -y docker-ce docker-ce-cli containerd.io \
    docker-buildx-plugin docker-compose-plugin

  systemctl enable --now docker
)

安装完成后检查：

docker --version
docker compose version
systemctl is-active docker
docker run --rm hello-world

前两条命令应显示版本信息，第三条应返回：

active

最后一条命令的输出中应包含：

Hello from Docker!

如果已经安装 Docker 和 Compose，并通过上述检查，可以跳过安装步骤。

5.2 解析域名并检查端口

以 rss.example.com 为例，在域名 DNS 管理页面添加一条 A 记录：

本文中的 rss.example.com 只是示例，后续需要替换成自己的域名。

本次使用直接 DNS 解析。如果 DNS 服务提供代理功能，先使用“仅 DNS”模式完成部署。

没有配置可用 IPv6 时，不添加 AAAA 记录；已有错误的 AAAA 记录应先修正。

同时，在云服务器安全组和系统防火墙中放行入站 TCP 80、443，保留现有 SSH 端口。

检查域名解析：

getent ahostsv4 rss.example.com

返回地址应与服务器公网 IPv4 相符。

检查端口占用：

ss -lntp '( sport = :80 or sport = :443 )'

如果已有其他程序监听这些端口，需要先处理冲突，再启动本教程的 Caddy。

5.3 创建目录并配置 HTTPS

创建项目目录：

mkdir -p /opt/freshrss/{data,extensions,caddy,caddy-data,caddy-config}
cd /opt/freshrss

保存域名配置。执行前，将下面的 rss.example.com 换成自己的域名：

cat > .env <<'EOF'
FRESHRSS_DOMAIN=rss.example.com
EOF

chmod 600 .env

这里只填写域名，不加 https://，也不加其他路径。

接着创建 Caddy 配置文件：

cat > caddy/Caddyfile <<'EOF'
{$FRESHRSS_DOMAIN} {
    reverse_proxy freshrss:80
}
EOF

域名解析正确、端口可达后，Caddy 会为该域名申请并续期 HTTPS 证书，同时将 HTTP 访问跳转到 HTTPS。

5.4 保存 Compose 配置并启动

继续在 /opt/freshrss 目录执行：

cat > compose.yaml <<'EOF'
name: freshrss

services:
  freshrss:
    image: freshrss/freshrss:1.30.4
    restart: unless-stopped
    environment:
      TZ: Asia/Shanghai
      CRON_MIN: '*/20'
    volumes:
      - ./data:/var/www/FreshRSS/data
      - ./extensions:/var/www/FreshRSS/extensions
    logging:
      options:
        max-size: '10m'
        max-file: '3'

  caddy:
    image: caddy:2-alpine
    restart: unless-stopped
    depends_on:
      - freshrss
    environment:
      FRESHRSS_DOMAIN: ${FRESHRSS_DOMAIN:?请先填写 .env 中的域名}
    ports:
      - '80:80'
      - '443:443'
    volumes:
      - ./caddy/Caddyfile:/etc/caddy/Caddyfile:ro
      - ./caddy-data:/data
      - ./caddy-config:/config
    logging:
      options:
        max-size: '10m'
        max-file: '3'
EOF

其中：

• data 保存 FreshRSS 配置和 SQLite 数据。
• extensions 保存额外安装的扩展。
• caddy-data 保存证书等数据。
• CRON_MIN 配置后台刷新任务，具体使用方法见第 9 节。

检查配置、拉取镜像并启动：

cd /opt/freshrss
docker compose config -q
docker compose pull
docker compose up -d
docker compose ps

docker compose config -q 成功时通常没有输出。如果出现错误，先修正，再执行后续命令。

查看服务日志：

docker compose logs --tail=80 caddy freshrss

确认 freshrss 和 caddy 两个容器保持运行，再进入浏览器完成安装。

6. 访问页面并创建管理员

在浏览器打开自己的域名：

https://rss.example.com

首次签发证书可能需要一些时间。浏览器没有证书警告后，按安装向导操作：

1、选择语言： 选择简体中文。

2、检查环境： 确认页面中的必要环境检查通过。

3、选择数据库： 数据库类型选择 SQLite，不需要填写外部数据库服务器。

4、配置账号： 填写站点标题、默认用户名，认证方式选择“网页表单”，设置独立的高强度密码。

5、完成安装： 进入登录页面，使用刚创建的账号登录。

站点标题可以填写：

我的订阅中心

服务启动后应随即完成首次安装。

个人使用时，保持匿名访问、匿名刷新和公开注册关闭。然后用浏览器无痕窗口访问一次，确认需要登录才能进入自己的阅读页面。

还可以检查 FreshRSS 记录的站点地址：

cd /opt/freshrss
docker compose exec -T freshrss php -r \
  '$c = include "/var/www/FreshRSS/data/config.php"; echo $c["base_url"], PHP_EOL;'

输出应为自己的 HTTPS 域名，末尾是否带斜杠不影响这里的检查。

7. 添加 RSS 订阅源

登录后，进入“订阅管理”，创建一个分类，例如：

技术订阅

点击添加订阅源，填写 RSS 地址，并选择刚创建的分类。

这里先添加莱卡云博客：

https://blog.lcayun.com/feed/

再添加 FreshRSS 官方项目更新：

https://github.com/FreshRSS/FreshRSS/releases.atom

两个地址分别是 RSS 和 Atom 订阅源，都可以用于 FreshRSS。添加时填写订阅地址、选择分类并保存即可。

返回阅读首页，检查左侧是否出现两个订阅源，以及对应的文章列表。

如果添加失败，先检查服务器是否能访问该地址，再查看源地址是否填写完整。不要把普通网页地址与明确提供的订阅地址混淆。

8. 阅读、收藏和搜索文章

添加订阅后，可以进行以下操作：

1. 点击左侧分类，查看该分类下的文章。
2. 点击文章展开内容。
3. 点击星标收藏需要保留的文章。
4. 进入“收藏”列表，确认刚才的文章已经出现。
5. 在搜索框输入文章标题中的关键词，查找已抓取的内容。
6. 阅读后标记为已读，整理未读列表。

这里的搜索针对自己的订阅内容，不是互联网搜索。

部分网站的 RSS 只提供摘要，FreshRSS 中看到的内容也可能只有摘要。需要阅读完整内容时，可以点击文章标题访问原网站。

另外，订阅源可能只提供最近若干篇文章。首次添加订阅，不代表能够自动获取这个网站的全部历史文章。

9. 配置自动刷新

前面的 Compose 文件已经设置：

CRON_MIN: '*/20'

表示后台任务在每小时的 0、20、40 分触发。

还需要注意，后台任务的触发时间与订阅源的刷新间隔是两层设置。

进入：

配置 → 归档

找到自动刷新间隔相关选项，演示时可将默认间隔设为 20 分钟。如果某个订阅源单独设置了更长的间隔，它仍会遵守自己的设置。

可以在服务器查看定时任务配置：

cd /opt/freshrss
docker compose exec freshrss crontab -l

任务实际运行后，查看最近一次任务的输出：

docker compose exec freshrss cat /tmp/FreshRSS.log

首次任务尚未触发时，这个日志文件可能还不存在。

也可以查看容器日志：

docker compose logs --since=30m freshrss

需要立即检查订阅时，可以在网页中点击刷新按钮。

刷新后没有新增文章，不一定是故障，也可能是原网站没有更新，或者订阅源尚未达到下一次刷新时间。

10. 导出和导入订阅列表

如果以后更换阅读器，可以使用 OPML 迁移订阅列表。

进入：

订阅管理 → 导入／导出

导出时：

1. 选择订阅源列表。
2. 选择需要导出的来源。
3. 下载 OPML 文件并妥善保存。

需要导入时，在同一页面选择已有的 OPML 文件，执行导入，再检查订阅源和分类是否出现。

OPML 主要用于迁移订阅列表和分类，不能代替完整备份。 账号配置、文章数据库及阅读状态等数据，需要通过项目数据备份保留。

11. 数据备份与日常维护

11.1 备份项目数据

本教程将持久化数据统一保存在：

/opt/freshrss

备份前短暂停止服务，可以避免一边写入 SQLite，一边复制数据库文件。官方备份说明也建议维护时停止相关服务和定时任务。

下面的命令会停止服务、打包项目目录、检查归档，再启动服务。执行期间网站会短暂无法访问，建议安排在空闲时段。

(
  set -e
  cd /opt/freshrss
  umask 077

  mkdir -p /opt/backups/freshrss
  backup_file="/opt/backups/freshrss/freshrss-$(date +%Y%m%d-%H%M%S).tar.gz"

  trap 'docker compose start >/dev/null' EXIT

  docker compose stop
  tar -czf "$backup_file" -C /opt freshrss
  tar -tzf "$backup_file" >/dev/null
  docker compose start

  trap - EXIT
  printf '备份文件：%s\n' "$backup_file"
)

docker compose -f /opt/freshrss/compose.yaml ps

完成后，确认两个容器重新运行，并在浏览器中检查能否登录。

备份文件保存在：

/opt/backups/freshrss

建议通过 SFTP 等方式另外下载一份，避免服务器故障时连同本机备份一起丢失。

这个归档包含账号数据和证书文件，应保存在自己控制的位置。

11.2 更新 FreshRSS

更新前先完成备份，并查看目标版本的官方发布说明。

将 compose.yaml 中的：

image: freshrss/freshrss:1.30.4

改成准备升级的稳定版本标签，然后执行：

cd /opt/freshrss
docker compose config -q
docker compose pull freshrss
docker compose up -d freshrss
docker compose ps
docker compose logs --tail=80 freshrss

由于本文固定了版本标签，只执行 pull 而不修改标签，不会自动跨版本升级。

升级后检查登录、订阅刷新、收藏和搜索是否正常。如果升级涉及数据库迁移，不要仅将镜像标签改回旧版就认为完成了回滚，应结合升级前备份恢复。

11.3 恢复备份

需要迁移到新服务器时，先按第 5.1 节安装 Docker。

将自己的备份文件上传到新服务器 /root 目录。下面适用于尚未存在 /opt/freshrss 的空白服务器，执行前替换实际备份文件名：

(
  set -e
  backup_file='/root/freshrss-实际备份时间.tar.gz'

  test -f "$backup_file"
  test ! -e /opt/freshrss || {
    echo '/opt/freshrss 已存在，请改用空白测试服务器'
    exit 1
  }

  tar -tzf "$backup_file" >/dev/null
  tar -xzf "$backup_file" -C /opt
)

如果继续使用原域名，将它的 DNS 记录指向新服务器，确认新服务器的 TCP 80、443 可达，然后启动：

cd /opt/freshrss
docker compose config -q
docker compose up -d
docker compose ps

打开原域名，用原来的账号登录，检查订阅源、分类、收藏及已读状态是否保留。

正常恢复后不需要重新创建管理员。若又出现首次安装向导，应检查备份内容及数据挂载是否正确。

12. 常见问题

12.1 HTTPS 页面打不开怎么办？

依次检查：

• A 记录是否指向实际服务器。
• 是否存在错误的 AAAA 记录。
• 安全组和系统防火墙是否放行 TCP 80、443。
• 这两个端口是否被其他程序占用。
• Caddy 日志是否提示证书签发失败。

查看日志：

cd /opt/freshrss
docker compose logs --tail=100 caddy

12.2 页面提示 502 怎么办？

先检查 FreshRSS 容器：

cd /opt/freshrss
docker compose ps
docker compose logs --tail=100 freshrss

再确认 Caddy 配置中的上游地址仍为：

freshrss:80

12.3 为什么订阅源添加失败？

常见原因包括地址填写错误、服务器无法访问来源网站、来源证书异常，或者网站返回 403、429。

先确认填写的是有效 RSS 或 Atom 地址，再根据错误处理网络或访问频率问题。

12.4 为什么没有自动更新？

先查看容器中的定时任务，再检查订阅源的刷新间隔和最近更新时间。

源站没有新文章时，正常执行的刷新任务也可能没有新增内容。网页中的手动刷新成功，也不能单独证明后台定时任务正常。

12.5 重启容器会丢失订阅吗？

按本文配置，数据保存在服务器的 data 目录中，正常重启容器会继续使用这些数据。

需要注意的是，删除 /opt/freshrss/data 会影响实际阅读数据。清理服务器空间时，应先确认目录用途并做好备份。

13. 写在最后

完成以上步骤后，就可以通过自己的 HTTPS 域名使用 FreshRSS，把技术博客和项目更新集中起来，按分类阅读、收藏，并定期备份数据。

建议先添加少量经常阅读的订阅源，确认自动刷新和备份正常，再逐步扩展订阅数量。

如果还想在服务器上搭建其他实用服务，可以继续阅读本站教程：

• Docker搭建Cloudreve私人网盘教程
• Docker搭建Uptime Kuma网站监控

一个用来整理文件，一个用来检查服务是否正常，再配合 FreshRSS 集中阅读更新，可以逐步完善自己的服务器应用。