data-sync-service/USERSCRIPT_USAGE.md

油猴脚本使用指南

📦 安装

1. 安装油猴扩展

首先需要在浏览器中安装油猴（Tampermonkey）扩展：

• Chrome / Edge: Chrome Web Store
• Firefox: Firefox Add-ons
• Safari: App Store

2. 选择脚本版本

项目提供两个版本的脚本：

版本	文件路径	特点	适用场景
增强版	clients/userscript-template.js	功能完整，支持高级配置	需要定时同步、自动同步等高级功能
简化版	client/userscript-template.js	功能精简，易于使用	只需基础同步功能

3. 安装脚本

1. 打开油猴扩展的管理界面
2. 点击"创建新脚本"
3. 复制对应版本的脚本内容
4. 粘贴到编辑器中
5. 保存（Ctrl+S 或 Cmd+S）

⚙️ 初次配置

必须配置的项目

安装脚本后，首次使用前必须配置：

1. 点击页面右侧的 🔄 按钮打开菜单
2. 选择 "⚙️ 配置设置"
3. 配置以下项目：

服务器地址: http://47.122.126.244:5001
密码:       admin123123123

⚠️ 重要：如果不配置正确的服务器地址和密码，同步将会失败！

可选配置项（仅增强版）

• Tag: 留空自动检测，或手动指定（格式：项目名:账号）
• 数据类型: 默认 Cookie
• 过期时间: 默认 604800 秒（7天）
• 自动检测: 建议保持开启
• 自动同步: 页面加载后自动同步（不推荐）
• 定时同步: 定时自动同步间隔，0 表示禁用

🚀 使用方法

基础使用流程

1. 访问支持的网站

   • 目前支持：听悟（tingwu.aliyun.com）、微信公众平台（mp.weixin.qq.com）
   • 增强版支持通过 @match 添加更多网站

2. 登录账号

   • 在目标网站正常登录

3. 同步数据

   • 点击页面右侧的 🔄 按钮
   • 选择 "🔄 立即同步"
   • 等待提示消息

4. 确认结果

   • ✅ 同步成功：显示 Tag 和时间戳
   • ❌ 同步失败：检查错误信息（密码错误、网络错误等）

高级功能（仅增强版）

快捷键操作

Ctrl+Shift+S  - 立即同步
Ctrl+Shift+C  - 复制配置到剪贴板

复制配置

用于分享或备份配置：

1. 点击 🔄 按钮
2. 选择 "📋 复制配置"
3. 配置信息已复制到剪贴板，格式：

{
  "serverUrl": "http://47.122.126.244:5001",
  "password": "admin123123123",
  "tag": "tingwu:user@email.com",
  "type": "cookie"
}

自动同步设置

在配置面板中可以开启：

• 自动同步: 页面加载 3 秒后自动执行同步
• 定时同步: 按设定间隔定期同步（例如：每 300 秒同步一次）

⚠️ 注意：频繁自动同步可能影响页面性能，建议手动同步

🔍 故障排查

问题 1: 提示"同步失败：Invalid password"

原因：密码配置错误

解决方案：

1. 打开配置面板
2. 确认密码为：admin123123123
3. 保存配置后重试

问题 2: 提示"网络错误：无法连接到服务器"

原因：服务器地址不可达

解决方案：

1. 检查服务器地址是否正确：http://47.122.126.244:5001
2. 确认服务器是否在运行
3. 检查网络连接
4. 检查浏览器控制台是否有跨域错误（CORS）

问题 3: 提示"当前网站不支持自动同步"

原因：当前网站不在支持列表中

解决方案：

对于增强版，可以手动添加项目规则：

编辑脚本，在 PROJECT_RULES 中添加：

{
    name: '项目名',
    match: (url) => url.includes('目标域名'),
    getAccount: () => {
        // 提取账号的逻辑
        return '账号名';
    },
    loginUrl: 'https://登录页面URL'
}

对于简化版，需要：

1. 在脚本头部添加 @match 规则：

// @match        https://目标域名/*

2. 在 PROJECT_PATTERNS 中添加配置：

'目标域名': {
    project: '项目名',
    accountSelector: '.账号选择器',
    loginUrl: 'https://登录页面URL'
}

问题 4: 未找到 Cookie

原因：当前页面没有 Cookie 或 Cookie 为空

解决方案：

1. 确认已经登录
2. 刷新页面后重试
3. 检查浏览器是否禁用了 Cookie

问题 5: 服务器响应格式错误

原因：服务器返回了非 JSON 格式的数据

解决方案：

1. 检查服务器是否正常运行
2. 确认 API 端点 /api/data 可访问
3. 查看浏览器控制台的详细错误信息

🎯 最佳实践

1. 安全建议

• ✅ 定期更换密码
• ✅ 不要在公共电脑上使用
• ✅ 配置数据仅存储在本地浏览器
• ❌ 不要将密码分享给他人

2. 使用建议

• ✅ 登录后立即同步，确保数据最新
• ✅ 重要账号手动同步，避免自动同步失败
• ✅ 定期检查同步状态
• ❌ 不要开启过于频繁的定时同步

3. 数据管理

• 数据保存在服务器的 /data 目录
• 文件名格式：项目名_账号.json
• 默认保留 7 天，可在配置中修改
• 可通过 Web 界面查看和管理：http://47.122.126.244:5001

📊 同步数据格式

脚本上传的数据格式：

{
  "tag": "tingwu:user@email.com",
  "type": "cookie",
  "data": {
    "cookies": [
      {
        "name": "cookie名",
        "value": "cookie值",
        "domain": "域名",
        "path": "/"
      }
    ],
    "raw_cookie": "原始cookie字符串",
    "user_agent": "浏览器UA"
  },
  "metadata": {
    "expires_in": 604800,
    "note": "同步备注",
    "login_url": "https://登录页面",
    "created_at": "2026-08-14 10:00:00",
    "updated_at": "2026-08-14 10:00:00"
  }
}

🆘 技术支持

查看日志

1. 打开浏览器控制台（F12）
2. 切换到 Console 标签
3. 查看脚本输出的日志信息

常见日志信息

🚀 通用数据同步脚本已加载     - 脚本初始化成功
🔍 自动检测结果: {...}        - 显示检测到的项目和账号
✅ 数据同步成功: {...}        - 同步成功
❌ 数据同步失败: {...}        - 同步失败，查看错误信息
❌ 网络错误: {...}            - 网络请求失败

获取帮助

如遇到问题，请提供以下信息：

1. 脚本版本（增强版 v3.0 或简化版 v2.0.0）
2. 浏览器类型和版本
3. 目标网站 URL
4. 错误提示信息
5. 浏览器控制台的错误日志

🔄 更新脚本

手动更新

1. 打开油猴管理界面
2. 找到对应的脚本
3. 点击编辑
4. 替换为新版本的代码
5. 保存

检查更新

在油猴管理界面中，可以查看脚本的版本号：

• 增强版当前版本：3.0
• 简化版当前版本：2.0.0

📝 附录

支持的浏览器

• ✅ Chrome 88+
• ✅ Firefox 85+
• ✅ Edge 88+
• ✅ Safari 14+
• ⚠️ Opera（需要测试）
• ❌ IE（不支持）

支持的网站

默认支持：

• 听悟（tingwu.aliyun.com）
• 微信公众平台（mp.weixin.qq.com）

扩展支持： 可通过修改脚本添加更多网站，参考上文"故障排查 - 问题3"

API 兼容性

脚本与以下 API 版本兼容：

• ✅ 当前项目的 nginx/nginx.conf 定义的 API
• ✅ POST /api/data 接口
• ✅ 支持 CORS 跨域请求
• ✅ 密码验证机制