Readest服务器配置：自托管同步服务指南

为什么需要自托管同步服务

你是否曾遇到过在不同设备间切换阅读时，进度无法同步的困扰？或者担心云端服务的隐私安全问题？Readest的自托管同步服务为你提供了完美解决方案。通过搭建私有同步服务器，你可以完全掌控自己的阅读数据，实现跨设备无缝阅读体验，同时保障数据安全与隐私。

自托管同步服务架构概述

Readest同步服务基于KOSync协议实现，支持多设备间的阅读进度、笔记和书签同步。主要组件包括：

• 同步客户端：src/services/sync/KOSyncClient.ts
• 设备端适配：readestsync.lua
• 配置管理：tauri.conf.json

同步流程采用客户端-服务器架构，支持直接连接或通过代理模式访问自托管服务器，适应不同网络环境需求。

准备工作

在开始配置前，请确保你的服务器满足以下要求：

• 操作系统：Linux/macOS/Windows
• 网络：支持HTTP/HTTPS，开放指定端口（默认8080）
• 存储：至少100MB可用空间（根据书籍数量可增加）
• Node.js环境：v16.0.0或更高版本

首先克隆项目仓库到本地服务器：

git clone https://gitcode.com/gh_mirrors/re/readest
cd readest

服务器端配置

基础配置

1. 进入同步服务目录：

cd apps/readest-app/src/services/sync/

2. 修改配置文件KOSyncClient.ts，设置服务器地址：

// 修改第27行的默认服务器地址
this.config.serverUrl = "https://your-server-ip:8080";

3. 配置安全认证： 在KOSyncClient.ts的connect方法中设置认证方式，支持用户名/密码或令牌认证：

// 第43-46行的认证头设置
headers.set('X-Auth-User', this.config.username);
headers.set('X-Auth-Key', this.config.userkey);

高级设置

1. 配置同步超时参数： 在readestsync.lua中调整同步超时设置：

-- 第6行的超时设置
local SYNC_TIMEOUTS = { 10, 20 } -- 连接超时10秒，数据传输超时20秒

2. 启用HTTPS： 修改tauri.conf.json中的安全设置，添加HTTPS支持：

"security": {
  "csp": {
    "connect-src": "'self' https://your-server-ip:8080"
  }
}

客户端配置

桌面端设置

1. 启动Readest应用，进入设置界面
2. 选择"同步"选项卡
3. 勾选"自定义同步服务器"
4. 输入服务器地址：https://your-server-ip:8080
5. 输入用户名和密码
6. 点击"测试连接"验证配置

移动设备设置

移动设备通过readestsync.lua脚本实现同步功能，配置方法：

1. 在设备上打开Readest应用
2. 进入"设置" > "高级" > "同步设置"
3. 配置服务器地址和认证信息
4. 启用自动同步选项

多设备同步配置

设备识别

Readest通过设备ID和名称区分不同设备，配置文件位于KOSyncClient.ts：

// 第186-187行的设备信息设置
device: this.config.deviceName,
device_id: this.config.deviceId,

同步策略

支持多种同步策略，可在KOSyncClient.ts中配置：

• 实时同步：阅读进度实时更新
• 定时同步：按设定时间间隔同步
• 手动同步：用户主动触发同步

测试与验证

连接测试

使用客户端内置的连接测试功能验证服务器配置是否正确：

// 在[KOSyncClient.ts](https://gitcode.com/gh_mirrors/re/readest/blob/9a991a31ba8b596869d578f814b2d6e79f4833df/apps/readest-app/src/services/sync/KOSyncClient.ts?utm_source=gitcode_repo_files)中调用connect方法
async connect(username, password) {
  // 连接测试代码
}

同步测试

1. 在一台设备上打开电子书并阅读几页
2. 等待自动同步或手动触发同步
3. 在另一台设备上打开同一本书
4. 验证阅读进度是否正确同步

常见问题解决

连接失败

1. 检查服务器是否启动，端口是否开放
2. 验证防火墙设置，确保8080端口可访问
3. 检查tauri.conf.json中的CSP设置是否包含服务器地址：

"connect-src": "'self' https://your-server-ip:8080"

同步冲突

当多设备修改同一内容导致冲突时，系统会采用时间戳策略解决。可在KOSyncClient.ts的updateProgress方法中自定义冲突解决策略：

// 第182-188行的同步数据结构
const payload = {
  document: documentHash,
  progress,
  percentage,
  device: this.config.deviceName,
  device_id: this.config.deviceId,
};

性能优化

如果同步速度慢，可调整readestsync.lua中的异步请求设置：

// 第44-68行的异步HTTP配置
package.loaded["Spore.Middleware.AsyncHTTP"] = {}
require("Spore.Middleware.AsyncHTTP").call = function(args, req)
  // 优化异步请求参数
end

安全最佳实践

数据加密

确保所有同步数据通过HTTPS传输，在tauri.conf.json中配置安全协议：

"security": {
  "csp": {
    "default-src": "'self' https:"
  }
}

访问控制

限制服务器访问IP，在KOSyncClient.ts中添加IP白名单：

// 在request方法中添加IP检查
private async request(endpoint, options = {}) {
  // IP白名单检查逻辑
  const allowedIPs = ["192.168.1.0/24", "10.0.0.0/8"];
  // 实现IP验证...
}

总结与展望

通过本文档，你已成功配置Readest自托管同步服务，实现了多设备间的阅读数据同步。主要配置文件包括：

• 核心同步逻辑：src/services/sync/KOSyncClient.ts
• 设备适配脚本：readestsync.lua
• 应用配置：tauri.conf.json

未来版本将支持更多高级功能：

• 端到端加密
• 增量同步
• 多服务器备份

如有任何问题或建议，请参考官方文档或提交issue反馈。