huace-aigc-auth-client 1.1.5__tar.gz → 1.1.7__tar.gz

{huace_aigc_auth_client-1.1.5/huace_aigc_auth_client.egg-info → huace_aigc_auth_client-1.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: huace-aigc-auth-client
-Version: 1.1.5
+Version: 1.1.7
 Summary: 华策AIGC Auth Client - 提供 Token 验证、用户信息获取、权限检查、旧系统接入等功能
 Author-email: Huace <support@huace.com>
 License: MIT
@@ -45,7 +45,7 @@ pip install huace-aigc-auth-client
 AIGC_AUTH_APP_ID=your_app_id
 AIGC_AUTH_APP_SECRET=your_app_secret
 
-# 可选：鉴权服务地址（默认为生产环境）
+# 可选：鉴权服务地址（默认为生产环境）- 测试环境鉴权地址：https://auth-test.aigc.huacemedia.com/aigc-auth/api/v1
 AIGC_AUTH_BASE_URL=https://aigc-auth.huacemedia.com/aigc-auth/api/v1
 ```
 
@@ -328,21 +328,21 @@ except AigcAuthError as e:
 
 ```
 ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
-│   aigc-auth     │────▶│   SDK 同步层    │────▶│   旧系统        │
-│   (鉴权中心)    │     │   (字段映射)    │     │   (用户表)      │
+│   aigc-auth     │────▶│   SDK 同步层     │────▶│   旧系统         │
+│   (鉴权中心)     │     │   (字段映射)     │     │   (用户表)       │
 └─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
-        │   1. 初始化同步       │                       │
+        │   1. 初始化同步        │                       │
         │◀──────────────────────────────────────────────│
-        │   (批量同步旧用户到 auth)                     │
+        │   (批量同步旧用户到 auth)                       │
         │                       │                       │
-        │   2. 增量同步         │                       │
+        │   2. 增量同步          │                       │
         │──────────────────────▶│──────────────────────▶│
-        │   (auth 新用户自动同步到旧系统)               │
+        │   (auth 新用户自动同步到旧系统)                  │
         │                       │                       │
-        │   3. Webhook 推送     │                       │
+        │   3. Webhook 推送      │                       │
         │──────────────────────────────────────────────▶│
-        │   (用户变更主动通知)                          │
+        │   (用户变更主动通知)                            │
 ```
 
 ### 快速开始
@@ -357,7 +357,7 @@ AIGC_AUTH_BASE_URL=https://aigc-auth.huacemedia.com/aigc-auth/api/v1
 
 # 同步配置
 AIGC_AUTH_SYNC_ENABLED=true
-AIGC_AUTH_SYNC_PASSWORD=Abc@123456
+AIGC_AUTH_SYNC_PASSWORD=通用密码
 AIGC_AUTH_WEBHOOK_URL=https://your-domain.com/api/v1/webhook/auth
 AIGC_AUTH_WEBHOOK_SECRET=your_secret
 ```
@@ -407,7 +407,7 @@ field_mappings = [
 sync_config = create_sync_config(
     field_mappings=field_mappings,
     password_mode=PasswordMode.UNIFIED,
-    unified_password="Abc@123456",
+    unified_password="通用密码",
     webhook_url="https://your-domain.com/api/v1/webhook/auth",
 )
 ```
@@ -486,18 +486,94 @@ async def auth_middleware(request, call_next):
 
 #### 5. 添加 Webhook 接收端点
 
+**推荐方式：使用 SDK 提供的通用 Webhook 路由**
+
 ```python
+from fastapi import APIRouter
+from huace_aigc_auth_client import register_webhook_router
+
+api_router = APIRouter()
+
+# 定义 webhook 处理函数
+async def handle_webhook(data: dict) -> dict:
+    """
+    处理来自 aigc-auth 的 webhook 通知
+    
+    Args:
+        data: webhook 数据，包含 event 和 data 字段
+        
+    Returns:
+        dict: 处理结果
+    """
+    from your_app.db import get_db_session
+    
+    event = data.get("event")
+    user_data = data.get("data", {})
+    
+    # 创建数据库会话
+    async with get_db_session() as db:
+        adapter = MyLegacyAdapter(db, sync_config)
+        
+        if event == "user.created":
+            # 处理用户创建事件
+            if not adapter.get_user_by_unique_field(user_data["username"]):
+                legacy_data = adapter.transform_auth_to_legacy(user_data)
+                legacy_data["password"] = sync_config.unified_password
+                adapter.create_user(legacy_data)
+                await db.commit()
+        
+        elif event == "user.updated":
+            # 处理用户更新事件
+            legacy_data = adapter.transform_auth_to_legacy(user_data)
+            adapter.update_user(user_data["username"], legacy_data)
+            await db.commit()
+    
+    return {"status": "ok", "event": event}
+
+# 注册 webhook 路由（自动处理签名验证）
+register_webhook_router(
+    api_router,
+    handler=handle_webhook,
+    prefix="/webhook",  # 可选，默认 "/webhook"
+    secret_env_key="aigc-auth-webhook-secret",  # 可选，在 auth 后台配置
+    tags=["Webhook"]  # 可选，默认 ["Webhook"]
+)
+
+# webhook 端点将自动创建在: /webhook/auth
+```
+
+**传统方式：手动实现 Webhook 端点**
+
+```python
+import hmac
+import hashlib
+import os
+
 @app.post("/api/v1/webhook/auth")
 async def receive_auth_webhook(request: Request, db: Session = Depends(get_db)):
     """接收 aigc-auth 的用户变更通知"""
+    # 获取原始请求体
+    body = await request.body()
+    
+    # 验证签名
+    signature = request.headers.get("X-Webhook-Signature", "")
+    secret = os.getenv("AIGC_AUTH_WEBHOOK_SECRET", "")
+    
+    if secret:
+        expected = hmac.new(
+            secret.encode('utf-8'),
+            body,
+            hashlib.sha256
+        ).hexdigest()
+        
+        if not hmac.compare_digest(expected, signature):
+            raise HTTPException(status_code=401, detail="Invalid signature")
+    
+    # 解析数据
     data = await request.json()
     event = data.get("event")
     user_data = data.get("data", {})
     
-    # 验证签名
-    signature = request.headers.get("X-Webhook-Signature")
-    # ... 验证逻辑
-    
     if event == "user.created":
         adapter = MyLegacyAdapter(db, sync_config)
         if not adapter.get_user_by_unique_field(user_data["username"]):
@@ -515,6 +591,14 @@ async def receive_auth_webhook(request: Request, db: Session = Depends(get_db)):
     return {"success": True}
 ```
 
+**Webhook 签名验证说明**
+
+SDK 的 `register_webhook_router` 会自动处理签名验证：
+- 从请求头 `X-Webhook-Signature` 获取签名
+- 从环境变量读取密钥（默认 `AIGC_AUTH_WEBHOOK_SECRET`）
+- 使用 HMAC-SHA256 算法验证签名
+- 签名不匹配时返回 401 错误
+
 #### 6. 执行初始化同步
 
 ```python
@@ -635,10 +719,41 @@ from huace_aigc_auth_client import (
     SyncResult,
     create_sync_config,
     create_default_field_mappings,
+    
+    # Webhook 接收
+    register_webhook_router,
+    verify_webhook_signature,
 )
 ```
 
----
+---5 (2026-01-15)
+
+#### 新增功能
+
+1. **Webhook 接收功能**
+   - 新增 `register_webhook_router()` 函数，快速注册 webhook 接收路由
+   - 自动处理签名验证、请求解析和错误处理
+   - 支持自定义前缀、密钥环境变量和标签
+   - 新增 `verify_webhook_signature()` 工具函数
+
+#### 使用示例
+
+```python
+from fastapi import APIRouter
+from huace_aigc_auth_client import register_webhook_router
+
+api_router = APIRouter()
+
+async def my_handler(data: dict) -> dict:
+    event = data.get("event")
+    # 处理逻辑...
+    return {"status": "ok"}
+
+# 注册 webhook 路由
+register_webhook_router(api_router, my_handler)
+```
+
+### v1.1.
 
 ## API 变更日志
 

{huace_aigc_auth_client-1.1.5 → huace_aigc_auth_client-1.1.7}/README.md

@@ -20,7 +20,7 @@ pip install huace-aigc-auth-client
 AIGC_AUTH_APP_ID=your_app_id
 AIGC_AUTH_APP_SECRET=your_app_secret
 
-# 可选：鉴权服务地址（默认为生产环境）
+# 可选：鉴权服务地址（默认为生产环境）- 测试环境鉴权地址：https://auth-test.aigc.huacemedia.com/aigc-auth/api/v1
 AIGC_AUTH_BASE_URL=https://aigc-auth.huacemedia.com/aigc-auth/api/v1
 ```
 
@@ -303,21 +303,21 @@ except AigcAuthError as e:
 
 ```
 ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
-│   aigc-auth     │────▶│   SDK 同步层    │────▶│   旧系统        │
-│   (鉴权中心)    │     │   (字段映射)    │     │   (用户表)      │
+│   aigc-auth     │────▶│   SDK 同步层     │────▶│   旧系统         │
+│   (鉴权中心)     │     │   (字段映射)     │     │   (用户表)       │
 └─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
-        │   1. 初始化同步       │                       │
+        │   1. 初始化同步        │                       │
         │◀──────────────────────────────────────────────│
-        │   (批量同步旧用户到 auth)                     │
+        │   (批量同步旧用户到 auth)                       │
         │                       │                       │
-        │   2. 增量同步         │                       │
+        │   2. 增量同步          │                       │
         │──────────────────────▶│──────────────────────▶│
-        │   (auth 新用户自动同步到旧系统)               │
+        │   (auth 新用户自动同步到旧系统)                  │
         │                       │                       │
-        │   3. Webhook 推送     │                       │
+        │   3. Webhook 推送      │                       │
         │──────────────────────────────────────────────▶│
-        │   (用户变更主动通知)                          │
+        │   (用户变更主动通知)                            │
 ```
 
 ### 快速开始
@@ -332,7 +332,7 @@ AIGC_AUTH_BASE_URL=https://aigc-auth.huacemedia.com/aigc-auth/api/v1
 
 # 同步配置
 AIGC_AUTH_SYNC_ENABLED=true
-AIGC_AUTH_SYNC_PASSWORD=Abc@123456
+AIGC_AUTH_SYNC_PASSWORD=通用密码
 AIGC_AUTH_WEBHOOK_URL=https://your-domain.com/api/v1/webhook/auth
 AIGC_AUTH_WEBHOOK_SECRET=your_secret
 ```
@@ -382,7 +382,7 @@ field_mappings = [
 sync_config = create_sync_config(
     field_mappings=field_mappings,
     password_mode=PasswordMode.UNIFIED,
-    unified_password="Abc@123456",
+    unified_password="通用密码",
     webhook_url="https://your-domain.com/api/v1/webhook/auth",
 )
 ```
@@ -461,18 +461,94 @@ async def auth_middleware(request, call_next):
 
 #### 5. 添加 Webhook 接收端点
 
+**推荐方式：使用 SDK 提供的通用 Webhook 路由**
+
 ```python
+from fastapi import APIRouter
+from huace_aigc_auth_client import register_webhook_router
+
+api_router = APIRouter()
+
+# 定义 webhook 处理函数
+async def handle_webhook(data: dict) -> dict:
+    """
+    处理来自 aigc-auth 的 webhook 通知
+    
+    Args:
+        data: webhook 数据，包含 event 和 data 字段
+        
+    Returns:
+        dict: 处理结果
+    """
+    from your_app.db import get_db_session
+    
+    event = data.get("event")
+    user_data = data.get("data", {})
+    
+    # 创建数据库会话
+    async with get_db_session() as db:
+        adapter = MyLegacyAdapter(db, sync_config)
+        
+        if event == "user.created":
+            # 处理用户创建事件
+            if not adapter.get_user_by_unique_field(user_data["username"]):
+                legacy_data = adapter.transform_auth_to_legacy(user_data)
+                legacy_data["password"] = sync_config.unified_password
+                adapter.create_user(legacy_data)
+                await db.commit()
+        
+        elif event == "user.updated":
+            # 处理用户更新事件
+            legacy_data = adapter.transform_auth_to_legacy(user_data)
+            adapter.update_user(user_data["username"], legacy_data)
+            await db.commit()
+    
+    return {"status": "ok", "event": event}
+
+# 注册 webhook 路由（自动处理签名验证）
+register_webhook_router(
+    api_router,
+    handler=handle_webhook,
+    prefix="/webhook",  # 可选，默认 "/webhook"
+    secret_env_key="aigc-auth-webhook-secret",  # 可选，在 auth 后台配置
+    tags=["Webhook"]  # 可选，默认 ["Webhook"]
+)
+
+# webhook 端点将自动创建在: /webhook/auth
+```
+
+**传统方式：手动实现 Webhook 端点**
+
+```python
+import hmac
+import hashlib
+import os
+
 @app.post("/api/v1/webhook/auth")
 async def receive_auth_webhook(request: Request, db: Session = Depends(get_db)):
     """接收 aigc-auth 的用户变更通知"""
+    # 获取原始请求体
+    body = await request.body()
+    
+    # 验证签名
+    signature = request.headers.get("X-Webhook-Signature", "")
+    secret = os.getenv("AIGC_AUTH_WEBHOOK_SECRET", "")
+    
+    if secret:
+        expected = hmac.new(
+            secret.encode('utf-8'),
+            body,
+            hashlib.sha256
+        ).hexdigest()
+        
+        if not hmac.compare_digest(expected, signature):
+            raise HTTPException(status_code=401, detail="Invalid signature")
+    
+    # 解析数据
     data = await request.json()
     event = data.get("event")
     user_data = data.get("data", {})
     
-    # 验证签名
-    signature = request.headers.get("X-Webhook-Signature")
-    # ... 验证逻辑
-    
     if event == "user.created":
         adapter = MyLegacyAdapter(db, sync_config)
         if not adapter.get_user_by_unique_field(user_data["username"]):
@@ -490,6 +566,14 @@ async def receive_auth_webhook(request: Request, db: Session = Depends(get_db)):
     return {"success": True}
 ```
 
+**Webhook 签名验证说明**
+
+SDK 的 `register_webhook_router` 会自动处理签名验证：
+- 从请求头 `X-Webhook-Signature` 获取签名
+- 从环境变量读取密钥（默认 `AIGC_AUTH_WEBHOOK_SECRET`）
+- 使用 HMAC-SHA256 算法验证签名
+- 签名不匹配时返回 401 错误
+
 #### 6. 执行初始化同步
 
 ```python
@@ -610,10 +694,41 @@ from huace_aigc_auth_client import (
     SyncResult,
     create_sync_config,
     create_default_field_mappings,
+    
+    # Webhook 接收
+    register_webhook_router,
+    verify_webhook_signature,
 )
 ```
 
----
+---5 (2026-01-15)
+
+#### 新增功能
+
+1. **Webhook 接收功能**
+   - 新增 `register_webhook_router()` 函数，快速注册 webhook 接收路由
+   - 自动处理签名验证、请求解析和错误处理
+   - 支持自定义前缀、密钥环境变量和标签
+   - 新增 `verify_webhook_signature()` 工具函数
+
+#### 使用示例
+
+```python
+from fastapi import APIRouter
+from huace_aigc_auth_client import register_webhook_router
+
+api_router = APIRouter()
+
+async def my_handler(data: dict) -> dict:
+    event = data.get("event")
+    # 处理逻辑...
+    return {"status": "ok"}
+
+# 注册 webhook 路由
+register_webhook_router(api_router, my_handler)
+```
+
+### v1.1.
 
 ## API 变更日志
 

{huace_aigc_auth_client-1.1.5 → huace_aigc_auth_client-1.1.7}/huace_aigc_auth_client/__init__.py

@@ -98,4 +98,4 @@ __all__ = [
     "register_webhook_router",
     "verify_webhook_signature",
 ]
-__version__ = "1.1.5"
+__version__ = "1.1.7"

{huace_aigc_auth_client-1.1.5 → huace_aigc_auth_client-1.1.7}/huace_aigc_auth_client/legacy_adapter.py

@@ -195,14 +195,14 @@ class LegacySystemAdapter(ABC):
         """
         raise NotImplementedError("Subclass must implement get_all_users_async method")
     
-    async def upsert_user_async(self, user_data: Dict[str, Any]) -> Dict[str, Any]:
+    async def upsert_user_async(self, user_data: Dict[str, Any], auth_data: Dict[str, Any] = None) -> Dict[str, Any]:
         """异步创建或更新用户（存在则更新，不存在则新增）
         
         这是一个默认实现，子类可以选择性覆盖以优化性能。
         
         Args:
             user_data: 用户数据字典（必须包含 username）
-            
+            auth_data: 鉴权系统用户数据字典（可选）
         Returns:
             Dict: 操作结果 {"created": bool, "user_id": Any}
         """
@@ -215,6 +215,9 @@ class LegacySystemAdapter(ABC):
         
         if existing:
             # 用户存在，执行更新
+            if not auth_data or auth_data.get("updatedFields") is None or len(auth_data.get("updatedFields")) == 0:
+                # 如果没有提供 auth_data 或 updatedFields，则不更新
+                return {"created": False, "user_id": existing.get("id")}
             await self._update_user_async(username, user_data)
             return {"created": False, "user_id": existing.get("id")}
         else:

{huace_aigc_auth_client-1.1.5 → huace_aigc_auth_client-1.1.7}/huace_aigc_auth_client/sdk.py

@@ -92,7 +92,7 @@ class AigcAuthClient:
         client = AigcAuthClient(
             app_id="your_app_id",
             app_secret="your_app_secret",
-            base_url="https://aigc-auth.huacemedia.com/aigc-auth/api/v1"  # 可选
+            base_url="https://aigc-auth.huacemedia.com/aigc-auth/api/v1"
         )
 
         # 验证 token
@@ -271,6 +271,7 @@ class AigcAuthClient:
             result = response.json()
 
             if result.get("code") != 0:
+                logger.error(f"AigcAuthClient 请求错误: {result}")
                 raise AigcAuthError(
                     result.get("code", -1),
                     result.get("message", "未知错误")
@@ -285,6 +286,7 @@ class AigcAuthClient:
             return response_data
 
         except requests.exceptions.RequestException as e:
+            logger.error(f"AigcAuthClient 请求失败: {str(e)}")
             raise AigcAuthError(-1, f"请求失败: {str(e)}")
 
     def verify_token(self, token: str) -> TokenVerifyResult:
@@ -599,6 +601,7 @@ class AuthMiddleware:
         token = self._extract_token(authorization)
 
         if not token:
+            logger.warning("AuthMiddleware未提供认证信息")
             return JSONResponse(
                 status_code=401,
                 content={"code": 401, "message": "未提供认证信息", "data": None}
@@ -616,6 +619,7 @@ class AuthMiddleware:
             if user_info_callback:
                 await user_info_callback(request, user_info)
         except AigcAuthError as e:
+            logger.error(f"AuthMiddleware认证失败: {e.message}")
             return JSONResponse(
                 status_code=401,
                 content={"code": e.code, "message": e.message, "data": None}
@@ -644,6 +648,7 @@ class AuthMiddleware:
         token = self._extract_token(authorization)
 
         if not token:
+            logger.warning("AuthMiddleware未提供认证信息")
             return jsonify({
                 "code": 401,
                 "message": "未提供认证信息",
@@ -658,6 +663,7 @@ class AuthMiddleware:
             if user_info_callback:
                 user_info_callback(request, user_info)
         except AigcAuthError as e:
+            logger.error(f"AuthMiddleware认证失败: {e.message}")
             return jsonify({
                 "code": e.code,
                 "message": e.message,
@@ -712,6 +718,7 @@ def create_fastapi_auth_dependency(client: AigcAuthClient):
         user_info = client.get_user_info_from_header(authorization)
 
         if user_info is None:
+            logger.warning("FastAPI依赖未登录或Token已过期")
             raise HTTPException(status_code=401, detail="未登录或 Token 已过期")
 
         return user_info

{huace_aigc_auth_client-1.1.5 → huace_aigc_auth_client-1.1.7/huace_aigc_auth_client.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: huace-aigc-auth-client
-Version: 1.1.5
+Version: 1.1.7
 Summary: 华策AIGC Auth Client - 提供 Token 验证、用户信息获取、权限检查、旧系统接入等功能
 Author-email: Huace <support@huace.com>
 License: MIT
@@ -45,7 +45,7 @@ pip install huace-aigc-auth-client
 AIGC_AUTH_APP_ID=your_app_id
 AIGC_AUTH_APP_SECRET=your_app_secret
 
-# 可选：鉴权服务地址（默认为生产环境）
+# 可选：鉴权服务地址（默认为生产环境）- 测试环境鉴权地址：https://auth-test.aigc.huacemedia.com/aigc-auth/api/v1
 AIGC_AUTH_BASE_URL=https://aigc-auth.huacemedia.com/aigc-auth/api/v1
 ```
 
@@ -328,21 +328,21 @@ except AigcAuthError as e:
 
 ```
 ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
-│   aigc-auth     │────▶│   SDK 同步层    │────▶│   旧系统        │
-│   (鉴权中心)    │     │   (字段映射)    │     │   (用户表)      │
+│   aigc-auth     │────▶│   SDK 同步层     │────▶│   旧系统         │
+│   (鉴权中心)     │     │   (字段映射)     │     │   (用户表)       │
 └─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
-        │   1. 初始化同步       │                       │
+        │   1. 初始化同步        │                       │
         │◀──────────────────────────────────────────────│
-        │   (批量同步旧用户到 auth)                     │
+        │   (批量同步旧用户到 auth)                       │
         │                       │                       │
-        │   2. 增量同步         │                       │
+        │   2. 增量同步          │                       │
         │──────────────────────▶│──────────────────────▶│
-        │   (auth 新用户自动同步到旧系统)               │
+        │   (auth 新用户自动同步到旧系统)                  │
         │                       │                       │
-        │   3. Webhook 推送     │                       │
+        │   3. Webhook 推送      │                       │
         │──────────────────────────────────────────────▶│
-        │   (用户变更主动通知)                          │
+        │   (用户变更主动通知)                            │
 ```
 
 ### 快速开始
@@ -357,7 +357,7 @@ AIGC_AUTH_BASE_URL=https://aigc-auth.huacemedia.com/aigc-auth/api/v1
 
 # 同步配置
 AIGC_AUTH_SYNC_ENABLED=true
-AIGC_AUTH_SYNC_PASSWORD=Abc@123456
+AIGC_AUTH_SYNC_PASSWORD=通用密码
 AIGC_AUTH_WEBHOOK_URL=https://your-domain.com/api/v1/webhook/auth
 AIGC_AUTH_WEBHOOK_SECRET=your_secret
 ```
@@ -407,7 +407,7 @@ field_mappings = [
 sync_config = create_sync_config(
     field_mappings=field_mappings,
     password_mode=PasswordMode.UNIFIED,
-    unified_password="Abc@123456",
+    unified_password="通用密码",
     webhook_url="https://your-domain.com/api/v1/webhook/auth",
 )
 ```
@@ -486,18 +486,94 @@ async def auth_middleware(request, call_next):
 
 #### 5. 添加 Webhook 接收端点
 
+**推荐方式：使用 SDK 提供的通用 Webhook 路由**
+
 ```python
+from fastapi import APIRouter
+from huace_aigc_auth_client import register_webhook_router
+
+api_router = APIRouter()
+
+# 定义 webhook 处理函数
+async def handle_webhook(data: dict) -> dict:
+    """
+    处理来自 aigc-auth 的 webhook 通知
+    
+    Args:
+        data: webhook 数据，包含 event 和 data 字段
+        
+    Returns:
+        dict: 处理结果
+    """
+    from your_app.db import get_db_session
+    
+    event = data.get("event")
+    user_data = data.get("data", {})
+    
+    # 创建数据库会话
+    async with get_db_session() as db:
+        adapter = MyLegacyAdapter(db, sync_config)
+        
+        if event == "user.created":
+            # 处理用户创建事件
+            if not adapter.get_user_by_unique_field(user_data["username"]):
+                legacy_data = adapter.transform_auth_to_legacy(user_data)
+                legacy_data["password"] = sync_config.unified_password
+                adapter.create_user(legacy_data)
+                await db.commit()
+        
+        elif event == "user.updated":
+            # 处理用户更新事件
+            legacy_data = adapter.transform_auth_to_legacy(user_data)
+            adapter.update_user(user_data["username"], legacy_data)
+            await db.commit()
+    
+    return {"status": "ok", "event": event}
+
+# 注册 webhook 路由（自动处理签名验证）
+register_webhook_router(
+    api_router,
+    handler=handle_webhook,
+    prefix="/webhook",  # 可选，默认 "/webhook"
+    secret_env_key="aigc-auth-webhook-secret",  # 可选，在 auth 后台配置
+    tags=["Webhook"]  # 可选，默认 ["Webhook"]
+)
+
+# webhook 端点将自动创建在: /webhook/auth
+```
+
+**传统方式：手动实现 Webhook 端点**
+
+```python
+import hmac
+import hashlib
+import os
+
 @app.post("/api/v1/webhook/auth")
 async def receive_auth_webhook(request: Request, db: Session = Depends(get_db)):
     """接收 aigc-auth 的用户变更通知"""
+    # 获取原始请求体
+    body = await request.body()
+    
+    # 验证签名
+    signature = request.headers.get("X-Webhook-Signature", "")
+    secret = os.getenv("AIGC_AUTH_WEBHOOK_SECRET", "")
+    
+    if secret:
+        expected = hmac.new(
+            secret.encode('utf-8'),
+            body,
+            hashlib.sha256
+        ).hexdigest()
+        
+        if not hmac.compare_digest(expected, signature):
+            raise HTTPException(status_code=401, detail="Invalid signature")
+    
+    # 解析数据
     data = await request.json()
     event = data.get("event")
     user_data = data.get("data", {})
     
-    # 验证签名
-    signature = request.headers.get("X-Webhook-Signature")
-    # ... 验证逻辑
-    
     if event == "user.created":
         adapter = MyLegacyAdapter(db, sync_config)
         if not adapter.get_user_by_unique_field(user_data["username"]):
@@ -515,6 +591,14 @@ async def receive_auth_webhook(request: Request, db: Session = Depends(get_db)):
     return {"success": True}
 ```
 
+**Webhook 签名验证说明**
+
+SDK 的 `register_webhook_router` 会自动处理签名验证：
+- 从请求头 `X-Webhook-Signature` 获取签名
+- 从环境变量读取密钥（默认 `AIGC_AUTH_WEBHOOK_SECRET`）
+- 使用 HMAC-SHA256 算法验证签名
+- 签名不匹配时返回 401 错误
+
 #### 6. 执行初始化同步
 
 ```python
@@ -635,10 +719,41 @@ from huace_aigc_auth_client import (
     SyncResult,
     create_sync_config,
     create_default_field_mappings,
+    
+    # Webhook 接收
+    register_webhook_router,
+    verify_webhook_signature,
 )
 ```
 
----
+---5 (2026-01-15)
+
+#### 新增功能
+
+1. **Webhook 接收功能**
+   - 新增 `register_webhook_router()` 函数，快速注册 webhook 接收路由
+   - 自动处理签名验证、请求解析和错误处理
+   - 支持自定义前缀、密钥环境变量和标签
+   - 新增 `verify_webhook_signature()` 工具函数
+
+#### 使用示例
+
+```python
+from fastapi import APIRouter
+from huace_aigc_auth_client import register_webhook_router
+
+api_router = APIRouter()
+
+async def my_handler(data: dict) -> dict:
+    event = data.get("event")
+    # 处理逻辑...
+    return {"status": "ok"}
+
+# 注册 webhook 路由
+register_webhook_router(api_router, my_handler)
+```
+
+### v1.1.
 
 ## API 变更日志
 

{huace_aigc_auth_client-1.1.5 → huace_aigc_auth_client-1.1.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "huace-aigc-auth-client"
-version = "1.1.5"
+version = "1.1.7"
 description = "华策AIGC Auth Client - 提供 Token 验证、用户信息获取、权限检查、旧系统接入等功能"
 readme = "README.md"
 requires-python = ">=3.7"