live-data-sync 1.0.0

Two-step MySQL sync CLI for live streaming data

live-data-sync (lds)

MySQL 两步式直播数据同步 CLI ─ 把指定主播在某段时间内的直播间数据从源库同步到目标库。

功能简介

按 platform_account_id + live_begin_time 范围筛选，分两步把数据同步到目标库：

1. 第一步：同步 live_custom_room_info 表的命中行，并收集所有 live_custom_room_info_id
2. 第二步：基于上一步收集的 ID 集合，分批 IN 查询并同步 live_platform_room_info 表

整个过程幂等：以主键去重，已存在的记录不会被覆盖或重复插入。

---

目录

• 快速开始
• 安装
• 配置
• 使用
• 卸载
• 日志
• 发布到-pypi
• 项目结构

---

快速开始

git clone https://git.ywwl.com/live/live-data-sync.git
cd live-data-sync
bash setup.sh

# 编辑配置文件，填入数据库连接信息
$EDITOR ~/.lds.json

# 执行同步
lds sync 1442088036 2026-04-21 2026-04-27

---

安装

一键安装（推荐）

setup.sh 自动检查 Python、安装 CLI、生成配置模板：

git clone https://git.ywwl.com/live/live-data-sync.git
cd live-data-sync

bash setup.sh                # 完整流程：检查 Python 3.9+ → pip install -e . → lds init
bash setup.sh --skip-config  # 已有 ~/.lds.json 时跳过模板初始化

从 PyPI 安装

pip install live-data-sync

本地开发安装（editable）

git clone https://git.ywwl.com/live/live-data-sync.git
cd live-data-sync
pip install -e .

代码改动即时生效，适合贡献者开发。

不安装直接运行

pip install -r requirements.txt
python -m lds --help

---

配置

配置文件硬编码在 ~/.lds.json，权限 0600。

生成模板

lds init                # 文件不存在时生成模板；已存在则报错
lds init --force        # 强制覆盖已有配置

字段说明

{
  "source_database": {
    "host": "源库 host",
    "port": 3306,
    "database": "源库 database 名",
    "user": "用户名",
    "password": "密码",
    "pool_size": 5
  },
  "target_database": {
    "host": "目标库 host",
    "port": 3306,
    "database": "目标库 database 名",
    "user": "用户名",
    "password": "密码",
    "pool_size": 5
  },
  "sync": {
    "batch_size": 1000,
    "log_dir": "~/.lds/logs"
  }
}

字段	说明	默认
source_database.*	数据来源库连接信息	—
target_database.*	数据接收库连接信息	—
sync.batch_size	IN 查询与 INSERT 的分批大小	1000
sync.log_dir	日志目录（支持 ~）	~/.lds/logs

---

使用

命令总览

lds [-h] [--version] {sync,init,config} ...

子命令:
  sync     执行同步
  init     生成 ~/.lds.json 模板
  config   查询当前配置（密码默认掩码）

lds sync

lds sync <account-id> <start-date> <end-date>

参数：

位置参数	说明
account-id	主播账号 ID（platform_account_id）
start-date	起始日期 YYYY-MM-DD，取当天 00:00:00
end-date	结束日期 YYYY-MM-DD，取当天 23:59:59

示例：

# 同步主播 1442088036 在 2026-04-21 至 2026-04-27 的直播数据
lds sync 1442088036 2026-04-21 2026-04-27

退出码：

• 0：同步成功
• 1：失败（配置缺失、参数错误、数据库异常等）

lds init

lds init             # 在 ~/.lds.json 写入默认模板
lds init --force     # 已存在时覆盖

lds config

查看当前 ~/.lds.json 内容。密码字段默认掩码（首尾各保留 1 位，中间 *），避免在终端或截图里泄露明文。

lds config                                       # 完整配置（密码掩码）
lds config --path                                # 仅打印配置文件路径
lds config --key source_database.host            # 取指定字段
lds config --key source_database                 # 取整个子树（仍掩码）
lds config --show-secrets                        # 不掩码（显示明文密码）
lds config --key source_database.password --show-secrets

参数：

参数	说明
--path	只输出配置文件路径，不读取内容（配置不存在也可用）
--key DOTTED	按 dot 路径取子字段，例如 sync.batch_size
--show-secrets	关闭掩码，输出明文密码（请确认终端可见性后再用）

输出特点：

• 标量字段直接 print（便于 lds config --key sync.batch_size 这类管道使用）
• 子树/全量输出为 JSON（与文件格式一致，可直接 lds config | jq ...）
• 提示信息走 stderr，stdout 始终是合法 JSON
• 字段不存在时 stderr 报错并以 exit 1 返回

---

卸载

一键卸载（推荐）

bash setup.sh --uninstall

三步交互流程：

1. 移除 CLI — pip uninstall live-data-sync
2. 清理配置 — 提示是否删除 ~/.lds.json（默认 N，含明文密码建议清理）
3. 清理日志 — 提示是否删除 ~/.lds/（默认 N，保留历史日志）

手动卸载

pip uninstall live-data-sync   # 移除 CLI
rm -f ~/.lds.json              # 删配置（含明文密码，建议清理）
rm -rf ~/.lds/                 # 删日志目录（如不需保留历史日志）

---

日志

每次 lds sync 会同时输出到 stdout 与日志文件：

• 路径：<log_dir>/sync_YYYY-MM-DD.log（默认 ~/.lds/logs/sync_YYYY-MM-DD.log）
• 编码：UTF-8
• 切分：按天切分（同一天的多次运行追加）

输出格式示例：

2026-04-27 20:33:14 - lds.cli       - INFO - [cli.py:57]  - 初始化数据库连接...
2026-04-27 20:33:15 - lds.sync      - INFO - [sync.py:48] - ===== 开始第一步：同步 live_custom_room_info 表 =====
2026-04-27 20:33:15 - lds.sync      - INFO - [sync.py:77] - 第一步同步完成 - 源表符合条件: 4, 新增记录: 4
2026-04-27 20:33:15 - lds.sync      - INFO - [sync.py:129]- 第二步同步完成 - 源表符合条件: 4, 新增记录: 4
2026-04-27 20:33:15 - lds.cli       - INFO - [cli.py:81] - 总新增: 8

---

从旧 config.ini 迁移

config.ini	~/.lds.json
[source_database] host/port/...	source_database.host/port/...
[target_database] host/port/...	target_database.host/port/...
[sync] batch_size	sync.batch_size
[sync] log_file（已废弃）	sync.log_dir（目录，按天切分）

迁移步骤：

lds init                # 生成新模板
$EDITOR ~/.lds.json     # 把旧字段填入对应位置

---

发布到 PyPI（维护者）

python -m pip install --upgrade build twine
python -m build              # 生成 dist/*.whl 与 *.tar.gz
python -m twine upload dist/*

发布前先确认 PyPI 上 live-data-sync 包名未被占用；如已被占用，改 pyproject.toml 中的 [project] name（如 live-data-sync-cli）。

版本管理：

# 1) 修改 pyproject.toml [project] version 与 lds/__init__.py __version__
# 2) 提交并打 tag
git commit -am "chore: bump version to X.Y.Z"
git tag -a vX.Y.Z -m "release X.Y.Z"
git push origin main --tags

---

项目结构

live-data-sync/
├── pyproject.toml          # hatchling 构建配置
├── setup.sh                # 一键安装脚本
├── requirements.txt        # 运行时依赖（pymysql）
├── README.md
├── lds/
│   ├── __init__.py         # 版本号
│   ├── __main__.py         # python -m lds 入口
│   ├── cli.py              # CLI（sync / init 子命令）
│   ├── config.py           # ~/.lds.json 加载与模板写入
│   ├── database.py         # 连接池
│   └── sync.py             # 两步式同步核心
└── docs/
    └── superpowers/
        ├── specs/          # 设计文档
        └── plans/          # 实现计划

---

调用方式对照

lds 支持三种等价调用路径：

场景	命令	前置条件
PyPI 安装	lds sync ...	pip install live-data-sync
本地 editable	lds sync ...	pip install -e .
源码直跑（无安装）	python -m lds sync ...	pip install -r requirements.txt

---

License

MIT