K-hermes
a3c23970d7
主要改进： 1. 修复核心Bug - 正确检测API响应状态（检查success字段） 2. 配置界面化 - 使用GM_setValue/GM_getValue持久化存储 3. 添加可视化配置面板 - 无需修改代码 4. 增强错误处理 - 显示详细的错误信息 5. API兼容性验证 - 与后端完全兼容 提供两个版本： - clients/userscript-template.js (v3.0增强版, 608行) - client/userscript-template.js (v2.0简化版, 431行) 新增文档： - USERSCRIPT_CHANGELOG.md - 更新日志 - USERSCRIPT_FIX_SUMMARY.md - 修复总结 - USERSCRIPT_USAGE.md - 使用指南 由Claude Code完成。
313 lines
7.4 KiB
Markdown
313 lines
7.4 KiB
Markdown
# 油猴脚本使用指南
|
||
|
||
## 📦 安装
|
||
|
||
### 1. 安装油猴扩展
|
||
|
||
首先需要在浏览器中安装油猴（Tampermonkey）扩展：
|
||
|
||
- **Chrome / Edge**: [Chrome Web Store](https://chrome.google.com/webstore/detail/tampermonkey/dhdgffkkebhmkfjojejmpbldmpobfkfo)
|
||
- **Firefox**: [Firefox Add-ons](https://addons.mozilla.org/firefox/addon/tampermonkey/)
|
||
- **Safari**: [App Store](https://apps.apple.com/app/tampermonkey/id1482490089)
|
||
|
||
### 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. 配置信息已复制到剪贴板，格式：
|
||
|
||
```json
|
||
{
|
||
"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` 中添加：
|
||
|
||
```javascript
|
||
{
|
||
name: '项目名',
|
||
match: (url) => url.includes('目标域名'),
|
||
getAccount: () => {
|
||
// 提取账号的逻辑
|
||
return '账号名';
|
||
},
|
||
loginUrl: 'https://登录页面URL'
|
||
}
|
||
```
|
||
|
||
**对于简化版**，需要：
|
||
|
||
1. 在脚本头部添加 `@match` 规则：
|
||
```javascript
|
||
// @match https://目标域名/*
|
||
```
|
||
|
||
2. 在 `PROJECT_PATTERNS` 中添加配置：
|
||
```javascript
|
||
'目标域名': {
|
||
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`
|
||
|
||
## 📊 同步数据格式
|
||
|
||
脚本上传的数据格式：
|
||
|
||
```json
|
||
{
|
||
"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 跨域请求
|
||
- ✅ 密码验证机制
|