使用 Docker 部署简悦同步助手 · 命令行

[jimlee2048]

同步助手 · 命令行现已提供 Docker 镜像，允许通过 docker 命令或使用 docker-compose 快捷部署，习惯了使用 Docker 部署服务的话，可以试试此方式。

使用 Docker 部署同步助手命令行，你可以：

• 使用提供的多平台镜像，方便在你的 arm 树莓派/ m1 mac / 软路由 / 群晖上部署。
• 隔离、统一的运行容器，避免污染宿主机环境，同时也能避免在不同平台上部署可能存在的奇怪问题。
• 通过 Docker 的 CLI，随时查看同步助手命令行的运行状态，方便进行日志查看、版本更新、停止/重启等维护操作。
• 使用docker-compose持久化你的配置参数，便利服务的部署与后续迁移。
• 配合简悦未来 自定义同步助手的服务地址 的 Feature，实现同步助手的远程部署。
• 配合其他 Docker 镜像，实现更多进阶玩法，请参见下方的进阶使用。

注意： 受当前版本简悦(v2.2.0)的限制， Docker 版的同步助手暂时只适合用作本机部署的用途，不适合作为SaaS服务部署在远程服务器，请参见 远端部署同步助手。

本文将介绍如何使用 Docker 部署简悦同步助手 · 命令行，让我们开始吧：

快速部署

使用 Docker 部署非常简单，这里推荐使用 docker-compose 进行部署：

首先，根据需要，创建并进入用于存放同步助手数据的文件夹，这里以 ~/simpread-sync 为例：

cd ~
mkdir simpread-sync
cd simpread-sync

在创建好的文件夹中，新建文件 docker-compose.yml，文件内容如下：

version: '3'

services:
  simpread-sync:
    image: ghcr.io/j1g5awi/simpread-sync:master
    container_name: simpread-sync
    environment:
      - TZ=Asia/Shanghai
      - SYNC_PATH=/data
      - OUTPUT_PATH=/data/output
    ports:
      - 7026:7026
    volumes:
      - ./data:/data # 同步助手&简悦配置文件保存路径
      - ./output:/data/output # 导出文章保存路径
    restart: unless-stopped

如果你正在小闪存的设备上部署（如 OpenWrt 软路由），在可用磁盘空间不足的情况下，你可能需要使用alpine分支的镜像，请参见 关于 Docker 镜像

如果需要自定义导出路径/配置邮件服务，请参考 修改同步助手暴露的端口号

文件保存后，在docker-compose.yml所在目录下，使用命令行启动同步助手容器：

docker-compose up -d

容器启动后，参考新手教程 - 如何安装和配置同步助手，在简悦插件设置页面授权验证后，开启自动同步并覆盖同步助手本地配置文件。

完成！现在试试看同步助手是否能够正常工作，默认导出的文件将在同步助手数据文件夹下的output文件夹中。

如果你需要修改导出文件夹，请参考自定义同步助手导出文章的保存路径

环境变量说明

环境变量	描述	默认值
TZ	容器所使用的时区
LISTEN_PORT	容器内同步助手的监听端口， 一般无需修改，如需自定义暴露端口，请直接修改docker容器的端口映射（参见修改同步助手暴露的端口号）	7026
SYNC_PATH	容器内同步助手的数据文件目录，用于存放自动同步下来的简悦的配置文件 必填项，一般无需修改，如需自定义目录位置，请直接修改docker容器的目录挂载（参考自定义同步助手导出文章的保存路径）	/data
OUTPUT_PATH	容器内同步助手导出文件的默认文件夹 一般无需修改，如需自定义目录位置，请直接修改docker容器的目录挂载（参见自定义同步助手导出文章的保存路径）	SYNC_PATH下的下的 output 文件夹
AUTO_REMOVE	是否自动删除旧文件，参见同步助手-导出服务-删除旧文件	Fasle
SMTP_HOST	同步助手邮件服务使用的 SMTP 服务器地址
SMTP_PORT	同步助手邮件服务联系 SMTP 服务器使用的端口号	465
SMTP_USERNAME	同步助手邮件服务使用的 SMTP 用户名（一般为发件邮箱地址）
SMTP_PASSWORD	同步助手邮件服务使用的 SMTP 密码
MAIL_TITLE	同步助手发送邮件时使用的邮件标题格式	[简悦] - {{title}}
MAIL_RECEIVER	同步助手邮件服务要发送到的收件邮箱地址
MAIL_KINDLE	同步助手邮件服务要发送到的Kindle邮箱地址
OUTPUT_PATH_{extension}	容器内后缀为{extension}的文件导出到的特定目录，请参见自定义同步助手导出文章的保存路径 当前同步助手命令行支持的后缀名： - html：OUTPUT_PATH_HTML - md: OUTPUT_PATH_MD - epub: OUTPUT_PATH_EPUB - textbundle: OUTPUT_PATH_TEXTBUNDLE

进阶使用

关于 Docker 镜像

#4312 (comment)

修改同步助手暴露的端口号

#4312 (comment)

配置邮件服务

#4312 (comment)

管理同步助手容器

操作前需先进入配置同步助手的 docker-compose.yml所在目录

查看容器运行状态

docker-compose status

停止容器

docker-compose down

重启容器

docker-compose restart

查看容器最新10条日志

docker-compose logs simpread-sync --tail 10

你也可以使用 Portainer进行管理，这里不再赘述。

更新同步助手

手动更新同步助手非常简单，重新执行启动命令即可：

docker-compose up -d

如果检测到更新，容器会自动下载最新镜像并自动重启。

你也可以使用 watchtower实现自动更新，这里不再赘述。

远端部署同步助手

#4312 (comment)

补充说明

#4312 (comment)

关联阅读

• Feature Request: Provide Docker Image · Issue #1 · j1g5awi/simpread-sync (github.com)
• 新手教程: 如何安装和配置同步助手 · Discussion #2754 · Kenshin/simpread (github.com)
• 将简悦 · 同步助手部署在远程（ SaasS 化 ），方便多个扩展端共用一个同步助手 · Discussion #3898 · Kenshin/simpread (github.com)
• Feature Request: 自定义同步助手的服务地址 · Issue #4247 · Kenshin/simpread (github.com)

[Kenshin]

关于 Docker 镜像

本镜像支持amd64与arm64，docker在拉取时会自动选择适配当前架构的镜像。

由于需要安装 pandoc （导出 Epub）和 wkhtml2pdf（导出PDF），所以镜像主分支基于更方便的 debian 打包，镜像体积较大（约700m）。对于在OpenWrt等小闪存环境中使用的用户，请注意你是否有足够的磁盘空间存放镜像。

services:
  simpread-sync:
    image: ghcr.io/j1g5awi/simpread-sync:master

如果不需要导出 Epub 和定制导出 PDF 的功能，可以选用基于 alpine 打包的，体积较小的镜像分支 alpine，只需修改 docker-compose.yml中镜像地址最后的分支名即可：

services:
  simpread-sync:
    image: ghcr.io/j1g5awi/simpread-sync:alpine

[Kenshin]

修改同步助手暴露的端口号

同步助手默认暴露以下端口号：

• 7026：用于连接简悦浏览器插件

示例：希望修改暴露的同步助手的监听端口为17026.

容器使用docker默认的bridge网络模式

为避免混淆，请不要直接修改环境变量LISTEN_PORT的默认值。

没有特别指定的话，docker默认使用的是bridge网络模式。

在该情况下，修改docker-compose.yml中定义的容器端口映射规则即可：

docker容器端口映射规则格式： <宿主机实际外部端口号>:<容器内部端口号>

services:
  simpread-sync:
    ports:
      - 17026:7026

容器使用host网络模式

直接添加环境变量LISTEN_PORT：

services:
  simpread-sync:
    network_mode: "host"
    environment:
      - LISTEN_PORT=17026

[Kenshin]

Done

[Kenshin]

自定义同步助手导出文章的保存路径

为避免混淆，不建议直接修改路径相关的环境变量：OUTPUT_PATH 与 SYNC_PATH 的默认值。

修改导出文章的默认路径

默认情况下，导出的所有文章都会保存在 SYNC_PATH 下的 output 文件夹中。

如果需要自定义导出文章的保存路径，请修改 docker-compose.yml 中映射到容器内的路径 /data/output（OUTPUT_PATH的值）的主机实际路径。

示例：将 /path/to/output 设为同步助手默认导出文章的路径：

docker容器路径映射规则格式： <宿主机实际路径>:<容器内部路径>

services:
  simpread-sync:
    volumes:
      - /path/to/output:/data/output # 导出文章保存路径

自定义特定格式文件的导出路径（增强导出）

在 docker-compose.yml 中：

• 先添加对应文件后缀名的变量 OUTPUT_PATH_{extension}，值设为容器内的导出路径（自定义）

• 随后，添加路径映射规则，将宿主机实际路径映射到容器内的该导出路径中

示例：

• 设置导出markdown格式的文章（文件后缀为md）到宿主机实际路径/another/path/to/output-md，设置容器内导出路径为/output-md
• 设置导出html格式的文章（文件后缀为html）到宿主机实际路径/another/path/to/output-html，设置容器内导出路径为/output-html

services:
  simpread-sync:
    environment:
      - OUTPUT_PATH_MD=/output-md
      - OUTPUT_PATH_HTML=/output-html
    volumes:
      - /another/path/to/output-md:/output-md
      - /another/path/to/output-html:/output-html

[Kenshin]

配置邮件服务

在 docker-compose.yml 中添加相关的环境变量即可，请参考同步助手 - 邮件服务：

services:
  simpread-sync:
    environment:
      - SMTP_HOST=
      - SMTP_PORT=465
      - SMTP_USERNAME=
      - SMTP_PASSWORD=
      - MAIL_TITLE="[简悦] - {{title}}"
      - MAIL_RECEIVER=
      - MAIL_KINDLE=

[Kenshin]

远端部署同步助手

基于 Docker 镜像，我们可以较为方便的在远程服务上部署同步助手命令行，实现多设备配置同步、文章远程统一导出归档等进阶需求。

然而，当前版本的简悦（v2.2.0）连接同步助手时，只能够监听本机上的回环地址127.0.0.1，并不支持修改为其他远程地址，因而无法直接连接部署在非本机上的远程同步助手。唯一连接远程的方法是依靠SSH端口转发的方式曲线救国，请参考将简悦 · 同步助手部署在远程（ SaasS 化 ），方便多个扩展端共用一个同步助手 · Discussion #3898 · Kenshin/simpread (github.com)

对于该问题，我已提交了Feature Request: 自定义同步助手的服务地址 · Issue #4247 · Kenshin/simpread (github.com)，待简悦更新相关功能后，我会再完善本指南的相关内容。

[shininome]

补充

必须要将 simpread_config 放入 ./data 中，不然无法正常连接，疑惑了有点时间，看日志才知道的。

[Kenshin]

谢谢提示，已经记录到教程中。

[shininome]

还有一个问题：使用稍后读的阅读模式，docker的无法正常加载，提示为 请确保 简悦 · 同步助手 处于 [开启状态]
但是查看config中的文件已经同步到nas中，说明已经连接上同步助手了（关闭docker后提示未连接也证明现在是连接状态，重启未恢复）

[Kenshin]

使用稍后读的阅读模式，docker的无法正常加载

这种方式是没法在稍后读中使用阅读模式的，所以会有这个提示。

[naah69]

使用docker部署后，使用md+asserts方式导出时会有以下问题：

1. http导出图片时，证书未知
   

2. 使用base64导出时
   

[naah69]

这个代码有对应仓库吗

[jimlee2048]

这个代码有对应仓库吗

https://github.com/j1g5awi/simpread-sync

[naah69]

请问目前有环境变量能控制请求体大小限制吗

[jimlee2048]

请问目前有环境变量能控制请求体大小限制吗

抱歉，我不是开发者，你可以到原仓库开issue

[Kenshin]

补充关联 j1g5awi/simpread-sync#4

[bicirci]

我是搭配使用了 Obsidian 配置库 , 对配置文件 simpread_config.json 和 快照文件夹 output 有相对位置的要求.
docker-compose.yml 我修改为:

    volumes:
      - .:/data # 同步助手&简悦配置文件保存路径
      - ./output:/data/output # 导出文章保存路径

[bicirci]

还有拉取 ghcr.io 的镜像比较慢, 用了这个镜像站: https://github.com/DaoCloud/public-image-mirror?tab=readme-ov-file#%E4%BD%BF%E7%94%A8%E6%96%B9%E6%B3%95

就是把 docker-compose.yml 里的地址修改为 image: m.daocloud.io/ghcr.io/j1g5awi/simpread-sync:master

[Kenshin]

谢谢提供新的使用思路 👍

[bicirci]

是不是docker的版本比较低, obsidian内同步的内部链接, 也就是 http://localhost:7026/unread/3 这种格式的链接, 跳转到obsidian新分栏标签的 SimpReader Unreader 页面看不到内容, 404报错. 使用1.2.0 的 Linux端的同步助手客户端是可以正常显示的, 不确定是不是需要配置docker的启动参数, 还是版本问题. 另外linux端的同步助手内的版本号没更新, 1.2.0的依然显示1.4.4, 一直跳出更新窗口.