feat(db): SQLite 全量迁移至 MySQL（config.yaml 配置化 + 迁移脚本 + 一致性校验）

- config.yaml database.mysql：host/port/db/user/charset 明文可提交；密码经 password_env
  引用 .env 的 MYSQL_PASSWORD（AGENT.md §33 密钥不进 git）
- config.py _build_mysql_url：URL 优先级 DATABASE_URL env > database.mysql 段 > sqlite 兜底
- pyproject 引入 pymysql>=1.1
- tests/conftest.py 强制每进程 /tmp SQLite（测试绝不触 MySQL 开发库）；test_config 覆盖
  mysql 组装/密码可选/sqlite 兜底分支
- scripts/migrate_sqlite_to_mysql.py：sqlite→mysql 一次性迁移工具（keyset 分页 + chunk
  多值 INSERT + 攒批 commit + 幂等续传 + 低配 MySQL 节流 --throttle-sec + --verify-only
  行数与抽样一致性校验）；已用于 data/quant.db 约 1605 万行迁移并经校验一致

backend/app/core/config.py

@@ -10,6 +10,7 @@ import os
 from dataclasses import dataclass
 from functools import lru_cache
 from pathlib import Path
+from urllib.parse import quote_plus
 
 import yaml
 
@@ -99,6 +100,26 @@ def _normalize_sqlite_url(url: str) -> str:
     return f"{_SQLITE_PREFIX}{(PROJECT_ROOT / rest).resolve()}"
 
 
+def _build_mysql_url(mysql: dict | None) -> str | None:
+    """由 config.yaml database.mysql 段组装 mysql+pymysql URL。
+
+    规则：仅当 enabled 且 host/user/db 齐全时返回 URL；密码经 password_env
+    指定的环境变量读取（AGENT.md §33 密钥只放 .env），未设置则按空密码处理。
+    """
+    if not mysql or not mysql.get("enabled"):
+        return None
+    host = mysql.get("host")
+    user = mysql.get("user")
+    db = mysql.get("db")
+    if not (host and user and db):
+        return None
+    port = mysql.get("port") or 3306
+    charset = mysql.get("charset") or "utf8mb4"
+    password = os.environ.get(mysql.get("password_env") or "MYSQL_PASSWORD", "")
+    auth = f"{quote_plus(user)}:{quote_plus(password)}" if password else quote_plus(user)
+    return f"mysql+pymysql://{auth}@{host}:{port}/{db}?charset={charset}"
+
+
 @lru_cache
 def get_settings() -> Settings:
     """加载并缓存 Settings。config / env 路径可通过参数覆盖以便测试。"""
@@ -115,7 +136,10 @@ def get_settings() -> Settings:
     llm_model_env = agent_llm.get("model_env") or "LLM_MODEL"
 
     default_url = "sqlite:///./data/quant.db"
-    database_url = os.environ.get(url_env) or default_url
+    # URL 优先级：环境变量(DATABASE_URL) > config.yaml database.mysql 段 > SQLite 兜底
+    database_url = os.environ.get(url_env) or _build_mysql_url(
+        _deep(cfg, "database.mysql") or {}
+    ) or default_url
 
     migrations_rel = _deep(cfg, "database.migrations_dir") or (
         "app/infrastructure/persistence/migrations"

backend/pyproject.toml

@@ -14,6 +14,7 @@ dependencies = [
     # Qlib 研究引擎：PyPI 无 aarch64 wheel（见 docs/ROADMAP.md §2 备注），故从源码 git 安装并固定 commit。
     # 网络下载困难时使用 HTTP 代理（见根目录 AGENT.md §0：192.168.1.160:3128）。
     "pyqlib @ git+https://github.com/microsoft/qlib.git@79633dd",
+    "pymysql>=1.1",
 ]
 
 [project.optional-dependencies]

backend/tests/conftest.py

@@ -1,8 +1,10 @@
 """全局测试配置。
 
+- 强制 SQLite 临时文件数据库：默认库已是 MySQL（config.yaml database.mysql），
+  测试绝不允许触碰开发 MySQL（qlib@192.168.1.10）；该 env 在 app 模块
+  首次导入前生效，SessionLocal/engine 会按它构造。
 - JOB_MODE=local：单测/CI 里 Job 在本进程执行（不 spawn 子进程、不依赖安装态）
 - QLIB_SKIP_STALE_JOB_CLEANUP=1：TestClient 启动 lifespan 不清理残留 Job
-  （避免连接/写入开发库 data/quant.db）
 
 必须在任何 app / config 模块首次导入前生效，故放在 conftest 模块顶层。
 """
@@ -11,6 +13,10 @@ from __future__ import annotations
 
 import os
 
+# 测试数据库：每进程唯一 /tmp sqlite 文件（隔离、不落项目目录、不触 MySQL）
+_TEST_DB = f"/tmp/qlib-pytest-{os.getpid()}.db"
+os.environ["DATABASE_URL"] = f"sqlite:///{_TEST_DB}"
+
 # 强制（不是 setdefault）：测试绝不 spawn 研究子进程 / 不触碰开发库
 os.environ["JOB_MODE"] = "local"
 os.environ["QLIB_SKIP_STALE_JOB_CLEANUP"] = "1"

backend/tests/test_config.py

@@ -1,9 +1,10 @@
-"""配置层测试：默认 SQLite 相对路径解析、config.yaml / .env 加载约定。"""
+"""配置层测试：默认 MySQL URL 组装（config.yaml database.mysql）、.env 加载约定、
+SQLite 兜底逻辑。conftest 已强制 DATABASE_URL=tmp sqlite，本文件内用
+monkeypatch/cache_clear 单独验证「无 env 时走 mysql 段」的分支（只组装不连接）。"""
 
 from __future__ import annotations
 
 import os
-from pathlib import Path
 
 from app.core.config import PROJECT_ROOT, _load_env_file, get_settings
 
@@ -14,14 +15,62 @@ def test_project_root_points_to_repo_root() -> None:
     assert (PROJECT_ROOT / "backend").is_dir()
 
 
-def test_default_database_url_resolves_to_project_data_dir() -> None:
+def test_test_runner_isolation_uses_tmp_sqlite() -> None:
+    """conftest 强制每进程唯一 /tmp sqlite，测试绝不触碰 MySQL 开发库。"""
     settings = get_settings()
-    assert settings.database_url.startswith("sqlite:///")
-    # 相对路径应解析到 <项目根>/data/quant.db
-    assert settings.database_url.endswith("/data/quant.db")
-    db_path = Path(settings.database_url.removeprefix("sqlite:///"))
-    assert db_path.is_absolute()
-    assert db_path == PROJECT_ROOT / "data" / "quant.db"
+    assert settings.database_url.startswith("sqlite:////tmp/qlib-pytest-")
+
+
+def test_mysql_default_from_config_yaml(monkeypatch) -> None:
+    """未设 DATABASE_URL 时，config.yaml database.mysql 段组装 MySQL URL（不连接）。"""
+    monkeypatch.delenv("DATABASE_URL", raising=False)
+    get_settings.cache_clear()
+    try:
+        url = get_settings().database_url
+    finally:
+        get_settings.cache_clear()
+    assert url.startswith("mysql+pymysql://qlib:")
+    assert "192.168.1.10:3306/qlib?charset=utf8mb4" in url
+
+
+def test_build_mysql_url(monkeypatch) -> None:
+    from app.core.config import _build_mysql_url
+
+    monkeypatch.setenv("MYSQL_PASSWORD", "p@ss:word")
+    cfg = {
+        "enabled": True,
+        "host": "10.0.0.2",
+        "port": 3307,
+        "db": "q",
+        "user": "u",
+        "password_env": "MYSQL_PASSWORD",
+    }
+    url = _build_mysql_url(cfg)
+    assert url == "mysql+pymysql://u:p%40ss%3Aword@10.0.0.2:3307/q?charset=utf8mb4"
+    # 未启用 / 缺字段 → None（回退 sqlite 兜底）
+    assert _build_mysql_url({**cfg, "enabled": False}) is None
+    assert _build_mysql_url({**cfg, "host": None}) is None
+    assert _build_mysql_url(None) is None
+
+
+def test_mysql_url_password_optional(monkeypatch) -> None:
+    """密码留空（未设 env）也可组装 URL —— 方便仅内网/免密场景。"""
+    from app.core.config import _build_mysql_url
+
+    monkeypatch.delenv("MYSQL_PASSWORD", raising=False)
+    cfg = {"enabled": True, "host": "h", "db": "d", "user": "u"}
+    assert _build_mysql_url(cfg) == "mysql+pymysql://u@h:3306/d?charset=utf8mb4"
+
+
+def test_sqlite_url_normalization_and_fallback() -> None:
+    """仅 sqlite 相对路径被解析为项目根绝对路径；其它 URL 原样透传。"""
+    from app.core.config import _normalize_sqlite_url
+
+    assert _normalize_sqlite_url("mysql+pymysql://u:p@h/d") == "mysql+pymysql://u:p@h/d"
+    abs_url = _normalize_sqlite_url("sqlite:///./data/quant.db")
+    assert abs_url.startswith("sqlite:///")
+    # 绝对路径 sqlite 不再重复解析
+    assert _normalize_sqlite_url("sqlite:////abs/x.db") == "sqlite:////abs/x.db"
 
 
 def test_settings_loaded_from_config_yaml() -> None:
@@ -32,7 +81,7 @@ def test_settings_loaded_from_config_yaml() -> None:
     assert settings.data_source_fallback == "sina"
 
 
-def test_env_file_loading(tmp_path: Path, monkeypatch) -> None:
+def test_env_file_loading(tmp_path, monkeypatch) -> None:
     monkeypatch.delenv("TUSHARE_TOKEN", raising=False)
     env_file = tmp_path / ".env"
     env_file.write_text(
@@ -57,14 +106,14 @@ def test_llm_from_config_yaml() -> None:
 
 
 def test_llm_env_overrides_yaml(monkeypatch) -> None:
-    from app.core.config import get_settings
-
     monkeypatch.setenv("LLM_MODEL", "env-model")
     monkeypatch.setenv("LLM_BASE_URL", "https://example.com/v1")
     monkeypatch.setenv("LLM_API_KEY", "sk-test")
     get_settings.cache_clear()  # Settings 有 lru_cache，刷新以读取新环境变量
-    s = get_settings()
+    try:
+        s = get_settings()
+    finally:
+        get_settings.cache_clear()
     assert s.llm_model == "env-model"
     assert s.llm_base_url == "https://example.com/v1"
     assert s.llm_api_key == "sk-test"
-    get_settings.cache_clear()

backend/uv.lock

@@ -3262,6 +3262,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/64/02/b2606ddf52fa615d4ff3edb2aa05fb064337fa871f99ebb184a39e051cc8/pymongo-4.18.0-cp314-cp314t-win_arm64.whl", hash = "sha256:4a81d166a43e8af1e5152b6854a263ba0a8831f7dd2ca1badc716f219f4f1bc0", size = 817605, upload-time = "2026-09-03T16:00:41.547Z" },
 ]
 
+[[package]]
+name = "pymysql"
+version = "1.2.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c9/bc/1c6a92f385940f727daeecf3bacaf186e03875dff57197801046c583bcf0/pymysql-1.2.0.tar.gz", hash = "sha256:6c7b17ca686988104d7426c27895b455cdeea3e9d3ceb1270f0c3704fead8c33", size = 49021, upload-time = "2026-05-19T08:26:22.302Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c4/bd/2534e130295c8cfd4f0a2e31623baab7502278f1e97bcfe61db75656a77f/pymysql-1.2.0-py3-none-any.whl", hash = "sha256:62169ce6d5510f08e140c5e7990ee884a9764024e4a9a27b2cc11f1099322ae0", size = 45716, upload-time = "2026-05-19T08:26:20.974Z" },
+]
+
 [[package]]
 name = "pyparsing"
 version = "3.3.2"
@@ -3540,6 +3549,7 @@ dependencies = [
     { name = "alembic" },
     { name = "fastapi" },
     { name = "httpx" },
+    { name = "pymysql" },
     { name = "pyqlib" },
     { name = "pyyaml" },
     { name = "sqlalchemy" },
@@ -3563,6 +3573,7 @@ requires-dist = [
     { name = "alembic", specifier = ">=1.13" },
     { name = "fastapi", specifier = ">=0.115" },
     { name = "httpx", specifier = ">=0.28.1" },
+    { name = "pymysql", specifier = ">=1.1" },
     { name = "pyqlib", git = "https://github.com/microsoft/qlib.git?rev=79633dd" },
     { name = "pyyaml", specifier = ">=6.0" },
     { name = "sqlalchemy", specifier = ">=2.0" },