初始提交: 通用数据同步服务

- 基于OpenResty的RESTful API服务 - 支持Cookie/Token等数据类型的存储和管理 - 登录认证保护 - Web管理界面 - 数据过期管理
2026-08-14 09:53:32 +08:00
commit edf4dfcd52
22 changed files with 4389 additions and 0 deletions
@@ -0,0 +1,330 @@
+# 部署指南
+
+## 🚀 快速部署
+
+### 1. 环境要求
+
+- Docker & Docker Compose
+- Python 3.7+
+- 开放端口：5001
+
+### 2. 部署步骤
+
+```bash
+# 1. 进入项目目录
+cd /home/hermes/projects/data-sync-service
+
+# 2. 创建数据目录并设置权限
+mkdir -p data
+chmod 777 data
+
+# 3. 启动服务
+docker-compose up -d
+
+# 4. 验证服务
+curl http://localhost:5001/health
+# 预期输出: {"status":"ok"}
+
+# 5. 查看日志
+docker-compose logs -f
+```
+
+### 3. 从 cookie-receiver 迁移
+
+如果你之前使用 cookie-receiver，可以迁移现有数据：
+
+```bash
+# 1. 停止旧服务
+cd /home/hermes/projects/cookie-receiver
+docker-compose down
+
+# 2. 运行迁移脚本
+cd /home/hermes/projects/data-sync-service
+python3 scripts/migrate_data.py
+
+# 3. 启动新服务
+docker-compose up -d
+
+# 4. 验证迁移
+curl http://localhost:5001/api/data
+```
+
+## 🔧 配置过期检测
+
+### 使用 Hermes Cron（推荐）
+
+```bash
+# 添加定时任务（每天上午9点检查）
+hermes cron add \
+  --name "data-sync-expiry-check" \
+  --schedule "0 9 * * *" \
+  --command "python3 /home/hermes/projects/data-sync-service/scripts/check_expiry.py"
+
+# 查看定时任务
+hermes cron list
+
+# 测试立即运行
+python3 /home/hermes/projects/data-sync-service/scripts/check_expiry.py
+```
+
+### 使用系统 Cron
+
+```bash
+# 编辑 crontab
+crontab -e
+
+# 添加以下行（每天上午9点）
+0 9 * * * cd /home/hermes/projects/data-sync-service && python3 scripts/check_expiry.py
+```
+
+## 📱 微信通知配置
+
+脚本的 `print()` 输出会自动通过 Hermes 发送到微信。确保 Hermes 已配置微信通知：
+
+```bash
+# 检查 Hermes 配置
+hermes config show
+
+# 如需配置微信通知，参考 Hermes 文档
+```
+
+## 🌐 外网访问配置
+
+如果需要从外网访问服务，建议使用 Nginx 反向代理：
+
+```nginx
+# /etc/nginx/sites-available/data-sync.conf
+
+server {
+    listen 80;
+    server_name sync.yourdomain.com;
+
+    location / {
+        proxy_pass http://localhost:5001;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```
+
+或使用 HTTPS：
+
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name sync.yourdomain.com;
+
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+
+    location / {
+        proxy_pass http://localhost:5001;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```
+
+## 🔐 安全加固
+
+### 1. 修改默认密码
+
+编辑 `nginx/nginx.conf`，替换所有 `admin123123123` 为新密码：
+
+```bash
+cd /home/hermes/projects/data-sync-service
+sed -i 's/admin123123123/YOUR_NEW_PASSWORD/g' nginx/nginx.conf
+docker-compose restart
+```
+
+同时更新客户端配置。
+
+### 2. IP 白名单
+
+在 `nginx/nginx.conf` 的 `server` 块中添加：
+
+```nginx
+# 只允许特定 IP 访问
+allow 192.168.1.0/24;
+allow 10.0.0.0/8;
+deny all;
+```
+
+### 3. 防火墙配置
+
+```bash
+# Ubuntu/Debian
+sudo ufw allow from 192.168.1.0/24 to any port 5001
+sudo ufw enable
+
+# CentOS/RHEL
+sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="192.168.1.0/24" port protocol="tcp" port="5001" accept'
+sudo firewall-cmd --reload
+```
+
+## 📊 监控和维护
+
+### 查看服务状态
+
+```bash
+cd /home/hermes/projects/data-sync-service
+
+# 查看容器状态
+docker-compose ps
+
+# 查看实时日志
+docker-compose logs -f
+
+# 查看资源占用
+docker stats data-sync-service
+```
+
+### 备份数据
+
+```bash
+# 手动备份
+tar -czf data-backup-$(date +%Y%m%d).tar.gz data/
+
+# 定期备份（添加到 crontab）
+0 2 * * * cd /home/hermes/projects/data-sync-service && tar -czf backups/data-backup-$(date +\%Y\%m\%d).tar.gz data/
+```
+
+### 恢复数据
+
+```bash
+# 停止服务
+docker-compose down
+
+# 恢复备份
+tar -xzf data-backup-20260814.tar.gz
+
+# 启动服务
+docker-compose up -d
+```
+
+### 清理过期数据
+
+```bash
+# 运行清理脚本（删除过期超过30天的数据）
+python3 scripts/clean_expired.py
+```
+
+## 🔄 更新服务
+
+```bash
+cd /home/hermes/projects/data-sync-service
+
+# 1. 备份数据
+tar -czf data-backup-$(date +%Y%m%d).tar.gz data/
+
+# 2. 更新配置文件
+# 编辑 nginx/nginx.conf 或其他文件
+
+# 3. 重启服务
+docker-compose restart
+
+# 4. 验证更新
+curl http://localhost:5001/health
+```
+
+## ❓ 常见问题
+
+### 服务无法启动
+
+```bash
+# 查看日志
+docker-compose logs
+
+# 检查端口占用
+netstat -tlnp | grep 5001
+
+# 检查数据目录权限
+ls -la data/
+chmod 777 data/
+```
+
+### 数据无法保存
+
+```bash
+# 检查磁盘空间
+df -h
+
+# 检查数据目录权限
+ls -la data/
+chmod 777 data/
+
+# 检查容器内文件
+docker exec data-sync-service ls -la /data
+```
+
+### 过期检测不工作
+
+```bash
+# 手动运行测试
+python3 scripts/check_expiry.py
+
+# 检查 Hermes Cron 状态
+hermes cron list
+
+# 查看 Cron 日志
+hermes cron logs data-sync-expiry-check
+```
+
+### 微信通知未收到
+
+```bash
+# 检查 Hermes 配置
+hermes config show
+
+# 测试微信通知
+python3 scripts/check_expiry.py
+
+# 查看 Hermes 日志
+hermes logs
+```
+
+## 📝 维护检查清单
+
+### 每日检查
+- [ ] 服务运行状态
+- [ ] 过期数据通知
+- [ ] 磁盘空间
+
+### 每周检查
+- [ ] 备份数据
+- [ ] 查看错误日志
+- [ ] 清理过期数据
+
+### 每月检查
+- [ ] 更新依赖镜像
+- [ ] 检查安全配置
+- [ ] 测试恢复流程
+
+## 🆘 紧急恢复
+
+如果服务完全不可用：
+
+```bash
+# 1. 停止所有容器
+docker-compose down
+
+# 2. 清理容器和网络
+docker system prune -f
+
+# 3. 从备份恢复数据
+tar -xzf data-backup-YYYYMMDD.tar.gz
+
+# 4. 重新启动
+docker-compose up -d
+
+# 5. 验证服务
+curl http://localhost:5001/health
+curl http://localhost:5001/api/data
+```
+
+## 📞 获取支持
+
+- 查看日志：`docker-compose logs -f`
+- 运行测试：`bash scripts/test_api.sh`
+- 检查配置：查看 `nginx/nginx.conf`
+- 项目文档：`README.md`