Skip to content

setup.md

Latest commit

 

History

History
330 lines (228 loc) · 10.4 KB

setup.md

File metadata and controls

330 lines (228 loc) · 10.4 KB
Raw

Suwayomi-Server 配置教程

本教程指导你部署 Suwayomi-Server 并配置漫画助手插件。

目录

第一步：部署 Suwayomi-Server

推荐使用 Docker 部署，简单可靠。

方式一：Docker Compose（推荐）

  1. 创建目录：

    mkdir -p ~/suwayomi && cd ~/suwayomi

  2. 创建 docker-compose.yml：

    services:
  suwayomi:
    image: ghcr.io/suwayomi/suwayomi-server:stable
    container_name: suwayomi-server
    volumes:
      - ./data:/home/suwayomi/.local/share/Tachidesk
    ports:
      - "4567:4567"    # 左边的端口可以改，右边必须是 4567
    environment:
      - TZ=Asia/Shanghai
      # 如果需要认证，取消下面的注释并填写：
      # - AUTH_MODE=basic_auth
      # - AUTH_USERNAME=admin
      # - AUTH_PASSWORD=你的密码
    restart: unless-stopped

  3. 启动：

    docker compose up -d

  4. 验证服务运行：

    浏览器打开 http://localhost:4567/ ，能正常访问WebUI即表示成功。

方式二：Docker 命令

docker run -d \
  --name suwayomi-server \
  -p 4567:4567 \
  -v ~/suwayomi/data:/home/suwayomi/.local/share/Tachidesk \
  -e TZ=Asia/Shanghai \
  --restart unless-stopped \
  ghcr.io/suwayomi/suwayomi-server:stable

方式三：直接下载

从 Suwayomi-Server Releases 下载对应系统的包：

  • Windows: 下载 win64 包，解压后双击启动脚本
  • macOS: 下载 macOS-arm64（M 芯片）或 macOS-x64（Intel），解压后运行
  • Linux: 下载 linux-x64，解压后运行启动脚本

默认访问地址：http://localhost:4567

认证配置（可选）

如果你的 Suwayomi-Server 暴露在公网上，建议开启认证。

通过环境变量配置（Docker）：

环境变量 说明 示例
AUTH_MODE 认证模式 none / basic_auth / ui_login
AUTH_USERNAME 用户名 admin
AUTH_PASSWORD 密码 your_password

通过 WebUI 配置：

  1. 打开 http://你的服务器地址:4567
  2. 进入设置（齿轮图标）
  3. 找到「服务器设置」→「认证模式」
  4. 选择模式并设置用户名密码

认证模式说明：

模式 说明 插件配置对应
none 无认证 auth_mode: none
basic_auth HTTP Basic 认证 auth_mode: basic
ui_login JWT 令牌认证 auth_mode: jwt

如果在内网使用，none 模式即可。公网部署建议用 basic_auth 或 ui_login。

常用环境变量

变量 默认值 说明
BIND_PORT 4567 服务端口（容器内）
TZ Etc/UTC 时区
WEB_UI_CHANNEL stable WebUI 更新渠道
UPDATE_INTERVAL 12 书库自动更新间隔（小时）

完整环境变量列表见 Suwayomi-Server-docker README。

第二步：安装漫画源扩展

Suwayomi 本身不包含漫画内容，需要安装「扩展」来连接漫画源网站。而Suwayomi 本身也不包含扩展库，所以需要先手动添加。

操作步骤

  1. 打开 Suwayomi WebUI：http://你的服务器地址:4567

  2. 点击左侧菜单的「设置」→「浏览」→「扩展库」，添加合适的扩展库（如keiyoushi中提供的库链接）

  3. 点击左侧菜单的「浏览」（Browse），再点击上方「扩展」标签

  4. 浏览可用扩展列表，找到你想用的源，点击「安装」：

    • 中文用户推荐：拷贝漫画、再漫画、Komiic 等
    • 英文用户推荐：MangaDex、MangaPlus 等

  5. 安装完成后，扩展状态变为「已安装」

  6. 安装扩展后，可在 Suwayomi-Server 的 WebUI 中调整插件的相关设置，如登录状态、语言过滤等。

第三步：配置 AstrBot 插件

安装插件

在Astrbot 插件市场中点击安装本插件，或Git安装：

cd AstrBot/data/plugins
git clone https://github.com/FFFold/astrbot_suwayomi_server.git

配置

在 AstrBot WebUI 的插件管理中找到「Suwayomi 漫画助手」，点击设置。完整配置项说明见 README 配置表。

网络连通性：AstrBot 所在机器必须能访问 Suwayomi-Server 地址。如果 AstrBot 和 Suwayomi 都在同一台机器上，用 http://localhost:4567。如果 AstrBot 运行在 Docker 中，则需要使用宿主机 IP 或 Docker 网桥 IP 确保 Suwayomi-Server 对 Astrbot 可达。

填写示例

配置项在 WebUI 插件设置中按分组展示（服务器连接 / 卡片渲染 / 阅读体验 / 下载打包 / 自动推送 / AI 漫画工具 / 高级）。

场景 1：同一台机器，无认证

server:
  server_url: http://localhost:4567
  auth_mode: none

场景 2：Suwayomi 在另一台服务器，Basic 认证

server:
  server_url: http://192.168.1.100:4567
  auth_mode: basic
  username: admin
  password: mypassword123

场景 3：Suwayomi 在公网，JWT 认证

server:
  server_url: https://manga.example.com
  auth_mode: jwt
  username: admin
  password: mypassword123

第四步：验证

在聊天中发送以下命令逐步验证：

# 1. 检查源列表
/漫画 源

# 2. 搜索测试
/漫画 搜索 海贼王

# 3. 订阅测试
/漫画 订阅 1

# 4. 查看订阅
/漫画 我的订阅

# 5. 查看章节
/漫画 章节 海贼王

# 6. 强制刷新章节（可选）
/漫画 章节 海贼王 --刷新

# 7. 阅读测试
/漫画 阅读 海贼王 1

如果第 1 步就失败（返回"漫画服务暂时不可用"），说明 AstrBot 无法连接到 Suwayomi-Server，检查：

  • Suwayomi-Server 是否在运行
  • server_url 是否正确
  • 防火墙是否放行了端口
  • AstrBot 所在网络是否能访问 Suwayomi 地址

⚠️ 更换 Suwayomi-Server 实例的注意事项

漫画 ID 和章节 ID 由 Suwayomi-Server 数据库自动生成，每个实例的数据库独立，ID 互不通用。这意味着不能直接更换后端实例而不做处理，否则：

  • 已有的订阅记录中的 manga_id 会指向错误的漫画或不存在
  • 自动更新检查会失败或查错漫画
  • 阅读/下载命令中使用的章节号可能对应错误内容

哪些数据绑定在实例上？

数据 存储位置 是否绑定实例
订阅记录（漫画名、manga_id、source_id） AstrBot KV 存储 ✅ 是
章节缓存时间戳 AstrBot KV 存储 ✅ 是（按 manga_id）
漫画元数据（标题、封面等） Suwayomi 数据库 ✅ 是
章节列表 Suwayomi 数据库 ✅ 是
已安装的扩展/源 Suwayomi 数据库 ✅ 是

迁移方案

方案一：复制数据库文件（推荐）

直接复制原实例的数据库文件到新实例，保持 ID 一致：

# Docker 环境下，数据库文件在挂载卷中
# 例如原实例数据目录为 ~/suwayomi/data
cp ~/suwayomi/data/tachidesk.mv.db /新实例数据目录/tachidesk.mv.db

注意：复制前需停止原实例，确保数据库文件完整。复制后两个实例的数据库内容完全相同，ID 一致。

方案二：重新订阅

如果无法复制数据库（例如跨版本不兼容），需要在新实例上重新订阅：

  1. 确认新实例已安装相同的源扩展（源 ID 也可能不同）
  2. 在聊天中执行 /漫画 更新 --刷新 强制刷新所有订阅（会因 ID 不匹配而失败）
  3. 逐个取消旧订阅：/漫画 取消订阅 <漫画名>
  4. 重新搜索并订阅：/漫画 搜索 <漫画名> → /漫画 订阅 <序号>
  5. 通知所有订阅者重新订阅

方案三：仅更换地址（同实例）

如果只是 Suwayomi-Server 换了地址（如迁移服务器但保留了数据库），只需修改插件配置中的 server_url，无需其他操作。

如何避免此问题？

  • 备份数据库：定期备份 Suwayomi 的数据目录（包含 tachidesk.mv.db）
  • 使用 Docker 卷：通过 Docker 卷管理数据，迁移时直接复制卷
  • 记录源 ID：不同实例的源 ID 可能不同，迁移后需确认源 ID 一致

常见问题

搜索返回"未找到相关漫画"

Suwayomi 中没有安装漫画源扩展。去 WebUI 的「扩展」页面安装源。

搜索返回"Unknown type 'Long'"

Suwayomi-Server 版本过旧。升级到最新稳定版：

docker pull ghcr.io/suwayomi/suwayomi-server:stable
docker compose up -d

图片发送失败

AstrBot 所在机器需要能访问 Suwayomi 的图片 URL。如果 Suwayomi 在内网，确保 AstrBot 也在同一网络中。

合并转发模式不生效（QQ）

send_mode 设为 forward 时，仅在 aiocqhttp（Napcat/Lagrange）平台生效，其他平台自动回退为直接发图。

更新推送不工作

  • 确认已使用 /漫画 订阅 订阅了漫画
  • 确认 Suwayomi 的书库中有该漫画（在 WebUI 中能看到）
  • 插件默认每 60 分钟检查一次，可通过 /漫画 更新 手动触发
  • 检查 AstrBot 日志中是否有错误信息

章节数据不是最新的

插件默认缓存章节数据 6 小时。如需强制刷新：

  • 使用 /漫画 章节 <漫画名> --刷新 从源重新拉取
  • 或在配置中将 chapter_cache_hours 设为 -1（每次都刷新）或 0（永不自动刷新）

连接超时或拒绝连接

# 从 AstrBot 所在机器测试连通性
curl http://你的Suwayomi地址:端口/api/v1/settings/about

如果超时，检查：

  • Suwayomi 容器是否在运行：docker ps | grep suwayomi
  • 端口映射是否正确：docker port suwayomi-server
  • 防火墙规则

认证失败

  • 确认 AstrBot 插件的 auth_mode 按下表对应 Suwayomi 的 AUTH_MODE：none→none，basic_auth→basic，ui_login→jwt
  • none 对应 none，basic_auth 对应 basic，ui_login 对应 jwt
  • 确认用户名密码正确