patmanteau/taosync

Docker部署指南

使用Docker和Docker Compose部署taosync的完整指南，实现TrainAsONE和Intervals.icu之间的自动同步。

目录

• 快速开始
• 安装选项
• 配置
• Docker命令
• 调度器配置
• 数据持久化
• 监控和日志
• 故障排除
• 高级用法

---

快速开始

使用Docker Hub（推荐）

bash
# 1. 创建目录结构
mkdir -p taosync/data
cd taosync

# 2. 创建.env文件
cat > .env << 'EOF'
TAO_WEBCAL_URL=https://trainasone.com/webcal/YOUR_ID
INTERVALS_API_KEY=API_KEY=your_key
INTERVALS_ATHLETE_ID=i123456
INTERVALS_THRESHOLD_PACE=05:00
EOF

# 3. 创建docker-compose.yml
cat > docker-compose.yml << 'EOF'
version: '3.8'

services:
  taosync:
    image: docker.xuanyuan.run/patmanteau/taosync:latest
    container_name: taosync
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - ./data:/app/data
    command: taosync schedule
EOF

# 4. 设置数据目录权限
chmod 777 ./data

# 5. 启动服务
docker compose up -d

# 6. 查看日志
docker compose logs -f taosync

完成！ taosync现在将自动：

• 每6小时从TrainAsONE拉取训练计划
• 每天早上8点将即将到来的训练推送到Intervals.icu

---

安装选项

选项1：使用已发布镜像的Docker Compose（推荐）

优势：

• 无需构建
• 使用docker compose pull自动更新
• 下载大小更小
• 启动更快

步骤：

1. 创建docker-compose.yml（参见快速开始）
2. 创建包含您凭据的.env文件
3. 运行docker compose up -d

选项2：本地构建的Docker Compose

优势：

• 从源代码构建
• 使用本地修改
• 开发和测试

步骤：

bash
# 1. 克隆仓库
git clone https://github.com/patmanteau/taosync.git
cd taosync

# 2. 创建.env文件
cp .env.example .env
# 编辑.env文件，填入您的凭据

# 3. 创建数据目录
mkdir -p ./data
chmod 777 ./data

# 4. 构建并启动
docker compose up -d --build

# 5. 查看日志
docker compose logs -f taosync

选项3：Docker Run（不使用Compose）

适用于简单的单容器部署：

bash
# 1. 创建数据目录
mkdir -p ./data
chmod 777 ./data

# 2. 运行容器
docker run -d \
  --name taosync \
  --restart unless-stopped \
  -e TAO_WEBCAL_URL="https://trainasone.com/webcal/YOUR_ID" \
  -e INTERVALS_API_KEY="API_KEY=your_key" \
  -e INTERVALS_ATHLETE_ID="i123456" \
  -e INTERVALS_THRESHOLD_PACE="05:00" \
  -v $(pwd)/data:/app/data \
  docker.xuanyuan.run/patmanteau/taosync:latest \
  taosync schedule

# 3. 查看日志
docker logs -f taosync

---

配置

必需的环境变量

TAO_WEBCAL_URL

您的TrainAsONE WebCal订阅URL。

如何获取：

1. 登录TrainAsONE
2. 进入设置 → 日历订阅
3. 复制WebCal URL

示例：

bash
TAO_WEBCAL_URL=https://trainasone.com/webcal/abc123def456

INTERVALS_API_KEY

您的Intervals.icu API密钥。

如何获取：

1. 登录Intervals.icu
2. 访问[***]
3. 复制您的API密钥（包含API_KEY=前缀）

示例：

bash
INTERVALS_API_KEY=API_KEY=1234567890abcdef

INTERVALS_ATHLETE_ID

您的Intervals.icu运动员ID。

如何获取：

1. 登录Intervals.icu
2. 查看您的个人资料URL：https://intervals.icu/athletes/i123456
3. 您的ID是/athletes/之后的部分（例如，i123456）

示例：

bash
INTERVALS_ATHLETE_ID=i123456

可选的环境变量

INTERVALS_THRESHOLD_PACE

您的阈值配速，格式为分:秒每公里。

默认值： 05:00

重要性： 用于将绝对配速转换为百分比。详见配置指南。

示例：

bash
INTERVALS_THRESHOLD_PACE=04:30  # 较快的跑步者
INTERVALS_THRESHOLD_PACE=05:00  # 默认值
INTERVALS_THRESHOLD_PACE=06:15  # 初学者

INTERVALS_WORKOUT_TAG

应用于同步训练的标签。

默认值： TrainAsONE

bash
INTERVALS_WORKOUT_TAG=TAO-Marathon

数据库和缓存

bash
# 数据库位置（Docker环境保持默认）
DATABASE_URL=sqlite:////app/data/taosync.db

# 缓存持续时间（分钟）
SYNC_INTERVAL=60

调度器配置

控制同步的时间和频率。

拉取计划

bash
# 启用/禁用定时拉取
SCHEDULER_PULL_ENABLED=true

# 从TrainAsONE拉取的时间（cron格式）
SCHEDULER_PULL_CRON="0 */6 * * *"  # 每6小时（默认）

推送计划

bash
# 启用/禁用定时推送
SCHEDULER_PUSH_ENABLED=true

# 推送到Intervals.icu的时间（cron格式）
SCHEDULER_PUSH_CRON="0 8 * * *"  # 每天早上8点（默认）

# 提前同步的天数
SCHEDULER_PUSH_DAYS_AHEAD=7  # 未来7天（默认）

完整的.env示例

bash
# 必需
TAO_WEBCAL_URL=https://trainasone.com/webcal/abc123def456
INTERVALS_API_KEY=API_KEY=1234567890abcdef
INTERVALS_ATHLETE_ID=i123456

# 阈值配速（根据您的体能水平调整）
INTERVALS_THRESHOLD_PACE=04:45

# 训练标签
INTERVALS_WORKOUT_TAG=TrainAsONE

# 调度器：每4小时拉取一次
SCHEDULER_PULL_ENABLED=true
SCHEDULER_PULL_CRON="0 */4 * * *"

# 调度器：每天推送两次（早上和晚上）
SCHEDULER_PUSH_ENABLED=true
SCHEDULER_PUSH_CRON="0 7,19 * * *"
SCHEDULER_PUSH_DAYS_AHEAD=14

# 数据库（保持默认）
DATABASE_URL=sqlite:////app/data/taosync.db

# 缓存：30分钟
SYNC_INTERVAL=30

---

Docker命令

启动和停止

bash
# 启动服务
docker compose up -d

# 停止服务
docker compose down

# 重启服务
docker compose restart

# 停止但不删除容器
docker compose stop

# 停止后启动
docker compose start

查看日志

bash
# 实时跟踪日志
docker compose logs -f taosync

# 查看最后100行
docker compose logs --tail=100 taosync

# 查看特定时间以来的日志
docker compose logs --since=1h taosync

# 查看带时间戳的日志
docker compose logs -t taosync

更新

bash
# 更新到最新版本（已发布镜像）
docker compose pull
docker compose up -d

# 从源代码重新构建（本地构建）
git pull
docker compose build --no-cache
docker compose up -d

容器管理

bash
# 检查容器状态
docker compose ps

# 检查容器健康状况
docker compose ps | grep healthy

# 查看资源使用情况
docker stats taosync

# 访问容器shell
docker compose exec taosync /bin/bash

# 运行一次性命令
docker compose exec taosync taosync pull --list

手动命令

在容器内运行CLI命令：

bash
# 手动拉取
docker compose exec taosync taosync pull

# 强制手动拉取
docker compose exec taosync taosync pull --force

# 列出即将到来的训练
docker compose exec taosync taosync list --upcoming

# 显示特定训练
docker compose exec taosync taosync show 2677 --convert

# 手动推送（单个训练）
docker compose exec taosync taosync push --uid 2677

# 手动推送（所有即将到来的训练）
docker compose exec taosync taosync push --upcoming --days 7

---

调度器配置

理解Cron表达式

调度器使用标准的cron格式：

┌─────────── 分钟 (0-59)
│ ┌─────────── 小时 (0-23)
│ │ ┌─────────── 日 (1-31)
│ │ │ ┌─────────── 月 (1-12)
│ │ │ │ ┌─────────── 星期 (0-6, 星期日 = 0)
│ │ │ │ │
* * * * *

常见计划

bash
# 每6小时
SCHEDULER_PULL_CRON="0 */6 * * *"

# 每天早上8点
SCHEDULER_PUSH_CRON="0 8 * * *"

# 每天两次（早上8点和晚上8点）
SCHEDULER_PUSH_CRON="0 8,20 * * *"

# 每30分钟
SCHEDULER_PULL_CRON="*/30 * * * *"

# 每4小时
SCHEDULER_PULL_CRON="0 */4 * * *"

# 工作日早上7点
SCHEDULER_PUSH_CRON="0 7 * * 1-5"

# 周日早上9点（每周计划）
SCHEDULER_PUSH_CRON="0 9 * * 0"

计划模式

保守模式（最少API调用）：

bash
SCHEDULER_PULL_CRON="0 6,18 * * *"  # 早上6点和晚上6点
SCHEDULER_PUSH_CRON="0 8 * * *"     # 每天早上8点
SCHEDULER_PUSH_DAYS_AHEAD=7

适中模式（默认）：

bash
SCHEDULER_PULL_CRON="0 */6 * * *"  # 每6小时
SCHEDULER_PUSH_CRON="0 8 * * *"    # 每天早上8点
SCHEDULER_PUSH_DAYS_AHEAD=7

频繁模式（始终保持最新）：

bash
SCHEDULER_PULL_CRON="0 */3 * * *"  # 每3小时
SCHEDULER_PUSH_CRON="0 7,19 * * *" # 早上7点和晚上7点
SCHEDULER_PUSH_DAYS_AHEAD=14

手动模式（关闭计划）：

bash
SCHEDULER_PULL_ENABLED=false
SCHEDULER_PUSH_ENABLED=false
# 手动运行命令：docker compose exec taosync taosync pull

调度工作原理

1. 拉取计划：

   • 从TrainAsONE获取最新训练
   • 更新本地数据库
   • 遵守缓存（默认60分钟）

2. 推送计划：

   • 首先自动拉取（确保数据最新）
   • 然后将即将到来的训练推送到Intervals.icu
   • 插入或更新训练
   • 仅影响SCHEDULER_PUSH_DAYS_AHEAD范围内的训练

3. 顺序执行：

   • 推送前始终先拉取
   • 防止竞争条件
   • 确保数据一致性

示例日志输出：

2025-10-15 08:00:00 | INFO | 计划推送：首先拉取最新训练...
2025-10-15 08:00:02 | INFO | 拉取完成，现在推送到Intervals.icu...
2025-10-15 08:00:05 | INFO | 计划推送完成：5个成功，0个错误

---

数据持久化

数据库位置

数据库存储在Docker卷挂载中：

主机： ./data/taosync.db 容器： /app/data/taosync.db

这确保您的数据在容器重启和更新后仍然保留。

目录权限

容器以用户app（UID 999）运行。数据目录必须可写：

bash
# 最简单的方法：对所有人可写
chmod 777 ./data

# 或设置特定所有权（Linux/macOS）
sudo chown 999:999 ./data

备份

bash
# 备份数据库
cp data/taosync.db data/taosync.db.backup

# 带时间戳的备份
cp data/taosync.db data/taosync.db.$(date +%Y%m%d_%H%M%S)

# 从备份恢复
docker compose down
cp data/taosync.db.backup data/taosync.db
docker compose up -d

数据库检查

bash
# 使用sqlite3访问数据库
docker compose exec taosync sqlite3 /app/data/taosync.db

# 显示表
sqlite> .tables

# 显示训练
sqlite> SELECT uid, start, summary FROM workout LIMIT 5;

# 退出
sqlite> .exit

---

监控和日志

实时监控

bash
# 跟踪日志
docker compose logs -f taosync

# 使用grep过滤
docker compose logs -f taosync | grep -i schedule
docker compose logs -f taosync | grep -i error

日志分析

bash
# 检查错误
docker compose logs taosync | grep ERROR

# 检查调度器活动
docker compose logs taosync | grep "Scheduled"

# 统计今天成功推送的数量
docker compose logs --since=24h taosync | grep "Successfully pushed"

# 查看启动日志
docker compose logs --tail=50 taosync | head -20

健康检查

bash
# 容器健康状态
docker compose ps

# 应显示：
# NAME      STATUS             PORTS
# taosync   Up 2 hours (healthy)

# 详细健康检查
docker inspect taosync | grep -A 10 Health

资源使用情况

bash
# 实时统计
docker stats taosync

# 一次性快照
docker stats --no-stream taosync

警报

创建简单的监控脚本：

bash
#!/bin/bash
# monitor-taosync.sh

if docker ps | grep -q taosync; then
    if docker logs --since=5m taosync 2>&1 | grep -qi error; then
        echo "⚠️  在taosync日志中检测到错误"
        docker logs --since=5m taosync | grep -i error
    else
        echo "✓ taosync运行正常"
    fi
else
    echo "❌ taosync容器未运行！"
fi

使用cron定期运行：

bash
# 每小时运行一次
0 * * * * /path/to/monitor-taosync.sh

---

故障排除

容器无法启动

检查状态：

bash
docker compose ps
docker compose logs taosync

常见原因：

• 缺少环境变量
• 无效的cron表达式
• 端口冲突（taosync