Merge branch 'v2.0' into master

Author: xuwei95

api/alembic/versions/0003_task_timeout.py

@@ -17,11 +17,15 @@
 
 
 def upgrade() -> None:
-    op.add_column(
-        'task',
-        sa.Column('timeout', sa.Integer(), nullable=True, server_default='0',
-                  comment='任务超时(秒):0=用全局默认,-1=不限(流式/超长),>0=自定义'),
-    )
+    # 幂等:列已存在(如从含该列的 ezdata.sql 建库)则跳过,便于 stamp 基线后重跑
+    bind = op.get_bind()
+    cols = [c['name'] for c in sa.inspect(bind).get_columns('task')]
+    if 'timeout' not in cols:
+        op.add_column(
+            'task',
+            sa.Column('timeout', sa.Integer(), nullable=True, server_default='0',
+                      comment='任务超时(秒):0=用全局默认,-1=不限(流式/超长),>0=自定义'),
+        )
 
 
 def downgrade() -> None:

api/alembic/versions/0004_datasource_remark_text.py

@@ -17,8 +17,12 @@
 
 
 def upgrade() -> None:
-    op.alter_column('data_source', 'remark', existing_type=sa.String(length=500),
-                    type_=sa.Text(), existing_nullable=True)
+    # 幂等:已是 TEXT(如从含该改动的 ezdata.sql 建库)则跳过
+    bind = op.get_bind()
+    col = next((c for c in sa.inspect(bind).get_columns('data_source') if c['name'] == 'remark'), None)
+    if col is not None and 'text' not in str(col['type']).lower():
+        op.alter_column('data_source', 'remark', existing_type=sa.String(length=500),
+                        type_=sa.Text(), existing_nullable=True)
 
 
 def downgrade() -> None:

api/config/get_db.py

@@ -27,6 +27,12 @@ async def init_create_table() -> None:
     :return:
     """
     logger.info('🔎 初始化数据库连接...')
+    # 可选:启动时自动 alembic 迁移(AUTO_MIGRATE=true 才执行,默认关);先于 create_all 跑,先改表结构再建缺失表。
+    from fastapi.concurrency import run_in_threadpool  # noqa: PLC0415
+
+    from config.migrate import run_auto_migrate  # noqa: PLC0415
+
+    await run_in_threadpool(run_auto_migrate)
     async with async_engine.begin() as conn:
         await conn.run_sync(Base.metadata.create_all)
     logger.info('✅️ 数据库连接成功')

api/config/migrate.py

@@ -0,0 +1,48 @@
+"""可选:启动时自动执行 alembic 迁移(默认关,`AUTO_MIGRATE=true` 开启)。
+
+背景:本项目库多由 `*.sql` 初始化、**不在 alembic 管控下**(无 alembic_version 表)。直接
+`alembic upgrade head` 会从 0001_baseline 重跑建表而报错。故本模块:
+  1) 已纳管(有 alembic_version)→ 直接 `upgrade head`;
+  2) 未纳管 → 先 `stamp` 到基线(`AUTO_MIGRATE_BASELINE`,默认 `0002_seed_system`,即 ezdata.sql 对应的
+     "建表+种子"状态)再 `upgrade head`。配合幂等迁移(add/alter 前查存在性),无论新库/滞后库都安全。
+迁移失败只记日志、**不阻断启动**。
+"""
+
+import os
+
+from utils.log_util import logger
+
+
+def _truthy(v: str | None) -> bool:
+    return str(v or '').strip().lower() in ('1', 'true', 'yes', 'on')
+
+
+def run_auto_migrate() -> None:
+    """按 AUTO_MIGRATE 开关执行 alembic 迁移(同步阻塞,由调用方 threadpool 包裹)。"""
+    if not _truthy(os.getenv('AUTO_MIGRATE')):
+        return
+    try:
+        from alembic import command  # noqa: PLC0415
+        from alembic.config import Config  # noqa: PLC0415
+        from alembic.runtime.migration import MigrationContext  # noqa: PLC0415
+        from sqlalchemy import create_engine  # noqa: PLC0415
+
+        from config.database import SYNC_SQLALCHEMY_DATABASE_URL  # noqa: PLC0415
+
+        eng = create_engine(SYNC_SQLALCHEMY_DATABASE_URL)
+        try:
+            with eng.connect() as conn:
+                current = MigrationContext.configure(conn).get_current_revision()
+        finally:
+            eng.dispose()
+
+        cfg = Config('alembic.ini')
+        if current is None:  # 库未纳入 alembic:先标记到基线,避免从 baseline 重跑
+            baseline = (os.getenv('AUTO_MIGRATE_BASELINE') or '0002_seed_system').strip()
+            logger.info(f'🔖 AUTO_MIGRATE: 库未纳入 alembic,先 stamp 到 {baseline}')
+            command.stamp(cfg, baseline)
+        logger.info('⛓️ AUTO_MIGRATE: alembic upgrade head …')
+        command.upgrade(cfg, 'head')
+        logger.info('✅️ AUTO_MIGRATE: 迁移完成')
+    except Exception as e:  # noqa: BLE001
+        logger.error(f'❌ AUTO_MIGRATE 迁移失败(不阻断启动,可手动处理): {e}')

docs/DEPLOY.md

@@ -272,6 +272,8 @@ dev 源码挂载,改完代码后端自动 reload;worker 需 `docker restart ezda
 
 > ⚠️ 新代码会查询新列,**先补列、再上带新代码的镜像**(同一维护窗口);列缺失会导致相关查询报错。
 
+**可选:启动时自动迁移** —— 设环境变量 **`AUTO_MIGRATE=true`**(默认关),后端启动时会自动 `alembic upgrade head`,省去手动。对"未纳入 alembic 的库(无 `alembic_version`,由 `*.sql` 建库)"会**先 stamp 基线再 upgrade**:基线由 `AUTO_MIGRATE_BASELINE` 控制(默认 `0002_seed_system`,即 `ezdata.sql` 对应的建表+种子状态)。迁移做了**幂等**(加列/改类型前查存在性),故对全新库(已含新列)、滞后库、已纳管库都安全;迁移失败只记日志、**不阻断启动**。滞后很多的库若基线不是 0002,把 `AUTO_MIGRATE_BASELINE` 设成它实际对应的版本即可。
+
 ---
 
 ## 10. 安全加固(对外部署)