TriliumNext同步功能故障排查与解决方案

问题现象分析

在TriliumNext笔记应用中，用户报告了服务器与本地客户端之间的同步功能失效问题。具体表现为：

1. 客户端尝试同步时返回401错误（"Logged in session not found"）
2. 同步过程在反向代理环境下失败，但直接IP访问时工作正常
3. 服务器日志显示会话验证失败（PUT /api/sync/update rejected with 401）

环境配置要点

典型故障环境具有以下特征：

• 服务器端：Docker容器部署（Unraid系统）
• 客户端：Windows 11平台
• 中间件：Zoraxy反向代理
• 版本信息：TriliumNext 0.91.6

根本原因诊断

经过技术分析，确定问题核心在于会话保持机制失效，具体表现为：

1. Cookie传递问题：反向代理可能未正确处理会话cookie
2. HTTPS/HTTP混合环境：安全连接与普通连接间的会话标识丢失
3. 跨域限制：不同域名访问导致会话无法延续
4. 路径处理异常：日志显示请求URL存在双斜杠（//api/sync/）

解决方案实施

方案一：反向代理配置优化

1. 确保代理正确传递以下头部：
   • Cookie
   • Authorization
   • X-Forwarded-For
2. 检查SSL终端设置，避免多次加密/解密
3. 验证代理的URL重写规则，消除路径异常

方案二：直接连接测试

1. 临时使用服务器本地IP进行同步测试
2. 确认基础功能正常后，再逐步切换至域名访问

方案三：会话管理重置

1. 服务器端：
   • 停止服务
   • 删除data/sessions目录
   • 重启服务
2. 客户端：
   • 清除AppData/Roaming/trilium-data
   • 重新初始化同步

预防性措施建议

1. 环境验证步骤：
   • 先确保内网直连同步正常
   • 再逐步引入代理组件
2. 日志监控：
   • 定期检查服务器PUT /api/sync/update请求
   • 监控401错误出现频率
3. 版本兼容性：
   • 保持客户端与服务器版本一致
   • 特别关注同步协议版本（当前为34）

技术深度解析

同步机制底层依赖：

1. 会话令牌：通过加密cookie维持认证状态
2. 增量同步：基于时间戳的变更检测
3. 冲突处理：采用最后写入优先策略
4. 数据校验：通过SHA-256校验传输完整性

当反向代理不当修改HTTP头或会话标识时，会导致上述机制中断，特别是：

• 代理过滤Set-Cookie头部
• 修改请求路径
• 不规范的SSL卸载
• 未正确传递X-Forwarded-Proto

典型配置示例

正确的反向代理应包含：

location / {
    proxy_pass http://trilium:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_pass_request_headers on;
    proxy_cookie_path / "/; Secure; SameSite=None";
}

总结